@martinloop/mcp 0.3.5 → 0.3.6

package/dist/server.js

@@ -16,12 +16,14 @@
  * Manual start:
  *   node dist/server.js
  */
+import { createServer as createHttpServer } from "node:http";
 import { fileURLToPath } from "node:url";
 import { realpathSync } from "node:fs";
 import path from "node:path";
 import { resolveRunsRoot } from "./vendor/core/index.js";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { MARTIN_MCP_PACKAGE_VERSION } from "./package-version.js";
 import { getMartinPrompt, listMartinPrompts } from "./prompts.js";
@@ -721,7 +723,7 @@ export function createMartinMcpServer(serverInfo) {
         tools: [
             {
                 name: "martin_run",
-                description: "Execute a governed Martin Loop run on a coding task and return the run summary, spend, artifact rollup, and verification state. This hard-blocks until martin_doctor, martin_plan, and martin_preflight receipts exist for the same task.",
+                description: "Execute a governed Martin Loop run on a coding task and return the run summary, spend, artifact rollup, and verification state. This hard-blocks until martin_doctor, martin_estimate, martin_plan, and martin_preflight receipts exist for the same task.",
                 annotations: {
                     destructiveHint: true,
                     idempotentHint: false,
@@ -1401,6 +1403,10 @@ export function createMartinMcpServer(serverInfo) {
                             type: "array",
                             items: { type: "string" },
                             description: "Optional file paths to scope the estimate."
+                        },
+                        workingDirectory: {
+                            type: "string",
+                            description: "Optional workspace path for recording the estimate receipt against the same task root you plan to run."
                         }
                     },
                     required: ["objective"]
@@ -1635,11 +1641,13 @@ export function createMartinMcpServer(serverInfo) {
                 return createToolSuccessResult(output, `PR review verdict for ${output.loopId}: ${output.verdict}.`);
             }
             if (name === "martin_estimate") {
-                const input = args;
+                const input = validateToolInput("martin_estimate", args);
                 const objective = input.objective;
                 const engine = input.engine ?? "claude";
                 const budgetUsd = input.budgetUsd ?? 5;
                 const fileScope = input.fileScope ?? [];
+                const runsRoot = resolveRunsRoot(process.env);
+                const workingDirectory = input.workingDirectory ?? resolveSafeRepoRoot();
                 const route = classifyRoute({
                     objective,
                     verificationPlan: [],
@@ -1662,9 +1670,24 @@ export function createMartinMcpServer(serverInfo) {
                     blockedSteps: route.blockedSteps,
                     compressed: route.compressed,
                     ...(route.compressionSummary ? { compressionSummary: route.compressionSummary } : {}),
-                    recommendedBudgetUsd
+                    recommendedBudgetUsd,
+                    recommendedModelTier: route.recommendedModelTier,
+                    estimatedSavingVsSonnetUsd: route.estimatedSavingVsSonnetUsd
                 };
-                return createToolSuccessResult(output, `Estimate: ${route.selectedMode} route, ~$${route.expectedCostUsd.toFixed(2)} expected cost, ${route.expectedPreworkBurnPct}% pre-work burn. Recommended budget: $${recommendedBudgetUsd.toFixed(2)}.`);
+                await recordMcpWorkflowStep({
+                    runsRoot,
+                    step: "estimate",
+                    workingDirectory,
+                    objective,
+                    engine,
+                    receiptScope: {
+                        invocationRoot: resolveSafeRepoRoot(),
+                        workingDirectory,
+                        repoRoot: workingDirectory,
+                        runsRoot
+                    }
+                }).catch(() => { });
+                return createToolSuccessResult(output, `Estimate: ${route.selectedMode} route (${route.recommendedModelTier}), ~$${route.expectedCostUsd.toFixed(2)} expected cost, ${route.expectedPreworkBurnPct}% pre-work burn. Recommended budget: $${recommendedBudgetUsd.toFixed(2)}.`);
             }
             return createToolErrorResult(toToolFailure(new Error(`Unknown tool: ${name}`)));
         }
@@ -1687,6 +1710,114 @@ export async function connectMartinMcpStdioServer() {
     await server.connect(transport);
     return server;
 }
+export function parseMartinMcpServerArgs(argv) {
+    let transport = "stdio";
+    let host = "127.0.0.1";
+    let port = 3033;
+    let path = "/mcp";
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === "--http") {
+            transport = "http";
+            continue;
+        }
+        if (token === "--port") {
+            const next = argv[index + 1];
+            const parsed = Number(next);
+            if (!Number.isInteger(parsed) || parsed < 0 || parsed > 65535) {
+                throw new Error(`Invalid --port value '${next ?? ""}'.`);
+            }
+            port = parsed;
+            index += 1;
+            continue;
+        }
+        if (token === "--host") {
+            const next = argv[index + 1];
+            if (!next) {
+                throw new Error("Missing value for --host.");
+            }
+            host = next;
+            index += 1;
+            continue;
+        }
+        if (token === "--path") {
+            const next = argv[index + 1];
+            if (!next || !next.startsWith("/")) {
+                throw new Error("MCP HTTP path must start with '/'.");
+            }
+            path = next;
+            index += 1;
+        }
+    }
+    return transport === "http"
+        ? { transport, host, port, path }
+        : { transport };
+}
+export async function connectMartinMcpHttpServer(options = {}) {
+    const host = options.host ?? "127.0.0.1";
+    const port = options.port ?? 3033;
+    const path = options.path ?? "/mcp";
+    const mcpServer = createMartinMcpServer();
+    const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: undefined
+    });
+    await mcpServer.connect(transport);
+    const httpServer = createHttpServer(async (req, res) => {
+        try {
+            const requestUrl = new URL(req.url ?? "/", `http://${req.headers.host ?? `${host}:${port}`}`);
+            if (requestUrl.pathname !== path) {
+                res.statusCode = 404;
+                res.setHeader("content-type", "application/json");
+                res.end(JSON.stringify({ error: "not_found", path: requestUrl.pathname }));
+                return;
+            }
+            if (req.method === "POST") {
+                const parsedBody = await readJsonBody(req, res);
+                if (res.writableEnded) {
+                    return;
+                }
+                await transport.handleRequest(req, res, parsedBody);
+                return;
+            }
+            if (req.method === "GET" || req.method === "DELETE") {
+                await transport.handleRequest(req, res);
+                return;
+            }
+            res.statusCode = 405;
+            res.setHeader("allow", "GET, POST, DELETE");
+            res.end();
+        }
+        catch (error) {
+            if (!res.headersSent) {
+                res.statusCode = 500;
+                res.setHeader("content-type", "application/json");
+                res.end(JSON.stringify({ error: "internal_error", message: error.message }));
+            }
+        }
+    });
+    await new Promise((resolve, reject) => {
+        httpServer.once("error", reject);
+        httpServer.listen(port, host, () => {
+            httpServer.off("error", reject);
+            resolve();
+        });
+    });
+    const address = httpServer.address();
+    const resolvedPort = typeof address === "object" && address ? address.port : port;
+    return {
+        server: httpServer,
+        host,
+        port: resolvedPort,
+        path,
+        endpoint: `http://${host}:${resolvedPort}${path}`,
+        close: async () => {
+            await transport.close();
+            await new Promise((resolve) => {
+                httpServer.close(() => resolve());
+            });
+        }
+    };
+}
 export function isDirectExecutionEntry(entryPath, moduleUrl = import.meta.url) {
     if (typeof entryPath !== "string" || entryPath.length === 0) {
         return false;
@@ -1707,5 +1838,30 @@ function realPathOrResolved(filePath) {
     }
 }
 if (isDirectExecution()) {
-    await connectMartinMcpStdioServer();
+    const startup = parseMartinMcpServerArgs(process.argv.slice(2));
+    if (startup.transport === "http") {
+        await connectMartinMcpHttpServer(startup);
+    }
+    else {
+        await connectMartinMcpStdioServer();
+    }
+}
+async function readJsonBody(req, res) {
+    const chunks = [];
+    for await (const chunk of req) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    const raw = Buffer.concat(chunks).toString("utf8").trim();
+    if (!raw) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        res.statusCode = 400;
+        res.setHeader("content-type", "application/json");
+        res.end(JSON.stringify({ error: "invalid_json" }));
+        return undefined;
+    }
 }

