Merge remote-tracking branch 'origin/main' into garrytan/gbrain-code-smell-audit

# Conflicts:
#	CHANGELOG.md
#	browse/test/dual-listener.test.ts
#	browse/test/fixtures/security-bench-haiku-responses.json
#	browse/test/sidebar-tabs.test.ts
#	browse/test/sidebar-ux.test.ts
#	browse/test/terminal-agent.test.ts
#	claude/SKILL.md.tmpl
#	scripts/gen-skill-docs.ts
#	scripts/proactive-suggestions.json
#	spec/SKILL.md
#	test/gen-skill-docs.test.ts
#	test/host-config.test.ts

browse/SKILL.md

@@ -80,13 +80,15 @@ if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then
 echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL"
 _QUESTION_TUNING=$(~/.claude/skills/gstack/bin/gstack-config get question_tuning 2>/dev/null || echo "false")
 echo "QUESTION_TUNING: $_QUESTION_TUNING"
+_UPDATE_CHECK=$(~/.claude/skills/gstack/bin/gstack-config get update_check 2>/dev/null || echo "true")
+echo "UPDATE_CHECK: $_UPDATE_CHECK"
 mkdir -p ~/.gstack/analytics
 if [ "$_TEL" != "off" ]; then
 echo '{"skill":"browse","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(_repo=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null | tr -cd 'a-zA-Z0-9._-'); echo "${_repo:-unknown}")'"}'  >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
 fi
 for _PF in $(find ~/.gstack/analytics -maxdepth 1 -name '.pending-*' 2>/dev/null); do
   if [ -f "$_PF" ]; then
-    if [ "$_TEL" != "off" ] && [ -x "~/.claude/skills/gstack/bin/gstack-telemetry-log" ]; then
+    if [ "$_TEL" != "off" ] && [ -x "$HOME/.claude/skills/gstack/bin/gstack-telemetry-log" ]; then
       ~/.claude/skills/gstack/bin/gstack-telemetry-log --event-type skill_run --skill _pending_finalize --outcome unknown --session-id "$_SESSION_ID" 2>/dev/null || true
     fi
     rm -f "$_PF" 2>/dev/null || true
@@ -152,6 +154,8 @@ If `PROACTIVE` is `"false"`, do not auto-invoke or proactively suggest skills. I
 
 If `SKILL_PREFIX` is `"true"`, suggest/invoke `/gstack-*` names. Disk paths stay `~/.claude/skills/gstack/[skill-name]/SKILL.md`.
 
+If `UPDATE_CHECK` is `"false"`, skip the next two lines — the update-check binary emits nothing in that mode, so there is no `UPGRADE_AVAILABLE` / `JUST_UPGRADED` output to act on.
+
 If output shows `UPGRADE_AVAILABLE <old> <new>`: read `~/.claude/skills/gstack/gstack-upgrade/SKILL.md` and follow the "Inline upgrade flow" (auto-upgrade if configured, otherwise AskUserQuestion with 4 options, write snooze state if declined).
 
 If output shows `JUST_UPGRADED <from> <to>`: print "Running gstack v{to} (just updated!)". If `SPAWNED_SESSION` is true, skip feature discovery.
@@ -339,8 +343,8 @@ if [ -f "$HOME/.gstack-artifacts-remote.txt" ]; then
 else
   _BRAIN_REMOTE_FILE="$HOME/.gstack-brain-remote.txt"
 fi
-_BRAIN_SYNC_BIN="~/.claude/skills/gstack/bin/gstack-brain-sync"
-_BRAIN_CONFIG_BIN="~/.claude/skills/gstack/bin/gstack-config"
+_BRAIN_SYNC_BIN="$HOME/.claude/skills/gstack/bin/gstack-brain-sync"
+_BRAIN_CONFIG_BIN="$HOME/.claude/skills/gstack/bin/gstack-config"
 
 # /sync-gbrain context-load: teach the agent to use gbrain when it's available.
 # Per-worktree pin: post-spike redesign uses kubectl-style `.gbrain-source` in the
@@ -449,8 +453,8 @@ If A/B and `~/.gstack/.git` is missing, ask whether to run `gstack-artifacts-ini
 At skill END before telemetry:
 
 ```bash
-"~/.claude/skills/gstack/bin/gstack-brain-sync" --discover-new 2>/dev/null || true
-"~/.claude/skills/gstack/bin/gstack-brain-sync" --once 2>/dev/null || true
+"$HOME/.claude/skills/gstack/bin/gstack-brain-sync" --discover-new 2>/dev/null || true
+"$HOME/.claude/skills/gstack/bin/gstack-brain-sync" --once 2>/dev/null || true
 ```
 
 
@@ -523,11 +527,15 @@ fi
 if [ "$_TEL" != "off" ] && [ -x ~/.claude/skills/gstack/bin/gstack-telemetry-log ]; then
   ~/.claude/skills/gstack/bin/gstack-telemetry-log \
     --skill "SKILL_NAME" --duration "$_TEL_DUR" --outcome "OUTCOME" \
-    --used-browse "USED_BROWSE" --session-id "$_SESSION_ID" 2>/dev/null &
+    --used-browse "USED_BROWSE" --session-id "$_SESSION_ID" \
+    --error-message "ERROR_MESSAGE" --failed-step "FAILED_STEP" 2>/dev/null &
 fi
 ```
 
 Replace `SKILL_NAME`, `OUTCOME`, and `USED_BROWSE` before running.
+Replace `ERROR_MESSAGE` with a short description of the error (if outcome is error,
+otherwise use empty string ""), and `FAILED_STEP` with the step name or number where
+the failure occurred (if outcome is error, otherwise use empty string "").
 
 ## Plan Status Footer
 

browse/scripts/build-node-server.sh

@@ -32,7 +32,7 @@ bun build "$SRC_DIR/server.ts" \
 # Replace import.meta.dir with a resolvable reference
 perl -pi -e 's/import\.meta\.dir/__browseNodeSrcDir/g' "$DIST_DIR/server-node.mjs"
 # Stub out bun:sqlite (macOS-only cookie import, not needed on Windows)
