@desplega.ai/qa-use 2.14.1 → 2.15.1

package/dist/src/cli/lib/startup-sweep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"startup-sweep.js","sourceRoot":"","sources":["../../../../src/cli/lib/startup-sweep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAEjE,MAAM,SAAS,GAAG,GAAG,CAAC;AAEtB;;;;;;;;GAQG;AACH,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,kBAAkB,CAAC,CAAC,CAAC;AAE9D;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,OAAiB,OAAO,CAAC,IAAI;IACvD,sEAAsE;IACtE,uEAAuE;IACvE,kEAAkE;IAClE,uCAAuC;IACvC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAClD,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACtB,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAS;QAC9C,IAAI,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;QAC3C,sEAAsE;QACtE,gDAAgD;QAChD,sEAAsE;QACtE,gCAAgC;IAClC,CAAC;IACD,yEAAyE;IACzE,IAAI,IAAI,CAAC,QAAQ,CAAC,kBAAkB,CAAC;QAAE,OAAO,KAAK,CAAC;IACpD,yEAAyE;IACzE,iEAAiE;IACjE,sEAAsE;IACtE,8DAA8D;IAC9D,gEAAgE;IAChE,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAC3C,IAAI,UAAU,KAAK,CAAC,CAAC,EAAE,CAAC;QACtB,KAAK,IAAI,CAAC,GAAG,UAAU,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YAClD,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;YACtB,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC;gBAAE,SAAS;YAC9C,IAAI,KAAK,KAAK,QAAQ;gBAAE,OAAO,KAAK,CAAC;YACrC,MAAM;QACR,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAQD,KAAK,UAAU,aAAa,CAAC,QAAgB;IAC3C,MAAM,GAAG,GAAG,WAAW,EAAE,CAAC;IAC1B,IAAI,KAAe,CAAC;IACpB,IAAI,CAAC;QACH,KAAK,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,CAAC;IACX,CAAC;IACD,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,QAAQ;YAAE,MAAM;QAClC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;YAAE,SAAS;QAC/D,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAClC,IAAI,MAAM,GAA6C,IAAI,CAAC;QAC5D,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YAC1C,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAsC,CAAC;QAChE,CAAC;QAAC,MAAM,CAAC;YACP,+BAA+B;YAC/B,IAAI,CAAC;gBACH,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;gBACpB,MAAM,IAAI,CAAC,CAAC;YACd,CAAC;YAAC,MAAM,CAAC;gBACP,YAAY;YACd,CAAC;YACD,SAAS;QACX,CAAC;QACD,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ,EAAE,CAAC;YAC9C,IAAI,CAAC;gBACH,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;gBACpB,MAAM,IAAI,CAAC,CAAC;YACd,CAAC;YAAC,MAAM,CAAC;gBACP,YAAY;YACd,CAAC;YACD,SAAS;QACX,CAAC;QACD,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;YAC5B,IAAI,CAAC;gBACH,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;YACtB,CAAC;YAAC,MAAM,CAAC;gBACP,kBAAkB;YACpB,CAAC;YACD,iEAAiE;YACjE,4DAA4D;YAC5D,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;gBAClB,IAAI,CAAC;oBACH,MAAM,cAAc,CAAC,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;gBACjD,CAAC;gBAAC,MAAM,CAAC;oBACP,iBAAiB;gBACnB,CAAC;YACH,CAAC;YACD,MAAM,IAAI,CAAC,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,KAAK,UAAU,YAAY,CAAC,QAAgB;IAC1C,MAAM,GAAG,GAAG,UAAU,EAAE,CAAC;IACzB,IAAI,KAAe,CAAC;IACpB,IAAI,CAAC;QACH,KAAK,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,CAAC;IACX,CAAC;IACD,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,QAAQ;YAAE,MAAM;QAClC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;YAAE,SAAS;QAC/D,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAClC,IAAI,MAAM,GAA6C,IAAI,CAAC;QAC5D,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YAC1C,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAsC,CAAC;QAChE,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,CAAC;gBACH,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;gBACpB,MAAM,IAAI,CAAC,CAAC;YACd,CAAC;YAAC,MAAM,CAAC;gBACP,YAAY;YACd,CAAC;YACD,SAAS;QACX,CAAC;QACD,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,CAAC,GAAG,KAAK,QAAQ,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;YACzE,IAAI,MAAM,EAAE,MAAM,EAAE,CAAC;gBACnB,IAAI,CAAC;oBACH,MAAM,cAAc,CAAC,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;gBACjD,CAAC;gBAAC,MAAM,CAAC;oBACP,gDAAgD;gBAClD,CAAC;YACH,CAAC;YACD,IAAI,CAAC;gBACH,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;YACtB,CAAC;YAAC,MAAM,CAAC;gBACP,kBAAkB;YACpB,CAAC;YACD,MAAM,IAAI,CAAC,CAAC;QACd,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe;IACnC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;IACxC,MAAM,MAAM,GAAgB;QAC1B,cAAc,EAAE,CAAC;QACjB,aAAa,EAAE,CAAC;QAChB,cAAc,EAAE,KAAK;KACtB,CAAC;IACF,IAAI,CAAC;QACH,MAAM,CAAC,cAAc,GAAG,MAAM,aAAa,CAAC,QAAQ,CAAC,CAAC;QACtD,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAC;YAC1B,MAAM,CAAC,aAAa,GAAG,MAAM,YAAY,CAAC,QAAQ,CAAC,CAAC;QACtD,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,kCAAkC;IACpC,CAAC;IACD,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,QAAQ,EAAE,CAAC;QAC3B,MAAM,CAAC,cAAc,GAAG,IAAI,CAAC;IAC/B,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAiB,OAAO,CAAC,IAAI;IAC/D,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;QAAE,OAAO;IAC/B,KAAK,eAAe,EAAE;SACnB,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE;QACf,MAAM,KAAK,GAAG,MAAM,CAAC,cAAc,GAAG,MAAM,CAAC,aAAa,CAAC;QAC3D,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;YACd,MAAM,KAAK,GAAa,EAAE,CAAC;YAC3B,IAAI,MAAM,CAAC,cAAc,GAAG,CAAC,EAAE,CAAC;gBAC9B,KAAK,CAAC,IAAI,CACR,GAAG,MAAM,CAAC,cAAc,iBAAiB,MAAM,CAAC,cAAc,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAClF,CAAC;YACJ,CAAC;YACD,IAAI,MAAM,CAAC,aAAa,GAAG,CAAC,EAAE,CAAC;gBAC7B,KAAK,CAAC,IAAI,CACR,GAAG,MAAM,CAAC,aAAa,gBAAgB,MAAM,CAAC,aAAa,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAC/E,CAAC;YACJ,CAAC;YACD,OAAO,CAAC,KAAK,CAAC,sBAAsB,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC,CAAC;SACD,KAAK,CAAC,GAAG,EAAE;QACV,kCAAkC;IACpC,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/src/cli/lib/tunnel-banner.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Auto-tunnel banner helpers (stderr-only, TTY-aware).
+ *
+ * `printTunnelStartBanner` is the multi-line boxed notice shown when a
+ * new tunnel is started. `printTunnelReuseBanner` is the short
+ * single-line notice used when an existing tunnel is reused (Phase 3
+ * consumer, but lands here so all banner copy lives in one place).
+ *
+ * Suppression rules — banner prints nothing when ANY of the following
+ * hold:
+ *   - `process.stderr.isTTY` is falsy (piped / redirected stderr)
+ *   - `process.env.QA_USE_QUIET === '1'`
+ *   - caller passes `{ quiet: true }`
+ */
+export interface TunnelBannerOptions {
+    /** The detected target URL (usually the localhost base URL). */
+    target: string;
+    /** The public tunnel URL that was just created / reused. */
+    publicUrl: string;
+    /** Opt-in quiet flag from a `--json`/`--quiet` caller. */
+    quiet?: boolean;
+}
+/**
+ * Multi-line boxed banner printed on a fresh tunnel start.
+ */
+export declare function printTunnelStartBanner(options: TunnelBannerOptions): void;
+/**
+ * Single-line notice printed when an existing tunnel is reused.
+ * Used by the Phase-3 registry layer; lives here so all banner copy
+ * stays co-located.
+ */
+export declare function printTunnelReuseBanner(options: TunnelBannerOptions): void;
+//# sourceMappingURL=tunnel-banner.d.ts.map

package/dist/src/cli/lib/tunnel-banner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel-banner.d.ts","sourceRoot":"","sources":["../../../../src/cli/lib/tunnel-banner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,mBAAmB;IAClC,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AASD;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAkBzE;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI,CAIzE"}

package/dist/src/cli/lib/tunnel-banner.js

@@ -0,0 +1,55 @@
+/**
+ * Auto-tunnel banner helpers (stderr-only, TTY-aware).
+ *
+ * `printTunnelStartBanner` is the multi-line boxed notice shown when a
+ * new tunnel is started. `printTunnelReuseBanner` is the short
+ * single-line notice used when an existing tunnel is reused (Phase 3
+ * consumer, but lands here so all banner copy lives in one place).
+ *
+ * Suppression rules — banner prints nothing when ANY of the following
+ * hold:
+ *   - `process.stderr.isTTY` is falsy (piped / redirected stderr)
+ *   - `process.env.QA_USE_QUIET === '1'`
+ *   - caller passes `{ quiet: true }`
+ */
+function shouldSuppress(quiet) {
+    if (quiet)
+        return true;
+    if (process.env.QA_USE_QUIET === '1')
+        return true;
+    if (!process.stderr.isTTY)
+        return true;
+    return false;
+}
+/**
+ * Multi-line boxed banner printed on a fresh tunnel start.
+ */
+export function printTunnelStartBanner(options) {
+    if (shouldSuppress(options.quiet))
+        return;
+    const lines = [
+        '╭─ Auto-tunnel active ──────────────────────────────',
+        `│ Detected localhost target: ${options.target}`,
+        '│ Remote backend cannot reach your machine directly,',
+        '│ so qa-use is exposing it via:',
+        '│',
+        `│   ${options.publicUrl}`,
+        '│',
+        '│ Disable with --no-tunnel (or use a public URL).',
+        '╰───────────────────────────────────────────────────',
+    ];
+    for (const line of lines) {
+        console.error(line);
+    }
+}
+/**
+ * Single-line notice printed when an existing tunnel is reused.
+ * Used by the Phase-3 registry layer; lives here so all banner copy
+ * stays co-located.
+ */
+export function printTunnelReuseBanner(options) {
+    if (shouldSuppress(options.quiet))
+        return;
+    console.error(`↻ Auto-tunnel reuse: ${options.target} → ${options.publicUrl}`);
+}
+//# sourceMappingURL=tunnel-banner.js.map

package/dist/src/cli/lib/tunnel-banner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel-banner.js","sourceRoot":"","sources":["../../../../src/cli/lib/tunnel-banner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAWH,SAAS,cAAc,CAAC,KAA0B;IAChD,IAAI,KAAK;QAAE,OAAO,IAAI,CAAC;IACvB,IAAI,OAAO,CAAC,GAAG,CAAC,YAAY,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IAClD,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACvC,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAA4B;IACjE,IAAI,cAAc,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO;IAE1C,MAAM,KAAK,GAAG;QACZ,sDAAsD;QACtD,gCAAgC,OAAO,CAAC,MAAM,EAAE;QAChD,sDAAsD;QACtD,iCAAiC;QACjC,GAAG;QACH,OAAO,OAAO,CAAC,SAAS,EAAE;QAC1B,GAAG;QACH,mDAAmD;QACnD,sDAAsD;KACvD,CAAC;IAEF,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACtB,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAA4B;IACjE,IAAI,cAAc,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO;IAE1C,OAAO,CAAC,KAAK,CAAC,wBAAwB,OAAO,CAAC,MAAM,MAAM,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;AACjF,CAAC"}

package/dist/src/cli/lib/tunnel-error-hint.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Triage-hint formatter for structured tunnel errors.
+ *
+ * The brainstorm defines the user-facing copy:
+ *   × Auto-tunnel failed for <target>
+ *     Attempted: start tunnel via <provider>
+ *     Likely cause: <subclass-specific>
+ *     Next steps:
+ *       • Retry: ...
+ *       • Skip tunnel: --no-tunnel ...
+ *       • Check tunnel status: `qa-use tunnel status`
+ *
+ * Each tunnel-error subclass picks its own "likely cause" line.
+ */
+import { type TunnelError } from '../../../lib/tunnel/errors.js';
+/**
+ * Return a multi-line string ready to print to stderr.
+ */
+export declare function formatTunnelFailure(err: TunnelError): string;
+//# sourceMappingURL=tunnel-error-hint.d.ts.map

package/dist/src/cli/lib/tunnel-error-hint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel-error-hint.d.ts","sourceRoot":"","sources":["../../../../src/cli/lib/tunnel-error-hint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAEL,KAAK,WAAW,EAGjB,MAAM,+BAA+B,CAAC;AAevC;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,CAoB5D"}

package/dist/src/cli/lib/tunnel-error-hint.js

@@ -0,0 +1,48 @@
+/**
+ * Triage-hint formatter for structured tunnel errors.
+ *
+ * The brainstorm defines the user-facing copy:
+ *   × Auto-tunnel failed for <target>
+ *     Attempted: start tunnel via <provider>
+ *     Likely cause: <subclass-specific>
+ *     Next steps:
+ *       • Retry: ...
+ *       • Skip tunnel: --no-tunnel ...
+ *       • Check tunnel status: `qa-use tunnel status`
+ *
+ * Each tunnel-error subclass picks its own "likely cause" line.
+ */
+import { TunnelAuthError, TunnelNetworkError, TunnelQuotaError, } from '../../../lib/tunnel/errors.js';
+function likelyCause(err) {
+    if (err instanceof TunnelNetworkError) {
+        return 'network timeout or connectivity issue reaching the tunnel provider';
+    }
+    if (err instanceof TunnelAuthError) {
+        return 'authentication rejected (bad or expired API key)';
+    }
+    if (err instanceof TunnelQuotaError) {
+        return 'tunnel quota / rate-limit exceeded, or subdomain already in use';
+    }
+    return 'unknown failure from the tunnel provider';
+}
+/**
+ * Return a multi-line string ready to print to stderr.
+ */
+export function formatTunnelFailure(err) {
+    const target = err.target ?? '<unknown target>';
+    const provider = err.provider ?? 'localtunnel';
+    const lines = [
+        `× Auto-tunnel failed for ${target}`,
+        `  Attempted: start tunnel via ${provider}`,
+        `  Likely cause: ${likelyCause(err)}`,
+    ];
+    if (err.message) {
+        lines.push(`  Error: ${err.message}`);
+    }
+    lines.push('  Next steps:');
+    lines.push('    • Retry: the failure may be transient');
+    lines.push('    • Skip tunnel: rerun with --no-tunnel (only works if the backend can reach your target)');
+    lines.push('    • Check tunnel status: `qa-use tunnel status`');
+    return lines.join('\n');
+}
+//# sourceMappingURL=tunnel-error-hint.js.map

package/dist/src/cli/lib/tunnel-error-hint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel-error-hint.js","sourceRoot":"","sources":["../../../../src/cli/lib/tunnel-error-hint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,eAAe,EAEf,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,+BAA+B,CAAC;AAEvC,SAAS,WAAW,CAAC,GAAgB;IACnC,IAAI,GAAG,YAAY,kBAAkB,EAAE,CAAC;QACtC,OAAO,oEAAoE,CAAC;IAC9E,CAAC;IACD,IAAI,GAAG,YAAY,eAAe,EAAE,CAAC;QACnC,OAAO,kDAAkD,CAAC;IAC5D,CAAC;IACD,IAAI,GAAG,YAAY,gBAAgB,EAAE,CAAC;QACpC,OAAO,iEAAiE,CAAC;IAC3E,CAAC;IACD,OAAO,0CAA0C,CAAC;AACpD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAgB;IAClD,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,IAAI,kBAAkB,CAAC;IAChD,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,IAAI,aAAa,CAAC;IAE/C,MAAM,KAAK,GAAa;QACtB,4BAA4B,MAAM,EAAE;QACpC,iCAAiC,QAAQ,EAAE;QAC3C,mBAAmB,WAAW,CAAC,GAAG,CAAC,EAAE;KACtC,CAAC;IACF,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;QAChB,KAAK,CAAC,IAAI,CAAC,YAAY,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;IACxC,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IAC5B,KAAK,CAAC,IAAI,CAAC,2CAA2C,CAAC,CAAC;IACxD,KAAK,CAAC,IAAI,CACR,6FAA6F,CAC9F,CAAC;IACF,KAAK,CAAC,IAAI,CAAC,mDAAmD,CAAC,CAAC;IAEhE,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/src/cli/lib/tunnel-option.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Tri-state `--tunnel` option helper for Commander commands.
+ *
+ * Shape:
+ *   --tunnel [auto|on|off]   (default: auto; bare --tunnel = on)
+ *   --no-tunnel              (alias for --tunnel off)
+ *
+ * Invalid values are rejected at parse time with a clear error.
+ *
+ * Bare `--tunnel` (no value) is preserved as sugar for `--tunnel on`, which
+ * matches the pre-tri-state UX. Commander represents the bare form by passing
+ * the literal string `"true"` (or `undefined` depending on argv shape) through
+ * to the parser, so we map both to `'on'`.
+ */
+import { type Command } from 'commander';
+export type TunnelMode = 'auto' | 'on' | 'off';
+/**
+ * Attach the tri-state `--tunnel` option to a Commander command.
+ *
+ * The option is stored under the property name `tunnel` on the options
+ * object. Callers can read it as a `TunnelMode`.
+ *
+ * Also registers `--no-tunnel` as an alias that resolves to `'off'`, and
+ * accepts bare `--tunnel` (no value) as sugar for `--tunnel on`.
+ */
+export declare function addTunnelOption(command: Command): Command;
+//# sourceMappingURL=tunnel-option.d.ts.map

package/dist/src/cli/lib/tunnel-option.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel-option.d.ts","sourceRoot":"","sources":["../../../../src/cli/lib/tunnel-option.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,KAAK,OAAO,EAAgC,MAAM,WAAW,CAAC;AAEvE,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,IAAI,GAAG,KAAK,CAAC;AAwC/C;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CA4BzD"}

package/dist/src/cli/lib/tunnel-option.js

@@ -0,0 +1,77 @@
+/**
+ * Tri-state `--tunnel` option helper for Commander commands.
+ *
+ * Shape:
+ *   --tunnel [auto|on|off]   (default: auto; bare --tunnel = on)
+ *   --no-tunnel              (alias for --tunnel off)
+ *
+ * Invalid values are rejected at parse time with a clear error.
+ *
+ * Bare `--tunnel` (no value) is preserved as sugar for `--tunnel on`, which
+ * matches the pre-tri-state UX. Commander represents the bare form by passing
+ * the literal string `"true"` (or `undefined` depending on argv shape) through
+ * to the parser, so we map both to `'on'`.
+ */
+import { InvalidArgumentError, Option } from 'commander';
+const VALID_MODES = ['auto', 'on', 'off'];
+/**
+ * Parser for --tunnel [mode]. Accepts 'auto' | 'on' | 'off'.
+ * - Bare `--tunnel` (no value) → 'on' (backward-compat sugar).
+ * - `--no-tunnel` (boolean `false`) → 'off'.
+ * - Invalid strings are rejected.
+ */
+function parseTunnelMode(value) {
+    // `--no-tunnel` arrives here as the boolean `false` (Commander's
+    // --no-<flag> negation semantics). Map it to 'off'.
+    if (value === false) {
+        return 'off';
+    }
+    // Bare `--tunnel` (no value). With the `[mode]` optional-arg form,
+    // Commander substitutes the literal string `"true"` as a placeholder
+    // when the flag is present without an explicit value. Treat that and
+    // `undefined` as the backward-compat sugar → 'on'.
+    if (value === undefined || value === true || value === 'true') {
+        return 'on';
+    }
+    if (typeof value !== 'string') {
+        throw new InvalidArgumentError(`Invalid --tunnel value. Expected one of: ${VALID_MODES.join(', ')}.`);
+    }
+    const normalized = value.toLowerCase();
+    if (!VALID_MODES.includes(normalized)) {
+        throw new InvalidArgumentError(`Invalid --tunnel value: "${value}". Expected one of: ${VALID_MODES.join(', ')}.`);
+    }
+    return normalized;
+}
+/**
+ * Attach the tri-state `--tunnel` option to a Commander command.
+ *
+ * The option is stored under the property name `tunnel` on the options
+ * object. Callers can read it as a `TunnelMode`.
+ *
+ * Also registers `--no-tunnel` as an alias that resolves to `'off'`, and
+ * accepts bare `--tunnel` (no value) as sugar for `--tunnel on`.
+ */
+export function addTunnelOption(command) {
+    const option = new Option('--tunnel [mode]', 'Tunnel mode: auto (localhost-only), on (force, default when flag present without value), off (never)')
+        .default('auto')
+        .argParser(parseTunnelMode);
+    command.addOption(option);
+    // `--no-tunnel` as an alias for `--tunnel off`. Commander treats this as a
+    // separate boolean option that, when present, sets the `tunnel` property to
+    // `false`. Normalise that to `'off'` in a preAction hook so downstream
+    // consumers only ever see a `TunnelMode` string.
+    command.option('--no-tunnel', 'Disable tunnel (alias for --tunnel off)');
+    command.hook('preAction', (cmd) => {
+        const opts = cmd.opts();
+        if (opts.tunnel === false) {
+            cmd.setOptionValue('tunnel', 'off');
+        }
+        else if (opts.tunnel === true || opts.tunnel === 'true') {
+            // Bare `--tunnel` with no argParser invocation path (belt-and-braces):
+            // some Commander versions skip argParser when the optional arg is absent.
+            cmd.setOptionValue('tunnel', 'on');
+        }
+    });
+    return command;
+}
+//# sourceMappingURL=tunnel-option.js.map

package/dist/src/cli/lib/tunnel-option.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel-option.js","sourceRoot":"","sources":["../../../../src/cli/lib/tunnel-option.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAgB,oBAAoB,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAIvE,MAAM,WAAW,GAA0B,CAAC,MAAM,EAAE,IAAI,EAAE,KAAK,CAAU,CAAC;AAE1E;;;;;GAKG;AACH,SAAS,eAAe,CAAC,KAAc;IACrC,iEAAiE;IACjE,oDAAoD;IACpD,IAAI,KAAK,KAAK,KAAK,EAAE,CAAC;QACpB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,mEAAmE;IACnE,qEAAqE;IACrE,qEAAqE;IACrE,mDAAmD;IACnD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,MAAM,EAAE,CAAC;QAC9D,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,IAAI,oBAAoB,CAC5B,4CAA4C,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CACtE,CAAC;IACJ,CAAC;IAED,MAAM,UAAU,GAAG,KAAK,CAAC,WAAW,EAAgB,CAAC;IACrD,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QACtC,MAAM,IAAI,oBAAoB,CAC5B,4BAA4B,KAAK,uBAAuB,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAClF,CAAC;IACJ,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,OAAgB;IAC9C,MAAM,MAAM,GAAG,IAAI,MAAM,CACvB,iBAAiB,EACjB,sGAAsG,CACvG;SACE,OAAO,CAAC,MAAoB,CAAC;SAC7B,SAAS,CAAC,eAAe,CAAC,CAAC;IAE9B,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAE1B,2EAA2E;IAC3E,4EAA4E;IAC5E,uEAAuE;IACvE,iDAAiD;IACjD,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,yCAAyC,CAAC,CAAC;IAEzE,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,GAAG,EAAE,EAAE;QAChC,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;QACxB,IAAI,IAAI,CAAC,MAAM,KAAK,KAAK,EAAE,CAAC;YAC1B,GAAG,CAAC,cAAc,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QACtC,CAAC;aAAM,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;YAC1D,uEAAuE;YACvE,0EAA0E;YAC1E,GAAG,CAAC,cAAc,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QACrC,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/src/cli/lib/tunnel-resolve.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Resolve the effective tunnel mode from CLI flag + config file, and
+ * turn that mode into a concrete on/off decision using the base URL
+ * and API URL.
+ *
+ * Precedence for `resolveTunnelFlag`:
+ *   1. CLI flag (if the user explicitly passed --tunnel / --no-tunnel)
+ *   2. Config file (`tunnel` key in ~/.qa-use.json)
+ *   3. Default: 'auto'
+ *
+ * `resolveTunnelMode` is the Phase-2 auto-inference: `'auto'` maps to
+ * `'on'` iff `isLocalhostUrl(baseUrl) && !isLocalhostUrl(apiUrl)`, else
+ * `'off'`. `'on'` and `'off'` are passed through untouched.
+ */
+import type { TunnelMode } from './tunnel-option.js';
+export type { TunnelMode } from './tunnel-option.js';
+/**
+ * Resolve the tunnel mode from CLI + config inputs.
+ *
+ * @param cliFlag - value of the `--tunnel` option after Commander parsing;
+ *   may be `undefined` when the caller hasn't wired the flag yet, or when
+ *   the option has no default (but in practice we default to 'auto', so
+ *   callers will usually pass 'auto' here)
+ * @param configFile - value of `~/.qa-use.json`'s `tunnel` key
+ */
+export declare function resolveTunnelFlag(cliFlag: TunnelMode | undefined, configFile: TunnelMode | undefined): TunnelMode;
+/**
+ * Resolve the concrete on/off decision for the tunnel.
+ *
+ * Matrix:
+ *   - `mode === 'on'`   → `'on'`  (force tunnel, even in dev mode)
+ *   - `mode === 'off'`  → `'off'` (never tunnel)
+ *   - `mode === 'auto'` → `'on'` iff base URL is localhost and API URL is
+ *                         *not* localhost; otherwise `'off'`.
+ *
+ * If either `baseUrl` or `apiUrl` is unknown in `'auto'` mode, we stay
+ * conservative and return `'off'`: without a localhost base URL there's
+ * nothing worth tunnelling, and without a known API URL we can't tell
+ * whether we're in dev mode (where auto-tunnel should be skipped).
+ */
+export declare function resolveTunnelMode(mode: TunnelMode, baseUrl: string | undefined, apiUrl: string | undefined): 'on' | 'off';
+//# sourceMappingURL=tunnel-resolve.d.ts.map

package/dist/src/cli/lib/tunnel-resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel-resolve.d.ts","sourceRoot":"","sources":["../../../../src/cli/lib/tunnel-resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,UAAU,GAAG,SAAS,EAC/B,UAAU,EAAE,UAAU,GAAG,SAAS,GACjC,UAAU,CAgBZ;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,MAAM,EAAE,MAAM,GAAG,SAAS,GACzB,IAAI,GAAG,KAAK,CAWd"}

package/dist/src/cli/lib/tunnel-resolve.js

@@ -0,0 +1,72 @@
+/**
+ * Resolve the effective tunnel mode from CLI flag + config file, and
+ * turn that mode into a concrete on/off decision using the base URL
+ * and API URL.
+ *
+ * Precedence for `resolveTunnelFlag`:
+ *   1. CLI flag (if the user explicitly passed --tunnel / --no-tunnel)
+ *   2. Config file (`tunnel` key in ~/.qa-use.json)
+ *   3. Default: 'auto'
+ *
+ * `resolveTunnelMode` is the Phase-2 auto-inference: `'auto'` maps to
+ * `'on'` iff `isLocalhostUrl(baseUrl) && !isLocalhostUrl(apiUrl)`, else
+ * `'off'`. `'on'` and `'off'` are passed through untouched.
+ */
+import { isLocalhostUrl } from '../../../lib/env/localhost.js';
+/**
+ * Resolve the tunnel mode from CLI + config inputs.
+ *
+ * @param cliFlag - value of the `--tunnel` option after Commander parsing;
+ *   may be `undefined` when the caller hasn't wired the flag yet, or when
+ *   the option has no default (but in practice we default to 'auto', so
+ *   callers will usually pass 'auto' here)
+ * @param configFile - value of `~/.qa-use.json`'s `tunnel` key
+ */
+export function resolveTunnelFlag(cliFlag, configFile) {
+    // Phase 1: we can't reliably distinguish "user passed --tunnel auto" from
+    // "Commander filled in the 'auto' default" without extra bookkeeping on the
+    // command. So the contract here is: the caller gives us the post-parse
+    // value. If they want config precedence to apply, they should pass
+    // `undefined` when the CLI value is the unchanged default. To keep this
+    // phase simple and predictable — and aligned with the plan's "CLI > config
+    // > default 'auto'" precedence — we treat a CLI-passed 'auto' as
+    // "no explicit override" so the config value can take effect.
+    if (cliFlag !== undefined && cliFlag !== 'auto') {
+        return cliFlag;
+    }
+    if (configFile !== undefined) {
+        return configFile;
+    }
+    return 'auto';
+}
+/**
+ * Resolve the concrete on/off decision for the tunnel.
+ *
+ * Matrix:
+ *   - `mode === 'on'`   → `'on'`  (force tunnel, even in dev mode)
+ *   - `mode === 'off'`  → `'off'` (never tunnel)
+ *   - `mode === 'auto'` → `'on'` iff base URL is localhost and API URL is
+ *                         *not* localhost; otherwise `'off'`.
+ *
+ * If either `baseUrl` or `apiUrl` is unknown in `'auto'` mode, we stay
+ * conservative and return `'off'`: without a localhost base URL there's
+ * nothing worth tunnelling, and without a known API URL we can't tell
+ * whether we're in dev mode (where auto-tunnel should be skipped).
+ */
+export function resolveTunnelMode(mode, baseUrl, apiUrl) {
+    if (mode === 'on')
+        return 'on';
+    if (mode === 'off')
+        return 'off';
+    // mode === 'auto'
+    if (!baseUrl)
+        return 'off';
+    if (!isLocalhostUrl(baseUrl))
+        return 'off';
+    // Dev-mode skip: if the API is itself local, the backend can reach
+    // localhost directly — no tunnel needed.
+    if (apiUrl && isLocalhostUrl(apiUrl))
+        return 'off';
+    return 'on';
+}
+//# sourceMappingURL=tunnel-resolve.js.map

package/dist/src/cli/lib/tunnel-resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tunnel-resolve.js","sourceRoot":"","sources":["../../../../src/cli/lib/tunnel-resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAK/D;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAA+B,EAC/B,UAAkC;IAElC,0EAA0E;IAC1E,4EAA4E;IAC5E,uEAAuE;IACvE,mEAAmE;IACnE,wEAAwE;IACxE,2EAA2E;IAC3E,iEAAiE;IACjE,8DAA8D;IAC9D,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QAChD,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,OAAO,UAAU,CAAC;IACpB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAgB,EAChB,OAA2B,EAC3B,MAA0B;IAE1B,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC/B,IAAI,IAAI,KAAK,KAAK;QAAE,OAAO,KAAK,CAAC;IAEjC,kBAAkB;IAClB,IAAI,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAC3B,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC;QAAE,OAAO,KAAK,CAAC;IAC3C,mEAAmE;IACnE,yCAAyC;IACzC,IAAI,MAAM,IAAI,cAAc,CAAC,MAAM,CAAC;QAAE,OAAO,KAAK,CAAC;IACnD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/lib/api/index.ts

@@ -840,9 +840,89 @@ export class ApiClient {
    * Run test definitions with SSE streaming progress
    * @param options - Test execution options
    * @param onEvent - Optional callback for SSE events
+   * @param runtimeOptions - Optional runtime controls (idle timeout, external signal)
    * @returns Promise resolving to test result
    */
-  async runCliTest(options: RunCliTestOptions, onEvent?: SSECallback): Promise<RunCliTestResult> {
+  async runCliTest(
+    options: RunCliTestOptions,
+    onEvent?: SSECallback,
+    runtimeOptions?: { idleTimeoutSec?: number; signal?: AbortSignal }
+  ): Promise<RunCliTestResult> {
+    // Internal AbortController is wired into both `fetch` and `streamSSE` so
+    // we can deterministically tear down the underlying TCP socket on every
+    // exit path. Phase 2 actively aborts on terminal SSE events (`complete` /
+    // `error`) so we don't wait for the backend to close the stream.
+    // Phase 3 widens the public signature to accept a caller signal and an
+    // idle-timeout watchdog (`--timeout` end-to-end).
+    const controller = new AbortController();
+
+    // Tracks why the loop terminated so the catch block can distinguish
+    // "we aborted on purpose because of `complete`/`error`" (swallow the
+    // AbortError, return result) from "real network error or external abort"
+    // (re-throw), or from "idle timeout fired" (throw a typed timeout error).
+    //
+    // The reason is mutated from inside async callbacks (idle watchdog
+    // setTimeout, caller signal abort listener) which TS can't see during
+    // control-flow analysis. We use a small wrapper object so TS doesn't
+    // narrow the type to the literal assigned in the synchronous flow.
+    type TerminationReason = 'complete' | 'idle-timeout' | 'external' | null;
+    const reasonRef: { current: TerminationReason } = { current: null };
+    let result: RunCliTestResult | null = null;
+
+    const idleTimeoutSec = runtimeOptions?.idleTimeoutSec;
+    const idleTimeoutMs =
+      idleTimeoutSec && idleTimeoutSec > 0 ? Math.round(idleTimeoutSec * 1000) : 0;
+    let idleTimer: ReturnType<typeof setTimeout> | null = null;
+
+    const clearIdleTimer = () => {
+      if (idleTimer !== null) {
+        clearTimeout(idleTimer);
+        idleTimer = null;
+      }
+    };
+
+    const armIdleTimer = () => {
+      if (idleTimeoutMs <= 0) return;
+      clearIdleTimer();
+      idleTimer = setTimeout(() => {
+        // Idle watchdog fired — no SSE bytes for `idleTimeoutSec` seconds.
+        // Mark the reason BEFORE aborting so the catch block can throw a
+        // typed timeout error instead of swallowing the AbortError.
+        reasonRef.current = 'idle-timeout';
+        controller.abort();
+      }, idleTimeoutMs);
+      // Don't keep the event loop alive just for the watchdog.
+      if (typeof idleTimer === 'object' && idleTimer && 'unref' in idleTimer) {
+        (idleTimer as { unref: () => void }).unref();
+      }
+    };
+
+    // Wire caller-provided signal: if it aborts, mark `terminationReason` so
+    // the catch block re-throws (instead of swallowing) with the abort error.
+    const callerSignal = runtimeOptions?.signal;
+    let callerAbortListener: (() => void) | null = null;
+    if (callerSignal) {
+      if (callerSignal.aborted) {
+        reasonRef.current = 'external';
+        controller.abort();
+      } else {
+        callerAbortListener = () => {
+          if (reasonRef.current === null) {
+            reasonRef.current = 'external';
+          }
+          controller.abort();
+        };
+        callerSignal.addEventListener('abort', callerAbortListener, { once: true });
+      }
+    }
+
+    // Merge caller signal with internal controller.signal so `fetch` and
+    // `streamSSE` see whichever fires first. `AbortSignal.any` is Node 20.3+
+    // and the project requires Node 20+.
+    const mergedSignal: AbortSignal = callerSignal
+      ? AbortSignal.any([callerSignal, controller.signal])
+      : controller.signal;
+
     try {
       const response = await fetch(`${this.getApiUrl()}/vibe-qa/cli/run`, {
         method: 'POST',
@@ -853,6 +933,7 @@ export class ApiClient {
           Accept: 'text/event-stream',
         },
         body: JSON.stringify(options),
+        signal: mergedSignal,
       });
 
       if (!response.ok) {
@@ -863,28 +944,77 @@ export class ApiClient {
         throw new Error(formatApiError(errorData, `HTTP ${response.status}: Failed to run test`));
       }
 
-      let result: RunCliTestResult | null = null;
-
-      // Stream SSE events
-      for await (const event of streamSSE(response)) {
+      // Arm the idle watchdog AFTER headers arrive — first event may take
+      // a while on a cold backend / large test. We don't punish slow first
+      // bytes; we punish silence between bytes.
+      armIdleTimer();
+
+      // Stream SSE events. `onChunk` resets the idle watchdog on every
+      // byte chunk (so SSE comment pings — which yield zero parsed events
+      // — still keep the connection alive).
+      for await (const event of streamSSE(response, {
+        signal: mergedSignal,
+        onChunk: () => armIdleTimer(),
+      })) {
         if (onEvent) onEvent(event);
 
-        // Capture final result
+        // Capture final result and tear down the socket immediately on a
+        // terminal event. Trailing events (e.g. `test_fixed`, `persisted`)
+        // that may arrive after `complete` are intentionally dropped per the
+        // plan — the backend keeps the SSE stream open, so waiting for it to
+        // close on its own is what causes the ~80s hang we're fixing.
         if (event.event === 'complete' || event.event === 'error') {
           result = event.data;
+          reasonRef.current = 'complete';
+          controller.abort();
+          break;
         }
       }
 
       if (!result) {
+        // No terminal event arrived AND the stream closed (or was aborted).
+        // If we got here via idle timeout, surface that explicitly.
+        if (reasonRef.current === 'idle-timeout') {
+          throw new Error(`Test run timed out: no SSE events for ${idleTimeoutSec}s`);
+        }
         throw new Error('No result received from test execution');
       }
 
       return result;
     } catch (error) {
+      // If we triggered the abort ourselves on a terminal event, the for-await
+      // loop may surface the abort as an AbortError after we've already
+      // captured `result`. Swallow it and return the captured result.
+      if (
+        reasonRef.current === 'complete' &&
+        error instanceof Error &&
+        error.name === 'AbortError' &&
+        result
+      ) {
+        return result;
+      }
+      // Idle-timeout: the abort came from our watchdog, not from a real
+      // network failure. Surface a typed message that tools (and humans)
+      // can grep for.
+      if (
+        reasonRef.current === 'idle-timeout' &&
+        error instanceof Error &&
+        error.name === 'AbortError'
+      ) {
+        throw new Error(`Test run timed out: no SSE events for ${idleTimeoutSec}s`);
+      }
       if (error instanceof Error) {
         throw error;
       }
       throw new Error('Unknown error running test');
+    } finally {
+      // Defensive teardown: abort is idempotent. Guarantees the socket is
+      // released even if the consumer above threw mid-iteration.
+      controller.abort();
+      clearIdleTimer();
+      if (callerSignal && callerAbortListener) {
+        callerSignal.removeEventListener('abort', callerAbortListener);
+      }
     }
   }