feat: harness hook resilience (self-heal hooks, start short-circuit, doctor drift detection)

[KristjanPikhof]

Summary

This branch makes the harness integration self-healing and adds first-class
diagnostics for it. Active hooks across Claude Code, Codex, OpenCode, and Pi
now run idempotent acd start && acd wake, so the daemon recovers after a
manual acd stop without waiting for a brand-new harness session. A new
per-session start cache short-circuits the hot path to roughly 50 ms.
acd doctor flags installed snippet drift and tails the Codex hook log.

It also ships Codex hooks v2 (~/.codex/hooks.json instead of the legacy TOML
snippet) and resolves the P1/P2 findings from the cr-expert review of the
branch (tracked under Trekoon epic fb35fb76-1487-4bfb-9da2-44eb09a3f90a).

Closes #7.

What changed

Self-healing active hooks

• All four harnesses (Claude Code, Codex, OpenCode, Pi) now use the canonical
  body { acd start --... && acd wake --... ; } 2>>"$LOG" || { printf '[ts] active hook failed exit=%d cmd=acd-start-wake\n' ... ; exit 1; }. acd start failure is no longer masked by a successful wake; the active hook
  exits non-zero and writes a stable line to the per-harness log fallback at
  ${XDG_STATE_HOME:-$HOME/.local/state}/acd/<harness>-hook.log.
• Adapter E2E coverage added for stop-all self-heal and corrupt-DB negative
  paths on every harness.

Start short-circuit fast path

• runStart now reads a per-session cache file at
  <gitDir>/acd/start-cache-<sha256(session_id)[:16]>.json (schema v2).
  Healthy hot path returns in ~50 ms vs. the 1 s cold-path budget.
• The cache stores a daemon fingerprint (DaemonStartTS + DaemonArgvHash).
  Short-circuit requires a live PID and a fingerprint match before reusing the
  cache, so PID reuse on long-running boxes cannot serve a stale fast path.
• Each hot-path call refreshes daemon_clients.last_seen_ts so the refcount
  sweeper does not evict a session that lives entirely on the fast path.
• Cache writes use os.CreateTemp so concurrent active hooks no longer
  collide on a shared start-cache.json.tmp.
• acd stop invalidates the cache on the Deferred path and after a failed
  force-stop escalation.
• test/integration/start_latency_budget_test.go enforces the speedup claim:
  10 hot calls each under 200 ms and under cold/1.5.

acd doctor upgrades

• Detects installed snippet drift: warns when active-hook bodies in
  ~/.claude/settings.json, ~/.codex/hooks.json,
  ~/.config/opencode/hooks.yaml, or ~/.pi/hook/hooks.yaml lack both
  acd start and acd wake or the log fallback. Per-harness remediation
  hints point at the merge-first install path.
• Tails the Codex hook log (last 50 lines or 5 minutes) and surfaces the
  error count plus the first failing line.
• Distinguishes "config unreadable" from "marker missing" on EACCES/EIO via a
  new config_read_error JSON field.
• Fixes a YAML drift parser bug that misread nested actions items as
  top-level hook entries (drift never fired for any real OpenCode/Pi config).
• Fixes parseLogTimestamp so the bracketed wrapper-printf shape parses
  correctly. The five-minute recency window was effectively disabled before.
• Tightens looksLikeHookError so JSONL info lines containing the substring
  failed (for example failed_blocking_pending=0) are no longer flagged.

Codex hooks v2 (breaking setup change)

• acd setup codex now writes ~/.codex/hooks.json instead of the legacy
  TOML snippet. Codex hooks read cwd from stdin via
  acd hook-stdin-extract session_id cwd?; CODEX_PROJECT_DIR is gone.
• All five Codex hook bodies (SessionStart, UserPromptSubmit, PreToolUse,
  PostToolUse, Stop) capture helper exit explicitly. A failing
  acd hook-stdin-extract now writes
  [ts] active hook failed exit=N cmd=acd-hook-stdin-extract to the hook log
  instead of being swallowed by a trailing || exit 0. This also fixes a
  latent bug where $? was consumed by $(date +%FT%T%z) before being
  printed, so the logged exit code was always 0.
