@golba98/codexa 1.0.1

package/src/core/planStorage.test.ts

@@ -0,0 +1,143 @@
+import assert from "node:assert/strict";
+import test, { afterEach, beforeEach, describe } from "node:test";
+import { existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { resolvePlanDir, savePlan, readPlan } from "./planStorage.js";
+
+describe("resolvePlanDir", () => {
+  const savedEnv: Record<string, string | undefined> = {};
+  const envKeys = ["CODEXA_PLAN_DIR", "LOCALAPPDATA", "APPDATA", "XDG_DATA_HOME"];
+
+  beforeEach(() => {
+    for (const key of envKeys) {
+      savedEnv[key] = process.env[key];
+    }
+  });
+
+  afterEach(() => {
+    for (const key of envKeys) {
+      if (savedEnv[key] === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = savedEnv[key];
+      }
+    }
+  });
+
+  test("CODEXA_PLAN_DIR override takes priority", () => {
+    process.env["CODEXA_PLAN_DIR"] = "/custom/plan/dir";
+    assert.equal(resolvePlanDir(), "/custom/plan/dir");
+  });
+
+  test("Windows LOCALAPPDATA path resolution", () => {
+    delete process.env["CODEXA_PLAN_DIR"];
+    process.env["LOCALAPPDATA"] = "C:\\Users\\test\\AppData\\Local";
+    const result = resolvePlanDir("win32");
+    assert.ok(result.includes("Codexa"));
+    assert.ok(result.includes("plans"));
+    assert.ok(result.includes("AppData"));
+  });
+
+  test("Windows APPDATA fallback", () => {
+    delete process.env["CODEXA_PLAN_DIR"];
+    delete process.env["LOCALAPPDATA"];
+    process.env["APPDATA"] = "C:\\Users\\test\\AppData\\Roaming";
+    const result = resolvePlanDir("win32");
+    assert.ok(result.includes("Codexa"));
+    assert.ok(result.includes("plans"));
+    assert.ok(result.includes("Roaming"));
+  });
+
+  test("macOS path", () => {
+    delete process.env["CODEXA_PLAN_DIR"];
+    const result = resolvePlanDir("darwin");
+    assert.ok(result.includes("Library"));
+    assert.ok(result.includes("Codexa"));
+    assert.ok(result.includes("plans"));
+  });
+
+  test("Linux default path", () => {
+    delete process.env["CODEXA_PLAN_DIR"];
+    delete process.env["XDG_DATA_HOME"];
+    const result = resolvePlanDir("linux");
+    assert.ok(result.includes(".local"));
+    assert.ok(result.includes("share"));
+    assert.ok(result.includes("codexa"));
+    assert.ok(result.includes("plans"));
+  });
+
+  test("Linux XDG_DATA_HOME override", () => {
+    delete process.env["CODEXA_PLAN_DIR"];
+    process.env["XDG_DATA_HOME"] = "/custom/xdg/data";
+    const result = resolvePlanDir("linux");
+    assert.ok(result.includes("custom"));
+    assert.ok(result.includes("xdg"));
+    assert.ok(result.includes("codexa"));
+    assert.ok(result.includes("plans"));
+  });
+});
+
+describe("savePlan", () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = join(tmpdir(), `planStorage-test-${Date.now()}`);
+    mkdirSync(tempDir, { recursive: true });
+    process.env["CODEXA_PLAN_DIR"] = tempDir;
+  });
+
+  afterEach(() => {
+    delete process.env["CODEXA_PLAN_DIR"];
+    rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  test("safe filename format with timestamp and 8-hex-char hash", () => {
+    const result = savePlan("# My Plan", "/some/workspace");
+    assert.notEqual(result, null);
+    const filename = result!.split(/[/\\]/).pop()!;
+    assert.match(filename, /^plan-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}.*-[0-9a-f]{8}\.md$/);
+  });
+
+  test("written content can be read back", () => {
+    const content = "# Test Plan\n\n- Step 1\n- Step 2\n";
+    const result = savePlan(content, "/workspace");
+    assert.notEqual(result, null);
+    assert.ok(existsSync(result!));
+    assert.equal(readPlan(result!), content);
+  });
+
+  test("write failure returns null", () => {
+    process.env["CODEXA_PLAN_DIR"] = "/nonexistent\x00/bad/path";
+    const result = savePlan("content", "/workspace");
+    assert.equal(result, null);
+  });
+
+  test("does not write to process.cwd()", () => {
+    const cwdPlanDir = join(process.cwd(), ".codexa");
+    const beforeMarkdown = existsSync(cwdPlanDir)
+      ? readdirSync(cwdPlanDir).filter((name) => name.endsWith(".md")).sort()
+      : [];
+    savePlan("# Plan", process.cwd());
+    const afterMarkdown = existsSync(cwdPlanDir)
+      ? readdirSync(cwdPlanDir).filter((name) => name.endsWith(".md")).sort()
+      : [];
+    assert.deepEqual(afterMarkdown, beforeMarkdown);
+  });
+});
+
+describe("readPlan", () => {
+  test("returns null for missing file", () => {
+    assert.equal(readPlan("/nonexistent/file.md"), null);
+  });
+
+  test("reads existing file content", () => {
+    const tempFile = join(tmpdir(), `plan-read-test-${Date.now()}.md`);
+    writeFileSync(tempFile, "hello plan", "utf-8");
+    try {
+      assert.equal(readPlan(tempFile), "hello plan");
+    } finally {
+      rmSync(tempFile, { force: true });
+    }
+  });
+});

