@opengsd/gsd-pi 1.1.1-dev.b2556262 → 1.2.0-dev.0b870afa

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();

package/src/resources/extensions/async-jobs/await-tool.test.ts

@@ -177,6 +177,145 @@ test("await_job suppresses follow-up for already-completed jobs (cross-turn case
 	manager.shutdown();
 });
 
+test("await_job aborts promptly when signal fires; job keeps running and is not suppressed", async () => {
+	const manager = new AsyncJobManager();
+	const tool = createAwaitTool(() => manager);
+
+	// Register a job that would run for 60s
+	const jobId = manager.register("bash", "long-job", async (_signal) => {
+		return new Promise<string>((resolve) => {
+			const timer = setTimeout(() => resolve("finally done"), 60_000);
+			if (typeof timer === "object" && "unref" in timer) timer.unref();
+		});
+	});
+
+	const ac = new AbortController();
+	// Abort after ~100ms
+	const abortTimer = setTimeout(() => ac.abort(), 100);
+	if (typeof abortTimer === "object" && "unref" in abortTimer) (abortTimer as NodeJS.Timeout).unref();
+
+	const start = Date.now();
+	const result = await tool.execute("tc_abort1", { jobs: [jobId], timeout: 60 }, ac.signal, () => {}, undefined as never);
+	const elapsed = Date.now() - start;
+	const text = getTextFromResult(result);
+
+	// Should abort quickly (within ~100ms + overhead), not wait for full timeout
+	assert.ok(elapsed < 5_000, `Expected abort in ~100ms but took ${elapsed}ms`);
+	assert.match(text, /interrupted/i);
+
+	// Job should still be running (not killed)
+	const job = manager.getJob(jobId)!;
+	assert.equal(job.status, "running", "Job should still be running after abort");
+	// Job should NOT be marked awaited — results must resurface later
+	assert.ok(!job.awaited, "Job should not be suppressed after abort");
+
+	// Cleanup
+	manager.cancel(jobId);
+	manager.shutdown();
+});
+
+test("after abort, a still-running job resurfaces via onJobComplete", async () => {
+	const followUps: string[] = [];
+	const manager = new AsyncJobManager({
+		onJobComplete: (job) => {
+			if (!job.awaited) followUps.push(job.id);
+		},
+	});
+	const tool = createAwaitTool(() => manager);
+
+	// Register a job that resolves after ~150ms
+	const jobId = manager.register("bash", "resurface-job", async () => {
+		return new Promise<string>((resolve) => {
+			const timer = setTimeout(() => resolve("done"), 150);
+			if (typeof timer === "object" && "unref" in timer) (timer as NodeJS.Timeout).unref();
+		});
+	});
+
+	const ac = new AbortController();
+	// Abort the await at ~50ms (before the job completes at ~150ms)
+	const abortTimer = setTimeout(() => ac.abort(), 50);
+	if (typeof abortTimer === "object" && "unref" in abortTimer) (abortTimer as NodeJS.Timeout).unref();
+
+	const result = await tool.execute("tc_abort2", { jobs: [jobId], timeout: 10 }, ac.signal, () => {}, undefined as never);
+	const text = getTextFromResult(result);
+	assert.match(text, /interrupted/i);
+
+	// Wait longer than the job's natural completion time (150ms) + delivery timer (0ms) + buffer
+	await new Promise((r) => setTimeout(r, 350));
+
+	// The job should have completed and the follow-up should have fired
+	// (because we did NOT suppress it on abort)
+	assert.ok(followUps.includes(jobId), `Expected job ${jobId} to resurface via onJobComplete, but got: ${followUps.join(", ")}`);
+
+	manager.shutdown();
+});
+
+test("await_job does not reprint a job whose follow-up was already delivered (no duplicate-in-context)", async () => {
+	// Real cross-turn timing: a job completes in a prior turn, its setTimeout(0)
+	// follow-up FIRES (delivered to context), and only THEN does await_job run in a
+	// later turn. The earlier #3787 test masked this by advancing with setImmediate,
+	// which races ahead of setTimeout(0); a real turn boundary does not. await_job
+	// must acknowledge the already-delivered job tersely instead of reprinting its
+	// full output (which would duplicate it in context).
+	const followUps: string[] = [];
+	const manager = new AsyncJobManager({
+		onJobComplete: (job) => {
+			if (!job.awaited) followUps.push(job.id);
+		},
+	});
+	const tool = createAwaitTool(() => manager);
+
+	const jobId = manager.register("bash", "already-delivered-job", async () => "THE_RESULT_TEXT");
+	await manager.getJob(jobId)!.promise;
+
+	// Real macrotask gap — generously long so the setTimeout(0) delivery fires even
+	// if the CI event loop is briefly starved (a tight 25ms could race the precondition).
+	await new Promise((r) => setTimeout(r, 100));
+	assert.equal(followUps.length, 1, "follow-up should have been delivered before the later-turn await_job");
+
+	const result = await tool.execute("tc_dup", { jobs: [jobId] }, noopSignal, () => {}, undefined as never);
+	const text = getTextFromResult(result);
+
+	// The full output must NOT be reprinted (it is already in context via the follow-up).
+	assert.ok(
+		!text.includes("THE_RESULT_TEXT"),
+		`await_job must not reprint already-delivered output, got:\n${text}`,
+	);
+	// It should still acknowledge the job so the agent knows the wait resolved.
+	assert.match(text, /already-delivered-job/);
+	// Single already-delivered job must use grammatical singular wording, not
+	// the plural form (regression: "These job ... their results ... they completed").
+	assert.match(text, /This job already finished and its result was shown above when it completed/);
+	assert.doesNotMatch(text, /These job\b/);
+
+	manager.shutdown();
+});
+
+test("await_job still renders full output for a job consumed within the same turn (not yet delivered)", async () => {
+	// Within-turn case: await_job wins the race against the delivery timer, so the
+	// follow-up is suppressed and never delivered. Here await_job IS the only place
+	// the result surfaces, so it must render the full output.
+	const followUps: string[] = [];
+	const manager = new AsyncJobManager({
+		onJobComplete: (job) => {
+			if (!job.awaited) followUps.push(job.id);
+		},
+	});
+	const tool = createAwaitTool(() => manager);
+
+	const jobId = manager.register("bash", "within-turn-job", async () => {
+		return new Promise<string>((resolve) => setTimeout(() => resolve("WITHIN_TURN_OUTPUT"), 40));
+	});
+
+	const result = await tool.execute("tc_within", { jobs: [jobId] }, noopSignal, () => {}, undefined as never);
+	const text = getTextFromResult(result);
+
+	assert.equal(followUps.length, 0, "within-turn await must suppress the follow-up");
+	assert.match(text, /WITHIN_TURN_OUTPUT/, "within-turn await must render the full output inline");
+
+	manager.shutdown();
+});
+
 test("unawaited jobs still get follow-up delivery (#2248)", async () => {
 	const followUps: string[] = [];
 	const manager = new AsyncJobManager({

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

@@ -33,7 +33,7 @@ export function createAwaitTool(getManager: () => AsyncJobManager): ToolDefiniti
 		description:
 			"Wait for background jobs to complete. Provide specific job IDs or omit to wait for the next job that finishes. Returns results of completed jobs.",
 		parameters: schema,
-		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+		async execute(_toolCallId, params, signal, _onUpdate, _ctx) {
 			const manager = getManager();
 			const { jobs: jobIds, timeout } = params;
 			const timeoutMs = ((timeout ?? DEFAULT_TIMEOUT_SECONDS) * 1000);
@@ -66,41 +66,79 @@ export function createAwaitTool(getManager: () => AsyncJobManager): ToolDefiniti
 				}
 			}
 
-			// Suppress follow-up notifications for all watched jobs upfront.
+			// If all watched jobs are already done, suppress follow-up and return immediately.
 			// suppressFollowUp() cancels the pending delivery timer (if any), which
 			// handles both the within-turn case (job completes while we await) and
 			// the cross-turn case (job already completed before await_job was called).
 			// Previously this only set j.awaited = true, which missed the cross-turn
 			// case because the queueMicrotask had already fired (#3787).
-			for (const j of watched) manager.suppressFollowUp(j.id);
-
-			// If all watched jobs are already done, return immediately
 			const running = watched.filter((j) => j.status === "running");
 			if (running.length === 0) {
-				const result = formatResults(watched);
-				return { content: [{ type: "text", text: result }], details: undefined };
+				for (const j of watched) manager.suppressFollowUp(j.id);
+				return { content: [{ type: "text", text: renderCompleted(watched) }], details: undefined };
 			}
 
-			// Wait for at least one to complete, or timeout
+			// Wait for at least one to complete, timeout, or abort signal
 			const TIMEOUT_SENTINEL = Symbol("timeout");
+			const ABORT_SENTINEL = Symbol("abort");
+
+			// The race timer and abort listener are explicitly torn down once the race
+			// settles (below) so a completion- or timeout-won race never leaks a pending
+			// timer or a lingering abort listener — the listener holds a closure over the
+			// race resolver, so { once: true } alone (which only detaches on fire) is not
+			// enough when ESC never happens.
+			let raceTimer: ReturnType<typeof setTimeout> | undefined;
+			let abortListener: (() => void) | undefined;
 			const timeoutPromise = new Promise<typeof TIMEOUT_SENTINEL>((resolve) => {
-				const timer = setTimeout(() => resolve(TIMEOUT_SENTINEL), timeoutMs);
+				raceTimer = setTimeout(() => resolve(TIMEOUT_SENTINEL), timeoutMs);
 				// Allow the process to exit even if the timer is pending
-				if (typeof timer === "object" && "unref" in timer) timer.unref();
+				if (typeof raceTimer === "object" && "unref" in raceTimer) raceTimer.unref();
+			});
+
+			const abortPromise = new Promise<typeof ABORT_SENTINEL>((resolve) => {
+				if (!signal || signal.aborted) {
+					resolve(ABORT_SENTINEL);
+				} else {
+					abortListener = () => resolve(ABORT_SENTINEL);
+					signal.addEventListener("abort", abortListener, { once: true });
+				}
 			});
 
 			const raceResult = await Promise.race([
 				Promise.race(running.map((j) => j.promise)).then(() => "completed" as const),
 				timeoutPromise,
+				abortPromise,
 			]);
 
+			// Tear down race resources now that a winner is decided.
+			if (raceTimer) clearTimeout(raceTimer);
+			if (abortListener && signal) signal.removeEventListener("abort", abortListener);
+
+			const aborted = raceResult === ABORT_SENTINEL;
 			const timedOut = raceResult === TIMEOUT_SENTINEL;
 
 			// Collect all completed results (more may have finished while waiting)
 			const completed = watched.filter((j) => j.status !== "running");
-
 			const stillRunning = watched.filter((j) => j.status === "running");
-			let result = formatResults(completed);
+
+			// Suppress follow-up ONLY for completed jobs — leave stillRunning unsuppressed
+			// so deliverResult/onJobComplete can resurface their results later.
+			for (const j of completed) manager.suppressFollowUp(j.id);
+
+			if (aborted) {
+				// ESC ended the wait, not the jobs: still-running jobs keep going and
+				// resurface via onJobComplete (they were deliberately not suppressed above).
+				const runningDesc = stillRunning.map((j) => `${j.id} (${j.label})`).join(", ");
+				const interrupt = stillRunning.length > 0
+					? `Wait interrupted. Still running: ${runningDesc} — results will surface when complete.`
+					: "Wait interrupted.";
+				const text = completed.length > 0
+					? `${renderCompleted(completed)}\n\n${interrupt}`
+					: interrupt;
+				return { content: [{ type: "text", text }], details: undefined };
+			}
+
+			let result = renderCompleted(completed);
 			if (stillRunning.length > 0) {
 				result += `\n\n**Still running:** ${stillRunning.map((j) => `${j.id} (${j.label})`).join(", ")}`;
 			}
@@ -115,6 +153,38 @@ export function createAwaitTool(getManager: () => AsyncJobManager): ToolDefiniti
 	};
 }
 
+/**
+ * Render completed jobs for the await_job result, de-duplicating against
+ * follow-ups that have already been delivered to context.
+ *
+ * A job's follow-up fires ~immediately (setTimeout(0)) once it settles, so when
+ * await_job runs in a LATER turn the result is already in context. Reprinting it
+ * inline produces the same output twice. Jobs already `delivered` are therefore
+ * acknowledged on a single line instead of having their full output reprinted;
+ * not-yet-delivered jobs (the within-turn case, where suppressFollowUp won the
+ * race) are rendered in full as before.
+ */
+function renderCompleted(jobs: Job[]): string {
+	if (jobs.length === 0) return "No completed jobs.";
+
+	const fresh = jobs.filter((j) => !j.delivered);
+	const alreadyDelivered = jobs.filter((j) => j.delivered);
+
+	const sections: string[] = [];
+	if (fresh.length > 0) sections.push(formatResults(fresh));
+	if (alreadyDelivered.length > 0) {
+		const names = alreadyDelivered
+			.map((j) => `${j.id} (${j.label})`)
+			.join(", ");
+		const sentence =
+			alreadyDelivered.length === 1
+				? `This job already finished and its result was shown above when it completed, so there is nothing new to report: ${names}.`
+				: `These jobs already finished and their results were shown above when they completed, so there is nothing new to report: ${names}.`;
+		sections.push(sentence);
+	}
+	return sections.join("\n\n");
+}
+
 function formatResults(jobs: Job[]): string {
 	if (jobs.length === 0) return "No completed jobs.";
 

package/src/resources/extensions/async-jobs/index.ts

@@ -117,10 +117,89 @@ export default function AsyncJobs(pi: ExtensionAPI) {
 				return;
 			}
 
+			const ctx = _ctx;
 			const running = manager.getRunningJobs();
 			const recent = manager.getRecentJobs(10);
 			const completed = recent.filter((j) => j.status !== "running");
 
+			// Interactive kill-picker when there are running jobs and a UI is available
+			if (running.length > 0 && ctx.hasUI) {
+				// Kill-picker loop: each iteration shows live running jobs.
+				// Step 1 picks a job (neutral label — selecting does NOT cancel yet);
+				// step 2 confirms before the destructive cancel. Labels deliberately
+				// omit a live elapsed time: ctx.ui.select renders the option strings
+				// once and never refreshes them, so a "(24s)" baked into the label
+				// would freeze and mislead. Accurate elapsed times are shown in the
+				// post-picker summary (rebuilt fresh) instead.
+				const DONE = "Close";
+				while (true) {
+					const liveJobs = manager.getRunningJobs();
+					if (liveJobs.length === 0) break;
+
+					// Map display label -> job id so we never parse ids back out of
+					// free-form label text.
+					const labelToId = new Map<string, string>();
+					for (const j of liveJobs) {
+						labelToId.set(`${j.id} — ${j.label} (running)`, j.id);
+					}
+					const options = [...labelToId.keys(), DONE];
+
+					const choice = await ctx.ui.select(
+						"Background jobs — pick one to cancel, Escape to close",
+						options,
+					);
+
+					// ESC returns undefined; headless may return string[]; DONE closes
+					if (!choice || typeof choice !== "string" || choice === DONE) break;
+
+					const id = labelToId.get(choice);
+					if (!id) break;
+
+					const job = liveJobs.find((j) => j.id === id);
+					const confirmed = await ctx.ui.confirm(
+						"Cancel background job?",
+						`This will stop ${id}${job ? ` — ${job.label}` : ""}. Other jobs keep running.`,
+					);
+					if (!confirmed) continue;
+
+					const r = manager.cancel(id);
+					ctx.ui.notify(
+						r === "cancelled" ? `Job ${id} cancelled.` : `Job ${id}: ${r}`,
+						r === "cancelled" ? "success" : "warning",
+					);
+				}
+
+				// After picker, send a summary of any still-running jobs
+				const stillRunning = manager.getRunningJobs();
+				const summaryLines: string[] = ["## Background Jobs"];
+				if (stillRunning.length > 0) {
+					summaryLines.push("", "### Running");
+					for (const job of stillRunning) {
+						const elapsed = ((Date.now() - job.startTime) / 1000).toFixed(0);
+						summaryLines.push(`- **${job.id}** — ${job.label} (${elapsed}s)`);
+					}
+				}
+				const recentCompleted = manager.getRecentJobs(10).filter((j) => j.status !== "running");
+				if (recentCompleted.length > 0) {
+					summaryLines.push("", "### Recent");
+					for (const job of recentCompleted) {
+						const elapsed = ((Date.now() - job.startTime) / 1000).toFixed(1);
+						summaryLines.push(`- **${job.id}** — ${job.label} (${job.status}, ${elapsed}s)`);
+					}
+				}
+				if (stillRunning.length === 0 && recentCompleted.length === 0) {
+					summaryLines.push("", "No background jobs.");
+				}
+
+				pi.sendMessage({
+					customType: "async_jobs_list",
+					content: summaryLines.join("\n"),
+					display: true,
+				});
+				return;
+			}
+
+			// Text-only display: headless/RPC mode, or no running jobs
 			const lines: string[] = ["## Background Jobs"];
 
 			if (running.length === 0 && completed.length === 0) {

package/src/resources/extensions/async-jobs/job-manager.ts

@@ -24,6 +24,14 @@ export interface Job {
 	errorText?: string;
 	/** Set by await_job when results are consumed. Suppresses follow-up delivery. */
 	awaited?: boolean;
+	/**
+	 * Set true once the follow-up notification has actually been delivered via
+	 * onJobComplete. The delivery timer fires ~immediately (setTimeout(0)) after a
+	 * job settles, so by a later LLM turn the follow-up is already in context.
+	 * await_job reads this to avoid rendering the same result inline a second time
+	 * (duplicate-in-context bug): a delivered job is acknowledged tersely, not reprinted.
+	 */
+	delivered?: boolean;
 	/**
 	 * Handle for the pending follow-up delivery timer (set by deliverResult).
 	 * Stored so suppressFollowUp() can cancel it before the notification fires,
@@ -102,6 +110,15 @@ export class AsyncJobManager {
 
 		job.promise = runFn(abortController.signal)
 			.then((resultText) => {
+				if (job.status === "cancelled") {
+					// Already cancelled by cancel(). The runFn resolves (not rejects) even
+					// when aborted — async_bash's safeResolve returns "Command aborted"
+					// rather than throwing — so without this guard the status would be
+					// clobbered back to "completed", mislabeling a user-cancelled job.
+					// Mirrors the symmetric guard in the .catch branch below.
+					this.scheduleEviction(id);
+					return;
+				}
 				job.status = "completed";
 				job.resultText = resultText;
 				this.scheduleEviction(id);
@@ -200,7 +217,10 @@ export class AsyncJobManager {
 		const cb = this.onJobComplete;
 		job.deliveryTimer = setTimeout(() => {
 			job.deliveryTimer = undefined;
-			if (!job.awaited) cb(job);
+			if (!job.awaited) {
+				job.delivered = true;
+				cb(job);
+			}
 		}, 0);
 		// Allow process to exit even if timer is pending
 		if (typeof job.deliveryTimer === "object" && "unref" in job.deliveryTimer) {

package/src/resources/extensions/bg-shell/bg-shell-command.ts

@@ -8,7 +8,7 @@ import { shortcutDesc } from "../shared/terminal.js";
 
 import {
 	processes,
-	killProcess,
+	terminateProcess,
 	getGroupStatus,
 	cleanupAll,
 } from "./process-manager.js";
@@ -150,11 +150,11 @@ export function registerBgShellCommand(pi: ExtensionAPI, state: BgShellSharedSta
 					ctx.ui.notify(`No process with id '${id}'`, "error");
 					return;
 				}
-				killProcess(id, "SIGTERM");
-				await new Promise(r => setTimeout(r, 300));
-				if (bg.alive) {
-					killProcess(id, "SIGKILL");
-					await new Promise(r => setTimeout(r, 200));
+				// Graceful ladder (SIGTERM → grace → SIGKILL) via killProcessTree.
+				terminateProcess(id);
+				const deadline = Date.now() + 6_000; // grace (5s) + slack
+				while (bg.alive && Date.now() < deadline) {
+					await new Promise(r => setTimeout(r, 100));
 				}
 				if (!bg.alive) processes.delete(id);
 				ctx.ui.notify(`Killed process ${id} (${bg.label})`, "info");

package/src/resources/extensions/bg-shell/bg-shell-tool.ts

@@ -12,6 +12,7 @@ import {
 	processes,
 	startProcess,
 	killProcess,
+	terminateProcess,
 	restartProcess,
 	getInfo,
 	getGroupStatus,
@@ -44,7 +45,8 @@ export function registerBgShellTool(pi: ExtensionAPI, state: BgShellSharedState)
 			"group_status (health of a process group), highlights (significant output lines only).",
 
 		promptGuidelines: [
-			"Use bg_shell to start long-running processes (servers, watchers, builds) that should not block the agent.",
+			"Use bg_shell for processes that STAY ALIVE and you interact with over time: servers, watchers, daemons, REPLs. For a command that runs to completion and exits (terraform apply, migrations, builds, tests, installs), use async_bash or sync bash instead — NOT bg_shell.",
+			"'wait_for_ready' is for long-lived processes that signal readiness (open a port / print a pattern). Never use it on a run-to-completion command: that command exits instead of becoming ready, so a clean exit-0 is reported as 'not ready'. If you see that, switch to async_bash.",
 			"After starting a server, use 'wait_for_ready' to efficiently block until it's listening — avoids polling loops entirely.",
 			"Use 'digest' instead of 'output' when you just need status — it returns a structured ~30-token summary instead of ~2000 tokens of raw output.",
 			"Use 'highlights' to see only significant output (errors, URLs, results) — typically 5-15 lines instead of hundreds.",
@@ -615,11 +617,13 @@ export function registerBgShellTool(pi: ExtensionAPI, state: BgShellSharedState)
 						};
 					}
 
-					const killed = killProcess(params.id, "SIGTERM");
-					await new Promise(r => setTimeout(r, 300));
-					if (bg.alive) {
-						killProcess(params.id, "SIGKILL");
-						await new Promise(r => setTimeout(r, 200));
+					// Graceful termination: SIGTERM → grace → SIGKILL via the shared
+					// killProcessTree ladder (same path bash/async_bash/exec use), so a
+					// stateful process gets a clean-shutdown window instead of a bare kill.
+					const killed = terminateProcess(params.id);
+					const deadline = Date.now() + 6_000; // grace (5s) + slack
+					while (bg.alive && Date.now() < deadline) {
+						await new Promise(r => setTimeout(r, 100));
 					}
 
 					const info = getInfo(bg);

package/src/resources/extensions/bg-shell/overlay.ts

@@ -9,7 +9,7 @@ import { ERROR_PATTERNS, WARNING_PATTERNS } from "./types.js";
 import { formatUptime, formatTimeAgo } from "./utilities.js";
 import {
 	processes,
-	killProcess,
+	terminateProcess,
 	cleanupAll,
 	restartProcess,
 } from "./process-manager.js";
@@ -134,16 +134,20 @@ export class BgManagerOverlay {
 			return;
 		}
 
-		// x or d = kill selected
+		// x or d = kill selected (graceful ladder via killProcessTree).
+		// Use a short interactive grace: the user explicitly asked to kill, so give the
+		// process a brief clean-shutdown window then force, and re-render AFTER that grace
+		// plus slack so the row reflects the SIGKILL escalation (a 300ms re-render against
+		// the default 5s grace would show the process still alive).
 		if (data === "x" || data === "d") {
 			const proc = procs[this.selected];
 			if (proc && proc.alive) {
-				killProcess(proc.id, "SIGTERM");
+				const OVERLAY_KILL_GRACE_MS = 500;
+				terminateProcess(proc.id, OVERLAY_KILL_GRACE_MS);
 				setTimeout(() => {
-					if (proc.alive) killProcess(proc.id, "SIGKILL");
 					this.invalidate();
 					this.tui.requestRender();
-				}, 300);
+				}, OVERLAY_KILL_GRACE_MS + 400);
 			}
 			return;
 		}