magus-cli 7.11.6 → 7.11.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magus-cli",
-  "version": "7.11.6",
+  "version": "7.11.7",
   "description": "TUI tool for managing Claude Code plugins, MCPs, and configuration",
   "type": "module",
   "main": "src/main.tsx",
@@ -65,8 +65,8 @@
     "typescript": "^5.6.3"
   },
   "optionalDependencies": {
-    "magus-cli-darwin-arm64": "7.11.6",
-    "magus-cli-darwin-x64": "7.11.6",
-    "magus-cli-linux-x64": "7.11.6"
+    "magus-cli-darwin-arm64": "7.11.7",
+    "magus-cli-darwin-x64": "7.11.7",
+    "magus-cli-linux-x64": "7.11.7"
   }
 }

package/src/__tests__/marketplace-refresh.test.ts

@@ -344,3 +344,116 @@ describe("fastForwardCloneIfPresent — single-clone helper (shared with claude-
 		expect(readPin(dir).pin).toBe("x@dirty");
 	});
 });
+
+/**
+ * Point the clone's origin at a fake ssh that hangs. git pull -> git fetch ->
+ * ssh: the fake ssh is NOT runBounded's direct child, so killing `git pull`
+ * leaves it holding the inherited stdout/stderr open. It records its own pid and
+ * its grandparent's (the `git pull` runBounded spawned) so the case can check
+ * them and the cleanup can kill them by pid, never by pattern.
+ */
+function hangSshTransport(dir: string): { sshPid: string; pullPid: string } {
+	const sshPid = path.join(tmp, "fake-ssh.pid");
+	const pullPid = path.join(tmp, "git-pull.pid");
+	const fakeSsh = path.join(tmp, "fake-ssh.sh");
+	fs.writeFileSync(
+		fakeSsh,
+		[
+			"#!/bin/sh",
+			`echo $$ > '${sshPid}'`,
+			`ps -o ppid= -p $PPID | tr -d ' ' > '${pullPid}'`,
+			`ps -o command= -p "$(cat '${pullPid}')" > '${pullPid}.cmd'`,
+			"exec sleep 60",
+			"",
+		].join("\n"),
+		{ mode: 0o755 },
+	);
+	git(dir, "remote", "set-url", "origin", "ssh://example.invalid/repo.git");
+	git(dir, "config", "core.sshCommand", fakeSsh);
+	hungPidFiles = [sshPid, pullPid];
+	return { sshPid, pullPid };
+}
+
+function readPid(file: string): number {
+	return Number(fs.readFileSync(file, "utf8").trim());
+}
+
+/** True once `pid` no longer exists, polling briefly to let the runtime reap it. */
+async function goneWithin(pid: number, ms: number): Promise<boolean> {
+	const until = Date.now() + ms;
+	for (;;) {
+		try {
+			process.kill(pid, 0);
+		} catch {
+			return true;
+		}
+		if (Date.now() > until) return false;
+		await Bun.sleep(20);
+	}
+}
+
+// pid files written by hangSshTransport; killed by pid after each case.
+let hungPidFiles: string[] = [];
+
+afterEach(() => {
+	for (const file of hungPidFiles) {
+		if (!fs.existsSync(file)) continue;
+		const pid = readPid(file);
+		if (pid > 0) {
+			try {
+				process.kill(pid, "SIGKILL");
+			} catch {
+				// already gone
+			}
+		}
+	}
+	hungPidFiles = [];
+});
+
+describe("fastForwardCloneIfPresent — a hung ssh transport", () => {
+	// REGRESSION: magus update stalls on the marketplaces step past the 30 s git timeout (ssh grandchild holds the pipes) — Fixed in /dev:fix session dev-fix-20261102-160435-22278 (MTL-365)
+	it("settles as 'failed' near the 30 s git timeout when ssh (a grandchild of git pull) holds the pipes", async () => {
+		const dir = installClone("magus");
+		hangSshTransport(dir);
+
+		const started = Date.now();
+		const status = await fastForwardCloneIfPresent("magus");
+		const elapsed = Date.now() - started;
+
+		expect(status).toBe("failed");
+		// 30 s timeout + grace. On the bug it settles only when ssh exits (~60 s).
+		expect(elapsed).toBeLessThan(40_000);
+		expect(fs.existsSync(dir)).toBe(true);
+	}, 45_000);
+});
+
+describe("fastForwardCloneIfPresent — per-clone deadline", () => {
+	// REGRESSION: the marketplaces step ran 56 min — a per-clone deadline bounds it whatever hangs (MTL-365)
+	it("returns 'failed' at the deadline while ssh still hangs, clone intact", async () => {
+		const dir = installClone("magus");
+		hangSshTransport(dir);
+
+		const started = Date.now();
+		const status = await fastForwardCloneIfPresent("magus", 1_000);
+		const elapsed = Date.now() - started;
+
+		expect(status).toBe("failed");
+		// Deadline 1 s plus slack. Without the deadline it settles at the 30 s git timeout.
+		expect(elapsed).toBeLessThan(3_000);
+		expect(fs.existsSync(dir)).toBe(true);
+	}, 10_000);
+
+	it("kills the in-flight git pull when the deadline wins, rather than leaving it running", async () => {
+		const dir = installClone("magus");
+		const { pullPid } = hangSshTransport(dir);
+
+		const status = await fastForwardCloneIfPresent("magus", 1_000);
+
+		expect(status).toBe("failed");
+		// The fake ssh got far enough to record its grandparent, the git pull.
+		expect(fs.existsSync(pullPid)).toBe(true);
+		expect(fs.readFileSync(`${pullPid}.cmd`, "utf8")).toContain("pull");
+		// Without the abort, git pull lives on until its own 30 s timeout.
+		expect(await goneWithin(readPid(pullPid), 1_000)).toBe(true);
+	}, 10_000);
+});