package/dist/tools/doctor.js

@@ -113,6 +113,12 @@ export async function martinDoctorTool(input) {
                 available: gemini.available,
                 detail: gemini.detail,
                 ...(gemini.resolvedPath ? { resolvedPath: gemini.resolvedPath } : {})
+            },
+            openai: {
+                available: Boolean(process.env.MARTIN_OPENAI_API_KEY),
+                detail: process.env.MARTIN_OPENAI_API_KEY
+                    ? `OpenAI-compatible endpoint configured (model: ${process.env.MARTIN_OPENAI_MODEL ?? "gpt-4.1-mini"})`
+                    : "Set MARTIN_OPENAI_API_KEY and optionally MARTIN_OPENAI_BASE_URL + MARTIN_OPENAI_MODEL to enable."
             }
         },
         ...(input.engine ? { requestedEngine: input.engine } : {}),

package/dist/tools/tool-support.d.ts

@@ -1,6 +1,6 @@
 import type { LoopArtifact, LoopBudget, LoopCost, LoopEvent, LoopTask, ReceiptIntegritySummary, ReceiptScope } from "../vendor/contracts/index.js";
 import { type LedgerEvent, type LoopAttemptRecord, type LoopRunRecord } from "../vendor/core/index.js";
-export declare const MARTIN_ENGINE_VALUES: readonly ["claude", "codex", "gemini"];
+export declare const MARTIN_ENGINE_VALUES: readonly ["claude", "codex", "gemini", "openai"];
 export type MartinEngine = (typeof MARTIN_ENGINE_VALUES)[number];
 export interface InspectableLoopAttempt extends LoopAttemptRecord {
     attemptId?: string;

package/dist/tools/tool-support.js

@@ -3,7 +3,7 @@ import { readdir, stat } from "node:fs/promises";
 import { join } from "node:path";
 import { evaluateCostGovernor, resolveRunsRoot } from "../vendor/core/index.js";
 import { readAllLoopRecordsSafely } from "./run-store.js";
-export const MARTIN_ENGINE_VALUES = ["claude", "codex", "gemini"];
+export const MARTIN_ENGINE_VALUES = ["claude", "codex", "gemini", "openai"];
 const CLI_CACHE_TTL_MS = 60_000;
 const RUN_STORE_CACHE_TTL_MS = 5_000;
 const cliAvailabilityCache = new Map();

package/dist/vendor/adapters/claude-cli.d.ts

@@ -11,14 +11,14 @@
  *
  * MCP tools and integration tests use the same factories.
  */
-import type { MartinAdapter } from "../core/index.js";
+import type { MartinAdapter, MartinAdapterRequest } from "../core/index.js";
 import { type SpawnLike } from "./cli-bridge.js";
 /**
  * Given a prompt string, returns the full argv array to pass to spawn().
  * Example for Claude:  () => ["--output-format", "json", "--print"]
  * Example for Codex:   () => ["exec", "--sandbox", "workspace-write", "-"]
  */
-export type CliArgsBuilder = (prompt: string) => string[];
+export type CliArgsBuilder = (prompt: string, request: MartinAdapterRequest) => string[];
 export type CliStdinBuilder = (prompt: string) => string | undefined;
 export interface AgentCliAdapterOptions {
     /** The executable to spawn (e.g. "claude", "codex"). */

package/dist/vendor/adapters/claude-cli.js

@@ -239,13 +239,15 @@ function extractGeminiJsonResult(stdout, modelLabel) {
         })
     };
 }
