cool-workflow 0.2.4 → 0.2.6

package/dist/mcp/server.js

@@ -7,8 +7,11 @@
 // "Invariants and error behavior" #9 / "Edge cases" sections:
 //   - transport: stdin/stdout, ONE JSON object per line, no
 //     Content-Length headers (mcp.md:13);
-//   - `initialize` -> protocolVersion/capabilities/serverInfo, ignoring
-//     params (mcp.md:19,263-269);
+//   - `initialize` -> protocolVersion/capabilities/serverInfo (mcp.md:
+//     19,263-269); the reply's protocolVersion echoes the client's
+//     requested one when it is in SUPPORTED_PROTOCOL_VERSIONS below, and
+//     falls back to the newest supported entry otherwise (with today's
+//     one-entry list this is byte-identical to the old fixed reply);
 //   - `tools/list` -> { tools: [...] } from core/capability-table.ts via
 //     mcp/dispatch.ts, ignoring params (mcp.md:20,271-277);
 //   - `tools/call` -> { content: [{ type: "text", text: <2-space pretty
@@ -48,12 +51,76 @@
 //     blow V8's per-string limit) becomes a small overflow notice instead
 //     of a multi-hundred-MB payload — every result under the cap is
 //     untouched, so this never affects the parity gate's own fixtures.
+//   - `tools/call` FAILURE result shape (post-v0.2.4 robustness hardening,
+//     not in the original mcp.md): an unknown tool name, a missing
+//     required tool argument, or the tool's own handler throwing is a
+//     normal RESULT, not a bare -32000 JSON-RPC protocol error — many MCP
+//     hosts never surface a protocol error back to the calling model, so
+//     it could not read the message or try again. The result is shaped
+//     { content: [{ type: "text", text: <message, plus a "Try: <hint>"
+//     line when core/format/recovery-hint.ts's recoveryHint finds one>
+//     }], isError: true }, same `resultMessage` helper as the success
+//     path. The envelope-level "missing field: name" check (right above
+//     this bullet) is unchanged — it still answers -32000.
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.mcpToolAuthority = mcpToolAuthority;
+exports.negotiateProtocolVersion = negotiateProtocolVersion;
 exports.startServer = startServer;
 const version_1 = require("../core/version");
-const safe_json_1 = require("../core/format/safe-json");
+const recovery_hint_1 = require("../core/format/recovery-hint");
 const dispatch_1 = require("./dispatch");
+const tool_process_1 = require("./tool-process");
 const MAX_LINE_BYTES = 16 * 1024 * 1024;
