[sanchitrk]

Summary

Stacked on #81. Decides who shares a running MCP server and how long it lives. Until now every session ran its own servers until the process exited.

Scopes (scope in mcp.json, default session)

Scope	Shared by	stdio cwd / roots on a local sandbox
session	one session	the session's directory
space	sessions in one space (sandbox + folder)	the space's folder
app	every session	where the app started, no roots

• When the sandbox isn't local, session and space servers start in hostDir, else hostCwd, and get no roots. MCP stays host-only.
• An instance is keyed by its scope plus everything its connection is made from (config minus exposure, cwd, roots). Sessions that resolve different settings for a server, for example through different project files, never share it.
• Exposure stays each session's own. Two sessions can share an instance and declare different tools.

Lifetime

• Each drain leases its session's instances for as long as it runs (runner/execute.ts, next to the mount).
• An instance no session uses closes at once, for example when a server is removed or its settings change.
• An instance no drain holds closes after an idle timeout: 10 minutes, or the Harness.layer option mcpIdleTimeout. The next exchange that needs it starts it again.
• Space changes need no hooks. After rehome or absorb, a session's next exchange resolves a different key and drops the old instance; an archived env's instances idle out.

Also

• A session's servers keep their config order across exchanges, so a restarted server's tools no longer move to the end of the list. That's more stable for prompt caching.
• Docs: "Sharing a Server" and idle close on the MCP page.

Review fixes (2026-10-15)

• Name in the key. An instance key includes the server's name. Two entries with the same settings are two instances, and renaming a server can't close the instance its new name uses.
• Exact lease counts. Leases count each instance once per session, so an alias can't drive a count negative and keep a server from idling out.
• Atomic bookkeeping. Reconcile updates every membership and lease count in one step and closes unused instances on their own, so an interrupted exchange can't leave a shared instance counting a session it no longer has.
• Idle timer from the start. An instance created with no drain holding it still gets an idle timer.
• Canonical keys. Keys are canonical JSON, so the same env / headers in another order share an instance.
• Dismissed: a lease arriving mid-reconcile. The coordinator runs one drain per session, and reconcile runs inside it. The atomic bookkeeping removes the window anyway.
• Test: the scope test adds twin, a server with mine's exact settings. It runs as its own process, and everything still idles out.

Tagged errors

Every MCP failure is now a Schema.TaggedError (UnavailableError, ToolCallError, ResourceError, ValueError, OutputError; connect attempts use ConnectError). The tool adapter turns error.message into model text only at the edge. The model-facing text is unchanged, and no artifact moved.

Codemode and deferred exposure

mcp.json accepts direct, hidden, codemode, deferred, and codemode-deferred as an alias, so entries copied from other agents stay valid.

• Until codemode and tool_search exist, codemode / deferred tools aren't declared, and the session is warned once.
• Resource tools are declared when a server with resources is direct, and reach every server with resources that isn't hidden.
• The default stays direct for now, and flips to codemode with the codemode work.

CLI end-to-end

packages/codework/test/cli.mcp.test.ts spawns the real codework run with mcp.json, a fake OpenAI-compatible provider and a hand-written stdio MCP server. It checks that:

• the tool is declared with the server's schema
• the call's result reaches the model
• the server ran in the session's directory
• the server is gone after the CLI exits

Artifact: cli.mcp.json.

Review fixes (2026-10-24)

• Failed instances recover: an instance whose connect failed is restarted at the next exchange, so a shared space / app instance no longer strands every later session.
• Carried over from feat(harness): run MCP servers per thread and declare their tools #80 / feat(harness): add MCP resource tools and keep oversized output on the host #81: tool-list refresh without the server lock, plain resource failures, resource tools waiting for connecting servers.
• Resource links: point to read_mcp_resource only when that tool is declared (a deferred server with one direct tool no longer names it).
• Session records: a session with no MCP servers is dropped once its drain ends. Closing a session's servers on archive / delete waits for a session archive or delete operation, which doesn't exist yet.
• Scope test: holds a lease across its three runs, so a slow runner can't change its pids.
• Docs: app servers get no roots.
• Second pass: the session runtime's race and shutdown fixes from feat(harness): run MCP servers per thread and declare their tools #80 are carried onto the scoped service.
• Third pass: the log-write fix from feat(harness): run MCP servers per thread and declare their tools #80, on the scoped service.

Test plan

• test/mcp.session.test.ts gets a new scope test, through the full harness with real stdio servers. Sessions A and B share a space and C is in another, each calling a session, a space and an app server:
  • session: three processes
  • space: A and B share one, C has its own
  • app: one process for all three
  • After the drains end, every instance idles out and its process is gone. A later run starts fresh instances.
  • Artifact: mcp.session.scopes.json, stable across runs.
• Lifecycle artifact: only the more stable tool order changed.
• Full harness suite: 525 passed, 34 skipped (live/remote)
• vp check and vp run typecheck

🤖 Generated with Claude Code

[sanchitrk]

Review (2026-10-24)

No blockers. Checked and correct:

• Lease and membership bookkeeping under concurrent drains.
• Idle close vs. a call that is starting: the lease is taken in execute.ts before runner.run.
• inflight gating on retire and release.
• rehome / absorb key changes.
• Keys hold raw templates, not resolved secrets.

should-fix: a shared instance whose first connect failed is never retried

• Where: mcp.ts L565–588. Same root cause as the feat(harness): run MCP servers per thread and declare their tools #80 finding, and worse here.
• Scenario:
  1. An app-scoped server is unreachable when the first session starts, for example with the VPN off.
  2. Every later session, in any project, joins that failed instance with no tools.
  3. This lasts until no session has drained for 10 minutes.
• Fix: in reconcile, restart existing instances that are failed / disconnected with no live, no attempt and no tools, and push them to started.

nit: the sessions map is never pruned

• Where: mcp.ts L506–521.
• What happens: a finished or deleted session keeps its record, and its id stays in server.users. A long-running server grows by one entry per session. A shared instance then never takes the "no users, close now" path; it only idles out.
• Fix: drop the session when it is deleted or archived, or when its last lease releases and it has no servers.

nit: simplify the lease counting

• What to derive: "held" can come from users' lease counts ([...server.users].some(id => (sessions.get(id)?.leases ?? 0) > 0)). Re-arm in used(session). That replaces the per-instance mirrored leases, which already had one fixed bug.
• Timer: keep one timer fiber per instance and interrupt it on re-arm, instead of generation. Every release currently forks a fresh 10-minute sleeper.

nit: the scope test is timing-sensitive

• Where: mcp.session.test.ts L418 uses mcpIdleTimeout: "1500 millis".
• Why: the gaps between the sequential a/b/c runs have no lease. On a slow runner, setup between runs can take over 1.5 s, so pids change and the artifact drifts.
• Fix: hold a lease across the three runs, or run them concurrently, and use the short timeout only for the idle phase.

DevX

• Idle close for session scope: it also closes a session's own servers after 10 minutes without a drain. That throws away state for stateful servers (browser, DB session) while the user is thinking.
  • The cheaper alternative: exempt session scope, since those instances already close when the session stops naming them.
  • Worth deciding before this is user-facing.
• Docs: say that app servers get no roots, so a filesystem server configured with "." isn't a surprise.