fix(diagnose,reset): unbreak in-agent recovery path (#410)

[jinhongkuan]

Summary

Closes #410. When the ledger hits a SurrealDB row-deserialization error, the agent's named recovery path (bicameral_reset) is often unreachable — either because Claude Code's tool surface has pinned the old schema, or because the MCP server itself can't finish init. This PR makes the CLI form genuinely callable from inside the agent loop, and (as part of the recovery substrate) fixes a silent zero-replay regression in --replay-from-events.

What changed

Diagnose + reset CLI escape hatch (the original #410 scope)

• cli/diagnose.py now opens a raw LedgerClient and forwards to gather_diagnosis_raw — the same defensive path handlers/diagnose.py already uses. The old code went through SurrealDBLedgerAdapter, which re-runs init_schema+migrate (the step the operator is trying to diagnose around).
• bicameral-mcp reset gains --confirm, --wipe-mode={ledger,full}, and --replay-from-events. With --confirm we bypass the interactive wizard and dispatch through cli/reset_cli.py:run_noninteractive_reset, a thin wrapper around handle_reset. No --confirm keeps the wizard for human-driven use.
• Filesystem-only fallback: when --confirm --wipe-mode=full is given and BicameralContext.from_env()/ledger.connect() raises (the literal reset tool missing + diagnose fails on SDK row-revision mismatch #410 scenario), we shutil.rmtree the resolved .bicameral/ directly.
• Recovery hints in LedgerDeserializationError.RECOVERY_HINT and handlers/diagnose.py:_classify_recovery now lead with the shell form, which works even when the MCP bicameral_reset tool isn't in the agent's pinned surface.

Silent zero-replay regression (d9737d7)

While dogfooding the new CLI against a real R4-layout install, --replay-from-events reported events_replayed: 0 with zero entries in replay_errors despite 3,002 valid events on disk. The pre-fix _resolve_events_dir derived its target by string-mangling the SurrealKV URL — Path(db_path).parent / "events". That inverse only worked while the ledger and events shared a parent. Once #408 (Ledger Locator) moved the ledger to ~/.bicameral/projects/<id>/ledger.db while events stayed repo-local at <repo>/.bicameral/events/, the inverse silently pointed at an empty path.

The fix splits two distinct concerns the inverse function had collapsed:

	Domain	Resolver
Events	Repo-local source — committed to git pre-#373, pulled from remote backend post-#373	<repo_path>/.bicameral/events (matches cli/sync_and_brief_cli.py:65)
Watermark	User-local derived state — per-author offset into the events stream	ledger_locator.resolve_watermark_path()
Bicameral dir (full-wipe target)	User-local derived state — what to delete in a nuclear restart	ledger_locator.project_dir_for() when no explicit SURREAL_URL is set; URL inverse otherwise (preserves the corruption-recovery test contract)

Replay now raises FileNotFoundError when the events substrate can't be located, and the caller surfaces it via replay_errors. Silent zero-replay becomes an explicit failure that names where events were expected and points the user at sync-and-brief for fresh-clone repopulation.

Linked decisions (from #408)

Forward-resolution through the locator is grounded in:

• decision:ko8efq3z1zwhbof7kecq — Ledger Locator naming + scope
• decision:rfbnlw7ghe175iu42u6b — Project identity via git rev-parse --git-common-dir hash
• decision:5nr66wvmapjpt58rrji8 — R4 config split (the layout transition that exposed the URL-inverse bug)

Boundary between user-local state (locator) and repo-local events tracks the deprecation arc in #373 — the event substrate must not be conflated with the user-local derived-state bucket.

Why this works for the original reproduction

Symptom in #410	Fix
bicameral.dashboard returns LedgerDeserializationError, recovery hint names bicameral_reset (not reachable)	Hint now points at bicameral-mcp reset --confirm ... first
bicameral_reset MCP tool gated / unregistered in running session	Agent can shell out via Bash to the now-non-interactive CLI
bicameral-mcp diagnose from shell crashes on migrate (Invalid revision 101 for type DefineTableStatement)	CLI now uses raw client; no migrate runs
--replay-from-events silently zero-replays under R4 layout	_resolve_events_dir forward-resolves repo-local; missing dir raises and surfaces via replay_errors

Test plan

• tests/test_reset_cli_410.py — 9 tests cover the flag surface, happy-path ledger wipe against memory://, filesystem fallback when from_env() raises during --wipe-mode=full, the explicit refusal to silently rmtree under --wipe-mode=ledger, the CLI-form presence in both recovery-hint surfaces, and three new regression tests for the silent zero-replay:
  • test_resolve_events_dir_under_legacy_local_layout_finds_sibling_events — guards the layout where ledger sits at <bicameral_dir>/local/ledger.db and events at <bicameral_dir>/events/. Pre-fix this returns None; post-fix returns the sibling events dir.
  • test_resolve_events_dir_uses_repo_path_not_locator_project_dir — pins the architectural boundary: events stay repo-local, never routed through project_dir_for() / "events". Guards against re-conflating user-local with repo-local in future refactors.
  • test_reset_cli_replay_surfaces_missing_events_dir_as_replay_error — end-to-end: missing events_dir produces a non-empty replay_errors, never a passing-looking zero-replay response.
• tests/test_diagnose_cli.py — updated test_diagnose_main_returns_one_on_raw_client_connect_failure (failure surface moved from adapter to raw client). Added test_diagnose_main_cli_does_not_use_adapter_path — patches SurrealDBLedgerAdapter.connect to raise; asserts diagnose still returns 0.
• ruff check + ruff format --check clean on every changed file.
• Existing test_diagnose_*, test_reset.py, test_ledger_sync_deserialization_recovery_301.py, test_ledger_locator.py all pass.

Out of scope (pre-existing on origin/dev)

• tests/test_diagnose_format.py — 8 failures from a fixture missing row_probe_warnings (field added in fix(ledger): ledger_sync deserialization error — Invalid revision 3 for type Value #301, fixture never updated). Confirmed on origin/dev independent of this PR.
• server.py --smoke-test — EXPECTED_TOOL_NAMES constant is missing bicameral.diagnose. Same one-liner drift on origin/dev. Worth a tiny follow-up.

Note on this session

Bicameral sync against the new commit was attempted but blocked by a stale SDK in the running MCP server (PID spawned pre-#408, partial-replay state with the newer SDK's revision). Restart the MCP host to pick it up; decisions linked manually above are the load-bearing set.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: c8272fcf-4e01-4f1d-ac7d-f4181bcf1f2d

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/410-reset-and-diagnose-recovery

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}