+/** Protocol versions this server can speak, oldest first. `initialize`
+ *  echoes the client's `params.protocolVersion` when it is in this list,
+ *  and answers with the newest entry (the last one) otherwise — the
+ *  standard MCP version-negotiation shape. With one entry this is
+ *  behavior-identical to the old hard-coded reply (mechanism first; a
+ *  second version is a one-line append here). */
+const SUPPORTED_PROTOCOL_VERSIONS = ["2024-11-05"];
+/** Read the optional server-side tool policy. When both values are unset, the
+ * full present tool list and access stay unchanged. An enabled list is an
+ * allowlist; disabled names are then removed. */
+function mcpToolAuthority(definitions = (0, dispatch_1.toolDefinitions)(), environment = process.env) {
+    const known = new Set(definitions.map((definition) => definition.name));
+    const enabled = configuredToolNames("CW_MCP_ENABLED_TOOLS", environment, known);
+    const disabled = configuredToolNames("CW_MCP_DISABLED_TOOLS", environment, known);
+    if (!enabled && !disabled)
+        return {};
+    const allowed = enabled ? new Set(enabled) : new Set(known);
+    for (const name of disabled ?? [])
+        allowed.delete(name);
+    return { allowed };
+}
+function configuredToolNames(name, environment, known) {
+    const value = environment[name];
+    if (value === undefined)
+        return undefined;
+    const names = value.split(",").map((part) => part.trim());
+    if (names.some((tool) => tool.length === 0))
+        throw new Error(`MCP tool policy ${name} contains an empty tool name`);
+    const selected = new Set(names);
+    for (const tool of selected) {
+        if (!known.has(tool))
+            throw new Error(`MCP tool policy ${name} names an unknown tool: ${tool}`);
+    }
+    return selected;
+}
+function permittedToolDefinitions(authority) {
+    const definitions = (0, dispatch_1.toolDefinitions)();
+    return authority.allowed ? definitions.filter((definition) => authority.allowed?.has(definition.name)) : definitions;
+}
+function toolPermitted(name, authority) {
+    return authority.allowed === undefined || authority.allowed.has(name);
+}
+/** Picks the `initialize` reply's protocolVersion from the client's
+ *  requested one (see SUPPORTED_PROTOCOL_VERSIONS). Exported for the
+ *  protocol-version smoke; pure. */
+function negotiateProtocolVersion(requested) {
+    if (typeof requested === "string" && SUPPORTED_PROTOCOL_VERSIONS.includes(requested))
+        return requested;
+    return SUPPORTED_PROTOCOL_VERSIONS[SUPPORTED_PROTOCOL_VERSIONS.length - 1];
+}
 // Tools whose result carries free-form text ORIGINALLY AUTHORED by a
 // worker/agent/operator/external caller — never computed or validated by
 // this codebase itself (a blackboard message body, a review comment, a
@@ -117,19 +184,15 @@ function resultMessage(id, result) {
     if (id !== undefined)
         message.id = id;
     return message;
+    // NOTE: a notification-shaped request (initialize/tools/list/tools/call
+    // with no `id`) still gets a reply here, just without an `id` key — a
+    // deliberate deviation from strict JSON-RPC (which says a notification
+    // MUST NOT be answered) pinned by SPEC/mcp.md's edge-cases. Revisit only
+    // as a deliberate spec change, not as a drive-by fix.
 }
