@qodeca/xezar 0.13.0 → 0.14.0

package/dist/mcp/service-adapter.js

@@ -0,0 +1,148 @@
+import { runIdParamSchema } from '../contract/index.js';
+import { hc } from 'hono/client';
+import { PROJECT_ID_RE } from '../workspace/config.js';
+/**
+ * The one seam every MCP operation reaches xezar's services through (#89, epic #67).
+ *
+ * N-02 is the rule this module exists for: UI and MCP share business rules, authorization,
+ * resource limits, locks and state transitions, and MCP never writes JSON or NDJSON around the
+ * services. A-08 is how it shows: a human and a leader act on the SAME task and configuration,
+ * and no MCP-only history or configuration exists.
+ *
+ * HOW. An operation is dispatched IN-PROCESS into the service's own chained route table — the
+ * Hono app's `request()` entry, typed by `hc<AppType>` — under `/api/v1/p/<bound project>/…`.
+ * No socket, no port, no TCP: the call never leaves the process (the transport is D-01's unix
+ * socket, which lands in front of this seam, not inside it). That is the smallest shape that keeps
+ * every invariant, because several of the rules a start must obey live ONLY in route handlers
+ * today — the models-lock 409, `stepsIssue`, the provider-availability re-probe, the account
+ * check, the follow-ups capability ceiling (`POST /runs` in `server/server.ts`). Calling
+ * `RunManager.startRun` directly would copy those checks into a second place, which is the drift
+ * this seam exists to prevent. Going through the route runs the SAME validator middleware, the
+ * same 400/404/409 answers, the same `ProjectContext` (so the same `RunStore`, `RunManager`,
+ * `AutomationStore`) and therefore the same workspace-wide `WorkspaceSemaphore` as the cockpit.
+ * MCP adds no queue, no agent-process controller, no store and no runner; it opens no file.
+ *
+ * NARROWING. This is not a proxy to every route (requirements § 8 says that is insufficient):
+ *   - the project is bound ONCE, at construction, from the connection (D-01/D-02: identity is a
+ *     property of the connection, never of anything the client says). No operation accepts a
+ *     project id, a path or a URL;
+ *   - the operation table is closed — each method is one named route, and there is no raw
+ *     `request(path)` escape hatch;
+ *   - a path parameter is checked against `runIdParamSchema` AND refused when it is a dot segment
+ *     (`.`/`..`), because the URL parser would resolve one and the call would land on a different
+ *     route than the one named. A refused id is answered without any dispatch.
+ *
+ * ORIGIN. Every result carries `origin: 'mcp'`, derived from the door the call came through —
+ * never from client input, and never from a request header, which any local process could send
+ * (D-06 § 10.4 rule 1). Where it is PERSISTED is D-06's audit record (§ 10.2), a separate writer
+ * that is later work; D-06 § 12.1 adds no field to the run record. So nothing is written for it
+ * here: the record, the event log and the files an MCP operation produces are the cockpit's.
+ *
+ * NOT READ HERE. Nothing private to `RunManager` — in particular no `ActiveRun` field, which is
+ * built at two sites (`execute`, `runContinuation`). An operation sees exactly what the route
+ * sends, so there is no second construction site for this seam to keep in step with.
+ */
+/** The origin marker every adapter result carries (N-04). */
+export const MCP_ORIGIN = 'mcp';
+/** Any absolute origin works — the request never leaves the process. The `host` is what the
+ *  request-origin guard (#426) checks, and an in-process call genuinely is this machine. No
+ *  `Origin` header is sent, which is how every non-browser local caller already reaches the API. */
+const IN_PROCESS_BASE = 'http://127.0.0.1';
+const IN_PROCESS_HOST = '127.0.0.1';
+const buildClient = (service) => hc(IN_PROCESS_BASE, {
+    fetch: async (input, init) => {
+        const headers = new Headers(init?.headers);
+        headers.set('host', IN_PROCESS_HOST);
+        headers.delete('origin');
+        const url = input instanceof Request ? input.url : String(input);
+        return service.request(url, { ...init, headers });
+    },
+});
+/** Thrown only by the constructor: an adapter bound to no valid project must not exist at all. */
+export class McpServiceAdapterError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'McpServiceAdapterError';
+    }
+}
+export class McpServiceAdapter {
+    origin = MCP_ORIGIN;
+    projectId;
+    api;
+    constructor(options) {
+        const { projectId } = options;
+        // The same rule the scope resolver applies (`projectIdSchema` in server.ts), checked here so
+        // a bad binding fails at connect time instead of answering a plausible 404 on every call.
+        if (projectId !== 'default' && !PROJECT_ID_RE.test(projectId)) {
+            throw new McpServiceAdapterError(`not a project id: ${JSON.stringify(projectId)}`);
+        }
+        this.projectId = projectId;
+        this.api = buildClient(options.service).api.v1.p[':projectId'];
+    }
+    listRuns() {
+        return this.settle(this.api.runs.$get({ param: this.scope() }), [200]);
+    }
+    getRun(runId) {
+        return this.withRunId(runId, (param) => this.api.runs[':id'].$get({ param }), [200]);
+    }
+    startRun(input) {
+        return this.settle(this.api.runs.$post({ param: this.scope(), json: input }), [201]);
+    }
+    patchRun(runId, input) {
+        return this.withRunId(runId, (param) => this.api.runs[':id'].$patch({ param, json: input }), [200]);
+    }
+    /** `expectedVersion` (#250) is the stale-write guard: the route refuses the change when the run
+     *  moved since that version was read. Every MCP tool that mutates a run passes one. */
+    cancelRun(runId, expectedVersion) {
+        return this.withRunId(runId, (param) => this.api.runs[':id'].cancel.$post({ param, json: guard(expectedVersion) }), [200]);
+    }
+    archiveRun(runId, archived = true, expectedVersion) {
+        return this.withRunId(runId, (param) => this.api.runs[':id'].archive.$post({ param, json: { archived, ...guard(expectedVersion) } }), [200]);
+    }
+    pinRun(runId, pinned = true, expectedVersion) {
+        return this.withRunId(runId, (param) => this.api.runs[':id'].pin.$post({ param, json: { pinned, ...guard(expectedVersion) } }), [200]);
+    }
+    scope() {
+        return { projectId: this.projectId };
+    }
+    /** Validate a run id BEFORE anything is dispatched, then call with the bound scope. */
+    withRunId(runId, call, success) {
+        const refusal = runIdRefusal(runId);
+        if (refusal)
+            return Promise.resolve({ ok: false, origin: MCP_ORIGIN, status: 400, error: refusal });
+        return this.settle(call({ ...this.scope(), id: runId }), success);
+    }
+    /**
+     * Map the service's answer onto a result. A success status WITHOUT a JSON body is an error,
+     * not an `undefined` value: "the service said nothing" and "the service said []" must never
+     * read the same to the leader.
+     */
+    async settle(pending, success) {
+        const res = await pending;
+        const body = await res.json().catch(() => undefined);
+        if (success.includes(res.status)) {
+            if (body === undefined) {
+                return { ok: false, origin: MCP_ORIGIN, status: 502, error: `service answered ${res.status} without a body` };
+            }
+            return { ok: true, origin: MCP_ORIGIN, status: res.status, value: body };
+        }
+        return { ok: false, origin: MCP_ORIGIN, status: res.status, error: errorMessage(body, res.status), body };
+    }
+}
+/** The guard as a body fragment: present only when there is a version to send. */
+function guard(expectedVersion) {
+    return expectedVersion === undefined ? {} : { expectedVersion };
+}
+function runIdRefusal(runId) {
+    if (runId === '.' || runId === '..' || !runIdParamSchema.safeParse({ id: runId }).success) {
+        return `not a run id: ${JSON.stringify(runId)}`;
+    }
+    return null;
+}
+function errorMessage(body, status) {
+    if (body && typeof body === 'object' && typeof body.error === 'string') {
+        return body.error;
+    }
+    return `service answered ${status}`;
+}
+//# sourceMappingURL=service-adapter.js.map

