@dailephd/my-dev-kit-lab 0.5.0 → 0.5.2

package/dist/src/agents/adapters/claudeAdapter.js

@@ -2,6 +2,20 @@ import { runCliAgent } from "./codexAdapter.js";
 import { applyPromptToCommandTemplate } from "../runAgentPrompt.js";
 import { parseAgentTokenUsage } from "../parseAgentTokenUsage.js";
 import { runMeasuredCommand } from "../../core/runMeasuredCommand.js";
+// v0.5.2 Batch 2 -- frozen stdin invocation for the real-agent evaluation transport. Every flag
+// here is planner-owned; --bare is intentionally not used (it changes auth behavior and still
+// exposes Bash/read/edit tools unless separately constrained).
+const CLAUDE_STDIN_ARGS = [
+    "--restricted",
+    "-p",
+    "--output-format",
+    "json",
+    "--no-session-persistence",
+    "--tools",
+    "",
+    "--disallowedTools",
+    "mcp__*"
+];
 export const claudeAdapter = {
     id: "claude",
     displayName: "Claude",
@@ -21,17 +35,46 @@ export const claudeAdapter = {
         return check.ok;
     },
     buildCommand(request) {
+        if (request.promptTransport === "stdin" && request.commandTemplate) {
+            throw new Error("claude agent: stdin prompt transport cannot be combined with a command template.");
+        }
         if (request.commandTemplate) {
             return applyPromptToCommandTemplate(request.commandTemplate, request.promptText);
         }
+        if (request.promptTransport === "stdin") {
+            return { command: "claude", args: [...CLAUDE_STDIN_ARGS], stdinText: request.promptText };
+        }
         return { command: "claude", args: ["-p", request.promptText] };
     },
     async runPrompt(request) {
         return runCliAgent(request, this);
     },
     parseTokenUsage: parseAgentTokenUsage,
-    parseFinalAnswer(text) {
-        const trimmed = text.trim();
-        return { finalAnswerText: trimmed, finalAnswerParseStatus: trimmed ? "parsed" : "empty" };
-    }
+    parseFinalAnswer: parseClaudeFinalAnswer
 };
+/**
+ * Parses a single JSON result envelope (`{ "result": "..." }`) when stdout is valid JSON, never
+ * the raw envelope itself. Falls back to the legacy plain-text behavior when stdout is not valid
+ * JSON, so existing argv-mode text output keeps working unchanged.
+ */
+export function parseClaudeFinalAnswer(text) {
+    const trimmedInput = text.trim();
+    if (trimmedInput) {
+        try {
+            const parsed = JSON.parse(trimmedInput);
+            if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                const payload = parsed;
+                if (typeof payload.result === "string") {
+                    const resultText = payload.result.trim();
+                    return { finalAnswerText: resultText, finalAnswerParseStatus: resultText ? "parsed" : "empty" };
+                }
+                // Valid JSON object without a string result: empty, never the raw envelope.
+                return { finalAnswerText: "", finalAnswerParseStatus: "empty" };
+            }
+        }
+        catch {
+            // Not valid JSON; fall through to the legacy plain-text behavior below.
+        }
+    }
+    return { finalAnswerText: trimmedInput, finalAnswerParseStatus: trimmedInput ? "parsed" : "empty" };
+}

package/dist/src/agents/adapters/codexAdapter.js

@@ -1,6 +1,17 @@
 import { runMeasuredCommand } from "../../core/runMeasuredCommand.js";
 import { applyPromptToCommandTemplate } from "../runAgentPrompt.js";
 import { parseAgentTokenUsage } from "../parseAgentTokenUsage.js";
