gsd-pi 2.33.0 → 2.33.1-dev.235d83a

package/README.md

@@ -24,24 +24,19 @@ One command. Walk away. Come back to a built project with clean git history.
 
 ---
 
-## What's New in v2.32
-
-- **Simplified pipeline** — research merged into planning, mechanical completion (ADR-003)
-- **Always-on health widget** — 🟢🟡🔴 traffic-light indicator in the progress widget and visualizer health tab
-- **Environment health checks** — progress scoring and status integration for auto-mode
-- **Extension registry** — user-managed enable/disable for bundled and custom extensions
-- **Built-in skill authoring** — create and distribute custom skills from within GSD
-- **Workflow templates** — right-sized workflows for every task type (research, plan, execute, complete)
-- **AWS Bedrock auth** — automatic credential refresh via the new `aws-auth` extension
-- **`-w` / `--worktree` CLI flag** — launch isolated worktree sessions from the command line
-- **Native MCP client** — replaced MCPorter with a built-in MCP client for better reliability
-- **External state directory** — `.gsd/` now lives in `~/.gsd/projects/` with a symlink (ADR-002)
-- **Model health indicator** — live health status based on error trends and consecutive failures
-- **Quick-task branch cleanup** — `/gsd quick` branches auto-merge back after completion
-- **Windows EPERM fallback** — migration rename uses copy+delete when NTFS blocks rename
-- **Worktree identity fix** — stable project hash across worktrees and main repo
-- **Crash recovery guidance** — actionable next-step messages based on what was interrupted
-- **UAT verdict gating** — non-PASS verdicts now block slice progression instead of being ignored
+## What's New in v2.33
+
+- **Dispatch loop hardening** — defensive guards, reentrancy protection, and 125 new regression tests covering the full `deriveState → resolveDispatch` chain without an LLM
+- **Live regression test harness** — post-build pipeline validation that catches dispatch, parser, and lock lifecycle regressions before promotion
+- **Unified error handling** — `getErrorMessage()` helper replaces 65 inline duplicates across the codebase
+- **Centralized unit ID parsing** — `parseUnitId()` eliminates fragile regex patterns scattered across dispatch, recovery, and metrics code
+- **Milestone merge consolidation** — `tryMergeMilestone()` replaces 4 duplicate merge paths in the auto-mode loop
+- **Lock alignment fix** — retry lock path now matches primary lock settings, preventing `ECOMPROMISED` errors on resume
+- **NixOS/nix-darwin support** — symlinks in `.gsd/` are skipped during `makeTreeWritable` to prevent `EPERM` failures
+- **Windows EPERM fallback** — `.gsd/` migration uses copy+delete when NTFS blocks direct rename
+- **Worktree identity fix** — stable project hash resolved from main repo root, not worktree path
+- **Quick-task branch cleanup** — `/gsd quick` branches auto-merge back to the original branch after completion
+- **Crash recovery guidance** — actionable next-step messages based on what was interrupted and what state survived
 
 See the full [Changelog](./CHANGELOG.md) for details.
 

package/dist/cli.js

@@ -10,6 +10,7 @@ import { shouldRunOnboarding, runOnboarding } from './onboarding.js';
 import chalk from 'chalk';
 import { checkForUpdates } from './update-check.js';
 import { printHelp, printSubcommandHelp } from './help-text.js';
