mcp: first-class worktree support — every call names its workspace

[oyvindberg]

Agentic development has a shape: an orchestrating session fans subagents out into git worktrees, each working a branch in parallel. Bleep's compile daemon was built for that shape — one process serving every checkout from shared, deduplicated state — but the layer agents actually talk to was not.

One idea runs under everything this PR ships: bleep realizes the build as immutable data, throughout. bleep.yaml is a value, not a DSL. The resolved build model is immutable data passed structurally — no global state anywhere. Everything the daemon does while building is emitted as typed events (compilation reasons with invalidated files, diagnostics, per-test status/duration/reason). So it is only logical that a completed run is also a value — a transcript written to a file in the worktree — and that values compose like values: diffing two runs is a pure function over two files. "Build logs you can diff" is not a feature bolted on; it falls out of the architecture.

The PR lands that arc in six pieces, in dependency order: a stateless MCP server where every call names its workspace; bleep copy-state so a forked agent's first build compiles only the diff; transcripts as a durable per-worktree history written once by the daemon and read by every client; bleep.history.diff / bleep.history.diff-timing — the "edit, rerun, what changed?" primitive over those transcripts; the same surface in the CLI (bleep history / history show / history diff), no daemon required; and one allow-list deciding what compiled state may leave a workspace at all. By the end, the MCP server's "one thing kept in memory" is nothing.

1. Stateless MCP server: every call names its workspace (4d15dbd)

One MCP server serves a whole Claude session, including subagents working in other git worktrees. The server used to pin one workspace at boot, so a subagent's compile silently built the parent checkout — green result, wrong code — and the server couldn't detect it: tool calls carry project names, not paths, and MCP tells the server nothing about the caller's cwd. Any fix based on detection is impossible; the only honest design is to make the caller state its location, which it always trivially knows.

So every tool that acts on a build now requires directory, and the server holds no ambient workspace at all: each call bootstraps fresh from that directory's bleep.yaml (CLI semantics, CLI cost), opens its own connection to the shared compile daemon, and disconnects. directory is required in every tool schema, so the wrong-checkout build is not guarded against — it is unrepresentable. Boot is workspace-free, so one user-scoped registration

claude mcp add --scope user bleep -- bleep mcp-server

serves every checkout and every worktree: no per-checkout .mcp.json, no seeding on git worktree add, nothing to clean up on git worktree remove.

Statelessness deletes whole categories of invalidation logic rather than fixing them:

• the bleep.yaml file-watcher and build-reload path — a fresh bootstrap per call sees config edits (including JVM changes) with no machinery at all
• the persistent BSP connection and its reconnect-on-death manager
• watch jobs (bleep.watch/sync/watch.stop) — background fibers holding connections into a daemon whose idle accounting counts connected clients
• the "last build" result cache and its diff-vs-previous responses, which went stale the moment anyone compiled outside MCP

A build declaring a different $version than the running server fails loudly with the fix in the message (install matching binary, call bleep.restart) — the client↔daemon wire protocol is version-locked, so serving it would be a lie. The JVM leg needs no such gate: daemons are keyed by bleep version + JVM + options, and per-call bootstrap routes each workspace to its matching daemon, spawning it if needed.

2. bleep copy-state: a fork starts warm (4a1a807, 665250b)

A fresh worktree has its parent's sources and none of its compiled state, so its first build recompiles the world. Content-addressed caching cannot fix the interesting part: digests are transitive, so one dirty edit in a base project makes every downstream project a cache miss — while zinc's invalidation cone for the same edit is a few files, because it keys on API hashes. What a fork actually wants is its parent's exact state as an incremental baseline.

bleep copy-state <parent> (MCP: bleep.copy-state { directory, from }) provides exactly that, and only that: state is copied from the worktree you forked off and nowhere else — dirty-file analyses included, which is the baseline that makes the first compile touch a few files rather than a few hundred. No cache tiering, no nearest-match heuristics.

