@qodeca/xezar 0.13.0 → 0.14.0

package/dist/mcp/audit-trail.d.ts

@@ -0,0 +1,162 @@
+import { type AuditEntry, type AuditOrigin, type AuditOutcome, type AuditResource } from '../contract/index.js';
+/**
+ * The audit trail (#102) — D-06 § 10, requirement N-04. Built for MCP and cockpit operations;
+ * writing MCP operations today, and only those (see THE SHARED PATH below).
+ *
+ * WHAT. One append-only NDJSON file per project, `<project>/.local/xezar/mcp-audit.ndjson`, one
+ * `AuditEntry` (packages/contract/src/mcp-audit.ts) per settled operation: action, time, project,
+ * resource, outcome and ORIGIN, plus D-06's join fields. It is written, never required: a missing
+ * file reads as an empty trail, and deleting it discards history and nothing else. It lives under
+ * `.local/`, which `ensureProjectDataIgnored` already blanket-ignores (D-06 § 13.2).
+ *
+ * THE SHARED PATH, AND THE ONE DOOR THAT USES IT. A door stamps its origin through an
+ * `AuditChannel`: the entry point that owns the door asks `trail.channel(origin)` ONCE and hands
+ * operations to it. The origin is therefore derived from which door the call came through — an
+ * operation object has no origin and no project field, and a stray `origin` or `projectId` key on
+ * one is ignored (D-06 § 10.4 rule 1). That is also the marker #106 reads to tell the leader's own
+ * echoes from new events.
+ *
+ * **Exactly one door does this today, and it is the MCP one:** `mcp/index.ts:254` builds
+ * `.channel('mcp')`, and it is the only non-test construction of this class in `packages/`
+ * (grepped for the type and for `.channel(` at `87d9f0d`, 2026-09-12). The cockpit's HTTP routes,
+ * the automation scheduler and headless `xezar run` are the doors the design expects and they
+ * record NOTHING — so `ui` is written only by tests (`audit-trail.test.ts`, `echo-guard.test.ts`,
+ * `test/helpers/ab-fixture.ts`), and `automation` and `cli` are written nowhere at all. That is decided for 0.14.0, not an oversight (#266, D-06 § 10.6);
+ * wiring the other three is #364. `channel()` takes any `AuditOrigin` because those doors are the
+ * point, but do not read this comment as a description of four live writers.
+ *
+ * MUST vs SHOULD (D-06 § 10.2, N-04 "should"):
+ *   - MUST: the project id comes from the trusted scope, the origin from the door, and no secret,
+ *     free text, path or foreign identifier is written (§ 10.3, F-15, F-12, N-01).
+ *   - MUST: the record grants nothing (§ 10.4 rule 3). Nothing here answers "may X do Y", and no
+ *     method consults the trail before an effect — a caller's own permission check runs first and
+ *     a refusal is simply recorded as `rejected`. An `origin: 'ui'` entry never widens MCP.
+ *   - SHOULD: the entry itself. Recording is best-effort by design: a write that fails is warned
+ *     about once and never fails the operation, which is the opposite of the receipt journal's
+ *     refuse-before-effect rule (D-06 § 7.5) and deliberately so — idempotency is mandatory, audit
+ *     is not.
+ *
+ * NO SECRETS, TWICE. First by construction: the schema has no free-text field, and payloads enter
+ * only as a SHA-256 digest (D-06 § 5.4). Second by value: every client-influenced identifier
+ * (`resource.id`, the operation id, the version token) is checked against the host's secret env
+ * values, the caller's known secrets (the MCP connection token, D-04) and the well-known token
+ * shapes, and a field that matches is DROPPED rather than masked. The check deliberately ignores
+ * `XEZ_REDACT_SECRETS=0`: that opt-out exists because masking can corrupt a transcript, and
+ * dropping an audit field corrupts nothing.
+ *
+ * RETENTION IS OPEN. N-04 keeps it open, D-06 § 10.5 does not close it, and D-09 B-23 fixes only
+ * the mechanism (count-based, never evicting an entry whose run is still kept) with the count
+ * UNRESOLVED (U-2). So nothing here evicts, and no period or count is asserted.
+ */
+/** File name under the project's data dir (`.local/xezar/`). D-06 § 10.5 puts it beside the receipts. */
+export declare const AUDIT_TRAIL_FILE = "mcp-audit.ndjson";
+export declare const auditTrailPath: (dataDir: string) => string;
+/** The trusted scope a trail is bound to — a project context's own id and data dir. */
+export interface AuditScope {
+    /** The resolved registry id. Never the `default` boot alias, which would split one history in two. */
+    projectId: string;
+    dataDir: string;
+}
+export interface AuditTrailOptions {
+    /** Clock, injectable for tests. */
+    now?: () => Date;
+    /** Secrets the caller knows about that are not in the env — the MCP connection token (D-04). */
+    secretValues?: () => readonly string[];
+    /** Where the one-time write/read warning goes. */
+    warn?: (message: string) => void;
+}
+/**
+ * What an entry point may say about an operation. Deliberately no `origin` and no `projectId`:
+ * both are properties of the door and the scope, never of the operation.
+ */
+export interface AuditedOperation {
+    /** Dotted action id, e.g. `runs.create`. */
+    action: string;
+    /** The resource acted on, when known before the effect. */
+    resource?: AuditResource;
+    /** The zod-PARSED payload. Only its digest is kept; never the raw params (D-06 § 5.4 step 1). */
+    payload?: unknown;
+    /** The `expectedVersion` the caller sent (D-06 § 4.2). Kept only when it has the `rev1` shape. */
+    expectedVersion?: string;
+    /** MCP only — the client's `operationId` (D-06 § 5.2). */
+    operationId?: string;
+    /**
+     * MCP only — the D-02.3 fencing token the mutation arrived under, `<wall-clock ms>-<UUIDv4>`, as
+     * the receipt journal records it. Only the wall-clock prefix is kept: the full token passes the
+     * owner's equality fence, so it is authority and never enters the trail.
+     */
+    ownerGeneration?: string;
+}
+export interface AuditSettlement {
+    outcome: AuditOutcome;
+    /** Short machine code for a non-`ok` outcome, e.g. `stale_version`. Never an error message. */
+    errorCode?: string;
+    /** The resource the effect produced (a created run), when it was unknown before. */
+    resource?: AuditResource;
+}
+/** Thrown by an effect to refuse BEFORE anything happened: validation, permission, stale version. */
+export declare class AuditRejection extends Error {
+    readonly code: string;
+    constructor(code: string);
+}
+/**
+ * The outcome an HTTP status stands for, for callers that settle through a route (the cockpit's
+ * handlers, and the MCP adapter, which dispatches into the same routes). The routes validate as
+ * middleware and answer 4xx before any effect, so a 4xx is a refusal; a 5xx may have come after
+ * the effect started, so it is `unverified`, never `rejected`.
+ */
+export declare function settlementForStatus(status: number): AuditSettlement;
+export interface AuditReadResult {
+    entries: AuditEntry[];
+    /** Lines that failed to parse or validate — skipped, never fatal (D-06 § 7.4's line-level rule). */
+    quarantined: number;
+}
+export declare class AuditTrail {
+    readonly scope: AuditScope;
+    private readonly now;
+    private readonly callerSecrets;
+    private readonly warn;
+    private warned;
+    constructor(scope: AuditScope, options?: AuditTrailOptions);
+    /**
+     * The recorder for one door. Call it where the door is, once; the origin is fixed from then on.
+     * One production caller: `mcp/index.ts:254`, with `'mcp'`. Every other origin is test-only (#364).
+     */
+    channel(origin: AuditOrigin): AuditChannel;
+    /**
+     * Every entry of THIS project, oldest first. A scoped read (D-06 § 10.4 rule 2): it opens only
+     * this project's file and additionally drops any line naming another project, so a reader bound
+     * to B learns nothing about A — not its entries, and not how many there are (N-01).
+     */
+    read(): AuditReadResult;
+    /** @internal — build, check and append one entry. Never throws. */
+    write(origin: AuditOrigin, op: AuditedOperation, settlement: AuditSettlement): AuditEntry | null;
+    private build;
+    private knownSecrets;
+    private warnOnce;
+}
+/** One door's recorder. The origin is fixed at construction and no operation can change it. */
+export declare class AuditChannel {
+    private readonly trail;
+    readonly origin: AuditOrigin;
+    constructor(trail: AuditTrail, origin: AuditOrigin);
+    /** Record an operation that has already settled. */
+    record(op: AuditedOperation, settlement: AuditSettlement): AuditEntry | null;
+    /** Record an operation that settled through an HTTP route, by its status. */
+    recordStatus(op: AuditedOperation, status: number): AuditEntry | null;
+    /**
+     * Run `effect` and record how it settled. An `AuditRejection` means "refused before any effect"
+     * and records `rejected`; any other throw may have come after the effect began, so it records
+     * `unverified`. Either error is rethrown unchanged: auditing never changes the operation's own
+     * answer. `resourceOf` names a resource the effect created.
+     */
+    run<T>(op: AuditedOperation, effect: () => T | Promise<T>, resourceOf?: (value: T) => AuditResource | undefined): Promise<T>;
+}
+/**
+ * D-06 § 5.4's canonical form: object keys sorted by code unit at every level, arrays in order,
+ * `undefined` keys dropped, and a byte blob replaced by `{ sha256, bytes }` so the digest covers
+ * bytes, never a path. A non-finite number is refused (zod refuses it upstream).
+ */
+export declare function canonicalJson(value: unknown): string;
+/** SHA-256, lowercase hex, of `canonicalJson(payload)`. */
+export declare function payloadDigest(payload: unknown): string;

