worktree_start: auto-detect/prep the compatible memory branch instead of a bare choose_memory_recovery block #87

Summary

worktree_start blocks with choose_memory_recovery when the memory repo's currently-checked-out branch has no ledger mapping for the code base commit — even when a different, already-present memory branch ledger-maps that exact commit. The block is effectively a bare error: it neither names the compatible branch nor offers to switch to it, and memory_choice="reconciliation" is a no-op in practice (re-blocks identically). The operator/agent then has to manually discover the right memory branch and git checkout it. This should be guided, or better, auto-performed by the server.

Observed (agents-remember 2.9.1, repo device-management, 2026-06-15)

Starting a worktree for a v1.2-based feature branch while the memory repo was checked out on readones_workbench:

• code source branch based on v1.2 @ 94ee40627db4308bca88e1be7143d4a5d51510f7
• memory repo on readones_workbench; ledger lastVerifiedCodeCommit = 67a1ec3a2… (a staging-line commit)

worktree_start(… memory_mode="external") returned:

{"state":"blocked","nextOperation":"choose_memory_recovery",
 "memory":{"state":"blocked","reason":"no exact ledger mapping for selected code base commit",
   "codeBaseCommit":"94ee40627…","lastVerifiedCodeCommit":"67a1ec3a2…",
   "choices":["reconciliation","disabled-memory","custom"]}}

Re-running with memory_choice="reconciliation" (3×, including the minimal nextArgs shape) re-blocked identically — the choice appears to be a no-op. memory_baseline_status returned already-ledgered, so memory_baseline_adopt is N/A.

The actual fix was trivial and local: a v1.2 memory branch already existed whose ledger mapped the exact code base commit:

v1.2:memory.md -> "lastVerifiedCodeCommit": "94ee40627db4308bca88e1be7143d4a5d51510f7"

git checkout v1.2 in the memory repo → worktree_start succeeded immediately (memory.state: "compatible", cheap provider seed, worktree memory branch created off the v1.2 tip 03ce99e).

Why this is a problem

• The block reads as a hard error with three abstract recovery tokens, none of which says "a compatible memory branch v1.2 exists — switch to it."
• reconciliation doesn't resolve it (no-op), pushing the operator toward disabled-memory (loses onboarding lockstep) or a heavy manual carryover — when a one-line branch switch was the correct answer.
• It forces the agent into manual git surgery in the memory repo, which the model shouldn't have to reason about.

Requested behavior

1. Minimum — guided error. When blocking on "no exact ledger mapping for the code base commit," scan the memory repo's local branches for one whose ledger lastVerifiedCodeCommit equals the code base commit, and surface it in the result (e.g. compatibleMemoryBranches: ["v1.2"]) with an actionable hint ("check out memory branch v1.2, or pass it as the memory source").
2. Better — auto-prep (preferred). Detect the matching memory branch and base the worktree's memory off it automatically (create the worktree memory branch off that tip), without requiring the operator to switch the main memory checkout or run a manual git checkout. Optionally accept an explicit memory_source_branch argument so callers can pin it.
3. Fix/clarify reconciliation. On 2.9.1 the memory_choice="reconciliation" path re-blocks with no effect and no diagnostic. Either make it perform the mapping/reconciliation, or return why it cannot and what to do instead.

Environment

• agents-remember MCP 2.9.1 (matches repo mcp/pyproject.toml), stdio transport.
• External-memory topology; coordination root ar-coordination.

Filed from a real device-management session (#1472 dark-mode deactivation); the worktree completed successfully after the manual git checkout v1.2 workaround.