@aexol/spectral 0.9.115 → 0.9.117

package/dist/extensions/browser/config.d.ts

@@ -14,9 +14,32 @@ export interface BrowserConfig {
         width: number;
         height: number;
     };
-    /** Whether to run the browser headless during recordings. Defaults to false
-     * (headful) for higher-quality video capture, mirroring the demo recorder. */
     recordHeadless: boolean;
 }
+/**
+ * Resolve a (possibly relative) output directory to an absolute path.
+ *
+ * - Absolute paths are returned as-is (normalized).
+ * - Relative paths are resolved against `cwd` when provided, otherwise against
+ *   `$HOME` — matching the convention in `server/paths.ts` (the server process
+ *   runs from `$HOME`, so relative-to-home matches the user's mental model).
+ *
+ * This prevents browser screenshots/recordings from leaking into
+ * `~/.spectral/browser-output/` when the extension is loaded from a server
+ * whose `process.cwd()` is the home directory rather than the project root.
+ */
+/**
+ * Resolve a (possibly relative) output directory to an absolute path.
+ *
+ * - Absolute paths are returned as-is (normalized).
+ * - Relative paths are resolved against `cwd` when provided, otherwise against
+ *   `$HOME` — matching the convention in `server/paths.ts` (the server process
+ *   runs from `$HOME`, so relative-to-home matches the user's mental model).
+ *
+ * This prevents browser screenshots/recordings from leaking into
+ * `~/.spectral/browser-output/` when the extension is loaded from a server
+ * whose `process.cwd()` is the home directory rather than the project root.
+ */
+export declare function resolveOutputDir(input: string, cwd?: string): string;
 export declare function getBrowserConfig(): BrowserConfig;
 //# sourceMappingURL=config.d.ts.map

package/dist/extensions/browser/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/extensions/browser/config.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;IAC/C,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACnD;kFAC8E;IAC9E,cAAc,EAAE,OAAO,CAAC;CACzB;AACD,wBAAgB,gBAAgB,IAAI,aAAa,CAgBhD"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/extensions/browser/config.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;IAC/C,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACnD,cAAc,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;GAWG;AACH;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAIpE;AAED,wBAAgB,gBAAgB,IAAI,aAAa,CAgBhD"}

package/dist/extensions/browser/config.js