The copy runs in the compile daemon on purpose. Ask-then-clone is a TOCTOU race — another agent can start compiling the parent between the asking and the cloning — so the daemon takes the same per-project locks compiles take, and the race is closed rather than narrowed. Per project, holding the lock: classes and test-classes, the zinc analysis (byte-portable by design, and byte-identical to one already resident, so the daemon's cross-workspace analysis sharing serves the fork for free), and generated sources/resources. Deliberately NOT copied: noop-manifest.bin — its keys are absolute paths into the parent, and a copied manifest validates against them, yielding a false noop that points the fork at the parent's classes. Transport is APFS clonefile on macOS, --reflink=auto on Linux, a JVM recursive copy elsewhere — chosen per OS up front, no fallback chain.

665250b fixed enumeration for hierarchical project names (dfmt/main-style cross names nest their state dirs): walk for dirs containing builds/<variant> instead of listing flat — found on a real 130-project repo where the flat listing silently copied 13 projects and skipped the rest.

The dangerous case, tested end-to-end (2b77392, b322f6f)

The parent is a working tree: its compiled state can be ahead of git — an uncommitted edit that was compiled — so the clone carries output into a workspace whose sources never contained it. Two integration tests drive real compiles through the BSP server to pin that zinc reconciles the fork's actual sources against the inherited analysis:

• Dirty downstream (2b77392): workspace A compiles core+app, app gains an uncommitted marker method and is recompiled, workspace B is created with the original sources and seeded via copy-state (asserted: the marker is byte-for-byte present in B's App.class). B's compile recompiles app, noops core (classfile mtime and bytes untouched), and afterwards the marker is gone from B's App.class. That byte-level assertion is the load-bearing one: the inherited classfile declares a method B's sources never wrote, and if zinc ever trusted inherited output, this is the assertion that catches it.
• Dirty upstream (b322f6f): the uncommitted edit lives in core — an added overload of the very name app calls (zinc's name-hashing invalidation only invalidates dependents that use an affected name), plus a marker. B's compile must purge both from Core.class and recompile app even though app's own source matches the inherited analysis — the core API it was compiled against no longer exists. Asserted via classfile mtime (a correct recompile of unchanged source is byte-identical), made non-vacuous by the sibling test proving uninvalidated seeded projects' mtimes stay put.

CI runs these on the real filesystem on every platform, so every clone transport lane is proven, alongside the endpoint's own contract tests: locking (copy-state blocks on an exclusively-locked mid-compile project and completes on release), manifest/lock-file exclusion, and loud refusals for every invalid input.

3. Transcripts live in the worktree (bef2ba8, e906dcf, fdcbaef)

What replaced the deleted result cache went through two stages. The first was an in-server RequestLog — a bounded ring keyed by explicit requestId. That already fixed staleness (a transcript describes its own run, never current state, so it cannot go stale), but it was still per-process memory: invisible to the CLI and IDEs, gone on restart, blind to compiles that didn't pass through MCP. The architecture points somewhere better: run history is a property of the worktree, not of any client. So:

Transcript is a value in bleep-core (bef2ba8, bleep.history): a header (id, workspace, variant, mode, targets, client) plus the full typed event stream and test-run result, circe-codecked for disk. Paths inside events stay absolute — transcripts are grepped and clicked, and absolute + workspace can always derive relative while the reverse loses paths outside the workspace.

The daemon writes it, once, for every client (e906dcf). Recording happens in the daemon at the one choke point every request event already passes through — sendEvent — via a per-request TranscriptRecorder created at the top of handleCompile/handleTest and threaded structurally through the whole chain. No connection- or daemon-scoped mutable state; what the client sees and what the transcript stores are the same stream by construction. At completion — success, failure or cancellation alike; a red run's transcript is exactly what a diff wants — the stream is persisted to .bleep/builds/<variant>/history/<id>.json in the workspace, tagged with the client name from the BSP handshake ("bleep", "bleep-mcp", "Metals", …). Every client shares one durable per-worktree history that survives daemon restarts, MCP-server restarts, and inspection on a machine with no daemon at all. Ids are per-workspace monotonic, minted under a file lock so racing writers cannot collide; writes are tmp+rename atomic so readers never see torn files and take no lock; retention is newest-32 / 64MB, noop transcripts kept deliberately — "everything up-to-date" is exactly what a copy-state verification diff wants to see. The id travels back in the BSP response (compile: CompileResult dataKind bleep-history-id; test: TestRunResult.historyId). One SANCTIONED EXCEPTION to fail-loudly: a transcript-write failure must not fail a build that already ran — the daemon logs and returns the result without an id. Everything else still throws.

The noop fast path now emits CompilationReason(UpToDate) before returning: without it a noop's transcript was just Started/Finished — indistinguishable from a compile whose reason was lost, and two noop runs would not have carried identical logical facts. With it, the flagship determinism property holds end-to-end through the real daemon, pinned by TranscriptStoreIntegrationTest: three compiles over the real protocol leave history/1..3.json, the responses carry the ids, clean-vs-noop diffs as exactly one reason transition, and noop-vs-noop diffs identical while every duration differs.

The MCP server now holds nothing (fdcbaef). bleep.compile/bleep.test report the daemon-assigned id instead of minting their own; bleep.history.show/bleep.history.diff/bleep.history.diff-timing read TranscriptStore directly — pure file reads, deliberately no bootstrap and no daemon spawn. RequestLog, the bridge, and the last Ref in the server are deleted: the answer to "what does the MCP server keep in memory?" is nothing. history.show/diff gain the required directory every other tool has — ids are per-workspace, so an id means nothing without saying whose history to look in — and diff gains optional baseDirectory for cross-worktree comparisons.

bleep.history.show is unchanged in spirit: expand any past run — every diagnostic, every stack trace, paginated, and searchable with a regex query over messages, paths, suite/test names and stack traces (agents grep, so give them grep — server-side, over structured data, returning exactly the matching items). The verbose flag stays dead: details are always one call away instead of a re-run away.

4. bleep.history.diff and bleep.history.diff-timing: "what changed?" (0cb899c, bef2ba8)

A transcript stores the complete event stream per request — all nine per-test statuses with durations and messages, per-project compilation reasons with invalidated files, diagnostics — and this turns that stored stream into the primitive of the agent loop: edit, rerun, "what changed?". Two tools, deliberately separate:

bleep.history.diff(base, target) is the mechanical diff. It is computed over a projection of the transcript that contains no time by type — not "durations zeroed out", they never enter the compared data structures — so two runs with the same logical outcome diff as identical no matter how timings jittered. Tests keyed by (project, suite, test): newlyFailing / fixed / newlySkipped (with the assume reason) / unskipped / added / removed, and stillFailing listed as context with a messageChanged flag (same failure vs a different failure — only the latter counts as a difference). Scope drift shows as added/removed, never as "fixed": a failing test that left the scope is not a fix. Compiles keyed by project: reason transitions (up-to-date→incremental), invalidated-file deltas, status changes, and new/resolved diagnostics keyed by (severity, path, message) with line as an attribute — a diagnostic that only moved lines is neither new nor resolved.

Cross-worktree diffs are allowed, flagged, and made honest by identity relativization (bef2ba8): diagnostic identity over absolute paths would count the same warning in a parent and its fork — same file, different root — as new + resolved. Now each side's paths, and occurrences of each side's workspace root embedded in message text, are relativized against that side's own root — ephemerally, for the comparison key only, never serialized and never shown. Paths outside any workspace (coursier, JDK) stay absolute for identity, correct on one machine. For single-workspace diffs the transformation is applied to both sides against the same root: an identity-preserving no-op, so the determinism property is untouched. Compile parent, copy-state, compile fork, diff with --base-dir — the "everything nooped except the dirty project" verification becomes one call.

bleep.history.diff-timing(base, target) owns durations: per-item deltas above max(50ms, 20% of base) as slower/faster, jitter suppressed and counted, plus slowestInTarget for the absolute question. The old diff-vs-last cache went stale the moment anyone compiled outside MCP; diffing two immutable transcripts by explicit historyId cannot.

16 scenario tests + 4 store tests in bleep-tests/src/scala/bleep/history/, the first of which pins the load-bearing property: identical outcomes with wildly different timings and event order diff as identical — and TranscriptStoreIntegrationTest pins the same property end-to-end through the real daemon.

From the deployed binary — break a test, rerun, diff:

{"identical":false,"summary":"1 newlyFailing","newlyFailing":[{...,"from":"passed","to":"failed","message":"\"expected 2, got [3]\" was not equal to \"expected 2, got [4]\""}]}

revert, rerun, diff the first run against the last:

{"identical":true,"summary":"No logical differences."}

despite ~800ms of wall-clock difference between the two runs — and bleep.history.diff-timing on the same pair suppressed all 14 per-test deltas as jitter (116ms → 120ms total).

5. The same history from the terminal (18c1d70)

Because transcripts are files in the worktree, the CLI surface is pure reads — it works with no daemon running and no MCP session anywhere:

• bleep history — list recorded runs: id, time, mode, targets, which client ran it
• bleep history show [id] — full transcript as JSON (latest when omitted); --project, --query (regex), --limit, --offset
• bleep history diff <base> <target> — the mechanical diff; --timing switches to the jitter-suppressed duration comparison; --base-dir <path> resolves base in another worktree's history (the copy-state verification flow)

The details rendering moved out of the MCP server into bleep-core as history.TranscriptFormat, so bleep history show and bleep.history.show are one implementation that cannot drift (contract pinned by TranscriptFormatTest). Compile/test summary lines print the id when the response carried one — History: #N (bleep history show N) — so a human sees the same handle an agent would use. HistoryCliIT closes the loop end-to-end: bleep new, two compiles through the production BSP server, transcripts land tagged client="bleep", the summary names both ids, and history list/show/diff (including --base-dir and --timing) run over the files.

6. One allow-list decides what leaves a workspace (ef5997b)

copy-state and the remote cache each kept a hand-maintained notion of which parts of a project's compiled state may cross the workspace boundary, and they had already drifted: copy-state correctly skipped .zinc/cache, KSP caches and lock files, while the remote cache's filter denied only noop-manifest.bin BY NAME and shipped everything else in the variant dir — zinc's classfile cache (absolute paths), per-machine KSP state, and even a .bleep-lock if one existed at pack time.

bleep.StateSharing (bleep-model) is now the single authority both consume: an ALLOW-list over paths relative to the variant build dir — {classes/, test-classes/, .zinc/analysis.zip} — with deny-by-default semantics, so state invented in the future is workspace-private until someone consciously declares it shareable, never leaked by omission. History transcripts are workspace-level and outside both mechanisms' reach by construction; CopyStateEndpointTest now pins that a seeded fork inherits neither them nor the zinc cache. The layout-level version of this rule — physically separating shared/ from local/ so the classification is enforceable by a directory walk — is deliberately left for a follow-up: it breaks on-disk layout and deserves its own change.

Why an MCP layer at all

The daemon does the heavy lifting, and agents could shell out to the CLI. The MCP layer earns its existence on three things:

• Force the workspace. Subagents share the session's server connection, so workspace identity must be explicit. A required schema field is stronger than convention, prompts, or docs: the call physically cannot be made without it.
• Save tokens — and the failure mode behind them. CLI output is for humans. An agent fed thousands of log lines starts managing output instead of fixing code: it diverts the log to a file, greps the file, and routinely misses the line that mattered. A ~200-token summary, streamed failures, and a searchable transcript one call away mean the divert-and-grep expedition never starts.
• Declare effects. Every tool carries the MCP effect annotation (read-only / additive / destructive), so a harness can auto-approve bleep.compile while still gating bleep.clean. Bash invocations get no such structure.

Also in this PR

• The whole run-history surface lives under one namespace: CLI bleep history / bleep history show / bleep history diff, MCP bleep.history.list / bleep.history.show / bleep.history.diff / bleep.history.diff-timing, wire dataKind bleep-history-id, field historyId, on-disk .bleep/builds/<variant>/history/. history because runs collides with bleep run and builds with bleep build; show follows the bleep build show precedent. bleep.history.list is new — the CLI listing as JSON, for parity.

• /deploy-local as a checked-in skill (eab72f2, f77c312): the local snapshot deploy recipe, executable, including the gotcha that bleep.restart severs the calling session's own MCP connection.

• The landing page tells this story in two sections — orchestration (one server, every worktree; forks start warm) and observability (the build that answers questions) — and sells the architecture behind it by name: data all the way down, from bleep.yaml to diffable runs, with the CLI surface alongside MCP (cdcaeae, 74625dd).

• The MCP docs page stops claiming run history lives in server memory, documents the per-worktree store, and lists bleep.history.diff / bleep.history.diff-timing in the tool table (fc3cfc4).

• docs/reference/cli regenerated via bleep gen-cli-docs — the new history pages plus the previously ungenerated copy-state page.

Verified

Over real stdio JSON-RPC against a live daemon (locally published snapshot): every workspace-acting tool lists directory as required in its schema; a valid directory bootstraps, compiles, and answers with a summary + historyId; relative paths, missing directories, and unknown historyIds fail with named errors; bleep.history.show with an invalid regex fails with the parse error, caret and all. The daemon-side store is pinned end-to-end by TranscriptStoreIntegrationTest (real protocol, ids in responses, determinism through the daemon), the CLI by HistoryCliIT (production BSP server, transcripts tagged and diffed over files), copy-state by the integration tests above plus CopyStateEndpointTest's state-sharing assertions, and the diff semantics by the 16-scenario suite. The demo output quoted here is verbatim from the deployed binary.

🤖 Generated with Claude Code