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

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 {

package/src/resources/extensions/bg-shell/tests/lifecycle-and-utilities.test.ts

@@ -1,7 +1,7 @@
 import { describe, test } from "node:test";
 import assert from "node:assert/strict";
 import type { BgProcess } from "../types.ts";
-import { detectProcessType } from "../process-manager.ts";
+import { detectProcessType, startProcess, terminateProcess, processes } from "../process-manager.ts";
 import { waitForReady } from "../readiness-detector.ts";
 import {
   formatTimeAgo,
@@ -108,6 +108,18 @@ describe("bg-shell waitForReady", () => {
     assert.match(result.detail, /137/);
   });
 
+  test("a clean exit-0 reads as completion, not a crash, and points at the right tool", async () => {
+    // Regression: a run-to-completion batch command (e.g. terraform apply) put
+    // under wait_for_ready exits 0 on success. It must NOT be framed as a crash;
+    // it should say it completed and steer toward async_bash.
+    const bg = makeBg({ alive: false, exitCode: 0 });
+    const result = await waitForReady(bg, 1000);
+    assert.equal(result.ready, false);
+    assert.match(result.detail, /completed \(exit 0\)/);
+    assert.match(result.detail, /async_bash/);
+    assert.doesNotMatch(result.detail, /exited before becoming ready/);
+  });
+
   test("reports failure when the process entered an error state", async () => {
     const bg = makeBg({ status: "error", readyPort: 5173 });
     const result = await waitForReady(bg, 1000);
@@ -204,3 +216,38 @@ describe("bg-shell resolveBgShellPersistenceCwd", () => {
     assert.equal(result, "/proj/.gsd/worktrees/feature-b");
   });
 });
+
+describe("bg-shell terminateProcess (graceful kill ladder)", () => {
+  test(
+    "force-kills a SIGTERM-immune process via the shared killProcessTree ladder",
+    { skip: process.platform === "win32" ? "Unix-primary graceful semantics" : false, timeout: 15_000 },
+    async (t) => {
+      // A process that ignores SIGTERM must still die — terminateProcess routes
+      // through killProcessTree, which escalates SIGTERM → grace → SIGKILL. A bare
+      // single-signal kill (the old behavior) would have left this running.
+      const bg = startProcess({
+        command: "trap '' TERM; while true; do sleep 1; done",
+        cwd: "/tmp",
+        label: "sigterm-immune",
+        type: "generic",
+      });
+      t.after(() => {
+        try { if (bg.proc.pid) process.kill(-bg.proc.pid, "SIGKILL"); } catch { /* gone */ }
+        processes.delete(bg.id);
+      });
+
+      // Let the trap install.
+      await new Promise((r) => setTimeout(r, 300));
+      assert.equal(bg.alive, true, "process should be alive before terminate");
+
+      terminateProcess(bg.id);
+
+      // SIGKILL fires after the 5s grace; poll up to grace + slack.
+      const deadline = Date.now() + 9_000;
+      while (bg.alive && Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 100));
+      }
+      assert.equal(bg.alive, false, "SIGTERM-immune process must be SIGKILLed via the ladder, not left running");
+    },
+  );
+});

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

@@ -43,9 +43,12 @@ export function formatTimeAgo(timestamp: number): string {
 	return formatDuration(Date.now() - timestamp) + " ago";
 }
 
+// NOTE: these worktree-layout regexes mirror findWorktreeSegment in
+// src/resources/extensions/gsd/worktree-root.ts (bg-shell does not import the
+// gsd extension). Keep them synchronized when a layout changes.
 function deriveProjectRootFromAutoWorktree(cachedCwd?: string): string | undefined {
 	if (!cachedCwd) return undefined;
-	const match = cachedCwd.match(/^(.*?)[\\/]\.gsd[\\/]worktrees[\\/][^\\/]+(?:[\\/].*)?$/);
+	const match = cachedCwd.match(/^(.*?)[\\/]\.gsd(?:-worktrees|[\\/]worktrees)[\\/][^\\/]+(?:[\\/].*)?$/);
 	return match?.[1];
 }
 
@@ -84,7 +87,7 @@ export function resolveBgShellPersistenceCwd(
 	pathExists: (path: string) => boolean = existsSync,
 ): string {
 	const resolvedLiveCwd = liveCwd ?? getBgShellLiveCwd(cachedCwd, pathExists);
-	const cachedIsAutoWorktree = /(?:^|[\\/])\.gsd[\\/]worktrees[\\/]/.test(cachedCwd);
+	const cachedIsAutoWorktree = /(?:^|[\\/])\.gsd(?:-worktrees|[\\/]worktrees)[\\/]/.test(cachedCwd);
 	if (!cachedIsAutoWorktree) return cachedCwd;
 	if (cachedCwd === resolvedLiveCwd && pathExists(cachedCwd)) return cachedCwd;
 	if (!pathExists(cachedCwd)) return resolvedLiveCwd;