package/src/core/planStorage.ts

@@ -0,0 +1,141 @@
+import { createHash } from "crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import { isNoiseLine } from "./providers/codexTranscript.js";
+import { sanitizeTerminalOutput } from "./terminal/terminalSanitize.js";
+
+type Platform = "win32" | "darwin" | "linux" | string;
+
+const SECTION_LINE_RE = /^\s*(?:#{1,3}\s+)?(?:\*\*)?([A-Za-z][A-Za-z0-9 /&-]{0,48})(?:\*\*)?:?\s*$/;
+const ABSOLUTE_WINDOWS_PATH_RE = /[A-Za-z]:[\\/][^\s`),;\]]+/g;
+
+function normalizePathSeparators(value: string): string {
+  return value.replace(/\\/g, "/");
+}
+
+function replaceAllLiteral(value: string, search: string, replacement: string): string {
+  if (!search) return value;
+  return value.split(search).join(replacement);
+}
+
+/**
+ * Strips absolute filesystem paths from plan text, replacing them with
+ * relative paths or truncated versions to protect user privacy.
+ */
+export function hidePlanReviewFilesystemDetails(planText: string, workspaceRoot?: string | null): string {
+  let output = planText;
+  const normalizedRoot = workspaceRoot?.trim() ? normalizePathSeparators(workspaceRoot.trim()).replace(/\/+$/, "") : "";
+
+  if (normalizedRoot) {
+    output = replaceAllLiteral(output, workspaceRoot!.replace(/\\+$/, ""), "");
+    output = replaceAllLiteral(normalizePathSeparators(output), normalizedRoot, "");
+    output = output.replace(/(^|[\s(`])\/+([A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)+)/g, "$1$2");
+  }
+
+  return output.replace(ABSOLUTE_WINDOWS_PATH_RE, (match) => {
+    const normalized = normalizePathSeparators(match);
+    const srcIndex = normalized.search(/(?:^|\/)(src|test|tests|docs|scripts|bin)\//);
+    if (srcIndex >= 0) {
+      return normalized.slice(normalized[srcIndex] === "/" ? srcIndex + 1 : srcIndex);
+    }
+    const parts = normalized.split("/").filter(Boolean);
+    return parts.slice(-2).join("/") || match;
+  });
+}
+
+/**
+ * Normalizes plan markdown for consistent rendering, converting bold labels
+ * into proper headings and hiding filesystem details.
+ */
+export function normalizePlanReviewMarkdown(planText: string, workspaceRoot?: string | null): string {
+  const sanitized = sanitizeTerminalOutput(hidePlanReviewFilesystemDetails(planText, workspaceRoot), {
+    preserveTabs: false,
+    tabSize: 2,
+  })
+    .replace(/\r\n/g, "\n")
+    .replace(/\r/g, "\n")
+    .replace(/\n{4,}/g, "\n\n\n")
+    .split("\n")
+    .filter((line) => !isNoiseLine(line))
+    .join("\n");
+
+  return sanitized
+    .split("\n")
+    .map((line) => {
+      const trimmed = line.trim();
+      const sectionMatch = SECTION_LINE_RE.exec(trimmed);
+      if (sectionMatch && !/^[-*]\s+/.test(trimmed) && !/^\d+\.\s+/.test(trimmed)) {
+        return `## ${sectionMatch[1]!.trim()}`;
+      }
+      return line;
+    })
+    .join("\n");
+}
+
+/**
+ * Resolve the directory where plan files are stored.
+ * Uses platform-appropriate app-data locations instead of the workspace.
+ */
+export function resolvePlanDir(platformOverride?: Platform): string {
+  const envDir = process.env["CODEXA_PLAN_DIR"];
+  if (envDir) return envDir;
+
+  const platform = platformOverride ?? process.platform;
+
+  if (platform === "win32") {
+    const localAppData = process.env["LOCALAPPDATA"];
+    if (localAppData) return join(localAppData, "Codexa", "plans");
+    const appData = process.env["APPDATA"];
+    if (appData) return join(appData, "Codexa", "plans");
+    return join(homedir(), "AppData", "Local", "Codexa", "plans");
+  }
+
+  if (platform === "darwin") {
+    return join(homedir(), "Library", "Application Support", "Codexa", "plans");
+  }
+
+  // Linux and other Unix-like
+  const xdgDataHome = process.env["XDG_DATA_HOME"];
+  if (xdgDataHome) return join(xdgDataHome, "codexa", "plans");
+  return join(homedir(), ".local", "share", "codexa", "plans");
+}
+
+// SHA-256 of the workspace path ensures filename uniqueness across projects with the same name.
+function workspaceHash(workspaceRoot: string): string {
+  return createHash("sha256").update(workspaceRoot).digest("hex").slice(0, 8);
+}
+
+function safeTimestamp(): string {
+  return new Date().toISOString().replace(/[:.]/g, "-");
+}
+
+/**
+ * Save plan content to the app-data plan directory.
+ * Returns the written file path, or null on failure.
+ */
+export function savePlan(content: string, workspaceRoot: string): string | null {
+  try {
+    const dir = resolvePlanDir();
+    mkdirSync(dir, { recursive: true });
+    const filename = `plan-${safeTimestamp()}-${workspaceHash(workspaceRoot)}.md`;
+    const filePath = join(dir, filename);
+    writeFileSync(filePath, content, "utf-8");
+    return filePath;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read plan content from a file path.
+ * Returns the content string, or null on failure.
+ */
+export function readPlan(filePath: string): string | null {
+  try {
+    if (!existsSync(filePath)) return null;
+    return readFileSync(filePath, "utf-8");
+  } catch {
+    return null;
+  }
+}

package/src/core/process/CommandRunner.test.ts

@@ -0,0 +1,105 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import test from "node:test";
+import { runCommand, runShellCommand, summarizeCommandResult, type CommandResult } from "./CommandRunner.js";
+
+function makeResult(overrides: Partial<CommandResult> = {}): CommandResult {
+  return {
+    status: "completed",
+    exitCode: 0,
+    signal: null,
+    stdout: "",
+    stderr: "",
+    startedAt: 1,
+    endedAt: 2,
+    durationMs: 1,
+    userMessage: "Command completed.",
+    ...overrides,
+  };
+}
+
+test("summarizes ripgrep file listings without flooding the UI", () => {
+  const result = makeResult({
+    stdout: "src/app.tsx\nsrc/ui/BottomComposer.tsx\n",
+  });
+
+  assert.equal(summarizeCommandResult("rg --files", result), "Found 2 files.");
+});
+
+test("keeps a concise fallback summary for generic successful commands", () => {
+  const result = makeResult({
+    stdout: "alpha\nbeta\ngamma\n",
+  });
+
+  assert.equal(summarizeCommandResult("node script.js", result), "Produced 3 lines of output.");
+});
+
+test("preserves the failure message for unsuccessful commands", () => {
+  const result = makeResult({
+    status: "failed",
+    exitCode: 1,
+    userMessage: "git exited with code 1.",
+    stderr: "fatal: not a git repository",
+  });
+
+  assert.equal(summarizeCommandResult("git status", result), "git exited with code 1.");
+});
+
+test("runCommand executes a direct executable with argument array", async () => {
+  const runner = runCommand({
+    executable: process.execPath,
+    args: ["-e", "console.log(process.argv[1])", "direct-ok"],
+    cwd: process.cwd(),
+  });
+
+  const result = await runner.result;
+  assert.equal(result.status, "completed");
+  assert.equal(result.exitCode, 0);
+  assert.equal(result.stdout.trim(), "direct-ok");
+});
+
+test("runCommand rejects obvious executable injection", () => {
+  assert.throws(
+    () => runCommand({
+      executable: "node & echo injected",
+      args: ["--version"],
+      cwd: process.cwd(),
+    }),
+    /single executable name|shell metacharacters/i,
+  );
+});
+
+test("runShellCommand is the explicit shell execution path", async () => {
+  const runner = runShellCommand("echo shell-ok", { cwd: process.cwd() });
+  const result = await runner.result;
+
+  assert.equal(result.status, "completed");
+  assert.equal(result.exitCode, 0);
+  assert.match(result.stdout, /shell-ok/);
+});
+
+test("command runner reports lifecycle boundaries for terminal title reassertion", () => {
+  const source = readFileSync(fileURLToPath(new URL("./CommandRunner.ts", import.meta.url)), "utf8");
+  const beforeSpawnIndex = source.indexOf('handlers.onProcessLifecycle?.("before-spawn")');
+  const spawnIndex = source.indexOf("child = spawn(");
+  const spawnedIndex = source.indexOf('handlers.onProcessLifecycle?.("spawned")', spawnIndex);
+  const errorIndex = source.indexOf('child.once("error"', spawnIndex);
+  const lifecycleErrorIndex = source.indexOf('handlers.onProcessLifecycle?.("error")', errorIndex);
+  const closeIndex = source.indexOf('child.once("close"', spawnIndex);
+  const exitIndex = source.indexOf('handlers.onProcessLifecycle?.("exit")', closeIndex);
+  const cancelIndex = source.indexOf("cancel: () =>");
+  const lifecycleCancelIndex = source.indexOf('handlers.onProcessLifecycle?.("cancel")', cancelIndex);
+
+  assert.ok(beforeSpawnIndex >= 0 && beforeSpawnIndex < spawnIndex);
+  assert.ok(spawnedIndex > spawnIndex);
+  assert.ok(lifecycleErrorIndex > errorIndex);
+  assert.ok(exitIndex > closeIndex);
+  assert.ok(lifecycleCancelIndex > cancelIndex);
+});
+
+test("generic command runner does not expose shell mode", () => {
+  const source = readFileSync(fileURLToPath(new URL("./CommandRunner.ts", import.meta.url)), "utf8");
+  assert.equal(source.includes("shell?: boolean"), false);
+  assert.equal(source.includes("spec.shell"), false);
+});

package/src/core/process/CommandRunner.ts

@@ -0,0 +1,269 @@
+import { spawn, type ChildProcess } from "child_process";
+import { sanitizeTerminalOutput } from "../terminal/terminalSanitize.js";
+import { createTerminalTitleSequenceStripper } from "../terminal/terminalTitle.js";
+import { validateExecutableForSpawn } from "./processValidation.js";
+
+export interface CommandSpec {
+  executable: string;
+  args: string[];
+  cwd: string;
+  env?: NodeJS.ProcessEnv;
+  timeoutMs?: number;
+}
+
+export interface CommandResult {
+  status: "completed" | "failed" | "spawn_error" | "timeout" | "canceled";
+  exitCode: number | null;
+  signal: NodeJS.Signals | null;
+  stdout: string;
+  stderr: string;
+  startedAt: number;
+  endedAt: number;
+  durationMs: number;
+  errorCode?: string;
+  userMessage: string;
+  debugMessage?: string;
+}
+
+export interface CommandStreamHandlers {
+  onStdout?: (text: string) => void;
+  onStderr?: (text: string) => void;
+  onProcessLifecycle?: (event: "before-spawn" | "spawned" | "exit" | "error" | "cancel") => void;
+}
+
+interface InternalCommandSpec extends CommandSpec {
+  displayExecutable?: string;
+}
+
+// Sanitize before splitting: title sequences can span newlines and must not corrupt the line output.
+function splitOutputLines(text: string): string[] {
+  return sanitizeTerminalOutput(text)
+    .replace(/\r\n/g, "\n")
+    .replace(/\r/g, "\n")
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+
+function pluralize(count: number, singular: string, plural = `${singular}s`): string {
+  return `${count} ${count === 1 ? singular : plural}`;
+}
+
+function looksLikePath(line: string): boolean {
+  return /[\\/]/.test(line) || /\.[a-z0-9_-]+$/i.test(line);
+}
+
+function buildUserMessage(result: {
+  executable: string;
+  code?: string;
+  exitCode: number | null;
+  stderr: string;
+  signal: NodeJS.Signals | null;
+  status: CommandResult["status"];
+}): string {
+  const stderrLine = sanitizeTerminalOutput(result.stderr).split(/\r?\n/).map((line) => line.trim()).find(Boolean);
+  if (result.status === "spawn_error" && result.code === "ENOENT") {
+    return `\`${result.executable}\` is not installed or not available on PATH.`;
+  }
+  if (result.status === "spawn_error" && result.code === "EACCES") {
+    return `\`${result.executable}\` could not be executed because permission was denied.`;
+  }
+  if (result.status === "timeout") {
+    return `Command timed out before it could finish.`;
+  }
+  if (result.status === "canceled") {
+    return "Command was canceled.";
+  }
+  if (result.signal) {
+    return `Command exited after receiving signal ${result.signal}.`;
+  }
+  if (result.exitCode === 1 && stderrLine?.match(/not recognized|not found|No such file/i)) {
+    return stderrLine;
+  }
+  if (result.exitCode === 1 && result.executable === "rg" && !stderrLine) {
+    return "ripgrep returned no matches.";
+  }
+  if (result.exitCode && result.exitCode !== 0) {
+    return stderrLine ?? `Command exited with code ${result.exitCode}.`;
+  }
+  return "Command completed.";
+}
+
+export function summarizeCommandResult(command: string, result: Pick<CommandResult, "status" | "exitCode" | "signal" | "stdout" | "stderr" | "userMessage">): string {
+  if (result.status !== "completed" || result.exitCode !== 0 || result.signal) {
+    return result.userMessage;
+  }
+
+  const stdoutLines = splitOutputLines(result.stdout);
+  if (stdoutLines.length === 0) {
+    return "Completed with no output.";
+  }
+
+  const lowerCommand = command.toLowerCase();
+  if (/\brg\b/.test(lowerCommand) && /--files\b/.test(lowerCommand)) {
+    return `Found ${pluralize(stdoutLines.length, "file")}.`;
+  }
+
+  if (/\b(get-childitem|ls|dir)\b/.test(lowerCommand)) {
+    return `Listed ${pluralize(stdoutLines.length, "item")}.`;
+  }
+
+  if (/\b(rg|grep|select-string|findstr)\b/.test(lowerCommand)) {
+    return `Found ${pluralize(stdoutLines.length, "match", "matches")}.`;
+  }
+
+  if (stdoutLines.length === 1) {
+    return stdoutLines[0]!;
+  }
+
+  if (stdoutLines.every(looksLikePath)) {
+    return `Returned ${pluralize(stdoutLines.length, "path")}.`;
+  }
+
+  return `Produced ${pluralize(stdoutLines.length, "line")} of output.`;
+}
+
+export function runCommand(
+  spec: CommandSpec,
+  handlers: CommandStreamHandlers = {},
+): { child: ChildProcess; result: Promise<CommandResult>; cancel: () => void } {
+  return runProcess(spec, handlers);
+}
+
+export function runShellCommand(
+  command: string,
+  options: Pick<CommandSpec, "cwd" | "env" | "timeoutMs">,
+  handlers: CommandStreamHandlers = {},
+): { child: ChildProcess; result: Promise<CommandResult>; cancel: () => void } {
+  const shellSpec = process.platform === "win32"
+    ? { executable: "cmd.exe", args: ["/d", "/s", "/c", command] }
+    : { executable: "/bin/sh", args: ["-c", command] };
+
+  return runProcess({
+    ...options,
+    executable: shellSpec.executable,
+    args: shellSpec.args,
+    displayExecutable: command,
+  }, handlers);
+}
+
+function runProcess(
+  spec: InternalCommandSpec,
+  handlers: CommandStreamHandlers,
+): { child: ChildProcess; result: Promise<CommandResult>; cancel: () => void } {
+  const startedAt = Date.now();
+  const executable = validateExecutableForSpawn(spec.executable, {
+    label: "Command executable",
+    cwd: spec.cwd,
+  });
+  const displayExecutable = spec.displayExecutable ?? executable;
+  let stdout = "";
+  let stderr = "";
+  let canceled = false;
+  let timeoutHandle: ReturnType<typeof setTimeout> | null = null;
+  const stdoutTitleStripper = createTerminalTitleSequenceStripper({
+    source: "src/core/process/CommandRunner.ts:shell.stdout",
+    stream: "stdout",
+    origin: "shell",
+  });
+  const stderrTitleStripper = createTerminalTitleSequenceStripper({
+    source: "src/core/process/CommandRunner.ts:shell.stderr",
+    stream: "stderr",
+    origin: "shell",
+  });
+
+  handlers.onProcessLifecycle?.("before-spawn");
+  const child = spawn(executable, spec.args, {
+    cwd: spec.cwd,
+    env: spec.env,
+    shell: false,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  handlers.onProcessLifecycle?.("spawned");
+
+  const result = new Promise<CommandResult>((resolve) => {
+    const finish = (partial: Omit<CommandResult, "stdout" | "stderr" | "startedAt" | "endedAt" | "durationMs" | "userMessage"> & { endedAt?: number }) => {
+      if (timeoutHandle) clearTimeout(timeoutHandle);
+      stdout += stdoutTitleStripper.flush();
+      stderr += stderrTitleStripper.flush();
+      const endedAt = partial.endedAt ?? Date.now();
+      resolve({
+        ...partial,
+        stdout: sanitizeTerminalOutput(stdout),
+        stderr: sanitizeTerminalOutput(stderr),
+        startedAt,
+        endedAt,
+        durationMs: endedAt - startedAt,
+        userMessage: buildUserMessage({
+          executable: displayExecutable,
+          code: partial.errorCode,
+          exitCode: partial.exitCode,
+          stderr,
+          signal: partial.signal,
+          status: partial.status,
+        }),
+      });
+    };
+
+    child.stdout?.on("data", (buffer: Buffer) => {
+      const text = stdoutTitleStripper.process(buffer);
+      stdout += text;
+      handlers.onStdout?.(sanitizeTerminalOutput(text));
+    });
+
+    child.stderr?.on("data", (buffer: Buffer) => {
+      const text = stderrTitleStripper.process(buffer);
+      stderr += text;
+      handlers.onStderr?.(sanitizeTerminalOutput(text));
+    });
+
+    child.once("error", (error: NodeJS.ErrnoException) => {
+      handlers.onProcessLifecycle?.("error");
+      finish({
+        status: canceled ? "canceled" : "spawn_error",
+        exitCode: null,
+        signal: null,
+        errorCode: error.code,
+        debugMessage: error.message,
+      });
+    });
+
+    child.once("close", (code, signal) => {
+      handlers.onProcessLifecycle?.("exit");
+      finish({
+        status: canceled ? "canceled" : code === 0 ? "completed" : "failed",
+        exitCode: code,
+        signal,
+      });
+    });
+
+    if (spec.timeoutMs && spec.timeoutMs > 0) {
+      timeoutHandle = setTimeout(() => {
+        if (child.killed) return;
+        child.kill();
+        finish({
+          status: "timeout",
+          exitCode: null,
+          signal: null,
+          debugMessage: `Timed out after ${spec.timeoutMs}ms`,
+        });
+      }, spec.timeoutMs);
+    }
+  });
+
+  return {
+    child,
+    result,
+    cancel: () => {
+      canceled = true;
+      handlers.onProcessLifecycle?.("cancel");
+      if (!child.killed) {
+        try {
+          child.kill();
+        } catch {
+          // ignore cancellation failures
+        }
+      }
+    },
+  };
+}