@desplega.ai/qa-use 2.14.0 → 2.15.0

package/dist/src/cli/generated/docs-content.js

@@ -56,11 +56,18 @@ qa-use info
 
 **CLI Workflow:**
 \`\`\`bash
-# Create browser session
+# Create browser session (returns immediately — runs detached in the background)
 qa-use browser create --viewport desktop
 
-# For localhost testing
-qa-use browser create --tunnel --no-headless
+# For localhost testing — auto-tunnels when base URL is localhost and API is remote.
+# No flag needed for the common case:
+qa-use browser create --no-headless http://localhost:3000
+
+# Force a tunnel even in dev mode:
+qa-use browser create --tunnel on --no-headless
+
+# Opt out of auto-tunnel (e.g. backend is also local):
+qa-use browser create --no-tunnel
 
 # Navigate
 qa-use browser goto https://example.com
@@ -76,6 +83,30 @@ qa-use browser fill e5 "text"
 qa-use browser close
 \`\`\`
 
+**Background session management:**
+
+\`qa-use browser create\` returns immediately — the actual browser + tunnel run in a detached child process so your terminal stays free. Manage sessions with:
+
+\`\`\`bash
+qa-use browser status --list   # Show all active sessions across processes
+qa-use browser status           # Details for the auto-resolved session
+qa-use browser close <id>       # Close a specific session
+qa-use doctor                   # Reap stale sessions/tunnels (dead PIDs)
+qa-use doctor --dry-run         # Preview what would be cleaned
+\`\`\`
+
+**Tunnel commands:**
+
+Cross-process tunnel registry — multiple commands share a single tunnel per target:
+
+\`\`\`bash
+qa-use tunnel start <url>         # Acquire a tunnel (released immediately unless --hold)
+qa-use tunnel start <url> --hold  # Keep the tunnel up until Ctrl+C
+qa-use tunnel ls                  # List active tunnels (target, public URL, refcount)
+qa-use tunnel status <target>     # Detail for a single tunnel
+qa-use tunnel close <target>      # Force-release a tunnel (kills detached holders)
+\`\`\`
+
 **Plugin Shortcut:**
 \`\`\`
 /qa-use:explore https://example.com
@@ -114,8 +145,8 @@ Blocks are atomic recorded interactions from a browser session. They are:
 **How blocks work:**
 
 \`\`\`bash
-# 1. Create session and interact
-qa-use browser create --tunnel --no-headless
+# 1. Create session and interact (auto-tunnels localhost)
+qa-use browser create --no-headless
 qa-use browser goto https://example.com
 qa-use browser snapshot        # Returns: [ref=e1] button
 qa-use browser click e1        # Records as block
@@ -218,17 +249,22 @@ local tests.
 |---------|-------------|
 | \`qa-use browser create\` | Create remote browser session |
 | \`qa-use browser create <url>\` | Create session and navigate to URL |
-| \`qa-use browser create --tunnel\` | Create local browser with API tunnel |
-| \`qa-use browser create --no-headless\` | Show browser window (tunnel mode only) |
+| \`qa-use browser create --tunnel [auto\\|on\\|off]\` | Tunnel mode — default \`auto\` (localhost + remote API). \`--no-tunnel\` is sugar for \`off\`. |
+| \`qa-use browser create --no-headless\` | Show browser window (paired with a local/tunnel browser) |
 | \`qa-use browser create --viewport <size>\` | Set viewport: \`desktop\`, \`tablet\`, \`mobile\` |
 | \`qa-use browser create --ws-url <url>\` | Connect to existing WebSocket browser |
 | \`qa-use browser create --after-test-id <uuid>\` | Run a test first, then become interactive |
 | \`qa-use browser create --var <key=value>\` | Override app config variables (repeatable) |
 | \`qa-use browser list\` | List active sessions |
 | \`qa-use browser status\` | Show current session details (app_url, recording_url, etc.) |
+| \`qa-use browser status --list\` | Show all active sessions across processes |
 | \`qa-use browser close\` | Close active session |
+| \`qa-use browser close <id>\` | Close a specific session by id |
+| \`qa-use doctor\` | Reap stale sessions/tunnels (dead PIDs) |
+| \`qa-use tunnel ls\` | List active tunnels in the registry |
+| \`qa-use tunnel start <url> --hold\` | Hold a public tunnel for external consumers |
 
-Sessions auto-persist in \`~/.qa-use.json\`. One active session = no \`-s\` flag needed.
+Sessions auto-persist in \`~/.qa-use.json\`. One active session = no \`-s\` flag needed. \`browser create\` returns immediately — the browser + tunnel run in a detached child. Use \`qa-use doctor\` if stale state accumulates.
 
 ### Navigation
 
@@ -284,7 +320,7 @@ Use diff output to interact with newly appeared elements directly, without runni
 |---------|-------------|
 | \`qa-use test run <name>\` | Run test by name |
 | \`qa-use test run --all\` | Run all tests |
-| \`qa-use test run <name> --tunnel\` | Run with local browser tunnel |
+| \`qa-use test run <name> --tunnel [mode]\` | Override tunnel mode (\`auto\`, \`on\`, \`off\`). \`--no-tunnel\` is sugar for \`off\`. Bare \`--tunnel\` is sugar for \`on\`. |
 | \`qa-use test run <name> --download\` | Download assets to \`/tmp/qa-use/downloads/\` |
 | \`qa-use test run <name> --var key=value\` | Override variable |
 | \`qa-use test validate <name>\` | Validate test syntax |
@@ -399,8 +435,8 @@ qa-use browser logs console
 
 **CLI Workflow:**
 \`\`\`bash
-# 1. Create session
-qa-use browser create --tunnel --no-headless
+# 1. Create session (auto-tunnels localhost targets)
+qa-use browser create --no-headless
 
 # 2. Navigate and interact
 qa-use browser goto https://example.com
@@ -466,7 +502,7 @@ qa-use test run login
 **CLI Workflow:**
 \`\`\`bash
 # Create session and navigate
-qa-use browser create --tunnel --no-headless
+qa-use browser create --no-headless
 qa-use browser goto https://evals.desplega.ai/checkboxes
 
 # goto shows diff — initial page load shows all elements:
@@ -555,32 +591,28 @@ jobs:
 
 ## Advanced Topics
 
-### Localhost Testing (Tunnel Mode)
+### Localhost Testing (Auto-Tunnel)
 
-**When to use tunnel mode:**
+**qa-use auto-tunnels localhost targets when the API is remote.** No flag required for the common case:
 
-\`\`\`
-Testing localhost (http://localhost:3000)?
-  ├─ YES → Use --tunnel
-  │   └─ qa-use browser create --tunnel [--no-headless]
-  │       (Starts local Playwright, creates localtunnel, keeps running)
-  │
-  └─ NO (Public URL) → Use remote browser (default)
-      └─ qa-use browser create
-          (Uses desplega.ai cloud browser via WebSocket)
+\`\`\`bash
+qa-use browser create --no-headless http://localhost:3000
+qa-use test run my_test   # auto-tunnels if base_url is localhost
 \`\`\`
 
-**The \`--tunnel\` flag is a binary choice:**
-- **Local tunnel mode**: Playwright on your machine + localtunnel
-- **Remote mode**: WebSocket URL to cloud-hosted browser
+**Tri-state \`--tunnel\` flag:**
 
-**For test execution:**
-\`\`\`bash
-# Local app
-qa-use test run my_test --tunnel [--headful]
+| Value | Behavior |
+|-------|----------|
+| \`auto\` (default) | Tunnel iff base URL is localhost AND API URL is remote |
+| \`on\` (or bare \`--tunnel\`) | Force a tunnel even in dev mode |
+| \`off\` (or \`--no-tunnel\`) | Never tunnel |
 
-# Public app
-qa-use test run my_test
+\`\`\`
+Testing localhost (http://localhost:3000)?
+  ├─ API remote (default)  → auto-tunnels. No flag needed.
+  ├─ API also local (dev)  → no tunnel by default. Use --tunnel on to force.
+  └─ Public URL target     → no tunnel (remote cloud browser)
 \`\`\`
 
 **Plugin shortcuts handle tunnel detection automatically:**
@@ -615,8 +647,8 @@ Sessions are stored in \`~/.qa-use.json\` and have:
 
 **Sharing sessions across processes:**
 \`\`\`bash
-# Process 1: Create session
-qa-use browser create --tunnel
+# Process 1: Create session (auto-tunnels if target is localhost + API remote)
+qa-use browser create http://localhost:3000
 # Output: ws://localhost:12345/browser/abc123
 
 # Process 2: Connect to session
@@ -681,7 +713,7 @@ See [references/test-format.md](references/test-format.md) for complete specific
 | \`browser close <session-id>\` | \`browser close\` |
 | Guessing element refs | Use refs from diff output or \`snapshot\` |
 | Running \`snapshot\` after every action | Use diff output; only \`snapshot\` when needed |
-| Testing localhost without \`--tunnel\` | Use \`--tunnel\` flag |
+| Forcing \`--tunnel\` in dev (both local) | Rely on auto-mode, or use \`--tunnel on\` explicitly |
 | \`test sync --pull\` | \`test sync pull\` (subcommand, not flag) |
 | \`test sync --push\` | \`test sync push\` (subcommand, not flag) |
 
@@ -745,9 +777,10 @@ qa-use browser create [url] [options]
 |------|-------------|
 | \`[url]\` | URL to navigate to after session is ready |
 | \`--viewport <size>\` | Viewport size: \`desktop\` (1280x720), \`tablet\` (768x1024), \`mobile\` (375x667) |
-| \`--tunnel\` | Run local browser with API tunnel (for localhost testing) |
-| \`--headless\` | Run in headless mode (default with \`--tunnel\`) |
-| \`--no-headless\` | Show browser window (use with \`--tunnel\` for debugging) |
+| \`--tunnel [mode]\` | Tunnel mode: \`auto\` (default — tunnel iff localhost base + remote API), \`on\` (force), \`off\` (never). Bare \`--tunnel\` is sugar for \`on\`. |
+| \`--no-tunnel\` | Shortcut for \`--tunnel off\` |
+| \`--headless\` | Run in headless mode (default for tunnel/local browsers) |
+| \`--no-headless\` | Show browser window (debugging) |
 | \`--ws-url <url>\` | Connect to existing WebSocket browser endpoint |
 | \`--after-test-id <uuid>\` | Run a test before session becomes interactive (start after login, etc.) |
 
@@ -756,8 +789,9 @@ qa-use browser create [url] [options]
 qa-use browser create                        # Remote browser, default viewport
 qa-use browser create https://example.com    # Remote browser, navigate to URL
 qa-use browser create --viewport mobile      # Remote browser, mobile viewport
-qa-use browser create --tunnel               # Local headless browser with tunnel
-qa-use browser create --tunnel --no-headless # Local visible browser for debugging
+qa-use browser create http://localhost:3000  # Auto-tunnels (localhost + remote API)
+qa-use browser create --tunnel on --no-headless  # Force tunnel + visible browser
+qa-use browser create --no-tunnel            # Opt out of auto-tunnel
 qa-use browser create --ws-url wss://...     # Connect to existing browser
 qa-use browser create --after-test-id <uuid> # Start session after running a test
 qa-use browser create --after-test-id <uuid> https://example.com/dashboard  # After login, go to dashboard
@@ -1202,11 +1236,11 @@ Opens interactive REPL for browser commands. Use \`--after-test-id\` to start th
 
 ## Local Browser with Tunnel
 
-The \`--tunnel\` flag starts a real browser on your machine with a tunnel for API control:
+qa-use auto-tunnels when your target is localhost and the API is remote — no flag required. Use the tri-state \`--tunnel\` flag only to override:
 
 1. **Browser runs locally** - you can see it (with \`--no-headless\`)
 2. **API controls via tunnel** - cloud API sends commands through the tunnel
-3. **Auto-cleanup** - session closes when you press Ctrl+C or run \`browser close\`
+3. **Detached lifecycle** - \`browser create\` returns immediately; the tunnel runs in a background child until \`browser close\` or TTL
 
 **Use cases:**
 - Debugging tests visually
@@ -1214,17 +1248,22 @@ The \`--tunnel\` flag starts a real browser on your machine with a tunnel for AP
 - Developing tests interactively
 
 \`\`\`bash
-# Start visible local browser
-qa-use browser create --tunnel --no-headless
+# Auto-mode — localhost + remote API tunnels automatically
+qa-use browser create --no-headless http://localhost:3000
 
-# Now interact normally
-qa-use browser goto http://localhost:3000
+# Force a tunnel in dev mode (both sides local)
+qa-use browser create --tunnel on --no-headless
+
+# Opt out of tunnel entirely
+qa-use browser create --no-tunnel
+
+# Interact normally
 qa-use browser snapshot
 qa-use browser click e3
-
-# Watch the browser respond in real-time
 \`\`\`
 
+See [localhost-testing.md](localhost-testing.md) for full tunnel mode documentation, \`qa-use tunnel *\` commands, and \`qa-use doctor\`.
+
 ---
 
 > **Runtime access:** \`qa-use docs browser-commands\` | All topics: \`qa-use docs --list\`
@@ -1800,7 +1839,9 @@ Test Failed
         title: 'Localhost Testing',
         content: `# Localhost Testing
 