package/src/__tests__/spawn-bounded.test.ts

@@ -0,0 +1,211 @@
+/**
+ * runBounded settles on its deadline even when a descendant of the child keeps
+ * the stdout/stderr pipes open — the shape of `git pull` -> `git fetch` -> `ssh`.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { runBounded } from "../utils/spawn-bounded.js";
+
+let tmp: string;
+let pidFile: string;
+
+beforeEach(() => {
+	tmp = fs.mkdtempSync(path.join(os.tmpdir(), "spawn-bounded-"));
+	pidFile = path.join(tmp, "grandchild.pid");
+});
+
+afterEach(() => {
+	// Kill the leftover grandchild by pid, never by pattern.
+	if (fs.existsSync(pidFile)) {
+		const pid = Number(fs.readFileSync(pidFile, "utf8").trim());
+		if (pid > 0) {
+			try {
+				process.kill(pid, "SIGKILL");
+			} catch {
+				// already gone
+			}
+		}
+	}
+	fs.rmSync(tmp, { recursive: true, force: true });
+});
+
+function writeScript(name: string, body: string): string {
+	const file = path.join(tmp, name);
+	fs.writeFileSync(file, `#!/bin/sh\n${body}`, { mode: 0o755 });
+	return file;
+}
+
+/**
+ * `sh -c` argv: background a `sleep 30` that inherits stdout, then exit 0.
+ * Run through /bin/sh rather than a freshly written script: macOS's first exec
+ * of a new file can take ~300 ms, which would push the exit past a 200 ms
+ * deadline and turn a normal exit into a timeout.
+ */
+function exitLeavingHolder(): string[] {
+	return ["-c", `sleep 30 & echo $! > '${pidFile}'; exit 0`];
+}
+
+describe("runBounded", () => {
+	it("settles at the deadline while a grandchild still holds the pipes", async () => {
+		const script = writeScript(
+			"holder.sh",
+			`sleep 30 &\necho $! > '${pidFile}'\nwait\n`,
+		);
+
+		const started = Date.now();
+		const r = await runBounded(script, [], { timeoutMs: 300 });
+		const elapsed = Date.now() - started;
+
+		expect(r.timedOut).toBe(true);
+		expect(r.signal).toBe("SIGKILL");
+		expect(r.code).not.toBe(0);
+		expect(elapsed).toBeLessThan(2_000);
+	}, 5_000);
+
+	it("settles at the deadline with stdout-only pipes, too", async () => {
+		const script = writeScript(
+			"holder.sh",
+			`sleep 30 &\necho $! > '${pidFile}'\nwait\n`,
+		);
+
+		const started = Date.now();
+		const r = await runBounded(script, [], {
+			timeoutMs: 300,
+			stdio: ["ignore", "pipe", "ignore"],
+		});
+
+		expect(r.timedOut).toBe(true);
+		expect(r.signal).toBe("SIGKILL");
+		expect(Date.now() - started).toBeLessThan(2_000);
+	}, 5_000);
+
+	it("returns the full stdout of a child that exits normally", async () => {
+		const lines = Array.from({ length: 2000 }, (_, i) => `line ${i}`);
+		const script = writeScript(
+			"talker.sh",
+			`i=0\nwhile [ $i -lt 2000 ]; do echo "line $i"; i=$((i+1)); done\necho oops >&2\n`,
+		);
+
+		const r = await runBounded(script, [], { timeoutMs: 5_000 });
+
+		expect(r.code).toBe(0);
+		expect(r.signal).toBeNull();
+		expect(r.timedOut).toBe(false);
+		expect(r.spawnError).toBeUndefined();
+		expect(r.stdout).toBe(`${lines.join("\n")}\n`);
+		expect(r.stderr.trim()).toBe("oops");
+	}, 5_000);
+
+	it("reports a non-zero exit code without timing out", async () => {
+		const script = writeScript("fail.sh", "exit 3\n");
+
+		const r = await runBounded(script, [], { timeoutMs: 5_000 });
+
+		expect(r.code).toBe(3);
+		expect(r.timedOut).toBe(false);
+	}, 5_000);
+
+	it("after a normal exit with a background descendant holding stdout, settles after the close grace", async () => {
+		const started = Date.now();
+		const r = await runBounded("/bin/sh", exitLeavingHolder(), {
+			timeoutMs: 20_000,
+		});
+		const elapsed = Date.now() - started;
+
+		expect(r.timedOut).toBe(false);
+		expect(r.code).toBe(0);
+		// CLOSE_GRACE_MS is 1_500: not before it, and not much after it.
+		expect(elapsed).toBeGreaterThanOrEqual(1_400);
+		expect(elapsed).toBeLessThan(2_500);
+	}, 5_000);
+
+	it("never extends a normal exit's close grace past the deadline", async () => {
+		const started = Date.now();
+		const r = await runBounded("/bin/sh", exitLeavingHolder(), {
+			timeoutMs: 200,
+		});
+		const elapsed = Date.now() - started;
+
+		// The child exited by itself, so this is not a timeout.
+		expect(r.timedOut).toBe(false);
+		expect(r.code).toBe(0);
+		// Deadline 200 ms; the 1_500 ms grace must not outlive it.
+		expect(elapsed).toBeLessThan(700);
+	}, 5_000);
+
+	it("an abort mid-run kills the child and settles at once", async () => {
+		const script = writeScript(
+			"sleeper.sh",
+			`echo $$ > '${pidFile}'\nexec sleep 30\n`,
+		);
+		const controller = new AbortController();
+
+		const started = Date.now();
+		const pending = runBounded(script, [], {
+			timeoutMs: 20_000,
+			signal: controller.signal,
+		});
+		// Abort once the child is really running (it has written its pid).
+		while (!fs.existsSync(pidFile) || !fs.readFileSync(pidFile, "utf8")) {
+			await Bun.sleep(10);
+		}
+		const pid = Number(fs.readFileSync(pidFile, "utf8").trim());
+		const abortedAt = Date.now();
+		controller.abort();
+		const r = await pending;
+		const settledAfterAbort = Date.now() - abortedAt;
+
+		expect(r.aborted).toBe(true);
+		expect(r.code).not.toBe(0);
+		expect(settledAfterAbort).toBeLessThan(300);
+		expect(Date.now() - started).toBeLessThan(2_000);
+
+		// The child is dead. Poll briefly: a SIGKILLed child is a zombie until the
+		// runtime reaps it, and signal 0 still succeeds on a zombie.
+		const dead = async (): Promise<boolean> => {
+			for (let i = 0; i < 50; i++) {
+				try {
+					process.kill(pid, 0);
+				} catch {
+					return true;
+				}
+				await Bun.sleep(20);
+			}
+			return false;
+		};
+		expect(await dead()).toBe(true);
+	}, 5_000);
+
+	it("an already-aborted signal settles at once and spawns nothing", async () => {
+		const marker = path.join(tmp, "ran");
+		const script = writeScript("marker.sh", `touch '${marker}'\n`);
+		const controller = new AbortController();
+		controller.abort();
+
+		const started = Date.now();
+		const r = await runBounded(script, [], {
+			timeoutMs: 5_000,
+			signal: controller.signal,
+		});
+		const elapsed = Date.now() - started;
+
+		expect(r.aborted).toBe(true);
+		expect(r.code).toBeNull();
+		expect(elapsed).toBeLessThan(100);
+		// Give a spawned child every chance to run before checking it did not.
+		await Bun.sleep(300);
+		expect(fs.existsSync(marker)).toBe(false);
+	}, 5_000);
+
+	it("settles with spawnError, never throws, for a command that does not exist", async () => {
+		const r = await runBounded(path.join(tmp, "no-such-command"), [], {
+			timeoutMs: 5_000,
+		});
+
+		expect(r.spawnError).toBeInstanceOf(Error);
+		expect(r.timedOut).toBe(false);
+	}, 5_000);
+});

