Module lease 

Task 19 (Commit B) — session-scoped exact MCP runtime leases (spec §7.4).

Deferred descriptor-backed MCP tools execute ONLY through this manager, AFTER the ExecutionGate has already authorized the exact call. The manager owns every live MCP child for the runtime:

• a lease is keyed by (session, server) and PINNED to the config fingerprint it was acquired under; per-key SINGLE-FLIGHT acquisition (a Starting placeholder holding a watch receiver, whose stored state makes wakeups lost-proof) guarantees concurrent first calls never spawn duplicate children, and the manager map lock is NEVER held across process/pipe I/O;
• acquisition starts exactly one child (kill_on_drop), initializes and lists ONCE, and pins the bounded listing; every call validates the selected exact runtime name and canonical schema digest against the cached expectation BEFORE tools/call — a mismatch terminates the poisoned lease without calling;
• revocation/termination semantics (exact and honest): revocation marks the lease cancelled under the per-lease call gate. A call that already passed the gate check (taken while holding the connection lock) MAY still complete; NO call passes the gate after revocation returns, and a completing call that observes cancellation kills the child before releasing the connection. Teardown is guaranteed by kill_on_drop once the last Arc drops (map removal plus bailing callers make that inevitable) with an immediate best-effort start_kill accelerator — the manager retains nothing;
• idle leases are reaped opportunistically with a CONSTANT per-pass scan cap; session end is the drop of the LAST owner of the shared durable McpSessionEndGuard scope (runtime clones + in-flight streams hold it; no per-turn guard exists). No PID signalling, no long-lived task, no unbounded channel;
• a server configured shared: true (daemon mode, opt-in) is keyed under SHARED_SESSION_KEY instead of the session: one child serves every session, terminate_session spares it, reap_idle and terminate_all still reap it. Every call still validates exact name + digest; sharing widens the CHILD, never the grant.

Structs

McpLeaseCapability

Typed per-session lease capability handed to tool contexts: the exact session identity plus the shared manager. Never widens to a server grant — every call re-validates the exact tool and fingerprint.

McpRuntimeManager

Session-scoped exact MCP runtime lease manager. See module docs.

McpSessionEndGuard

Durable last-owner session scope. The Runtime mints ONE of these per tool session (wrapped in an Arc shared by every runtime clone and in-flight stream); streams HOLD it, never construct or drop their own. Leases therefore survive across provider turns, and only the drop of the LAST owner — true session end — terminates the session’s leases.

Enums

McpLeaseError

Typed lease failures. Provider-controlled content never appears here — only static text, local identities, and numeric metadata.

Constants

DEFAULT_IDLE_MAX

Default idle bound for opportunistic reaping.

MAX_LIVE_LEASES

Hard cap on simultaneously live leases per manager, so termination fanout (and cleanup-task count) is always bounded.

REAP_SCAN_MAX

Reap passes scan up to the FULL capped map (equal to the live-lease cap), so idle entries can never starve behind an active HashMap iteration prefix.

SHARED_SESSION_KEY

Lease-map session key for shared: true servers (one child per process, not per session). Never a real session’s key: terminate_session skips it explicitly.

Functions

config_source_from_disk

Production config source: profile-resolved mcp.json lookup.

lease_session_key

Session component of the lease key for server under config.

Type Aliases

ConfigSource

Injectable current-config lookup: production reads mcp.json per acquisition (bounded local file read); tests inject a mutable map.