@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.72e3af2a

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;
 		}

package/src/resources/extensions/bg-shell/process-manager.ts

@@ -7,7 +7,7 @@ import { spawn, spawnSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { writeFileSync, readFileSync, existsSync, mkdirSync } from "node:fs";
 import { join } from "node:path";
-import { getShellConfig, sanitizeCommand } from "@gsd/pi-coding-agent";
+import { getShellConfig, sanitizeCommand, killProcessTree } from "@gsd/pi-coding-agent";
 import { rewriteCommandWithRtk } from "../shared/rtk.js";
 import type {
 	BgProcess,
@@ -259,6 +259,34 @@ export function startProcess(opts: StartOptions): BgProcess {
 
 // ── Process Kill ───────────────────────────────────────────────────────────
 
+/**
+ * Gracefully terminate a process and its tree using the shared killProcessTree
+ * ladder (SIGTERM → grace window → SIGKILL), the same path bash/async_bash/exec
+ * use. This is the "I want it dead, cleanly" intent — use it for the `kill`
+ * action, `restart`, and session cleanup. For sending a SPECIFIC signal the
+ * agent chose on purpose (SIGINT, SIGHUP, …) use killProcess(), which delivers
+ * that exact signal once and does not escalate.
+ *
+ * `graceMs` overrides the SIGTERM→SIGKILL window (default: killProcessTree's 5s);
+ * session cleanup passes a shorter grace so it stays snappy between units.
+ *
+ * Returns false only when the process is unknown/already dead; the actual
+ * SIGKILL escalation fires asynchronously after the grace window, so callers
+ * should not assume the process is dead the instant this returns.
+ */
+export function terminateProcess(id: string, graceMs?: number): boolean {
+	const bg = processes.get(id);
+	if (!bg) return false;
+	if (!bg.alive) return true;
+	if (!bg.proc.pid) {
+		// No pid to target a tree; fall back to a direct graceful signal.
+		try { bg.proc.kill("SIGTERM"); } catch { /* already gone */ }
+		return true;
+	}
+	killProcessTree(bg.proc.pid, graceMs !== undefined ? { graceMs } : undefined);
+	return true;
+}
+
 export function killProcess(id: string, sig: NodeJS.Signals = "SIGTERM"): boolean {
 	const bg = processes.get(id);
 	if (!bg) return false;
@@ -306,13 +334,14 @@ export async function restartProcess(id: string): Promise<BgProcess | null> {
 	const config = old.startConfig;
 	const restartCount = old.restartCount + 1;
 
-	// Kill old process
+	// Kill old process via the graceful ladder, then wait for it to actually die.
+	// killProcessTree escalates SIGTERM → grace → SIGKILL asynchronously, so poll
+	// for death rather than assuming a fixed sleep is enough.
 	if (old.alive) {
-		killProcess(id, "SIGTERM");
-		await new Promise(r => setTimeout(r, 300));
-		if (old.alive) {
-			killProcess(id, "SIGKILL");
-			await new Promise(r => setTimeout(r, 200));
+		terminateProcess(id);
+		const deadline = Date.now() + 6_000; // grace (5s) + slack
+		while (old.alive && Date.now() < deadline) {
+			await new Promise(r => setTimeout(r, 100));
 		}
 	}
 	processes.delete(id);
@@ -374,25 +403,16 @@ export function pruneDeadProcesses(): void {
 }
 
 export function cleanupAll(): void {
+	// Deliberately a bare, synchronous SIGKILL — not the graceful ladder. This runs
+	// from process 'exit'/signal handlers where timers no longer fire, so a deferred
+	// SIGKILL would never be delivered and children would be orphaned when we vanish.
+	// Immediate force-kill is the correct teardown semantics here.
 	for (const [id, bg] of processes) {
 		if (bg.alive) killProcess(id, "SIGKILL");
 	}
 	processes.clear();
 }
 
-/**
- * Kill all alive, non-persistent bg processes.
- * Called between auto-mode units to prevent orphaned servers from
- * keeping ports bound across task boundaries (#1209).
- */
-export function killSessionProcesses(): void {
-	for (const [id, bg] of processes) {
-		if (bg.alive && !bg.persistAcrossSessions) {
-			killProcess(id, "SIGTERM");
-		}
-	}
-}
-
 async function waitForProcessExit(bg: BgProcess, timeoutMs: number): Promise<boolean> {
 	if (!bg.alive) return true;
 	await new Promise<void>((resolve) => {
@@ -406,6 +426,13 @@ async function waitForProcessExit(bg: BgProcess, timeoutMs: number): Promise<boo
 	return !bg.alive;
 }
 
+/**
+ * Terminate the alive, non-persistent processes owned by a session, gracefully.
+ * Routes through the shared killProcessTree ladder (SIGTERM → grace → SIGKILL)
+ * via terminateProcess, with a short grace (default 300ms) so cleanup between
+ * units stays snappy; killProcessTree handles the SIGKILL escalation itself, so
+ * there is no separate force-kill pass here.
+ */
 export async function cleanupSessionProcesses(
 	sessionFile: string,
 	options?: { graceMs?: number },
@@ -417,13 +444,11 @@ export async function cleanupSessionProcesses(
 	if (matches.length === 0) return [];
 
 	for (const bg of matches) {
-		killProcess(bg.id, "SIGTERM");
+		terminateProcess(bg.id, graceMs);
 	}
 	if (graceMs > 0) {
-		await Promise.all(matches.map((bg) => waitForProcessExit(bg, graceMs)));
-	}
-	for (const bg of matches) {
-		if (bg.alive) killProcess(bg.id, "SIGKILL");
+		// Wait past the grace so the SIGKILL escalation has fired and exits are observed.
+		await Promise.all(matches.map((bg) => waitForProcessExit(bg, graceMs + 200)));
 	}
 	return matches.map((bg) => bg.id);
 }

package/src/resources/extensions/bg-shell/readiness-detector.ts

@@ -87,6 +87,18 @@ export async function waitForReady(bg: BgProcess, timeout: number, signal?: Abor
 			return { ready: false, detail: "Cancelled" };
 		}
 		if (!bg.alive) {
+			// A clean exit-0 means the command ran to completion — it was a batch
+			// command (e.g. terraform apply, a migration, a build), not a long-lived
+			// server. That is success, not a readiness failure; say so plainly and
+			// point at the right tool so the agent stops using wait_for_ready here.
+			if (bg.exitCode === 0) {
+				return {
+					ready: false,
+					detail:
+						"Process completed (exit 0) before signaling readiness — it ran to completion rather than staying alive. " +
+						"wait_for_ready is for long-lived servers/watchers; for a run-to-completion command use async_bash (or bg_shell 'run').",
+				};
+			}
 			const stderrLines = bg.output.filter(l => l.stream === "stderr").slice(-5).map(l => l.line);
 			const stderrContext = stderrLines.length > 0 ? `\nstderr:\n${stderrLines.join("\n").slice(0, 500)}` : "";
 			return {