-/** Handles one already-parsed JSON-RPC request object. May write zero or
- *  one reply line to stdout. `await`ing callTool's result is a no-op for
- *  the ~197 tools whose handler returns a plain value already (an `await`
- *  on a non-Promise resolves on the next microtask, invisible to a
- *  caller that already awaits handleRequest) -- it only matters for
- *  `cw_run`, whose live drive loop returns a real Promise so it can
- *  actually stay interruptible (see shell/drive.ts's driveAsync). This
- *  must stay inside the existing try/catch: an async tool handler throws
- *  by REJECTING its returned Promise rather than throwing synchronously,
- *  and an unawaited rejection here would be an unhandled rejection
- *  instead of the normal `-32000` JSON-RPC error reply. */
-async function handleRequest(message) {
+/** Handles one already-parsed JSON-RPC request object. The parent owns the
+ * protocol reply while the durable tool process owns the blocking tool work. */
+async function handleRequest(message, tools, authority) {
     const hasId = Object.prototype.hasOwnProperty.call(message, "id");
     const id = message.id;
     if (typeof message.method !== "string") {
@@ -142,15 +205,27 @@ async function handleRequest(message) {
     try {
         switch (message.method) {
             case "initialize": {
+                const params = (message.params ?? {});
                 writeMessage(resultMessage(id, {
-                    protocolVersion: "2024-11-05",
+                    protocolVersion: negotiateProtocolVersion(params.protocolVersion),
                     capabilities: { tools: {} },
                     serverInfo: { name: "cool-workflow", version: version_1.CURRENT_COOL_WORKFLOW_VERSION },
                 }));
                 return;
             }
             case "tools/list": {
-                writeMessage(resultMessage(id, { tools: (0, dispatch_1.toolDefinitions)() }));
+                writeMessage(resultMessage(id, { tools: permittedToolDefinitions(authority) }));
+                return;
+            }
+            case "ping": {
+                // MCP (2024-11-05, the version negotiateProtocolVersion advertises)
+                // makes ping mandatory: reply promptly with an EMPTY result. Hosts
+                // ping for keep-alive and may drop a connection that never answers.
+                // Answered here in the fast protocol path (not the serial tool
+                // queue), so a ping during a long cw_run drive still gets a reply.
+                // A ping notification (no id) gets no reply, per JSON-RPC.
+                if (hasId)
+                    writeMessage(resultMessage(id, {}));
                 return;
             }
             case "tools/call": {
@@ -160,12 +235,34 @@ async function handleRequest(message) {
                     throw new Error("MCP tools/call missing required field: name");
                 }
                 const args = params.arguments;
-                const coreResult = await (0, dispatch_1.callTool)(name, args ?? {});
-                const content = [{ type: "text", text: (0, safe_json_1.safeJsonStringify)(coreResult) }];
-                const advisory = untrustedContentAdvisory(name);
-                if (advisory)
-                    content.push({ type: "text", text: advisory });
-                writeMessage(resultMessage(id, { content }));
+                // A failure from HERE down (an unknown tool name, a missing
+                // required tool argument, or the tool's own handler throwing) is a
+                // normal call outcome, not a broken request — many MCP hosts never
+                // surface a bare JSON-RPC protocol error (-32000) back to the
+                // calling model at all, so it could not see the message and try
+                // again. Answer with a normal RESULT instead, shaped isError:
+                // true, so the model always sees the message (and, when one
+                // applies, a "Try: <hint>" recovery line) and can self-correct.
+                // The envelope-level "missing field: name" check above stays OUT
+                // of this inner try/catch — that one is a malformed request, not
+                // a tool-call outcome, and keeps going through the outer
+                // try/catch as a -32000 error, unchanged.
+                try {
+                    if (!toolPermitted(name, authority))
+                        throw new Error(`MCP tool disabled by policy: ${name}`);
+                    const text = await tools.execute(name, args ?? {});
+                    const content = [{ type: "text", text }];
+                    const advisory = untrustedContentAdvisory(name);
+                    if (advisory)
+                        content.push({ type: "text", text: advisory });
+                    writeMessage(resultMessage(id, { content }));
+                }
+                catch (error) {
+                    const text = error instanceof Error ? error.message : String(error);
+                    const hint = (0, recovery_hint_1.recoveryHint)(text);
+                    const errorText = hint ? `${text}\nTry: ${hint}` : text;
+                    writeMessage(resultMessage(id, { content: [{ type: "text", text: errorText }], isError: true }));
+                }
                 return;
             }
             default: {
@@ -180,22 +277,28 @@ async function handleRequest(message) {
         writeMessage(errorMessage(id, -32000, text));
     }
 }
-/** Handles one raw (already-trimmed, non-empty) stdin line. */
-async function handleLine(line) {
+/** Parses a raw stdin line without writing. This lets a valid ping use the
+ * control path while parse errors keep their old place in the work queue. */
+function parseLine(line) {
     let parsed;
     try {
         parsed = JSON.parse(line);
     }
     catch (error) {
         const detail = error instanceof Error ? error.message : String(error);
-        writeMessage(errorMessage(null, -32700, `Parse error: ${detail}`));
-        return;
+        return { error: { code: -32700, message: `Parse error: ${detail}` } };
     }
     if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-        writeMessage(errorMessage(null, -32600, "Invalid Request: not a JSON-RPC object"));
+        return { error: { code: -32600, message: "Invalid Request: not a JSON-RPC object" } };
+    }
+    return { message: parsed };
+}
+async function handleLine(parsed, tools, authority) {
+    if ("error" in parsed) {
+        writeMessage(errorMessage(null, parsed.error.code, parsed.error.message));
         return;
     }
-    await handleRequest(parsed);
+    await handleRequest(parsed.message, tools, authority);
 }
 /** Starts the stdio read loop. Never resolves — the server is long-lived
  *  and stops only when its stdin closes / the process exits.
@@ -205,28 +308,104 @@ async function handleLine(line) {
  *  tool but `cw_run` is still a plain synchronous handler), so this adds
  *  no real delay, but it keeps replies in the same order the requests
  *  arrived even now that one tool (`cw_run`'s live drive loop) can take
- *  many real event-loop turns to answer. */
+ *  many real event-loop turns to answer. The one exception is `ping`,
+ *  answered in handleRequest's fast path before any tool work, so a
+ *  keep-alive ping still gets a reply while a long drive holds the queue. */
 function startServer() {
+    const authority = mcpToolAuthority();
     process.stdin.setEncoding("utf8");
+    const tools = new tool_process_1.ToolProcessExecutor();
+    // EOF is a normal protocol close: keep the queue alive so a client which
+    // sent a batch and then closed stdin still gets its ordered replies. A
+    // process stop is different. Stop the child before giving the same signal
+    // back to the parent, so a child in a synchronous lock wait cannot wake up
+    // later and write state after its MCP parent is gone.
+    const stopForSignal = (signal) => {
+        const stop = () => {
+            tools.close();
+            process.removeListener(signal, stop);
+            process.kill(process.pid, signal);
+        };
+        process.once(signal, stop);
+    };
+    stopForSignal("SIGINT");
+    stopForSignal("SIGTERM");
     let buffer = "";
+    // True while the REST of an oversize line is still streaming in: emit one
+    // -32700 for the whole line and skip everything up to its terminating
+    // newline, instead of dropping the head and then re-parsing the tail as a
+    // fresh (also-failing) line — which produced a second, spurious parse
+    // error per 16MB crossed.
+    let discarding = false;
     let queue = Promise.resolve();
+    // Chain each task onto `queue` WITH a per-task `.catch`. The `.catch` is
+    // load-bearing, not decoration: a task here can reject — a raw
+    // `writeMessage` (`process.stdout.write`) that throws mid-reply because the
+    // client closed the pipe, or any other throw out of handleLine — and
+    // without a handler that one rejection would leave `queue` REJECTED for
+    // good, so every later `queue.then(...)` is skipped and the server goes
+    // silent and answers no more requests (finding: one bad write poisons the
+    // queue). The `.catch` swallows the single failure onto stderr
+    // (diagnostics, never stdout data) and hands back a RESOLVED promise, so
+    // the next request is still served. Order is still kept: the next task
+    // only runs after this one settles.
+    const enqueue = (task) => {
+        queue = queue.then(task).catch((error) => {
+            const detail = error instanceof Error ? (error.stack ?? error.message) : String(error);
+            process.stderr.write(`cool-workflow mcp: a request failed and its reply was dropped; still serving: ${detail}\n`);
+        });
+    };
     process.stdin.on("data", (chunk) => {
         buffer += chunk;
         for (;;) {
+            if (discarding) {
+                // Skip the rest of an oversize line already reported. Until its
+                // terminating newline arrives, throw away what we have (so a huge
+                // line can't grow the buffer unboundedly); once found, resume
+                // normal parsing from the next line with no second error.
+                const nl = buffer.indexOf("\n");
+                if (nl === -1) {
+                    buffer = "";
+                    break;
+                }
+                buffer = buffer.slice(nl + 1);
+                discarding = false;
+            }
             const newlineIndex = buffer.indexOf("\n");
             if (newlineIndex === -1)
                 break;
             const line = buffer.slice(0, newlineIndex);
             buffer = buffer.slice(newlineIndex + 1);
             const trimmed = line.trim();
-            if (trimmed)
-                queue = queue.then(() => handleLine(trimmed));
+            if (!trimmed)
+                continue;
+            const parsed = parseLine(trimmed);
+            // Ping is a control-plane keep-alive. It must not wait behind a tool
+            // process that is blocked on a file lock or an outside agent.
+            if ("message" in parsed && parsed.message.method === "ping") {
+                void handleLine(parsed, tools, authority).catch((error) => {
+                    const detail = error instanceof Error ? (error.stack ?? error.message) : String(error);
+                    process.stderr.write(`cool-workflow mcp: a ping reply failed: ${detail}\n`);
+                });
+            }
+            else {
+                enqueue(() => handleLine(parsed, tools, authority));
+            }
         }
-        if (buffer.length > MAX_LINE_BYTES) {
+        // No newline yet and the pending (unterminated) line already exceeds the
+        // cap: report ONCE, drop the head, and discard the rest of this line
+        // until its newline arrives (guarded by `discarding` so a >32MB line
+        // yields a single -32700, not one per 16MB crossed).
+        if (!discarding && buffer.length > MAX_LINE_BYTES) {
             buffer = "";
-            queue = queue.then(() => {
-                writeMessage(errorMessage(null, -32700, `Parse error: request line exceeds ${MAX_LINE_BYTES} bytes`));
-            });
+            discarding = true;
+            enqueue(() => writeMessage(errorMessage(null, -32700, `Parse error: request line exceeds ${MAX_LINE_BYTES} bytes`)));
         }
     });
+    // A client may send a batch and close stdin at once. Keep the tool process
+    // alive until the serial queue has written those replies, then close it so
+    // it cannot outlive the MCP parent.
+    process.stdin.on("end", () => {
+        void queue.finally(() => tools.close());
+    });
 }

package/dist/mcp/tool-process.js

@@ -0,0 +1,181 @@
+"use strict";
+// mcp/tool-process.ts — the private execution lane for MCP tools.
+//
+// The MCP server keeps its stdio protocol work in the parent process. This
+// child process runs one tools/call at a time, so a synchronous file-lock wait
+// or a long agent call cannot stop the parent from reading and answering ping.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolProcessExecutor = void 0;
+exports.startToolProcessWorker = startToolProcessWorker;
+const node_child_process_1 = require("node:child_process");
+const path = __importStar(require("node:path"));
+const safe_json_1 = require("../core/format/safe-json");
+const dispatch_1 = require("./dispatch");
+function isResponse(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const record = value;
+    return record.schemaVersion === 1 && typeof record.id === "number" && typeof record.ok === "boolean" &&
+        (record.ok ? typeof record.text === "string" : typeof record.error === "string");
+}
+function diagnostic(kind, chunk) {
+    const text = String(chunk);
+    if (text)
+        process.stderr.write(`cool-workflow mcp tool process ${kind}: ${text}`);
+}
+/** One durable, serial child process for tools/call. The public MCP server
+ * owns response shapes; this class moves only a tool request and its already
+ * rendered JSON text across IPC. A stopped child never causes an automatic
+ * retry because a tool may already have written part of its state. */
+class ToolProcessExecutor {
+    workerPath;
+    child;
+    nextId = 1;
+    pending;
+    constructor(options = {}) {
+        this.workerPath = options.workerPath ?? path.join(__dirname, "tool-process.js");
+    }
+    execute(name, args) {
+        if (this.pending)
+            throw new Error("MCP tool process received concurrent work");
+        const child = this.ensureChild();
+        const id = this.nextId++;
+        const request = { schemaVersion: 1, id, name, args };
+        return new Promise((resolve, reject) => {
+            this.pending = { id, name, resolve, reject };
+            try {
+                child.send(request, (error) => {
+                    if (!error || this.pending?.id !== id)
+                        return;
+                    this.pending = undefined;
+                    reject(error);
+                });
+            }
+            catch (error) {
+                if (this.pending?.id === id)
+                    this.pending = undefined;
+                reject(error instanceof Error ? error : new Error(String(error)));
+            }
+        });
+    }
+    close() {
+        const child = this.child;
+        this.child = undefined;
+        const pending = this.pending;
+        this.pending = undefined;
+        if (pending)
+            pending.reject(new Error(`MCP tool process stopped before ${pending.name} ended`));
+        if (!child)
+            return;
+        if (child.connected)
+            child.disconnect();
+        child.kill();
+    }
+    ensureChild() {
+        if (this.child && !this.child.killed && this.child.connected)
+            return this.child;
+        const child = (0, node_child_process_1.fork)(this.workerPath, [], {
+            cwd: process.cwd(),
+            env: process.env,
+            stdio: ["ignore", "pipe", "pipe", "ipc"],
+            serialization: "json",
+        });
+        child.stdout?.on("data", (chunk) => diagnostic("stdout", chunk));
+        child.stderr?.on("data", (chunk) => diagnostic("stderr", chunk));
+        child.on("message", (message) => this.handleMessage(child, message));
+        child.on("error", (error) => this.handleStopped(child, error));
+        child.on("exit", () => this.handleStopped(child));
+        this.child = child;
+        return child;
+    }
+    handleMessage(child, message) {
+        if (child !== this.child || !isResponse(message)) {
+            this.handleStopped(child, new Error("MCP tool process sent an invalid response"));
+            child.kill();
+            return;
+        }
+        const pending = this.pending;
+        if (!pending || pending.id !== message.id) {
+            this.handleStopped(child, new Error("MCP tool process sent an unexpected response"));
+            child.kill();
+            return;
+        }
+        this.pending = undefined;
+        if (message.ok)
+            pending.resolve(message.text);
+        else
+            pending.reject(new Error(message.error));
+    }
+    handleStopped(child, error) {
+        if (child !== this.child)
+            return;
+        this.child = undefined;
+        const pending = this.pending;
+        this.pending = undefined;
+        if (pending) {
+            pending.reject(error ?? new Error(`MCP tool process stopped before ${pending.name} ended`));
+        }
+    }
+}
+exports.ToolProcessExecutor = ToolProcessExecutor;
+function isRequest(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const record = value;
+    return record.schemaVersion === 1 && typeof record.id === "number" && typeof record.name === "string";
+}
+function send(message) {
+    if (process.send)
+        process.send(message);
+}
+/** Child entry point. Kept in this module so the parent and child share one
+ * small, checked IPC shape. */
+function startToolProcessWorker() {
+    process.on("disconnect", () => process.exit(0));
+    process.on("message", async (message) => {
+        if (!isRequest(message))
+            return;
+        try {
+            const result = await (0, dispatch_1.callTool)(message.name, message.args);
+            send({ schemaVersion: 1, id: message.id, ok: true, text: (0, safe_json_1.safeJsonStringify)(result) });
+        }
+        catch (error) {
+            send({ schemaVersion: 1, id: message.id, ok: false, error: error instanceof Error ? error.message : String(error) });
+        }
+    });
+}
+if (require.main === module)
+    startToolProcessWorker();

package/dist/mcp-server.js

@@ -6,4 +6,31 @@
 // real MCP client launches it directly with `node`).
 Object.defineProperty(exports, "__esModule", { value: true });
 const server_1 = require("./mcp/server");
-(0, server_1.startServer)();
+/** Broken-pipe guard for the MCP stdio server, the same idea as
+ *  cli/entry.ts's `main()`. When an MCP client closes the read end of our
+ *  stdout part-way through a reply, the raw write gives an async 'error'
+ *  event that no promise `.catch` can see; with no listener Node comes down
+ *  hard with a `write EPIPE` stack and exit 1. One process-level listener
+ *  turns that into a quiet exit 0 — the reader has gone, there is nothing
+ *  left to say. Any other stream error is thrown again, same as before.
+ *
+ *  This is a small COPY of cli/entry.ts's helper, not an import: the purity
+ *  gate (scripts/purity-gate.js) forbids an mcp/ file from importing cli/,
+ *  and pulling in the whole CLI entry graph for five lines would be worse. */
+function exitQuietOnEpipe(stream) {
+    stream.on("error", (error) => {
+        if (error && error.code === "EPIPE")
+            process.exit(0);
+        throw error;
+    });
+}
+exitQuietOnEpipe(process.stdout);
+exitQuietOnEpipe(process.stderr);
+try {
+    (0, server_1.startServer)();
+}
+catch (error) {
+    const text = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`cool-workflow mcp: ${text}\n`);
+    process.exitCode = 1;
+}

package/dist/shell/agent-config.js

@@ -246,10 +246,19 @@ function resolveAgentConfig(args = {}, env = process.env) {
     if (!finalCommand && !endpoint) {
         const detected = detectAgentFromPath(env);
         if (detected) {
-            finalCommand = expandBuiltinAgentCommand(`builtin:${detected}`);
+            // Detect = use what was found. Auto-detect saw a BINARY on PATH, so it
+            // must resolve to the wrapper that runs THAT binary. For "gemini" the
+            // plain builtin:gemini template goes through opencode instead (a user
+            // choice kept for the explicit -gemini flag, where --help says "via
+            // opencode") — a machine with only the native gemini CLI would be
+            // detected as ready and then fail when the wrapper spawns a missing
+            // opencode. So the auto path maps gemini to builtin:gemini-cli, the
+            // wrapper that spawns the found binary itself.
+            const template = detected === "gemini" ? "gemini-cli" : detected;
+            finalCommand = expandBuiltinAgentCommand(`builtin:${template}`);
             finalSource = "auto";
             if (!finalModel)
-                finalModel = `builtin:${detected}`;
+                finalModel = `builtin:${template}`;
         }
     }
     return {

package/dist/shell/audit-cli.js

@@ -160,7 +160,7 @@ function auditRepairCli(runId, args) {
  *  data can never drift from the standalone commands' output. */
 function auditSummaryCli(runId, args) {
     const run = (0, run_store_1.loadRunFromCwd)(runId, invocationCwd(args));
-    return (0, trust_audit_1.summarizeTrustAudit)(run);
+    return (0, trust_audit_1.summarizeTrustAudit)(run, { persist: args.__cwWorkbenchReadOnlyProjection !== true });
 }
 function auditMultiAgentCli(runId, args) {
     const run = (0, run_store_1.loadRunFromCwd)(runId, invocationCwd(args));

package/dist/shell/commit.js

@@ -199,7 +199,13 @@ function commitState(run, input) {
     // NOT prematurely move the run off "interpret".
     if (gate.verifierGated)
         run.loopStage = "checkpoint";
-    (0, fs_atomic_1.writeJson)(snapshotPath, { commit, run });
+    // Only store the commit's own (small, bounded) record. The whole run
+    // (all tasks, nodes, workers, feedback, and run.commits itself) used to
+    // be embedded here too, but no reader anywhere ever parses a `run` key
+    // back out of a commits/<id>.json file — see docs/run-retention-reclamation.7.md.
+    // Embedding the growing run made total commit-dir bytes grow like N^2
+    // in the number of commits.
+    (0, fs_atomic_1.writeJson)(snapshotPath, { commit });
     run.commits.push(commit);
     return commit;
 }
@@ -214,7 +220,7 @@ function recordCommitNode(run, commit, options, gate) {
             artifacts: [{ id: "snapshot", kind: "json", path: commit.snapshotPath }],
             evidence: commit.evidence || verifierNode.evidence,
             metadata: { ...(options.metadata || {}), reason: options.reason, commitId: commit.id, verifierGated: true, checkpoint: false, verifierNodeId: verifierNode.id, candidateId: gate.candidateId, selectionId: gate.selectionId, selectionNodeId: gate.selectionNodeId },
-        }, { persist: false, persistNode: node_store_1.writeRunNode });
+        }, { persist: false, persistNode: node_store_1.writeRunNode, pathExists: fs.existsSync });
         if (gate.selectionNodeId && commitResult.outputNodeId)
             linkAdditionalParent(run, gate.selectionNodeId, commitResult.outputNodeId);
         return commitResult.outputNodeId;