@cjhyy/code-shell-core 0.6.0-rc.7 → 0.6.0-rc.9

package/dist/protocol/server.js

@@ -26,6 +26,19 @@ import { logger } from "../logging/logger.js";
 import { nanoid } from "nanoid";
 import { redactLlmConfig, maskSecretValue } from "./redact.js";
 import { redactSecrets } from "../logging/sanitize-messages.js";
+const COMPACT_STREAM_STRATEGIES = new Set([
+    "micro",
+    "summary",
+    "window",
+    "snip",
+    "emergency",
+    "compacted",
+]);
+function toCompactStreamStrategy(strategy) {
+    return COMPACT_STREAM_STRATEGIES.has(strategy)
+        ? strategy
+        : "compacted";
+}
 export class AgentServer {
     chatManager;
     legacyEngine;
@@ -336,9 +349,9 @@ export class AgentServer {
             session.engine.setAskUser((question, opts) => this.requestAskUserForSession(session, sid, question, opts));
             // Browser automation bridge: each method routes a browser action to the
             // client (Electron main drives the webview via CDP) over the SAME
-            // request/response channel as askUser (pendingApprovals + requestId),
-            // reusing its proven resolve/timeout/cleanup. The main-side handler
-            // replies with the action's JSON result.
+            // request/response channel as askUser (pendingApprovals + requestId).
+            // Browser actions still keep their own bounded timeout; AskUserQuestion
+            // waits for a real answer or Stop/cancel.
             session.engine.setBrowserBridge(this.makeBrowserBridge(session, sid));
             // Cookie→browser injection (InjectCredential tool): same cross-process
             // channel; main restores the cookie jar into the built-in browser.
@@ -352,6 +365,7 @@ export class AgentServer {
                     ? params.goal
                     : undefined,
                 onStream: (event) => this.notify(Methods.StreamEvent, { sessionId: sid, event }),
+                clientMessageId: typeof params.clientMessageId === "string" ? params.clientMessageId : undefined,
             });
             const runResult = {
                 text: result.text,
@@ -431,6 +445,7 @@ export class AgentServer {
                 sessionId: params.sessionId,
                 signal: runController.signal,
                 onStream: streamToClient,
+                clientMessageId: typeof params.clientMessageId === "string" ? params.clientMessageId : undefined,
                 goal: typeof params.goal === "string" ||
                     (params.goal != null && typeof params.goal === "object")
                     ? params.goal
@@ -478,7 +493,10 @@ export class AgentServer {
     // ─── Approve ────────────────────────────────────────────────────
     handleApprove(req) {
         const params = (req.params ?? {});
-        // ChatSessionManager path: look up per-session pendingApprovals
+        // ChatSessionManager path: approvals are scoped by (sessionId, requestId).
+        // Never fall back from a session-tagged response to the legacy global map:
+        // a stale/misrouted UI response must fail closed instead of resolving a
+        // pending prompt from another session.
         if (this.chatManager && typeof params.sessionId === "string") {
             const s = this.chatManager.get(params.sessionId);
             if (!s) {
@@ -487,25 +505,13 @@ export class AgentServer {
             }
             const resolve = s.pendingApprovals.get(params.requestId);
             if (!resolve) {
-                // Tool approvals still resolve through the interactive backend's
-                // legacy pending map; the sessionId on their envelope is UI routing
-                // metadata. Accept a session-tagged response for those requests too.
-                const legacyResolve = this.pendingApprovals.get(params.requestId);
-                if (!legacyResolve) {
-                    this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, `No pending approval: ${params.requestId}`));
-                    return;
-                }
-                this.pendingApprovals.delete(params.requestId);
-                this.clearApprovalTimer(params.requestId);
-                legacyResolve(params.decision);
-                this.transport.send(createResponse(req.id, { ok: true }));
+                this.transport.send(createErrorResponse(req.id, ErrorCodes.InvalidParams, `No pending approval for session ${params.sessionId}: ${params.requestId}`));
                 return;
             }
             s.pendingApprovals.delete(params.requestId);
-            // Cancel the pending timeout for THIS request (the ask path armed one).
-            // The legacy single-engine branch below already does this; without it
-            // here a decided request leaves a live timer that fires at
-            // APPROVAL_TIMEOUT_MS and churns a dead map entry.
+            // Cancel the pending timeout for requests that arm one (browser actions,
+            // credential injection, and tool approvals). AskUserQuestion does not use
+            // a timeout; this is harmless for those request ids.
             this.clearApprovalTimer(params.requestId);
             resolve(params.decision);
             this.transport.send(createResponse(req.id, { ok: true }));
@@ -539,11 +545,10 @@ export class AgentServer {
             s.cancel();
             // s.cancel() only aborts the engine controller + drains queued turns. The
             // session's pendingApprovals (askUser / browser_action / tool approvals)
-            // are NOT driven by the abort signal — they only settle on a client reply
-            // or the 5-minute APPROVAL_TIMEOUT_MS. Left alone, the awaiting tool call
-            // hangs until that timeout (delaying run wind-down) and the server-side
-            // approvalTimers entry leaks. Resolve them as cancelled now and clear the
-            // matching timers, mirroring the legacy path below.
+            // are NOT driven directly by the abort signal. Left alone, an awaiting
+            // AskUserQuestion would now wait forever, while bounded request types
+            // would wait until APPROVAL_TIMEOUT_MS. Resolve them as cancelled now and
+            // clear any matching timers, mirroring the legacy path below.
             this.cancelSessionApprovals(s);
             this.transport.send(createResponse(req.id, { ok: true }));
             return;
@@ -726,6 +731,10 @@ export class AgentServer {
             return;
         }
         if (this.chatManager) {
+            const session = this.chatManager.get(params.sessionId);
+            if (session) {
+                this.cancelSessionApprovals(session, "session closed");
+            }
             this.chatManager.close(params.sessionId);
         }
         // Explicit session teardown — reap that session's background shells
@@ -997,17 +1006,53 @@ export class AgentServer {
                 break;
             }
             case "compact": {
-                const compactEngine = this.chatManager && typeof params.sessionId === "string"
-                    ? this.chatManager.get(params.sessionId)?.engine
-                    : engine;
+                const compactSessionId = typeof params.sessionId === "string" && params.sessionId.length > 0
+                    ? params.sessionId
+                    : undefined;
+                let compactEngine = engine;
+                if (this.chatManager) {
+                    if (compactSessionId) {
+                        let session = this.chatManager.get(compactSessionId);
+                        if (!session) {
+                            const probeEngine = this.anyEngine();
+                            if (!probeEngine?.sessionExistsOnDisk(compactSessionId)) {
+                                this.transport.send(createErrorResponse(req.id, ErrorCodes.SessionNotFound, `Session not found: ${compactSessionId}`));
+                                return;
+                            }
+                            try {
+                                session = this.chatManager.getOrCreate(compactSessionId, {
+                                    cwd: probeEngine.getSessionManager().readCwd(compactSessionId),
+                                });
+                            }
+                            catch (err) {
+                                this.transport.send(createErrorResponse(req.id, err.code ?? ErrorCodes.InternalError, err.message));
+                                return;
+                            }
+                        }
+                        compactEngine = session.engine;
+                    }
+                    else {
+                        compactEngine = this.anyEngine();
+                    }
+                }
                 if (!compactEngine) {
-                    this.transport.send(createErrorResponse(req.id, this.chatManager && params.sessionId ? ErrorCodes.SessionClosed : ErrorCodes.InternalError, this.chatManager && params.sessionId
-                        ? `No such live session: ${params.sessionId}`
-                        : "No engine available for compact query"));
+                    this.transport.send(createErrorResponse(req.id, ErrorCodes.InternalError, "No engine available for compact query"));
                     return;
                 }
                 try {
-                    const result = compactEngine.forceCompact();
+                    const result = await compactEngine.forceCompact(compactSessionId);
+                    if (result.before > result.after) {
+                        const event = {
+                            type: "context_compact",
+                            strategy: toCompactStreamStrategy(result.strategy),
+                            before: result.before,
+                            after: result.after,
+                        };
+                        this.notify(Methods.StreamEvent, {
+                            sessionId: compactSessionId ?? "",
+                            event,
+                        });
+                    }
                     this.transport.send(createResponse(req.id, {
                         type: "compact",
                         data: result,
@@ -1335,8 +1380,8 @@ export class AgentServer {
             return;
         }
         try {
-            engine.enqueueSteer(params.sessionId, params.text, params.id);
-            this.transport.send(createResponse(req.id, { ok: true }));
+            const result = engine.enqueueSteer(params.sessionId, params.text, params.id, params.clientMessageId);
+            this.transport.send(createResponse(req.id, { ok: true, ...result }));
         }
         catch (err) {
             this.transport.send(createErrorResponse(req.id, ErrorCodes.InternalError, err.message));
@@ -1373,10 +1418,23 @@ export class AgentServer {
         return new Promise((resolve) => {
             const requestId = nanoid(12);
             const sessionId = typeof request.sessionId === "string" ? request.sessionId : undefined;
-            this.pendingApprovals.set(requestId, resolve);
+            const session = this.chatManager && sessionId ? this.chatManager.get(sessionId) : undefined;
+            if (this.chatManager && sessionId && !session) {
+                resolve({ approved: false, reason: `session closed: ${sessionId}` });
+                return;
+            }
+            if (session) {
+                session.pendingApprovals.set(requestId, (decision) => {
+                    resolve(decision);
+                });
+            }
+            else {
+                this.pendingApprovals.set(requestId, resolve);
+            }
             const timer = setTimeout(() => {
-                if (this.pendingApprovals.has(requestId)) {
-                    this.pendingApprovals.delete(requestId);
+                const pending = session?.pendingApprovals ?? this.pendingApprovals;
+                if (pending.has(requestId)) {
+                    pending.delete(requestId);
                     this.approvalTimers.delete(requestId);
                     resolve({ approved: false, reason: "approval timed out" });
                 }
@@ -1390,14 +1448,11 @@ export class AgentServer {
         });
     }
     /**
-     * Ask the client to answer a question from the agent (legacy single-engine path).
-     */
-    /**
-     * Per-session AskUserQuestion for the chatManager path. Mirrors
-     * requestAskUserFromClient but resolves via the SESSION's pendingApprovals
-     * (the chatManager approve handler looks there, keyed by sessionId+requestId)
-     * and tags the notify with sessionId so the renderer routes the question to
-     * the right chat tab.
+     * Per-session AskUserQuestion for the chatManager path. Resolves via the
+     * SESSION's pendingApprovals (the chatManager approve handler looks there,
+     * keyed by sessionId+requestId) and tags the notify with sessionId so the
+     * renderer routes the question to the right chat tab. This intentionally has
+     * no wall-clock timeout; Stop/cancel drains the pending ask.
      */
     requestAskUserForSession(session, sessionId, question, opts) {
         return new Promise((resolve) => {
@@ -1413,14 +1468,6 @@ export class AgentServer {
                     resolve(typeof decision === "string" ? decision : "");
                 }
             });
-            const timer = setTimeout(() => {
-                if (session.pendingApprovals.has(requestId)) {
-                    session.pendingApprovals.delete(requestId);
-                    this.approvalTimers.delete(requestId);
-                    resolve("(approval timed out)");
-                }
-            }, AgentServer.APPROVAL_TIMEOUT_MS);
-            this.approvalTimers.set(requestId, timer);
             const args = { question };
             if (opts?.header !== undefined)
                 args.header = opts.header;
@@ -1565,6 +1612,11 @@ export class AgentServer {
             });
         });
     }
+    /**
+     * Ask the client to answer a question from the agent (legacy single-engine
+     * path). This intentionally has no wall-clock timeout; Stop/cancel drains
+     * the pending ask.
+     */
     requestAskUserFromClient(question, opts) {
         return new Promise((resolve) => {
             const requestId = nanoid(12);
@@ -1577,14 +1629,6 @@ export class AgentServer {
                     resolve(result.reason ?? "(user declined to answer)");
                 }
             });
-            const timer = setTimeout(() => {
-                if (this.pendingApprovals.has(requestId)) {
-                    this.pendingApprovals.delete(requestId);
-                    this.approvalTimers.delete(requestId);
-                    resolve("(approval timed out)");
-                }
-            }, AgentServer.APPROVAL_TIMEOUT_MS);
-            this.approvalTimers.set(requestId, timer);
             const args = { question };
             if (opts?.header !== undefined)
                 args.header = opts.header;
@@ -1646,6 +1690,9 @@ export class AgentServer {
             this.bgAgentBusUnsubscribe = null;
         }
         if (this.chatManager) {
+            this.chatManager.forEachSession((session) => {
+                this.cancelSessionApprovals(session, "server closing");
+            });
             this.chatManager.closeAll();
         }
         // Legacy path cleanup
@@ -1674,17 +1721,16 @@ export class AgentServer {
     }
     /**
      * Resolve all of a chat session's pending approvals as cancelled and clear
-     * the matching server-side approval timers. Used by handleCancel's
+     * any matching server-side approval timers. Used by handleCancel's
      * per-session path so a Stop while a tool is awaiting approval doesn't leave
-     * the tool hanging until APPROVAL_TIMEOUT_MS (and leak the timer). Each
-     * requestId in the session map has a same-keyed entry in this.approvalTimers
-     * (see requestAskUserForSession / makeBrowserBridge).
+     * the tool hanging. Bounded request types have same-keyed timer entries;
+     * AskUserQuestion does not.
      */
-    cancelSessionApprovals(session) {
+    cancelSessionApprovals(session, reason = "cancelled") {
         for (const [requestId, resolve] of session.pendingApprovals) {
             this.clearApprovalTimer(requestId);
             try {
-                resolve({ approved: false, reason: "cancelled" });
+                resolve({ approved: false, reason });
             }
             catch {
                 /* a resolver must never break cancel cleanup */

package/dist/protocol/types.d.ts

@@ -51,6 +51,8 @@ export declare const ErrorCodes: {
 export interface RunParams {
     sessionId: string;
     task: string;
+    /** Stable id for the user's submit intent; duplicate ids are idempotent. */
+    clientMessageId?: string;
     /**
      * Working directory for this run. When omitted, the Engine uses its
      * configured cwd.
@@ -133,6 +135,8 @@ export interface SteerParams {
     /** Stable host-side id for this queued draft. Rides through to the
      *  steer_injected event and is the handle Unsteer uses to revoke it. */
     id?: string;
+    /** Stable submit-intent id, distinct from the queued steer id. */
+    clientMessageId?: string;
 }
 /** Revoke a still-pending steer entry by id (before the loop consumes it). */
 export interface UnsteerParams {

package/dist/runtime/safe-spawn.js

@@ -35,7 +35,7 @@
  */
 import { spawn } from "node:child_process";
 import { StringDecoder } from "node:string_decoder";
-import { resolveSpawnTarget, defaultShellBinary, killChildTree } from "./spawn-common.js";
+import { resolveSpawnTarget, defaultShellBinary, killChildTree, killProcessGroup } from "./spawn-common.js";
 export const DEFAULT_MAX_OUTPUT_BYTES = 1_000_000;
 export const DEFAULT_IO_DRAIN_GRACE_MS = 100;
 const TIMEOUT_SIGKILL_GRACE_MS = 2000;
@@ -71,9 +71,21 @@ export function safeSpawnShell(command, opts) {
         shell,
         sandbox: opts.sandbox,
     });
-    return runLifecycle({ file, args, opts, cleanup, resolveMs: elapsedMs(resolveStartedAt) });
+    // Shell commands run free-form LLM strings that routinely background
+    // grandchildren (`pytest &`, `sh → npm → node`). Spawn as a process-group
+    // leader (detached) so a timeout/abort kill reaches the WHOLE subtree, not
+    // just the direct shell — otherwise an orphaned grandchild keeps the
+    // inherited stdout pipe open and Node's `close` never fires (the hang).
+    return runLifecycle({
+        file,
+        args,
+        opts,
+        cleanup,
+        resolveMs: elapsedMs(resolveStartedAt),
+        detached: true,
+    });
 }
-function runLifecycle({ file, args, opts, cleanup, resolveMs }) {
+function runLifecycle({ file, args, opts, cleanup, resolveMs, detached }) {
     const maxBytes = opts.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
     const abortGrace = opts.ioDrainGraceMs ?? DEFAULT_IO_DRAIN_GRACE_MS;
     const lifecycleStartedAt = spawnProfileEnabled() ? performance.now() : 0;
@@ -84,10 +96,19 @@ function runLifecycle({ file, args, opts, cleanup, resolveMs }) {
     }
     return new Promise((resolve) => {
         let settled = false;
+        // Declared before finish() so the spawn-failed early-return (which calls
+        // finish before these are assigned) doesn't hit a TDZ reference.
+        let timer;
+        let settleTimer;
+        let onAbort;
         const finish = (result) => {
             if (settled)
                 return;
             settled = true;
+            if (timer)
+                clearTimeout(timer);
+            if (settleTimer)
+                clearTimeout(settleTimer);
             logSpawnProfile(file, args, resolveMs, elapsedMs(lifecycleStartedAt), result.reason);
             // Always release backend-allocated resources, regardless of exit path.
             // cleanup is best-effort — see seatbelt backend for rationale.
@@ -101,7 +122,7 @@ function runLifecycle({ file, args, opts, cleanup, resolveMs }) {
         };
         let child;
         try {
-            child = spawn(file, args, { cwd: opts.cwd, env: opts.env });
+            child = spawn(file, args, { cwd: opts.cwd, env: opts.env, detached });
         }
         catch (err) {
             finish(emptyResult({ reason: "spawn_failed", spawnFailed: true, error: err.message }));
@@ -115,21 +136,63 @@ function runLifecycle({ file, args, opts, cleanup, resolveMs }) {
         let stderrTruncated = false;
         let timedOut = false;
         let aborted = false;
-        const timer = setTimeout(() => {
+        let lastExitCode = null;
+        let lastExitSignal = null;
+        // Terminate the child on timeout/abort. When detached (shell mode) the
+        // child leads its own process group, so kill the WHOLE group — this reaps
+        // backgrounded grandchildren (`pytest &`, `sh → npm → node`) that a bare
+        // child.kill() would orphan. After the kill, arm a settle deadline:
+        // Node's `close` waits for every inherited stdio pipe to close, and an
+        // orphaned grandchild can hold stdout open forever, so `close` may never
+        // fire. Force a resolve via the last-seen `exit` code once the kill grace
+        // has elapsed — the promise must never hang past terminate().
+        const terminate = (graceMs) => {
+            if (detached && typeof child.pid === "number") {
+                void killProcessGroup(child.pid, { graceMs });
+            }
+            else {
+                killChildTree(child, graceMs);
+            }
+            if (settleTimer)
+                return;
+            settleTimer = setTimeout(() => {
+                finishFromExit();
+            }, graceMs + 500);
+            settleTimer.unref?.();
+        };
+        timer = setTimeout(() => {
             timedOut = true;
-            // win32: taskkill /T reaps the whole tree (a foreground `npm test`
-            // spawns node children that child.kill() alone would orphan). POSIX:
-            // SIGTERM → grace → SIGKILL. See killChildTree.
-            killChildTree(child, TIMEOUT_SIGKILL_GRACE_MS);
+            terminate(TIMEOUT_SIGKILL_GRACE_MS);
         }, opts.timeoutMs);
-        let onAbort;
         if (opts.signal) {
             onAbort = () => {
                 aborted = true;
-                killChildTree(child, abortGrace);
+                terminate(abortGrace);
             };
             opts.signal.addEventListener("abort", onAbort, { once: true });
         }
+        // Fallback finish when `close` never arrives because a killed process's
+        // orphaned grandchild still holds a stdio pipe. Uses whatever `exit` code
+        // we saw (exit fires when the direct child dies, independent of stdio).
+        const finishFromExit = () => {
+            const reason = timedOut ? "timeout" : aborted ? "aborted" : "ok";
+            finish({
+                reason,
+                stdout,
+                stderr,
+                exitCode: lastExitCode,
+                signal: lastExitSignal,
+                stdoutTruncated,
+                stderrTruncated,
+                timedOut,
+                aborted,
+                spawnFailed: false,
+            });
+        };
+        child.on("exit", (code, sig) => {
+            lastExitCode = code;
+            lastExitSignal = sig;
+        });
         child.stdout?.on("data", (chunk) => {
             if (stdoutTruncated)
                 return;

package/dist/session/session-manager.js

@@ -7,6 +7,7 @@ import { homedir } from "node:os";
 import { nanoid } from "nanoid";
 import { Transcript } from "./transcript.js";
 import { SessionError } from "../exceptions.js";
+import { normalizeCumulativeUsageCounters } from "../engine/session-usage.js";
 /**
  * Validate a session ID before it is joined into a filesystem path.
  *
@@ -83,6 +84,9 @@ export class SessionManager {
             model,
             provider,
             tokenUsage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+            cumulativePromptTokens: 0,
+            cumulativeCacheReadTokens: 0,
+            cumulativeCacheCreationTokens: 0,
             turnCount: 0,
             invokedSkills: [],
             status: "active",
@@ -245,6 +249,7 @@ export class SessionManager {
         const transcriptFile = join(sessionDir, "transcript.jsonl");
         const transcript = Transcript.loadFromFile(transcriptFile);
         state.status = "active";
+        Object.assign(state, normalizeCumulativeUsageCounters(state, state.tokenUsage));
         return { state, transcript };
     }
     saveState(state) {
@@ -275,7 +280,8 @@ export class SessionManager {
         newBundle.state.parentSessionId = sourceSessionId;
         // Copy events up to the fork point
         for (const event of events) {
-            if (event.type === "turn_boundary" && (event.data.turnNumber ?? -1) > forkTurn) {
+            if (event.type === "turn_boundary" &&
+                (event.data.turnNumber ?? -1) > forkTurn) {
                 break;
             }
             newBundle.transcript.append(event.type, event.data);

package/dist/session/transcript.d.ts

@@ -22,7 +22,10 @@ export declare class Transcript {
      */
     appendMessage(role: string, content: string | ContentBlock[], opts?: {
         injected?: boolean;
+        steerId?: string;
+        clientMessageId?: string;
     }): TranscriptEvent;
+    hasClientMessageId(clientMessageId: string): boolean;
     appendToolUse(toolName: string, toolCallId: string, args: Record<string, unknown>): TranscriptEvent;
     appendToolResult(toolCallId: string, toolName: string, result?: string, error?: string): TranscriptEvent;
     /** Anchor for a spawned sub-agent (see TranscriptEventType "subagent").
@@ -52,6 +55,7 @@ export declare class Transcript {
     getEvents(type?: TranscriptEventType): TranscriptEvent[];
     get turnNumber(): number;
     get eventCount(): number;
+    private findMessageByClientId;
     private flush;
     /**
      * Repair tool_result pairing issues:

package/dist/session/transcript.js

@@ -5,6 +5,7 @@
 import { appendFileSync, readFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { nanoid } from "nanoid";
+import { logger } from "../logging/logger.js";
 export class Transcript {
     events = [];
     filePath;
@@ -40,12 +41,28 @@ export class Transcript {
      * step-gap steering messages are left unmarked so they render normally.
      */
     appendMessage(role, content, opts) {
+        if (opts?.clientMessageId) {
+            const existing = this.findMessageByClientId(opts.clientMessageId);
+            if (existing) {
+                logger.info("steer.submit.duplicate_ignored", {
+                    clientMessageId: opts.clientMessageId,
+                    role,
+                    transcript: this.filePath,
+                });
+                return existing;
+            }
+        }
         return this.append("message", {
             role,
             content,
             ...(opts?.injected ? { injected: true } : {}),
+            ...(opts?.steerId ? { steerId: opts.steerId } : {}),
+            ...(opts?.clientMessageId ? { clientMessageId: opts.clientMessageId } : {}),
         });
     }
+    hasClientMessageId(clientMessageId) {
+        return this.findMessageByClientId(clientMessageId) !== undefined;
+    }
     appendToolUse(toolName, toolCallId, args) {
         return this.append("tool_use", { toolName, toolCallId, args });
     }
@@ -150,6 +167,10 @@ export class Transcript {
     get eventCount() {
         return this.events.length;
     }
+    findMessageByClientId(clientMessageId) {
+        return this.events.find((event) => event.type === "message" &&
+            event.data.clientMessageId === clientMessageId);
+    }
     flush(event) {
         try {
             appendFileSync(this.filePath, JSON.stringify(event) + "\n", "utf-8");

package/dist/tool-system/mcp-manager.js

@@ -11,6 +11,7 @@ import { CredentialStore } from "../credentials/index.js";
 import { ENV_ALLOWLIST } from "../runtime/spawn-common.js";
 import { writeFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";
+import { diagnoseMcpStdioMissingCommand, previewPath } from "./mcp-stdio-diagnostics.js";
 /**
  * Read a required secret from `process.env` by NAME (Codex-style env-secret
  * handling — the value is never persisted in MCP config). A referenced env var
@@ -393,6 +394,22 @@ export class MCPManager {
             catch {
                 // ignore cleanup errors
             }
+            if (transportType === "stdio" && config.command) {
+                const diagnostic = await diagnoseMcpStdioMissingCommand(config.command, err);
+                if (diagnostic) {
+                    logger.warn("mcp.stdio_command_missing", {
+                        server: name,
+                        command: config.command,
+                        foundPaths: diagnostic.foundPaths,
+                        path: previewPath(),
+                        message: diagnostic.message,
+                    });
+                    const original = err instanceof Error ? err.message : String(err);
+                    const enhanced = new Error(`${original}\n${diagnostic.message}`);
+                    enhanced.cause = err;
+                    throw enhanced;
+                }
+            }
             throw err;
         }
         finally {

package/dist/tool-system/mcp-stdio-diagnostics.d.ts

@@ -0,0 +1,9 @@
+export declare function isBareCommand(command: string): boolean;
+export declare function isMissingCommandError(error: unknown): boolean;
+export declare function probeCommonExecutableLocations(command: string, env?: NodeJS.ProcessEnv): Promise<string[]>;
+export declare function classifyMcpStdioMissingCommand(command: string, foundPaths: readonly string[]): string;
+export declare function diagnoseMcpStdioMissingCommand(command: string, error: unknown, env?: NodeJS.ProcessEnv): Promise<{
+    message: string;
+    foundPaths: string[];
+} | null>;
+export declare function previewPath(env?: NodeJS.ProcessEnv): string;