package/dist/mcp/audit-trail.js

@@ -0,0 +1,306 @@
+import { createHash } from 'node:crypto';
+import { appendFileSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { auditEntrySchema, } from '../contract/index.js';
+import { collectSecretValues, redactSecrets } from '../core/secret-redaction.js';
+import { PROJECT_ID_RE } from '../workspace/config.js';
+/**
+ * The audit trail (#102) — D-06 § 10, requirement N-04. Built for MCP and cockpit operations;
+ * writing MCP operations today, and only those (see THE SHARED PATH below).
+ *
+ * WHAT. One append-only NDJSON file per project, `<project>/.local/xezar/mcp-audit.ndjson`, one
+ * `AuditEntry` (packages/contract/src/mcp-audit.ts) per settled operation: action, time, project,
+ * resource, outcome and ORIGIN, plus D-06's join fields. It is written, never required: a missing
+ * file reads as an empty trail, and deleting it discards history and nothing else. It lives under
+ * `.local/`, which `ensureProjectDataIgnored` already blanket-ignores (D-06 § 13.2).
+ *
+ * THE SHARED PATH, AND THE ONE DOOR THAT USES IT. A door stamps its origin through an
+ * `AuditChannel`: the entry point that owns the door asks `trail.channel(origin)` ONCE and hands
+ * operations to it. The origin is therefore derived from which door the call came through — an
+ * operation object has no origin and no project field, and a stray `origin` or `projectId` key on
+ * one is ignored (D-06 § 10.4 rule 1). That is also the marker #106 reads to tell the leader's own
+ * echoes from new events.
+ *
+ * **Exactly one door does this today, and it is the MCP one:** `mcp/index.ts:254` builds
+ * `.channel('mcp')`, and it is the only non-test construction of this class in `packages/`
+ * (grepped for the type and for `.channel(` at `87d9f0d`, 2026-09-12). The cockpit's HTTP routes,
+ * the automation scheduler and headless `xezar run` are the doors the design expects and they
+ * record NOTHING — so `ui` is written only by tests (`audit-trail.test.ts`, `echo-guard.test.ts`,
+ * `test/helpers/ab-fixture.ts`), and `automation` and `cli` are written nowhere at all. That is decided for 0.14.0, not an oversight (#266, D-06 § 10.6);
+ * wiring the other three is #364. `channel()` takes any `AuditOrigin` because those doors are the
+ * point, but do not read this comment as a description of four live writers.
+ *
+ * MUST vs SHOULD (D-06 § 10.2, N-04 "should"):
+ *   - MUST: the project id comes from the trusted scope, the origin from the door, and no secret,
+ *     free text, path or foreign identifier is written (§ 10.3, F-15, F-12, N-01).
+ *   - MUST: the record grants nothing (§ 10.4 rule 3). Nothing here answers "may X do Y", and no
+ *     method consults the trail before an effect — a caller's own permission check runs first and
+ *     a refusal is simply recorded as `rejected`. An `origin: 'ui'` entry never widens MCP.
+ *   - SHOULD: the entry itself. Recording is best-effort by design: a write that fails is warned
+ *     about once and never fails the operation, which is the opposite of the receipt journal's
+ *     refuse-before-effect rule (D-06 § 7.5) and deliberately so — idempotency is mandatory, audit
+ *     is not.
+ *
+ * NO SECRETS, TWICE. First by construction: the schema has no free-text field, and payloads enter
+ * only as a SHA-256 digest (D-06 § 5.4). Second by value: every client-influenced identifier
+ * (`resource.id`, the operation id, the version token) is checked against the host's secret env
+ * values, the caller's known secrets (the MCP connection token, D-04) and the well-known token
+ * shapes, and a field that matches is DROPPED rather than masked. The check deliberately ignores
+ * `XEZ_REDACT_SECRETS=0`: that opt-out exists because masking can corrupt a transcript, and
+ * dropping an audit field corrupts nothing.
+ *
+ * RETENTION IS OPEN. N-04 keeps it open, D-06 § 10.5 does not close it, and D-09 B-23 fixes only
+ * the mechanism (count-based, never evicting an entry whose run is still kept) with the count
+ * UNRESOLVED (U-2). So nothing here evicts, and no period or count is asserted.
+ */
+/** File name under the project's data dir (`.local/xezar/`). D-06 § 10.5 puts it beside the receipts. */
+export const AUDIT_TRAIL_FILE = 'mcp-audit.ndjson';
+export const auditTrailPath = (dataDir) => join(dataDir, AUDIT_TRAIL_FILE);
+/** The same floor `secret-redaction.ts` applies to env values: below it a value is a common word. */
+const MIN_KNOWN_SECRET_LEN = 12;
+/** Thrown by an effect to refuse BEFORE anything happened: validation, permission, stale version. */
+export class AuditRejection extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = 'AuditRejection';
+    }
+}
+/**
+ * The outcome an HTTP status stands for, for callers that settle through a route (the cockpit's
+ * handlers, and the MCP adapter, which dispatches into the same routes). The routes validate as
+ * middleware and answer 4xx before any effect, so a 4xx is a refusal; a 5xx may have come after
+ * the effect started, so it is `unverified`, never `rejected`.
+ */
+export function settlementForStatus(status) {
+    if (status >= 200 && status < 300)
+        return { outcome: 'ok' };
+    if (status >= 400 && status < 500)
+        return { outcome: 'rejected', errorCode: `http_${status}` };
+    return { outcome: 'unverified', errorCode: `http_${status}` };
+}
+export class AuditTrail {
+    scope;
+    now;
+    callerSecrets;
+    warn;
+    warned = false;
+    constructor(scope, options = {}) {
+        if (scope.projectId === 'default' || !PROJECT_ID_RE.test(scope.projectId)) {
+            throw new Error(`audit trail needs a resolved project id, got ${JSON.stringify(scope.projectId)}`);
+        }
+        this.scope = { projectId: scope.projectId, dataDir: scope.dataDir };
+        this.now = options.now ?? (() => new Date());
+        this.callerSecrets = options.secretValues ?? (() => []);
+        this.warn = options.warn ?? ((message) => console.warn(message));
+    }
+    /**
+     * The recorder for one door. Call it where the door is, once; the origin is fixed from then on.
+     * One production caller: `mcp/index.ts:254`, with `'mcp'`. Every other origin is test-only (#364).
+     */
+    channel(origin) {
+        return new AuditChannel(this, origin);
+    }
+    /**
+     * Every entry of THIS project, oldest first. A scoped read (D-06 § 10.4 rule 2): it opens only
+     * this project's file and additionally drops any line naming another project, so a reader bound
+     * to B learns nothing about A — not its entries, and not how many there are (N-01).
+     */
+    read() {
+        let raw;
+        try {
+            raw = readFileSync(auditTrailPath(this.scope.dataDir), 'utf8');
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT')
+                this.warnOnce('read', err);
+            return { entries: [], quarantined: 0 };
+        }
+        const entries = [];
+        let quarantined = 0;
+        for (const line of raw.split('\n')) {
+            if (line.trim() === '')
+                continue;
+            let json;
+            try {
+                json = JSON.parse(line);
+            }
+            catch {
+                quarantined += 1;
+                continue;
+            }
+            const parsed = auditEntrySchema.safeParse(json);
+            if (!parsed.success) {
+                quarantined += 1;
+                continue;
+            }
+            if (parsed.data.projectId !== this.scope.projectId)
+                continue;
+            entries.push(parsed.data);
+        }
+        return { entries, quarantined };
+    }
+    /** @internal — build, check and append one entry. Never throws. */
+    write(origin, op, settlement) {
+        try {
+            const entry = this.build(origin, op, settlement);
+            if (!entry)
+                return null;
+            appendFileSync(auditTrailPath(this.scope.dataDir), `${JSON.stringify(entry)}\n`, { mode: 0o600 });
+            return entry;
+        }
+        catch (err) {
+            this.warnOnce('write', err);
+            return null;
+        }
+    }
+    build(origin, op, settlement) {
+        const secrets = this.knownSecrets();
+        const clean = (value) => value !== undefined && redactSecrets(value, secrets) === value ? value : undefined;
+        const field = (key, value) => {
+            const parsed = auditEntrySchema.shape[key].safeParse(value);
+            return parsed.success ? parsed.data : undefined;
+        };
+        const resourceOf = (resource) => {
+            if (!resource || clean(resource.id) === undefined || clean(resource.kind) === undefined)
+                return undefined;
+            return field('resource', { kind: resource.kind, id: resource.id });
+        };
+        const candidate = {
+            v: 1,
+            ts: this.now().toISOString(),
+            projectId: this.scope.projectId,
+            action: op.action,
+            outcome: settlement.outcome,
+            origin,
+        };
+        const optional = {
+            resource: resourceOf(settlement.resource) ?? resourceOf(op.resource),
+            ownerGeneration: origin === 'mcp' ? field('ownerGeneration', fencingTokenMs(op.ownerGeneration)) : undefined,
+            operationKey: origin === 'mcp' && op.operationId !== undefined
+                ? field('operationKey', clean(`${this.scope.projectId}/${op.operationId}`))
+                : undefined,
+            versionToken: field('versionToken', clean(op.expectedVersion)),
+            payloadDigest: op.payload === undefined ? undefined : field('payloadDigest', safeDigest(op.payload)),
+            errorCode: settlement.outcome === 'ok' ? undefined : field('errorCode', clean(settlement.errorCode)),
+        };
+        // Spread only what is present: an `undefined` key would be typed as present and dropped by
+        // JSON.stringify anyway, and the read path must see exactly what was written.
+        for (const [key, value] of Object.entries(optional))
+            if (value !== undefined)
+                candidate[key] = value;
+        const parsed = auditEntrySchema.safeParse(candidate);
+        if (!parsed.success || clean(parsed.data.action) === undefined) {
+            this.warnOnce('write', new Error(`not an auditable operation: ${parsed.error?.issues[0]?.message ?? 'secret-shaped action'}`));
+            return null;
+        }
+        return parsed.data;
+    }
+    knownSecrets() {
+        const values = new Set(collectSecretValues());
+        for (const value of this.callerSecrets())
+            if (value.length >= MIN_KNOWN_SECRET_LEN)
+                values.add(value);
+        return [...values].sort((a, b) => b.length - a.length);
+    }
+    warnOnce(what, err) {
+        if (this.warned)
+            return;
+        this.warned = true;
+        // The code only — an error message can carry a path, and a path is not for logs either.
+        const code = err?.code ?? err?.name ?? 'error';
+        this.warn(`xezar: audit trail ${what} failed (${code}); operations continue unaudited`);
+    }
+}
+/** One door's recorder. The origin is fixed at construction and no operation can change it. */
+export class AuditChannel {
+    trail;
+    origin;
+    constructor(trail, origin) {
+        this.trail = trail;
+        this.origin = origin;
+    }
+    /** Record an operation that has already settled. */
+    record(op, settlement) {
+        return this.trail.write(this.origin, op, settlement);
+    }
+    /** Record an operation that settled through an HTTP route, by its status. */
+    recordStatus(op, status) {
+        return this.record(op, settlementForStatus(status));
+    }
+    /**
+     * Run `effect` and record how it settled. An `AuditRejection` means "refused before any effect"
+     * and records `rejected`; any other throw may have come after the effect began, so it records
+     * `unverified`. Either error is rethrown unchanged: auditing never changes the operation's own
+     * answer. `resourceOf` names a resource the effect created.
+     */
+    async run(op, effect, resourceOf) {
+        let value;
+        try {
+            value = await effect();
+        }
+        catch (err) {
+            this.record(op, err instanceof AuditRejection
+                ? { outcome: 'rejected', errorCode: err.code }
+                : { outcome: 'unverified', errorCode: 'effect_failed' });
+            throw err;
+        }
+        this.record(op, { outcome: 'ok', resource: resourceOf?.(value) });
+        return value;
+    }
+}
+/**
+ * D-06 § 5.4's canonical form: object keys sorted by code unit at every level, arrays in order,
+ * `undefined` keys dropped, and a byte blob replaced by `{ sha256, bytes }` so the digest covers
+ * bytes, never a path. A non-finite number is refused (zod refuses it upstream).
+ */
+export function canonicalJson(value) {
+    return JSON.stringify(canonicalize(value));
+}
+/** SHA-256, lowercase hex, of `canonicalJson(payload)`. */
+export function payloadDigest(payload) {
+    return createHash('sha256').update(canonicalJson(payload)).digest('hex');
+}
+/**
+ * The wall-clock prefix of a D-02.3 fencing token, `<ms>-<UUIDv4>` — the number D-06 § 10.2 keeps.
+ * D-02 names human-readable audit as the prefix's one consumer; the random half is what the fence
+ * compares, so it is dropped here. Anything not shaped like a token yields nothing.
+ */
+function fencingTokenMs(token) {
+    const match = token === undefined ? null : /^(\d{1,15})-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.exec(token);
+    return match ? Number(match[1]) : undefined;
+}
+function safeDigest(payload) {
+    try {
+        return payloadDigest(payload);
+    }
+    catch {
+        return undefined;
+    }
+}
+function canonicalize(value) {
+    if (value instanceof Uint8Array) {
+        return { bytes: value.byteLength, sha256: createHash('sha256').update(value).digest('hex') };
+    }
+    if (typeof value === 'number' && !Number.isFinite(value))
+        throw new Error('non-finite number in payload');
+    if (typeof value === 'bigint' || typeof value === 'function' || typeof value === 'symbol') {
+        throw new Error(`${typeof value} in payload`);
+    }
+    if (value === null || typeof value !== 'object')
+        return value;
+    const withJson = value;
+    if (typeof withJson.toJSON === 'function')
+        return canonicalize(withJson.toJSON());
+    if (Array.isArray(value))
+        return value.map((item) => (item === undefined ? null : canonicalize(item)));
+    const out = {};
+    for (const key of Object.keys(value).sort()) {
+        const item = value[key];
+        if (item !== undefined)
+            out[key] = canonicalize(item);
+    }
+    return out;
+}
+//# sourceMappingURL=audit-trail.js.map