@@ -1,3 +1,35 @@
+import { homedir } from "node:os";
+import { isAbsolute, resolve } from "node:path";
+/**
+ * Resolve a (possibly relative) output directory to an absolute path.
+ *
+ * - Absolute paths are returned as-is (normalized).
+ * - Relative paths are resolved against `cwd` when provided, otherwise against
+ *   `$HOME` — matching the convention in `server/paths.ts` (the server process
+ *   runs from `$HOME`, so relative-to-home matches the user's mental model).
+ *
+ * This prevents browser screenshots/recordings from leaking into
+ * `~/.spectral/browser-output/` when the extension is loaded from a server
+ * whose `process.cwd()` is the home directory rather than the project root.
+ */
+/**
+ * Resolve a (possibly relative) output directory to an absolute path.
+ *
+ * - Absolute paths are returned as-is (normalized).
+ * - Relative paths are resolved against `cwd` when provided, otherwise against
+ *   `$HOME` — matching the convention in `server/paths.ts` (the server process
+ *   runs from `$HOME`, so relative-to-home matches the user's mental model).
+ *
+ * This prevents browser screenshots/recordings from leaking into
+ * `~/.spectral/browser-output/` when the extension is loaded from a server
+ * whose `process.cwd()` is the home directory rather than the project root.
+ */
+export function resolveOutputDir(input, cwd) {
+    if (isAbsolute(input))
+        return resolve(input);
+    const base = cwd ?? homedir();
+    return resolve(base, input);
+}
 export function getBrowserConfig() {
     return {
         browserName: process.env.BROWSER_NAME ?? "chromium",
@@ -8,9 +40,9 @@ export function getBrowserConfig() {
         },
         navigationTimeout: Number(process.env.BROWSER_NAVIGATION_TIMEOUT) || 60_000,
         actionTimeout: Number(process.env.BROWSER_ACTION_TIMEOUT) || 5_000,
-        outputDir: process.env.BROWSER_OUTPUT_DIR ?? ".spectral/browser-output",
+        outputDir: resolveOutputDir(process.env.BROWSER_OUTPUT_DIR ?? ".spectral/browser-output"),
         debug: process.env.BROWSER_DEBUG === "true" ? true : false,
-        recordOutputDir: process.env.BROWSER_RECORD_DIR ?? ".spectral/browser-recordings",
+        recordOutputDir: resolveOutputDir(process.env.BROWSER_RECORD_DIR ?? ".spectral/browser-recordings"),
         recordViewport: undefined, // defaults to viewport via code
         recordHeadless: process.env.BROWSER_RECORD_HEADLESS === "true" ? true : false,
     };

package/dist/extensions/browser/scenario/scenario-tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scenario-tool.d.ts","sourceRoot":"","sources":["../../../../src/extensions/browser/scenario/scenario-tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,oCAAoC,CAAC;AACvF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAsC5D,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,YAAY,EAAE,EAAE,EAAE,cAAc,GAAG,IAAI,CA+VjF"}
+{"version":3,"file":"scenario-tool.d.ts","sourceRoot":"","sources":["../../../../src/extensions/browser/scenario/scenario-tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,oCAAoC,CAAC;AACvF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAuC5D,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,YAAY,EAAE,EAAE,EAAE,cAAc,GAAG,IAAI,CAgWjF"}

package/dist/extensions/browser/scenario/scenario-tool.js

@@ -1,3 +1,4 @@
+import { resolveOutputDir } from "../config.js";
 import { parseMarkdownScenarioFile, } from "./markdown-parser.js";
 function sleep(ms) {
     return new Promise((r) => setTimeout(r, ms));
@@ -82,7 +83,7 @@ export function registerScenarioTools(ext, bs) {
             },
             required: ["url"],
         },
-        async execute(_toolCallId, params) {
+        async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
             const p = params;
             if (!p.url) {
                 return {
@@ -272,9 +273,10 @@ export function registerScenarioTools(ext, bs) {
                             case "screenshot": {
                                 const config = bs.getConfig();
                                 const { mkdirSync } = await import("node:fs");
-                                mkdirSync(config.outputDir, { recursive: true });
+                                const outDir = resolveOutputDir(config.outputDir, ctx.cwd);
+                                mkdirSync(outDir, { recursive: true });
                                 const ts = new Date().toISOString().replace(/[:.]/g, "-");
-                                const filepath = `${config.outputDir}/scenario-step-${i + 1}-${ts}.png`;
+                                const filepath = `${outDir}/scenario-step-${i + 1}-${ts}.png`;
                                 await page.screenshot({ path: filepath });
                                 detail = `Screenshot: ${filepath}`;
                                 break;

package/dist/extensions/browser/tools/screenshot.d.ts

@@ -1,6 +1,3 @@
-/**
- * Screenshot & snapshot tools: browser_take_screenshot, browser_snapshot.
- */
 import type { ExtensionAPI } from "../../../sdk/coding-agent/index.js";
 import { BrowserService } from "../browser-service.js";
 export declare function registerScreenshotTools(ext: ExtensionAPI, bs: BrowserService): void;

package/dist/extensions/browser/tools/screenshot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"screenshot.d.ts","sourceRoot":"","sources":["../../../../src/extensions/browser/tools/screenshot.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,oCAAoC,CAAC;AACvF,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,YAAY,EAAE,EAAE,EAAE,cAAc,GAAG,IAAI,CAiKnF"}
+{"version":3,"file":"screenshot.d.ts","sourceRoot":"","sources":["../../../../src/extensions/browser/tools/screenshot.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAkB,MAAM,oCAAoC,CAAC;AAEvF,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,YAAY,EAAE,EAAE,EAAE,cAAc,GAAG,IAAI,CA8InF"}

package/dist/extensions/browser/tools/screenshot.js

@@ -1,8 +1,6 @@
-/**
- * Screenshot & snapshot tools: browser_take_screenshot, browser_snapshot.
- */
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { resolveOutputDir } from "../config.js";
 export function registerScreenshotTools(ext, bs) {
     const screenshotTool = {
         name: "browser_take_screenshot",
@@ -29,14 +27,15 @@ export function registerScreenshotTools(ext, bs) {
                 },
             },
         },
-        async execute(_toolCallId, params) {
+        async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
             const p = params;
             try {
                 const page = bs.getActivePage();
                 const config = bs.getConfig();
-                mkdirSync(config.outputDir, { recursive: true });
+                const outDir = resolveOutputDir(config.outputDir, ctx.cwd);
+                mkdirSync(outDir, { recursive: true });
                 const filename = p.filename ?? `screenshot-${Date.now()}.${p.type ?? "png"}`;
-                const filepath = join(config.outputDir, filename);
+                const filepath = join(outDir, filename);
                 await page.screenshot({
                     path: filepath,
                     fullPage: p.fullPage ?? false,
@@ -73,12 +72,11 @@ export function registerScreenshotTools(ext, bs) {
                 },
             },
         },
-        async execute(_toolCallId, params) {
+        async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
             const p = params;
             try {
                 const page = bs.getActivePage();
                 const config = bs.getConfig();
-                // Inject ARIA snapshot helper
                 const snapshot = await page.evaluate(() => {
                     function buildSnapshot(element, depth) {
                         if (depth > 20)
@@ -95,7 +93,6 @@ export function registerScreenshotTools(ext, bs) {
                         const text = element.childNodes.length === 1 && element.childNodes[0].nodeType === Node.TEXT_NODE
                             ? ` "${element.textContent?.trim()}"`
                             : "";
-                        // Build element description
                         let desc = `${indent}${tag}${id}${className}`;
                         if (role)
                             desc += ` [role=${role}]`;
@@ -103,7 +100,6 @@ export function registerScreenshotTools(ext, bs) {
                             desc += ` [aria-label="${ariaLabel}"]`;
                         if (text && text.length < 100)
                             desc += text;
-                        // Interactive hints
                         const href = element.href;
                         const placeholder = element.placeholder;
                         const value = element.value;
@@ -121,9 +117,10 @@ export function registerScreenshotTools(ext, bs) {
                     }
                     return buildSnapshot(document.body ?? document.documentElement, 0);
                 });
-                mkdirSync(config.outputDir, { recursive: true });
+                const outDir = resolveOutputDir(config.outputDir, ctx.cwd);
+                mkdirSync(outDir, { recursive: true });
                 const filename = p.filename ?? `snapshot-${Date.now()}.txt`;
-                const filepath = join(config.outputDir, filename);
+                const filepath = join(outDir, filename);
                 writeFileSync(filepath, snapshot, "utf-8");
                 const truncated = snapshot.length > 50000
                     ? snapshot.slice(0, 50000) + `\n\n[truncated — full snapshot saved to ${filepath}]`

package/dist/sdk/coding-agent/core/exec.js

@@ -54,13 +54,13 @@ export async function execCommand(command, args, cwd, options) {
         // Wait for process termination without hanging on inherited stdio handles
         // held open by detached descendants.
         waitForChildProcess(proc)
-            .then((code) => {
+            .then(({ code, forcedKill }) => {
             if (timeoutId)
                 clearTimeout(timeoutId);
             if (options?.signal) {
                 options.signal.removeEventListener("abort", killProcess);
             }
-            resolve({ stdout, stderr, code: code ?? 0, killed });
+            resolve({ stdout, stderr, code: forcedKill ? 1 : code ?? 0, killed: forcedKill || killed });
         })
             .catch((_err) => {
             if (timeoutId)

package/dist/sdk/coding-agent/core/tools/bash.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bash.d.ts","sourceRoot":"","sources":["../../../../../src/sdk/coding-agent/core/tools/bash.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAE9D,OAAO,EAAE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAU5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAI7D,OAAO,EAAoD,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAExG,QAAA,MAAM,UAAU;;;EAGd,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,UAAU,CAAC,CAAC;AAEtD,MAAM,WAAW,eAAe;IAC/B,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC9B;;;;;;OAMG;IACH,IAAI,EAAE,CACL,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,OAAO,EAAE;QACR,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;QAC/B,MAAM,CAAC,EAAE,WAAW,CAAC;QACrB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;KACxB,KACG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;CAC1C;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,cAAc,CA+D1F;AAED,MAAM,WAAW,gBAAgB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;CACvB;AAED,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,gBAAgB,KAAK,gBAAgB,CAAC;AAO5E,MAAM,WAAW,eAAe;IAC/B,oEAAoE;IACpE,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,mFAAmF;IACnF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,aAAa,CAAC;CAC1B;AAwFD,wBAAgB,wBAAwB,CACvC,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,eAAe,GACvB,cAAc,CAAC,OAAO,UAAU,EAAE,eAAe,GAAG,SAAS,CAAC,CAsIhE;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC,OAAO,UAAU,CAAC,CAEnG"}
+{"version":3,"file":"bash.d.ts","sourceRoot":"","sources":["../../../../../src/sdk/coding-agent/core/tools/bash.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAE9D,OAAO,EAAE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAU5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAI7D,OAAO,EAAoD,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAExG,QAAA,MAAM,UAAU;;;EAGd,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,UAAU,CAAC,CAAC;AAEtD,MAAM,WAAW,eAAe;IAC/B,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC9B;;;;;;OAMG;IACH,IAAI,EAAE,CACL,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,OAAO,EAAE;QACR,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;QAC/B,MAAM,CAAC,EAAE,WAAW,CAAC;QACrB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;KACxB,KACG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;CAC1C;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,cAAc,CAkF1F;AAED,MAAM,WAAW,gBAAgB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;CACvB;AAED,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,gBAAgB,KAAK,gBAAgB,CAAC;AAO5E,MAAM,WAAW,eAAe;IAC/B,oEAAoE;IACpE,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,mFAAmF;IACnF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,SAAS,CAAC,EAAE,aAAa,CAAC;CAC1B;AAyFD,wBAAgB,wBAAwB,CACvC,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE,eAAe,GACvB,cAAc,CAAC,OAAO,UAAU,EAAE,eAAe,GAAG,SAAS,CAAC,CAsIhE;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC,OAAO,UAAU,CAAC,CAEnG"}

package/dist/sdk/coding-agent/core/tools/bash.js

@@ -41,8 +41,17 @@ export function createLocalBashOperations(options) {
                 if (timeout !== undefined && timeout > 0) {
                     timeoutHandle = setTimeout(() => {
                         timedOut = true;
-                        if (child.pid)
-                            killProcessTree(child.pid);
+                        if (child.pid) {
+                            try {
+                                killProcessTree(child.pid);
+                            }
+                            catch {
+                                // ESRCH: process already exited. If it's truly gone, treat as normal exit.
+                                if (child.exitCode !== null || child.signalCode) {
+                                    return;
+                                }
+                            }
+                        }
                     }, timeout * 1000);
                 }
                 // Stream stdout and stderr.
@@ -61,8 +70,13 @@ export function createLocalBashOperations(options) {
                 }
                 // Handle shell spawn errors and wait for the process to terminate without hanging
                 // on inherited stdio handles held by detached descendants.
-                waitForChildProcess(child)
-                    .then((code) => {
+                // Hard deadline = max(LLM timeout + 5s grace, 30m default). Guarantees the
+                // promise resolves even if a detached descendant keeps the pipe open.
+                const hardDeadlineMs = timeout !== undefined && timeout > 0
+                    ? Math.max(timeout * 1000 + 5000, BASH_HARD_DEADLINE_MS)
+                    : BASH_HARD_DEADLINE_MS;
+                waitForChildProcess(child, hardDeadlineMs)
+                    .then(({ code, forcedKill }) => {
                     if (child.pid)
                         untrackDetachedChildPid(child.pid);
                     if (timeoutHandle)
@@ -73,6 +87,10 @@ export function createLocalBashOperations(options) {
                         reject(new Error("aborted"));
                         return;
                     }
+                    if (forcedKill) {
+                        reject(new Error(`Command force-killed after hard deadline (${Math.round(hardDeadlineMs / 60000)}m)`));
+                        return;
+                    }
                     if (timedOut) {
                         reject(new Error(`timeout:${timeout}`));
                         return;
@@ -98,6 +116,7 @@ function resolveSpawnContext(command, cwd, spawnHook) {
 }
 const BASH_PREVIEW_LINES = 5;
 const BASH_UPDATE_THROTTLE_MS = 100;
+const BASH_HARD_DEADLINE_MS = Number(process.env.SPECTRAL_BASH_HARD_DEADLINE_MS) || 30 * 60 * 1000;
 function formatDuration(ms) {
     return `${(ms / 1000).toFixed(1)}s`;
 }

package/dist/sdk/coding-agent/utils/child-process.d.ts

@@ -1,5 +1,11 @@
 import { type ChildProcess, type ChildProcessByStdio, type SpawnOptions, type SpawnOptionsWithStdioTuple, type SpawnSyncOptionsWithStringEncoding, type SpawnSyncReturns, type StdioNull, type StdioPipe } from "node:child_process";
 import type { Readable } from "node:stream";
+export interface WaitForChildProcessResult {
+    /** Process exit code, or null if the process did not exit cleanly. */
+    code: number | null;
+    /** True when the hard deadline fired and we force-killed the process tree. */
+    forcedKill: boolean;
+}
 export declare function spawnProcess(command: string, args: string[], options: SpawnOptionsWithStdioTuple<StdioNull, StdioPipe, StdioPipe>): ChildProcessByStdio<null, Readable, Readable>;
 export declare function spawnProcess(command: string, args: string[], options: SpawnOptions): ChildProcess;
 export declare function spawnProcessSync(command: string, args: string[], options: SpawnSyncOptionsWithStringEncoding): SpawnSyncReturns<string>;
@@ -10,6 +16,11 @@ export declare function spawnProcessSync(command: string, args: string[], option
  * handles. In that case the child emits `exit`, but `close` can hang forever even
  * though the original process is already gone. We wait briefly for stdio to end,
  * then forcibly stop tracking the inherited handles.
+ *
+ * As an escape hatch, a hard deadline (default 30 minutes, env-overridable via
+ * SPECTRAL_BASH_HARD_DEADLINE_MS) force-kills the process tree and resolves the
+ * promise so callers can never hang indefinitely on a pipe held open by a
+ * detached descendant.
  */
-export declare function waitForChildProcess(child: ChildProcess): Promise<number | null>;
+export declare function waitForChildProcess(child: ChildProcess, hardDeadlineMs?: number): Promise<WaitForChildProcessResult>;
 //# sourceMappingURL=child-process.d.ts.map

package/dist/sdk/coding-agent/utils/child-process.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"child-process.d.ts","sourceRoot":"","sources":["../../../../src/sdk/coding-agent/utils/child-process.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,YAAY,EACjB,KAAK,mBAAmB,EAGxB,KAAK,YAAY,EACjB,KAAK,0BAA0B,EAC/B,KAAK,kCAAkC,EACvC,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,KAAK,SAAS,EACd,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAK5C,wBAAgB,YAAY,CAC3B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,0BAA0B,CAAC,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC,GAClE,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;AACjD,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,YAAY,GAAG,YAAY,CAAC;AAKnG,wBAAgB,gBAAgB,CAC/B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,kCAAkC,GACzC,gBAAgB,CAAC,MAAM,CAAC,CAI1B;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAyE/E"}
+{"version":3,"file":"child-process.d.ts","sourceRoot":"","sources":["../../../../src/sdk/coding-agent/utils/child-process.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,YAAY,EACjB,KAAK,mBAAmB,EAGxB,KAAK,YAAY,EACjB,KAAK,0BAA0B,EAC/B,KAAK,kCAAkC,EACvC,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,KAAK,SAAS,EACd,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAO5C,MAAM,WAAW,yBAAyB;IACzC,sEAAsE;IACtE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,8EAA8E;IAC9E,UAAU,EAAE,OAAO,CAAC;CACpB;AAED,wBAAgB,YAAY,CAC3B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,0BAA0B,CAAC,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC,GAClE,mBAAmB,CAAC,IAAI,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;AACjD,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,YAAY,GAAG,YAAY,CAAC;AAKnG,wBAAgB,gBAAgB,CAC/B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,EAAE,kCAAkC,GACzC,gBAAgB,CAAC,MAAM,CAAC,CAI1B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAClC,KAAK,EAAE,YAAY,EACnB,cAAc,GAAE,MAA8B,GAC5C,OAAO,CAAC,yBAAyB,CAAC,CAsFpC"}

package/dist/sdk/coding-agent/utils/child-process.js

@@ -1,6 +1,8 @@
 import { spawn as nodeSpawn, spawnSync as nodeSpawnSync, } from "node:child_process";
 import crossSpawn from "cross-spawn";
+import { killProcessTree } from "./shell.js";
 const EXIT_STDIO_GRACE_MS = 100;
+const BASH_HARD_DEADLINE_MS = Number(process.env.SPECTRAL_BASH_HARD_DEADLINE_MS) || 30 * 60 * 1000;
 export function spawnProcess(command, args, options) {
     return process.platform === "win32" ? crossSpawn(command, args, options) : nodeSpawn(command, args, options);
 }
@@ -16,13 +18,19 @@ export function spawnProcessSync(command, args, options) {
  * handles. In that case the child emits `exit`, but `close` can hang forever even
  * though the original process is already gone. We wait briefly for stdio to end,
  * then forcibly stop tracking the inherited handles.
+ *
+ * As an escape hatch, a hard deadline (default 30 minutes, env-overridable via
+ * SPECTRAL_BASH_HARD_DEADLINE_MS) force-kills the process tree and resolves the
+ * promise so callers can never hang indefinitely on a pipe held open by a
+ * detached descendant.
  */
-export function waitForChildProcess(child) {
+export function waitForChildProcess(child, hardDeadlineMs = BASH_HARD_DEADLINE_MS) {
     return new Promise((resolve, reject) => {
         let settled = false;
         let exited = false;
         let exitCode = null;
         let postExitTimer;
+        let hardDeadlineTimer;
         let stdoutEnded = child.stdout === null;
         let stderrEnded = child.stderr === null;
         const cleanup = () => {
@@ -30,20 +38,24 @@ export function waitForChildProcess(child) {
                 clearTimeout(postExitTimer);
                 postExitTimer = undefined;
             }
+            if (hardDeadlineTimer) {
+                clearTimeout(hardDeadlineTimer);
+                hardDeadlineTimer = undefined;
+            }
             child.removeListener("error", onError);
             child.removeListener("exit", onExit);
             child.removeListener("close", onClose);
             child.stdout?.removeListener("end", onStdoutEnd);
             child.stderr?.removeListener("end", onStderrEnd);
         };
-        const finalize = (code) => {
+        const finalize = (code, forcedKill = false) => {
             if (settled)
                 return;
             settled = true;
             cleanup();
             child.stdout?.destroy();
             child.stderr?.destroy();
-            resolve(code);
+            resolve({ code, forcedKill });
         };
         const maybeFinalizeAfterExit = () => {
             if (!exited || settled)
@@ -83,5 +95,24 @@ export function waitForChildProcess(child) {
         child.once("error", onError);
         child.once("exit", onExit);
         child.once("close", onClose);
+        // Hard deadline escape hatch: if the child (or a grandchild) keeps the
+        // stdout/stderr pipe open indefinitely, force-kill the tree and resolve.
+        if (hardDeadlineMs > 0 && !settled) {
+            hardDeadlineTimer = setTimeout(() => {
+                if (settled)
+                    return;
+                if (child.pid) {
+                    try {
+                        killProcessTree(child.pid);
+                    }
+                    catch {
+                        // Process may already be gone; ignore.
+                    }
+                }
+                child.stdout?.destroy();
+                child.stderr?.destroy();
+                finalize(null, true);
+            }, hardDeadlineMs);
+        }
     });
 }

package/dist/server/agent-bridge.d.ts

@@ -168,6 +168,8 @@ export declare class AgentBridge {
     private lastAppliedModelId?;
     private promptActivityTimer?;
     private promptReject?;
+    /** Per-turn tool execution backstop timer (see TOOL_EXECUTION_TIMEOUT_MS). */
+    private toolExecutionTimer?;
     /** Current model's credit rates (from availableAgentModels), used for token_usage. */
     private activeCreditRates;
     private memoryPhase;
@@ -342,12 +344,35 @@ export declare class AgentBridge {
      */
     private withPromptTimeout;
     /**
-     * Reset the inactivity watchdog. Called from `handleEvent` on EVERY session
-     * event so a long-running prompt that is actively streaming / calling tools
-     * is never killed by the inactivity timeout.
+     * Whether `ev` represents real agent progress and should reset the
+     * inactivity watchdog. High-frequency churn events that can stream
+     * indefinitely without progress are excluded:
+     *   - `tool_execution_update` (e.g. bash stdout chunks from a grandchild)
+     *   - `compaction_delta`
+     *   - `token_usage` (wire-only; not a session event, excluded for clarity)
+     *
+     * Meaningful events map the task's allow-list (message_start, text/thinking
+     * deltas via message_update, message_end, agent_end, tool_execution_start,
+     * tool_execution_end → tool_result / subagent_end).
+     */
+    private isMeaningfulPromptActivity;
+    /**
+     * Reset the inactivity watchdog. Called from `handleEvent` ONLY for
+     * meaningful progress events (see `isMeaningfulPromptActivity`), so a
+     * long-running prompt that is actively streaming text / calling tools is
+     * never killed by the inactivity timeout — but churn (e.g. bash stdout
+     * chunks) no longer keeps a stuck session alive forever.
      */
     private bumpPromptActivity;
     private clearPromptTimers;
+    /**
+     * Start the per-turn tool execution backstop. Only the first
+     * `tool_execution_start` of a turn arms it; nested tool starts reuse the
+     * running timer. Cleared on `tool_execution_end` / `agent_end` and on
+     * teardown via `clearPromptTimers`.
+     */
+    private startToolExecutionTimer;
+    private clearToolExecutionTimer;
     compact(options?: string | AgentBridgeCompactionOptions): Promise<CompactionResult>;
     dispose(): void;
     /**

package/dist/server/agent-bridge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-bridge.d.ts","sourceRoot":"","sources":["../../src/server/agent-bridge.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent-bridge.d.ts","sourceRoot":"","sources":["../../src/server/agent-bridge.ts"],"names":[],"mappings":"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"}

package/dist/server/agent-bridge.js

@@ -535,16 +535,36 @@ function toRestoredMemorySnapshot(snapshot) {
 }
 /**
  * Inactivity-based prompt hang watchdog. Unlike a fixed wall-clock deadline,
- * this only fires when the agent session has emitted NO events (text deltas,
- * tool calls, tool results, thinking, message boundaries) for the configured
- * window. Long-running but active prompts (multi-turn tool use, builds,
- * subagents, streaming) are NOT killed — only truly stuck sessions are.
+ * this only fires when the agent session has emitted NO *meaningful* progress
+ * events (text deltas, tool calls, tool results, thinking, message boundaries)
+ * for the configured window. Long-running but active prompts (multi-turn tool
+ * use, builds, subagents, streaming) are NOT killed — only truly stuck
+ * sessions are.
  *
- * Reset on every `AgentSessionEvent` seen by `handleEvent`. Default 120s of
- * total silence. Hard ceiling removed — working agents (including
- * subagents) must never be killed by a wall-clock timeout.
+ * Meaningful events are an explicit allow-list defined by
+ * `isMeaningfulPromptActivity(ev)` in `handleEvent`. High-frequency churn
+ * events — `tool_execution_update` (e.g. bash stdout chunks), `compaction_delta`,
+ * `token_usage` — do NOT reset the watchdog, because they can stream
+ * indefinitely without real agent progress (a hung grandchild writing bytes
+ * to stdout would otherwise keep the watchdog alive forever).
+ *
+ * Default 120s of total silence. Hard ceiling removed for meaningful work —
+ * working agents (including subagents) must never be killed by this watchdog.
  */
 const PROMPT_INACTIVITY_TIMEOUT_MS = Number(process.env.SPECTRAL_PROMPT_INACTIVITY_MS) || 2 * 60 * 1000;
+/**
+ * Per-turn ceiling for a single tool execution. Started on the first
+ * `tool_execution_start` of a turn and cleared on `tool_execution_end` /
+ * `agent_end`. Protects against a single tool call (e.g. a bash grandchild
+ * streaming stdout chunks via `tool_execution_update`) running forever: even
+ * though those chunks no longer reset the inactivity watchdog, this timer
+ * provides an absolute backstop per tool invocation.
+ *
+ * Default 30 minutes, overridable via `SPECTRAL_TOOL_EXECUTION_TIMEOUT_MS`.
+ * On expiry it forces a prompt reject (same abort path as the inactivity
+ * watchdog) with a descriptive message.
+ */
+const TOOL_EXECUTION_TIMEOUT_MS = Number(process.env.SPECTRAL_TOOL_EXECUTION_TIMEOUT_MS) || 30 * 60 * 1000;
 export class AgentBridge {
     session;
     suppressNextAgentEndForGeneration;
@@ -576,6 +596,8 @@ export class AgentBridge {
     lastAppliedModelId;
     promptActivityTimer;
     promptReject;
+    /** Per-turn tool execution backstop timer (see TOOL_EXECUTION_TIMEOUT_MS). */
+    toolExecutionTimer;
     /** Current model's credit rates (from availableAgentModels), used for token_usage. */
     activeCreditRates = null;
     memoryPhase = "idle";
@@ -720,6 +742,14 @@ export class AgentBridge {
                             arguments: tc.arguments,
                         });
                     }
+                    // Detect orphaned tool calls: CLI was killed mid-tool-call, so some
+                    // tool_use blocks have no matching tool_result in the persisted events.
+                    // Mark as "error" so transform-messages inserts synthetic "No result provided"
+                    // + isError=true, letting the LLM retry the action after a CLI restart.
+                    const orphanedToolCallIds = toolCalls
+                        .filter((tc) => !toolResults.some((tr) => tr.id === tc.id))
+                        .map((tc) => tc.id);
+                    const hasOrphanedToolCalls = orphanedToolCallIds.length > 0;
                     sessionManager.appendMessage({
                         role: "assistant",
                         content,
@@ -741,7 +771,9 @@ export class AgentBridge {
                             },
                         },
                         stopReason: toolCalls.length > 0
-                            ? "toolUse"
+                            ? (hasOrphanedToolCalls
+                                ? "error"
+                                : "toolUse")
                             : "stop",
                         timestamp: msg.createdAt,
                     });
@@ -768,6 +800,9 @@ export class AgentBridge {
                             timestamp: msg.createdAt,
                         });
                     }
+                    if (hasOrphanedToolCalls) {
+                        console.warn(`[AgentBridge] Rehydrated message ${msg.id} marked as error (orphaned tool calls after CLI restart: ${orphanedToolCallIds.join(", ")})`);
+                    }
                 }
                 // system messages are informational only; skip for LLM context
             }
@@ -1384,10 +1419,10 @@ export class AgentBridge {
      * observations can stay relevant to the current task.
      */
     async withPromptTimeout(prompt) {
-        // Activity-based watchdog: reset on every session event via
-        // `bumpPromptActivity()`. Only triggers on total silence, NOT on long
-        // active prompts. Hard ceiling removed — working agents (including
-        // subagents) must never be killed by a wall-clock timeout.
+        // Activity-based watchdog: reset on meaningful session events only via
+        // `bumpPromptActivity()` (churn like tool_execution_update excluded). A
+        // separate per-tool TOOL_EXECUTION_TIMEOUT_MS backstop guards single
+        // tool calls. Triggers on total silence, NOT on long active prompts.
         const inactivityPromise = new Promise((_, reject) => {
             this.promptReject = reject;
             this.promptActivityTimer = setTimeout(() => {
@@ -1402,9 +1437,39 @@ export class AgentBridge {
         }
     }
     /**
-     * Reset the inactivity watchdog. Called from `handleEvent` on EVERY session
-     * event so a long-running prompt that is actively streaming / calling tools
-     * is never killed by the inactivity timeout.
+     * Whether `ev` represents real agent progress and should reset the
+     * inactivity watchdog. High-frequency churn events that can stream
+     * indefinitely without progress are excluded:
+     *   - `tool_execution_update` (e.g. bash stdout chunks from a grandchild)
+     *   - `compaction_delta`
+     *   - `token_usage` (wire-only; not a session event, excluded for clarity)
+     *
+     * Meaningful events map the task's allow-list (message_start, text/thinking
+     * deltas via message_update, message_end, agent_end, tool_execution_start,
+     * tool_execution_end → tool_result / subagent_end).
+     */
+    isMeaningfulPromptActivity(ev) {
+        switch (ev.type) {
+            case "message_start":
+            case "message_update":
+            case "message_end":
+            case "agent_end":
+            case "tool_execution_start":
+            case "tool_execution_end":
+                return true;
+            default:
+                // tool_execution_update, compaction_*, prompt_mutation_status,
+                // queue_update, auto_retry_*, length_continuation, session_info_changed,
+                // thinking_level_changed — churn / non-progress, do NOT reset watchdog.
+                return false;
+        }
+    }
+    /**
+     * Reset the inactivity watchdog. Called from `handleEvent` ONLY for
+     * meaningful progress events (see `isMeaningfulPromptActivity`), so a
+     * long-running prompt that is actively streaming text / calling tools is
+     * never killed by the inactivity timeout — but churn (e.g. bash stdout
+     * chunks) no longer keeps a stuck session alive forever.
      */
     bumpPromptActivity() {
         if (!this.promptActivityTimer)
@@ -1419,8 +1484,32 @@ export class AgentBridge {
             clearTimeout(this.promptActivityTimer);
             this.promptActivityTimer = undefined;
         }
+        this.clearToolExecutionTimer();
         this.promptReject = undefined;
     }
+    /**
+     * Start the per-turn tool execution backstop. Only the first
+     * `tool_execution_start` of a turn arms it; nested tool starts reuse the
+     * running timer. Cleared on `tool_execution_end` / `agent_end` and on
+     * teardown via `clearPromptTimers`.
+     */
+    startToolExecutionTimer() {
+        if (this.toolExecutionTimer)
+            return;
+        this.toolExecutionTimer = setTimeout(() => {
+            this.toolExecutionTimer = undefined;
+            // Mirror bumpPromptActivity: reject the inactivity race so the existing
+            // prompt() catch path runs session.abort() + emits error/agent_end.
+            // The withPromptTimeout finally block clears all timers afterwards.
+            this.promptReject?.(new Error(`Tool execution exceeded ${TOOL_EXECUTION_TIMEOUT_MS / 60000} minutes`));
+        }, TOOL_EXECUTION_TIMEOUT_MS);
+    }
+    clearToolExecutionTimer() {
+        if (this.toolExecutionTimer) {
+            clearTimeout(this.toolExecutionTimer);
+            this.toolExecutionTimer = undefined;
+        }
+    }
     async compact(options) {
         if (!this.session)
             throw new Error("AgentBridge.start() not called");
@@ -1546,9 +1635,16 @@ export class AgentBridge {
     handleEvent(ev) {
         if (this.disposed)
             return;
-        // Reset inactivity watchdog on every session event so long active
-        // prompts (multi-tool, streaming, subagents) are not killed.
-        this.bumpPromptActivity();
+        // Reset inactivity watchdog ONLY on meaningful agent progress events
+        // (text/thinking deltas, message boundaries, tool start/end, agent_end).
+        // Churn events like tool_execution_update (bash stdout chunks) and
+        // compaction_delta are intentionally excluded so a stuck grandchild
+        // streaming bytes cannot keep the watchdog alive forever. A separate
+        // per-tool TOOL_EXECUTION_TIMEOUT_MS (30 min) backstop covers a single
+        // tool call running too long.
+        if (this.isMeaningfulPromptActivity(ev)) {
+            this.bumpPromptActivity();
+        }
         switch (ev.type) {
             case "message_start": {
                 // Only assistant messages get our message_start frame on the wire.
@@ -1613,6 +1709,7 @@ export class AgentBridge {
                 return;
             }
             case "tool_execution_start": {
+                this.startToolExecutionTimer();
                 // Emit subagent_start for subagent tool invocations (Option B frontend panels).
                 if (ev.toolName === "subagent") {
                     const args = ev.args;
@@ -1699,6 +1796,7 @@ export class AgentBridge {
                 return;
             }
             case "tool_execution_end": {
+                this.clearToolExecutionTimer();
                 // Emit subagent_end for subagent tool completions.
                 if (ev.toolName === "subagent") {
                     const result = ev.result;
@@ -1848,6 +1946,7 @@ export class AgentBridge {
                 return;
             }
             case "agent_end": {
+                this.clearToolExecutionTimer();
                 if (this.suppressNextAgentEndForGeneration !== undefined) {
                     const isSameTurn = this.suppressNextAgentEndForGeneration === this.turnGeneration;
                     this.suppressNextAgentEndForGeneration = undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aexol/spectral",
-  "version": "0.9.115",
+  "version": "0.9.117",
   "description": "AI coding agent for Aexol with relay-based browser access.",
   "type": "module",
   "private": false,