MCP capture pipeline is unreachable when the agent's session root differs from the wired repo

[MongLong0214]

Found during first real use of v0.8.2, working on MongLong0214/agent-control-plane.

What happened

The capture pipeline is MCP-only — commitlore_prepare_capture, commitlore_verify_capture, commitlore_stage_capture have no CLI equivalent (commitlore --help lists parse, sync, pre-push, validate, uninstall, hooks, index, context, limits, ruled-out, warnings).

MCP servers are loaded from the agent session's root project, not from the repository the agent is editing. My session root is ~/projects/repo-factory; all my work is in ~/projects/agent-control-plane, which is where .mcp.json wires commitlore mcp. So:

~/projects/agent-control-plane/.mcp.json   → { "command": "commitlore", "args": ["mcp"] }   ✅ wired
~/projects/repo-factory/.mcp.json           → does not exist                                 ❌ session root

Result: the three capture tools are not in my tool list at all. The read side is fine — commitlore context <path> works from the CLI regardless of session root, and correctly returned no active records for src/guard/managed-write-guard.ts.

Reproduction

1. wire .mcp.json with commitlore mcp in repo A
2. start an agent session rooted in repo B
3. from that session, cd into repo A and do the work there — the normal shape when one session drives several repositories
4. the capture tools are absent; commitlore context still works

Why it matters

This is not an exotic setup. A single agent session commonly works across several repositories — the owner's own note says six repos are wired. Under the current design, capture only reaches the one repo that happens to be the session root, and the others silently get the read side only. Nothing warns you: the tools are simply not there, and an agent that does not check will conclude there is nothing to record.

What would fix it

Any one of:

• a CLI equivalent for the three capture steps, so capture works wherever commitlore is on PATH — this also makes capture scriptable and testable without an MCP host
• path-scoped MCP discovery, so the server is picked up from the repository being edited rather than the session root
• a documented note that capture requires the session root to be the wired repo, plus a way to detect it — for example commitlore doctor reporting "capture unavailable from this session root"

The CLI route seems strongest: it removes the coupling to the host's MCP loading rules entirely.

Environment

commitlore 0.8.2 · macOS (Darwin 25.3.0) · Node 22 · Claude Code session

[MongLong0214]

Checked the premise against the version this was filed on, and it does not hold.

capture exists on the CLI, and did on v0.8.2

$ commitlore capture --help
Usage: commitlore capture [options] [command]

prepare → verify → stage a record from a transcript and draft (no trailer syntax needed)
  --transcript <path>   --diff <path>   --draft <path>   --out <path>
  --json   --unattended   --shadow   --since <rev>

Measured on the v0.8.2 tag's own build, not only on main, and it is listed in the top-level --help in both.

The command list in this report is from an older binary

The report quotes commitlore --help as listing parse, sync, pre-push, validate, uninstall, hooks, index, context, limits, ruled-out, warnings. That list is missing capture — and also doctor, guard, inject, init, auto and stale, all of which v0.8.2 ships.

The likely explanation is #660: this machine was running four generations of CommitLore at once, including two servers from ~/.claude/plugins/cache/commitlore/commitlore/0.6.0 — a directory that no longer exists on disk. An agent asking a 0.6.0 runtime for its command list gets a 0.6.0 answer, and nothing said which runtime answered. #644 now reports that divergence, and #661 adds the check that sees runtimes by process rather than by registration.

What survives, and it is narrower

The MCP half is unchanged and still true: capture tools load from the session root, not from the repository being edited, so a session rooted elsewhere does not get them. What is not true is that this leaves no way to capture — the CLI path works from any repository, which is also what makes capture scriptable and testable without a host.

So the remaining gap is that nothing tells you. The tools are simply absent, and an agent that does not check concludes there is nothing to record. That is a discoverability problem rather than a missing capability, and it deserves a different fix from the one this issue proposes.

Suggested rescope

• keep: a session whose root differs from the edited repository gets no capture tools, and no surface says so
• drop: "the capture pipeline is MCP-only" — it is not, and was not when this was filed
• the fix to consider is something that notices the asymmetry, rather than a CLI equivalent that already exists

[MongLong0214]

The session-root reading does not reproduce on the built server

This issue was narrowed to capture tools load from the session root, so a
session rooted elsewhere silently gets none. Measured against the built server
(main at 2efe185) driven as a separate process over stdio, that is not what
happens.

Tool listing, inside a repository and outside one:

cwd=/tmp/wt-631                  (repo=true)   tools=8
  capture= [commitlore_prepare_capture, commitlore_verify_capture, commitlore_stage_capture]