+// v0.5.2 Batch 2 -- frozen stdin invocation for the real-agent evaluation transport. Every flag
+// here is planner-owned; do not add sandbox/model/approval-policy flags in this batch.
+const CODEX_STDIN_ARGS = [
+    "exec",
+    "--json",
+    "--ephemeral",
+    "--skip-git-repo-check",
+    "--ignore-user-config",
+    "--ignore-rules",
+    "-"
+];
 export const codexAdapter = {
     id: "codex",
     displayName: "Codex",
@@ -20,20 +31,67 @@ export const codexAdapter = {
         return check.ok;
     },
     buildCommand(request) {
+        if (request.promptTransport === "stdin" && request.commandTemplate) {
+            throw new Error("codex agent: stdin prompt transport cannot be combined with a command template.");
+        }
         if (request.commandTemplate) {
             return applyPromptToCommandTemplate(request.commandTemplate, request.promptText);
         }
+        if (request.promptTransport === "stdin") {
+            return { command: "codex", args: [...CODEX_STDIN_ARGS], stdinText: request.promptText };
+        }
         return { command: "codex", args: ["exec", "--json", request.promptText] };
     },
     async runPrompt(request) {
         return runCliAgent(request, this);
     },
     parseTokenUsage: parseAgentTokenUsage,
-    parseFinalAnswer(text) {
-        const trimmed = text.trim();
-        return { finalAnswerText: trimmed, finalAnswerParseStatus: trimmed ? "parsed" : "empty" };
-    }
+    parseFinalAnswer: parseCodexFinalAnswer
 };
+/**
+ * Recognizes a Codex JSONL event stream (at least one line parses to an object with a string
+ * `type`) and, when recognized, uses the LAST `item.completed` `agent_message` text as the final
+ * answer -- never the raw JSONL. Falls back to the legacy plain-text behavior when no event-shaped
+ * line is found, so non-JSONL Codex output (and existing tests) keep working unchanged.
+ */
+export function parseCodexFinalAnswer(text) {
+    let sawEventLine = false;
+    let lastAgentMessageText = null;
+    for (const line of text.split(/\r?\n/)) {
+        const trimmedLine = line.trim();
+        if (!trimmedLine)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmedLine);
+        }
+        catch {
+            // Agent output can mix JSONL with incidental non-JSON noise; ignore malformed lines.
+            continue;
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            continue;
+        const event = parsed;
+        if (typeof event.type !== "string")
+            continue;
+        sawEventLine = true;
+        if (event.type === "item.completed") {
+            const item = event.item;
+            if (item && typeof item === "object" && item.type === "agent_message") {
+                const itemText = item.text;
+                if (typeof itemText === "string") {
+                    lastAgentMessageText = itemText;
+                }
+            }
+        }
+    }
+    if (sawEventLine) {
+        const finalAnswerText = lastAgentMessageText ?? "";
+        return { finalAnswerText, finalAnswerParseStatus: finalAnswerText ? "parsed" : "empty" };
+    }
+    const trimmed = text.trim();
+    return { finalAnswerText: trimmed, finalAnswerParseStatus: trimmed ? "parsed" : "empty" };
+}
 export async function runCliAgent(request, adapter) {
     const started = Date.now();
     const command = adapter.buildCommand(request);
@@ -74,7 +132,8 @@ export async function runCliAgent(request, adapter) {
         cwd: request.commandTemplate?.cwd ?? request.cwd,
         outDir: request.outDir,
         env: request.env,
-        timeoutMs: request.timeoutMs
+        timeoutMs: request.timeoutMs,
+        stdinText: command.stdinText
     });
     const ended = Date.now();
     const combinedOutput = `${measured.stdout}\n${measured.stderr}`;

package/dist/src/cli/help.js