package/dist/mcp/service-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-adapter.js","sourceRoot":"","sources":["../../src/mcp/service-adapter.ts"],"names":[],"mappings":"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"}

package/dist/mcp/service.d.ts

@@ -0,0 +1,83 @@
+import { ProjectOwnership } from '../workspace/project-owner.ts';
+import { type McpTool, type McpToolContext, type McpToolResult } from './tool.ts';
+/**
+ * The service half of the IPC leg (D-01 § 1.2–1.5): the running xezar opens one
+ * Unix socket for a project and answers the bridge on it.
+ *
+ * Project binding lives HERE, not in any frame: the socket was opened for exactly
+ * one project, a request has no project field to name another, and `ctx.project`
+ * is the project this socket belongs to (§ 1.5, F-01, N-09). There is no loopback
+ * HTTP leg, so § 8's "equivalent enforcement for a loopback HTTP alternative" does
+ * not arise; the same-user boundary is the directory's 0700 and the socket's 0600
+ * (D-01 E7).
+ *
+ * ## One connection is one MCP session (#302, D-02)
+ *
+ * The bridge keeps ONE connection for the life of its `xez mcp` process. The session key is minted
+ * here, per connection — never read from a frame, so no client can name or borrow another's
+ * session. `session/open` makes that session the project's owner through `ProjectOwnership`
+ * (D-02.2) or answers project-occupied; `health` and `tools/call` need the session to still own the
+ * project, and every mutating call is fenced on its token right before it runs (D-02.3).
+ *
+ * Who ends a session, and nothing else does (D-02.4):
+ * - the connection closing — the bridge exited, was killed, or its client went away. That is the
+ *   "confirmed termination" signal, observed in milliseconds (D-02 X2);
+ * - the owner's lease lapsing, which only a frozen service can cause, because the renewal timer
+ *   runs in this process and needs no request and no model turn. MODEL SILENCE IS NOT SESSION
+ *   DEATH: an idle connection keeps its project for as long as it stays open;
+ * - the service stopping (`close()`), which ends every session (D-02 § 5).
+ * One request finishing, failing or timing out ends nothing.
+ *
+ * Ending a session touches the owner claim and nothing else (N-05). A tool call still running
+ * when its connection closes runs to completion — its answer is simply not sent — and no path
+ * here reaches a run: a disconnect never cancels a task.
+ */
+export interface McpServiceOptions {
+    readonly project: McpToolContext['project'];
+    readonly version: string;
+    readonly tools: readonly McpTool[];
+    readonly env?: NodeJS.ProcessEnv;
+    readonly platform?: NodeJS.Platform;
+    /**
+     * Extra context every tool call gets — the running app's in-process entry (`service`) in
+     * production. It can never replace `project` or `xezarVersion`: the binding is this socket's.
+     */
+    readonly context?: Readonly<Record<string, unknown>>;
+    /** The MCP door: wraps every tool call whose arguments parsed (see `startMcpService`). */
+    readonly door?: McpDoor;
+    /** Where the owner claims live (D-02.8). Defaults to the project's own `.local/xezar`. */
+    readonly dataDir?: string;
+    /** The owner slot to enforce. Absent: one is built per socket. */
+    readonly ownership?: ProjectOwnership;
+    /** Told when a session becomes the owner and when its connection closes — push delivery (#309). */
+    readonly sessions?: McpSessionObserver;
+}
+/**
+ * The two session edges push delivery (#309) follows: `opened` once `session/open` made the session
+ * the project's owner, `closed` when its connection closes (before the claim is released). Neither
+ * may fail a session: a throw is one warning and the session carries on (N-07).
+ */
+export interface McpSessionObserver {
+    opened(sessionKey: string): void;
+    closed(sessionKey: string): void;
+}
+/**
+ * Runs around one validated tool call. `invoke` is the tool itself; a throw from either reaches
+ * the same handler a tool's own throw does, so nothing secret reaches the response (F-15).
+ */
+export type McpDoor = (call: {
+    readonly tool: McpTool;
+    readonly args: Record<string, unknown>;
+    readonly ctx: McpToolContext;
+}, invoke: () => Promise<McpToolResult>) => Promise<McpToolResult>;
+export interface McpServiceHandle {
+    readonly path: string;
+    /** Stop answering and remove the socket. Synchronous, so a shutdown handler can call it. */
+    close(): void;
+}
+/**
+ * Open the project's socket. Throws a one-line, readable error when it cannot —
+ * whether that is fatal is the CALLER's policy, and the cockpit's policy is that
+ * it never is (N-07): see `startMcpService` in ./index.ts.
+ */
+export declare function listenMcpSocket(opts: McpServiceOptions): Promise<McpServiceHandle>;