-perl -pi -e 's|import { Database } from "bun:sqlite";|const Database = null; // bun:sqlite stubbed on Node|g' "$DIST_DIR/server-node.mjs"
+perl -pi -e 's|import \{ Database \} from "bun:sqlite";|const Database = null; // bun:sqlite stubbed on Node|g' "$DIST_DIR/server-node.mjs"
 
 # Step 3: Create the final file with polyfill header injected after the first line
 {

browse/src/browser-manager.ts

@@ -91,7 +91,11 @@ export function shouldEnableChromiumSandbox(): boolean {
  * restarts on backoff.
  */
 export async function resolveDisconnectCause(browser: Browser | null): Promise<'clean' | 'crash'> {
-  const proc = browser?.process();
+  // `.process()` only exists on browsers we launched ourselves. A browser
+  // obtained via connectOverCDP() (or a stub in tests) has no such method —
+  // calling it blind throws inside the disconnect handler, which killed the
+  // whole daemon with "browser?.process is not a function".
+  const proc = typeof browser?.process === 'function' ? browser.process() : null;
   if (proc && proc.exitCode === null && proc.signalCode === null) {
     await new Promise<void>((resolve) => {
       const timer = setTimeout(resolve, 1000);
@@ -798,19 +802,31 @@ export class BrowserManager {
     const page = this.pages.get(tabId);
     if (!page) throw new Error(`Tab ${tabId} not found`);
 
+    // Capture BEFORE close(): the page 'close' event handler wired in
+    // wirePageEvents() can fire while page.close() is awaited. It removes
+    // the tab from the maps and reassigns activeTabId (to 0 when no tabs
+    // remain), so a post-close `tabId === this.activeTabId` check is
+    // order-dependent — whether the event dispatches before or after
+    // close() resolves varies across Playwright/Chromium versions and
+    // machines, and losing the race means the last-tab auto-create below
+    // never runs, leaving the manager with zero tabs.
+    const wasActive = tabId === this.activeTabId;
+
     await page.close();
     this.pages.delete(tabId);
     this.tabSessions.delete(tabId);
     this.tabOwnership.delete(tabId);
 
     // Switch to another tab if we closed the active one
-    if (tabId === this.activeTabId) {
+    if (wasActive) {
       const remaining = [...this.pages.keys()];
-      if (remaining.length > 0) {
-        this.activeTabId = remaining[remaining.length - 1];
-      } else {
+      if (remaining.length === 0) {
         // No tabs left — create a new blank one
         await this.newTab();
+      } else if (!this.pages.has(this.activeTabId)) {
+        // The 'close' handler may have already switched to a valid tab;
+        // only reassign when activeTabId no longer points at a live tab.
+        this.activeTabId = remaining[remaining.length - 1];
       }
     }
   }

browse/src/bun-polyfill.cjs

@@ -75,6 +75,10 @@ globalThis.Bun = {
       timeout: options.timeout,
       env: options.env,
       cwd: options.cwd,
+      // Node defaults windowsHide to false; Bun.spawn hides the console
+      // window. Without this the shim silently inverts the behavior on the
+      // one platform it exists to serve. See the spawn() note below.
+      windowsHide: options.windowsHide !== false,
     });
 
     return {
@@ -91,13 +95,110 @@ globalThis.Bun = {
       stdio,
       env: options.env,
       cwd: options.cwd,
+      // stdio:'ignore' silences a child's output but does not suppress its
+      // console window on Windows. The terminal-agent respawn (server.ts
+      // watchdog, 60s ticker) therefore popped a visible bun.exe window on
+      // every respawn until this was forwarded.
+      windowsHide: options.windowsHide !== false,
+    });
+
+    // Drain stdout/stderr eagerly into in-memory buffers. Bun's spawn buffers
+    // these for the consumer; Node's Readables are pull-based, so if the caller
+    // awaits `proc.exited` before reading, anything past the OS pipe buffer
+    // (~16-64 KB) back-pressures the child until it blocks in write() and
+    // `exit` never fires. Eager draining keeps the pipes flowing regardless
+    // of read order; replay below is via fresh Web ReadableStreams.
+    //
+    // Cap the buffer so a runaway child can't OOM the server. 16 MB is
+    // generous: DPAPI outputs are tiny, tasklist is <1 KB, and the
+    // browser-skill consumer has its own 1 MB readCapped. Once the cap is
+    // reached we keep draining the pipe (so the child never blocks) but
+    // discard further bytes. Override via GSTACK_SPAWN_MAX_BUFFER (bytes).
+    const MAX_BUFFER = Math.max(
+      0,
+      parseInt(process.env.GSTACK_SPAWN_MAX_BUFFER || '', 10) || 16 * 1024 * 1024,
+    );
+    const drain = (stream) => {
+      if (!stream) return { done: Promise.resolve(), chunks: [], truncated: false };
+      const state = { chunks: [], bytes: 0, truncated: false };
+      const done = new Promise((resolve) => {
+        stream.on('data', (chunk) => {
+          if (state.bytes >= MAX_BUFFER) { state.truncated = true; return; }
+          if (state.bytes + chunk.length <= MAX_BUFFER) {
+            state.chunks.push(chunk);
+            state.bytes += chunk.length;
+          } else {
+            const remaining = MAX_BUFFER - state.bytes;
+            state.chunks.push(chunk.subarray(0, remaining));
+            state.bytes = MAX_BUFFER;
+            state.truncated = true;
+          }
+        });
+        // Any terminal event resolves: 'end' on normal close, 'error' on a
+        // stream-level error, 'close' as the belt-and-suspenders for spawn
+        // failures where Node fires 'close' but neither 'end' nor 'error'.
+        stream.once('end', resolve);
+        stream.once('error', resolve);
+        stream.once('close', resolve);
+      });
+      return { done, chunks: state.chunks };
+    };
+    const stdoutDrain = drain(proc.stdout);
+    const stderrDrain = drain(proc.stderr);
+
+    // Bun's spawn exposes `proc.exited` as a Promise resolving to the exit
+    // code; several call sites — DPAPI decryption, isBrowserRunning,
+    // browser-skill-commands — `await proc.exited` directly or via
+    // Promise.race with a timeout. Without this, those awaits resolve to
+    // `undefined` immediately and the operation looks like a silent failure.
+    // Resolve only after both pipes have finished draining so consumers that
+    // read stdout AFTER awaiting exit see the full output, not a partial buffer.
+    const exited = new Promise((resolveExited) => {
+      let exitStatus;
+      proc.once('exit', (code, signal) => {
+        // Match Bun: exit code on normal exit; 128 + signal number on signal;
+        // 0 if neither was reported.
+        if (code !== null) exitStatus = code;
+        else if (signal) exitStatus = 128 + (require('os').constants.signals[signal] || 0);
+        else exitStatus = 0;
+      });
+      proc.once('error', () => {
+        if (exitStatus === undefined) exitStatus = 1;
+      });
+      // Wait for either 'exit' (normal child lifecycle) or 'error' (spawn
+      // failure — Node fires error without exit when the binary is missing).
+      // Either path resolves the lifecycle promise; without listening to both
+      // a spawn error hangs `await proc.exited` until the consumer's own
+      // timeout fires.
+      const lifecycle = new Promise((r) => {
+        proc.once('exit', r);
+        proc.once('error', r);
+      });
+      Promise.all([lifecycle, stdoutDrain.done, stderrDrain.done])
+        .then(() => resolveExited(exitStatus !== undefined ? exitStatus : 0));
+    });
+
+    // Replay buffered output as a fresh Web ReadableStream. `start()` awaits
+    // the drain before enqueueing so `new Response(proc.stdout).text()` yields
+    // the complete output regardless of whether the consumer reads before or
+    // after awaiting `proc.exited`. Stream is single-shot (locked after one
+    // read), matching Bun's behavior.
+    const replay = (d) => new ReadableStream({
+      async start(controller) {
+        await d.done;
+        for (const chunk of d.chunks) {
+          controller.enqueue(chunk instanceof Uint8Array ? chunk : new Uint8Array(chunk));
+        }
+        controller.close();
+      },
     });
 
     return {
       pid: proc.pid,
-      stdout: proc.stdout,
-      stderr: proc.stderr,
+      stdout: replay(stdoutDrain),
+      stderr: replay(stderrDrain),
       stdin: proc.stdin,
+      exited,
       unref() { proc.unref(); },
       kill(signal) { proc.kill(signal); },
     };

browse/src/cli.ts

@@ -21,7 +21,32 @@ import { spawnTerminalAgent } from './terminal-agent-control';
 
 const config = resolveConfig();
 const IS_WINDOWS = process.platform === 'win32';
-const MAX_START_WAIT = IS_WINDOWS ? 15000 : (process.env.CI ? 30000 : 8000); // Node+Chromium takes longer on Windows
+
+/**
+ * Startup health-probe budget (ms) for a freshly spawned server. The daemon is
+ * detached + unref'd, so it keeps booting regardless of how long the CLI is
+ * willing to poll — this constant only bounds how long `startServer` waits
+ * before reporting failure.
+ *
+ * Overridable via `BROWSE_START_TIMEOUT` (ms) for hosts where even the platform
+ * ceiling isn't enough — e.g. Windows under heavy load (#1846), where the 15s
+ * budget can still elapse before a busy box finishes booting Node+Chromium.
+ * Mirrors the `BROWSE_*` tunable convention used throughout server.ts
+ * (BROWSE_PORT, BROWSE_IDLE_TIMEOUT, ...). A non-positive or unparseable value
+ * falls back to the platform default. Pure + exported for tests.
+ */
+export function resolveStartTimeout(env: NodeJS.ProcessEnv = process.env): number {
+  // Cold Chromium launch measured ~5.7s at load avg 10 on a dev machine running
+  // many servers; at load 12+ it exceeds the old 8s budget, so the CLI gave up
+  // while the (detached) daemon was still booting → "Server failed to start
+  // within 8s". 15s matches the Windows budget and gives real headroom; the poll
+  // loop returns the instant the daemon is healthy, so this only costs time in a
+  // genuine-failure case.
+  const platformDefault = IS_WINDOWS ? 15000 : (env.CI ? 30000 : 15000); // Node+Chromium takes longer on Windows
+  const override = parseInt(env.BROWSE_START_TIMEOUT || '', 10);
+  return Number.isFinite(override) && override > 0 ? override : platformDefault;
+}
+const MAX_START_WAIT = resolveStartTimeout();
 
 export function resolveServerScript(
   env: Record<string, string | undefined> = process.env,
@@ -357,6 +382,17 @@ async function startServer(extraEnv?: Record<string, string>): Promise<ServerSta
     await Bun.sleep(100);
   }
 
+  // One last check before declaring failure. The daemon is detached + unref'd,
+  // so on a loaded machine it can become healthy in the gap between the poll
+  // loop's final tick and now — the probe timed out, the launch did not
+  // (#1846). Re-checking here turns that false negative into a success, and
+  // mirrors the post-loop recovery already done in ensureServer(). A genuinely
+  // failed server is still unhealthy, so this falls through to the error report.
+  const lateState = readState();
+  if (lateState && await isServerHealthy(lateState.port)) {
+    return lateState;
+  }
+
   // Server didn't start in time — check the on-disk startup error log.
   // Both platforms now spawn with stdio: 'ignore', so the server writes
   // errors to disk for the CLI to read (see server.ts start().catch).
@@ -372,12 +408,31 @@ async function startServer(extraEnv?: Record<string, string>): Promise<ServerSta
   throw new Error(`Server failed to start within ${MAX_START_WAIT / 1000}s`);
 }
 
+function errorCode(err: unknown): string {
+  if (err && typeof err === 'object' && 'code' in err) {
+    const code = (err as { code?: unknown }).code;
+    if (typeof code === 'string' && code.length > 0) return code;
+  }
+  return 'UNKNOWN';
+}
+
+function errorMessage(err: unknown): string {
+  if (err && typeof err === 'object' && 'message' in err) {
+    const message = (err as { message?: unknown }).message;
+    if (typeof message === 'string' && message.length > 0) return message;
+  }
+  return String(err);
+}
+
+function logServerLockError(action: string, lockPath: string, err: unknown): void {
+  console.error(`[browse] acquireServerLock: unexpected ${errorCode(err)} while ${action} ${lockPath}: ${errorMessage(err)}`);
+}
+
 /**
  * Acquire an exclusive lockfile to prevent concurrent ensureServer() races (TOCTOU).
  * Returns a cleanup function that releases the lock.
  */
-function acquireServerLock(): (() => void) | null {
-  const lockPath = `${config.stateFile}.lock`;
+export function acquireServerLock(lockPath: string = `${config.stateFile}.lock`): (() => void) | null {
   try {
     // 'wx' — create exclusively, fails if file already exists (atomic check-and-create)
     // Using string flag instead of numeric constants for Bun Windows compatibility
@@ -385,19 +440,36 @@ function acquireServerLock(): (() => void) | null {
     fs.writeSync(fd, `${process.pid}\n`);
     fs.closeSync(fd);
     return () => { safeUnlink(lockPath); };
-  } catch {
-    // Lock already held — check if the holder is still alive
-    try {
-      const holderPid = parseInt(fs.readFileSync(lockPath, 'utf8').trim(), 10);
-      if (holderPid && isProcessAlive(holderPid)) {
-        return null; // Another live process holds the lock
-      }
-      // Stale lock — remove and retry
-      fs.unlinkSync(lockPath);
-      return acquireServerLock();
-    } catch {
+  } catch (err) {
+    if (errorCode(err) !== 'EEXIST') {
+      logServerLockError('opening', lockPath, err);
       return null;
     }
+
+    // Lock already held — check if the holder is still alive
+    let holderPid: number;
+    try {
+      holderPid = parseInt(fs.readFileSync(lockPath, 'utf8').trim(), 10);
+    } catch (readErr) {
+      if (errorCode(readErr) === 'ENOENT') {
+        return acquireServerLock(lockPath);
+      }
+      logServerLockError('reading holder PID from', lockPath, readErr);
+      return null;
+    }
+
+    if (holderPid && isProcessAlive(holderPid)) {
+      return null; // Another live process holds the lock
+    }
+
+    // Stale lock — remove and retry
+    try {
+      fs.unlinkSync(lockPath);
+    } catch (unlinkErr) {
+      logServerLockError('removing stale', lockPath, unlinkErr);
+      return null;
+    }
+    return acquireServerLock(lockPath);
   }
 }
 
@@ -584,7 +656,17 @@ async function sendCommand(state: ServerState, command: string, args: string[],
       process.exit(1);
     }
     // Connection error — server may have crashed, OR may just be busy.
-    if (err.code === 'ECONNREFUSED' || err.code === 'ECONNRESET' || err.message?.includes('fetch failed')) {
+    // The compiled CLI runs on Bun, whose fetch reports a refused/dropped
+    // socket as err.code 'ConnectionRefused' / 'ConnectionClosed' (message
+    // "Unable to connect. Is the computer able to access the url?"), NOT Node's
+    // ECONNREFUSED/ECONNRESET. Match both, or daemon crashes leak the raw Bun
+    // error and exit 1 instead of triggering the busy-check/restart below.
+    const isConnError =
+      err.code === 'ECONNREFUSED' || err.code === 'ECONNRESET' ||
+      err.code === 'ConnectionRefused' || err.code === 'ConnectionClosed' ||
+      err.message?.includes('fetch failed') ||
+      err.message?.includes('Unable to connect');
+    if (isConnError) {
       const oldState = readState();
       // #1781 busy-vs-dead: a single-threaded daemon under beacon/extension load
       // can briefly stop answering HTTP while still alive. Before declaring a
@@ -1125,6 +1207,7 @@ Refs:           After 'snapshot', use @e1, @e2... as selectors:
         const newPid = spawnTerminalAgent({
           stateFile: config.stateFile,
           serverPort: newState.port,
+          ownerPid: newState.pid,
           cwd: config.projectDir,
         });
         if (newPid) {
@@ -1217,6 +1300,7 @@ Refs:           After 'snapshot', use @e1, @e2... as selectors:
           spawnTerminalAgent({
             stateFile: config.stateFile,
             serverPort: respawned.port,
+            ownerPid: respawned.pid,
             cwd: config.projectDir,
           });
         } catch (err: any) {

browse/src/config.ts

@@ -34,7 +34,12 @@ export function getGitRoot(): string | null {
     const proc = Bun.spawnSync(['git', 'rev-parse', '--show-toplevel'], {
       stdout: 'pipe',
       stderr: 'pipe',
-      timeout: 2_000, // Don't hang if .git is broken
+      // Raised from 2s: under heavy machine load `git rev-parse` routinely
+      // takes >2s (measured 6.3s spikes). Timing out here returns null →
+      // resolveConfig falls back to process.cwd() → state files scatter across
+      // cwds (split-brain daemons; `goto` and `url` hit different servers). 8s
+      // still bounds a genuinely broken .git from hanging the CLI forever.
+      timeout: 8_000,
     });
     if (proc.exitCode !== 0) return null;
     return proc.stdout.toString().trim() || null;
@@ -78,6 +83,20 @@ export function resolveConfig(
   };
 }
 
+function isIgnoredByGit(projectDir: string, relPath: string): boolean {
+  try {
+    const proc = Bun.spawnSync(['git', 'check-ignore', '-q', '--', relPath], {
+      cwd: projectDir, stdout: 'pipe', stderr: 'pipe',
+      timeout: 2_000,
+    });
+    return proc.exitCode === 0;
+  } catch {
+    // git not found, timed out, or not a repo (exit 128). Fall through to
+    // the text-check path — appending is the safe default when unsure.
+    return false;
+  }
+}
+
 /**
  * Create the .gstack/ state directory if it doesn't exist.
  * Throws with a clear message on permission errors.
@@ -96,6 +115,9 @@ export function ensureStateDir(config: BrowseConfig): void {
   }
 
   // Ensure .gstack/ is in the project's .gitignore
+  // First, check if git already ignores .gstack/ (via global excludes, .git/info/exclude, or parent .gitignore)
+  if (isIgnoredByGit(config.projectDir, '.gstack/')) return;
+
   const gitignorePath = path.join(config.projectDir, '.gitignore');
   try {
     const content = fs.readFileSync(gitignorePath, 'utf-8');

browse/src/error-handling.ts

@@ -7,8 +7,6 @@
 
 import * as fs from 'fs';
 
-const IS_WINDOWS = process.platform === 'win32';
-
 // ─── Filesystem ────────────────────────────────────────────────
 
 /** Remove a file, ignoring ENOENT (already gone). Rethrows other errors. */
@@ -36,23 +34,39 @@ export function safeKill(pid: number, signal: NodeJS.Signals | number): void {
   }
 }
 
-/** Check if a PID is alive. Pure boolean probe — returns false for ALL errors. */
+/**
+ * Check if a PID is alive. Pure boolean probe — never throws.
+ *
+ * Signal 0 on every platform. Node and Bun both map `process.kill(pid, 0)` to
+ * an OpenProcess existence check on Windows, so the POSIX idiom is portable
+ * here — no shell-out needed.
+ *
+ * Windows used to shell out to `tasklist /FI "PID eq <pid>"` and string-match
+ * the CSV. That was wrong in two ways, both of which bit in production:
+ *
+ *   1. FALSE NEGATIVES UNDER LOAD. `tasklist` takes ~700-1700ms on an idle
+ *      Windows box and far longer under memory pressure. A Bun.spawnSync that
+ *      hits its `timeout` still RETURNS, carrying partial stdout — so the
+ *      `.includes()` match came back false and a LIVE process was reported
+ *      dead. Callers (killAgentByRecord, the terminal-agent watchdog) then
+ *      skipped the kill and respawned around the survivor, leaking one
+ *      terminal-agent per watchdog tick. The leak was self-reinforcing: every
+ *      orphan added memory pressure, which made the next tasklist slower,
+ *      which produced the next false negative.
+ *   2. A VISIBLE CONSOLE WINDOW per probe (no windowsHide), so a background
+ *      watchdog strobed a terminal into the foreground every 60 seconds.
+ *
+ * Signal 0 is ~74,000x faster (0.004ms vs 270ms, measured), spawns nothing,
+ * and cannot time out.
+ *
+ * EPERM means the process EXISTS but we lack rights to signal it. That is
+ * alive; returning false there would reintroduce failure mode 1.
+ */
 export function isProcessAlive(pid: number): boolean {
-  if (IS_WINDOWS) {
-    try {
-      const result = Bun.spawnSync(
-        ['tasklist', '/FI', `PID eq ${pid}`, '/NH', '/FO', 'CSV'],
-        { stdout: 'pipe', stderr: 'pipe', timeout: 3000 }
-      );
-      return result.stdout.toString().includes(`"${pid}"`);
-    } catch {
-      return false;
-    }
-  }
   try {
     process.kill(pid, 0);
     return true;
-  } catch {
-    return false;
+  } catch (err: any) {
+    return err?.code === 'EPERM';
   }
 }

browse/src/file-permissions.ts

@@ -42,6 +42,52 @@ import * as os from 'os';
 
 let warnedOnce = false;
 
+let cachedSid: string | null | undefined;
+
+/**
+ * Resolve the current user's SID, cached for the process lifetime.
+ *
+ * Returns null if `whoami` is unavailable or its output cannot be parsed,
+ * in which case callers fall back to a domain-qualified account name.
+ */
+function currentUserSid(): string | null {
+  if (cachedSid !== undefined) return cachedSid;
+  try {
+    // Pin to the System32 binary. A bare `whoami` resolves to the MSYS/Git
+    // Bash build under a bash-flavoured PATH, which rejects `/user` — the
+    // lookup would then silently fail on one of the most common Windows
+    // setups for this tool.
+    const systemRoot = process.env.SystemRoot || process.env.windir || 'C:\\Windows';
+    const out = execFileSync(`${systemRoot}\\System32\\whoami.exe`, ['/user', '/fo', 'csv', '/nh'], {
+      encoding: 'utf8',
+    });
+    const match = out.match(/S-1-[\d-]+/);
+    cachedSid = match ? match[0] : null;
+  } catch {
+    cachedSid = null;
+  }
+  return cachedSid;
+}
+
+/**
+ * The principal to hand icacls for "the current user".
+ *
+ * An unqualified username is ambiguous: on a machine whose hostname equals
+ * the username, it fails to resolve to the user account and icacls silently
+ * writes an ACE for the machine SID instead. Combined with `/inheritance:r`
+ * that leaves a directory whose only ACE matches nobody — locking out the
+ * process that just created it.
+ *
+ * `*<SID>` is icacls' literal-SID form and is immune to that ambiguity.
+ * The domain-qualified name is the fallback.
+ */
+function currentUserPrincipal(): string {
+  const sid = currentUserSid();
+  if (sid) return `*${sid}`;
+  const domain = process.env.USERDOMAIN || os.hostname();
+  return `${domain}\\${os.userInfo().username}`;
+}
+
 function warnIcaclsFailure(fsPath: string, err: unknown): void {
   if (warnedOnce) return;
   warnedOnce = true;
@@ -67,7 +113,7 @@ function warnIcaclsFailure(fsPath: string, err: unknown): void {
 export function restrictFilePermissions(filePath: string): void {
   if (process.platform === 'win32') {
     try {
-      const user = os.userInfo().username;
+      const user = currentUserPrincipal();
       execFileSync(
         'icacls',
         [filePath, '/inheritance:r', '/grant:r', `${user}:(F)`],
@@ -97,7 +143,7 @@ export function restrictFilePermissions(filePath: string): void {
 export function restrictDirectoryPermissions(dirPath: string): void {
   if (process.platform === 'win32') {
     try {
-      const user = os.userInfo().username;
+      const user = currentUserPrincipal();
       execFileSync(
         'icacls',
         [dirPath, '/inheritance:r', '/grant:r', `${user}:(OI)(CI)(F)`],

browse/src/meta-commands.ts

@@ -421,15 +421,25 @@ export async function handleMetaCommand(
     }
 
     case 'stop': {
-      await shutdown();
+      // Defer shutdown so the response flushes before process.exit() (same
+      // reason as 'restart' below). Otherwise the CLI sees a dropped socket;
+      // and now that connection-loss triggers the crash-retry path, that would
+      // resurrect a fresh daemon only to stop it again. Send the 200, then exit.
+      setTimeout(() => { void shutdown(); }, 100);
       return 'Server stopped';
     }
 
     case 'restart': {
-      // Signal that we want a restart — the CLI will detect exit and restart
+      // Signal that we want a restart — the CLI will detect exit and restart.
       console.log('[browse] Restart requested. Exiting for CLI to restart.');
-      await shutdown();
-      return 'Restarting...';
+      // Defer shutdown one tick so this HTTP response actually flushes before
+      // process.exit(). shutdown() exits inline (server.ts), so the old
+      // `await shutdown(); return 'Restarting...'` never sent a response — the
+      // CLI saw a dropped socket and `browse restart` errored out. The daemon
+      // now exits ~100ms after the CLI gets its 200; the next browse command
+      // lazily cold-starts a fresh one.
+      setTimeout(() => { void shutdown(); }, 100);
+      return 'Restarting... (daemon exiting; next browse command starts a fresh one)';
     }
 
     // ─── Visual ────────────────────────────────────────

browse/src/server.ts

@@ -1590,8 +1590,18 @@ export function buildFetchHandler(cfg: ServerConfig): ServerHandle {
     process.env.GSTACK_AGENT_WATCHDOG_TICK_MS || '60000',
     10,
   );
-  const RESPAWN_GUARD_WINDOW_MS = 60_000;
   const RESPAWN_GUARD_MAX = 3;
+  // The guard window MUST span enough ticks for RESPAWN_GUARD_MAX respawns to
+  // land inside it. This was a fixed 60_000 against a 60_000 tick, so at most
+  // ONE respawn could ever be in the window and `respawnHistory.length >= 3`
+  // was unreachable — the guard could not fire at the default tick rate, and a
+  // steady one-per-tick leak ran unbounded instead of stopping after 3. Scale
+  // with the tick so the intent ("3 crashes in quick succession → stop") holds
+  // at any tick value: 3 respawns within 5 ticks trips it.
+  const RESPAWN_GUARD_WINDOW_MS = Math.max(
+    60_000,
+    AGENT_WATCHDOG_TICK_MS * (RESPAWN_GUARD_MAX + 2),
+  );
   let agentRespawnGuardTripped = false;
 
   if (ownsTerminalAgent) {
@@ -1624,6 +1634,7 @@ export function buildFetchHandler(cfg: ServerConfig): ServerHandle {
         const pid = spawnTerminalAgent({
           stateFile: cfg.config.stateFile,
           serverPort: cfg.browsePort,
+          ownerPid: process.pid,
           cwd: cfg.config.projectDir,
         });
         if (pid) {

browse/src/terminal-agent-control.ts

@@ -49,12 +49,13 @@ export function resolveTerminalAgentScript(searchHints: { metaDir?: string; exec
  *
  * Used by both the CLI cold-start path (cli.ts) and the v1.44 watchdog in
  * server.ts. Centralizing here removes a copy-paste between them and means
- * future spawn-env additions (e.g. BROWSE_OWNER_PID for the generation
- * counter rollout) land in one place.
+ * spawn-env additions (BROWSE_OWNER_PID being the first) land in one place.
  */
 export function spawnTerminalAgent(opts: {
   stateFile: string;
   serverPort: number;
+  /** PID of the browse server that owns this agent. */
+  ownerPid: number;
   cwd?: string;
   /** Optional extra env vars to add to the agent's process env. */
   extraEnv?: Record<string, string>;
@@ -75,9 +76,14 @@ export function spawnTerminalAgent(opts: {
       ...process.env,
       BROWSE_STATE_FILE: opts.stateFile,
       BROWSE_SERVER_PORT: String(opts.serverPort),
+      BROWSE_OWNER_PID: String(opts.ownerPid),
       ...(opts.extraEnv || {}),
     },
     stdio: ['ignore', 'ignore', 'ignore'],
+    // Explicit for the Node fallback path (dist/bun-polyfill.cjs), where the
+    // host default is the opposite of Bun's. A visible console window on every
+    // watchdog respawn is the symptom when this is missing.
+    windowsHide: true,
   });
   proc.unref?.();
   return proc.pid ?? null;

browse/src/terminal-agent.ts

@@ -32,6 +32,11 @@ import { extractPtyCookie } from './pty-session-cookie';
 const STATE_FILE = process.env.BROWSE_STATE_FILE || path.join(process.env.HOME || '/tmp', '.gstack', 'browse.json');
 const PORT_FILE = path.join(path.dirname(STATE_FILE), 'terminal-port');
 const BROWSE_SERVER_PORT = parseInt(process.env.BROWSE_SERVER_PORT || '0', 10);
+const BROWSE_OWNER_PID = parseInt(process.env.BROWSE_OWNER_PID || '0', 10);
+const OWNER_WATCHDOG_MS = parseInt(
+  process.env.GSTACK_TERMINAL_OWNER_WATCHDOG_MS || '15000',
+  10,
+);
 const EXTENSION_ID = process.env.BROWSE_EXTENSION_ID || ''; // optional: tighten Origin check
 const INTERNAL_TOKEN = crypto.randomBytes(32).toString('base64url'); // shared with parent server via env at spawn
 /**
@@ -597,12 +602,10 @@ function buildServer() {
         // first that matches a known token.
         const protoHeader = req.headers.get('sec-websocket-protocol') || '';
         let token: string | null = null;
-        let acceptedProtocol: string | null = null;
         for (const raw of protoHeader.split(',').map(s => s.trim()).filter(Boolean)) {
           const candidate = raw.startsWith('gstack-pty.') ? raw.slice('gstack-pty.'.length) : raw;
           if (validTokens.has(candidate)) {
             token = candidate;
-            acceptedProtocol = raw;
             break;
           }
         }
@@ -627,13 +630,13 @@ function buildServer() {
         // sessionsById so /internal/restart and (Commit 3) re-attach
         // lookups can find it.
         const sessionId = validTokens.get(token) ?? null;
+        // No explicit Sec-WebSocket-Protocol echo: Bun >= 1.3 auto-echoes the
+        // first offered protocol in the 101 response, so setting the header
+        // here produced a DUPLICATE header — strict clients (Chromium, python
+        // websockets) reject the handshake per RFC 6455 and the sidebar
+        // terminal could never connect. Verified on Bun 1.3.6.
         const upgraded = server.upgrade(req, {
           data: { cookie: token, sessionId },
-          // Echo the protocol back so the browser accepts the upgrade.
-          // Required when the client sends Sec-WebSocket-Protocol — the
-          // server MUST select one of the offered protocols, otherwise
-          // the browser closes the connection immediately.
-          ...(acceptedProtocol ? { headers: { 'Sec-WebSocket-Protocol': acceptedProtocol } } : {}),
         });
         return upgraded ? undefined : new Response('upgrade failed', { status: 500 });
       }
@@ -971,13 +974,33 @@ function main() {
   console.log(`[terminal-agent] listening on 127.0.0.1:${port} pid=${process.pid} gen=${CURRENT_GEN}`);
 
   // Cleanup port file + agent record on exit.
+  let cleaningUp = false;
   const cleanup = () => {
+    if (cleaningUp) return;
+    cleaningUp = true;
     safeUnlink(PORT_FILE);
+    safeUnlink(INTERNAL_TOKEN_FILE);
     clearAgentRecord(dir);
     process.exit(0);
   };
   process.on('SIGTERM', cleanup);
   process.on('SIGINT', cleanup);
+
+  // The terminal agent is intentionally detached so it survives the short-lived
+  // CLI launcher, but its real owner is the persistent browse server. If that
+  // server crashes or is killed before running normal shutdown, the agent would
+  // otherwise be adopted by PID 1 and live forever. Poll the server PID and use
+  // the same cleanup path as an intentional shutdown when it disappears.
+  if (BROWSE_OWNER_PID > 0) {
+    const ownerWatchdog = setInterval(() => {
+      try {
+        process.kill(BROWSE_OWNER_PID, 0);
+      } catch {
+        cleanup();
+      }
+    }, OWNER_WATCHDOG_MS);
+    (ownerWatchdog as any)?.unref?.();
+  }
 }
 
 // Export the internal token so cli.ts can pass the SAME value to the parent

browse/src/url-validation.ts

@@ -269,9 +269,24 @@ export async function validateNavigationUrl(url: string): Promise<string> {
     return pathToFileURL(fsPath).href + parsed.search + parsed.hash;
   }
 
+  // about:blank ONLY — the canonical empty page, and the one the daemon opens its own
+  // first tab on. Blocking it meant `browse newtab about:blank` failed, which is what
+  // `make-pdf setup` runs as its Chromium smoke test: make-pdf reported "Chromium failed
+  // to launch" against a perfectly healthy Chromium, and any browse session whose daemon
+  // restarted could never recreate the blank tab it starts from.
+  //
+  // Deliberately not the whole `about:` scheme. about:blank has no origin, loads nothing
+  // and runs nothing; about:config, about:net-internals and friends are real surfaces.
+  // Exact href match, not a prefix test, so `about:blankfoo` stays blocked.
+  // Compared lower-cased: the URL parser normalises the PROTOCOL but not the opaque part,
+  // so `ABOUT:BLANK` parses to href `about:BLANK` and an exact === would reject it.
+  if (parsed.protocol === 'about:' && parsed.href.toLowerCase() === 'about:blank') {
+    return 'about:blank';
+  }
+
   if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
     throw new Error(
-      `Blocked: scheme "${parsed.protocol}" is not allowed. Only http:, https:, and file: URLs are permitted.`
+      `Blocked: scheme "${parsed.protocol}" is not allowed. Only http:, https:, file:, and about:blank URLs are permitted.`
     );
   }
 

browse/src/write-commands.ts

@@ -249,11 +249,11 @@ export async function handleWriteCommand(
       if (!filePath) throw new Error('Usage: browse load-html <file> [--wait-until load|domcontentloaded|networkidle] [--tab-id <N>]  |  load-html --from-file <payload.json> [--tab-id <N>]');
 
       // Extension allowlist
-      const ALLOWED_EXT = ['.html', '.htm', '.xhtml', '.svg'];
+      const ALLOWED_EXT = ['.html', '.htm', '.xhtml'];
       const ext = path.extname(filePath).toLowerCase();
       if (!ALLOWED_EXT.includes(ext)) {
         throw new Error(
-          `load-html: file does not appear to be HTML. Expected .html/.htm/.xhtml/.svg, got ${ext || '(no extension)'}. Rename the file if it's really HTML.`
+          `load-html: file does not appear to be HTML. Expected .html/.htm/.xhtml, got ${ext || '(no extension)'}. Rename the file if it's really HTML.`
         );
       }
 
@@ -377,11 +377,14 @@ export async function handleWriteCommand(
       const value = valueParts.join(' ');
       if (!selector || !value) throw new Error('Usage: browse fill <selector> <value>');
       const resolved = await session.resolveRef(selector);
-      if ('locator' in resolved) {
-        await resolved.locator.fill(value, { timeout: 5000 });
-      } else {
-        await target.locator(resolved.selector).fill(value, { timeout: 5000 });
-      }
+      const locator = 'locator' in resolved ? resolved.locator : target.locator(resolved.selector);
+      await locator.fill(value, { timeout: 5000 });
+      // Playwright's fill() only dispatches an `input` event. Frameworks that
+      // validate on `change` (AngularJS ng-change, debounced strength/match
+      // checks — e.g. cPanel's Jupiter theme) never see the update, so a value
+      // that's correct in the DOM can still fail the framework's own
+      // validation. Dispatch `change` too so those listeners fire.
+      await locator.dispatchEvent('change');
       // Wait for network to settle (form validation XHRs)
       await page.waitForLoadState('networkidle', { timeout: 2000 }).catch(() => {});
       return `Filled ${selector}`;

browse/test/batch.test.ts

@@ -42,9 +42,14 @@ beforeAll(async () => {
   // The test needs to start a server. Let's use the existing server infrastructure.
 });
 
-afterAll(() => {
+afterAll(async () => {
   try { testServer.server.stop(); } catch {}
-  setTimeout(() => process.exit(0), 500);
+  // Close only this file's own browser — never process.exit(): bun test runs
+  // all files in one process, so a delayed exit kills the whole suite
+  // (see test/no-suicide-exit.test.ts). close() can hang when the browser
+  // already died, and its internal 5s timeout ties bun's 5s hook timeout —
+  // so race it at 3s and abandon; the child is reaped at process exit.
+  try { await Promise.race([bm?.close(), new Promise((resolve) => setTimeout(resolve, 3000))]); } catch {}
 });
 
 // We need a running browse server for HTTP tests.

browse/test/bun-polyfill.test.ts

@@ -3,6 +3,9 @@ import * as path from 'path';
 
 // Load the polyfill into a fresh object (don't clobber globalThis.Bun)
 const polyfillPath = path.resolve(import.meta.dir, '../src/bun-polyfill.cjs');
+// Forward slashes so the path survives interpolation into a JS string literal
+// on Windows, which is the platform this polyfill exists for.
+const requirePath = polyfillPath.replace(/\\/g, '/');
 
 describe('bun-polyfill', () => {
   // We test the polyfill by requiring it in a subprocess under Node.js
@@ -10,7 +13,7 @@ describe('bun-polyfill', () => {
 
   test('Bun.sleep resolves after delay', async () => {
     const result = Bun.spawnSync(['node', '-e', `
-      require('${polyfillPath}');
+      require('${requirePath}');
       (async () => {
         const start = Date.now();
         await Bun.sleep(50);
@@ -24,7 +27,7 @@ describe('bun-polyfill', () => {
 
   test('Bun.spawnSync runs a command and returns stdout', () => {
     const result = Bun.spawnSync(['node', '-e', `
-      require('${polyfillPath}');
+      require('${requirePath}');
       const r = Bun.spawnSync(['echo', 'hello'], { stdout: 'pipe' });
       console.log(r.stdout.toString().trim());
       console.log('exit:' + r.exitCode);
@@ -36,7 +39,7 @@ describe('bun-polyfill', () => {
 
   test('Bun.spawn launches a process with pid', async () => {
     const result = Bun.spawnSync(['node', '-e', `
-      require('${polyfillPath}');
+      require('${requirePath}');
       const p = Bun.spawn(['echo', 'test'], { stdio: ['pipe', 'pipe', 'pipe'] });
       console.log(typeof p.pid === 'number' ? 'HAS_PID' : 'NO_PID');
       console.log(typeof p.kill === 'function' ? 'HAS_KILL' : 'NO_KILL');
@@ -48,9 +51,179 @@ describe('bun-polyfill', () => {
     expect(lines[2]).toBe('HAS_UNREF');
   });
 
+  // Bun.spawn parity: `proc.exited` is a Promise resolving to the exit code.
+  // The DPAPI helper and isBrowserRunning both `await proc.exited`; without
+  // it the awaits resolve immediately to `undefined` and the caller reads
+  // stdout before the child has produced it — surfacing as a silent failure.
+  test('Bun.spawn exposes proc.exited that resolves to the exit code', async () => {
+    const result = Bun.spawnSync(['node', '-e', `
+      require('${requirePath}');
+      (async () => {
+        const p = Bun.spawn(['node', '-e', 'process.exit(0)'], { stdio: ['ignore', 'ignore', 'ignore'] });
+        console.log(typeof p.exited === 'object' && typeof p.exited.then === 'function' ? 'IS_PROMISE' : 'NOT_PROMISE');
+        console.log('exit:' + await p.exited);
+      })();
+    `], { stdout: 'pipe', stderr: 'pipe' });
+    const lines = result.stdout.toString().trim().split('\n');
+    expect(lines[0]).toBe('IS_PROMISE');
+    expect(lines[1]).toBe('exit:0');
+  });
+
+  test('Bun.spawn proc.exited reflects non-zero exit codes', async () => {
+    const result = Bun.spawnSync(['node', '-e', `
+      require('${requirePath}');
+      (async () => {
+        const p = Bun.spawn(['node', '-e', 'process.exit(3)'], { stdio: ['ignore', 'ignore', 'ignore'] });
+        console.log('exit:' + await p.exited);
+      })();
+    `], { stdout: 'pipe', stderr: 'pipe' });
+    expect(result.stdout.toString().trim()).toBe('exit:3');
+  });
+
+  test('Bun.spawn proc.exited resolves before reading stdout (no race)', async () => {
+    const result = Bun.spawnSync(['node', '-e', `
+      require('${requirePath}');
+      (async () => {
+        // Real-world pattern: write to stdout, then exit. Awaiting proc.exited
+        // before reading must guarantee the bytes are flushed.
+        const p = Bun.spawn(['node', '-e', 'process.stdout.write("ready"); process.exit(0)'], {
+          stdio: ['ignore', 'pipe', 'ignore']
+        });
+        const code = await p.exited;
+        const out = await new Response(p.stdout).text();
+        console.log(out + ':' + code);
+      })();
+    `], { stdout: 'pipe', stderr: 'pipe' });
+    expect(result.stdout.toString().trim()).toBe('ready:0');
+  });
+
+  // Spawn-failure case: Node emits 'error' but not 'exit' when the binary
+  // is missing, so listening only for 'exit' hangs `await proc.exited`
+  // forever. The lifecycle promise must resolve on either event.
+  test('Bun.spawn proc.exited resolves on spawn failure (missing binary)', async () => {
+    const result = Bun.spawnSync(['node', '-e', `
+      require('${requirePath}');
+      (async () => {
+        const p = Bun.spawn(['this-binary-does-not-exist-zzz-' + Date.now()], {
+          stdio: ['ignore', 'pipe', 'pipe']
+        });
+        const code = await Promise.race([
+          p.exited,
+          new Promise((_, r) => setTimeout(() => r(new Error('timeout')), 3000))
+        ]).catch(() => 'TIMEOUT');
+        console.log('exit:' + code);
+      })();
+    `], { stdout: 'pipe', stderr: 'pipe' });
+    // Anything other than 'TIMEOUT' (and ideally a non-zero number) means the
+    // lifecycle promise resolved on the spawn error.
+    const out = result.stdout.toString().trim();
+    expect(out).not.toBe('exit:TIMEOUT');
+    expect(out).toMatch(/^exit:\d+$/);
+  });
+
+  // GSTACK_SPAWN_MAX_BUFFER caps the drain so a runaway child can't OOM the
+  // server. Past the cap, the pipe keeps flowing (child doesn't block) but
+  // further bytes are dropped. Set a small cap, write more than that, assert
+  // the captured stdout equals the cap and the child exits cleanly.
+  test('Bun.spawn caps buffered output at GSTACK_SPAWN_MAX_BUFFER', async () => {
+    const result = Bun.spawnSync(['node', '-e', `
+      process.env.GSTACK_SPAWN_MAX_BUFFER = '${1024}';
+      require('${requirePath}');
+      (async () => {
+        // Child writes 10 KB; cap is 1 KB; drained output should be exactly 1 KB
+        // and exit should still resolve cleanly (child not back-pressured to death).
+        const p = Bun.spawn(
+          ['node', '-e', 'process.stdout.write("y".repeat(10 * 1024)); process.exit(0)'],
+          { stdio: ['ignore', 'pipe', 'ignore'] }
+        );
+        const code = await Promise.race([
+          p.exited,
+          new Promise((_, r) => setTimeout(() => r(new Error('timeout')), 3000))
+        ]).catch(() => 'TIMEOUT');
+        const out = await new Response(p.stdout).text();
+        console.log(out.length + ':' + code);
+      })();
+    `], { stdout: 'pipe', stderr: 'pipe' });
+    expect(result.stdout.toString().trim()).toBe('1024:0');
+  });
+
+  // Regression for the pipe-blocking case: if the child writes more than the
+  // OS pipe buffer (~16-64 KB) and the polyfill doesn't drain eagerly, the
+  // child blocks in write() and `exit` never fires. 1 MB is well past every
+  // OS pipe buffer size. Pre-fix this test hangs forever; post-fix it returns
+  // in <500ms. Bun's default per-test timeout is 5s — generous here.
+  test('Bun.spawn drains large stdout so proc.exited still resolves', async () => {
+    const result = Bun.spawnSync(['node', '-e', `
+      require('${requirePath}');
+      (async () => {
+        const ONE_MB = 1024 * 1024;
+        // Exit in the write callback, not straight after write(): on modern
+        // Node a pipe write past the OS buffer is async, and process.exit()
+        // right after write() truncates at ~64 KB even with a live reader.
+        // The callback only fires once the full MB is flushed — which still
+        // requires the parent to drain, so the regression (no eager drain →
+        // child blocks → timeout) is still caught.
+        const p = Bun.spawn(
+          ['node', '-e', 'process.stdout.write("x".repeat(' + ONE_MB + '), () => process.exit(0))'],
+          { stdio: ['ignore', 'pipe', 'ignore'] }
+        );
+        const code = await Promise.race([
+          p.exited,
+          new Promise((_, r) => setTimeout(() => r(new Error('timeout')), 10000))
+        ]).catch(e => 'TIMEOUT');
+        const out = await new Response(p.stdout).text();
+        console.log(out.length + ':' + code);
+      })().catch((e) => { console.log('THREW:' + e.message); });
+    `], { stdout: 'pipe', stderr: 'pipe' });
+    expect(result.stdout.toString().trim()).toBe('1048576:0');
+  }, 15000);
+
+  // windowsHide is the one option where Node's default is the opposite of
+  // Bun's: Node shows the child's console window, Bun hides it. Dropping it
+  // in translation makes every spawned child pop a window on Windows, which
+  // is the platform this whole file exists for. Both shims are covered.
+  test('Bun.spawn defaults windowsHide to true', () => {
+    const result = Bun.spawnSync(['node', '-e', `
+      const cp = require('child_process');
+      const orig = cp.spawn;
+      let seen;
+      cp.spawn = (c, a, o) => { seen = o; return orig(c, a, o); };
+      require('${requirePath}');
+      Bun.spawn(['node', '-e', ''], { stdio: ['ignore', 'ignore', 'ignore'] });
+      console.log('windowsHide:' + seen.windowsHide);
+    `], { stdout: 'pipe', stderr: 'pipe' });
+    expect(result.stdout.toString().trim()).toBe('windowsHide:true');
+  });
+
+  test('Bun.spawnSync defaults windowsHide to true', () => {
+    const result = Bun.spawnSync(['node', '-e', `
+      const cp = require('child_process');
+      const orig = cp.spawnSync;
+      let seen;
+      cp.spawnSync = (c, a, o) => { seen = o; return orig(c, a, o); };
+      require('${requirePath}');
+      Bun.spawnSync(['node', '-e', '']);
+      console.log('windowsHide:' + seen.windowsHide);
+    `], { stdout: 'pipe', stderr: 'pipe' });
+    expect(result.stdout.toString().trim()).toBe('windowsHide:true');
+  });
+
+  test('an explicit windowsHide:false is honored', () => {
+    const result = Bun.spawnSync(['node', '-e', `
+      const cp = require('child_process');
+      const orig = cp.spawn;
+      let seen;
+      cp.spawn = (c, a, o) => { seen = o; return orig(c, a, o); };
+      require('${requirePath}');
+      Bun.spawn(['node', '-e', ''], { stdio: ['ignore', 'ignore', 'ignore'], windowsHide: false });
+      console.log('windowsHide:' + seen.windowsHide);
+    `], { stdout: 'pipe', stderr: 'pipe' });
+    expect(result.stdout.toString().trim()).toBe('windowsHide:false');
+  });
+
   test('Bun.serve creates an HTTP server that responds', async () => {
     const result = Bun.spawnSync(['node', '-e', `
-      require('${polyfillPath}');
+      require('${requirePath}');
       const server = Bun.serve({
         port: 0,  // Note: polyfill uses port directly, so we pick one
         hostname: '127.0.0.1',

browse/test/cdp-session-cleanup.test.ts

@@ -18,7 +18,7 @@ import { withCdpSession, getOrCreateCdpSession } from '../src/cdp-bridge';
 // browse/test/server-sanitize-surrogates.test.ts: read source files
 // directly, assert an invariant on their contents.
 
-const SRC_DIR = path.resolve(new URL(import.meta.url).pathname, '..', '..', 'src');
+const SRC_DIR = path.resolve(import.meta.path, '..', '..', 'src');
 
 function readAllSourceFiles(): Array<{ file: string; content: string }> {
   const out: Array<{ file: string; content: string }> = [];

browse/test/cli-lock.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, test } from 'bun:test';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { acquireServerLock } from '../src/cli';
+
+function withTempDir<T>(fn: (dir: string) => T): T {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'browse-lock-'));
+  try {
+    return fn(dir);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+function captureErrors<T>(fn: () => T): { result: T; messages: string[] } {
+  const original = console.error;
+  const messages: string[] = [];
+  console.error = (...args: unknown[]) => {
+    messages.push(args.map(String).join(' '));
+  };
+  try {
+    return { result: fn(), messages };
+  } finally {
+    console.error = original;
+  }
+}
+
+describe('browse CLI server lock diagnostics (#1084)', () => {
+  test('logs non-EEXIST open failures instead of reporting phantom lock contention', () => {
+    withTempDir((dir) => {
+      const lockPath = path.join(dir, 'missing-parent', 'browse.json.lock');
+      const { result, messages } = captureErrors(() => acquireServerLock(lockPath));
+
+      expect(result).toBeNull();
+      expect(messages.join('\n')).toContain('unexpected ENOENT while opening');
+      expect(messages.join('\n')).toContain(lockPath);
+    });
+  });
+
+  test('returns null silently when a live process holds the lock', () => {
+    withTempDir((dir) => {
+      const lockPath = path.join(dir, 'browse.json.lock');
+      fs.writeFileSync(lockPath, `${process.pid}\n`);
+
+      const { result, messages } = captureErrors(() => acquireServerLock(lockPath));
+
+      expect(result).toBeNull();
+      expect(messages).toEqual([]);
+    });
+  });
+
+  test('logs holder PID read failures with code and lock path', () => {
+    withTempDir((dir) => {
+      const lockPath = path.join(dir, 'browse.json.lock');
+      fs.mkdirSync(lockPath);
+
+      const { result, messages } = captureErrors(() => acquireServerLock(lockPath));
+
+      expect(result).toBeNull();
+      expect(messages.join('\n')).toContain('unexpected EISDIR while reading holder PID from');
+      expect(messages.join('\n')).toContain(lockPath);
+    });
+  });
+
+  test('removes stale lock and reacquires it', () => {
+    withTempDir((dir) => {
+      const lockPath = path.join(dir, 'browse.json.lock');
+      fs.writeFileSync(lockPath, 'not-a-pid\n');
+
+      const release = acquireServerLock(lockPath);
+
+      expect(release).toBeFunction();
+      expect(fs.readFileSync(lockPath, 'utf-8').trim()).toBe(String(process.pid));
+      release?.();
+      expect(fs.existsSync(lockPath)).toBe(false);
+    });
+  });
+});

browse/test/cli-start-final-healthcheck.test.ts

@@ -0,0 +1,77 @@
+/**
+ * Coverage for #1846 — `browse` CLI must not report "Server failed to start
+ * within Ns" when the detached daemon actually came up healthy a moment later.
+ *
+ * The spawned server is `detached: true` + `.unref()`'d, so it keeps booting
+ * independently of the CLI's poll loop. On a loaded machine (the issue repro is
+ * Windows under load) the loop's budget can elapse in the gap between its last
+ * health tick and the daemon becoming ready — the very next `browse status`
+ * then shows a healthy, listening server. #1732 only widened the budget; the
+ * throw site itself still fired on timeout regardless of real health.
+ *
+ * Two invariants are defended here:
+ *   1. `startServer` does a final readState()+isServerHealthy() re-check before
+ *      the timeout throw (structural — removes the false negative at any budget).
+ *   2. The startup budget is env-overridable via BROWSE_START_TIMEOUT, matching
+ *      the BROWSE_* tunable convention (BROWSE_PORT, BROWSE_IDLE_TIMEOUT, ...).
+ *
+ * (1) is a static source invariant (live spawn cycles belong in the e2e tier);
+ * (2) is exercised behaviorally against the exported pure helper.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { resolveStartTimeout } from '../src/cli';
+
+const CLI = path.join(import.meta.dir, '..', 'src', 'cli.ts');
+const read = (): string => fs.readFileSync(CLI, 'utf-8');
+
+describe('#1846 startServer false-negative on a late-healthy detached daemon', () => {
+  test('a final health re-check sits between the poll loop and the timeout throw', () => {
+    const src = read();
+    const throwIdx = src.indexOf('Server failed to start within');
+    expect(throwIdx).toBeGreaterThan(-1);
+
+    // The startServer poll loop ends at its `await Bun.sleep(100)`; the final
+    // re-check must live AFTER that loop and BEFORE the timeout throw.
+    const loopEnd = src.lastIndexOf('await Bun.sleep(100)', throwIdx);
+    expect(loopEnd).toBeGreaterThan(-1);
+    const between = src.slice(loopEnd, throwIdx);
+
+    // It must re-read state and re-probe health, then be able to return — i.e.
+    // a genuine recovery path, not just a comment.
+    expect(between).toContain('readState()');
+    expect(between).toMatch(/isServerHealthy\([^)]*\)/);
+    expect(between).toMatch(/return\s+\w+;/);
+  });
+
+  test('the re-check returns the recovered state rather than swallowing it', () => {
+    const src = read();
+    // Guard against a refactor that probes health but forgets to return the
+    // state (which would re-introduce the false negative).
+    expect(src).toMatch(/if\s*\([^)]*await\s+isServerHealthy\([^)]*\)\)\s*\{\s*return\s+\w+;/);
+  });
+});
+
+describe('#1846 BROWSE_START_TIMEOUT env override (resolveStartTimeout)', () => {
+  const platformDefault = resolveStartTimeout({} as NodeJS.ProcessEnv);
+
+  test('platform default is a positive millisecond budget when unset', () => {
+    expect(platformDefault).toBeGreaterThan(0);
+  });
+
+  test('honors a positive BROWSE_START_TIMEOUT override', () => {
+    expect(resolveStartTimeout({ BROWSE_START_TIMEOUT: '42000' } as NodeJS.ProcessEnv)).toBe(42000);
+  });
+
+  test('falls back to the platform default for non-positive / unparseable values', () => {
+    for (const bad of ['0', '-5', 'abc', '', '   ']) {
+      expect(resolveStartTimeout({ BROWSE_START_TIMEOUT: bad } as NodeJS.ProcessEnv)).toBe(platformDefault);
+    }
+  });
+
+  test('MAX_START_WAIT is wired through resolveStartTimeout (no stray hardcoded constant)', () => {
+    const src = read();
+    expect(src).toMatch(/const\s+MAX_START_WAIT\s*=\s*resolveStartTimeout\(\)/);
+  });
+});

browse/test/cli-supervisor.test.ts

@@ -15,7 +15,7 @@ import * as path from 'path';
 // 3-8s each). These tripwires defend the load-bearing invariants:
 // opt-in by default, signal handlers wired, crash-loop guard, env knobs.
 
-const CLI_TS = path.resolve(new URL(import.meta.url).pathname, '..', '..', 'src', 'cli.ts');
+const CLI_TS = path.resolve(import.meta.path, '..', '..', 'src', 'cli.ts');
 
 describe('CLI outer supervisor (v1.44+)', () => {
   test('1. supervisor is opt-in via --supervise flag or BROWSE_SUPERVISE env', () => {

browse/test/commands.test.ts

@@ -126,11 +126,14 @@ beforeAll(async () => {
   await bm.launch();
 });
 
-afterAll(() => {
-  // Force kill browser instead of graceful close (avoids hang)
+afterAll(async () => {
   try { testServer.server.stop(); } catch {}
-  // bm.close() can hang — just let process exit handle it
-  setTimeout(() => process.exit(0), 500);
+  // Close only this file's own browser — never process.exit(): bun test runs
+  // all files in one process, so a delayed exit kills the whole suite
+  // (see test/no-suicide-exit.test.ts). close() can hang when the browser
+  // already died, and its internal 5s timeout ties bun's 5s hook timeout —
+  // so race it at 3s and abandon; the child is reaped at process exit.
+  try { await Promise.race([bm?.close(), new Promise((resolve) => setTimeout(resolve, 3000))]); } catch {}
 });
 
 // ─── Navigation ─────────────────────────────────────────────────
@@ -913,7 +916,10 @@ describe('CLI lifecycle', () => {
     cliEnv.BROWSE_STATE_FILE = stateFile;
     const result = await new Promise<{ code: number; stdout: string; stderr: string }>((resolve) => {
       const proc = spawn('bun', ['run', cliPath, 'status'], {
-        timeout: 15000,
+        // Must exceed the CLI's startup budget (resolveStartTimeout, 15s
+        // non-CI POSIX) or a slow cold boot under full-suite load gets the
+        // child killed at the exact moment the CLI would have succeeded.
+        timeout: 18000,
         env: cliEnv,
       });
       let stdout = '';
@@ -2315,6 +2321,19 @@ describe('load-html', () => {
     }
   });
 
+  test('load-html rejects .svg files', async () => {
+    const svgPath = path.join(tmpDir, `load-html-test-${Date.now()}.svg`);
+    fs.writeFileSync(svgPath, '<svg xmlns="http://www.w3.org/2000/svg"><text>hi</text></svg>');
+    try {
+      await handleWriteCommand('load-html', [svgPath], bm);
+      expect(true).toBe(false);
+    } catch (err: any) {
+      expect(err.message).toMatch(/does not appear to be HTML/);
+    } finally {
+      try { fs.unlinkSync(svgPath); } catch {}
+    }
+  });
+
   test('load-html rejects file outside safe dirs', async () => {
     try {
       await handleWriteCommand('load-html', ['/etc/passwd.html'], bm);

browse/test/compare-board.test.ts

@@ -69,10 +69,15 @@ beforeAll(async () => {
   await handleWriteCommand('goto', [boardUrl], bm);
 });
 
-afterAll(() => {
+afterAll(async () => {
   try { server.stop(); } catch {}
   fs.rmSync(tmpDir, { recursive: true, force: true });
-  setTimeout(() => process.exit(0), 500);
+  // Close only this file's own browser — never process.exit(): bun test runs
+  // all files in one process, so a delayed exit kills the whole suite
+  // (see test/no-suicide-exit.test.ts). close() can hang when the browser
+  // already died, and its internal 5s timeout ties bun's 5s hook timeout —
+  // so race it at 3s and abandon; the child is reaped at process exit.
+  try { await Promise.race([bm?.close(), new Promise((resolve) => setTimeout(resolve, 3000))]); } catch {}
 });
 
 // ─── DOM Structure ──────────────────────────────────────────────

browse/test/config.test.ts

@@ -124,6 +124,41 @@ describe('config', () => {
       expect(fs.existsSync(path.join(tmpDir, '.gitignore'))).toBe(false);
       fs.rmSync(tmpDir, { recursive: true, force: true });
     });
+
+    test('leaves .gitignore alone when git already ignores .gstack/ globally', () => {
+      const { spawnSync } = require('child_process');
+      const tmpDir = path.join(os.tmpdir(), `browse-gitignore-global-${Date.now()}`);
+      fs.mkdirSync(tmpDir, { recursive: true });
+
+      // Set up a real git repo
+      spawnSync('git', ['init', '-q'], { cwd: tmpDir });
+      spawnSync('git', ['config', 'user.email', 'test@test.com'], { cwd: tmpDir });
+      spawnSync('git', ['config', 'user.name', 'Test'], { cwd: tmpDir });
+
+      // Write a global excludes file that ignores .gstack/
+      const excludesFile = path.join(tmpDir, 'global-gitignore');
+      fs.writeFileSync(excludesFile, '.gstack/\n');
+      spawnSync('git', ['config', 'core.excludesFile', excludesFile], { cwd: tmpDir });
+
+      // .gitignore exists but does NOT contain .gstack/
+      fs.writeFileSync(path.join(tmpDir, '.gitignore'), 'node_modules/\n');
+      spawnSync('git', ['add', '.gitignore'], { cwd: tmpDir });
+      spawnSync('git', ['commit', '-qm', 'init'], { cwd: tmpDir });
+
+      // Verify git knows .gstack/ is ignored
+      const check = spawnSync('git', ['check-ignore', '-q', '.gstack/'], { cwd: tmpDir });
+      expect(check.status).toBe(0);
+
+      const config = resolveConfig({ BROWSE_STATE_FILE: path.join(tmpDir, '.gstack', 'browse.json') });
+      ensureStateDir(config);
+
+      // .gitignore must NOT have been modified
+      const content = fs.readFileSync(path.join(tmpDir, '.gitignore'), 'utf-8');
+      expect(content).toBe('node_modules/\n');
+      expect(fs.existsSync(path.join(tmpDir, '.gstack'))).toBe(true);
+
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
   });
 
   describe('getRemoteSlug', () => {

browse/test/content-security.test.ts

@@ -470,9 +470,14 @@ describe('Hidden element stripping', () => {
     await bm.launch();
   });
 
-  afterAll(() => {
+  afterAll(async () => {
     try { testServer.server.stop(); } catch {}
-    setTimeout(() => process.exit(0), 500);
+    // Close only this file's own browser — never process.exit(): bun test
+    // runs all files in one process, so a delayed exit kills the whole suite
+    // (see test/no-suicide-exit.test.ts). close() can hang when the browser
+    // already died, and its internal 5s timeout ties bun's 5s hook timeout —
+    // so race it at 3s and abandon; the child is reaped at process exit.
+    try { await Promise.race([bm?.close(), new Promise((resolve) => setTimeout(resolve, 3000))]); } catch {}
   });
 
   test('detects CSS-hidden elements on injection-hidden page', async () => {

browse/test/dual-listener.test.ts

@@ -224,9 +224,8 @@ describe('/command tunnel command allowlist', () => {
       'return handleCommand(body, tokenInfo)'
     );
     expect(commandBlock).toContain("surface === 'tunnel'");
-    // v1.63.0.0 made the allowlist args-aware (canDispatchOverTunnel gained a
-    // second param for --out denial); this pin was stale from then until the
-    // free suite got a CI job.
+    // Args-aware since the --out (disk write) tunnel ban: the dispatch gate
+    // takes both the command and its args.
     expect(commandBlock).toContain('canDispatchOverTunnel(body?.command, body?.args)');
     expect(commandBlock).toContain('disallowed_command');
     expect(commandBlock).toContain('is not allowed over the tunnel surface');

browse/test/extension-sender-auth.test.ts

@@ -0,0 +1,271 @@
+/**
+ * Sender authorization for privileged extension messages.
+ *
+ * A content script runs in web-page context and can be influenced by page
+ * content; a foreign extension is not us. Neither may read or spend the
+ * browse server's auth token or port through background.js's message
+ * surface. PR #1822 (@punksterlabs) found getPort handing the token to any
+ * caller that passed the type allowlist; this suite pins the reimplemented
+ * gate BEHAVIORALLY — it drives the real background.js onMessage listener
+ * under a chrome stub with four sender shapes (own extension page, own
+ * content script, foreign extension, url-less) and asserts denied responses
+ * are { error: 'unauthorized' } with no token/port fields at all.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const EXT_DIR = path.join(import.meta.dir, '..', '..', 'extension');
+const BG_SRC = fs.readFileSync(path.join(EXT_DIR, 'background.js'), 'utf-8');
+
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const senderAuth = require(path.join(EXT_DIR, 'sender-auth.js'));
+
+// The pinned production id (derivable via browse/scripts/extension-id.ts) —
+// the policy only compares it against sender.id, so any stable value works.
+const OWN_ID = 'dgbkdbjebeiblbajiilljmhjdpmiglep';
+const FOREIGN_ID = 'ffffffffffffffffffffffffffffffff';
+
+// ─── The four sender shapes ─────────────────────────────────────
+const PAGE_SENDER = { id: OWN_ID, url: `chrome-extension://${OWN_ID}/sidepanel.html` };
+const CONTENT_SCRIPT_SENDER = { id: OWN_ID, url: 'https://evil.example/page', tab: { id: 42 } };
+const FOREIGN_SENDER = { id: FOREIGN_ID, url: `chrome-extension://${FOREIGN_ID}/background.html` };
+const NO_URL_SENDER = { id: OWN_ID };
+
+const PRIVILEGED = [
+  'getPort', 'setPort', 'getServerUrl', 'getToken', 'fetchRefs',
+  'command', 'sidebar-command', 'getTabState',
+];
+// Content-script-originated flows that must keep working.
+const CONTENT_SCRIPT_TYPES = ['openSidePanel', 'elementPicked', 'pickerCancelled', 'inspectResult'];
+// Sidepanel-originated, non-privileged (page effects only, no token/port).
+const PAGE_EFFECT_TYPES = ['sidebarOpened', 'startInspector', 'stopInspector', 'applyStyle', 'toggleClass', 'injectCSS', 'resetAll'];
+
+const LEAK_FIELDS = ['token', 'authToken', 'port', 'url', 'connected', 'tabs', 'active', 'ok'];
+
+// ─── Unit: the policy predicate ─────────────────────────────────
+
+describe('sender-auth policy (unit)', () => {
+  test('own extension page is allowed for every privileged type', () => {
+    for (const type of PRIVILEGED) {
+      expect(senderAuth.denialFor(type, PAGE_SENDER, OWN_ID)).toBeNull();
+    }
+    expect(senderAuth.isExtensionPageSender(PAGE_SENDER, OWN_ID)).toBe(true);
+  });
+
+  test('own popup page is allowed (any own-extension page path)', () => {
+    const popup = { id: OWN_ID, url: `chrome-extension://${OWN_ID}/popup.html` };
+    expect(senderAuth.denialFor('getPort', popup, OWN_ID)).toBeNull();
+  });
+
+  test('own content script (sender.tab + page URL) is denied for every privileged type', () => {
+    for (const type of PRIVILEGED) {
+      const denial = senderAuth.denialFor(type, CONTENT_SCRIPT_SENDER, OWN_ID);
+      expect(denial).toEqual({ error: 'unauthorized' });
+      expect(Object.keys(denial)).toEqual(['error']);
+    }
+  });
+
+  test('foreign extension id is denied for every privileged type', () => {
+    for (const type of PRIVILEGED) {
+      expect(senderAuth.denialFor(type, FOREIGN_SENDER, OWN_ID)).toEqual({ error: 'unauthorized' });
+    }
+  });
+
+  test('missing sender.url is denied (no provenance)', () => {
+    for (const type of PRIVILEGED) {
+      expect(senderAuth.denialFor(type, NO_URL_SENDER, OWN_ID)).toEqual({ error: 'unauthorized' });
+    }
+    expect(senderAuth.denialFor('getToken', undefined, OWN_ID)).toEqual({ error: 'unauthorized' });
+  });
+
+  test('own extension page opened inside a TAB is denied (conservative: sender.tab wins)', () => {
+    const pageInTab = { id: OWN_ID, url: `chrome-extension://${OWN_ID}/sidepanel.html`, tab: { id: 7 } };
+    expect(senderAuth.denialFor('getToken', pageInTab, OWN_ID)).toEqual({ error: 'unauthorized' });
+  });
+
+  test('non-privileged types are never gated here — content-script flows stay reachable', () => {
+    for (const type of [...CONTENT_SCRIPT_TYPES, ...PAGE_EFFECT_TYPES]) {
+      expect(senderAuth.denialFor(type, CONTENT_SCRIPT_SENDER, OWN_ID)).toBeNull();
+      expect(senderAuth.denialFor(type, PAGE_SENDER, OWN_ID)).toBeNull();
+    }
+  });
+});
+
+// ─── Behavioral: the real background.js listener ────────────────
+
+type Listener = (msg: unknown, sender: unknown, sendResponse: (r: unknown) => void) => unknown;
+
+function loadBackground() {
+  const captured: { listener?: Listener } = {};
+  const calls = { storageSet: [] as unknown[], fetch: [] as unknown[] };
+  const never = new Promise(() => {}); // storage.get never settles → startup health polling never starts
+  const chromeStub = {
+    runtime: {
+      id: OWN_ID,
+      onMessage: { addListener: (fn: Listener) => { captured.listener = fn; } },
+      onInstalled: { addListener: () => {} },
+      sendMessage: () => Promise.resolve(),
+    },
+    storage: {
+      local: {
+        get: () => never,
+        set: (obj: unknown) => { calls.storageSet.push(obj); return Promise.resolve(); },
+      },
+    },
+    tabs: {
+      onActivated: { addListener: () => {} },
+      onCreated: { addListener: () => {} },
+      onRemoved: { addListener: () => {} },
+      onUpdated: { addListener: () => {} },
+      query: (_opts: unknown, cb?: (tabs: unknown[]) => void) => {
+        if (cb) { cb([]); return; }
+        return Promise.resolve([]);
+      },
+      sendMessage: () => Promise.resolve(),
+      get: () => {},
+    },
+    action: { setBadgeBackgroundColor: () => {}, setBadgeText: () => {} },
+    scripting: { executeScript: () => Promise.resolve(), insertCSS: () => Promise.resolve() },
+    // no chrome.sidePanel: autoOpenSidePanel exits immediately (no retry timers)
+  };
+  const fetchSpy = (...args: unknown[]) => {
+    calls.fetch.push(args);
+    return Promise.reject(new Error('no network in tests'));
+  };
+  // background.js is a classic (non-module) service worker script — evaluate
+  // it with its globals injected. importScripts is satisfied by passing the
+  // already-required sender-auth module under the global name it registers.
+  const run = new Function('chrome', 'importScripts', 'gstackSenderAuth', 'fetch', BG_SRC);
+  run(chromeStub, () => {}, senderAuth, fetchSpy);
+  if (!captured.listener) throw new Error('background.js did not register an onMessage listener');
+  return { listener: captured.listener, calls };
+}
+
+function dispatch(listener: Listener, msg: unknown, sender: unknown) {
+  const result = { responded: false, response: undefined as Record<string, unknown> | undefined };
+  listener(msg, sender, (resp: unknown) => {
+    result.responded = true;
+    result.response = resp as Record<string, unknown>;
+  });
+  return result;
+}
+
+// Denied senders get { error: 'unauthorized' } and nothing else — or no
+// response at all (the pre-existing foreign-sender early return). Either
+// way: never a token, port, or tab-state field.
+function expectDenied(result: ReturnType<typeof dispatch>) {
+  if (result.responded) {
+    expect(result.response).toEqual({ error: 'unauthorized' });
+    expect(Object.keys(result.response!)).toEqual(['error']);
+  }
+  const resp = result.response ?? {};
+  for (const leak of LEAK_FIELDS) {
+    expect(resp[leak]).toBeUndefined();
+  }
+}
+
+describe('background.js onMessage listener (behavioral)', () => {
+  const { listener, calls } = loadBackground();
+
+  test('own sidepanel page: getPort responds with port/connected/token fields, no error', () => {
+    const r = dispatch(listener, { type: 'getPort' }, PAGE_SENDER);
+    expect(r.responded).toBe(true);
+    expect('port' in r.response!).toBe(true);
+    expect('connected' in r.response!).toBe(true);
+    // The sidepanel's tryConnect reads resp.token — the field must exist for
+    // extension pages (value is null until the token bootstrap completes).
+    expect('token' in r.response!).toBe(true);
+    expect(r.response!.error).toBeUndefined();
+  });
+
+  test('own sidepanel page: getToken responds with a token field', () => {
+    const r = dispatch(listener, { type: 'getToken' }, PAGE_SENDER);
+    expect(r.responded).toBe(true);
+    expect('token' in r.response!).toBe(true);
+    expect(r.response!.error).toBeUndefined();
+  });
+
+  test('own content script: every privileged type is denied with no token/port fields', () => {
+    for (const type of PRIVILEGED) {
+      const r = dispatch(listener, { type }, CONTENT_SCRIPT_SENDER);
+      expect(r.responded).toBe(true); // the gate answers, it does not go silent
+      expectDenied(r);
+    }
+  });
+
+  test('foreign extension: every privileged type yields no token/port fields', () => {
+    for (const type of PRIVILEGED) {
+      expectDenied(dispatch(listener, { type }, FOREIGN_SENDER));
+    }
+  });
+
+  test('missing sender.url: every privileged type is denied', () => {
+    for (const type of PRIVILEGED) {
+      const r = dispatch(listener, { type }, NO_URL_SENDER);
+      expect(r.responded).toBe(true);
+      expectDenied(r);
+    }
+  });
+
+  test('denied setPort never persists the attacker port', () => {
+    const before = calls.storageSet.length;
+    const r = dispatch(listener, { type: 'setPort', port: 6666 }, CONTENT_SCRIPT_SENDER);
+    expectDenied(r);
+    expect(calls.storageSet.length).toBe(before);
+  });
+
+  test('denied command never reaches the network and fails at the gate, not the handler', () => {
+    const before = calls.fetch.length;
+    const r = dispatch(listener, { type: 'command', command: 'goto', args: ['https://evil.example'] }, CONTENT_SCRIPT_SENDER);
+    // 'unauthorized' proves the gate fired; the handler's own failure mode is
+    // 'Not connected to browse server'.
+    expect(r.response).toEqual({ error: 'unauthorized' });
+    expect(calls.fetch.length).toBe(before);
+  });
+
+  test('content script can still run the inspector flow (elementPicked → ok)', async () => {
+    const r = dispatch(
+      listener,
+      { type: 'elementPicked', selector: '#hero', tagName: 'div', classes: [], id: null, dimensions: { width: 1, height: 1 } },
+      CONTENT_SCRIPT_SENDER,
+    );
+    await new Promise((res) => setTimeout(res, 10));
+    expect(r.response).toEqual({ ok: true });
+  });
+
+  test('content script can still request openSidePanel (not rejected as unauthorized)', () => {
+    const r = dispatch(listener, { type: 'openSidePanel' }, CONTENT_SCRIPT_SENDER);
+    // chrome.sidePanel is absent in the stub so the handler is a no-op — the
+    // load-bearing assertion is that the gate did not deny it.
+    expect(r.response?.error).toBeUndefined();
+  });
+
+  test('sidepanel getTabState still works (terminal pane tab sync)', async () => {
+    const r = dispatch(listener, { type: 'getTabState' }, PAGE_SENDER);
+    await new Promise((res) => setTimeout(res, 10));
+    expect(r.responded).toBe(true);
+    expect(r.response).toEqual({ active: null, tabs: [] });
+  });
+});
+
+// ─── Wiring tripwire ────────────────────────────────────────────
+// The behavioral suite injects senderAuth directly, so pin that the real
+// worker actually loads it: importScripts of the helper file plus a
+// denialFor call in the listener. A refactor that drops either fails here.
+
+describe('background.js ↔ sender-auth.js wiring', () => {
+  test('background.js importScripts sender-auth.js (classic worker load path)', () => {
+    expect(BG_SRC).toContain("importScripts('sender-auth.js')");
+  });
+
+  test('background.js consults gstackSenderAuth.denialFor in the message listener', () => {
+    expect(BG_SRC).toContain('gstackSenderAuth.denialFor(msg.type, sender, chrome.runtime.id)');
+  });
+
+  test('manifest keeps a classic (non-module) service worker — importScripts requires it', () => {
+    const manifest = JSON.parse(fs.readFileSync(path.join(EXT_DIR, 'manifest.json'), 'utf-8'));
+    expect(manifest.background.service_worker).toBe('background.js');
+    expect(manifest.background.type).toBeUndefined();
+  });
+});

browse/test/file-permissions.test.ts

@@ -77,6 +77,26 @@ describe('restrictDirectoryPermissions', () => {
     fs.mkdirSync(d);
     expect(() => restrictDirectoryPermissions(d)).not.toThrow();
   });
+
+  test('on Windows, the directory stays usable by the calling process', () => {
+    if (process.platform !== 'win32') return;
+    const d = path.join(tmpDir, 'still-usable');
+    fs.mkdirSync(d);
+    fs.writeFileSync(path.join(d, 'before'), 'x');
+
+    restrictDirectoryPermissions(d);
+
+    // Regression: an unqualified username passed to icacls can resolve to
+    // the machine SID rather than the user account. Combined with
+    // /inheritance:r that leaves a directory whose only ACE matches nobody,
+    // so the process that just "secured" it can no longer enumerate or
+    // write to it. icacls still reports success, so a not-toThrow assertion
+    // sails straight past it — hence these access checks.
+    expect(() => fs.readdirSync(d)).not.toThrow();
+    expect(fs.readdirSync(d)).toContain('before');
+    expect(() => fs.writeFileSync(path.join(d, 'after'), 'y')).not.toThrow();
+    expect(fs.readFileSync(path.join(d, 'after'), 'utf8')).toBe('y');
+  });
 });
 
 describe('writeSecureFile', () => {
@@ -138,6 +158,16 @@ describe('mkdirSecure', () => {
     expect(() => mkdirSecure(d)).not.toThrow();
   });
 
+  test('on Windows, the created directory stays usable by the caller', () => {
+    if (process.platform !== 'win32') return;
+    // The state-dir path that broke: mkdirSecure() creates .gstack/, hardens
+    // it, and the very next thing the daemon does is write a lockfile inside.
+    const d = path.join(tmpDir, 'state', '.gstack');
+    mkdirSecure(d);
+    expect(() => fs.writeFileSync(path.join(d, 'browse.json.lock'), '1')).not.toThrow();
+    expect(fs.readdirSync(d)).toContain('browse.json.lock');
+  });
+
   test('recursive behavior: creates intermediate directories', () => {
     const d = path.join(tmpDir, 'a', 'b', 'c');
     mkdirSecure(d);

browse/test/fill-change-event.test.ts

@@ -0,0 +1,57 @@
+/**
+ * Regression test for `browse fill` on change-only validators.
+ *
+ * Playwright's Locator.fill() dispatches an `input` event but not `change`.
+ * Frameworks that validate on `change` (AngularJS ng-change, debounced
+ * strength/match checks — e.g. cPanel's Jupiter theme "Add FTP Account"
+ * password-match check) never see the update: the DOM value is correct but
+ * the framework's own validator still reports a mismatch.
+ */
+
+import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
+import { startTestServer } from './test-server';
+import { BrowserManager } from '../src/browser-manager';
+import { handleWriteCommand as _handleWriteCommand } from '../src/write-commands';
+
+const handleWriteCommand = (cmd: string, args: string[], b: BrowserManager) =>
+  _handleWriteCommand(cmd, args, b.getActiveSession(), b);
+
+let testServer: ReturnType<typeof startTestServer>;
+let bm: BrowserManager;
+let baseUrl: string;
+
+beforeAll(async () => {
+  testServer = startTestServer(0);
+  baseUrl = testServer.url;
+  bm = new BrowserManager();
+  await bm.launch();
+});
+
+afterAll(async () => {
+  try { testServer.server.stop(); } catch {}
+  // Close only this file's own browser — never process.exit(): bun test runs
+  // all files in one process, so a delayed exit kills the whole suite
+  // (see test/no-suicide-exit.test.ts). close() can hang when the browser
+  // already died, so race it at 3s and abandon; the child is reaped at exit.
+  try { await Promise.race([bm?.close(), new Promise((resolve) => setTimeout(resolve, 3000))]); } catch {}
+});
+
+describe('fill dispatches change event', () => {
+  test('a change-only validator sees the filled value', async () => {
+    await handleWriteCommand('goto', [baseUrl + '/change-only-validator.html'], bm);
+    await handleWriteCommand('fill', ['#password', 'hello123'], bm);
+    await handleWriteCommand('fill', ['#password2', 'hello123'], bm);
+
+    const status = await bm.getPage().locator('#match-status').textContent();
+    expect(status).toBe('match');
+  });
+
+  test('a change-only validator still catches a real mismatch', async () => {
+    await handleWriteCommand('goto', [baseUrl + '/change-only-validator.html'], bm);
+    await handleWriteCommand('fill', ['#password', 'hello123'], bm);
+    await handleWriteCommand('fill', ['#password2', 'different'], bm);
+
+    const status = await bm.getPage().locator('#match-status').textContent();
+    expect(status).toBe('no-match');
+  });
+});

browse/test/fixtures/change-only-validator.html

@@ -0,0 +1,31 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Test Page - Change-Only Validator</title>
+</head>
+<body>
+  <h1>Change-Only Validator</h1>
+
+  <!--
+    Minimal repro of AngularJS ng-change / debounced cross-field validators
+    (e.g. cPanel's Jupiter theme "Add FTP Account" password-match check):
+    the listener only reacts to `change`, never `input`. A page like this
+    silently "loses" a Playwright-style value-set-without-a-change-event.
+  -->
+  <input type="password" id="password" name="password">
+  <input type="password" id="password2" name="password2">
+  <div id="match-status">unknown</div>
+
+  <script>
+    function checkMatch() {
+      var a = document.getElementById('password').value;
+      var b = document.getElementById('password2').value;
+      document.getElementById('match-status').textContent =
+        a && a === b ? 'match' : 'no-match';
+    }
+    document.getElementById('password').addEventListener('change', checkMatch);
+    document.getElementById('password2').addEventListener('change', checkMatch);
+  </script>
+</body>
+</html>

browse/test/gstack-update-check.test.ts

@@ -42,6 +42,14 @@ beforeEach(() => {
   const binDir = join(gstackDir, 'bin');
   mkdirSync(binDir);
   symlinkSync(join(import.meta.dir, '..', '..', 'bin', 'gstack-config'), join(binDir, 'gstack-config'));
+  // v1.63+: the script sources bin/gstack-egress-lib.sh unconditionally
+  // (receipted fetch helpers). A real install always has it beside
+  // gstack-config; without this link every test failed at the source line —
+  // masked until the suite-truncation fix because the runner died first.
+  symlinkSync(
+    join(import.meta.dir, '..', '..', 'bin', 'gstack-egress-lib.sh'),
+    join(binDir, 'gstack-egress-lib.sh'),
+  );
 });
 
 afterEach(() => {

browse/test/handoff.test.ts

@@ -26,9 +26,14 @@ beforeAll(async () => {
   await bm.launch();
 });
 
-afterAll(() => {
+afterAll(async () => {
   try { testServer.server.stop(); } catch {}
-  setTimeout(() => process.exit(0), 500);
+  // Close only this file's own browser — never process.exit(): bun test runs
+  // all files in one process, so a delayed exit kills the whole suite
+  // (see test/no-suicide-exit.test.ts). close() can hang when the browser
+  // already died, and its internal 5s timeout ties bun's 5s hook timeout —
+  // so race it at 3s and abandon; the child is reaped at process exit.
+  try { await Promise.race([bm?.close(), new Promise((resolve) => setTimeout(resolve, 3000))]); } catch {}
 });
 
 // ─── Unit Tests: Failure Tracking (no browser needed) ────────────
@@ -172,8 +177,15 @@ describe('handoff edge cases', () => {
 // Each handoff test creates its own BrowserManager since handoff swaps the browser.
 // These tests run sequentially (one browser at a time) to avoid resource issues.
 
+// Headed-mode launch is broken on current macOS (the rebrand invalidates the
+// Chrome-for-Testing bundle signature and XProtect kills the relaunch —
+// #2242, #2554, #2138). These three integration tests drive a real headed
+// handoff and fail ~5s in on any darwin box. They stay ENABLED on Linux CI.
+// Un-skip when the browse-daemon lifecycle wave lands the signature fix.
+const HEADED_BROKEN_ON_DARWIN = process.platform === 'darwin';
+
 describe('handoff integration', () => {
-  test('full handoff: cookies preserved, headed mode active, commands work', async () => {
+  test.skipIf(HEADED_BROKEN_ON_DARWIN)('full handoff: cookies preserved, headed mode active, commands work', async () => {
     const hbm = new BrowserManager();
     await hbm.launch();
 
@@ -206,7 +218,7 @@ describe('handoff integration', () => {
     }
   }, 45000);
 
-  test('multi-tab handoff preserves all tabs', async () => {
+  test.skipIf(HEADED_BROKEN_ON_DARWIN)('multi-tab handoff preserves all tabs', async () => {
     const hbm = new BrowserManager();
     await hbm.launch();
 
@@ -223,7 +235,7 @@ describe('handoff integration', () => {
     }
   }, 45000);
 
-  test('handoff meta command joins args as message', async () => {
+  test.skipIf(HEADED_BROKEN_ON_DARWIN)('handoff meta command joins args as message', async () => {
     const hbm = new BrowserManager();
     await hbm.launch();
 

browse/test/process-liveness-windows.test.ts

@@ -0,0 +1,138 @@
+import { describe, test, expect } from 'bun:test';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { isProcessAlive } from '../src/error-handling';
+import { spawnTerminalAgent } from '../src/terminal-agent-control';
+
+// REGRESSION TEST for the Windows terminal-agent leak.
+//
+// Symptom (reported on Windows 11, 48GB box under a heavy parallel build):
+// a console window popped to the foreground every 60 seconds, and orphaned
+// `bun run terminal-agent.ts` processes accumulated at one per minute until
+// the machine ran out of committable memory.
+//
+// Root cause was a three-bug chain, each of which this file pins:
+//
+//   1. `isProcessAlive` shelled out to `tasklist` on Windows with a 3s
+//      timeout. A Bun.spawnSync that hits its timeout STILL RETURNS, carrying
+//      partial stdout — so the `.includes()` PID match came back false and a
+//      LIVE agent was reported dead. Measured tasklist latency was 700-1700ms
+//      idle, and far worse under memory pressure, so the timeout was reachable
+//      in ordinary use.
+//   2. That false negative made `killAgentByRecord` skip the kill (it
+//      validates liveness first) while the watchdog respawned anyway —
+//      leaking the survivor. Each orphan added memory pressure, slowing the
+//      next tasklist, producing the next false negative. Self-reinforcing.
+//   3. Neither the tasklist probe nor the agent spawn passed `windowsHide`,
+//      so every tick allocated a visible console and stole focus.
+//
+// The guard-window arithmetic bug that let this run unbounded instead of
+// tripping the crash-loop guard is pinned separately, in test 6.
+
+const SRC_DIR = path.resolve(import.meta.dir, '..', 'src');
+
+function readAllSourceFiles(): Array<{ file: string; content: string }> {
+  return fs
+    .readdirSync(SRC_DIR)
+    .filter((e) => e.endsWith('.ts'))
+    .map((e) => ({ file: e, content: fs.readFileSync(path.join(SRC_DIR, e), 'utf-8') }));
+}
+
+/** Strip line and block comments so static greps only see real code. */
+function stripComments(src: string): string {
+  return src.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^\s*\/\/.*$/gm, '');
+}
+
+describe('process liveness probe (Windows terminal-agent leak)', () => {
+  test('1. isProcessAlive reports the current process alive', () => {
+    expect(isProcessAlive(process.pid)).toBe(true);
+  });
+
+  test('2. isProcessAlive reports an unused PID dead', () => {
+    // Below Linux PID_MAX_LIMIT, far above any realistic Windows/macOS PID.
+    expect(isProcessAlive(2147483646)).toBe(false);
+  });
+
+  test('3. isProcessAlive spawns NO subprocess', () => {
+    // The heart of the bug: a liveness probe that forks is slow enough to
+    // time out, and a timed-out probe silently answers "dead". Signal 0
+    // cannot time out because it never leaves the process.
+    const origSpawn = (Bun as any).spawn;
+    const origSpawnSync = (Bun as any).spawnSync;
+    const spawns: string[] = [];
+    (Bun as any).spawn = (...args: any[]) => { spawns.push(`spawn:${JSON.stringify(args[0])}`); return origSpawn(...args); };
+    (Bun as any).spawnSync = (...args: any[]) => { spawns.push(`spawnSync:${JSON.stringify(args[0])}`); return origSpawnSync(...args); };
+    try {
+      isProcessAlive(process.pid);
+      isProcessAlive(2147483646);
+      expect(spawns).toEqual([]);
+    } finally {
+      (Bun as any).spawn = origSpawn;
+      (Bun as any).spawnSync = origSpawnSync;
+    }
+  });
+
+  test('4. no source file probes liveness via tasklist', () => {
+    // Static tripwire: re-introducing a tasklist-based existence check
+    // anywhere in src/ resurrects the false-negative class.
+    const offenders: string[] = [];
+    for (const { file, content } of readAllSourceFiles()) {
+      const code = stripComments(content);
+      // `PID eq` is the existence-probe form specifically. Other tasklist
+      // uses (e.g. IMAGENAME filters for browser detection) are unaffected.
+      if (/tasklist/.test(code) && /PID eq/.test(code)) offenders.push(file);
+    }
+    expect(offenders).toEqual([]);
+  });
+
+  test('5. spawnTerminalAgent passes windowsHide so no console is shown', () => {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-hide-'));
+    const script = path.join(tmpDir, 'fake-agent.ts');
+    fs.writeFileSync(script, '// no-op\n');
+    const origSpawn = (Bun as any).spawn;
+    let captured: any = null;
+    (Bun as any).spawn = (_cmd: any, opts: any) => {
+      captured = opts;
+      return { pid: 4242, unref() {} };
+    };
+    try {
+      const pid = spawnTerminalAgent({
+        stateFile: path.join(tmpDir, 'state.json'),
+        serverPort: 12345,
+        ownerPid: process.pid,
+        cwd: tmpDir,
+        scriptPath: script,
+      });
+      expect(pid).toBe(4242);
+      expect(captured).not.toBeNull();
+      expect(captured.windowsHide).toBe(true);
+      // Owner-PID lifetime tie (#2019): the agent polls this and exits when
+      // its owning browse server dies, so it can't be adopted by PID 1.
+      expect(captured.env.BROWSE_OWNER_PID).toBe(String(process.pid));
+      // Detached background daemon — must not inherit a terminal either.
+      expect(captured.stdio).toEqual(['ignore', 'ignore', 'ignore']);
+    } finally {
+      (Bun as any).spawn = origSpawn;
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  test('6. respawn guard window spans enough ticks for the guard to fire', () => {
+    // The guard was `RESPAWN_GUARD_WINDOW_MS = 60_000` against a 60_000ms
+    // tick, allowing at most ONE respawn in the window — so the
+    // `>= RESPAWN_GUARD_MAX (3)` trip condition was unreachable and a steady
+    // one-per-tick leak never self-limited. Assert the window is derived from
+    // the tick rather than fixed.
+    const src = fs.readFileSync(path.join(SRC_DIR, 'server.ts'), 'utf-8');
+    const match = src.match(/const RESPAWN_GUARD_WINDOW_MS =([\s\S]{0,160}?);/);
+    expect(match).not.toBeNull();
+    expect(match![1]).toContain('AGENT_WATCHDOG_TICK_MS');
+
+    // Pin the arithmetic itself: at the default tick, three respawns must fit.
+    const tick = 60_000;
+    const guardMax = 3;
+    const windowMs = Math.max(60_000, tick * (guardMax + 2));
+    expect(windowMs).toBeGreaterThanOrEqual(tick * guardMax);
+  });
+});

browse/test/security-live-playwright.test.ts

@@ -56,9 +56,14 @@ describe('defense-in-depth — live Playwright fixture', () => {
     await bm.launch();
   });
 
-  afterAll(() => {
+  afterAll(async () => {
     try { testServer.server.stop(); } catch {}
-    setTimeout(() => process.exit(0), 500);
+    // Close only this file's own browser — never process.exit(): bun test
+    // runs all files in one process, so a delayed exit kills the whole suite
+    // (see test/no-suicide-exit.test.ts). close() can hang when the browser
+    // already died, and its internal 5s timeout ties bun's 5s hook timeout —
+    // so race it at 3s and abandon; the child is reaped at process exit.
+    try { await Promise.race([bm?.close(), new Promise((resolve) => setTimeout(resolve, 3000))]); } catch {}
   });
 
   test('L2 — content-security.ts hidden-element stripper detects the .sneaky div', async () => {

browse/test/server-embedder-terminal-port.test.ts

@@ -236,7 +236,7 @@ describe('buildFetchHandler ownsTerminalAgent gate', () => {
     // Resolves browse/src/server.ts relative to this test file so the test
     // works regardless of cwd. import.meta.url is the test file's URL.
     const serverTsPath = path.resolve(
-      new URL(import.meta.url).pathname,
+      import.meta.path,
       '..',
       '..',
       'src',

browse/test/server-pty-lease-routes.test.ts

@@ -7,7 +7,7 @@ import * as path from 'path';
 // loopback to be live (e2e-tier); these static-grep tripwires pin the
 // load-bearing protocol invariants.
 
-const SERVER_TS = path.resolve(new URL(import.meta.url).pathname, '..', '..', 'src', 'server.ts');
+const SERVER_TS = path.resolve(import.meta.path, '..', '..', 'src', 'server.ts');
 
 describe('server: PTY lease routes (v1.44+ Commit 2)', () => {
   test('1. /pty-session returns the 4-tuple shape (sessionId, attachToken, leaseExpiresAt)', () => {

browse/test/sidebar-tabs.test.ts

@@ -157,9 +157,9 @@ describe('sidepanel-terminal.js: eager auto-connect + injection API', () => {
   test('forceRestart helper closes ws, disposes xterm, returns to IDLE', () => {
     expect(TERM_JS).toContain('function forceRestart');
     const fn = TERM_JS.slice(TERM_JS.indexOf('function forceRestart'));
-    // Deliberate close code so the agent's close handler can distinguish an
-    // intentional restart from a dropped connection (codex D8 redesign).
-    expect(fn).toContain("ws.close(4001, 'intentional-restart')");
+    // close() carries an intentional-restart close code so the agent's
+    // close handler can distinguish user restarts from network drops.
+    expect(fn).toContain("ws && ws.close(4001, 'intentional-restart')");
     expect(fn).toContain('term.dispose()');
     expect(fn).toContain('STATE.IDLE');
     expect(fn).toContain('tryAutoConnect()');
@@ -225,16 +225,17 @@ describe('cli.ts: sidebar-agent is no longer spawned', () => {
   });
 
   test('Terminal-agent spawn survives', () => {
-    // The inline Bun.spawn of termAgentScript moved into the shared
-    // spawnTerminalAgent helper (terminal-agent-control.ts) so the CLI
-    // cold-start path and the supervisor respawn path share one
-    // identity-tracked spawn. The CLI must still call it.
-    expect(CLI_SRC).toContain("import { spawnTerminalAgent } from './terminal-agent-control'");
-    expect(CLI_SRC).toMatch(/spawnTerminalAgent\(\{/);
+    // v1.44 moved the raw Bun.spawn into the shared spawnTerminalAgent
+    // helper (terminal-agent-control.ts) so cli.ts, the supervisor respawn
+    // loop, and the watchdog all share identity-based process control.
+    // cli.ts must still route through that helper.
+    expect(CLI_SRC).toContain('spawnTerminalAgent');
     const CONTROL_SRC = fs.readFileSync(
-      path.join(import.meta.dir, '../src/terminal-agent-control.ts'), 'utf-8');
+      path.join(import.meta.dir, '../src/terminal-agent-control.ts'),
+      'utf-8',
+    );
     expect(CONTROL_SRC).toContain('terminal-agent.ts');
-    expect(CONTROL_SRC).toMatch(/spawn\(\['bun',\s*'run',\s*script\]/);
+    expect(CONTROL_SRC).toMatch(/\.spawn\(\['bun',\s*'run',\s*script\]/);
   });
 });
 

browse/test/sidebar-ux.test.ts

@@ -1,14 +1,23 @@
 /**
- * Tests for sidebar UX invariants that survived the chat-tab rip:
- * - Browser tab bar HTML/CSS + browser-manager tab sync plumbing
- * - Inspector message allowlist + CSP fallback basic picker
- * - Cleanup/screenshot toolbar buttons + deterministic cleanup heuristics
- * - Welcome page, sidebar auto-open, arrow hint signal chain
- * - Connection auth race, startup fast-retry, debug visibility
+ * Structural tests for the sidebar's surviving UX surfaces:
+ * - Quick-action toolbar (cleanup via PTY injection, screenshot, cookies)
+ * - CSP fallback basic picker (content.js) + inspector allowlist
+ * - Deterministic cleanup heuristics (write-commands.ts)
+ * - Welcome page + sidebar auto-open + arrow hint signal chain
+ * - Connection/auth race prevention + startup health check
+ * - browser-manager tab tracking + no-focus-steal invariants
+ * - Server shutdown teardown of the terminal-agent
  *
- * The chat-queue pipeline (sidebar-agent.ts, /sidebar-command,
- * /sidebar-chat, chat bubbles) is gone — its tests were pruned with it.
- * See sidebar-tabs.test.ts for the invariants locking that removal.
+ * History: this file used to also pin the chat-queue architecture
+ * (sidebar-agent.ts, /sidebar-command, /sidebar-chat, /sidebar-tabs,
+ * per-tab chat context, stop button, chat polling, processAgentEvent,
+ * pickSidebarModel). That entire path was deliberately ripped in PR #1216
+ * (v1.14.0.0) when the interactive claude PTY (terminal-agent.ts) proved
+ * strictly more capable — see docs/designs/SIDEBAR_MESSAGE_FLOW.md. The
+ * stale blocks kept "passing" only because a teardown bug made `bun test`
+ * exit 0 before reporting; once that was fixed (PR #2172) they surfaced as
+ * failures and were removed. The rip itself is pinned as absence tests in
+ * browse/test/sidebar-tabs.test.ts.
  */
 
 import { describe, test, expect } from 'bun:test';
@@ -17,8 +26,6 @@ import * as path from 'path';
 
 const ROOT = path.resolve(__dirname, '..');
 
-// ─── Browser tab bar ────────────────────────────────────────────
-
 describe('browser tab bar (sidepanel.html)', () => {
   const html = fs.readFileSync(path.join(ROOT, '..', 'extension', 'sidepanel.html'), 'utf-8');
 
@@ -48,8 +55,6 @@ describe('sidebar→browser tab switch', () => {
 
 describe('browser→sidebar tab sync', () => {
   const bmSrc = fs.readFileSync(path.join(ROOT, 'src', 'browser-manager.ts'), 'utf-8');
-  const serverSrc = fs.readFileSync(path.join(ROOT, 'src', 'server.ts'), 'utf-8');
-  const js = fs.readFileSync(path.join(ROOT, '..', 'extension', 'sidepanel.js'), 'utf-8');
 
   test('syncActiveTabByUrl method exists on BrowserManager', () => {
     expect(bmSrc).toContain('syncActiveTabByUrl(activeUrl: string)');
@@ -89,12 +94,16 @@ describe('browser→sidebar tab sync', () => {
     expect(fn).toContain('this.pages.size <= 1');
   });
 
+  // NOTE: the /sidebar-tabs + /sidebar-command server consumers of
+  // syncActiveTabByUrl and the sidepanel chat-tab handlers were removed
+  // with the chat-queue rip (PR #1216). The BrowserManager primitives above
+  // survive (tab tracking feeds active-tab.json for the PTY claude).
+
   test('background.js listens for chrome.tabs.onActivated', () => {
     const bgSrc = fs.readFileSync(path.join(ROOT, '..', 'extension', 'background.js'), 'utf-8');
     expect(bgSrc).toContain('chrome.tabs.onActivated.addListener');
     expect(bgSrc).toContain('browserTabActivated');
   });
-
 });
 
 describe('browser tab bar (sidepanel.css)', () => {
@@ -197,13 +206,14 @@ describe('CSP fallback basic picker', () => {
     expect(contentSrc).toContain('getBoundingClientRect()');
   });
 
-  test('content.js contains CSSOM iteration tolerating cross-origin sheets', () => {
+  test('content.js contains CSSOM iteration guarded against cross-origin sheets', () => {
     expect(contentSrc).toContain('document.styleSheets');
     expect(contentSrc).toContain('cssRules');
-    // Cross-origin sheets throw DOMException on cssRules access — the
-    // iteration swallows exactly that (typed catch), nothing broader.
-    expect(contentSrc).toContain('same-origin only');
-    expect(contentSrc).toContain('instanceof DOMException');
+    // Cross-origin stylesheets throw DOMException on cssRules access. The
+    // iteration must swallow exactly that (typed catch, not a bare catch {}
+    // — see the slop-scan philosophy in CLAUDE.md).
+    expect(contentSrc).toContain('(same-origin only)');
+    expect(contentSrc).toMatch(/catch \(e\) \{ if \(!\(e instanceof DOMException\)\) throw e; \}/);
   });
 
   test('content.js saves and restores outline on elements', () => {
@@ -260,6 +270,24 @@ describe('cleanup and screenshot buttons', () => {
     expect(html).toContain('quick-actions');
   });
 
+  test('cleanup button injects smart prompt into the live PTY (not just deterministic selectors)', () => {
+    // Cleanup pipes a prompt into the running claude PTY via
+    // gstackInjectToTerminal (the chat-queue POST to /sidebar-command was
+    // ripped in PR #1216 — the live REPL is the only execution surface).
+    const cleanupFn = js.slice(
+      js.indexOf('async function runCleanup('),
+      js.indexOf('async function runScreenshot('),
+    );
+    expect(cleanupFn).toContain('gstackInjectToTerminal');
+    expect(cleanupFn).toContain('cleanupPrompt');
+    // Should include both deterministic first pass AND agent snapshot analysis
+    expect(cleanupFn).toContain('cleanup --all');
+    expect(cleanupFn).toContain('snapshot -i');
+    // Should instruct claude to keep site branding
+    expect(cleanupFn).toContain('Keep the site');
+    expect(cleanupFn).toContain('header/masthead');
+  });
+
   test('sidepanel.js screenshot handler POSTs to /command with screenshot', () => {
     expect(js).toContain("command: 'screenshot'");
   });
@@ -408,9 +436,9 @@ describe('chat toolbar buttons disabled state', () => {
   });
 });
 
-// ─── No focus stealing (switchTab bringToFront) ─────────────────
+// ─── Focus stealing prevention ──────────────────────────────────
 
-describe('no focus stealing (switchTab bringToFront)', () => {
+describe('tab switching does not steal focus', () => {
   const serverSrc = fs.readFileSync(path.join(ROOT, 'src', 'server.ts'), 'utf-8');
   const bmSrc = fs.readFileSync(path.join(ROOT, 'src', 'browser-manager.ts'), 'utf-8');
 
@@ -438,6 +466,17 @@ describe('LLM-based cleanup (smart agent cleanup)', () => {
   const js = fs.readFileSync(path.join(ROOT, '..', 'extension', 'sidepanel.js'), 'utf-8');
   const wcSrc = fs.readFileSync(path.join(ROOT, 'src', 'write-commands.ts'), 'utf-8');
 
+  test('cleanup button does not bypass the agent with a direct /command POST', () => {
+    const cleanupFn = js.slice(
+      js.indexOf('async function runCleanup('),
+      js.indexOf('async function runScreenshot('),
+    );
+    // The smart cleanup goes through the claude PTY, never a raw
+    // deterministic /command fetch. (The PTY-injection wiring itself is
+    // pinned in sidebar-tabs.test.ts.)
+    expect(cleanupFn).not.toMatch(/fetch.*\/command['"]/);
+  });
+
   test('cleanup prompt includes deterministic first pass', () => {
     const cleanupFn = js.slice(
       js.indexOf('async function runCleanup('),
@@ -447,6 +486,64 @@ describe('LLM-based cleanup (smart agent cleanup)', () => {
     expect(cleanupFn).toContain('cleanup --all');
   });
 
+  test('cleanup prompt instructs agent to snapshot and analyze', () => {
+    const cleanupFn = js.slice(
+      js.indexOf('async function runCleanup('),
+      js.indexOf('async function runScreenshot('),
+    );
+    // Agent should take a snapshot to see what deterministic pass missed
+    expect(cleanupFn).toContain('snapshot -i');
+    // Agent should analyze what remains
+    expect(cleanupFn).toContain('identify any remaining');
+  });
+
+  test('cleanup prompt lists specific clutter categories for agent', () => {
+    const cleanupFn = js.slice(
+      js.indexOf('async function runCleanup('),
+      js.indexOf('async function runScreenshot('),
+    );
+    // Should guide the agent on what to look for
+    expect(cleanupFn).toContain('cookie/consent banners');
+    expect(cleanupFn).toContain('newsletter popups');
+    expect(cleanupFn).toContain('login walls');
+    expect(cleanupFn).toContain('video autoplay');
+    expect(cleanupFn).toContain('sidebar');
+    expect(cleanupFn).toContain('share');
+    expect(cleanupFn).toContain('floating chat');
+  });
+
+  test('cleanup prompt instructs agent to preserve site identity', () => {
+    const cleanupFn = js.slice(
+      js.indexOf('async function runCleanup('),
+      js.indexOf('async function runScreenshot('),
+    );
+    // Must keep the site looking like itself
+    expect(cleanupFn).toContain('Keep the site');
+    expect(cleanupFn).toContain('header/masthead');
+    expect(cleanupFn).toContain('headline');
+    expect(cleanupFn).toContain('article body');
+    expect(cleanupFn).toContain('byline');
+  });
+
+  test('cleanup prompt instructs agent to unlock scrolling', () => {
+    const cleanupFn = js.slice(
+      js.indexOf('async function runCleanup('),
+      js.indexOf('async function runScreenshot('),
+    );
+    expect(cleanupFn).toContain('unlock scrolling');
+    expect(cleanupFn).toContain('scroll-locked');
+  });
+
+  test('cleanup prompt instructs agent to use $B eval for removal', () => {
+    const cleanupFn = js.slice(
+      js.indexOf('async function runCleanup('),
+      js.indexOf('async function runScreenshot('),
+    );
+    // Agent should use $B eval to hide elements via JavaScript
+    expect(cleanupFn).toContain('$B eval');
+    expect(cleanupFn).toContain('hide each');
+  });
+
   test('cleanup removes loading state after short delay (agent is async)', () => {
     const cleanupFn = js.slice(
       js.indexOf('async function runCleanup('),
@@ -677,13 +774,16 @@ describe('sidebar arrow hint hide flow (4-step signal chain)', () => {
   test('step 1: sidepanel sends sidebarOpened message on connect', () => {
     expect(spSrc).toContain("{ type: 'sidebarOpened' }");
     // Should be in updateConnection, after setConnState('connected').
-    // Window is 1500 chars — the function grew bootstrap-global exports
-    // for sidepanel-terminal.js ahead of the sidebarOpened send.
+    // Window is generous: updateConnection also exposes the PTY bootstrap
+    // globals (gstackServerPort/gstackAuthToken) before the connected branch.
     const connectFn = spSrc.slice(
       spSrc.indexOf('function updateConnection('),
-      spSrc.indexOf('function updateConnection(') + 1500,
+      spSrc.indexOf('function updateConnection(') + 2500,
     );
-    expect(connectFn).toContain('sidebarOpened');
+    const connectedIdx = connectFn.indexOf("setConnState('connected')");
+    const openedIdx = connectFn.indexOf('sidebarOpened');
+    expect(connectedIdx).toBeGreaterThan(0);
+    expect(openedIdx).toBeGreaterThan(connectedIdx);
   });
 
   // Step 2: background.js accepts and relays sidebarOpened
@@ -798,6 +898,51 @@ describe('sidebar debug visibility when stuck', () => {
   });
 });
 
+describe('BROWSE_NO_AUTOSTART (sidebar headless prevention)', () => {
+  const cliSrc = fs.readFileSync(path.join(ROOT, 'src', 'cli.ts'), 'utf-8');
+  const termAgentSrc = fs.readFileSync(path.join(ROOT, 'src', 'terminal-agent.ts'), 'utf-8');
+
+  test('cli.ts checks BROWSE_NO_AUTOSTART before starting a new server', () => {
+    // ensureServer must check this env var BEFORE spawning a server.
+    // (Anchor on the open paren — both functions grew parameters.)
+    const ensureStart = cliSrc.indexOf('async function ensureServer(');
+    const ensureEnd = cliSrc.indexOf('\nasync function ', ensureStart + 1);
+    const ensureServerFn = cliSrc.slice(
+      ensureStart,
+      ensureEnd > ensureStart ? ensureEnd : undefined,
+    );
+    expect(ensureServerFn).toContain('BROWSE_NO_AUTOSTART');
+    expect(ensureServerFn).toContain('process.exit(1)');
+  });
+
+  test('cli.ts shows actionable error message when BROWSE_NO_AUTOSTART blocks', () => {
+    expect(cliSrc).toContain('/open-gstack-browser');
+    expect(cliSrc).toContain('BROWSE_NO_AUTOSTART is set');
+  });
+
+  test('terminal-agent.ts sets BROWSE_NO_AUTOSTART=1 for the claude PTY', () => {
+    // The PTY claude must reuse THIS headed server, never race to spawn
+    // its own. (sidebar-agent.ts, the original setter, was ripped in
+    // PR #1216 — the PTY agent inherited the same env contract.)
+    expect(termAgentSrc).toContain("BROWSE_NO_AUTOSTART: '1'");
+  });
+
+  test('terminal-agent.ts sets BROWSE_PORT for headed server reuse', () => {
+    expect(termAgentSrc).toContain('BROWSE_PORT');
+  });
+
+  test('BROWSE_NO_AUTOSTART check happens before lock acquisition', () => {
+    // The guard must be BEFORE the lock acquisition. If it's after,
+    // we'd acquire a lock and then exit, leaving a stale lock file.
+    const ensureServerStart = cliSrc.indexOf('async function ensureServer(');
+    const noAutoStart = cliSrc.indexOf('BROWSE_NO_AUTOSTART', ensureServerStart);
+    const lockAcquisition = cliSrc.indexOf('Acquire lock', ensureServerStart);
+    expect(noAutoStart).toBeGreaterThan(0);
+    expect(lockAcquisition).toBeGreaterThan(0);
+    expect(noAutoStart).toBeLessThan(lockAcquisition);
+  });
+});
+
 // ─── Idle timeout disabled in headed mode (server.ts) ───────────
 //
 // The original 'idle check skips in headed mode' string-grep test was deleted
@@ -806,6 +951,32 @@ describe('sidebar debug visibility when stuck', () => {
 // Behavioral coverage lives in browse/test/server-factory.test.ts under the
 // 'idle timer + onDisconnect dual-instance fix' describe block, which
 // exercises the headed/headless/tunnel branches of idleCheckTick directly.
+// The companion '/sidebar-command resets idle timer' test went with the
+// chat-queue rip (PR #1216) — /command and /batch reset the timer and are
+// covered by that factory suite.
+
+// ─── Shutdown kills the terminal-agent (server.ts) ──────────────
+
+describe('shutdown cleanup (server.ts)', () => {
+  const serverSrc = fs.readFileSync(path.join(ROOT, 'src', 'server.ts'), 'utf-8');
+
+  test('shutdown kills the terminal-agent via identity-based kill (no pkill)', () => {
+    // v1.44+ identity-based teardown: only the PID recorded by THIS
+    // daemon's agent is signaled. The pre-v1.44 `pkill -f terminal-agent`
+    // regex killed sibling gstack sessions on the same host (also pinned
+    // by browse/test/terminal-agent-pid-identity.test.ts).
+    const shutdownFn = serverSrc.slice(
+      serverSrc.indexOf('async function shutdown('),
+      serverSrc.indexOf('async function shutdown(') + 1200,
+    );
+    expect(shutdownFn).toContain('killAgentByRecord');
+    expect(shutdownFn).toContain('readAgentRecord');
+    // No pkill CALL — the word may appear in the explanatory comment, so
+    // match invocation shapes only. The repo-wide reintroduction tripwire
+    // is browse/test/terminal-agent-pid-identity.test.ts.
+    expect(shutdownFn).not.toMatch(/(?:spawnSync|execSync|\$)\(\s*['"`]pkill/);
+  });
+});
 
 // ─── Cookie button in sidebar footer ────────────────────────────
 

browse/test/sidepanel-patient-autoconnect.test.ts

@@ -12,7 +12,7 @@ import * as path from 'path';
 // explicit unrecoverable signals (401 auth invalid).
 
 const CLIENT_JS = path.resolve(
-  new URL(import.meta.url).pathname,
+  import.meta.path,
   '..',
   '..',
   '..',

browse/test/sidepanel-reattach.test.ts

@@ -13,7 +13,7 @@ import * as path from 'path';
 // in the e2e tier.
 
 const TERMINAL_JS = path.resolve(
-  new URL(import.meta.url).pathname, '..', '..', '..', 'extension', 'sidepanel-terminal.js',
+  import.meta.path, '..', '..', '..', 'extension', 'sidepanel-terminal.js',
 );
 
 describe('sidepanel re-attach loop (v1.44+ Commit 3)', () => {

browse/test/sidepanel-restart-dispose.test.ts

@@ -16,10 +16,10 @@ import * as path from 'path';
 // doesn't leak a 60s-zombie claude.
 
 const TERMINAL_JS = path.resolve(
-  new URL(import.meta.url).pathname, '..', '..', '..', 'extension', 'sidepanel-terminal.js',
+  import.meta.path, '..', '..', '..', 'extension', 'sidepanel-terminal.js',
 );
 const SIDEPANEL_JS = path.resolve(
-  new URL(import.meta.url).pathname, '..', '..', '..', 'extension', 'sidepanel.js',
+  import.meta.path, '..', '..', '..', 'extension', 'sidepanel.js',
 );
 
 describe('sidepanel-terminal: forceRestart via /pty-restart (v1.44+)', () => {

browse/test/snapshot.test.ts

@@ -31,9 +31,14 @@ beforeAll(async () => {
   await bm.launch();
 });
 
-afterAll(() => {
+afterAll(async () => {
   try { testServer.server.stop(); } catch {}
-  setTimeout(() => process.exit(0), 500);
+  // Close only this file's own browser — never process.exit(): bun test runs
+  // all files in one process, so a delayed exit kills the whole suite
+  // (see test/no-suicide-exit.test.ts). close() can hang when the browser
+  // already died, and its internal 5s timeout ties bun's 5s hook timeout —
+  // so race it at 3s and abandon; the child is reaped at process exit.
+  try { await Promise.race([bm?.close(), new Promise((resolve) => setTimeout(resolve, 3000))]); } catch {}
 });
 
 // ─── Snapshot Output ────────────────────────────────────────────

browse/test/terminal-agent-detach-reattach.test.ts

@@ -10,7 +10,7 @@ import * as path from 'path';
 // in the e2e tier; these static-grep tripwires defend the load-bearing
 // protocol + correctness properties.
 
-const AGENT_TS = path.resolve(new URL(import.meta.url).pathname, '..', '..', 'src', 'terminal-agent.ts');
+const AGENT_TS = path.resolve(import.meta.path, '..', '..', 'src', 'terminal-agent.ts');
 
 describe('terminal-agent detach + re-attach (v1.44+ Commit 3)', () => {
   test('1. PtySession carries ring buffer + alt-screen + detach state', () => {

browse/test/terminal-agent-integration.test.ts

@@ -227,6 +227,45 @@ describe('terminal-agent: PTY round-trip via real WebSocket (Cookie auth)', () =
     expect(resp.headers.get('sec-websocket-protocol')).toBe(`gstack-pty.${token}`);
   });
 
+  test('upgrade response contains exactly ONE Sec-WebSocket-Protocol header', async () => {
+    // RFC 6455: the server MUST select at most one subprotocol. Bun >= 1.3
+    // auto-echoes the first offered protocol in server.upgrade(), so a
+    // manual echo on top of that produced TWO Sec-WebSocket-Protocol
+    // headers — and strict clients (Chromium, python websockets) reject the
+    // handshake, leaving the sidebar terminal permanently disconnected.
+    //
+    // Headers.get() normalizes duplicates away, so this test handshakes
+    // over a raw socket and counts header lines in the response head.
+    const token = 'dup-proto-token-must-be-at-least-seventeen-chars';
+    await grantToken(token);
+
+    const head = await new Promise<string>((resolve, reject) => {
+      const req =
+        'GET /ws HTTP/1.1\r\n' +
+        `Host: 127.0.0.1:${agentPort}\r\n` +
+        'Connection: Upgrade\r\n' +
+        'Upgrade: websocket\r\n' +
+        'Sec-WebSocket-Version: 13\r\n' +
+        'Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==\r\n' +
+        `Sec-WebSocket-Protocol: gstack-pty.${token}\r\n` +
+        'Origin: chrome-extension://test-extension-id\r\n' +
+        '\r\n';
+      let buf = '';
+      const socket = require('net').connect(agentPort, '127.0.0.1', () => socket.write(req));
+      socket.setTimeout(5000, () => { socket.destroy(); reject(new Error('handshake timeout')); });
+      socket.on('data', (chunk: Buffer) => {
+        buf += chunk.toString('utf8');
+        const end = buf.indexOf('\r\n\r\n');
+        if (end !== -1) { socket.destroy(); resolve(buf.slice(0, end)); }
+      });
+      socket.on('error', reject);
+    });
+
+    expect(head).toContain('101');
+    const protoLines = head.split('\r\n').filter(l => l.toLowerCase().startsWith('sec-websocket-protocol:'));
+    expect(protoLines).toEqual([`Sec-WebSocket-Protocol: gstack-pty.${token}`]);
+  });
+
   test('Sec-WebSocket-Protocol auth: rejects unknown token even with valid Origin', async () => {
     const resp = await fetch(`http://127.0.0.1:${agentPort}/ws`, {
       headers: {

browse/test/terminal-agent-internal-handler.test.ts

@@ -12,7 +12,7 @@ import * as path from 'path';
 // (token grant/revoke behavior) already live in
 // browse/test/terminal-agent-integration.test.ts.
 
-const AGENT_TS = path.resolve(new URL(import.meta.url).pathname, '..', '..', 'src', 'terminal-agent.ts');
+const AGENT_TS = path.resolve(import.meta.path, '..', '..', 'src', 'terminal-agent.ts');
 
 describe('terminal-agent internalHandler refactor (v1.44+)', () => {
   test('1. internalHandler<T> exists with the documented signature', () => {

browse/test/terminal-agent-keepalive.test.ts

@@ -11,8 +11,8 @@ import * as path from 'path';
 // regressed by a refactor. These tests fail CI if either side stops sending
 // or stops accepting the protocol frames.
 
-const AGENT_TS = path.resolve(new URL(import.meta.url).pathname, '..', '..', 'src', 'terminal-agent.ts');
-const CLIENT_JS = path.resolve(new URL(import.meta.url).pathname, '..', '..', '..', 'extension', 'sidepanel-terminal.js');
+const AGENT_TS = path.resolve(import.meta.path, '..', '..', 'src', 'terminal-agent.ts');
+const CLIENT_JS = path.resolve(import.meta.path, '..', '..', '..', 'extension', 'sidepanel-terminal.js');
 
 describe('terminal-agent WS keepalive (v1.44+)', () => {
   test('1. agent has a KEEPALIVE_INTERVAL_MS env knob, default 25000', () => {

browse/test/terminal-agent-owner-watchdog.test.ts

@@ -0,0 +1,74 @@
+import { afterEach, describe, expect, test } from 'bun:test';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+const AGENT_SCRIPT = path.join(import.meta.dir, '../src/terminal-agent.ts');
+const spawned: any[] = [];
+const tempDirs: string[] = [];
+
+function isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function waitFor(predicate: () => boolean, timeoutMs = 5_000): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (predicate()) return true;
+    await Bun.sleep(25);
+  }
+  return predicate();
+}
+
+afterEach(() => {
+  for (const proc of spawned.splice(0)) {
+    try { proc.kill?.('SIGKILL'); } catch {}
+  }
+  for (const dir of tempDirs.splice(0)) {
+    try { fs.rmSync(dir, { recursive: true, force: true }); } catch {}
+  }
+});
+
+describe('terminal-agent owner lifecycle', () => {
+  test('exits after its owning browse server process exits', async () => {
+    const stateDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gstack-term-owner-'));
+    tempDirs.push(stateDir);
+    const stateFile = path.join(stateDir, 'browse.json');
+    fs.writeFileSync(stateFile, JSON.stringify({ token: 'test-token' }));
+
+    // process.execPath (the running bun) instead of `sleep`: coreutils are
+    // not guaranteed on a bare windows-latest runner, and this test is on the
+    // Windows CI curated list — the owner-orphan leak it pins is a Windows bug.
+    const owner = Bun.spawn(
+      [process.execPath, '-e', 'await Bun.sleep(30000)'],
+      { stdio: ['ignore', 'ignore', 'ignore'] },
+    );
+    spawned.push(owner);
+    const agent = Bun.spawn(['bun', 'run', AGENT_SCRIPT], {
+      env: {
+        ...process.env,
+        BROWSE_STATE_FILE: stateFile,
+        BROWSE_SERVER_PORT: '0',
+        BROWSE_OWNER_PID: String(owner.pid),
+        GSTACK_TERMINAL_OWNER_WATCHDOG_MS: '25',
+      },
+      stdio: ['ignore', 'ignore', 'ignore'],
+    });
+    spawned.push(agent);
+
+    expect(await waitFor(() => fs.existsSync(path.join(stateDir, 'terminal-agent-pid')))).toBe(true);
+    expect(isAlive(agent.pid)).toBe(true);
+
+    owner.kill('SIGTERM');
+    await owner.exited;
+
+    expect(await waitFor(() => !isAlive(agent.pid))).toBe(true);
+    expect(fs.existsSync(path.join(stateDir, 'terminal-agent-pid'))).toBe(false);
+    expect(fs.existsSync(path.join(stateDir, 'terminal-port'))).toBe(false);
+  });
+});

browse/test/terminal-agent-pid-identity.test.ts

@@ -30,7 +30,7 @@ import {
 // and browse/test/server-sanitize-surrogates.test.ts: read source files
 // directly, assert an invariant on their contents.
 
-const SRC_DIR = path.resolve(new URL(import.meta.url).pathname, '..', '..', 'src');
+const SRC_DIR = path.resolve(import.meta.path, '..', '..', 'src');
 
 function readAllSourceFiles(): Array<{ file: string; content: string }> {
   const out: Array<{ file: string; content: string }> = [];

browse/test/terminal-agent-session-routing.test.ts

@@ -13,7 +13,7 @@ import * as path from 'path';
 //   - {type:"start"} triggers spawn for eager UX after forceRestart
 //   - maybeSpawnPty helper is the single entry point for both spawn paths
 
-const AGENT_TS = path.resolve(new URL(import.meta.url).pathname, '..', '..', 'src', 'terminal-agent.ts');
+const AGENT_TS = path.resolve(import.meta.path, '..', '..', 'src', 'terminal-agent.ts');
 
 describe('terminal-agent session routing (v1.44+ Commit 2)', () => {
   test('1. validTokens is a Map binding token → sessionId', () => {

browse/test/terminal-agent-watchdog.test.ts

@@ -10,8 +10,8 @@ import * as path from 'path';
 // load-bearing properties: identity-based liveness check (not name match),
 // crash-loop guard, gated on ownsTerminalAgent, and cleared on shutdown.
 
-const SERVER_TS = path.resolve(new URL(import.meta.url).pathname, '..', '..', 'src', 'server.ts');
-const CONTROL_TS = path.resolve(new URL(import.meta.url).pathname, '..', '..', 'src', 'terminal-agent-control.ts');
+const SERVER_TS = path.resolve(import.meta.path, '..', '..', 'src', 'server.ts');
+const CONTROL_TS = path.resolve(import.meta.path, '..', '..', 'src', 'terminal-agent-control.ts');
 
 describe('terminal-agent watchdog (v1.44+)', () => {
   test('1. spawnTerminalAgent helper exists with PID return type', () => {
@@ -50,7 +50,13 @@ describe('terminal-agent watchdog (v1.44+)', () => {
   test('4. crash-loop guard with rolling window', () => {
     const src = fs.readFileSync(SERVER_TS, 'utf-8');
     const block = sliceBetween(src, '─── Terminal-Agent Watchdog', 'Factory-scoped validateAuth');
-    expect(block).toContain('RESPAWN_GUARD_WINDOW_MS = 60_000');
+    // The window MUST be derived from the tick, not a fixed 60_000. It was
+    // hardcoded to 60_000 against a 60_000ms tick, so at most ONE respawn
+    // could ever sit inside the window and the `>= RESPAWN_GUARD_MAX` trip
+    // was unreachable — a steady one-respawn-per-tick leak ran unbounded
+    // instead of self-limiting after 3. Pinning the literal is what let that
+    // ship, so pin the relationship instead.
+    expect(block).toMatch(/RESPAWN_GUARD_WINDOW_MS =[\s\S]{0,200}AGENT_WATCHDOG_TICK_MS/);
     expect(block).toContain('RESPAWN_GUARD_MAX = 3');
     expect(block).toContain('respawnHistory');
     expect(block).toContain('agentRespawnGuardTripped');
@@ -72,7 +78,7 @@ describe('terminal-agent watchdog (v1.44+)', () => {
 
   test('7. CLI cold-start path uses the same spawnTerminalAgent helper', () => {
     const cli = fs.readFileSync(
-      path.resolve(new URL(import.meta.url).pathname, '..', '..', 'src', 'cli.ts'),
+      path.resolve(import.meta.path, '..', '..', 'src', 'cli.ts'),
       'utf-8',
     );
     // Otherwise the CLI and watchdog could drift on spawn env/cwd, and

browse/test/terminal-agent.test.ts

@@ -129,21 +129,26 @@ describe('Source-level guard: terminal-agent', () => {
     expect(wsHandler).toContain('validTokens.has');
   });
 
-  test('Sec-WebSocket-Protocol auth: strips gstack-pty. prefix and echoes back', () => {
+  test('Sec-WebSocket-Protocol auth: strips gstack-pty. prefix, no manual echo', () => {
     const wsHandler = AGENT_SRC.slice(AGENT_SRC.indexOf("if (url.pathname === '/ws')"));
     // Browsers send `Sec-WebSocket-Protocol: gstack-pty.<token>`. The agent
-    // must strip the prefix before checking validTokens, AND echo the
-    // protocol back in the upgrade response — without the echo, the
-    // browser closes the connection immediately.
+    // must strip the prefix before checking validTokens. The protocol echo
+    // is Bun's job: Bun >= 1.3 auto-echoes the first offered protocol in the
+    // 101 response. A manual echo on top produced a DUPLICATE
+    // Sec-WebSocket-Protocol header, which strict clients (Chromium, python
+    // websockets) reject per RFC 6455 — the sidebar terminal could never
+    // connect. Pin the invariant: no manual echo in the upgrade call.
     expect(wsHandler).toContain("'gstack-pty.'");
-    expect(wsHandler).toContain('Sec-WebSocket-Protocol');
-    expect(wsHandler).toContain('acceptedProtocol');
+    expect(wsHandler).toContain('sec-websocket-protocol');
+    expect(wsHandler).not.toContain("headers: { 'Sec-WebSocket-Protocol'");
   });
 
   test('lazy spawn: claude PTY is spawned in message handler, not on upgrade', () => {
     // The whole point of lazy-spawn (codex finding #8) is that the WS
-    // upgrade itself does NOT call spawnClaude. Spawn happens on first
-    // message frame.
+    // upgrade itself does NOT spawn claude. Spawn happens on first
+    // message frame (binary input or the v1.44 explicit `start` frame),
+    // routed through the maybeSpawnPty helper, which is the only caller
+    // of spawnClaude.
     const upgradeBlock = AGENT_SRC.slice(
       AGENT_SRC.indexOf("if (url.pathname === '/ws')"),
       AGENT_SRC.indexOf("websocket: {"),
@@ -151,11 +156,27 @@ describe('Source-level guard: terminal-agent', () => {
     // v1.44 renamed spawnClaude -> maybeSpawnPty (explicit `start` frame +
     // lazy first-byte spawn share one helper). Pin was stale from then until
     // the free suite got a CI job.
+    expect(upgradeBlock).not.toContain('spawnClaude(');
     expect(upgradeBlock).not.toContain('maybeSpawnPty(');
     // Spawn must be invoked from the message handler (lazy on first byte).
+    // v1.44 routes both spawn triggers (explicit {type:"start"} text frame
+    // and the lazy binary-frame path) through the maybeSpawnPty helper.
     const messageHandler = AGENT_SRC.slice(AGENT_SRC.indexOf('message(ws, raw)'));
     expect(messageHandler).toContain('maybeSpawnPty(');
     expect(messageHandler).toContain('!session.spawned');
+    // The open() upgrade handler must not spawn — it only creates the
+    // (spawned: false) session record or re-attaches a detached one.
+    const openBlock = AGENT_SRC.slice(
+      AGENT_SRC.indexOf('open(ws)'),
+      AGENT_SRC.indexOf('message(ws, raw)'),
+    );
+    expect(openBlock).not.toContain('spawnClaude(');
+    expect(openBlock).not.toContain('maybeSpawnPty(');
+    // And the helper itself is where spawnClaude actually happens, gated
+    // on session.spawned so it stays a single-shot lazy spawn.
+    const helperBlock = AGENT_SRC.slice(AGENT_SRC.indexOf('function maybeSpawnPty'));
+    expect(helperBlock).toContain('spawnClaude(');
+    expect(helperBlock).toContain('if (session.spawned) return true;');
   });
 
   test('process.on uncaughtException + unhandledRejection handlers exist', () => {

browse/test/url-validation.test.ts

@@ -47,6 +47,28 @@ describe('validateNavigationUrl', () => {
     await expect(validateNavigationUrl('file://host.example.com/foo.html')).rejects.toThrow(/Unsupported file URL host/i);
   });
 
+  // The daemon opens its own first tab on about:blank, so blocking it meant a restarted
+  // daemon could never initialise — and `make-pdf setup`, whose Chromium smoke test is
+  // `browse newtab about:blank`, reported "Chromium failed to launch" on a healthy browser.
+  it('allows about:blank — the daemon opens its own first tab there', async () => {
+    await expect(validateNavigationUrl('about:blank')).resolves.toBe('about:blank');
+  });
+
+  it('allows about:blank regardless of case, since URL parsing normalises it', async () => {
+    await expect(validateNavigationUrl('ABOUT:BLANK')).resolves.toBe('about:blank');
+  });
+
+  // The allowance is about:blank EXACTLY, not the about: scheme. about:blank has no
+  // origin and loads nothing; the rest of the scheme is a real surface.
+  it('still blocks other about: URLs', async () => {
+    await expect(validateNavigationUrl('about:config')).rejects.toThrow(/scheme.*not allowed/i);
+    await expect(validateNavigationUrl('about:net-internals')).rejects.toThrow(/scheme.*not allowed/i);
+  });
+
+  it('blocks about:blankfoo — exact match, never a prefix test', async () => {
+    await expect(validateNavigationUrl('about:blankfoo')).rejects.toThrow(/scheme.*not allowed/i);
+  });
+
   it('blocks javascript: scheme', async () => {
     await expect(validateNavigationUrl('javascript:alert(1)')).rejects.toThrow(/scheme.*not allowed/i);
   });