package/src/services/marketplace-catalog-git.ts

@@ -27,10 +27,10 @@
  * working precisely when the HTTP catalog cannot.
  */
 
-import { spawn } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { claudeConfigDirOrNull } from "../utils/config-dir.js";
+import { runBounded } from "../utils/spawn-bounded.js";
 import {
 	type MarketplacePlugin,
 	normalizeCatalogJson,
@@ -55,36 +55,27 @@ function cloneDir(name: string): string | null {
 	return path.join(configDir, "plugins", "marketplaces", name);
 }
 
-function git(
+async function git(
 	cwd: string,
 	args: string[],
 	timeoutMs: number,
 ): Promise<{ ok: boolean; out: string }> {
-	return new Promise((resolve) => {
-		const child = spawn("git", args, {
-			cwd,
-			stdio: ["ignore", "pipe", "ignore"],
-			timeout: timeoutMs,
-			killSignal: "SIGKILL",
-			env: {
-				...process.env,
-				// Never let git stop for credentials: this runs inside a TUI with no
-				// way to answer a prompt, and a private marketplace we cannot read
-				// should degrade to "unknown", not hang the screen forever.
-				GIT_TERMINAL_PROMPT: "0",
-				GIT_ASKPASS: "echo",
-				SSH_ASKPASS: "echo",
-			},
-		});
-		let out = "";
-		child.stdout.on("data", (d: Buffer | string) => {
-			out += String(d);
-		});
-		child.on("error", () => resolve({ ok: false, out: "" }));
-		child.on("close", (code: number | null) =>
-			resolve({ ok: code === 0, out }),
-		);
+	const r = await runBounded("git", args, {
+		cwd,
+		stdio: ["ignore", "pipe", "ignore"],
+		timeoutMs,
+		env: {
+			...process.env,
+			// Never let git stop for credentials: this runs inside a TUI with no
+			// way to answer a prompt, and a private marketplace we cannot read
+			// should degrade to "unknown", not hang the screen forever.
+			GIT_TERMINAL_PROMPT: "0",
+			GIT_ASKPASS: "echo",
+			SSH_ASKPASS: "echo",
+		},
 	});
+	if (r.spawnError) return { ok: false, out: "" };
+	return { ok: r.code === 0, out: r.stdout };
 }
 
 /**

package/src/services/marketplace-refresh.ts

@@ -17,9 +17,9 @@
  * A failed `git pull --ff-only` leaves the clone exactly as it was: stale, but intact.
  */
 
-import { spawn } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
+import { runBounded } from "../utils/spawn-bounded.js";
 import {
 	getConfiguredMarketplaces,
 	getGlobalClaudeDir,
@@ -29,6 +29,9 @@ import {
 /** Per-git-invocation timeout. A hung pull must never block launching Claude. */
 const GIT_TIMEOUT_MS = 30_000;
 
+/** Hard cap per clone, whatever hangs: `git status` then `git pull`, each GIT_TIMEOUT_MS, plus slack. */
+const CLONE_DEADLINE_MS = 2 * GIT_TIMEOUT_MS + 5_000;
+
 export interface RefreshResult {
 	/** Clones fast-forwarded to a newer commit (or already current). */
 	refreshed: string[];
@@ -42,46 +45,36 @@ function cloneDir(name: string): string {
 	return path.join(getGlobalClaudeDir(), "plugins", "marketplaces", name);
 }
 
-/** Run git in `cwd`, resolving stdout on exit 0. Killed after `timeoutMs`. */
-function runGit(
+/**
+ * Run git in `cwd`, resolving stdout on exit 0. Killed after `timeoutMs`, or as
+ * soon as `signal` aborts (an already-aborted signal runs nothing). Throws on
+ * anything but exit 0.
+ */
+async function runGit(
 	cwd: string,
 	args: string[],
 	timeoutMs: number,
+	signal?: AbortSignal,
 ): Promise<string> {
-	return new Promise((resolve, reject) => {
-		const proc = spawn("git", args, {
-			cwd,
-			timeout: timeoutMs,
-			killSignal: "SIGKILL",
-		});
-		let stdout = "";
-		let stderr = "";
-		proc.stdout?.on("data", (b) => {
-			stdout += b.toString();
-		});
-		proc.stderr?.on("data", (b) => {
-			stderr += b.toString();
-		});
-		proc.on("error", reject);
-		proc.on("close", (code, signal) => {
-			if (code === 0) {
-				resolve(stdout);
-			} else {
-				reject(
-					new Error(
-						`git ${args.join(" ")} ${
-							signal ? `killed (${signal})` : `exited ${code}`
-						}: ${stderr.trim()}`,
-					),
-				);
-			}
-		});
-	});
+	const r = await runBounded("git", args, { cwd, timeoutMs, signal });
+	if (r.spawnError) throw r.spawnError;
+	if (r.code === 0 && !r.aborted) return r.stdout;
+	const how = r.aborted
+		? "aborted"
+		: r.signal
+			? `killed (${r.signal})`
+			: `exited ${r.code}`;
+	throw new Error(`git ${args.join(" ")} ${how}: ${r.stderr.trim()}`);
 }
 
 /** True if the clone has uncommitted changes we must not clobber. */
-async function isDirty(dir: string): Promise<boolean> {
-	const out = await runGit(dir, ["status", "--porcelain"], GIT_TIMEOUT_MS);
+async function isDirty(dir: string, signal?: AbortSignal): Promise<boolean> {
+	const out = await runGit(
+		dir,
+		["status", "--porcelain"],
+		GIT_TIMEOUT_MS,
+		signal,
+	);
 	return out.trim().length > 0;
 }
 
@@ -99,23 +92,50 @@ export type CloneRefresh = "absent" | "skipped" | "refreshed" | "failed";
  * deletes: the worst case is `failed` (stale clone left intact). Shared by the
  * batch refresh below and by claude-cli's "plugin not found" recovery, so both
  * paths get the same safe semantics instead of the old `marketplace update`.
+ *
+ * Bounded by `deadlineMs`: when it passes, the result is `failed` and the git
+ * command then in flight (`status` or `pull`) is SIGKILLed; no further git
+ * command starts. Only that direct child is killed: a `git fetch` or `ssh` it
+ * spawned may linger until it exits on its own, holding nothing we wait on.
+ * The clone directory is never deleted, but a pull killed while it updates the
+ * working tree can leave that update part-way and a `.git/index.lock` behind;
+ * later pulls then return `failed` until the lock is removed. The deadline sits
+ * well above a healthy pull, so that is the price of never hanging, not a
+ * normal outcome.
  */
 export async function fastForwardCloneIfPresent(
 	name: string,
+	deadlineMs: number = CLONE_DEADLINE_MS,
 ): Promise<CloneRefresh> {
 	const dir = cloneDir(name);
 	// No clone on disk (claude never installed it) or not a git repo.
 	if (!fs.existsSync(path.join(dir, ".git"))) return "absent";
+	const abort = new AbortController();
+	const work = (async (): Promise<CloneRefresh> => {
+		try {
+			// Never clobber a user's local edits to the clone.
+			if (await isDirty(dir, abort.signal)) return "skipped";
+			// --ff-only is the safety guarantee: it fetches and fast-forwards, and
+			// aborts without mutating the tree if it can't. It never deletes the dir,
+			// so a failure degrades to "stale clone", never "deleted marketplace".
+			await runGit(dir, ["pull", "--ff-only"], GIT_TIMEOUT_MS, abort.signal);
+			return "refreshed";
+		} catch {
+			return "failed";
+		}
+	})();
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	const deadline = new Promise<CloneRefresh>((resolve) => {
+		timer = setTimeout(() => {
+			// Kill the in-flight git child rather than leave it running.
+			abort.abort();
+			resolve("failed");
+		}, deadlineMs);
+	});
 	try {
-		// Never clobber a user's local edits to the clone.
-		if (await isDirty(dir)) return "skipped";
-		// --ff-only is the safety guarantee: it fetches and fast-forwards, and
-		// aborts without mutating the tree if it can't. It never deletes the dir,
-		// so a failure degrades to "stale clone", never "deleted marketplace".
-		await runGit(dir, ["pull", "--ff-only"], GIT_TIMEOUT_MS);
-		return "refreshed";
-	} catch {
-		return "failed";
+		return await Promise.race([work, deadline]);
+	} finally {
+		clearTimeout(timer);
 	}
 }
 

package/src/utils/spawn-bounded.ts

@@ -0,0 +1,202 @@
+/**
+ * spawn-bounded.ts — run an argv (never a shell) with a hard deadline that
+ * actually holds.
+ *
+ * Guarantee: the returned promise settles, exactly once, no later than
+ * `timeoutMs + KILL_SETTLE_MS`, whatever the child or its descendants do — even
+ * if the child never delivers "exit" at all (stuck in uninterruptible I/O). It
+ * never rejects: a spawn failure (ENOENT etc.) comes back as `spawnError`.
+ *
+ * The gotcha this exists for: a timeout kill reaches only the DIRECT child,
+ * while "close" waits for EVERY holder of the stdout/stderr pipes. `git pull`
+ * runs `git fetch`, which runs `ssh`; kill `git pull` and ssh still holds the
+ * inherited pipes, so a promise that settles on "close" waits for ssh to give up
+ * on its own (122 s observed, against a 30 s timeout). So:
+ *  - normal path: settle on "close", so all output is read;
+ *  - after a normal "exit" with no "close": settle after a short grace, or at
+ *    the deadline, whichever comes first — the deadline is never extended;
+ *  - deadline with the child still running: SIGKILL it, settle on its "exit",
+ *    and if that never comes, settle anyway KILL_SETTLE_MS later;
+ *  - `signal` aborted: SIGKILL the child and settle at once; an already-aborted
+ *    signal spawns nothing;
+ *  - on settle: destroy the pipe ends, so an orphan's copies cannot pin the
+ *    event loop.
+ *
+ * No `detached` / process-group kill: on POSIX that is setsid(), which drops the
+ * controlling terminal, and ssh then cannot reach /dev/tty for a key passphrase
+ * or a security-key PIN. The cost is that an orphaned descendant may outlive the
+ * call until it exits or hits SIGPIPE; it blocks nothing.
+ */
+
+import {
+	type ChildProcess,
+	type StdioOptions,
+	spawn,
+} from "node:child_process";
+
+/** How long to wait for "close" after a normal "exit" before settling anyway. */
+const CLOSE_GRACE_MS = 1_500;
+
+/** How long after our SIGKILL to wait for "exit" before settling without it. */
+const KILL_SETTLE_MS = 1_000;
+
+export interface BoundedOptions {
+	cwd?: string;
+	env?: NodeJS.ProcessEnv;
+	/** Defaults to ["pipe", "pipe", "pipe"]. */
+	stdio?: StdioOptions;
+	timeoutMs: number;
+	/** Abort: SIGKILL the child and settle at once. Already aborted: spawn nothing. */
+	signal?: AbortSignal;
+}
+
+export interface BoundedResult {
+	code: number | null;
+	signal: NodeJS.Signals | null;
+	stdout: string;
+	stderr: string;
+	/** True when our deadline fired while the child was still running, and we SIGKILLed it. */
+	timedOut: boolean;
+	/** True when `options.signal` aborted the call (the child, if any, was SIGKILLed). */
+	aborted: boolean;
+	/** Set when the process could not be spawned at all (ENOENT, EACCES, ...). */
+	spawnError?: Error;
+}
+
+function isRunning(child: ChildProcess): boolean {
+	return child.exitCode === null && child.signalCode === null;
+}
+
+export function runBounded(
+	cmd: string,
+	args: string[],
+	options: BoundedOptions,
+): Promise<BoundedResult> {
+	return new Promise((resolve) => {
+		const abortSignal = options.signal;
+		if (abortSignal?.aborted) {
+			resolve({
+				code: null,
+				signal: null,
+				stdout: "",
+				stderr: "",
+				timedOut: false,
+				aborted: true,
+			});
+			return;
+		}
+
+		let stdout = "";
+		let stderr = "";
+		let timedOut = false;
+		let aborted = false;
+		let settled = false;
+		/** Set by "exit"; the child is gone even if "close" never comes. */
+		let exited: { code: number | null; signal: NodeJS.Signals | null } | null =
+			null;
+		let graceTimer: ReturnType<typeof setTimeout> | undefined;
+		let killSettleTimer: ReturnType<typeof setTimeout> | undefined;
+
+		let child: ChildProcess;
+		try {
+			child = spawn(cmd, args, {
+				cwd: options.cwd,
+				env: options.env,
+				stdio: options.stdio ?? ["pipe", "pipe", "pipe"],
+			});
+		} catch (err) {
+			resolve({
+				code: null,
+				signal: null,
+				stdout: "",
+				stderr: "",
+				timedOut: false,
+				aborted: false,
+				spawnError: err instanceof Error ? err : new Error(String(err)),
+			});
+			return;
+		}
+
+		const settle = (
+			code: number | null,
+			signal: NodeJS.Signals | null,
+			spawnError?: Error,
+		) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(deadlineTimer);
+			clearTimeout(graceTimer);
+			clearTimeout(killSettleTimer);
+			abortSignal?.removeEventListener("abort", onAbort);
+			child.stdout?.destroy();
+			child.stderr?.destroy();
+			child.stdin?.destroy();
+			resolve({
+				code,
+				signal,
+				stdout,
+				stderr,
+				timedOut,
+				aborted,
+				spawnError,
+			});
+		};
+
+		/** SIGKILL the child, then settle on its "exit" — or without it, soon. */
+		const killAndBoundSettle = () => {
+			child.kill("SIGKILL");
+			killSettleTimer = setTimeout(
+				() => settle(null, "SIGKILL"),
+				KILL_SETTLE_MS,
+			);
+		};
+
+		// An explicit timer, not spawn's `timeout` option, so we know the kill was
+		// ours. It stays armed until settle: it is also what caps the close grace.
+		// `settle` above reads it, but no child event or abort can fire before this
+		// line runs, so the reference is always initialised by then.
+		const deadlineTimer = setTimeout(() => {
+			if (exited) {
+				// Exited on its own, still waiting for "close": the grace ends here.
+				settle(exited.code, exited.signal);
+				return;
+			}
+			if (!isRunning(child)) {
+				// Exited, but the "exit" event has not been delivered yet.
+				settle(child.exitCode, child.signalCode);
+				return;
+			}
+			timedOut = true;
+			killAndBoundSettle();
+		}, options.timeoutMs);
+
+		function onAbort() {
+			aborted = true;
+			if (exited) {
+				settle(exited.code, exited.signal);
+				return;
+			}
+			if (isRunning(child)) child.kill("SIGKILL");
+			settle(child.exitCode, child.signalCode ?? "SIGKILL");
+		}
+		abortSignal?.addEventListener("abort", onAbort, { once: true });
+
+		child.stdout?.on("data", (b: Buffer | string) => {
+			stdout += b.toString();
+		});
+		child.stderr?.on("data", (b: Buffer | string) => {
+			stderr += b.toString();
+		});
+
+		child.on("error", (err) => settle(null, null, err));
+		child.on("exit", (code, signal) => {
+			exited = { code, signal };
+			if (timedOut) {
+				settle(code, signal);
+				return;
+			}
+			graceTimer = setTimeout(() => settle(code, signal), CLOSE_GRACE_MS);
+		});
+		child.on("close", (code, signal) => settle(code, signal));
+	});
+}