package/dist/mcp/service.js

@@ -0,0 +1,233 @@
+import { randomUUID } from 'node:crypto';
+import { chmod, lstat, mkdir, unlink } from 'node:fs/promises';
+import { createConnection, createServer } from 'node:net';
+import { assertXezarHomeWriteIsSandboxed } from '../paths.js';
+import { projectDataDir } from '../project-data-paths.js';
+import { ProjectOwnership, sessionExpiredError } from '../workspace/project-owner.js';
+import { IPC_PROTOCOL_VERSION, LineFramer, encodeFrame, ipcRequestSchema, mcpSocketDir, mcpSocketLocation, toolCallParamsSchema, } from './ipc.js';
+import { errorResult } from './tool.js';
+/**
+ * Open the project's socket. Throws a one-line, readable error when it cannot —
+ * whether that is fatal is the CALLER's policy, and the cockpit's policy is that
+ * it never is (N-07): see `startMcpService` in ./index.ts.
+ */
+export async function listenMcpSocket(opts) {
+    const location = mcpSocketLocation(opts.project, opts.env, opts.platform);
+    if (location.kind === 'unavailable')
+        throw new Error(location.reason);
+    const dir = mcpSocketDir(opts.env);
+    assertXezarHomeWriteIsSandboxed(dir, opts.env);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    // mkdir leaves an existing directory's mode alone; this one is ours alone.
+    await chmod(dir, 0o700);
+    await clearStaleSocket(location.path);
+    // Built only once the socket path is ours: it writes nothing until a session opens.
+    const ownership = opts.ownership ??
+        new ProjectOwnership({ dataDir: opts.dataDir ?? projectDataDir(opts.project.root), projectId: opts.project.id });
+    const sockets = new Set();
+    const server = createServer((socket) => {
+        sockets.add(socket);
+        socket.on('close', () => sockets.delete(socket));
+        serveConnection(socket, opts, ownership);
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(location.path, () => {
+            server.off('error', reject);
+            resolve();
+        });
+    });
+    // Node creates the socket at the umask default (755 observed, D-01 E7). The 0700
+    // directory already fences it off during this gap.
+    try {
+        await chmod(location.path, 0o600);
+    }
+    catch (err) {
+        server.close();
+        throw err;
+    }
+    server.on('error', (err) => console.warn(`[xez] MCP socket error: ${err.message}`));
+    return {
+        path: location.path,
+        close() {
+            for (const socket of sockets)
+                socket.destroy();
+            server.close();
+            // D-02 § 5: a service that stops ends every session, and its claim goes with it.
+            ownership.dispose();
+        },
+    };
+}
+/**
+ * A socket file left by a xezar that died without closing is removed; a LIVE one
+ * belongs to another cockpit serving the same project and is never stolen; any
+ * other file at that path is not ours and is left alone.
+ */
+async function clearStaleSocket(path) {
+    let isSocket;
+    try {
+        isSocket = (await lstat(path)).isSocket();
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return;
+        throw err;
+    }
+    if (!isSocket)
+        throw new Error(`${path} exists and is not a socket — leaving it alone`);
+    if (await socketIsLive(path)) {
+        throw new Error('another xezar is already serving this project over MCP');
+    }
+    await unlink(path);
+}
+function socketIsLive(path) {
+    return new Promise((resolve) => {
+        const probe = createConnection(path);
+        probe.once('connect', () => {
+            probe.destroy();
+            resolve(true);
+        });
+        probe.once('error', () => resolve(false));
+    });
+}
+function serveConnection(socket, opts, ownership) {
+    // Minted here, per connection. Nothing a client sends can choose it.
+    const sessionKey = randomUUID();
+    socket.on('error', () => {
+        // A bridge that vanished mid-answer is not the cockpit's problem.
+    });
+    // Confirmed termination (D-02.4 signal 1): the connection is the session, so its close frees the
+    // project at once. `release` touches the owner claim and nothing else — calls still running go
+    // on running, and no run is touched (N-05).
+    socket.once('close', () => {
+        // The session's event controller ends with its connection, before the claim goes (#309).
+        observe(opts, 'closed', sessionKey);
+        ownership.release(sessionKey);
+    });
+    const send = (response) => {
+        if (!socket.destroyed)
+            socket.write(encodeFrame(response));
+    };
+    const framer = new LineFramer((line) => {
+        void answer(line, opts, ownership, sessionKey).then(send);
+    }, () => send(failure(null, 'bad-frame', 'frame too large')));
+    socket.on('data', (chunk) => framer.push(chunk));
+}
+async function answer(line, opts, ownership, sessionKey) {
+    let json;
+    try {
+        json = JSON.parse(line);
+    }
+    catch {
+        return failure(null, 'bad-frame', 'frame is not JSON');
+    }
+    const parsed = ipcRequestSchema.safeParse(json);
+    if (!parsed.success)
+        return failure(null, 'bad-frame', 'frame is not a request');
+    const request = parsed.data;
+    if (request.v !== IPC_PROTOCOL_VERSION) {
+        return {
+            ...failure(request.id, 'version-mismatch', `this xezar speaks bridge protocol ${IPC_PROTOCOL_VERSION}, the bridge sent ${request.v}`),
+            serviceVersion: opts.version,
+        };
+    }
+    const ctx = { ...opts.context, project: opts.project, xezarVersion: opts.version };
+    switch (request.method) {
+        case 'session/open': {
+            const opened = await openSession(request.id, ownership, sessionKey, opts.project.id);
+            // Push delivery starts for the owner at once — on by default, no flag (#309).
+            if (opened.ok)
+                observe(opts, 'opened', sessionKey);
+            return opened;
+        }
+        case 'health': {
+            if (ownership.sessionToken(sessionKey) === undefined)
+                return expired(request.id, opts.project.id);
+            const result = {
+                ipcVersion: IPC_PROTOCOL_VERSION,
+                xezarVersion: opts.version,
+                project: { id: opts.project.id, name: opts.project.name },
+            };
+            return { v: IPC_PROTOCOL_VERSION, id: request.id, ok: true, result };
+        }
+        case 'tools/call': {
+            // The token this request is bound to, taken as it arrives; the fence below compares it again.
+            const token = ownership.sessionToken(sessionKey);
+            if (token === undefined)
+                return expired(request.id, opts.project.id);
+            const params = toolCallParamsSchema.safeParse(request.params);
+            if (!params.success)
+                return failure(request.id, 'invalid-params', 'tools/call needs a tool name');
+            const tool = opts.tools.find((t) => t.name === params.data.name);
+            if (!tool)
+                return failure(request.id, 'unknown-tool', `unknown tool: ${params.data.name}`);
+            const outcome = await callTool(tool, params.data.arguments, ctx, opts.door, () => ownership.checkMutation(token).ok);
+            if (outcome === 'fenced')
+                return expired(request.id, opts.project.id);
+            return { v: IPC_PROTOCOL_VERSION, id: request.id, ok: true, result: outcome };
+        }
+        default:
+            return failure(request.id, 'unknown-method', `unknown method: ${request.method}`);
+    }
+}
+function observe(opts, edge, sessionKey) {
+    try {
+        opts.sessions?.[edge](sessionKey);
+    }
+    catch (err) {
+        console.warn(`[xez] MCP event delivery hook failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/** Make this connection's session the project's owner, or say why not (D-02.2, § 4). */
+async function openSession(id, ownership, sessionKey, projectId) {
+    let acquired;
+    try {
+        acquired = await ownership.acquire(sessionKey);
+    }
+    catch (err) {
+        // The claim could not be written (a read-only data directory, a full disk). Fail closed: no
+        // session, so no call runs. The path stays in the cockpit's log, never in a response (F-15).
+        console.warn(`[xez] MCP owner claim failed: ${err instanceof Error ? err.message : String(err)}`);
+        return failure(id, 'internal', 'xezar could not record which MCP client owns this project; the cockpit log has the details');
+    }
+    switch (acquired.outcome) {
+        case 'owner':
+            return { v: IPC_PROTOCOL_VERSION, id, ok: true, result: { owner: true } };
+        case 'occupied':
+            return { ...failure(id, 'project-occupied', acquired.error.message), rpcError: acquired.error };
+        case 'closed':
+            // The connection is gone; nobody reads this answer.
+            return expired(id, projectId);
+    }
+}
+async function callTool(tool, args, ctx, door, stillOwner) {
+    const parsed = tool.inputSchema.safeParse(args ?? {});
+    // An argument error is a tool result, not a protocol error, so the model can
+    // correct itself (MCP 2025-11-25, "Error Handling").
+    if (!parsed.success) {
+        const issues = parsed.error.issues.map((i) => `${i.path.join('.') || '(arguments)'}: ${i.message}`);
+        return errorResult(`Invalid arguments for ${tool.name}: ${issues.join('; ')}`);
+    }
+    // The fence (D-02.3): equality with the live owner's token, immediately before anything that can
+    // change state. A read changes nothing, so it only needed the session check on arrival.
+    if (tool.annotations?.readOnlyHint !== true && !stillOwner())
+        return 'fenced';
+    try {
+        const invoke = () => tool.call(parsed.data, ctx);
+        return await (door ? door({ tool, args: parsed.data, ctx }, invoke) : invoke());
+    }
+    catch (err) {
+        // The exception text stays in the cockpit's own log: it can quote a command
+        // line or a file, and nothing secret may reach a tool response (F-15).
+        console.warn(`[xez] MCP tool ${tool.name} failed: ${err instanceof Error ? err.message : String(err)}`);
+        return errorResult(`${tool.name} failed inside xezar; the cockpit's log has the details.`);
+    }
+}
+function expired(id, projectId) {
+    const rpcError = sessionExpiredError(projectId);
+    return { ...failure(id, 'session-expired', rpcError.message), rpcError };
+}
+function failure(id, code, message) {
+    return { v: IPC_PROTOCOL_VERSION, id, ok: false, error: { code, message } };
+}
+//# sourceMappingURL=service.js.map

package/dist/mcp/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../../src/mcp/service.ts"],"names":[],"mappings":"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"}

package/dist/mcp/session-binding.d.ts

@@ -0,0 +1,105 @@
+import type { RunRecord } from '../runs/store.ts';
+import { type ProjectContext, type ProjectContexts } from '../server/project-context.ts';
+/**
+ * The MCP session's project binding (#87; F-01, F-16, N-01, N-09, S-03, A-02).
+ *
+ * A session is bound to exactly ONE project, once, from a TRUSTED source: the id of
+ * the project whose socket accepted the connection (D-01 § 1.5 and § 6 — "the trusted
+ * connection binding is which socket the peer connected to"). That id is chosen by the
+ * service when it opens the socket; nothing a client sends — a tool argument, a
+ * project alias, a URL, prompt text, a resource identifier read out of a result —
+ * reaches this module as a project selector, because no method below accepts one.
+ * Tasks, files and results are data, not authority (N-09).
+ *
+ * This is deliberately NOT `resolveProjectScope` (server.ts). That resolver reads the
+ * project from the REQUEST and maps `default` to the boot project, which is right for
+ * the same-origin cockpit and wrong here (requirements § 8: derive identity from the
+ * connection, never forward an arbitrary `projectId`). So:
+ *
+ * - `default` is never a binding. It is a reserved alias, never an allocated slug
+ *   (`RESERVED_PROJECT_IDS`), and "whichever project the service booted in" is not a
+ *   project. A binding names the registry id itself.
+ * - There is no fallback. A bound project that is gone fails closed with its own
+ *   reason; nothing here ever resolves the boot project or any other id.
+ * - The binding is re-checked on EVERY access, not just at bind time. The context map
+ *   caches a built context and would keep handing it out after its folder was deleted
+ *   or replaced, so each access re-resolves through `ProjectContexts.context(boundId)`
+ *   and then verifies the root is still the very directory the session was bound to
+ *   (same realpath, same device and inode). A folder deleted, moved away, swapped for a
+ *   symlink or recreated at the same path is `missing-root`, never "carry on".
+ *
+ * Rejections disclose nothing (N-01). Every error message below is a fixed sentence:
+ * it never echoes a client-supplied identifier (which could be another project's id or
+ * run id), and never names the bound project's path. `projectId` on the error object
+ * is only ever the BOUND project's id, which the leader already knows. This module
+ * writes no log line.
+ *
+ * Scope: binding and scope enforcement only. Occupancy, leases and fencing are D-02
+ * (#99); the socket is D-01 (#86); the operations themselves go through the shared
+ * service adapter (#89). Releasing or losing a binding touches nothing on
+ * `RunManager` (N-05).
+ */
+/** Why an MCP session cannot act. `unknown-project` / `missing-root` keep the meaning
+ *  `ProjectContextError` gives them (404 / 409); `unavailable` is a bound project
+ *  that could not be opened for any other reason (another process owns its data, a
+ *  filesystem error) — its cause stays server-side; `not-in-project` is a resource this session
+ *  cannot see, whether it belongs to another project or to none. */
+export type McpScopeFailure = 'unknown-project' | 'missing-root' | 'unavailable' | 'not-in-project';
+/** The one error this module throws. Carries no client-supplied value. */
+export declare class McpScopeError extends Error {
+    readonly reason: McpScopeFailure;
+    /** The BOUND project's id — never a foreign or client-supplied one. */
+    readonly projectId: string;
+    constructor(reason: McpScopeFailure, 
+    /** The BOUND project's id — never a foreign or client-supplied one. */
+    projectId: string, 
+    /** The underlying failure, for the service's own log only — never sent to a client. */
+    cause?: unknown);
+}
+/** What the binding needs from the context map — `ProjectContexts` in production. */
+export type McpProjectContextSource = Pick<ProjectContexts, 'context'>;
+/**
+ * The live binding a connection holds. Construct only through `bindMcpSession`.
+ * Every read and write an MCP operation makes goes through `project()`, `run()` or
+ * `withRun()`; there is no other door to a `ProjectContext` for it.
+ */
+export declare class McpSessionBinding {
+    #private;
+    private constructor();
+    /** The bound registry id. Fixed for the life of the session; there is no setter. */
+    get projectId(): string;
+    /**
+     * Bind a session to `trustedProjectId` — the registry id of the project whose socket
+     * accepted this connection, as the SERVICE knows it. Never pass anything read from a
+     * client frame, a tool argument, a path or a URL here: that value is untrusted by
+     * definition, and binding to it is exactly the escape F-01 forbids.
+     *
+     * Fails closed with `McpScopeError`: `default` and every other reserved alias, a
+     * malformed id, an unregistered project and a missing root are all refused — there
+     * is no fallback to the boot project. The constructor is private, so this is the
+     * only way a binding comes into existence.
+     */
+    static bind(contexts: McpProjectContextSource, trustedProjectId: string): Promise<McpSessionBinding>;
+    /**
+     * The bound project's context, re-validated on every call. Throws `McpScopeError`
+     * when the project is no longer registered, its folder is gone or replaced, or
+     * another process owns its data. Never returns any other project's context.
+     */
+    project(): Promise<ProjectContext>;
+    /**
+     * One task of the BOUND project, by id. The id is client data: it is shape-checked
+     * against the contract's run-id rule and looked up in the bound project's own store
+     * only, so another project's id — or any string naming a project, alias, path or
+     * URL — reads as `not-in-project`, identically to an id that exists nowhere. The
+     * error never repeats the id.
+     */
+    run(runId: unknown): Promise<RunRecord>;
+    /**
+     * Gate for an operation on one task: resolves the task in the bound project first
+     * and only then runs `operation` with the bound context and that task. A foreign or
+     * unknown id is refused before `operation` is called, so it causes no side effect.
+     */
+    withRun<T>(runId: unknown, operation: (run: RunRecord, ctx: ProjectContext) => T | Promise<T>): Promise<T>;
+}
+/** Bind a session — see `McpSessionBinding.bind`. */
+export declare function bindMcpSession(contexts: McpProjectContextSource, trustedProjectId: string): Promise<McpSessionBinding>;