-Testing applications running on \`localhost\` requires a tunnel because the cloud-hosted browser cannot access your local machine.
+**When your base URL is localhost and your API is remote, qa-use auto-tunnels. No flag required.**
+
+Testing applications running on \`localhost\` usually requires a tunnel because the cloud-hosted browser cannot reach your local machine. qa-use detects this automatically — the tri-state \`--tunnel\` flag only needs to be set for the edge cases.
 
 ## Why Tunnels Are Needed
 
@@ -1832,79 +1873,83 @@ With tunnel: Local browser accesses localhost,
              API controls browser through tunnel
 \`\`\`
 
-## Using \`--tunnel\` Flag
+## Auto-Tunnel (Default)
 
-The simplest approach - add \`--tunnel\` to your test run command:
+For the common case — your app on \`http://localhost:3000\`, your API at \`https://api.desplega.ai\` — you don't need to pass any flag:
 
 \`\`\`bash
-qa-use test run my-test --tunnel
+# Base URL is localhost, API is remote → qa-use auto-tunnels
+qa-use browser create --no-headless http://localhost:3000
+qa-use test run my-test
 \`\`\`
 
 This:
-1. Starts a local headless browser
+1. Starts a local browser (Playwright)
 2. Creates a tunnel for API control
-3. Runs the test
-4. Cleans up automatically
+3. Runs your commands/tests
+4. Cleans up automatically when the session closes
 
-### With Visible Browser
+## Tri-State \`--tunnel\` Flag
 
-For debugging, add \`--headful\`:
+Use \`--tunnel\` only when you need to override the auto-decision:
 
-\`\`\`bash
-qa-use test run my-test --tunnel --headful
+| Flag form | Mode | When to use |
+|-----------|------|-------------|
+| _(none)_ | \`auto\` | Default. Tunnel iff localhost base + remote API. |
+| \`--tunnel\` / \`--tunnel on\` | \`on\` | Force a tunnel — e.g. dev mode where both API and app are local. |
+| \`--no-tunnel\` / \`--tunnel off\` | \`off\` | Never tunnel — e.g. both sides are on your machine and you want the cloud browser to stay out of it. |
+| \`--tunnel auto\` | \`auto\` | Explicit form (same as omitting). |
+
+You can also pin a project-wide default in \`~/.qa-use.json\`:
+
+\`\`\`json
+{
+  "tunnel": "on"
+}
 \`\`\`
 
-## Persistent Tunnel Session
+CLI flag beats config; config beats the \`auto\` default.
 
-For running multiple tests or interactive development, create a persistent tunnel session:
+### With Visible Browser
 
-### Terminal 1: Start Tunnel
+For debugging, add \`--no-headless\`:
 
 \`\`\`bash
-qa-use browser create --tunnel --no-headless
+qa-use browser create --no-headless http://localhost:3000
+qa-use test run my-test --no-headless
 \`\`\`
 
-Output:
-\`\`\`
-Session created: abc123
-WebSocket URL: wss://tunnel.desplega.ai/abc123
-Tunnel active. Press Ctrl+C to stop.
-\`\`\`
+## Holding a Tunnel Outside a Browser Session
 
-### Terminal 2: Run Tests
+If you just need a public URL (for webhook testing, sharing a dev build with a remote backend, etc.) without spinning up a browser session, use \`qa-use tunnel\`:
 
 \`\`\`bash
-# Run test against the tunneled browser
-qa-use test run my-test --ws-url wss://tunnel.desplega.ai/abc123
+# Acquire and hold a public tunnel to localhost:3000 until Ctrl+C
+qa-use tunnel start http://localhost:3000 --hold
 
-# Or run multiple tests
-qa-use test run login --ws-url wss://tunnel.desplega.ai/abc123
-qa-use test run checkout --ws-url wss://tunnel.desplega.ai/abc123
+# From another shell, inspect the registry
+qa-use tunnel ls
+qa-use tunnel status http://localhost:3000
 \`\`\`
 
-### Benefits
-
-- **Reuse browser session** - no startup time between tests
-- **Watch execution** - see what's happening in real-time
-- **Debug interactively** - use browser commands between test runs
-- **Inspect state** - check page state after failures
+The tunnel registry refcounts — if a \`browser create\` session and \`tunnel start --hold\` point at the same target, they share one tunnel and the tunnel stays up as long as either holder exists.
 
-## Browser Session Commands with Tunnel
+## Browser Session Commands with Localhost
 
-You can also use browser commands directly for exploration:
+Detached \`browser create\` returns immediately — the browser + tunnel run in a background child. Your terminal is free for the next command:
 
 \`\`\`bash
-# Create tunneled session
-qa-use browser create --tunnel --no-headless
-
-# Navigate to your local app
-qa-use browser goto http://localhost:3000
+# Create session — returns in < 3s, background child holds the browser
+qa-use browser create --no-headless http://localhost:3000
 
 # Explore
 qa-use browser snapshot
 qa-use browser click e3
 qa-use browser screenshot
 
+# List all active sessions (across processes)
+qa-use browser status --list
+
 # Close when done
 qa-use browser close
 \`\`\`
@@ -1927,13 +1972,24 @@ steps:
 Override at runtime:
 
 \`\`\`bash
-# Local development
-qa-use test run my-test --tunnel --var base_url=http://localhost:3000
+# Local development — auto-tunnels
+qa-use test run my-test --var base_url=http://localhost:3000
 
-# Staging
+# Staging — no tunnel
 qa-use test run my-test --var base_url=https://staging.example.com
 \`\`\`
 
+## Cleaning Up Stale State
+
+Detached sessions persist PID + registry files in \`~/.qa-use/\`. If a child crashes or is killed with \`SIGKILL\`, stale entries can linger. Reap them with:
+
+\`\`\`bash
+qa-use doctor             # Reap stale sessions + tunnels (dead PIDs)
+qa-use doctor --dry-run   # Preview what would be cleaned
+\`\`\`
+
+A bounded startup sweep also runs silently on every CLI invocation, so most stale state is cleaned opportunistically — \`doctor\` is the explicit escape hatch when you want to see and audit the reaping.
+
 ## Common Issues
 
 ### "Connection refused" / "Network error"
@@ -1949,10 +2005,7 @@ curl http://localhost:3000
 
 The tunnel process was interrupted.
 
-**Fix:** Restart the tunnel:
-\`\`\`bash
-qa-use browser create --tunnel
-\`\`\`
+**Fix:** Re-run the command — \`browser create\` will acquire a fresh tunnel. If stale registry entries remain, run \`qa-use doctor\`.
 
 ### "localhost" resolved differently
 
@@ -1975,17 +2028,21 @@ qa-use browser goto http://localhost:3000
 # Test HTTPS only in staging/prod environments
 \`\`\`
 
+### Tunnel errors have triage hints
+
+Structured tunnel errors (\`TunnelNetworkError\`, \`TunnelAuthError\`, \`TunnelQuotaError\`, \`TunnelUnknownError\`) print a \`Next steps:\` block with the \`--no-tunnel\` opt-out and other recovery hints. No silent retries — failures surface immediately.
+
 ## Best Practices
 
-1. **Use \`--tunnel\` for all localhost tests** - Don't forget, or tests will fail with confusing network errors
+1. **Trust auto-mode** — Don't pass \`--tunnel\` unless you're overriding the default.
 
-2. **Keep tunnel running during development** - Create once, run many tests
+2. **Use \`--tunnel on\` in pure-local dev** — When both your API and app are on localhost, auto-mode skips the tunnel; add \`--tunnel on\` if the cloud still needs to reach you.
 
-3. **Use \`--no-headless\` for debugging** - Watch what's happening
+3. **Use \`--no-headless\` for debugging** — Watch what's happening.
 
-4. **Save WebSocket URL** - Copy it from tunnel output for reuse in \`--ws-url\`
+4. **\`qa-use tunnel start --hold\` for shared public URLs** — When a tunnel needs to outlive any single command.
 
-5. **Clean up sessions** - Run \`qa-use browser close\` when done to free resources
+5. **\`qa-use doctor\` if state feels stale** — Fast, safe, and \`--dry-run\` previews the plan.
 
 ---
 

package/dist/src/cli/generated/docs-content.js.map

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

package/dist/src/cli/index.js

@@ -10,6 +10,7 @@ import { appContextCommand } from './commands/app-context/index.js';
 import { browserCommand } from './commands/browser/index.js';
 import { dataAssetCommand } from './commands/data-asset/index.js';
 import { docsCommand } from './commands/docs.js';
+import { doctorCommand } from './commands/doctor.js';
 import { infoCommand } from './commands/info.js';
 import { installDepsCommand } from './commands/install-deps.js';
 import { issuesCommand } from './commands/issues/index.js';
@@ -18,8 +19,10 @@ import { personaCommand } from './commands/persona/index.js';
 import { setupCommand } from './commands/setup.js';
 import { suiteCommand } from './commands/suite/index.js';
 import { testCommand } from './commands/test/index.js';
+import { tunnelCommand } from './commands/tunnel/index.js';
 import { updateCommand } from './commands/update.js';
 import { usageCommand } from './commands/usage.js';
+import { kickoffStartupSweep } from './lib/startup-sweep.js';
 import { checkForUpdateAsync, getUpdateHintForHelp, shouldSkipCheck, showUpdateHintIfAvailable, } from './lib/update-check.js';
 // Get version from package.json
 const require = createRequire(import.meta.url);
@@ -37,6 +40,7 @@ program.addCommand(testCommand);
 program.addCommand(suiteCommand);
 program.addCommand(mcpCommand);
 program.addCommand(browserCommand);
+program.addCommand(tunnelCommand());
 program.addCommand(installDepsCommand);
 program.addCommand(updateCommand);
 program.addCommand(apiCommand);
@@ -46,6 +50,10 @@ program.addCommand(personaCommand);
 program.addCommand(dataAssetCommand);
 program.addCommand(issuesCommand);
 program.addCommand(usageCommand);
+program.addCommand(doctorCommand);
+// Bounded startup sweep — reaps orphaned PID files silently. Budget-capped
+// at 250 ms, skips itself when `doctor` or `__browser-detach` is running.
+kickoffStartupSweep();
 // Auto-update hint (reads from cache, fires async fetch — never blocks)
 if (!shouldSkipCheck(process.argv)) {
     showUpdateHintIfAvailable(version);

package/dist/src/cli/index.js.map

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

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

@@ -5,10 +5,19 @@
  * and browser WebSocket connection for remote test execution.
  */
 import { BrowserManager } from '../../../lib/browser/index.js';
-import { TunnelManager } from '../../../lib/tunnel/index.js';
+import type { TunnelManager } from '../../../lib/tunnel/index.js';
+import { type TunnelHandle } from '../../../lib/tunnel/registry.js';
+import { type TunnelMode } from './tunnel-resolve.js';
 export interface BrowserTunnelSession {
     browser: BrowserManager;
+    /**
+     * Back-compat shim: historical callers check `session.tunnel` for
+     * truthiness to decide "is a tunnel active?". Sourced from the
+     * registry's in-process cache; callers never construct one directly.
+     */
     tunnel: TunnelManager | null;
+    /** Registry handle owning this tunnel (null when no tunnel). */
+    tunnelHandle: TunnelHandle | null;
     wsUrl: string;
     publicWsUrl: string | null;
     isLocalhost: boolean;
@@ -17,20 +26,27 @@ export interface BrowserTunnelOptions {
     headless?: boolean;
     apiKey?: string;
     sessionIndex?: number;
+    /**
+     * Effective tri-state tunnel mode after CLI/config resolution.
+     * Defaults to `'auto'` so callers that don't care about the flag
+     * still pick up the Phase-2 auto-inference.
+     */
+    tunnelMode?: TunnelMode;
+    /**
+     * API URL used to detect dev mode. When the API URL is itself
+     * localhost, `'auto'` skips the tunnel.
+     */
+    apiUrl?: string;
+    /**
+     * Suppress the stderr auto-tunnel banner (e.g. for `--json` callers).
+     */
+    quiet?: boolean;
 }
-/**
- * Check if a URL points to localhost
- */
-export declare function isLocalhostUrl(url: string): boolean;
 /**
  * Check if Playwright browsers are installed and exit with helpful message if not.
  * This is a guard function to call before expensive tunnel/browser operations.
  */
 export declare function ensureBrowsersInstalled(): void;
-/**
- * Get the port from a URL
- */
-export declare function getPortFromUrl(url: string): number;
 /**
  * Start browser and tunnel (if needed for localhost testing)
  *

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

@@ -1 +1 @@
-{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../../../src/cli/lib/browser.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAG7D,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,cAAc,CAAC;IACxB,MAAM,EAAE,aAAa,GAAG,IAAI,CAAC;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAYnD;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAY9C;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAWlD;AAED;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,oBAAoB,CAAC,CA2C/B;AAED;;GAEG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKxF;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,CAEvE;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,OAAO,CAAC,CAaxF"}
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../../../src/cli/lib/browser.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAE/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,EAAE,KAAK,YAAY,EAAkB,MAAM,iCAAiC,CAAC;AAIpF,OAAO,EAAqB,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAiBzE,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,cAAc,CAAC;IACxB;;;;OAIG;IACH,MAAM,EAAE,aAAa,GAAG,IAAI,CAAC;IAC7B,gEAAgE;IAChE,YAAY,EAAE,YAAY,GAAG,IAAI,CAAC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAY9C;AAED;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,oBAAoB,CAAC,CAmF/B;AAED;;GAEG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAOxF;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,CAEvE;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,OAAO,CAAC,CAaxF"}