@desplega.ai/qa-use 2.14.1 → 2.15.1

package/dist/src/cli/lib/browser.js

@@ -4,23 +4,26 @@
  * Provides automatic localhost tunneling when tests target localhost URLs,
  * and browser WebSocket connection for remote test execution.
  */
-import { URL } from 'node:url';
 import { BrowserManager } from '../../../lib/browser/index.js';
-import { TunnelManager } from '../../../lib/tunnel/index.js';
+import { classifyTunnelFailure, TunnelError } from '../../../lib/tunnel/errors.js';
+import { tunnelRegistry } from '../../../lib/tunnel/registry.js';
 import { error } from './output.js';
+import { printTunnelReuseBanner, printTunnelStartBanner } from './tunnel-banner.js';
+import { formatTunnelFailure } from './tunnel-error-hint.js';
+import { resolveTunnelMode } from './tunnel-resolve.js';
 /**
- * Check if a URL points to localhost
+ * Mirror of `TunnelManager.getWebSocketUrl` for the cross-process
+ * attach case where we don't have a live `TunnelManager` to call.
+ * Converts the tunnel's public HTTPS URL + the local browser WS path
+ * into a `wss://.../devtools/browser/...` URL.
  */
-export function isLocalhostUrl(url) {
+function deriveCrossProcessWsUrl(publicHttpUrl, localWsEndpoint) {
     try {
-        const parsed = new URL(url);
-        return (parsed.hostname === 'localhost' ||
-            parsed.hostname === '127.0.0.1' ||
-            parsed.hostname === '::1' ||
-            parsed.hostname.endsWith('.localhost'));
+        const wsPath = new URL(localWsEndpoint).pathname;
+        return publicHttpUrl.replace('https://', 'wss://').replace('http://', 'ws://') + wsPath;
     }
     catch {
-        return false;
+        return null;
     }
 }
 /**
@@ -39,22 +42,6 @@ export function ensureBrowsersInstalled() {
         process.exit(1);
     }
 }
-/**
- * Get the port from a URL
- */
-export function getPortFromUrl(url) {
-    try {
-        const parsed = new URL(url);
-        if (parsed.port) {
-            return parseInt(parsed.port, 10);
-        }
-        // Default ports
-        return parsed.protocol === 'https:' ? 443 : 80;
-    }
-    catch {
-        return 80;
-    }
-}
 /**
  * Start browser and tunnel (if needed for localhost testing)
  *
@@ -67,6 +54,7 @@ export async function startBrowserWithTunnel(testUrl, options = {}) {
     ensureBrowsersInstalled();
     const browser = new BrowserManager();
     let tunnel = null;
+    let tunnelHandle = null;
     let publicWsUrl = null;
     // Start browser
     console.error('Starting browser...');
@@ -74,24 +62,65 @@ export async function startBrowserWithTunnel(testUrl, options = {}) {
         headless: options.headless ?? true,
     });
     const wsUrl = browserSession.wsEndpoint;
-    const isLocalhost = testUrl ? isLocalhostUrl(testUrl) : false;
-    // If testing localhost, set up tunnel for browser WebSocket
-    if (isLocalhost || !testUrl) {
-        console.error('Localhost URL detected - starting tunnel for browser connection...');
-        tunnel = new TunnelManager();
-        // Extract port from WebSocket URL
-        const wsPort = getPortFromUrl(wsUrl);
-        const tunnelSession = await tunnel.startTunnel(wsPort, {
-            apiKey: options.apiKey,
-            sessionIndex: options.sessionIndex,
-        });
-        publicWsUrl = tunnel.getWebSocketUrl(wsUrl);
-        console.error(`Tunnel established: ${tunnelSession.publicUrl}`);
-        console.error(`Public WebSocket URL: ${publicWsUrl}\n`);
+    // Resolve the on/off decision. Default mode is 'auto' — that way
+    // callers that don't pass `tunnelMode` still get Phase-2 behaviour.
+    const mode = options.tunnelMode ?? 'auto';
+    const decision = resolveTunnelMode(mode, testUrl, options.apiUrl);
+    const isLocalhost = decision === 'on';
+    if (decision === 'on') {
+        // The tunnel target is the browser WebSocket URL — that's what the
+        // remote backend needs to reach. `testUrl` is retained only for the
+        // banner copy so users see the localhost *app* URL they typed.
+        const bannerTarget = testUrl ?? wsUrl;
+        try {
+            tunnelHandle = await tunnelRegistry.acquire(wsUrl, {
+                apiKey: options.apiKey,
+                sessionIndex: options.sessionIndex,
+            });
+            if (tunnelHandle.isCrossProcessAttach) {
+                // Another process owns the TunnelManager. We can't construct a
+                // new one (it would race for the same subdomain). Derive the
+                // public WS URL from the recorded public HTTP URL + our local
+                // ws path — mirrors `TunnelManager.getWebSocketUrl` without
+                // needing an in-process manager.
+                tunnel = null;
+                publicWsUrl = deriveCrossProcessWsUrl(tunnelHandle.publicUrl, wsUrl);
+            }
+            else {
+                // `tunnel` field is a back-compat shim for existing callers
+                // that check `session.tunnel` and reach into
+                // `stopTunnel`/`checkHealth`. The registry owns the lifecycle
+                // now — release goes through `registry.release(handle)` in
+                // `stopBrowserWithTunnel`.
+                tunnel = tunnelRegistry.getLiveManager(wsUrl);
+                publicWsUrl = tunnel ? tunnel.getWebSocketUrl(wsUrl) : null;
+            }
+            // Branch banner: reuse banner when this acquire landed on an
+            // already-running tunnel (refcount > 1 after increment OR we
+            // attached to a sibling process's tunnel), else the fresh-start
+            // banner.
+            const bannerOpts = {
+                target: bannerTarget,
+                publicUrl: tunnelHandle.publicUrl,
+                quiet: options.quiet,
+            };
+            if (tunnelHandle.refcount > 1 || tunnelHandle.isCrossProcessAttach) {
+                printTunnelReuseBanner(bannerOpts);
+            }
+            else {
+                printTunnelStartBanner(bannerOpts);
+            }
+        }
+        catch (err) {
+            const classified = err instanceof TunnelError ? err : classifyTunnelFailure(err, { target: bannerTarget });
+            console.error(formatTunnelFailure(classified));
+            throw classified;
+        }
     }
     return {
         browser,
         tunnel,
+        tunnelHandle,
         wsUrl,
         publicWsUrl,
         isLocalhost,
@@ -101,8 +130,10 @@ export async function startBrowserWithTunnel(testUrl, options = {}) {
  * Stop browser and tunnel
  */
 export async function stopBrowserWithTunnel(session) {
-    if (session.tunnel) {
-        await session.tunnel.stopTunnel();
+    if (session.tunnelHandle) {
+        await tunnelRegistry.release(session.tunnelHandle);
+        session.tunnelHandle = null;
+        session.tunnel = null;
     }
     await session.browser.stopBrowser();
 }

package/dist/src/cli/lib/browser.js.map

@@ -1 +1 @@
-{"version":3,"file":"browser.js","sourceRoot":"","sources":["../../../../src/cli/lib/browser.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../../../../src/cli/lib/browser.ts"],"names":[],"mappings":"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"}

package/dist/src/cli/lib/cli-entry.d.ts

@@ -0,0 +1,40 @@
+/**
+ * CLI re-exec resolver.
+ *
+ * The detached `browser create` path spawns the CLI binary as a child
+ * process and runs it with the hidden `__browser-detach` subcommand. The
+ * parent process needs to deterministically figure out the right
+ * `(command, args)` to invoke, regardless of HOW the parent was invoked:
+ *
+ *   1. Installed binary  — e.g. `qa-use` on PATH (maps to node or bun
+ *      executing the compiled entry under `dist/` or a shim script).
+ *   2. `bun run cli ...` — `process.argv[1]` is a `.ts` file under the
+ *      repo and `process.execPath` is the `bun` binary, which handles
+ *      `.ts` natively.
+ *   3. Symlinked binary — `process.argv[1]` is a symlink; `fs.realpathSync`
+ *      resolves it to the underlying file, so we don't re-exec through a
+ *      broken symlink.
+ *
+ * In every case we return `{ command: process.execPath, args: [realPath, ...] }`
+ * so the child inherits the same runtime (node OR bun) as the parent.
+ */
+export interface CliEntry {
+    /** Executable to spawn (typically `process.execPath`). */
+    command: string;
+    /** Argv to pass (first element is the real script path). */
+    args: string[];
+}
+export interface ResolveCliEntryDeps {
+    argv?: string[];
+    execPath?: string;
+    realpathSync?: (p: string) => string;
+}
+/**
+ * Resolve the `(command, args)` needed to re-exec the CLI binary.
+ *
+ * When `extraArgs` is provided, they are appended after the resolved
+ * script path — callers use this to inject `__browser-detach <session-id>`
+ * and related flags.
+ */
+export declare function resolveCliEntry(extraArgs?: string[], deps?: ResolveCliEntryDeps): CliEntry;
+//# sourceMappingURL=cli-entry.d.ts.map

package/dist/src/cli/lib/cli-entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-entry.d.ts","sourceRoot":"","sources":["../../../../src/cli/lib/cli-entry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,MAAM,WAAW,QAAQ;IACvB,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,CAAC;CACtC;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,SAAS,GAAE,MAAM,EAAO,EACxB,IAAI,GAAE,mBAAwB,GAC7B,QAAQ,CAsCV"}

package/dist/src/cli/lib/cli-entry.js

@@ -0,0 +1,65 @@
+/**
+ * CLI re-exec resolver.
+ *
+ * The detached `browser create` path spawns the CLI binary as a child
+ * process and runs it with the hidden `__browser-detach` subcommand. The
+ * parent process needs to deterministically figure out the right
+ * `(command, args)` to invoke, regardless of HOW the parent was invoked:
+ *
+ *   1. Installed binary  — e.g. `qa-use` on PATH (maps to node or bun
+ *      executing the compiled entry under `dist/` or a shim script).
+ *   2. `bun run cli ...` — `process.argv[1]` is a `.ts` file under the
+ *      repo and `process.execPath` is the `bun` binary, which handles
+ *      `.ts` natively.
+ *   3. Symlinked binary — `process.argv[1]` is a symlink; `fs.realpathSync`
+ *      resolves it to the underlying file, so we don't re-exec through a
+ *      broken symlink.
+ *
+ * In every case we return `{ command: process.execPath, args: [realPath, ...] }`
+ * so the child inherits the same runtime (node OR bun) as the parent.
+ */
+import fs from 'node:fs';
+/**
+ * Resolve the `(command, args)` needed to re-exec the CLI binary.
+ *
+ * When `extraArgs` is provided, they are appended after the resolved
+ * script path — callers use this to inject `__browser-detach <session-id>`
+ * and related flags.
+ */
+export function resolveCliEntry(extraArgs = [], deps = {}) {
+    const argv = deps.argv ?? process.argv;
+    const execPath = deps.execPath ?? process.execPath;
+    const realpathSync = deps.realpathSync ?? fs.realpathSync;
+    const rawEntry = argv[1];
+    if (!rawEntry) {
+        throw new Error('resolveCliEntry: process.argv[1] is empty — cannot re-exec the CLI');
+    }
+    let resolvedEntry;
+    try {
+        resolvedEntry = realpathSync(rawEntry);
+    }
+    catch {
+        // Fallback to the raw path if realpath fails (e.g. rare sandboxed
+        // environments). We still want the spawn to attempt with what we have
+        // rather than bubble an unrelated error.
+        resolvedEntry = rawEntry;
+    }
+    // If the entry is a TypeScript source file and the runtime is Node.js
+    // (not Bun), raw `node` can't execute it — we need the tsx loader. This
+    // happens in dev (`bun run cli` / `npm run cli` → `tsx src/cli/index.ts`).
+    // Under Bun, .ts is native. In production (installed binary), the entry
+    // is a compiled .js under dist/.
+    const isTsEntry = /\.(ts|tsx|mts|cts)$/.test(resolvedEntry);
+    const isBun = typeof globalThis.Bun !== 'undefined';
+    if (isTsEntry && !isBun) {
+        return {
+            command: execPath,
+            args: ['--import', 'tsx', resolvedEntry, ...extraArgs],
+        };
+    }
+    return {
+        command: execPath,
+        args: [resolvedEntry, ...extraArgs],
+    };
+}
+//# sourceMappingURL=cli-entry.js.map

package/dist/src/cli/lib/cli-entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-entry.js","sourceRoot":"","sources":["../../../../src/cli/lib/cli-entry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AAezB;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAC7B,YAAsB,EAAE,EACxB,OAA4B,EAAE;IAE9B,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IACvC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ,CAAC;IACnD,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,IAAI,EAAE,CAAC,YAAY,CAAC;IAE1D,MAAM,QAAQ,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;IACzB,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,oEAAoE,CAAC,CAAC;IACxF,CAAC;IAED,IAAI,aAAqB,CAAC;IAC1B,IAAI,CAAC;QACH,aAAa,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,kEAAkE;QAClE,sEAAsE;QACtE,yCAAyC;QACzC,aAAa,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED,sEAAsE;IACtE,wEAAwE;IACxE,2EAA2E;IAC3E,wEAAwE;IACxE,iCAAiC;IACjC,MAAM,SAAS,GAAG,qBAAqB,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAC5D,MAAM,KAAK,GAAG,OAAQ,UAAgC,CAAC,GAAG,KAAK,WAAW,CAAC;IAC3E,IAAI,SAAS,IAAI,CAAC,KAAK,EAAE,CAAC;QACxB,OAAO;YACL,OAAO,EAAE,QAAQ;YACjB,IAAI,EAAE,CAAC,UAAU,EAAE,KAAK,EAAE,aAAa,EAAE,GAAG,SAAS,CAAC;SACvD,CAAC;IACJ,CAAC;IAED,OAAO;QACL,OAAO,EAAE,QAAQ;QACjB,IAAI,EAAE,CAAC,aAAa,EAAE,GAAG,SAAS,CAAC;KACpC,CAAC;AACJ,CAAC"}

package/dist/src/cli/lib/runner.d.ts

@@ -15,6 +15,12 @@ export interface RunTestOptions {
     testId?: string;
     /** Run ID for organizing downloads (set automatically) */
     runId?: string;
+    /**
+     * Idle timeout in seconds. If no SSE events arrive for this long, the
+     * underlying fetch is aborted and `runCliTest` rejects with a `timed out`
+     * error. `0` (or undefined) disables the watchdog.
+     */
+    idleTimeoutSec?: number;
 }
 /**
  * Run a test with real-time progress output

package/dist/src/cli/lib/runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../../../src/cli/lib/runner.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAChG,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAGxD,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,8CAA8C;IAC9C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,mCAAmC;IACnC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,uCAAuC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,wBAAsB,OAAO,CAC3B,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,iBAAiB,EAC1B,UAAU,GAAE,cAAmB,EAC/B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,GAClC,OAAO,CAAC,gBAAgB,CAAC,CAgB3B;AAED;;;;;;GAMG;AACH,wBAAsB,QAAQ,CAC5B,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,iBAAiB,EAAE,GACzB,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAU7B"}
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../../../src/cli/lib/runner.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAChG,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAGxD,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,8CAA8C;IAC9C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,mCAAmC;IACnC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,uCAAuC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,wBAAsB,OAAO,CAC3B,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,iBAAiB,EAC1B,UAAU,GAAE,cAAmB,EAC/B,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,GAClC,OAAO,CAAC,gBAAgB,CAAC,CA4B3B;AAED;;;;;;GAMG;AACH,wBAAsB,QAAQ,CAC5B,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,iBAAiB,EAAE,GACzB,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAU7B"}

package/dist/src/cli/lib/runner.js

@@ -12,7 +12,7 @@ import { printSSEProgress } from './output.js';
  * @returns Test result
  */
 export async function runTest(client, options, runOptions = {}, onEvent) {
-    const { verbose = false, sourceFile, download, downloadBaseDir, testId, runId } = runOptions;
+    const { verbose = false, sourceFile, download, downloadBaseDir, testId, runId, idleTimeoutSec, } = runOptions;
     // Build context for SSE progress handler
     const context = sourceFile || download ? { sourceFile, download, downloadBaseDir, testId, runId } : undefined;
     return await client.runCliTest(options, (event) => {
@@ -22,7 +22,7 @@ export async function runTest(client, options, runOptions = {}, onEvent) {
         if (onEvent) {
             onEvent(event);
         }
-    });
+    }, { idleTimeoutSec });
 }
 /**
  * Run multiple tests sequentially

package/dist/src/cli/lib/runner.js.map

@@ -1 +1 @@
-{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../../../src/cli/lib/runner.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EAAE,gBAAgB,EAA2B,MAAM,aAAa,CAAC;AAgBxE;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,MAAiB,EACjB,OAA0B,EAC1B,aAA6B,EAAE,EAC/B,OAAmC;IAEnC,MAAM,EAAE,OAAO,GAAG,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,UAAU,CAAC;IAE7F,yCAAyC;IACzC,MAAM,OAAO,GACX,UAAU,IAAI,QAAQ,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAEhG,OAAO,MAAM,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;QAChD,4BAA4B;QAC5B,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAE1C,uCAAuC;QACvC,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,CAAC,KAAK,CAAC,CAAC;QACjB,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,MAAiB,EACjB,KAA0B;IAE1B,MAAM,OAAO,GAAuB,EAAE,CAAC;IAEvC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,OAAO,CAAC,CAAC;QAC5D,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/C,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACvB,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../../../src/cli/lib/runner.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EAAE,gBAAgB,EAA2B,MAAM,aAAa,CAAC;AAsBxE;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,MAAiB,EACjB,OAA0B,EAC1B,aAA6B,EAAE,EAC/B,OAAmC;IAEnC,MAAM,EACJ,OAAO,GAAG,KAAK,EACf,UAAU,EACV,QAAQ,EACR,eAAe,EACf,MAAM,EACN,KAAK,EACL,cAAc,GACf,GAAG,UAAU,CAAC;IAEf,yCAAyC;IACzC,MAAM,OAAO,GACX,UAAU,IAAI,QAAQ,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAEhG,OAAO,MAAM,MAAM,CAAC,UAAU,CAC5B,OAAO,EACP,CAAC,KAAK,EAAE,EAAE;QACR,4BAA4B;QAC5B,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAE1C,uCAAuC;QACvC,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,CAAC,KAAK,CAAC,CAAC;QACjB,CAAC;IACH,CAAC,EACD,EAAE,cAAc,EAAE,CACnB,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,MAAiB,EACjB,KAA0B;IAE1B,MAAM,OAAO,GAAuB,EAAE,CAAC;IAEvC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,OAAO,CAAC,CAAC;QAC5D,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/C,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACvB,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/src/cli/lib/startup-sweep.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Bounded startup sweep — runs on every CLI invocation except `doctor`
+ * itself and `__browser-detach`. Cheap, silent-on-success cleanup of
+ * orphaned PID files whose owning process is no longer alive.
+ *
+ * Design constraints:
+ *   - **Budget**: 250 ms hard cap. We stop iterating early if the budget
+ *     is exceeded, even if more stale entries remain. `doctor` picks up
+ *     the rest on the next explicit run.
+ *   - **Zero net/API calls**. We only remove PID files and force-close
+ *     tunnel registry entries (in-process). Backend session-end calls
+ *     belong to `doctor`, not to the sweep.
+ *   - **Silent on success**. A single-line stderr notice only when we
+ *     actually reaped something: `qa-use: cleaned up N stale session(s)`.
+ *   - **Safe on empty state**. If `~/.qa-use/sessions/` or
+ *     `~/.qa-use/tunnels/` doesn't exist, return immediately.
+ */
+/**
+ * Determine whether to run the sweep for this CLI invocation. Looks at
+ * `process.argv` positionally — we don't have the parsed Commander tree
+ * available at this stage.
+ */
+export declare function shouldSweep(argv?: string[]): boolean;
+interface SweepResult {
+    reapedSessions: number;
+    reapedTunnels: number;
+    budgetExceeded: boolean;
+}
+/**
+ * Run the bounded sweep. Returns a summary object; callers may use it for
+ * tests. The function never throws — failures are swallowed so startup
+ * is never blocked.
+ */
+export declare function runStartupSweep(): Promise<SweepResult>;
+/**
+ * Entry point for `src/cli/index.ts`. Fire-and-forget: we kick off the
+ * sweep but don't await it — subsequent CLI work can run in parallel.
+ * The sweep's own budget guarantees it won't hold the process open for
+ * long.
+ *
+ * If the sweep reaped anything, we emit a single-line stderr notice.
+ */
+export declare function kickoffStartupSweep(argv?: string[]): void;
+export {};
+//# sourceMappingURL=startup-sweep.d.ts.map

package/dist/src/cli/lib/startup-sweep.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"startup-sweep.d.ts","sourceRoot":"","sources":["../../../../src/cli/lib/startup-sweep.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAqBH;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CA+BlE;AAED,UAAU,WAAW;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,OAAO,CAAC;CACzB;AAwGD;;;;GAIG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,WAAW,CAAC,CAmB5D;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,GAAE,MAAM,EAAiB,GAAG,IAAI,CAuBvE"}

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

@@ -0,0 +1,246 @@
+/**
+ * Bounded startup sweep — runs on every CLI invocation except `doctor`
+ * itself and `__browser-detach`. Cheap, silent-on-success cleanup of
+ * orphaned PID files whose owning process is no longer alive.
+ *
+ * Design constraints:
+ *   - **Budget**: 250 ms hard cap. We stop iterating early if the budget
+ *     is exceeded, even if more stale entries remain. `doctor` picks up
+ *     the rest on the next explicit run.
+ *   - **Zero net/API calls**. We only remove PID files and force-close
+ *     tunnel registry entries (in-process). Backend session-end calls
+ *     belong to `doctor`, not to the sweep.
+ *   - **Silent on success**. A single-line stderr notice only when we
+ *     actually reaped something: `qa-use: cleaned up N stale session(s)`.
+ *   - **Safe on empty state**. If `~/.qa-use/sessions/` or
+ *     `~/.qa-use/tunnels/` doesn't exist, return immediately.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { sessionsDir, tunnelsDir } from '../../../lib/env/paths.js';
+import { isPidAlive } from '../../../lib/env/sessions.js';
+import { tunnelRegistry } from '../../../lib/tunnel/registry.js';
+const BUDGET_MS = 250;
+/**
+ * Commands that MUST NOT trigger a sweep:
+ *   - `doctor` — runs its own fuller reap; double-reap is a no-op but
+ *     noisy when it prints "cleaned up N" from the sweep, immediately
+ *     followed by doctor's own report of zero.
+ *   - `__browser-detach` — the detached child. It is itself a freshly
+ *     spawned process whose PID file we may not have written yet; the
+ *     sweep must not race with that write.
+ */
+const SKIP_COMMANDS = new Set(['doctor', '__browser-detach']);
+/**
+ * Determine whether to run the sweep for this CLI invocation. Looks at
+ * `process.argv` positionally — we don't have the parsed Commander tree
+ * available at this stage.
+ */
+export function shouldSweep(argv = process.argv) {
+    // argv[0] = node, argv[1] = cli entry. Command is argv[2] unless it's
+    // a flag (e.g. `--version`, `--help` alone). Additionally, many nested
+    // commands (e.g. `browser __browser-detach`) have the sentinel in
+    // argv[3]; scan the first few entries.
+    for (let i = 2; i < Math.min(argv.length, 5); i++) {
+        const token = argv[i];
+        if (!token || token.startsWith('-'))
+            continue;
+        if (SKIP_COMMANDS.has(token))
+            return false;
+        // First non-flag token found; it's the top-level command. Return true
+        // if it isn't a skip command (already handled).
+        // We still check nested tokens because `browser __browser-detach` has
+        // the sentinel in position i+1.
+    }
+    // Also explicitly scan entire argv for __browser-detach (can be nested).
+    if (argv.includes('__browser-detach'))
+        return false;
+    // `browser status` (with or without --list / session id) must not sweep:
+    // the sweep would race with rendering and silently reap the very
+    // stale entries the user asked to see. `browser` followed (somewhere)
+    // by `status` is the canonical shape we skip. Other `browser`
+    // subcommands (create/close/snapshot/...) still sweep normally.
+    const browserIdx = argv.indexOf('browser');
+    if (browserIdx !== -1) {
+        for (let i = browserIdx + 1; i < argv.length; i++) {
+            const token = argv[i];
+            if (!token || token.startsWith('-'))
+                continue;
+            if (token === 'status')
+                return false;
+            break;
+        }
+    }
+    return true;
+}
+async function sweepSessions(deadline) {
+    const dir = sessionsDir();
+    let files;
+    try {
+        files = fs.readdirSync(dir);
+    }
+    catch {
+        return 0;
+    }
+    let reaped = 0;
+    for (const name of files) {
+        if (Date.now() >= deadline)
+            break;
+        if (!name.endsWith('.json') || name.endsWith('.tmp'))
+            continue;
+        const file = path.join(dir, name);
+        let parsed = null;
+        try {
+            const raw = fs.readFileSync(file, 'utf8');
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            // Unreadable file — remove it.
+            try {
+                fs.unlinkSync(file);
+                reaped += 1;
+            }
+            catch {
+                /* ignore */
+            }
+            continue;
+        }
+        if (!parsed || typeof parsed.pid !== 'number') {
+            try {
+                fs.unlinkSync(file);
+                reaped += 1;
+            }
+            catch {
+                /* ignore */
+            }
+            continue;
+        }
+        if (!isPidAlive(parsed.pid)) {
+            try {
+                fs.unlinkSync(file);
+            }
+            catch {
+                /* already gone */
+            }
+            // Best-effort: if the session referenced a tunnel target, ensure
+            // any registry handle is released in-process. No net calls.
+            if (parsed.target) {
+                try {
+                    await tunnelRegistry.forceClose(parsed.target);
+                }
+                catch {
+                    /* best-effort */
+                }
+            }
+            reaped += 1;
+        }
+    }
+    return reaped;
+}
+async function sweepTunnels(deadline) {
+    const dir = tunnelsDir();
+    let files;
+    try {
+        files = fs.readdirSync(dir);
+    }
+    catch {
+        return 0;
+    }
+    let reaped = 0;
+    for (const name of files) {
+        if (Date.now() >= deadline)
+            break;
+        if (!name.endsWith('.json') || name.endsWith('.tmp'))
+            continue;
+        const file = path.join(dir, name);
+        let parsed = null;
+        try {
+            const raw = fs.readFileSync(file, 'utf8');
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            try {
+                fs.unlinkSync(file);
+                reaped += 1;
+            }
+            catch {
+                /* ignore */
+            }
+            continue;
+        }
+        if (!parsed || typeof parsed.pid !== 'number' || !isPidAlive(parsed.pid)) {
+            if (parsed?.target) {
+                try {
+                    await tunnelRegistry.forceClose(parsed.target);
+                }
+                catch {
+                    /* best-effort; fall through to manual unlink */
+                }
+            }
+            try {
+                fs.unlinkSync(file);
+            }
+            catch {
+                /* already gone */
+            }
+            reaped += 1;
+        }
+    }
+    return reaped;
+}
+/**
+ * Run the bounded sweep. Returns a summary object; callers may use it for
+ * tests. The function never throws — failures are swallowed so startup
+ * is never blocked.
+ */
+export async function runStartupSweep() {
+    const deadline = Date.now() + BUDGET_MS;
+    const result = {
+        reapedSessions: 0,
+        reapedTunnels: 0,
+        budgetExceeded: false,
+    };
+    try {
+        result.reapedSessions = await sweepSessions(deadline);
+        if (Date.now() < deadline) {
+            result.reapedTunnels = await sweepTunnels(deadline);
+        }
+    }
+    catch {
+        /* never surface sweep failures */
+    }
+    if (Date.now() >= deadline) {
+        result.budgetExceeded = true;
+    }
+    return result;
+}
+/**
+ * Entry point for `src/cli/index.ts`. Fire-and-forget: we kick off the
+ * sweep but don't await it — subsequent CLI work can run in parallel.
+ * The sweep's own budget guarantees it won't hold the process open for
+ * long.
+ *
+ * If the sweep reaped anything, we emit a single-line stderr notice.
+ */
+export function kickoffStartupSweep(argv = process.argv) {
+    if (!shouldSweep(argv))
+        return;
+    void runStartupSweep()
+        .then((result) => {
+        const total = result.reapedSessions + result.reapedTunnels;
+        if (total > 0) {
+            const parts = [];
+            if (result.reapedSessions > 0) {
+                parts.push(`${result.reapedSessions} stale session${result.reapedSessions === 1 ? '' : 's'}`);
+            }
+            if (result.reapedTunnels > 0) {
+                parts.push(`${result.reapedTunnels} stale tunnel${result.reapedTunnels === 1 ? '' : 's'}`);
+            }
+            console.error(`qa-use: cleaned up ${parts.join(' + ')}`);
+        }
+    })
+        .catch(() => {
+        /* never surface sweep failures */
+    });
+}
+//# sourceMappingURL=startup-sweep.js.map