@qodeca/xezar 0.13.1 → 0.14.0

package/dist/mcp/session-binding.js

@@ -0,0 +1,163 @@
+import { realpathSync, statSync } from 'node:fs';
+import { runIdParamSchema } from '../contract/index.js';
+import { ProjectContextError, } from '../server/project-context.js';
+import { PROJECT_ID_RE } from '../workspace/config.js';
+import { RESERVED_PROJECT_IDS } from '../workspace/projects.js';
+/** Fixed, identifier-free sentences — the rejection text is part of the surface (N-01). */
+const MESSAGES = {
+    'unknown-project': 'this MCP session is not bound to a registered xezar project; reconnect from the project folder',
+    'missing-root': 'the project folder this MCP session is bound to is missing; restore it or reconnect from the project folder',
+    unavailable: 'the project this MCP session is bound to cannot be opened right now; the cockpit log has the details',
+    'not-in-project': 'no such resource in this project',
+};
+/** The one error this module throws. Carries no client-supplied value. */
+export class McpScopeError extends Error {
+    reason;
+    projectId;
+    constructor(reason, 
+    /** The BOUND project's id — never a foreign or client-supplied one. */
+    projectId, 
+    /** The underlying failure, for the service's own log only — never sent to a client. */
+    cause) {
+        super(MESSAGES[reason], cause === undefined ? undefined : { cause });
+        this.reason = reason;
+        this.projectId = projectId;
+        this.name = 'McpScopeError';
+    }
+}
+/**
+ * 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 class McpSessionBinding {
+    // Runtime-private (`#`), not TypeScript `readonly`: a `readonly` property is still
+    // writable at runtime, and the binding must not be re-pointable by any code holding it.
+    #projectId;
+    #contexts;
+    #root;
+    constructor(projectId, contexts, root) {
+        this.#projectId = projectId;
+        this.#contexts = contexts;
+        this.#root = root;
+    }
+    /** The bound registry id. Fixed for the life of the session; there is no setter. */
+    get projectId() {
+        return this.#projectId;
+    }
+    /**
+     * 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 async bind(contexts, trustedProjectId) {
+        if (typeof trustedProjectId !== 'string' ||
+            RESERVED_PROJECT_IDS.has(trustedProjectId) ||
+            !PROJECT_ID_RE.test(trustedProjectId)) {
+            // Not echoed: a malformed binding id is a caller bug, and the message stays fixed.
+            throw new McpScopeError('unknown-project', '');
+        }
+        const ctx = await resolveContext(contexts, trustedProjectId);
+        if (ctx.id !== trustedProjectId)
+            throw new McpScopeError('unknown-project', trustedProjectId);
+        const root = rootIdentity(ctx.root);
+        // The registry stores realpath'd roots. A root that no longer IS its own realpath
+        // was swapped for a symlink (or moved) after registration; pinning what it points
+        // at now would bind the session to whatever the link names — possibly another
+        // project's folder. Refuse instead of pinning.
+        if (!root || root.realpath !== ctx.root)
+            throw new McpScopeError('missing-root', trustedProjectId);
+        return new McpSessionBinding(trustedProjectId, contexts, root);
+    }
+    /**
+     * 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.
+     */
+    async project() {
+        const ctx = await resolveContext(this.#contexts, this.#projectId);
+        // Defence in depth: the map is keyed by id, so this holds today. A context whose
+        // id is not the bound id must never be handed to an operation, whatever changes.
+        if (ctx.id !== this.#projectId)
+            throw new McpScopeError('unknown-project', this.#projectId);
+        const current = rootIdentity(ctx.root);
+        if (!current ||
+            current.realpath !== this.#root.realpath ||
+            current.dev !== this.#root.dev ||
+            current.ino !== this.#root.ino) {
+            throw new McpScopeError('missing-root', this.#projectId);
+        }
+        return ctx;
+    }
+    /**
+     * 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.
+     */
+    async run(runId) {
+        const ctx = await this.project();
+        return lookupRun(ctx, runId, this.#projectId);
+    }
+    /**
+     * 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.
+     */
+    async withRun(runId, operation) {
+        const ctx = await this.project();
+        const run = lookupRun(ctx, runId, this.#projectId);
+        return operation(run, ctx);
+    }
+}
+/** Bind a session — see `McpSessionBinding.bind`. */
+export function bindMcpSession(contexts, trustedProjectId) {
+    return McpSessionBinding.bind(contexts, trustedProjectId);
+}
+/** Resolve the bound id through the context map, translating its failures. Only ever
+ *  called with the bound id — the one place a `ProjectContexts` lookup happens. */
+async function resolveContext(contexts, projectId) {
+    try {
+        return await contexts.context(projectId);
+    }
+    catch (err) {
+        if (err instanceof ProjectContextError)
+            throw new McpScopeError(err.reason, projectId, err);
+        // Anything else — the writer error, or a raw fs error from building the context —
+        // can carry a data directory, a path or a pid in its message; none may reach a
+        // client. The original stays on `cause` for the service's own log.
+        throw new McpScopeError('unavailable', projectId, err);
+    }
+}
+function lookupRun(ctx, runId, projectId) {
+    // Dot segments pass the character class but are never run ids; refuse them here so
+    // no caller can build a path or URL out of one.
+    if (typeof runId !== 'string' || runId === '.' || runId === '..' || !runIdParamSchema.safeParse({ id: runId }).success) {
+        throw new McpScopeError('not-in-project', projectId);
+    }
+    const run = ctx.store.getRun(runId);
+    if (!run)
+        throw new McpScopeError('not-in-project', projectId);
+    return run;
+}
+/** Realpath + device/inode of a directory, or null when it is gone or not a directory. */
+function rootIdentity(root) {
+    try {
+        const realpath = realpathSync(root);
+        const stats = statSync(realpath);
+        if (!stats.isDirectory())
+            return null;
+        return { realpath, dev: stats.dev, ino: stats.ino };
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=session-binding.js.map

package/dist/mcp/session-binding.js.map

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

package/dist/mcp/stale-write.d.ts

@@ -0,0 +1,145 @@
+import { type ExecutionFailed, type McpVersionedResourceRef, type StaleVersionRejection, type VersionedMutationDone } from '../contract/index.js';
+import type { RunRecord, RunStore } from '../runs/store.ts';
+/**
+ * Stale-write rejection for leader mutations (#100) — the mechanism D-06 chose for N-03
+ * (`docs/features/mcp-server/mcp-d06-versioning-idempotency-audit-decision.md` § 4). N-03 is an
+ * agreed outcome and nothing here makes it optional: a leader mutation based on state a human has
+ * changed since is REFUSED, before any effect. It is never merged, never retried with the fresh
+ * token, and never offered to anyone for approval (§ 4.4 rule 3). There is no switch that turns
+ * the check off, and there must never be one.
+ *
+ * Two pieces, deliberately tool-agnostic — this is infrastructure a tool calls, not a tool:
+ *
+ *  - `versionToken` computes `rev1:<kind>:<id>:<seq>:<digest12>` (§ 4.2) from a resource's
+ *    DECISION PROJECTION (§ 4.3): the fields the server reads to judge a mutation plus the fields
+ *    it writes, and nothing that moves on its own. A token that included a token counter would go
+ *    stale within seconds of an agent emitting anything, and a check that always fails is an outage
+ *    people learn to switch off.
+ *  - `guardedMutation` is the compare-and-swap (§ 4.5). It reads the current token, compares, and
+ *    applies — all in ONE synchronous stretch. Node runs one stretch of synchronous code at a time,
+ *    and `ownProjectData` (`runs/project-writer.ts`) keeps a project's state to one writing process,
+ *    so no other write can land between the check and the effect. That is also why `apply` must
+ *    not be async: an `await` inside it would open exactly the gap the check exists to close.
+ *
+ * N-02: the effect `apply` performs is the SAME store call the cockpit's route makes — this module
+ * wraps the shared service, it never writes JSON or NDJSON itself. The cockpit keeps calling those
+ * methods exactly as it does today — requiring a token there would break every existing client —
+ * and the leader's write reaches the very same methods, behind this check.
+ *
+ * U-M05: the result tells the three endings apart — `done`, `conflict` (rejected, NOTHING applied)
+ * and `failed` (the effect ran and failed, so the state may have moved). See
+ * `packages/contract/src/mcp-versioning.ts` for the shapes.
+ */
+/** One resource, as the check sees it. Build it from live state on every call — never cache one. */
+export interface VersionedSnapshot {
+    readonly ref: McpVersionedResourceRef;
+    /**
+     * For a run-scoped resource, its highest event `seq`; absent for a resource with no event stream
+     * (a config file, an automation). This half catches A→B→A — a human who changes something and
+     * changes it back leaves the projection byte-identical, but not the event counter, because `seq`
+     * is monotonic and never reused, even across a restart (`RunStore.rehydrateSeq`).
+     */
+    readonly seq?: number;
+    /** The decision projection. Canonicalized and digested; its content never leaves this module. */
+    readonly projection: unknown;
+}
+/**
+ * JSON with object keys sorted by UTF-16 code unit at every level, arrays kept in order, no
+ * whitespace, and `undefined`-valued keys dropped — D-06 § 5.4 step 4, so a token does not depend
+ * on the order in which a record's keys happened to be assigned.
+ *
+ * Serialized by hand rather than by rebuilding an object for `JSON.stringify`: an engine iterates
+ * integer-like keys (`"10"`, `"9"`) numerically whatever order they were inserted in, which is not
+ * code-unit order.
+ */
+export declare function canonicalJson(value: unknown): string;
+/** The token a read hands out and a mutation must echo back. Opaque to every client. */
+export declare function versionToken(snapshot: VersionedSnapshot): string;
+/** What `guardedMutation` answers when the change went through: the contract shape plus the value
+ *  `apply` returned, for the calling tool to project onto its own result. */
+export type GuardedMutationDone<T> = VersionedMutationDone & {
+    readonly value: T;
+};
+export type GuardedMutationResult<T> = GuardedMutationDone<T> | StaleVersionRejection | ExecutionFailed;
+/**
+ * `apply` has to finish inside the critical section, so an async one is a compile error — this
+ * rest parameter demands an impossible extra argument when `apply` returns a promise — and, for a
+ * caller that got past the types, a `failed` result at run time.
+ */
+type SyncOnly<T> = [T] extends [never] ? [] : [T] extends [PromiseLike<unknown>] ? [asyncApplyIsNotAllowed: never] : [];
+export interface GuardedMutationInput<T> {
+    readonly resource: McpVersionedResourceRef;
+    /**
+     * The token the leader read. A missing one is REFUSED, never waved through: "no token" and "token
+     * matches" must not share a branch (D-06 § 4.4 rule 4). The tool schema already requires it; this
+     * is the same guarantee for a caller that bypassed the schema.
+     */
+    readonly expectedVersion: string | undefined;
+    /** Reads the resource as it is NOW; `undefined` when it no longer exists. */
+    readonly read: () => VersionedSnapshot | undefined;
+    /** The effect: the shared store call. Synchronous — see `SyncOnly`. */
+    readonly apply: () => T;
+}
+/**
+ * Check the leader's token against the resource's current one and apply the effect only on a match.
+ *
+ * Never throws for a stale token or a failed effect — both are ANSWERS the leader must reason
+ * about, which is why D-05 returns them as ordinary results rather than tool errors.
+ */
+export declare function guardedMutation<T>(input: GuardedMutationInput<T>, ..._sync: SyncOnly<T>): GuardedMutationResult<T>;
+export declare const RUN_RESOURCE_KIND = "run";
+/**
+ * A run's decision projection (D-06 § 4.3).
+ *
+ * D-06 proposed `status`, `archived`, `pinned`, `title`, `titleOrigin`, `autoResumeAt`,
+ * `queuedMessages[].id`, `steps[].id`/`steps[].status`, `branch` and `workflow`, and left the list
+ * to be reviewed against `runRecordSchema`. Reviewed against it, two additions follow from the
+ * rule itself — every field a leader mutation of a run WRITES:
+ *
+ *  - `task`: a queued run's brief stays editable until the scheduler picks it up, and a human
+ *    editing it is the "edits its brief" case § 4.1 names;
+ *  - `queuedMessages[].text`, not only the id: a queued follow-up is editable in the same way.
+ *
+ * Left out on purpose: telemetry (`tokensUsed`, `inputTokens`, `outputTokens`, `costUsd`,
+ * `peakRssBytes`, `peakProcCount`, `diffStat`, the per-step counters), presentation (`seenAt`, and
+ * the `archivedAt`/`pinnedAt` stamps whose flags ARE covered), and everything derived by the server
+ * for display (`titleSummary`, the referenced PR/issue tiers).
+ */
+export declare function runDecisionProjection(run: RunRecord): unknown;
+/** A run as the check sees it right now, or `undefined` when there is no such run. */
+export declare function runVersionSnapshot(store: RunStore, runId: string): VersionedSnapshot | undefined;
+/** The `version` a read of this run hands the leader, or `undefined` when there is no such run. */
+export declare function runVersion(store: RunStore, runId: string): string | undefined;
+/**
+ * The route half of the check (#250): the rejection a run-mutating route answers with, or
+ * `undefined` when its effect may go ahead.
+ *
+ * WHY THE ROUTE, NOT THE TOOL. An MCP tool reaches the services through in-process HTTP dispatch
+ * (N-02, `service-adapter.ts`), which is async, so a tool cannot hold `guardedMutation`'s
+ * synchronous critical section around the store call — only the route handler can. So the route
+ * accepts an OPTIONAL `expectedVersion` and calls this RIGHT BEFORE its effect, with nothing but
+ * synchronous code between the two: the check and the store call then run in one stretch, exactly
+ * as `guardedMutation` would run them (§ 4.5). A handler must never put an `await` between this
+ * call and its effect; each call site says so.
+ *
+ * ABSENT MEANS "NOT ASKED", ON PURPOSE. `undefined` is the cockpit, which has never sent a token and
+ * keeps its behaviour byte-for-byte. The leader can never reach that branch: every MCP tool that
+ * mutates a run REQUIRES `expectedVersion` in its own schema (D-06 § 4.4 rule 4), and the tool
+ * tests pin that each action sends it. Present-but-wrong — empty, foreign, unknown tag, another
+ * run's — is always a rejection, never a pass.
+ *
+ * AN ASYNC EFFECT (a worktree removal, a push, `gh pr create`) cannot sit inside a synchronous
+ * stretch at all. Those routes call this right before the effect STARTS, so a stale decision never
+ * begins; a change that lands while the effect is already running is outside what a version check
+ * can see, and each such effect keeps its own guards (`isActive`, the worktree checks).
+ */
+export declare function staleRunWrite(store: RunStore, runId: string, expectedVersion: string | undefined): StaleVersionRejection | undefined;
+/** The rejection a route answered with, when the body is one — how a tool tells a stale-version
+ *  409 from every other 409 (`run already started`, `session closed`, …). */
+export declare function staleRejectionIn(body: unknown): StaleVersionRejection | undefined;
+/**
+ * `guardedMutation` for one run: `apply` receives the CURRENT record and performs the shared store
+ * call on it (`setPinned`, `updateRun`, …). It is never called when the token is stale.
+ */
+export declare function guardedRunMutation<T>(store: RunStore, runId: string, expectedVersion: string | undefined, apply: (run: RunRecord) => T, ..._sync: SyncOnly<T>): GuardedMutationResult<T>;
+export {};

package/dist/mcp/stale-write.js

@@ -0,0 +1,219 @@
+import { createHash } from 'node:crypto';
+import { MCP_EXECUTION_FAILED_GUIDANCE, MCP_STALE_VERSION_GUIDANCE, MCP_VERSION_TOKEN_TAG, staleVersionRejectionSchema, } from '../contract/index.js';
+/**
+ * JSON with object keys sorted by UTF-16 code unit at every level, arrays kept in order, no
+ * whitespace, and `undefined`-valued keys dropped — D-06 § 5.4 step 4, so a token does not depend
+ * on the order in which a record's keys happened to be assigned.
+ *
+ * Serialized by hand rather than by rebuilding an object for `JSON.stringify`: an engine iterates
+ * integer-like keys (`"10"`, `"9"`) numerically whatever order they were inserted in, which is not
+ * code-unit order.
+ */
+export function canonicalJson(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => (item === undefined ? 'null' : canonicalJson(item))).join(',')}]`;
+    }
+    if (value !== null && typeof value === 'object') {
+        const parts = [];
+        for (const key of Object.keys(value).sort()) {
+            const item = value[key];
+            if (item !== undefined)
+                parts.push(`${JSON.stringify(key)}:${canonicalJson(item)}`);
+        }
+        return `{${parts.join(',')}}`;
+    }
+    return JSON.stringify(value) ?? 'null';
+}
+/** The token a read hands out and a mutation must echo back. Opaque to every client. */
+export function versionToken(snapshot) {
+    const digest = createHash('sha256').update(canonicalJson(snapshot.projection)).digest('hex').slice(0, 12);
+    const seq = snapshot.seq === undefined ? '-' : String(snapshot.seq);
+    return `${MCP_VERSION_TOKEN_TAG}:${snapshot.ref.kind}:${snapshot.ref.id}:${seq}:${digest}`;
+}
+/**
+ * Check the leader's token against the resource's current one and apply the effect only on a match.
+ *
+ * Never throws for a stale token or a failed effect — both are ANSWERS the leader must reason
+ * about, which is why D-05 returns them as ordinary results rather than tool errors.
+ */
+export function guardedMutation(input, ..._sync) {
+    const before = input.read();
+    const currentVersion = before ? versionToken(before) : undefined;
+    // Verbatim comparison is the whole rule, and it covers D-06 § 4.4 rule 5 without parsing: an
+    // unparseable, foreign or unknown-tag token can never equal a token this server just minted.
+    if (!input.expectedVersion || currentVersion === undefined || input.expectedVersion !== currentVersion) {
+        return staleVersionRejection(input.resource, currentVersion);
+    }
+    let value;
+    try {
+        value = input.apply();
+    }
+    catch (error) {
+        return executionFailed(input.resource, error);
+    }
+    if (isThenable(value)) {
+        // The effect escaped the critical section. Swallow a later rejection so it cannot crash the
+        // process as an unhandled one, and report what is actually known: it ran, and it is not done.
+        value.then(undefined, () => undefined);
+        return executionFailed(input.resource, new Error('apply returned a promise; a guarded mutation must be synchronous'));
+    }
+    const after = input.read();
+    return {
+        status: 'done',
+        resource: input.resource,
+        ...(after ? { version: versionToken(after) } : {}),
+        value,
+    };
+}
+function staleVersionRejection(resource, currentVersion) {
+    return {
+        status: 'conflict',
+        applied: false,
+        error: 'stale_version',
+        resource,
+        // Spread, not `currentVersion: undefined` — a key that is always present in the type but
+        // dropped by `JSON.stringify` is exactly the drift the contract-parity rule warns about.
+        ...(currentVersion === undefined ? {} : { currentVersion }),
+        changedSince: true,
+        guidance: MCP_STALE_VERSION_GUIDANCE,
+    };
+}
+function executionFailed(resource, error) {
+    // The message stays in the cockpit's own log: it can quote a path or a command line, and nothing
+    // secret may reach a tool response (F-15).
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn(`[xez] MCP mutation of ${resource.kind} ${resource.id} failed after execution: ${message}`);
+    return {
+        status: 'failed',
+        executed: true,
+        error: 'execution_failed',
+        resource,
+        guidance: MCP_EXECUTION_FAILED_GUIDANCE,
+    };
+}
+function isThenable(value) {
+    return (value !== null &&
+        (typeof value === 'object' || typeof value === 'function') &&
+        typeof value.then === 'function');
+}
+// ---- runs -------------------------------------------------------------------------------------
+export const RUN_RESOURCE_KIND = 'run';
+/**
+ * A run's decision projection (D-06 § 4.3).
+ *
+ * D-06 proposed `status`, `archived`, `pinned`, `title`, `titleOrigin`, `autoResumeAt`,
+ * `queuedMessages[].id`, `steps[].id`/`steps[].status`, `branch` and `workflow`, and left the list
+ * to be reviewed against `runRecordSchema`. Reviewed against it, two additions follow from the
+ * rule itself — every field a leader mutation of a run WRITES:
+ *
+ *  - `task`: a queued run's brief stays editable until the scheduler picks it up, and a human
+ *    editing it is the "edits its brief" case § 4.1 names;
+ *  - `queuedMessages[].text`, not only the id: a queued follow-up is editable in the same way.
+ *
+ * Left out on purpose: telemetry (`tokensUsed`, `inputTokens`, `outputTokens`, `costUsd`,
+ * `peakRssBytes`, `peakProcCount`, `diffStat`, the per-step counters), presentation (`seenAt`, and
+ * the `archivedAt`/`pinnedAt` stamps whose flags ARE covered), and everything derived by the server
+ * for display (`titleSummary`, the referenced PR/issue tiers).
+ */
+export function runDecisionProjection(run) {
+    return {
+        status: run.status,
+        archived: run.archived,
+        pinned: run.pinned,
+        title: run.title,
+        titleOrigin: run.titleOrigin,
+        autoResumeAt: run.autoResumeAt,
+        task: run.task,
+        queuedMessages: run.queuedMessages?.map((message) => ({ id: message.id, text: message.text })),
+        steps: run.steps.map((step) => ({ id: step.id, status: step.status })),
+        branch: run.branch,
+        workflow: run.workflow,
+    };
+}
+/**
+ * The run's highest event `seq` on disk.
+ *
+ * D-06 names the highest ALLOCATED seq. The allocation counter is private to the store, so this
+ * reads the persisted one: it moves on every persisted event and never goes backwards, which is the
+ * property the token needs. The only allocations it cannot see are `emitEphemeral`'s, which are
+ * presentation-only and never persisted — § 4.3 would exclude them anyway.
+ */
+function highestEventSeq(store, runId) {
+    let max = 0;
+    for (const event of store.readEvents(runId)) {
+        if (typeof event.seq === 'number' && event.seq > max)
+            max = event.seq;
+    }
+    return max;
+}
+/** A run as the check sees it right now, or `undefined` when there is no such run. */
+export function runVersionSnapshot(store, runId) {
+    const run = store.getRun(runId);
+    if (!run)
+        return undefined;
+    return {
+        ref: { kind: RUN_RESOURCE_KIND, id: runId },
+        seq: highestEventSeq(store, runId),
+        projection: runDecisionProjection(run),
+    };
+}
+/** The `version` a read of this run hands the leader, or `undefined` when there is no such run. */
+export function runVersion(store, runId) {
+    const snapshot = runVersionSnapshot(store, runId);
+    return snapshot ? versionToken(snapshot) : undefined;
+}
+/**
+ * The route half of the check (#250): the rejection a run-mutating route answers with, or
+ * `undefined` when its effect may go ahead.
+ *
+ * WHY THE ROUTE, NOT THE TOOL. An MCP tool reaches the services through in-process HTTP dispatch
+ * (N-02, `service-adapter.ts`), which is async, so a tool cannot hold `guardedMutation`'s
+ * synchronous critical section around the store call — only the route handler can. So the route
+ * accepts an OPTIONAL `expectedVersion` and calls this RIGHT BEFORE its effect, with nothing but
+ * synchronous code between the two: the check and the store call then run in one stretch, exactly
+ * as `guardedMutation` would run them (§ 4.5). A handler must never put an `await` between this
+ * call and its effect; each call site says so.
+ *
+ * ABSENT MEANS "NOT ASKED", ON PURPOSE. `undefined` is the cockpit, which has never sent a token and
+ * keeps its behaviour byte-for-byte. The leader can never reach that branch: every MCP tool that
+ * mutates a run REQUIRES `expectedVersion` in its own schema (D-06 § 4.4 rule 4), and the tool
+ * tests pin that each action sends it. Present-but-wrong — empty, foreign, unknown tag, another
+ * run's — is always a rejection, never a pass.
+ *
+ * AN ASYNC EFFECT (a worktree removal, a push, `gh pr create`) cannot sit inside a synchronous
+ * stretch at all. Those routes call this right before the effect STARTS, so a stale decision never
+ * begins; a change that lands while the effect is already running is outside what a version check
+ * can see, and each such effect keeps its own guards (`isActive`, the worktree checks).
+ */
+export function staleRunWrite(store, runId, expectedVersion) {
+    if (expectedVersion === undefined)
+        return undefined;
+    const checked = guardedRunMutation(store, runId, expectedVersion, () => undefined);
+    return checked.status === 'conflict' ? checked : undefined;
+}
+/** The rejection a route answered with, when the body is one — how a tool tells a stale-version
+ *  409 from every other 409 (`run already started`, `session closed`, …). */
+export function staleRejectionIn(body) {
+    const parsed = staleVersionRejectionSchema.safeParse(body);
+    return parsed.success ? parsed.data : undefined;
+}
+/**
+ * `guardedMutation` for one run: `apply` receives the CURRENT record and performs the shared store
+ * call on it (`setPinned`, `updateRun`, …). It is never called when the token is stale.
+ */
+export function guardedRunMutation(store, runId, expectedVersion, apply, ..._sync) {
+    return guardedMutation({
+        resource: { kind: RUN_RESOURCE_KIND, id: runId },
+        expectedVersion,
+        read: () => runVersionSnapshot(store, runId),
+        apply: () => {
+            const run = store.getRun(runId);
+            // Unreachable after a passing check — the read above found it in this same synchronous
+            // stretch — but a missing run must fail loudly rather than hand `apply` an undefined.
+            if (!run)
+                throw new Error(`run ${runId} vanished inside the critical section`);
+            return apply(run);
+        },
+    }, ..._sync);
+}
+//# sourceMappingURL=stale-write.js.map

package/dist/mcp/stale-write.js.map

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

package/dist/mcp/tool.d.ts

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+import type { McpToolResult } from './ipc.ts';
+export type { McpToolResult } from './ipc.ts';
+/**
+ * What a tool runs with. Tools execute INSIDE the running xezar service, never in
+ * the bridge: the bridge only lists them and forwards `tools/call` over the
+ * project's socket (D-01 § 3.5–3.6 — the bridge is a transport adapter, not
+ * another business engine). So `project` is the project that socket belongs to,
+ * and no argument a client sends can change it (D-01 § 1.5, F-01).
+ *
+ * Deliberately small. The session binding (#87) and the shared business-service
+ * adapter (#89) widen it; widening an interface is additive for every tool.
+ */
+export interface McpToolContext {
+    readonly project: {
+        readonly id: string;
+        readonly name: string;
+        readonly root: string;
+    };
+    readonly xezarVersion: string;
+}
+/**
+ * One MCP tool. `inputSchema` is the only definition of its arguments: the JSON
+ * Schema clients see is derived from it, and the service validates every call
+ * against it before `call` runs. Results follow D-05: the text block is
+ * authoritative and `structuredContent` may only add to it.
+ */
+export interface McpTool<S extends z.ZodObject = z.ZodObject> {
+    /** `snake_case`, unique across the registry — `tools/index.test.ts` enforces both. */
+    readonly name: string;
+    readonly title?: string;
+    readonly description: string;
+    readonly inputSchema: S;
+    readonly annotations?: {
+        readonly readOnlyHint?: boolean;
+        readonly destructiveHint?: boolean;
+        readonly idempotentHint?: boolean;
+        readonly openWorldHint?: boolean;
+    };
+    call(args: z.output<S>, ctx: McpToolContext): Promise<McpToolResult>;
+}
+/** Keeps a tool's argument type inferred from its own schema. */
+export declare function defineTool<S extends z.ZodObject>(tool: McpTool<S>): McpTool;
+export declare const TOOL_NAME_RE: RegExp;
+export declare function textResult(text: string, structuredContent?: Record<string, unknown>): McpToolResult;
+export declare function errorResult(text: string, structuredContent?: Record<string, unknown>): McpToolResult;
+/** The tool as `tools/list` sends it. */
+export declare function toolListing(tool: McpTool): Record<string, unknown>;

package/dist/mcp/tool.js

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+/** Keeps a tool's argument type inferred from its own schema. */
+export function defineTool(tool) {
+    return tool;
+}
+export const TOOL_NAME_RE = /^[a-z][a-z0-9_]{0,63}$/;
+export function textResult(text, structuredContent) {
+    return { content: [{ type: 'text', text }], ...(structuredContent ? { structuredContent } : {}) };
+}
+export function errorResult(text, structuredContent) {
+    return { ...textResult(text, structuredContent), isError: true };
+}
+/** The tool as `tools/list` sends it. */
+export function toolListing(tool) {
+    const { $schema: _dialect, ...inputSchema } = z.toJSONSchema(tool.inputSchema, { io: 'input' });
+    return {
+        name: tool.name,
+        ...(tool.title ? { title: tool.title } : {}),
+        description: tool.description,
+        inputSchema,
+        ...(tool.annotations ? { annotations: tool.annotations } : {}),
+    };
+}
+//# sourceMappingURL=tool.js.map

package/dist/mcp/tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../../src/mcp/tool.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAyCxB,iEAAiE;AACjE,MAAM,UAAU,UAAU,CAAwB,IAAgB;IAChE,OAAO,IAA0B,CAAC;AACpC,CAAC;AAED,MAAM,CAAC,MAAM,YAAY,GAAG,wBAAwB,CAAC;AAErD,MAAM,UAAU,UAAU,CAAC,IAAY,EAAE,iBAA2C;IAClF,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,iBAAiB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AACpG,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,iBAA2C;IACnF,OAAO,EAAE,GAAG,UAAU,CAAC,IAAI,EAAE,iBAAiB,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AACnE,CAAC;AAED,yCAAyC;AACzC,MAAM,UAAU,WAAW,CAAC,IAAa;IACvC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,WAAW,EAAE,GAAG,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;IAChG,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5C,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,WAAW;QACX,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC/D,CAAC;AACJ,CAAC"}