• acd setup --raw validates JSON for .json snippet targets and refuses to
  emit malformed templates, so users cannot redirect garbage into
  ~/.codex/hooks.json.
• templates/codex/uninstall.md now documents surgical removal of the five
  acd hook entries plus the _acd_managed flag instead of deleting the
  whole file (which destroyed merged custom hooks).
• README, doctor remediation, and per-harness READMEs (claude-code, opencode,
  pi) carry overwrite warnings that mirror the existing codex template note.

Marker tightening and Pi SID

• yamlAcdManagedMarkers now requires the # comment prefix. A hand-edited
  config with bare acd-managed: true is no longer detected as installed,
  and the marker no longer collides with the TOML form as a substring.
• Pi SID fallback is now per-process unique (pi-$$-$(date +%s)) instead of
  a shared unknown. Multiple Pi sessions without PI_SESSION_ID no longer
  collapse onto the same client and tear down the daemon when one session
  ends.

Files

Area	Files
Doctor	internal/cli/doctor.go (+507/-18), internal/cli/doctor_test.go (+668/-8)
Start short-circuit	internal/cli/start_shortcircuit.go (+344/-0), internal/cli/start_shortcircuit_test.go (+798/-0), internal/cli/start.go (+143/-1), internal/cli/stop.go, internal/cli/stop_test.go
Setup / templates	internal/cli/setup.go, internal/cli/setup_test.go (+664/-6), templates/codex/hooks.json, templates/{claude-code,codex,opencode,pi}/..., internal/adapter/{detect,known}.go, internal/adapter/detect_test.go
Hook helper	internal/cli/hookhelper.go, internal/cli/hookhelper_test.go (+269/-0)
Integration	test/integration/adapter_e2e_test.go (+420/-71), test/integration/regressions_test.go, test/integration/start_latency_budget_test.go (+172/-0)
Docs	README.md, CHANGELOG.md, CLAUDE.md, docs/multi-tool.md, per-harness READMEs

Total: 32 files changed, 5457 insertions(+), 388 deletions(-).

Migration

Existing users must re-run acd setup <harness> after pulling and merge the
updated hook block into their installed config so the self-heal pattern takes
effect. Codex users additionally need /hooks re-approval after every
hooks.json content change. Per-harness READMEs and CHANGELOG v2026-05-08
document the migration in detail. acd doctor flags drift on stale installs.

Test plan

Pre-PR gate (CLAUDE.md), all green via cleanenv:

• cleanenv make lint
• cleanenv make test
• cleanenv go test ./test/integration/... -tags=integration -race -count=1 -timeout 5m
• cleanenv go test ./internal/daemon/... ./internal/git/... ./internal/state/... ./internal/pause/... ./internal/cli/... -race -count=3 -timeout 10m

Per-task verifies (cr-expert P1/P2 fixes) all pass at -race -count=3. New
regression coverage: YAML drift table-driven snippets, parseLogTimestamp with
TZ=Asia/Tokyo, EACCES/EIO disambig, fingerprint mismatch, multi-session
hot-path, concurrent writeStartCache, deferred/failed cache invalidation,
Codex helper-missing E2E, Pi SID uniqueness, mkdir gate parity for OpenCode
and Pi.

Known follow-ups (out of scope)

• Same $?-after-$(date) bug pattern still exists in claude-code,
  opencode, and pi hook bodies; only Codex was in scope for this branch.
• templates/pi/README.md SID prose update was deferred; the YAML change
  stands alone.
• start-cache force-failed escalation wipes all caches (intentional but
  worth flagging).

Notes for reviewers

The diff is large because it lands the cr-expert P1/P2 fixes alongside the
feature work. Review pointers:

• internal/cli/start_shortcircuit.go is the new fast path. Pair with
  start_shortcircuit_test.go (matrix coverage for fingerprint, multisession,
  TouchClient, deferred/failed cache invalidation).
• internal/cli/doctor.go carries the YAML drift parser, parseLogTimestamp,
  looksLikeHookError, and config_read_error work.
• templates/codex/hooks.json is the new canonical Codex install; all five
  hook bodies share the new helper-failure handling.
• internal/adapter/known.go for the # acd-managed: true marker tightening.