-function createStreamingUsageInspector(capUsd, modelLabel) {
+function createStreamingUsageInspector(capUsd, modelLabel, promptTokenEstimate) {
     const pricing = (modelLabel ? MODEL_PRICING[modelLabel] : undefined) ??
         { inputPer1K: BLENDED_INPUT_COST_PER_1K, outputPer1K: BLENDED_OUTPUT_COST_PER_1K };
     // Safety margin: terminate at 80% of cap to bound one-turn overshoot.
     // Without this, a single expensive turn can blow past the cap before the
     // next check fires (proven live: $1.50 cap → $28.42 actual).
-    const effectiveCapUsd = capUsd * 0.8;
+    const largeContext = promptTokenEstimate > 10_000;
+    const effectiveCapRatio = largeContext ? 0.7 : 0.8;
+    const effectiveCapUsd = capUsd * effectiveCapRatio;
     // Token-count ceiling fallback: if no usage events are ever parsed (e.g.
     // Claude changes its stream-json event format), use raw byte volume as a
     // last-resort circuit breaker. Derived from budget / blended cost per char.
@@ -269,7 +271,7 @@ function createStreamingUsageInspector(capUsd, modelLabel) {
     const checkBudgetExceeded = (terminate) => {
         if (capUsd > 0 && cumulativeUsd > effectiveCapUsd) {
             terminate(`Streaming usage cap exceeded after ${String(turns)} turn(s): cumulative cost ~$${cumulativeUsd.toFixed(4)} ` +
-                `surpassed the per-attempt cap $${capUsd.toFixed(4)} (80% threshold: $${effectiveCapUsd.toFixed(4)}). ` +
+                `surpassed the per-attempt cap $${capUsd.toFixed(4)} (${String(Math.round(effectiveCapRatio * 100))}% threshold: $${effectiveCapUsd.toFixed(4)}). ` +
                 `Subprocess terminated to bound runaway overspend.`);
         }
     };
@@ -300,11 +302,23 @@ function createStreamingUsageInspector(capUsd, modelLabel) {
         if (turnTokensIn === 0 && turnTokensOut === 0) {
             return;
         }
+        const turnUsd = (turnTokensIn / 1000) * pricing.inputPer1K + (turnTokensOut / 1000) * pricing.outputPer1K;
+        const remainingBudgetBeforeTurn = Math.max(capUsd - cumulativeUsd, 0);
+        if (capUsd > 0 && remainingBudgetBeforeTurn > 0 && turnUsd > remainingBudgetBeforeTurn * 0.5) {
+            cumulativeUsd += turnUsd;
+            tokensIn += turnTokensIn;
+            tokensOut += turnTokensOut;
+            turns += 1;
+            usageEventSeen = true;
+            terminate(`Single turn spend ~$${turnUsd.toFixed(4)} consumed more than 50% of the remaining per-attempt budget ` +
+                `($${remainingBudgetBeforeTurn.toFixed(4)} before the turn). Subprocess terminated to prevent a one-turn overshoot.`);
+            return;
+        }
         tokensIn += turnTokensIn;
         tokensOut += turnTokensOut;
         turns += 1;
         usageEventSeen = true;
-        cumulativeUsd += (turnTokensIn / 1000) * pricing.inputPer1K + (turnTokensOut / 1000) * pricing.outputPer1K;
+        cumulativeUsd += turnUsd;
         checkBudgetExceeded(terminate);
     };
     const ingestLine = (line, terminate) => {
@@ -463,7 +477,7 @@ export function createAgentCliAdapter(options) {
                     };
                 }
             }
-            const args = options.argsBuilder(prompt);
+            const args = options.argsBuilder(prompt, request);
             const stdinData = options.stdinBuilder?.(prompt);
             // Live cumulative-cost circuit breaker: a single attempt should never be
             // allowed to spend more than the loop has left. `--output-format json`
@@ -472,7 +486,7 @@ export function createAgentCliAdapter(options) {
             // instant projected spend crosses what remains — bounding the worst case
             // to roughly one turn's overshoot rather than the entire runaway session.
             const streamingUsage = options.streamingUsageCap && request.context.remainingBudgetUsd > 0
-                ? createStreamingUsageInspector(request.context.remainingBudgetUsd, options.model ?? options.command)
+                ? createStreamingUsageInspector(request.context.remainingBudgetUsd, options.model ?? options.command, estimatedUsage.tokensIn)
                 : undefined;
             const agentResult = await runSubprocess(options.command, args, {
                 cwd: workingDirectory,
@@ -790,7 +804,7 @@ export function createClaudeCliAdapter(options = {}) {
         supportsJsonOutput: true,
         streamingUsageCap: true,
         spawnImpl: options.spawnImpl,
-        argsBuilder: (_prompt) => [
+        argsBuilder: (_prompt, request) => [
             "--output-format",
             "stream-json",
             "--verbose",
@@ -801,6 +815,7 @@ export function createClaudeCliAdapter(options = {}) {
             // inside the governed subprocess, causing conflicts and "MCP server being
             // overwritten" errors.
             "--strict-mcp-config",
+            ...(request.context.remainingTokens > 0 ? ["--max-tokens", String(request.context.remainingTokens)] : []),
             ...modelArgs,
             ...extraArgs
         ],

package/dist/vendor/adapters/cli-bridge.d.ts

@@ -87,6 +87,13 @@ export interface SpawnPlan {
     args: string[];
 }
 export declare function createSpawnPlan(command: string, args: string[], cwd: string, preserveRawForInjectedSpawn: boolean): SpawnPlan;
+/**
+ * npm generates Windows shims (.cmd/.ps1, occasionally .bat) that ultimately just exec
+ * `node <real-cli-script>.js <args>` relative to the shim's own directory. Parse the shim text to
+ * find that real script path and return it if it resolves to a file that actually exists on disk;
+ * otherwise return undefined so callers fall back to the existing wrapper-shell behavior unchanged.
+ */
+export declare function resolveNpmShimScript(shimPath: string): string | undefined;
 /**
  * Returns true if the command string contains shell operators that cannot be
  * passed as literal arguments to spawn(). These must be routed through a

package/dist/vendor/adapters/cli-bridge.js

@@ -1,6 +1,6 @@
 import { spawn } from "node:child_process";
 import { delimiter, dirname, extname, isAbsolute, join, resolve } from "node:path";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { diffStatsFromNumstat } from "./runtime-support.js";
 const gitRepositoryRootCache = new Map();
 export async function runSubprocess(command, args, options) {
@@ -319,20 +319,106 @@ export function createSpawnPlan(command, args, cwd, preserveRawForInjectedSpawn)
         };
     }
     const extension = extname(resolvedOrUndefined).toLowerCase();
-    if (extension === ".cmd" || extension === ".bat") {
+    if (extension === ".cmd" || extension === ".bat" || extension === ".ps1") {
+        // npm-installed CLIs resolve to a generated shim on Windows. Wrapping that shim through an
+        // extra cmd.exe/powershell.exe hop adds a process layer that can lose the OS-level
+        // workspace-write sandbox permission when the whole tree is already nested inside another
+        // restricted parent process (e.g. VS Code's extension host), even though the same shim works
+        // fine from a top-level PowerShell window. When we can statically resolve the shim's real
+        // wrapped `node <script>` target, invoke that directly instead — this removes the extra hop
+        // for every Windows launch, nested or not, with no behavior change when resolution fails.
+        const directScript = resolveNpmShimScript(resolvedOrUndefined);
+        if (directScript !== undefined) {
+            // Use the system node rather than process.execPath. When MartinLoop runs
+            // inside Claude Code desktop or VS Code, process.execPath is Electron's
+            // bundled Node — which has different module resolution and may fail to
+            // load native CLI scripts. Prefer an explicit `node` from PATH instead.
+            const systemNode = resolveSystemNode();
+            return { command: systemNode, args: [directScript, ...args] };
+        }
+        if (extension === ".ps1") {
+            return {
+                command: "powershell.exe",
+                args: ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", resolvedOrUndefined, ...args]
+            };
+        }
         return {
             command: process.env.ComSpec || "cmd.exe",
             args: ["/d", "/c", resolvedOrUndefined, ...args]
         };
     }
-    if (extension === ".ps1") {
-        return {
-            command: "powershell.exe",
-            args: ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", resolvedOrUndefined, ...args]
-        };
-    }
     return { command: resolvedOrUndefined, args };
 }
+/**
+ * npm generates Windows shims (.cmd/.ps1, occasionally .bat) that ultimately just exec
+ * `node <real-cli-script>.js <args>` relative to the shim's own directory. Parse the shim text to
+ * find that real script path and return it if it resolves to a file that actually exists on disk;
+ * otherwise return undefined so callers fall back to the existing wrapper-shell behavior unchanged.
+ */
+export function resolveNpmShimScript(shimPath) {
+    let contents;
+    try {
+        contents = readFileSync(shimPath, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    const shimDir = dirname(shimPath);
+    const scriptPathPattern = /["']?(?:%~?dp0%?|\$basedir)[\\/]([^"'\s]+\.[cm]?js)["']?/gi;
+    const matches = contents.matchAll(scriptPathPattern);
+    for (const match of matches) {
+        const relativeScript = match[1];
+        if (!relativeScript) {
+            continue;
+        }
+        const segments = relativeScript.split(/[\\/]+/u).filter(Boolean);
+        const resolvedScript = resolve(shimDir, ...segments);
+        if (existsSync(resolvedScript)) {
+            return resolvedScript;
+        }
+    }
+    return undefined;
+}
+/**
+ * Resolve a reliable `node` executable for spawning CLI scripts on Windows.
+ *
+ * When MartinLoop runs inside Claude Code desktop, VS Code, or the Codex IDE,
+ * `process.execPath` points to the host application's bundled Electron Node —
+ * not the system Node. Electron's Node has different module resolution paths
+ * and may fail to load native npm CLI scripts that expect the system Node.
+ *
+ * Strategy:
+ * 1. Use MARTIN_NODE_PATH env var if explicitly set (escape hatch for CI)
+ * 2. Look for `node` / `node.exe` on PATH — the system install
+ * 3. Fall back to process.execPath (Electron Node) if nothing else found
+ */
+function resolveSystemNode() {
+    // Explicit override — useful in CI or restricted environments
+    const envOverride = process.env.MARTIN_NODE_PATH?.trim();
+    if (envOverride && envOverride.length > 0 && existsSync(envOverride)) {
+        return envOverride;
+    }
+    // Search PATH for a real `node` executable, skipping Electron binaries.
+    // Electron's node path typically contains "electron" or "Claude" in it.
+    for (const dir of windowsPathDirectories()) {
+        for (const candidate of ["node.exe", "node.cmd", "node"]) {
+            const fullPath = join(dir, candidate);
+            if (existsSync(fullPath) && !isElectronNode(fullPath)) {
+                return fullPath;
+            }
+        }
+    }
+    // Last resort: use process.execPath even if it's Electron's node
+    return process.execPath;
+}
+function isElectronNode(nodePath) {
+    const lower = nodePath.toLowerCase();
+    return (lower.includes("electron") ||
+        lower.includes("claude") ||
+        lower.includes("vscode") ||
+        lower.includes("code.exe") ||
+        lower.includes("cursor"));
+}
 function resolveWindowsCommand(command, cwd) {
     const hasPathSegment = command.includes("\\") || command.includes("/");
     const baseCandidates = expandWindowsCommandCandidates(hasPathSegment ? resolve(cwd, command) : command);

package/dist/vendor/adapters/codex-launcher.js

@@ -1,6 +1,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, readdirSync, statSync } from "node:fs";
 import { dirname, extname, join, resolve } from "node:path";
+import { resolveNpmShimScript } from "./cli-bridge.js";
 const codexLaunchProbeCache = new Map();
 export const DEFAULT_CODEX_CHATGPT_MODEL = "gpt-5.4";
 const CODEX_LAUNCH_PROBE_PROMPT = [
@@ -121,17 +122,27 @@ function buildProbeCommand(command, args, platform) {
     switch (extension) {
         case ".cmd":
         case ".bat":
+        case ".ps1": {
+            // Bypass the npm shim's cmd.exe/powershell.exe wrapper hop when we can statically resolve
+            // the real `node <script>` target it wraps — keeps the live probe's process-nesting depth
+            // consistent with the real run's invocation (see createSpawnPlan in cli-bridge.ts).
+            const directScript = resolveNpmShimScript(command);
+            if (directScript !== undefined) {
+                return { command: process.execPath, args: [directScript, ...args], invocationMode: "direct" };
+            }
+            if (extension === ".ps1") {
+                return {
+                    command: "powershell.exe",
+                    args: ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", command, ...args],
+                    invocationMode: "powershell"
+                };
+            }
             return {
                 command: process.env.ComSpec || "cmd.exe",
                 args: ["/d", "/c", command, ...args],
                 invocationMode: "cmd_shell"
             };
-        case ".ps1":
-            return {
-                command: "powershell.exe",
-                args: ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", command, ...args],
-                invocationMode: "powershell"
-            };
+        }
         default:
             return { command, args, invocationMode: "direct" };
     }
@@ -236,7 +247,7 @@ function classifyProbeFailure(stderr, stdout, diagnosis) {
                 ...diagnosis,
                 sandboxCompatible: false,
                 warnings,
-                remediation: "Update or reinstall Codex on this Windows host until `codex exec --sandbox workspace-write` can launch a simple shell command before running governed Codex work."
+                remediation: "MartinLoop already invokes Codex's underlying binary directly when it can resolve the npm shim (bypassing the cmd.exe/PowerShell wrapper hop), so this failure persisted even at the shallowest invocation depth available. Update or reinstall Codex on this Windows host until `codex exec --sandbox workspace-write` can launch a simple shell command before running governed Codex work."
             }
         };
     }