+import { markStartup, printStartupTimings } from './startup-timings.js';
 function exitIfManagedResourcesAreNewer(currentAgentDir) {
     const currentVersion = process.env.GSD_VERSION || '0.0.0';
     const managedVersion = getNewerManagedResourceVersion(currentAgentDir, currentVersion);
@@ -172,14 +173,18 @@ if (cliFlags.messages[0] === 'headless') {
 // because spawnSync(..., ["--version"]) returns EPERM despite a zero exit code.
 // Provision local managed binaries first so Pi sees them without probing PATH.
 ensureManagedTools(join(agentDir, 'bin'));
+markStartup('ensureManagedTools');
 const authStorage = AuthStorage.create(authFilePath);
+markStartup('AuthStorage.create');
 loadStoredEnvKeys(authStorage);
 migratePiCredentials(authStorage);
 // Resolve models.json path with fallback to ~/.pi/agent/models.json
 const { resolveModelsJsonPath } = await import('./models-resolver.js');
 const modelsJsonPath = resolveModelsJsonPath();
 const modelRegistry = new ModelRegistry(authStorage, modelsJsonPath);
+markStartup('ModelRegistry');
 const settingsManager = SettingsManager.create(agentDir);
+markStartup('SettingsManager.create');
 // Run onboarding wizard on first launch (no LLM provider configured)
 if (!isPrintMode && shouldRunOnboarding(authStorage, settingsManager.getDefaultProvider())) {
     await runOnboarding(authStorage);
@@ -304,12 +309,14 @@ if (isPrintMode) {
     }
     exitIfManagedResourcesAreNewer(agentDir);
     initResources(agentDir);
+    markStartup('initResources');
     const resourceLoader = new DefaultResourceLoader({
         agentDir,
         additionalExtensionPaths: cliFlags.extensions.length > 0 ? cliFlags.extensions : undefined,
         appendSystemPrompt,
     });
     await resourceLoader.reload();
+    markStartup('resourceLoader.reload');
     const { session, extensionsResult } = await createAgentSession({
         authStorage,
         modelRegistry,
@@ -317,6 +324,7 @@ if (isPrintMode) {
         sessionManager,
         resourceLoader,
     });
+    markStartup('createAgentSession');
     if (extensionsResult.errors.length > 0) {
         for (const err of extensionsResult.errors) {
             process.stderr.write(`[gsd] Extension load error: ${err.error}\n`);
@@ -333,10 +341,12 @@ if (isPrintMode) {
     }
     const mode = cliFlags.mode || 'text';
     if (mode === 'rpc') {
+        printStartupTimings();
         await runRpcMode(session);
         process.exit(0);
     }
     if (mode === 'mcp') {
+        printStartupTimings();
         const { startMcpServer } = await import('./mcp-server.js');
         await startMcpServer({
             tools: session.agent.state.tools ?? [],
@@ -345,6 +355,7 @@ if (isPrintMode) {
         // MCP server runs until the transport closes; keep alive
         await new Promise(() => { });
     }
+    printStartupTimings();
     await runPrintMode(session, {
         mode: mode,
         messages: cliFlags.messages,
@@ -431,8 +442,10 @@ const sessionManager = cliFlags._selectedSessionPath
         : SessionManager.create(cwd, projectSessionsDir);
 exitIfManagedResourcesAreNewer(agentDir);
 initResources(agentDir);
+markStartup('initResources');
 const resourceLoader = buildResourceLoader(agentDir);
 await resourceLoader.reload();
+markStartup('resourceLoader.reload');
 const { session, extensionsResult } = await createAgentSession({
     authStorage,
     modelRegistry,
@@ -440,6 +453,7 @@ const { session, extensionsResult } = await createAgentSession({
     sessionManager,
     resourceLoader,
 });
+markStartup('createAgentSession');
 if (extensionsResult.errors.length > 0) {
     for (const err of extensionsResult.errors) {
         process.stderr.write(`[gsd] Extension load error: ${err.error}\n`);
@@ -487,4 +501,6 @@ if (enabledModelPatterns && enabledModelPatterns.length > 0) {
     }
 }
 const interactiveMode = new InteractiveMode(session);
+markStartup('InteractiveMode');
+printStartupTimings();
 await interactiveMode.run();

package/dist/resource-loader.d.ts

@@ -1,5 +1,6 @@
 import { DefaultResourceLoader } from '@gsd/pi-coding-agent';
 export { discoverExtensionEntryPaths } from './extension-discovery.js';
+export declare function getExtensionKey(entryPath: string, extensionsDir: string): string;
 export declare function readManagedResourceVersion(agentDir: string): string | null;
 export declare function getNewerManagedResourceVersion(agentDir: string, currentVersion: string): string | null;
 /**
@@ -18,4 +19,5 @@ export declare function getNewerManagedResourceVersion(agentDir: string, current
  * Inspectable: `ls ~/.gsd/agent/extensions/`
  */
 export declare function initResources(agentDir: string): void;
+export declare function hasStaleCompiledExtensionSiblings(extensionsDir: string): boolean;
 export declare function buildResourceLoader(agentDir: string): DefaultResourceLoader;

package/dist/resource-loader.js

@@ -22,9 +22,9 @@ const resourcesDir = existsSync(distResources) ? distResources : srcResources;
 const bundledExtensionsDir = join(resourcesDir, 'extensions');
 const resourceVersionManifestName = 'managed-resources.json';
 export { discoverExtensionEntryPaths } from './extension-discovery.js';
-function getExtensionKey(entryPath, extensionsDir) {
+export function getExtensionKey(entryPath, extensionsDir) {
     const relPath = relative(extensionsDir, entryPath);
-    return relPath.split(/[\\/]/)[0];
+    return relPath.split(/[\\/]/)[0].replace(/\.(?:ts|js)$/, '');
 }
 function getManagedResourceManifestPath(agentDir) {
     return join(agentDir, resourceVersionManifestName);
@@ -158,6 +158,7 @@ function makeTreeWritable(dirPath) {
 function syncResourceDir(srcDir, destDir) {
     makeTreeWritable(destDir);
     if (existsSync(srcDir)) {
+        pruneStaleSiblingFiles(srcDir, destDir);
         for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
             if (entry.isDirectory()) {
                 const target = join(destDir, entry.name);
@@ -176,6 +177,24 @@ function syncResourceDir(srcDir, destDir) {
         makeTreeWritable(destDir);
     }
 }
+function pruneStaleSiblingFiles(srcDir, destDir) {
+    if (!existsSync(destDir))
+        return;
+    const sourceFiles = new Set(readdirSync(srcDir, { withFileTypes: true })
+        .filter((entry) => entry.isFile())
+        .map((entry) => entry.name));
+    for (const entry of readdirSync(destDir, { withFileTypes: true })) {
+        if (!entry.isFile())
+            continue;
+        if (sourceFiles.has(entry.name))
+            continue;
+        const sourceJsName = entry.name.replace(/\.ts$/, '.js');
+        const sourceTsName = entry.name.replace(/\.js$/, '.ts');
+        if (sourceFiles.has(sourceJsName) || sourceFiles.has(sourceTsName)) {
+            rmSync(join(destDir, entry.name), { force: true });
+        }
+    }
+}
 /**
  * Recursive directory copy using copyFileSync — workaround for cpSync failures
  * on Windows paths containing non-ASCII characters (#1178).
@@ -218,7 +237,8 @@ export function initResources(agentDir) {
     if (manifest && manifest.gsdVersion === currentVersion) {
         // Version matches — check content fingerprint for same-version staleness.
         const currentHash = computeResourceFingerprint();
-        if (manifest.contentHash && manifest.contentHash === currentHash) {
+        const hasStaleExtensionFiles = hasStaleCompiledExtensionSiblings(join(agentDir, 'extensions'));
+        if (manifest.contentHash && manifest.contentHash === currentHash && !hasStaleExtensionFiles) {
             return;
         }
     }
@@ -231,6 +251,19 @@ export function initResources(agentDir) {
     writeManagedResourceManifest(agentDir);
     ensureRegistryEntries(join(agentDir, 'extensions'));
 }
+export function hasStaleCompiledExtensionSiblings(extensionsDir) {
+    if (!existsSync(extensionsDir))
+        return false;
+    for (const entry of readdirSync(extensionsDir, { withFileTypes: true })) {
+        if (!entry.isFile() || !entry.name.endsWith('.ts'))
+            continue;
+        const jsName = entry.name.replace(/\.ts$/, '.js');
+        if (existsSync(join(extensionsDir, jsName))) {
+            return true;
+        }
+    }
+    return false;
+}
 /**
  * Constructs a DefaultResourceLoader that loads extensions from both
  * ~/.gsd/agent/extensions/ (GSD's default) and ~/.pi/agent/extensions/ (pi's default).

package/dist/resources/extensions/ask-user-questions.js

@@ -0,0 +1,217 @@
+/**
+ * Request User Input — LLM tool for asking the user questions
+ *
+ * Thin wrapper around the shared interview-ui. The LLM presents 1-3
+ * questions with 2-3 options each. Each question can be single-select (default)
+ * or multi-select (allowMultiple: true). A free-form "None of the above" option
+ * is added automatically to single-select questions.
+ *
+ * Based on: https://github.com/openai/codex (codex-rs/core/src/tools/handlers/ask_user_questions.rs)
+ */
+import { sanitizeError } from "./shared/sanitize.js";
+import { Text } from "@gsd/pi-tui";
+import { Type } from "@sinclair/typebox";
+import { showInterviewRound, } from "./shared/mod.js";
+// ─── Schema ───────────────────────────────────────────────────────────────────
+const OptionSchema = Type.Object({
+    label: Type.String({ description: "User-facing label (1-5 words)" }),
+    description: Type.String({ description: "One short sentence explaining impact/tradeoff if selected" }),
+});
+const QuestionSchema = Type.Object({
+    id: Type.String({ description: "Stable identifier for mapping answers (snake_case)" }),
+    header: Type.String({ description: "Short header label shown in the UI (12 or fewer chars)" }),
+    question: Type.String({ description: "Single-sentence prompt shown to the user" }),
+    options: Type.Array(OptionSchema, {
+        description: 'Provide 2-3 mutually exclusive choices for single-select, or any number for multi-select. Put the recommended option first and suffix its label with "(Recommended)". Do not include an "Other" option for single-select; the client adds a free-form "None of the above" option automatically.',
+    }),
+    allowMultiple: Type.Optional(Type.Boolean({
+        description: "If true, the user can select multiple options using SPACE to toggle and ENTER to confirm. No 'None of the above' option is added. Default: false.",
+    })),
+});
+const AskUserQuestionsParams = Type.Object({
+    questions: Type.Array(QuestionSchema, {
+        description: "Questions to show the user. Prefer 1 and do not exceed 3.",
+    }),
+});
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+const OTHER_OPTION_LABEL = "None of the above";
+function errorResult(message, questions = []) {
+    return {
+        content: [{ type: "text", text: sanitizeError(message) }],
+        details: { questions, response: null, cancelled: true },
+    };
+}
+/** Convert the shared RoundResult into the JSON the LLM expects. */
+function formatForLLM(result) {
+    const answers = {};
+    for (const [id, answer] of Object.entries(result.answers)) {
+        const list = [];
+        if (Array.isArray(answer.selected)) {
+            list.push(...answer.selected);
+        }
+        else {
+            list.push(answer.selected);
+        }
+        if (answer.notes) {
+            list.push(`user_note: ${answer.notes}`);
+        }
+        answers[id] = { answers: list };
+    }
+    return JSON.stringify({ answers });
+}
+// ─── Extension ────────────────────────────────────────────────────────────────
+export default function AskUserQuestions(pi) {
+    pi.registerTool({
+        name: "ask_user_questions",
+        label: "Request User Input",
+        description: "Request user input for one to three short questions and wait for the response. Single-select questions have 2-3 mutually exclusive options with a free-form 'None of the above' added automatically. Multi-select questions (allowMultiple: true) let the user toggle multiple options with SPACE and confirm with ENTER.",
+        promptGuidelines: [
+            "Use ask_user_questions when you need the user to choose between concrete alternatives before proceeding.",
+            "Keep questions to 1 when possible; never exceed 3.",
+            "For single-select: each question must have 2-3 options. Put the recommended option first with '(Recommended)' suffix. Do not include an 'Other' or 'None of the above' option - the client adds one automatically.",
+            "For multi-select: set allowMultiple: true. The user can pick any number of options. No 'None of the above' is added.",
+        ],
+        parameters: AskUserQuestionsParams,
+        async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+            // Validation
+            if (params.questions.length === 0 || params.questions.length > 3) {
+                return errorResult("Error: questions must contain 1-3 items", params.questions);
+            }
+            for (const q of params.questions) {
+                if (!q.options || q.options.length === 0) {
+                    return errorResult(`Error: ask_user_questions requires non-empty options for every question (question "${q.id}" has none)`, params.questions);
+                }
+            }
+            if (!ctx.hasUI) {
+                const { tryRemoteQuestions } = await import("./remote-questions/manager.js");
+                const remoteResult = await tryRemoteQuestions(params.questions, signal);
+                if (remoteResult)
+                    return { ...remoteResult, details: remoteResult.details };
+                return errorResult("Error: UI not available (non-interactive mode)", params.questions);
+            }
+            // Delegate to shared interview UI
+            const result = await showInterviewRound(params.questions, {}, ctx);
+            // RPC mode fallback: custom() returns undefined, so showInterviewRound
+            // may return undefined. Fall back to sequential ctx.ui.select() calls.
+            if (!result) {
+                const answers = {};
+                for (const q of params.questions) {
+                    const options = q.options.map((o) => o.label);
+                    if (!q.allowMultiple) {
+                        options.push(OTHER_OPTION_LABEL);
+                    }
+                    const selected = await ctx.ui.select(`${q.header}: ${q.question}`, options, { signal, ...(q.allowMultiple ? { allowMultiple: true } : {}) });
+                    if (selected === undefined) {
+                        return errorResult("ask_user_questions was cancelled", params.questions);
+                    }
+                    answers[q.id] = {
+                        answers: Array.isArray(selected) ? selected : [selected],
+                    };
+                }
+                const roundResult = {
+                    endInterview: false,
+                    answers: Object.fromEntries(Object.entries(answers).map(([id, a]) => [
+                        id,
+                        { selected: a.answers.length === 1 ? a.answers[0] : a.answers, notes: "" },
+                    ])),
+                };
+                return {
+                    content: [{ type: "text", text: JSON.stringify({ answers }) }],
+                    details: {
+                        questions: params.questions,
+                        response: roundResult,
+                        cancelled: false,
+                    },
+                };
+            }
+            // Check if cancelled (empty answers = user exited)
+            const hasAnswers = Object.keys(result.answers).length > 0;
+            if (!hasAnswers) {
+                return {
+                    content: [{ type: "text", text: "ask_user_questions was cancelled before receiving a response" }],
+                    details: { questions: params.questions, response: null, cancelled: true },
+                };
+            }
+            return {
+                content: [{ type: "text", text: formatForLLM(result) }],
+                details: { questions: params.questions, response: result, cancelled: false },
+            };
+        },
+        // ─── Rendering ────────────────────────────────────────────────────────
+        renderCall(args, theme) {
+            const qs = args.questions || [];
+            let text = theme.fg("toolTitle", theme.bold("ask_user_questions "));
+            text += theme.fg("muted", `${qs.length} question${qs.length !== 1 ? "s" : ""}`);
+            if (qs.length > 0) {
+                const headers = qs.map((q) => q.header).join(", ");
+                text += theme.fg("dim", ` (${headers})`);
+            }
+            for (const q of qs) {
+                const multiSel = !!q.allowMultiple;
+                text += `\n  ${theme.fg("text", q.question)}`;
+                const optLabels = multiSel
+                    ? (q.options || []).map((o) => o.label)
+                    : [...(q.options || []).map((o) => o.label), OTHER_OPTION_LABEL];
+                const prefix = multiSel ? "☐" : "";
+                const numbered = optLabels.map((l, i) => `${prefix}${i + 1}. ${l}`).join(", ");
+                text += `\n  ${theme.fg("dim", numbered)}`;
+            }
+            return new Text(text, 0, 0);
+        },
+        renderResult(result, _options, theme) {
+            const details = result.details;
+            if (!details) {
+                const text = result.content[0];
+                return new Text(text?.type === "text" ? text.text : "", 0, 0);
+            }
+            // Remote channel result (discriminated on details.remote === true)
+            if (details.remote) {
+                if (details.timed_out) {
+                    return new Text(`${theme.fg("warning", `${details.channel} — timed out`)}${details.threadUrl ? theme.fg("dim", ` ${details.threadUrl}`) : ""}`, 0, 0);
+                }
+                const questions = (details.questions ?? []);
+                const lines = [];
+                lines.push(theme.fg("dim", details.channel));
+                if (details.response) {
+                    for (const q of questions) {
+                        const answer = details.response.answers[q.id];
+                        if (!answer) {
+                            lines.push(`${theme.fg("accent", q.header)}: ${theme.fg("dim", "(no answer)")}`);
+                            continue;
+                        }
+                        const answerText = answer.answers.length > 0 ? answer.answers.join(", ") : "(custom)";
+                        let line = `${theme.fg("success", "✓ ")}${theme.fg("accent", q.header)}: ${answerText}`;
+                        if (answer.user_note) {
+                            line += ` ${theme.fg("muted", `[note: ${answer.user_note}]`)}`;
+                        }
+                        lines.push(line);
+                    }
+                }
+                return new Text(lines.join("\n"), 0, 0);
+            }
+            if (details.cancelled || !details.response) {
+                return new Text(theme.fg("warning", "Cancelled"), 0, 0);
+            }
+            const lines = [];
+            for (const q of details.questions) {
+                const answer = details.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);
+        },
+    });
+}

package/dist/resources/extensions/async-jobs/async-bash-tool.js

@@ -0,0 +1,180 @@
+/**
+ * async_bash tool — run a bash command in the background.
+ *
+ * Registers the command with the AsyncJobManager and returns a job ID
+ * immediately. The LLM can continue working and check results later
+ * with await_job.
+ */
+import { getShellConfig, sanitizeCommand, DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, } from "@gsd/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import { spawn } from "node:child_process";
+import { createWriteStream } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { randomBytes } from "node:crypto";
+const schema = Type.Object({
+    command: Type.String({ description: "Bash command to execute in the background" }),
+    timeout: Type.Optional(Type.Number({ description: "Timeout in seconds (optional)" })),
+    label: Type.Optional(Type.String({ description: "Short label for the job (shown in /jobs). Defaults to a truncated version of the command." })),
+});
+function getTempFilePath() {
+    const id = randomBytes(8).toString("hex");
+    return join(tmpdir(), `pi-async-bash-${id}.log`);
+}
+/**
+ * Kill a process and its children. Uses process group kill on Unix.
+ */
+function killTree(pid) {
+    try {
+        // Kill the process group (negative PID)
+        process.kill(-pid, "SIGTERM");
+    }
+    catch {
+        try {
+            process.kill(pid, "SIGTERM");
+        }
+        catch {
+            // Already exited
+        }
+    }
+}
+export function createAsyncBashTool(getManager, getCwd) {
+    return {
+        name: "async_bash",
+        label: "Background Bash",
+        description: `Run a bash command in the background. Returns a job ID immediately so you can continue working. ` +
+            `Use await_job to get results or cancel_job to stop. Ideal for long-running builds, tests, or installs. ` +
+            `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).",
+            "After starting async jobs, continue with other work and use await_job when you need the results.",
+            "Use cancel_job to stop a running background job.",
+            "Check /jobs to see all running and recent background jobs.",
+        ],
+        parameters: schema,
+        async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+            const manager = getManager();
+            const cwd = getCwd();
+            const { command, timeout, label } = params;
+            const shortCmd = label ?? (command.length > 60 ? command.slice(0, 57) + "..." : command);
+            const jobId = manager.register("bash", shortCmd, (signal) => {
+                return executeBashInBackground(command, cwd, signal, timeout);
+            });
+            return {
+                content: [{
+                        type: "text",
+                        text: [
+                            `Background job started: **${jobId}**`,
+                            `Command: \`${shortCmd}\``,
+                            "",
+                            "Use `await_job` to get results when ready, or `cancel_job` to stop.",
+                        ].join("\n"),
+                    }],
+                details: undefined,
+            };
+        },
+    };
+}
+/**
+ * Execute a bash command, collecting output. Returns the text result.
+ */
+function executeBashInBackground(command, cwd, signal, timeout) {
+    return new Promise((resolve, reject) => {
+        const { shell, args } = getShellConfig();
+        const resolvedCommand = sanitizeCommand(command);
+        const child = spawn(shell, [...args, resolvedCommand], {
+            cwd,
+            detached: true,
+            env: { ...process.env },
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let timedOut = false;
+        let timeoutHandle;
+        if (timeout !== undefined && timeout > 0) {
+            timeoutHandle = setTimeout(() => {
+                timedOut = true;
+                if (child.pid)
+                    killTree(child.pid);
+            }, timeout * 1000);
+        }
+        const chunks = [];
+        let totalBytes = 0;
+        let spillFilePath;
+        let spillStream;
+        const MAX_BUFFER = DEFAULT_MAX_BYTES * 2;
+        const onData = (data) => {
+            totalBytes += data.length;
+            if (totalBytes > DEFAULT_MAX_BYTES && !spillFilePath) {
+                spillFilePath = getTempFilePath();
+                spillStream = createWriteStream(spillFilePath);
+                for (const chunk of chunks)
+                    spillStream.write(chunk);
+            }
+            if (spillStream)
+                spillStream.write(data);
+            chunks.push(data);
+            let chunksBytes = chunks.reduce((s, c) => s + c.length, 0);
+            while (chunksBytes > MAX_BUFFER && chunks.length > 1) {
+                const removed = chunks.shift();
+                chunksBytes -= removed.length;
+            }
+        };
+        if (child.stdout)
+            child.stdout.on("data", onData);
+        if (child.stderr)
+            child.stderr.on("data", onData);
+        const onAbort = () => {
+            if (child.pid)
+                killTree(child.pid);
+        };
+        if (signal.aborted) {
+            onAbort();
+        }
+        else {
+            signal.addEventListener("abort", onAbort, { once: true });
+        }
+        child.on("error", (err) => {
+            if (timeoutHandle)
+                clearTimeout(timeoutHandle);
+            signal.removeEventListener("abort", onAbort);
+            reject(err);
+        });
+        child.on("close", (code) => {
+            if (timeoutHandle)
+                clearTimeout(timeoutHandle);
+            signal.removeEventListener("abort", onAbort);
+            if (spillStream)
+                spillStream.end();
+            if (signal.aborted) {
+                const output = Buffer.concat(chunks).toString("utf-8");
+                resolve(output ? `${output}\n\nCommand aborted` : "Command aborted");
+                return;
+            }
+            if (timedOut) {
+                const output = Buffer.concat(chunks).toString("utf-8");
+                resolve(output ? `${output}\n\nCommand timed out after ${timeout} seconds` : `Command timed out after ${timeout} seconds`);
+                return;
+            }
+            const fullOutput = Buffer.concat(chunks).toString("utf-8");
+            const lines = fullOutput.split("\n");
+            let text;
+            if (lines.length > DEFAULT_MAX_LINES) {
+                text = lines.slice(-DEFAULT_MAX_LINES).join("\n");
+                if (spillFilePath) {
+                    text += `\n\n[Showing last ${DEFAULT_MAX_LINES} of ${lines.length} lines. Full output: ${spillFilePath}]`;
+                }
+                else {
+                    text += `\n\n[Showing last ${DEFAULT_MAX_LINES} of ${lines.length} lines]`;
+                }
+            }
+            else {
+                text = fullOutput || "(no output)";
+            }
+            if (code !== 0 && code !== null) {
+                text += `\n\nCommand exited with code ${code}`;
+            }
+            resolve(text);
+        });
+    });
+}