cwd=/var/folders/.../tmp.Iqw2IS  (repo=no)     tools=8
  capture= [commitlore_prepare_capture, commitlore_verify_capture, commitlore_stage_capture]

All three capture tools are advertised either way.

Calling one from outside a repository reaches the tool and fails on its own
argument contract, not on where the session is rooted:

commitlore: transcript is required

So at both layers a client can reach the pipeline regardless of cwd. Whatever
made the pipeline unreachable in the original report is not the tool list and
not a repository-root guard.

What is still open

The original report is a session restart, and #660 established that four
generations of this product were installed at once, two of them from a deleted
plugin cache that install.sh never touches. A client that reconnects to an
older binary would see that binary's tool list, which is the same shape of
symptom and would not reproduce here, because this measurement drives one known
build directly.

Recording the negative result rather than fixing the narrowed reading: a repair
aimed at session-root loading would change code that is behaving correctly. The
next measurement is which binary the failing client was actually talking to, and
#660 is where that lives.

[MongLong0214]

Which binary the client was talking to — measured

Following the previous comment's next step. Every CommitLore bundle installed on
the machine that produced the original report:

0.8.0  ~/.claude/plugins/cache/commitlore/commitlore/0.8.0/dist/commitlore.mjs
0.8.0  ~/.claude/plugins/marketplaces/commitlore/dist/commitlore.mjs
0.8.0  ~/.local/share/commitlore/v0.8.0/dist/commitlore.mjs
0.8.1  ~/.local/share/commitlore/v0.8.1/dist/commitlore.mjs
0.8.2  ~/.local/share/commitlore/v0.8.2/dist/commitlore.mjs

0.8.2  ~/.local/bin/commitlore          <- the CLI on PATH

Five bundles, three generations. The two paths an agent client actually
launches — the plugin cache and the marketplace checkout — are both 0.8.0, two
releases behind the CLI on PATH.

That is the explanation this issue was missing, and it is #660: install.sh
never touches the Claude plugin cache, so a release does not reach the tools
agents call. A session restart reconnects through the plugin and gets 0.8.0,
while every measurement taken from a terminal gets 0.8.2 and cannot reproduce
the report.

It also closes the loop on the previous comment: the session-root reading did
not reproduce because it was measured against a current build, and the failing
client was never running one.

What this means for the fix

There is nothing to repair in capture-tool loading — the code measured correct.
What is missing is that nothing tells a user the plugin is serving an older
generation than the CLI they just installed, and #660 is where that belongs.

This issue is a duplicate of #660 in cause. Leaving the close/merge decision to
the CTO rather than taking it, since #630 is on the release list and #660 is not,
and moving it changes what 0.9.0 is judged against.

[MongLong0214]

Closing as a duplicate of #660 in cause. The symptom was real; the diagnosis in
this issue was not, and leaving it open would make the next person re-measure it.

What was measured

Driving the built server over stdio, the narrowed reading — capture tools load
from the session root, so a session rooted elsewhere silently gets none — does
not reproduce. All three capture tools are advertised inside a repository and
outside one, and calling one from outside a repository fails on its own argument
contract (transcript is required), not on a repository-root guard.

Every CommitLore bundle installed on the machine that produced the report:

0.8.0  ~/.claude/plugins/cache/commitlore/commitlore/0.8.0/dist/commitlore.mjs
0.8.0  ~/.claude/plugins/marketplaces/commitlore/dist/commitlore.mjs
0.8.0  ~/.local/share/commitlore/v0.8.0/dist/commitlore.mjs
0.8.1  ~/.local/share/commitlore/v0.8.1/dist/commitlore.mjs
0.8.2  ~/.local/share/commitlore/v0.8.2/dist/commitlore.mjs
0.8.2  ~/.local/bin/commitlore          <- the CLI on PATH

The two paths an agent client actually launches were both 0.8.0 while the CLI
was 0.8.2. A session restart reconnects through the plugin and gets a
two-release-old binary — which is #660, and why every terminal measurement
failed to reproduce this.

Why closed rather than rescoped

There is nothing to repair in capture-tool loading; that code measured correct.
An issue whose stated defect does not exist, kept open because its symptom does,
is how the same measurement gets made twice. The symptom now lives where its
cause is.

One consequence for the release

This was carrying release:0.9.0 and #660 was not. By the stated criterion —
does a user who does not know about this defect install CommitLore, use it, and
get a wrong result — #660 qualifies plainly: they install a release and their
agent keeps calling the previous one. Moving the label with the issue, and
flagging it because it changes what 0.9.0 is judged against.