feat: add host-visible integration diagnostics

[Alanxtl]

Which issue or RFC does this PR close?

This PR implements the first step of #1298. It does not close #1298.

This PR is downstream of #1343 and should be reviewed after #1343 is merged.

Rationale for this change

When PowerContext is unavailable or returns an incompatible response, integrations currently provide limited or inconsistent feedback. Users need a bounded, fail-open diagnostic that explains the failure and points to powercontext doctor without exposing request details or disrupting the host.

What changes are included in this PR?

• Add common failure classification:
  • authentication_failed
  • version_mismatch
  • server_unavailable
  • invalid_response
• Add host-visible diagnostics for:

Host	Diagnostic channel	Component
Codex	Hook stderr	powercontext.codex.recall
Claude Code	Hook stderr	powercontext.claude_code.recall
DSH	Host logger warning	powercontext.dsh
OpenClaw	Plugin logger warning	powercontext.openclaw
Pi	Host terminal warning	powercontext.pi
Hermes	Python host logger warning	powercontext.hermes

• Use each host’s supported logging/output channel.
• Add 60-second deduplication to avoid repeated warnings.
• Keep integrations fail-open and content-free.
• Preserve generic tool errors for model-facing responses.
• Add the powercontext doctor recovery hint for unavailable servers.
• Update troubleshooting documentation and integration tests.
• Bub is out of scope for this PR.

Are there any user-facing changes?

Yes.

Users now receive a bounded diagnostic when PowerContext is unavailable or returns a classified failure. Normal host execution continues, and no URL, token, response body, or user content is included in the diagnostic.

There are no breaking API or persistence-format changes.

How was this change tested?

• uv run pytest tests/integrations/test_hermes_provider.py -q — 36 passed
• uv run ruff check integrations/hermes/plugins/powercontext/commands.py tests/integrations/test_hermes_provider.py — passed
• Codex and Claude Code diagnostic tests passed
• Pi and OpenClaw lifecycle diagnostic tests passed
• DSH bundled output passed node --check
• Manual validation with an unreachable PowerContext endpoint confirmed fail-open behavior and generic tool errors.
• Verified diagnostic deduplication and powercontext doctor recovery metadata.

AI usage statement

Implemented and reviewed with OpenAI Codex

[Teingi]

[P2] This lock is unbounded on the hook critical path (LOCK_EX / LK_LOCK). With another process holding the file lock, I reproduced should_emit() blocking for 6.5 seconds, so a diagnostic cooldown can stall an otherwise fail-open host invocation. Please use non-blocking locking or a very small bounded retry, fall back to emit or skip on contention, and add a subprocess contention regression test.

[Alanxtl]

add test

[Teingi]

[P2] Keep error-body parsing under the shared wall-clock deadline. This direct error.read(...) bypasses _read_response(..., deadline=request_deadline), so a peer that trickles one byte within each socket timeout can exceed the hook budget indefinitely. On the current head, a 422 response sending one byte every 20 ms took 0.714 s despite a 0.1 s deadline; Claude has the same branch. Please use a deadline- and size-bounded error-body reader and add a slow-4xx regression test.

[Alanxtl]

fixed

[Teingi]

LGTM