@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.8e6112e9

package/src/resources/extensions/ask-user-questions.ts

@@ -9,7 +9,8 @@
  * Based on: https://github.com/openai/codex (codex-rs/core/src/tools/handlers/ask_user_questions.rs)
  */
 
-import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+import type { ExtensionAPI, Theme } from "@gsd/pi-coding-agent";
+import type { NotificationPreferences } from "./gsd/types.js";
 import { sanitizeError } from "./shared/sanitize.js";
 import { Text } from "@gsd/pi-tui";
 import { Type } from "@sinclair/typebox";
@@ -188,6 +189,61 @@ function errorResult(
 	};
 }
 
+/** Parse the LLM-facing JSON payload back into a RoundResult for TUI rendering. */
+function parseLlmAnswersContent(text: string): RoundResult | null {
+	try {
+		const parsed = JSON.parse(text) as { answers?: Record<string, { answers?: string[] }> };
+		if (!parsed?.answers || typeof parsed.answers !== "object") return null;
+
+		const answers: RoundResult["answers"] = {};
+		for (const [id, entry] of Object.entries(parsed.answers)) {
+			const list = Array.isArray(entry?.answers) ? [...entry.answers] : [];
+			let notes = "";
+			const noteIdx = list.findIndex((item) => typeof item === "string" && item.startsWith("user_note:"));
+			if (noteIdx >= 0) {
+				notes = list.splice(noteIdx, 1)[0].replace(/^user_note:\s*/, "");
+			}
+			if (list.length === 0) continue;
+			answers[id] = {
+				selected: list.length === 1 ? list[0] : list,
+				notes,
+			};
+		}
+		if (Object.keys(answers).length === 0) return null;
+		return { endInterview: false, answers };
+	} catch {
+		return null;
+	}
+}
+
+function isCancelledResultContent(text: string): boolean {
+	return /\bwas cancelled before receiving a response\b/i.test(text)
+		|| /\bwas interrupted before receiving a response\b/i.test(text);
+}
+
+function renderAnswerLines(questions: Question[], response: RoundResult, theme: Theme): Text {
+	const lines: string[] = [];
+	for (const q of questions) {
+		const answer = response.answers[q.id];
+		if (!answer) {
+			lines.push(`${theme.fg("accent", q.header)}: ${theme.fg("dim", "(no answer)")}`);
+			continue;
+		}
+		const selected = answer.selected;
+		const notes = answer.notes;
+		const multiSel = !!q.allowMultiple;
+		const answerText = multiSel && Array.isArray(selected)
+			? selected.join(", ")
+			: (Array.isArray(selected) ? selected[0] : selected) ?? "(no answer)";
+		let line = `${theme.fg("success", "✓ ")}${theme.fg("accent", q.header)}: ${answerText}`;
+		if (notes) {
+			line += ` ${theme.fg("muted", `[note: ${notes}]`)}`;
+		}
+		lines.push(line);
+	}
+	return new Text(lines.join("\n"), 0, 0);
+}
+
 /** Convert the shared RoundResult into the JSON the LLM expects. */
 function formatForLLM(result: RoundResult): string {
 	const answers: Record<string, { answers: string[] }> = {};
@@ -206,10 +262,14 @@ function formatForLLM(result: RoundResult): string {
 	return JSON.stringify({ answers });
 }
 
-async function playQuestionBell(): Promise<void> {
+/** @internal Exported for testing only. */
+export async function playQuestionBell(
+	preferences?: NotificationPreferences,
+	stream?: { isTTY?: boolean; write(chunk: string): unknown },
+): Promise<void> {
 	try {
 		const { playNotificationBell } = await import("./gsd/notifications.js");
-		playNotificationBell("question");
+		playNotificationBell("question", preferences, stream);
 	} catch {
 		// Best-effort: question rendering must never depend on alert delivery.
 	}
@@ -433,11 +493,18 @@ export default function AskUserQuestions(pi: ExtensionAPI) {
 			return new Text(text, 0, 0);
 		},
 
-		renderResult(result, _options, theme) {
+		renderResult(result, _options, theme, context) {
 			const details = result.details as AskUserQuestionsDetails | undefined;
+			const contentText = result.content[0]?.type === "text" ? result.content[0].text : "";
+			const questionsFromArgs = (context?.args as { questions?: Question[] } | undefined)?.questions;
+			const parsedResponse = contentText ? parseLlmAnswersContent(contentText) : null;
+
 			if (!details) {
-				const text = result.content[0];
-				return new Text(text?.type === "text" ? text.text : "", 0, 0);
+				const questions = questionsFromArgs;
+				if (questions?.length && parsedResponse) {
+					return renderAnswerLines(questions, parsedResponse, theme);
+				}
+				return new Text(contentText, 0, 0);
 			}
 
 			// Remote channel result (discriminated on details.remote === true)
@@ -474,7 +541,10 @@ export default function AskUserQuestions(pi: ExtensionAPI) {
 				return new Text(lines.join("\n"), 0, 0);
 			}
 
-			if (details.cancelled || !details.response) {
+			const questions = details.questions ?? questionsFromArgs;
+			const response = details.response ?? parsedResponse;
+			const explicitCancel = details.cancelled === true || isCancelledResultContent(contentText);
+			if (explicitCancel && !response) {
 				const interrupted = "interrupted" in details && details.interrupted === true;
 				return new Text(
 					theme.fg("warning", interrupted ? "Interrupted" : "Cancelled"),
@@ -483,26 +553,24 @@ export default function AskUserQuestions(pi: ExtensionAPI) {
 				);
 			}
 
-			const lines: string[] = [];
-			for (const q of details.questions) {
-				const answer = (details.response as RoundResult).answers[q.id];
-				if (!answer) {
-					lines.push(`${theme.fg("accent", q.header)}: ${theme.fg("dim", "(no answer)")}`);
-					continue;
-				}
-				const selected = answer.selected;
-				const notes = answer.notes;
-				const multiSel = !!q.allowMultiple;
-				const answerText = multiSel && Array.isArray(selected)
-					? selected.join(", ")
-					: (Array.isArray(selected) ? selected[0] : selected) ?? "(no answer)";
-				let line = `${theme.fg("success", "✓ ")}${theme.fg("accent", q.header)}: ${answerText}`;
-				if (notes) {
-					line += ` ${theme.fg("muted", `[note: ${notes}]`)}`;
-				}
-				lines.push(line);
+			if (questions?.length && response) {
+				return renderAnswerLines(questions, response, theme);
 			}
-			return new Text(lines.join("\n"), 0, 0);
+
+			if (contentText) {
+				return new Text(contentText, 0, 0);
+			}
+
+			if (details.cancelled || !details.response) {
+				const interrupted = "interrupted" in details && details.interrupted === true;
+				return new Text(
+					theme.fg("warning", interrupted ? "Interrupted" : "Cancelled"),
+					0,
+					0,
+				);
+			}
+
+			return new Text("", 0, 0);
 		},
 	});
 }

package/src/resources/extensions/async-jobs/async-bash-cancel.test.ts

@@ -0,0 +1,360 @@
+/**
+ * async-bash-cancel.test.ts — Tests for graceful async_bash cancellation.
+ *
+ * Proves that:
+ *   1. The killProcessTree re-export from @gsd/pi-coding-agent resolves correctly
+ *      (loading async-bash-tool.ts will fail at import-time if the export is missing).
+ *   2. manager.cancel() sets status to 'cancelled' and returns 'cancelled'.
+ *   3. The job promise settles promptly (SIGTERM kills a well-behaved child).
+ *   4. The timeout path force-kills a SIGTERM-immune child via SIGKILL (regression:
+ *      it must not be left running in the background after the timeout fires).
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createAsyncBashTool } from "./async-bash-tool.ts";
+import { createAwaitTool } from "./await-tool.ts";
+import { AsyncJobManager } from "./job-manager.ts";
+
+function isAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0); // signal 0 probes existence without killing
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+// If killProcessTree is missing from the re-export the import above will throw
+// at load time (async-bash-tool.ts destructures it from @gsd/pi-coding-agent).
+// A load-time error surfaces as a test runner parse failure — no explicit
+// assertion needed; the test file simply won't run.
+
+const noopSignal = new AbortController().signal;
+
+test("graceful cancel: manager.cancel returns 'cancelled' and job settles promptly", async () => {
+	const manager = new AsyncJobManager();
+	const tool = createAsyncBashTool(() => manager, () => process.cwd());
+
+	// Launch a long-running well-behaved process (responds to SIGTERM)
+	const result = await tool.execute(
+		"tc-cancel-01",
+		{
+			command: "sleep 30",
+			label: "cancel-test-sleep",
+		},
+		noopSignal,
+		() => {},
+		undefined as never,
+	);
+
+	const text = result.content.map((c: { type: string; text?: string }) => c.text ?? "").join("\n");
+	const jobId = text.match(/\*\*(bg_[a-f0-9]+)\*\*/)?.[1];
+	assert.ok(jobId, `Expected a job ID in result text, got: ${text}`);
+
+	const job = manager.getJob(jobId)!;
+	assert.ok(job, "Job should be registered in manager");
+	assert.equal(job.status, "running", "Job should be running before cancel");
+
+	// Cancel — should return 'cancelled' immediately
+	const cancelResult = manager.cancel(jobId);
+	assert.equal(cancelResult, "cancelled", `cancel() should return 'cancelled', got: ${cancelResult}`);
+	assert.equal(job.status, "cancelled", "Job status should flip to 'cancelled'");
+
+	// Job promise should settle promptly — SIGTERM kills sleep quickly
+	const start = Date.now();
+	await Promise.race([
+		job.promise,
+		new Promise<never>((_, reject) => {
+			const t = setTimeout(() => {
+				reject(new Error(
+					`Job promise did not settle within 5s after cancel ` +
+					`(${Date.now() - start}ms elapsed) — graceful cancel may be broken`,
+				));
+			}, 5_000);
+			if (typeof t === "object" && "unref" in t) t.unref();
+		}),
+	]);
+
+	const elapsed = Date.now() - start;
+	assert.ok(elapsed < 5_000, `Job promise should settle under 5s, took ${elapsed}ms`);
+
+	manager.shutdown();
+});
+
+test(
+	"graceful cancel: status STAYS 'cancelled' after the job promise settles (not clobbered to 'completed')",
+	async (t) => {
+		// Regression: async_bash resolves (not rejects) its run promise even when aborted —
+		// safeResolve returns "Command aborted" rather than throwing — so the job-manager
+		// .then branch used to overwrite status back to 'completed', mislabeling a job the
+		// user explicitly cancelled. A cancelled job must also deliver NO follow-up.
+		const delivered: string[] = [];
+		const manager = new AsyncJobManager({ onJobComplete: (j) => delivered.push(j.id) });
+		// Tear down via t.after() so a thrown assertion still cleans up the manager.
+		t.after(() => manager.shutdown());
+		const tool = createAsyncBashTool(() => manager, () => process.cwd());
+
+		const result = await tool.execute(
+			"tc-cancel-status",
+			{ command: "sleep 30", label: "cancel-status-test" },
+			noopSignal,
+			() => {},
+			undefined as never,
+		);
+		const text = result.content.map((c: { type: string; text?: string }) => c.text ?? "").join("\n");
+		const jobId = text.match(/\*\*(bg_[a-f0-9]+)\*\*/)?.[1];
+		assert.ok(jobId, `Expected a job ID, got: ${text}`);
+
+		const job = manager.getJob(jobId)!;
+		assert.equal(manager.cancel(jobId), "cancelled");
+		assert.equal(job.status, "cancelled", "status should be 'cancelled' synchronously");
+
+		// Await the run promise settling (SIGTERM kills sleep quickly), THEN re-check status.
+		await job.promise;
+		// Let the deliverResult setTimeout(0) (if any) and microtasks flush.
+		await new Promise((r) => setTimeout(r, 20));
+
+		assert.equal(
+			job.status,
+			"cancelled",
+			`status must REMAIN 'cancelled' after the run promise settles, got '${job.status}' ` +
+				`(the .then branch clobbered the user-cancelled status)`,
+		);
+		assert.equal(
+			delivered.includes(jobId),
+			false,
+			"a cancelled job must not fire an onJobComplete follow-up",
+		);
+	},
+);
+
+test("graceful cancel: killProcessTree re-export resolves (load-time check)", async () => {
+	// This test is a belt-and-suspenders static check. If killProcessTree were
+	// not re-exported, the import at the top of this file would have already
+	// caused the entire test file to fail to load. We do an explicit runtime
+	// check here to make the intent clear and produce a readable assertion failure
+	// rather than a cryptic module-not-found error in the test runner output.
+	const mod = await import("@gsd/pi-coding-agent");
+	assert.ok(
+		typeof (mod as Record<string, unknown>).killProcessTree === "function",
+		"killProcessTree must be exported from @gsd/pi-coding-agent",
+	);
+});
+
+test(
+	"timeout path: SIGTERM-immune job is force-killed (SIGKILL), not left running in the background",
+	// Worst case ~12s (1s timeout + 5s grace + 3s hard-deadline + 3s poll); the
+	// explicit timeout prevents an infinite hang if force-resolve ever regresses.
+	{ skip: process.platform === "win32" ? "Unix-primary graceful semantics" : false, timeout: 20_000 },
+	async (t) => {
+		// Regression: the timeout path previously called a local killTree that only
+		// ever sent SIGTERM (twice), so a `trap '' TERM` child survived its timeout
+		// and ran forever in the background. It now routes through killProcessTree,
+		// which escalates SIGTERM -> grace -> SIGKILL. This proves the child is
+		// actually dead shortly after the 5s grace window, not orphaned.
+		const dir = mkdtempSync(join(tmpdir(), "async-timeout-sigkill-"));
+		const pidFile = join(dir, "pgid.pid");
+		t.after(() => {
+			// Best-effort: kill the process group if the test failed and left it alive.
+			try {
+				const pgid = Number.parseInt(readFileSync(pidFile, "utf-8").trim(), 10);
+				// Guard pgid > 0: process.kill(-0, ...) would signal the test runner's OWN
+				// process group (-0 === 0 === "caller's group" under POSIX).
+				if (Number.isFinite(pgid) && pgid > 0) process.kill(-pgid, "SIGKILL");
+			} catch {
+				/* already gone */
+			}
+			rmSync(dir, { recursive: true, force: true });
+		});
+
+		const manager = new AsyncJobManager();
+		const tool = createAsyncBashTool(() => manager, () => process.cwd());
+
+		// echo $$ records the detached shell's PID (process-group leader). The shell
+		// ignores SIGTERM and loops forever, so only SIGKILL can end it.
+		const command = `echo $$ > '${pidFile}'; trap '' TERM; while true; do sleep 1; done`;
+		const result = await tool.execute(
+			"tc-timeout-sigkill",
+			{ command, label: "timeout-sigkill", timeout: 1 },
+			noopSignal,
+			() => {},
+			undefined as never,
+		);
+
+		const text = result.content.map((c: { type: string; text?: string }) => c.text ?? "").join("\n");
+		const jobId = text.match(/\*\*(bg_[a-f0-9]+)\*\*/)?.[1];
+		assert.ok(jobId, `Expected a job ID, got: ${text}`);
+
+		// The promise force-resolves at ~timeout + grace + hard-deadline (~1+5+3s).
+		await manager.getJob(jobId)!.promise;
+
+		const pgid = Number.parseInt(readFileSync(pidFile, "utf-8").trim(), 10);
+		assert.ok(Number.isFinite(pgid) && pgid > 0, "child must have recorded a valid positive process-group PID");
+
+		// Poll briefly: SIGKILL was sent at timeout+grace (~6s); give it a moment to reap.
+		const deadlineMs = Date.now() + 3_000;
+		while (isAlive(pgid) && Date.now() < deadlineMs) {
+			await new Promise((r) => setTimeout(r, 100));
+		}
+		assert.equal(
+			isAlive(pgid),
+			false,
+			`SIGTERM-immune timed-out job (pgid ${pgid}) must be SIGKILLed, not left running`,
+		);
+
+		manager.shutdown();
+	},
+);
+
+test("graceful cancel: job promise settles even for node process on cancel", async () => {
+	const manager = new AsyncJobManager();
+	const tool = createAsyncBashTool(() => manager, () => process.cwd());
+
+	// node process that blocks for 30s — responds to SIGTERM
+	const result = await tool.execute(
+		"tc-cancel-02",
+		{
+			command: `node -e "setTimeout(()=>{}, 30000)"`,
+			label: "cancel-test-node",
+		},
+		noopSignal,
+		() => {},
+		undefined as never,
+	);
+
+	const text = result.content.map((c: { type: string; text?: string }) => c.text ?? "").join("\n");
+	const jobId = text.match(/\*\*(bg_[a-f0-9]+)\*\*/)?.[1];
+	assert.ok(jobId, "Expected a job ID");
+
+	const job = manager.getJob(jobId)!;
+	assert.equal(job.status, "running");
+
+	const cancelResult = manager.cancel(jobId);
+	assert.equal(cancelResult, "cancelled");
+
+	const start = Date.now();
+	await Promise.race([
+		job.promise,
+		new Promise<never>((_, reject) => {
+			const t = setTimeout(() => {
+				reject(new Error(`Job promise hung after cancel (${Date.now() - start}ms)`));
+			}, 5_000);
+			if (typeof t === "object" && "unref" in t) t.unref();
+		}),
+	]);
+
+	assert.ok(Date.now() - start < 5_000, "Promise should settle quickly after cancel");
+	manager.shutdown();
+});
+
+test(
+	"cancel path: SIGTERM-immune job force-resolves via hard deadline, does not hang",
+	// Worst case ~8s (5s grace + 3s hard-deadline after cancel); explicit timeout
+	// guards against an infinite hang if the abort-path force-resolve regresses.
+	{ skip: process.platform === "win32" ? "Unix-primary graceful semantics" : false, timeout: 20_000 },
+	async () => {
+		// Regression: onAbort (the /jobs cancel path) used to kill the child but arm no
+		// hard deadline, so cancelling a `trap '' TERM` child that never closes left the
+		// job promise dangling forever. It now arms the same hard-deadline force-resolve
+		// the timeout path uses.
+		const manager = new AsyncJobManager();
+		const tool = createAsyncBashTool(() => manager, () => process.cwd());
+
+		const result = await tool.execute(
+			"tc-cancel-dstate",
+			{ command: `trap '' TERM; while true; do sleep 1; done`, label: "cancel-dstate" },
+			noopSignal,
+			() => {},
+			undefined as never,
+		);
+		const text = result.content.map((c: { type: string; text?: string }) => c.text ?? "").join("\n");
+		const jobId = text.match(/\*\*(bg_[a-f0-9]+)\*\*/)?.[1];
+		assert.ok(jobId, "Expected a job ID");
+
+		const job = manager.getJob(jobId)!;
+		assert.equal(job.status, "running");
+		assert.equal(manager.cancel(jobId), "cancelled");
+
+		// The promise must settle via the hard deadline (~8s) rather than hang.
+		const start = Date.now();
+		await Promise.race([
+			job.promise,
+			new Promise<never>((_, reject) => {
+				const t = setTimeout(() => {
+					reject(new Error(`Cancelled D-state job hung (${Date.now() - start}ms) — abort-path force-resolve missing`));
+				}, 15_000);
+				if (typeof t === "object" && "unref" in t) t.unref();
+			}),
+		]);
+		assert.ok(Date.now() - start < 15_000, "cancelled D-state job must force-resolve, not hang");
+
+		manager.shutdown();
+	},
+);
+
+test(
+	"ESC during await_job ends the wait but leaves the real background process alive",
+	// End-to-end proof of the headline claim: a real OS subprocess (not a synthetic
+	// in-process job) must survive an aborted await_job. The await tool resolves on
+	// abort; we then confirm the child PID is still alive before cleaning it up.
+	{ skip: process.platform === "win32" ? "Unix-primary graceful semantics" : false, timeout: 20_000 },
+	async (t) => {
+		const dir = mkdtempSync(join(tmpdir(), "await-esc-alive-"));
+		const pidFile = join(dir, "pgid.pid");
+		const manager = new AsyncJobManager();
+		t.after(() => {
+			try {
+				const pgid = Number.parseInt(readFileSync(pidFile, "utf-8").trim(), 10);
+				if (Number.isFinite(pgid) && pgid > 0) process.kill(-pgid, "SIGKILL");
+			} catch {
+				/* already gone */
+			}
+			manager.shutdown();
+			rmSync(dir, { recursive: true, force: true });
+		});
+
+		const asyncBash = createAsyncBashTool(() => manager, () => process.cwd());
+		const awaitJob = createAwaitTool(() => manager);
+
+		// Start a real 60s background process that records its process-group PID.
+		const started = await asyncBash.execute(
+			"tc-await-esc",
+			{ command: `echo $$ > '${pidFile}'; sleep 60`, label: "await-esc-sleeper" },
+			noopSignal,
+			() => {},
+			undefined as never,
+		);
+		const jobId = started.content.map((c: { type: string; text?: string }) => c.text ?? "").join("\n")
+			.match(/\*\*(bg_[a-f0-9]+)\*\*/)?.[1];
+		assert.ok(jobId, "expected a job id from async_bash");
+
+		// Give the child a moment to write its pidfile.
+		await new Promise((r) => setTimeout(r, 200));
+		const pgid = Number.parseInt(readFileSync(pidFile, "utf-8").trim(), 10);
+		assert.ok(Number.isFinite(pgid) && pgid > 0, "child must record a valid pgid");
+		assert.equal(isAlive(pgid), true, "child should be alive before the await");
+
+		// await_job, then fire ESC (abort) ~100ms in. The wait must end promptly.
+		const ac = new AbortController();
+		const abortTimer = setTimeout(() => ac.abort(), 100);
+		if (typeof abortTimer === "object" && "unref" in abortTimer) (abortTimer as NodeJS.Timeout).unref();
+
+		const waitStart = Date.now();
+		const awaitResult = await awaitJob.execute("tc-await-esc-wait", { jobs: [jobId!] }, ac.signal, () => {}, undefined as never);
+		const elapsed = Date.now() - waitStart;
+		const awaitText = awaitResult.content.map((c: { type: string; text?: string }) => c.text ?? "").join("\n");
+
+		// (a) The wait ended promptly on ESC, not after the 120s default timeout.
+		assert.ok(elapsed < 5_000, `await should end promptly on ESC, took ${elapsed}ms`);
+		assert.match(awaitText, /interrupted/i, "aborted await should report the interruption");
+
+		// (b) The job and its real OS process are both STILL ALIVE — ESC ends the wait,
+		//     it does not kill the job.
+		assert.equal(manager.getJob(jobId!)!.status, "running", "job should still be running after ESC");
+		assert.equal(isAlive(pgid), true, "the real background process must survive an aborted await_job");
+	},
+);

package/src/resources/extensions/async-jobs/async-bash-tool.ts

@@ -10,11 +10,14 @@ import type { ToolDefinition } from "@gsd/pi-coding-agent";
 import {
 	getShellConfig,
 	sanitizeCommand,
+	killProcessTree,
+	SIGKILL_GRACE_MS,
+	HARD_DEADLINE_MS,
 	DEFAULT_MAX_BYTES,
 	DEFAULT_MAX_LINES,
 } from "@gsd/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
-import { spawn, spawnSync } from "node:child_process";
+import { spawn } from "node:child_process";
 import { createWriteStream } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -37,29 +40,6 @@ function getTempFilePath(): string {
 	return join(tmpdir(), `pi-async-bash-${id}.log`);
 }
 
-/**
- * Kill a process and its children (cross-platform).
- * Uses process group kill on Unix; taskkill /F /T on Windows.
- */
-function killTree(pid: number): void {
-	if (process.platform === "win32") {
-		try {
-			spawnSync("taskkill", ["/F", "/T", "/PID", String(pid)], {
-				timeout: 5_000,
-				stdio: "ignore",
-			});
-		} catch {
-			try { process.kill(pid, "SIGTERM"); } catch { /* already exited */ }
-		}
-	} else {
-		try {
-			process.kill(-pid, "SIGTERM");
-		} catch {
-			try { process.kill(pid, "SIGTERM"); } catch { /* already exited */ }
-		}
-	}
-}
-
 export function createAsyncBashTool(
 	getManager: () => AsyncJobManager,
 	getCwd: () => string,
@@ -73,7 +53,7 @@ export function createAsyncBashTool(
 			`Output is truncated to the last ${DEFAULT_MAX_LINES} lines or ${DEFAULT_MAX_BYTES / 1024}KB.`,
 		promptSnippet: "Run a bash command in the background, returning a job ID immediately.",
 		promptGuidelines: [
-			"Use async_bash for commands that take more than a few seconds (builds, tests, installs, large git operations).",
+			"Use async_bash for long-running builds, tests, installs, or operations that should run in the background so you can continue other work (the job ID lets you await_job later). Sync bash is uncapped — use async_bash when you want non-blocking behavior, not because of a timeout concern.",
 			"After starting async jobs, continue with other work and use await_job when you need the results.",
 			"await_job has a configurable timeout (default 120s) to prevent indefinite blocking — if it times out, jobs keep running and you can check again later.",
 			"For long-running processes (SSH, deploys, training) that may take minutes+, prefer async_bash with periodic await_job polling over a single long await.",
@@ -138,39 +118,27 @@ function executeBashInBackground(
 
 		let timedOut = false;
 		let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
-		let sigkillHandle: ReturnType<typeof setTimeout> | undefined;
 		let hardDeadlineHandle: ReturnType<typeof setTimeout> | undefined;
 
-		/** Grace period (ms) between SIGTERM and SIGKILL. */
-		const SIGKILL_GRACE_MS = 5_000;
-		/** Hard deadline (ms) after SIGKILL to force-resolve the promise. */
-		const HARD_DEADLINE_MS = 3_000;
-
 		if (timeout !== undefined && timeout > 0) {
 			timeoutHandle = setTimeout(() => {
 				timedOut = true;
-				if (child.pid) killTree(child.pid);
-
-				// If the process ignores SIGTERM, escalate to SIGKILL
-				sigkillHandle = setTimeout(() => {
-					if (child.pid) {
-						// killTree already uses taskkill /F /T on Windows
-						killTree(child.pid);
-					}
-
-					// Hard deadline: if even SIGKILL doesn't trigger 'close',
-					// force-resolve so the job doesn't hang forever (#2186).
-					hardDeadlineHandle = setTimeout(() => {
-						const output = Buffer.concat(chunks).toString("utf-8");
-						safeResolve(
-							output
-								? `${output}\n\nCommand timed out after ${timeout} seconds (force-killed)`
-								: `Command timed out after ${timeout} seconds (force-killed)`,
-						);
-					}, HARD_DEADLINE_MS);
-					if (typeof hardDeadlineHandle === "object" && "unref" in hardDeadlineHandle) hardDeadlineHandle.unref();
-				}, SIGKILL_GRACE_MS);
-				if (typeof sigkillHandle === "object" && "unref" in sigkillHandle) sigkillHandle.unref();
+				// killProcessTree owns the SIGTERM -> grace -> SIGKILL escalation, so a
+				// SIGTERM-immune child is actually force-killed rather than left running.
+				if (child.pid) killProcessTree(child.pid);
+
+				// Hard deadline: a D-state (uninterruptible-I/O) child never emits 'close'
+				// even after SIGKILL, so force-resolve the promise rather than hang (#2186).
+				// Fires after the full grace window so SIGKILL has had its chance first.
+				hardDeadlineHandle = setTimeout(() => {
+					const output = Buffer.concat(chunks).toString("utf-8");
+					safeResolve(
+						output
+							? `${output}\n\nCommand timed out after ${timeout} seconds (force-killed)`
+							: `Command timed out after ${timeout} seconds (force-killed)`,
+					);
+				}, SIGKILL_GRACE_MS + HARD_DEADLINE_MS);
+				if (typeof hardDeadlineHandle === "object" && "unref" in hardDeadlineHandle) hardDeadlineHandle.unref();
 			}, timeout * 1000);
 		}
 
@@ -202,7 +170,18 @@ function executeBashInBackground(
 		if (child.stderr) child.stderr.on("data", onData);
 
 		const onAbort = () => {
-			if (child.pid) killTree(child.pid);
+			if (child.pid) killProcessTree(child.pid);
+			// Arm the same hard-deadline force-resolve the timeout path uses, so a
+			// cancelled D-state child (never emits 'close' even after SIGKILL) can't
+			// hang the job promise forever. safeResolve is idempotent, so the real
+			// 'close' still wins if the child does exit.
+			if (!hardDeadlineHandle) {
+				hardDeadlineHandle = setTimeout(() => {
+					const output = Buffer.concat(chunks).toString("utf-8");
+					safeResolve(output ? `${output}\n\nCommand aborted (force-killed)` : "Command aborted (force-killed)");
+				}, SIGKILL_GRACE_MS + HARD_DEADLINE_MS);
+				if (typeof hardDeadlineHandle === "object" && "unref" in hardDeadlineHandle) hardDeadlineHandle.unref();
+			}
 		};
 
 		if (signal.aborted) {
@@ -213,7 +192,6 @@ function executeBashInBackground(
 
 		child.on("error", (err) => {
 			if (timeoutHandle) clearTimeout(timeoutHandle);
-			if (sigkillHandle) clearTimeout(sigkillHandle);
 			if (hardDeadlineHandle) clearTimeout(hardDeadlineHandle);
 			signal.removeEventListener("abort", onAbort);
 			safeReject(err);
@@ -221,7 +199,6 @@ function executeBashInBackground(
 
 		child.on("close", (code) => {
 			if (timeoutHandle) clearTimeout(timeoutHandle);
-			if (sigkillHandle) clearTimeout(sigkillHandle);
 			if (hardDeadlineHandle) clearTimeout(hardDeadlineHandle);
 			signal.removeEventListener("abort", onAbort);
 			if (spillStream) spillStream.end();