@opengsd/gsd-pi 1.2.0-dev.b1abb545 → 1.2.0-dev.fb12b103

package/dist/resources/extensions/bg-shell/bg-shell-command.js

@@ -3,7 +3,7 @@
  */
 import { Key } from "@gsd/pi-tui";
 import { shortcutDesc } from "../shared/terminal.js";
-import { processes, killProcess, getGroupStatus, cleanupAll, } from "./process-manager.js";
+import { processes, terminateProcess, getGroupStatus, cleanupAll, } from "./process-manager.js";
 import { generateDigest, getOutput, formatDigestText, } from "./output-formatter.js";
 import { formatUptime } from "./utilities.js";
 import { BgManagerOverlay } from "./overlay.js";
@@ -119,11 +119,11 @@ export function registerBgShellCommand(pi, state) {
                     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);

package/dist/resources/extensions/bg-shell/bg-shell-tool.js

@@ -4,7 +4,7 @@
 import { StringEnum, Type } from "@gsd/pi-ai";
 import { Text } from "@gsd/pi-tui";
 import { DEFAULT_READY_TIMEOUT } from "./types.js";
-import { processes, startProcess, killProcess, restartProcess, getInfo, getGroupStatus, persistManifest, } from "./process-manager.js";
+import { processes, startProcess, killProcess, terminateProcess, restartProcess, getInfo, getGroupStatus, persistManifest, } from "./process-manager.js";
 import { generateDigest, getHighlights, getOutput, formatDigestText, } from "./output-formatter.js";
 import { waitForReady } from "./readiness-detector.js";
 import { queryShellEnv, sendAndWait, runOnSession } from "./interaction.js";
@@ -22,7 +22,8 @@ export function registerBgShellTool(pi, state) {
             "signal (send OS signal), list (all processes with status), kill (terminate), restart (kill + relaunch), " +
             "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.",
@@ -511,11 +512,13 @@ export function registerBgShellTool(pi, state) {
                             isError: true, details: undefined,
                         };
                     }
-                    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);
                     if (!bg.alive)

package/dist/resources/extensions/bg-shell/overlay.js

@@ -4,7 +4,7 @@
 import { truncateToWidth, visibleWidth, matchesKey, Key } from "@gsd/pi-tui";
 import { ERROR_PATTERNS, WARNING_PATTERNS } from "./types.js";
 import { formatUptime, formatTimeAgo } from "./utilities.js";
-import { processes, killProcess, cleanupAll, restartProcess, } from "./process-manager.js";
+import { processes, terminateProcess, cleanupAll, restartProcess, } from "./process-manager.js";
 export class BgManagerOverlay {
     tui;
     theme;
@@ -110,17 +110,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/dist/resources/extensions/bg-shell/process-manager.js

@@ -6,7 +6,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 { MAX_BUFFER_LINES, MAX_EVENTS, DEAD_PROCESS_TTL, } from "./types.js";
 import { restoreWindowsVTInput, formatUptime } from "./utilities.js";
@@ -221,6 +221,38 @@ export function startProcess(opts) {
     return bg;
 }
 // ── 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, graceMs) {
+    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, sig = "SIGTERM") {
     const bg = processes.get(id);
     if (!bg)
@@ -272,13 +304,14 @@ export async function restartProcess(id) {
         return 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);
@@ -328,24 +361,16 @@ export function pruneDeadProcesses() {
     }
 }
 export function cleanupAll() {
+    // 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() {
-    for (const [id, bg] of processes) {
-        if (bg.alive && !bg.persistAcrossSessions) {
-            killProcess(id, "SIGTERM");
-        }
-    }
-}
 async function waitForProcessExit(bg, timeoutMs) {
     if (!bg.alive)
         return true;
@@ -359,20 +384,24 @@ async function waitForProcessExit(bg, timeoutMs) {
     });
     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, options) {
     const graceMs = Math.max(0, options?.graceMs ?? 300);
     const matches = Array.from(processes.values()).filter((bg) => bg.alive && !bg.persistAcrossSessions && bg.ownerSessionFile === sessionFile);
     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/dist/resources/extensions/bg-shell/readiness-detector.js

@@ -72,6 +72,17 @@ export async function waitForReady(bg, timeout, signal) {
             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/dist/resources/extensions/bg-shell/utilities.js

@@ -37,10 +37,13 @@ export const formatUptime = formatDuration;
 export function formatTimeAgo(timestamp) {
     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) {
     if (!cachedCwd)
         return undefined;
-    const match = cachedCwd.match(/^(.*?)[\\/]\.gsd[\\/]worktrees[\\/][^\\/]+(?:[\\/].*)?$/);
+    const match = cachedCwd.match(/^(.*?)[\\/]\.gsd(?:-worktrees|[\\/]worktrees)[\\/][^\\/]+(?:[\\/].*)?$/);
     return match?.[1];
 }
 export function getBgShellLiveCwd(cachedCwd, pathExists = existsSync, getCwd = () => process.cwd(), chdir = (path) => process.chdir(path)) {
@@ -67,7 +70,7 @@ export function getBgShellLiveCwd(cachedCwd, pathExists = existsSync, getCwd = (
 }
 export function resolveBgShellPersistenceCwd(cachedCwd, liveCwd = undefined, pathExists = existsSync) {
     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))