@@ -157,8 +157,29 @@ export function renderExperimentRunHelp() {
         "  --kit-command <command>                            my-dev-kit command used to build one index per benchmark",
         "                                                      project and retrieve per task",
         "                                                      (default: npx @dailephd/my-dev-kit@latest)",
-        "                                                      Agent evidence uses the deterministic fake agent only;",
+        "                                                      Legacy/default mode uses the deterministic fake agent only;",
         "                                                      agent options below are not accepted by this plugin.",
+        "  --campaign <preset>                                 Runs the selected real-agent campaign preset: codex-full,",
+        "                                                      claude-full, codex-timeout-isolation. Selects Codex or",
+        "                                                      Claude as the preset's single provider and requires",
+        "                                                      --include-real-agents. The preset owns the bundled",
+        "                                                      production corpus and project profiles; explicit",
+        "                                                      --cases/--project-profiles and --target are rejected in",
+        "                                                      campaign mode. --case and --benchmark-project narrow the",
+        "                                                      preset's case set. --kit-command and --timeout-ms are",
+        "                                                      accepted. The report distinguishes warm-index",
+        "                                                      infrastructure status from agent/provider outcome status;",
+        "                                                      provider token telemetry may be unavailable and is never",
+        "                                                      replaced by a context-size estimate. A campaign run",
+        "                                                      automatically produces the report JSON/text/HTML, the",
+        "                                                      four warm-index SVG plots, a best-effort report PNG",
+        "                                                      screenshot, and a gallery manifest/index. A missing",
+        "                                                      Playwright/browser runtime makes screenshot capture skip",
+        "                                                      without invalidating the campaign; an unexpected",
+        "                                                      screenshot failure makes the command unsuccessful after",
+        "                                                      preserving the report, plots, and gallery. Legacy",
+        "                                                      non-campaign warm-index runs retain their existing",
+        "                                                      report-only behavior.",
         "",
         "context-strategy-comparison only:",
         "  --agents <list>                                    Comma-separated agent ids (default: fake-agent)",

package/dist/src/commands/runExperimentDescribeCommand.js

@@ -145,11 +145,16 @@ function describeExamples(plugin) {
     // Only advertise agent-matrix options for plugins that declare them.
     const agentOptions = hasConfigField(plugin, "agents") ? " --agents fake-agent --complexities short" : "";
     const screenshotOption = hasConfigField(plugin, "agents") ? " --no-screenshot" : "";
-    return [
+    const examples = [
         `my-dev-kit-lab experiment describe --experiment ${plugin.metadata.id}`,
         `my-dev-kit-lab experiment run --experiment ${plugin.metadata.id}${agentOptions}`,
         `my-dev-kit-lab experiment run --experiment ${plugin.metadata.id} --target "Z:\\Users\\newuser\\Projects\\my-dev-kit-v1"${agentOptions}${screenshotOption}`
     ];
+    // Only advertise campaign examples for plugins that declare the campaignPreset config field.
+    if (hasConfigField(plugin, "campaignPreset")) {
+        examples.push(`my-dev-kit-lab experiment run --experiment ${plugin.metadata.id} --campaign codex-full --include-real-agents --out <dir>`, `my-dev-kit-lab experiment run --experiment ${plugin.metadata.id} --campaign claude-full --include-real-agents --case warm-medium-complete-idempotent --out <dir>`);
+    }
+    return examples;
 }
 function hasConfigField(plugin, name) {
     return (plugin.configDefinition?.fields ?? []).some((field) => field.name === name);

package/dist/src/commands/runExperimentRunCommand.js

@@ -2,11 +2,12 @@ import path from "node:path";
 import { parseAgentCommandTemplate } from "../agents/index.js";
 import { parseAgentId } from "../agents/agentRegistry.js";
 import { readBenchmarkProjectProfiles, readEvaluationCases } from "../evaluation/index.js";
-import { contextStrategyComparisonPlugin, createDefaultExperimentPluginRegistry, resolveExperimentTarget, runExperiment, warmIndexReusePlugin } from "../experiments/index.js";
+import { contextStrategyComparisonPlugin, createDefaultExperimentPluginRegistry, getWarmIndexCampaignPreset, parseWarmIndexCampaignPresetId, resolveExperimentTarget, runExperiment, warmIndexReusePlugin } from "../experiments/index.js";
 import { buildDefaultExperimentOutputRoot } from "../experiments/outputPaths.js";
 import { parsePromptComplexityLevel, parsePromptStrategy } from "../prompts/index.js";
 import { writePluginExperimentReports } from "../report/index.js";
 import { createLabExecutionContext, resolvePackageResource } from "../runtime/index.js";
+import { runWarmIndexCampaignPresentation } from "./runWarmIndexCampaignPresentation.js";
 // ---------------------------------------------------------------------------
 // v0.4.6 Batch 4 -- reusable experiment-run command owner.
 //
@@ -61,7 +62,7 @@ export async function runExperimentRunCommandFromArgs(argv, options = {}) {
             plugin: registry.describe(result.pluginId),
             outputRoot: String(result.metadata?.outputRoot ?? "")
         });
-        console.log([
+        const outputLines = [
             `Experiment: ${result.pluginId}`,
             `Run ID: ${result.runId}`,
             `Status: ${result.status}`,
@@ -71,8 +72,51 @@ export async function runExperimentRunCommandFromArgs(argv, options = {}) {
             `Output: ${String(result.metadata?.outputRoot ?? "")}`,
             `Report JSON: ${reports.outputPaths.jsonPath}`,
             `Report HTML: ${reports.outputPaths.htmlPath}`
-        ].join("\n"));
-        return result.status === "failed" ? 1 : 0;
+        ];
+        // Automatic presentation (report already produced above) applies only to warm-index-reuse
+        // campaign runs; legacy fake-agent warm-index runs and context-strategy-comparison stay
+        // report-only, unchanged.
+        let screenshotFailed = false;
+        if (args.experimentId === warmIndexReusePlugin.metadata.id && args.config.campaignPreset) {
+            const executionArtifactPath = readMetadataString(result.metadata?.executionArtifactPath);
+            const campaignAgentId = readMetadataString(result.metadata?.campaignAgentId);
+            if (!executionArtifactPath) {
+                throw new Error("Warm-index campaign presentation requires an execution artifact path on the completed run.");
+            }
+            if (campaignAgentId !== "codex" && campaignAgentId !== "claude") {
+                throw new Error(`Warm-index campaign presentation requires a codex or claude campaign agent id on the completed run; received ${String(campaignAgentId)}.`);
+            }
+            const presentation = await runWarmIndexCampaignPresentation({
+                outputRoot: String(result.metadata?.outputRoot ?? ""),
+                reportPaths: reports.outputPaths,
+                executionArtifactPath,
+                campaignPreset: args.config.campaignPreset,
+                agentId: campaignAgentId,
+                captureScreenshot: options.presentation?.captureScreenshot
+            });
+            outputLines.push(`Plots: ${presentation.plots.artifactPaths.summaryPath}`);
+            if (presentation.screenshot.status === "captured") {
+                outputLines.push(`Screenshot: ${presentation.screenshot.pngPath}`);
+            }
+            else if (presentation.screenshot.status === "skipped") {
+                outputLines.push("Screenshot: skipped");
+                if (presentation.screenshot.warning)
+                    outputLines.push(presentation.screenshot.warning);
+            }
+            else {
+                outputLines.push("Screenshot: failed");
+                outputLines.push(presentation.screenshot.error ?? "Screenshot capture failed.");
+                screenshotFailed = true;
+            }
+            outputLines.push(`Gallery manifest: ${presentation.gallery.manifestPath}`);
+            outputLines.push(`Gallery index: ${presentation.gallery.indexPath}`);
+        }
+        console.log(outputLines.join("\n"));
+        if (result.status === "failed")
+            return 1;
+        if (screenshotFailed)
+            return 1;
+        return 0;
     }
     catch (error) {
         if (process.env.DEBUG) {
@@ -101,6 +145,7 @@ export function parseRunExperimentArgs(argv) {
     let requireAgents;
     let includeRealAgents;
     let kitCommand;
+    let campaignPreset;
     const commandTemplates = {};
     for (let index = 0; index < argv.length; index += 1) {
         const arg = argv[index];
@@ -161,6 +206,9 @@ export function parseRunExperimentArgs(argv) {
         else if (arg === "--kit-command") {
             kitCommand = readRequiredValue(argv, ++index, "--kit-command");
         }
+        else if (arg === "--campaign") {
+            campaignPreset = parseWarmIndexCampaignPresetId(readRequiredValue(argv, ++index, "--campaign"));
+        }
         else if (arg === "--no-screenshot") {
             // The plugin-aware report path does not capture screenshots yet; accept this
             // flag so smoke commands can share the legacy demo option set.
@@ -175,6 +223,20 @@ export function parseRunExperimentArgs(argv) {
     if (kitCommand !== undefined && experimentId !== warmIndexReusePlugin.metadata.id) {
         throw new Error(`--kit-command is only supported for --experiment ${warmIndexReusePlugin.metadata.id}.`);
     }
+    if (campaignPreset !== undefined) {
+        if (experimentId !== warmIndexReusePlugin.metadata.id) {
+            throw new Error(`--campaign is only supported for --experiment ${warmIndexReusePlugin.metadata.id}.`);
+        }
+        if (targetPath !== undefined) {
+            throw new Error("--campaign cannot be combined with --target; campaigns run only against bundled synthetic benchmark projects.");
+        }
+        if (casesPath !== undefined) {
+            throw new Error("--campaign cannot be combined with --cases; the selected preset owns the production corpus.");
+        }
+        if (projectProfilesPath !== undefined) {
+            throw new Error("--campaign cannot be combined with --project-profiles; the selected preset owns the project profiles.");
+        }
+    }
     return {
         experimentId,
         targetPath,
@@ -193,7 +255,8 @@ export function parseRunExperimentArgs(argv) {
             requireAgents,
             includeRealAgents,
             commandTemplates: Object.keys(commandTemplates).length > 0 ? commandTemplates : undefined,
-            kitCommand
+            kitCommand,
+            campaignPreset
         })
     };
 }
@@ -232,6 +295,9 @@ async function loadPluginInputs(args, toolRoot, context) {
         if (!validation.valid || !validation.config) {
             throw new Error(`Invalid warm index reuse config: ${validation.errors.join("; ")}`);
         }
+        if (args.config.campaignPreset) {
+            return loadCampaignCasesAndProjectProfiles(args.config.campaignPreset, toolRoot, context);
+        }
         return loadCasesAndProjectProfiles(args, toolRoot, context);
     }
     return undefined;
@@ -252,6 +318,19 @@ async function loadCasesAndProjectProfiles(args, toolRoot, context) {
     });
     return { cases, projectProfiles, env: process.env };
 }
+// Campaign resource resolution (v0.5.2 Batch 1): the preset owns both bundled resource paths;
+// explicit --cases/--project-profiles are already rejected for campaign mode by argument parsing.
+async function loadCampaignCasesAndProjectProfiles(campaignPresetId, toolRoot, context) {
+    const preset = getWarmIndexCampaignPreset(campaignPresetId);
+    const projectProfilesPath = resolvePackageResource(context, preset.projectProfilesResourcePath);
+    const casesPath = resolvePackageResource(context, preset.casesResourcePath);
+    const projectProfiles = await readBenchmarkProjectProfiles(projectProfilesPath, toolRoot);
+    const cases = await readEvaluationCases(casesPath, toolRoot, {
+        projectProfiles,
+        requireProjectProfileRef: true
+    });
+    return { cases, projectProfiles, env: process.env };
+}
 function splitList(value) {
     return value
         .split(",")
@@ -272,6 +351,9 @@ function parsePositiveInteger(label, value) {
     }
     return parsed;
 }
+function readMetadataString(value) {
+    return typeof value === "string" && value.trim() ? value : undefined;
+}
 function withoutUndefined(value) {
     return Object.fromEntries(Object.entries(value).filter(([, entryValue]) => entryValue !== undefined));
 }

package/dist/src/commands/runWarmIndexCampaignPresentation.js

@@ -0,0 +1,64 @@
+import path from "node:path";
+import { writeWarmIndexCampaignGallery } from "../gallery/writeWarmIndexCampaignGallery.js";
+import { captureReportScreenshot } from "../screenshot/captureReportScreenshot.js";
+import { writePlotArtifacts } from "../plots/writePlotArtifacts.js";
+// ---------------------------------------------------------------------------
+// v0.5.2 Batch 5 -- command-level warm-index campaign presentation owner.
+//
+// This is the single orchestrator for: existing report -> existing four warm-
+// index plots -> best-effort report screenshot -> narrow warm-index campaign
+// gallery. It reuses writePlotArtifacts, captureReportScreenshot, and
+// writeWarmIndexCampaignGallery unchanged; it builds no new plot, screenshot,
+// or gallery mechanism of its own. The warm-index-reuse plugin remains free of
+// this orchestration -- it is invoked only by the command layer, and only for
+// campaign runs.
+// ---------------------------------------------------------------------------
+const EXPECTED_WARM_INDEX_CHART_IDS = [
+    "warm-index-amortized-index-cost",
+    "warm-index-context-size",
+    "warm-index-correctness",
+    "warm-index-cumulative-token-usage",
+];
+export async function runWarmIndexCampaignPresentation(args) {
+    const plotsDir = path.join(args.outputRoot, "plots");
+    const plots = await writePlotArtifacts({ experimentDir: args.outputRoot, outDir: plotsDir });
+    const chartIds = Object.keys(plots.artifactPaths.charts);
+    const hasExactlyExpectedCharts = chartIds.length === EXPECTED_WARM_INDEX_CHART_IDS.length &&
+        EXPECTED_WARM_INDEX_CHART_IDS.every((id) => chartIds.includes(id));
+    if (!hasExactlyExpectedCharts) {
+        throw new Error(`Warm-index campaign presentation requires exactly the four warm-index plot charts (${EXPECTED_WARM_INDEX_CHART_IDS.join(", ")}); got: ${chartIds.join(", ") || "none"}.`);
+    }
+    const capture = args.captureScreenshot ?? captureReportScreenshot;
+    const pngPath = path.join(args.outputRoot, "report.png");
+    // Non-fatal by design: a missing Playwright/browser runtime is a normal, expected environment,
+    // never a reason to fail the campaign (see captureReportScreenshot's captured/skipped/failed contract).
+    const screenshot = await capture(args.reportPaths.htmlPath, pngPath);
+    const gallery = await writeWarmIndexCampaignGallery({
+        outDir: path.join(args.outputRoot, "gallery"),
+        campaignOutputRoot: args.outputRoot,
+        reportPaths: {
+            jsonPath: args.reportPaths.jsonPath,
+            htmlPath: args.reportPaths.htmlPath,
+            textPath: args.reportPaths.textPath,
+        },
+        executionArtifactPath: args.executionArtifactPath,
+        plotArtifacts: plots,
+        screenshot,
+        campaignPreset: args.campaignPreset,
+        agentId: args.agentId,
+    });
+    const warnings = [];
+    if (screenshot.status === "skipped" && screenshot.warning) {
+        warnings.push(screenshot.warning);
+    }
+    else if (screenshot.status === "failed") {
+        warnings.push(`Report screenshot capture failed: ${screenshot.error ?? "unknown error"}.`);
+    }
+    warnings.push(...plots.summary.warnings);
+    return {
+        plots,
+        screenshot,
+        gallery: { manifest: gallery.manifest, manifestPath: gallery.manifestPath, indexPath: gallery.indexPath },
+        warnings,
+    };
+}

package/dist/src/core/runMeasuredCommand.js

@@ -41,13 +41,15 @@ export async function runMeasuredCommand(options) {
         let spawnError;
         let timedOut = false;
         let timeout;
+        let killGraceTimeout;
+        let settled = false;
         let child;
         try {
             child = spawn(executable, args, {
                 cwd: options.cwd,
                 env: { ...process.env, ...options.env },
                 shell: false,
-                stdio: ["ignore", "pipe", "pipe"]
+                stdio: options.stdinText !== undefined ? ["pipe", "pipe", "pipe"] : ["ignore", "pipe", "pipe"]
             });
         }
         catch (error) {
@@ -80,6 +82,7 @@ export async function runMeasuredCommand(options) {
             ]).then(() => resolve(measured));
             return;
         }
+        // stdout/stderr are always piped in both stdio branches above.
         child.stdout.on("data", (chunk) => {
             stdout += String(chunk);
         });
@@ -89,17 +92,40 @@ export async function runMeasuredCommand(options) {
         child.on("error", (error) => {
             spawnError = error.message;
         });
-        if (options.timeoutMs !== undefined) {
-            timeout = setTimeout(() => {
-                timedOut = true;
-                spawnError = `Command timed out after ${options.timeoutMs}ms.`;
-                forceTerminateProcess(child.pid);
-            }, options.timeoutMs);
+        if (options.stdinText !== undefined) {
+            // A child that exits or closes stdin before we write must not crash the process (EPIPE).
+            child.stdin?.on("error", (error) => {
+                spawnError = spawnError ?? `Failed to write to command stdin: ${error.message}`;
+            });
+            child.stdin?.write(options.stdinText, "utf8");
+            child.stdin?.end();
         }
-        child.on("close", async (exitCode) => {
-            if (timeout) {
+        // forceTerminateProcess is fire-and-forget (it never confirms the target process tree actually
+        // exited: on Windows it spawns a detached `taskkill /T /F` and does not await or check its
+        // result). That is normally sufficient, but a grandchild process spawned through an
+        // intermediate shim (for example a Windows .cmd launcher) can occasionally outlive an
+        // already-killed intermediate process. Without a bounded fallback, a caller whose kill silently
+        // failed would await this promise forever instead of receiving the already-known timeout error.
+        const KILL_GRACE_MS = 3000;
+        const settle = async (exitCode) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timeout)
                 clearTimeout(timeout);
-            }
+            if (killGraceTimeout)
+                clearTimeout(killGraceTimeout);
+            // The caller's `scripts/cli.ts` entry point sets `process.exitCode` rather than calling
+            // `process.exit()`, so the process only exits once Node's event loop actually drains. A
+            // still-open child stdio pipe -- the same situation the kill-grace fallback above exists for
+            // -- would otherwise keep this process alive forever even though this promise has already
+            // resolved. Detaching is safe to do unconditionally: once "close" has fired the streams are
+            // already ended, so this is a harmless no-op on the normal (non-fallback) path.
+            child.stdout?.destroy();
+            child.stderr?.destroy();
+            child.stdin?.destroy();
+            child.removeAllListeners();
+            child.unref();
             const endedAt = new Date().toISOString();
             const durationMs = Date.now() - started;
             await writeArtifact(stdoutPath, stdout);
@@ -125,6 +151,19 @@ export async function runMeasuredCommand(options) {
             };
             await writeArtifact(telemetryPath, JSON.stringify(measured, null, 2));
             resolve(measured);
+        };
+        if (options.timeoutMs !== undefined) {
+            timeout = setTimeout(() => {
+                timedOut = true;
+                spawnError = `Command timed out after ${options.timeoutMs}ms.`;
+                forceTerminateProcess(child.pid);
+                killGraceTimeout = setTimeout(() => {
+                    void settle(null);
+                }, KILL_GRACE_MS);
+            }, options.timeoutMs);
+        }
+        child.on("close", (exitCode) => {
+            void settle(exitCode);
         });
     });
     return result;