package/dist/mcp/audit-trail.js.map

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

package/dist/mcp/bridge.d.ts

@@ -0,0 +1,81 @@
+import { type McpTool } from './tool.ts';
+/**
+ * `xez mcp`: the stdio MCP endpoint a coding agent spawns (D-01 § 1.1, § 1.7). A
+ * transport adapter with two legs — MCP on stdin/stdout facing the client, the
+ * project's Unix socket facing the running service — and nothing else: no store,
+ * no queue, no server, no port.
+ *
+ * ## One connection, one session (#302, D-02)
+ *
+ * The bridge keeps ONE connection to the service for its whole life and opens its MCP session on
+ * it when the client sends `initialize` — that is where D-02.6 puts acquisition. The service then
+ * sees the session open and, when this process exits or its client goes away, sees it close: the
+ * owner went away, observably, in milliseconds. That is what makes exclusive ownership enforceable;
+ * the one-connection-per-call bridge this replaces gave the service no session to observe.
+ *
+ * What one-connection-per-call was load-bearing FOR, and how each guarantee is kept:
+ *
+ * - **N-07 / D-01 § 5 — xezar not running.** Every call re-resolved the target and connected, so a
+ *   cockpit started later was picked up on the next call with no client restart and no reconnect
+ *   timer. Kept: `initialize` still succeeds with no service, and every call made without a live
+ *   session tries to open one — the next call is still the next attempt, with no timer.
+ * - **Cockpit restart.** A fresh connection per call simply reached the new service. Now the old
+ *   session ends with the old service (D-02 § 5): the FIRST call that reaches the new service is
+ *   answered session-expired, so a write made under the old session is fenced rather than silently
+ *   replayed, and the bridge has already opened a new session for the next call — no model turn and
+ *   no human step.
+ * - **Failure containment.** A hung or garbled answer spoiled one call's connection and nothing
+ *   else. Now answers are matched by request id on the shared connection: a call that times out
+ *   is answered as a timeout and its late answer dropped, and a garbled frame fails the calls in
+ *   flight — neither closes the session, so neither costs the project.
+ * - **A client that dies mid-call.** Its connections were destroyed and the service carried on
+ *   with the operation. Unchanged: the service still runs every call it accepted to completion; the
+ *   close now also frees the project, and still cancels no task (N-05).
+ * - **Two clients at once.** Both were served — the defect. Now the second is refused.
+ *
+ * Refusals are D-02 § 4's JSON-RPC errors, passed through as the service built them:
+ * `initialize` while another session owns the project answers project-occupied (`-32080`); a call
+ * from a session that does not own the project — refused, lost with a restart, or fenced — answers
+ * session-expired (`-32081`), and the next call is made on a new session. Nothing here lets one
+ * session end another (F-18).
+ */
+export type ServiceTarget = {
+    readonly kind: 'socket';
+    readonly path: string;
+    readonly project: {
+        readonly id: string;
+        readonly name: string;
+    };
+} | {
+    readonly kind: 'unavailable';
+    readonly status: 'not-registered' | 'unsupported';
+    readonly message: string;
+};
+export interface BridgeOptions {
+    readonly input: NodeJS.ReadableStream;
+    readonly output: NodeJS.WritableStream;
+    readonly version: string;
+    /** The registry (`./tools/index.ts`). Listed here, executed in the service. */
+    readonly tools: readonly McpTool[];
+    /** Re-resolved whenever a session is opened, so registering or starting the project later just works. */
+    resolveTarget(): Promise<ServiceTarget>;
+    readonly requestTimeoutMs?: number;
+}
+/** Built into the bridge rather than the registry: it is how a client learns the service is down. */
+export declare const HEALTH_TOOL: {
+    readonly name: 'health';
+    readonly title: 'xezar health';
+    readonly description: 'Report whether the xezar cockpit is running for the project this session was started in, and which project that is.';
+    readonly inputSchema: {
+        readonly type: 'object';
+        readonly properties: {};
+        readonly additionalProperties: false;
+    };
+    readonly annotations: {
+        readonly readOnlyHint: true;
+        readonly idempotentHint: true;
+        readonly openWorldHint: false;
+    };
+};
+/** Serve MCP until `input` ends. Resolves then; the session closes and in-flight answers are dropped. */
+export declare function runBridge(opts: BridgeOptions): Promise<void>;