Fix companion stop metadata and token permissions

A second adversarial review of the merged branch found that combining the
session-key auth with the feature work created real bugs the (vacuous) tests
missed:

- [Critical] GET /files/ (empty name) resolved to CONTENT_DIR and crashed the
  process with uncaught EISDIR — newly reachable because the query-stripping
  refactor turns /files/?key=... into /files/. Reject non-regular-file names.
- [High] --open opened a KEYLESS url, which the auth gate 403s — the headline
  feature landed on the error page. Open the keyed url.
- [High] Same-port restart regenerated the token (port persisted, token not), so
  the open tab's old cookie 403'd and never reconnected — contradicting the
  documented promise. Persist the token (BRAINSTORM_TOKEN_FILE / .last-token)
  alongside the port.
- [Medium] Token sat in world-readable server-info/server.log (0644 in /tmp).
  umask 077 in start-server.sh + mode 0600 on server-info/.last-token.
- [Medium] touchActivity() ran before the auth check, so unauthenticated requests
  defeated the idle timeout. Count activity only after authorization.
- [Low] COOKIE_NAME embedded the pre-fallback port; derive it from the actual
  bound port (also prevents a cross-server cookie-jar collision on fallback).

Tests added/strengthened (previously passed vacuously): /files/ no-crash; the
auto-open url carries the key and is reachable (200); restart reuses the same key
not just the port; unauthenticated requests don't reset the idle clock.
Full suite green (ws-protocol 32, helper 12, auth 13, server 29, lifecycle 8,
stop-server 4); restart smoke confirms same port+key and old URL -> 200.

.gitignore

@@ -1,6 +1,7 @@
 .worktrees/
 .private-journal/
 .claude/
+.superpowers/
 .DS_Store
 node_modules/
 inspo

docs/superpowers/plans/2026-06-09-visual-companion-issues.md

@@ -0,0 +1,352 @@
+# Visual Brainstorming Companion — Issue & Change Catalog
+
+**Date:** 2026-06-09
+**Status:** Analysis / triage. We are implementing these ourselves; the referenced
+community PRs are evidence and reference material, **not** code we intend to merge.
+
+## Purpose
+
+A single place that captures every open issue and PR touching the visual
+brainstorming companion (the local server in `skills/brainstorming/scripts/`),
+distilled to the underlying problem and the change we'd make. Each item is
+grounded against the current code, not the PR author's description.
+
+## Scope decisions (Jesse, 2026-06-09)
+
+- **Not vendoring Alpine.js.** PR #1639 (interactive mockups via a vendored
+  Alpine build) is **dropped**. See E3.
+- **E1 (terminal-vs-HTML hard gate) is a workshop item.** We'll design it
+  together; it is not specced here.
+- **E2 (storage location, #975/#977) is deferred** for now.
+- **Remote serving is a first-class scenario.** Superpowers is general-purpose;
+  users connect from remote (SSH tunnel, Tailscale, `--host 0.0.0.0`). The
+  security fix MUST protect those users, not just loopback. **Decision: a
+  per-session secret key**, not a Host allowlist. A Host allowlist only
+  defends the loopback browser-confused-deputy; a direct remote client just
+  sends the expected `Host`, so the allowlist is theater for remote exposure. A
+  secret key is the only thing that authenticates a client uniformly across
+  loopback, tunnel, and direct-remote, and it also defeats DNS rebinding. See A1.
+
+## Component map
+
+| File | Role |
+|------|------|
+| `skills/brainstorming/scripts/server.cjs` | Zero-dep HTTP + WebSocket server (RFC 6455 hand-rolled). Serves the newest screen, watches `content/`, records events to `state/events`. |
+| `skills/brainstorming/scripts/helper.js` | Injected into every page. WebSocket client, click capture, `window.brainstorm` API. |
+| `skills/brainstorming/scripts/frame-template.html` | Frame (header, theme CSS, status dot, indicator bar) wrapped around content fragments. |
+| `skills/brainstorming/scripts/start-server.sh` | Launch wrapper. Session dir, host/url-host, owner-PID resolution, platform backgrounding. |
+| `skills/brainstorming/scripts/stop-server.sh` | Kills the server by PID file, cleans `/tmp` sessions. |
+| `skills/brainstorming/visual-companion.md` | Operator guide the agent reads when it accepts the companion. |
+| `skills/brainstorming/SKILL.md` | Where the companion is offered and the per-question decision lives. |
+
+## Disposition summary
+
+| ID | Item | Source | Disposition |
+|----|------|--------|-------------|
+| A1 | Per-session secret key on `/`, `/files/*`, and WS (supersedes Host allowlist) | issues #1014, PRs #1110/#1553 | **Do** — chosen approach |
+| A2 | Host allowlist; browser WS Origin check | PRs #1110/#1553 | Host allowlist dropped; WS Origin check retained after auth for browser confused-deputy defense |
+| A3 | Crash on `null` / non-object WS payload | PR #1504 | Do |
+| A4 | Frame-length bound in `decodeFrame` | issue #1446 | Already fixed — verify/close |
+| B1 | Dotfile screens served as content (`._*.html`) | PR #950 | Do |
+| B2 | `stop-server.sh` kills reused/stale PID | PR #1703 | Do |
+| B3 | WS client reconnect backoff + status indicator | PR #856 | Do |
+| C1 | Idle timeout too short / not configurable; WS not closed on shutdown | issue #1237 (PR #1689) | Do |
+| C2 | Server death is invisible to user/agent | issue #1237 (residual) | Do |
+| D1 | Permanent opt-out of the companion | issue #892 | Deferred - not in PR #1720 |
+| D2 | Free-text feedback from the browser | issue #957 | Deferred - not in PR #1720 |
+| D3 | Auto-open the companion URL | PR #759 (#755) | Done in PR #1720 via `--open` |
+| D4 | Light/dark contrast helpers in the frame | PR #1683 | Deferred - not in PR #1720 |
+| E1 | Hard-gate terminal-vs-HTML per question | PR #1037 | **Workshop** |
+| E2 | Move session state out of the working tree | issue #975 (PR #977) | **Deferred** |
+| E3 | Vendor Alpine.js for interactive mockups | PR #1639 | **Dropped** |
+| E4 | Shell-lint warnings in start/stop scripts | PR #1677 | Opportunistic only |
+
+---
+
+## A. Server security hardening (`server.cjs`)
+
+### A1 — Per-session secret key (chosen approach)
+
+**Threat model.** Two assets: confidentiality of the served screen (`/`) and
+files (`/files/*`), and integrity of `state/events` — a WebSocket client with a
+truthy `choice` writes there (`server.cjs:243-246`), and the agent reads it next
+turn as the user's selection, i.e. **prompt injection into a live session with
+full tool access**. Reachers: with the default `127.0.0.1` bind, a malicious
+page in the user's browser (a confused deputy — runs attacker JS *and* can reach
+loopback); with a remote bind (`--host 0.0.0.0`, tailnet/LAN), any host that can
+route to the port, directly, with no same-origin policy in the way. Today
+`handleUpgrade` (`server.cjs:176`) checks only `Sec-WebSocket-Key`, and
+`handleRequest` (`server.cjs:138`) checks nothing — both are wide open.
+
+**Why a key, not a Host allowlist.** A Host allowlist only defends the
+loopback browser-deputy. A direct remote client just sends the expected `Host`
+and forges/omits `Origin`, so the allowlist is theater for exactly the remote
+case we must protect. A per-session secret authenticates the client uniformly
+across loopback, SSH tunnel, and direct-remote, and it also kills DNS rebinding
+(the rebound page neither knows the key nor receives the host-scoped cookie).
+So the key **supersedes** A1/A2's Host allowlist entirely — no `BRAINSTORM_ALLOWED_HOSTS`.
+
+**Design.** Random token (`crypto.randomBytes(32)` hex), generated in
+`server.cjs` at startup (overridable via `BRAINSTORM_TOKEN` for deterministic
+tests):
+
+1. **URL carries it** as `?key=<token>`. The server already builds `url` in its
+   `server-started` JSON (`server.cjs:351`) and writes it to `state/server-info`
+   — appending `?key=` there means `start-server.sh` (greps and prints that
+   JSON) and the skill (hands the user that URL) need **no change**.
+2. **Cookie bootstrap.** A valid `?key` on `/` sets
+   `brainstorm-key-<port>=<token>; HttpOnly; SameSite=Strict; Path=/`. The
+   browser then auto-attaches it to same-origin subresources (`/files/*`) and
+   the WebSocket handshake, so the agent can write any URL style and it works,
+   and `helper.js` needs no change. Cookie name is **per-port** to avoid the
+   Jupyter multi-server collision (cookies aren't port-scoped).
+   `SameSite=Strict` is safe for CDN/Unsplash content — that cookie is host-
+   scoped, so outbound CDN requests never carry it; SameSite only governs
+   requests back to our origin, which are all same-site.
+3. **Auth gate** = valid `?key` **OR** valid cookie (compared with
+   `crypto.timingSafeEqual`) on `/`, `/files/*`, and the WS upgrade. Missing/bad
+   key → friendly **403 HTML page** ("this page needs the full URL your coding
+   agent gave you, including `?key=…`" — generic "coding agent", not "Claude",
+   since this ships on Codex/Gemini/Copilot too). WS upgrade → destroy socket.
+
+The query token is the source of truth; the cookie is a convenience that never
+bears initial-auth load.
+
+**Blast radius.** `server.cjs` (all logic). `helper.js` optional one-liner
+(append `?key=` from `location.search` to the WS URL as a cookie-blocked
+fallback). `start-server.sh` none. `visual-companion.md` doc note (URL now has
+`?key=`; don't strip it). Tests updated to pass the token.
+
+### A2 — Host allowlist dropped; browser WS Origin retained
+
+Subsumed by A1. The secret key closes the WS-injection vector (#1014), the
+HTTP/WS DNS-rebinding read vector (PR #1553), and the cross-origin WS vector
+(PR #1110) in one mechanism, and unlike an allowlist it actually protects the
+remote-bind case. No `BRAINSTORM_ALLOWED_HOSTS` and no Host allowlist. The final
+implementation still checks browser WebSocket `Origin` after session auth so a
+cross-origin localhost tab cannot ride the companion cookie.
+
+### A3 — Server crashes on `null` / primitive WS payload
+
+**Problem.** `handleMessage` (`server.cjs:233`) does `JSON.parse(text)` then
+`if (event.choice)` at `server.cjs:243`. A client that sends the 4-byte text
+frame `null` yields `event === null`, and `null.choice` throws. The throw is
+**not** caught — `handleMessage` is called from the `socket.on('data')` handler
+(`server.cjs:207`) outside the `try/catch`, which only wraps `decodeFrame`. The
+result is an uncaught exception and process exit. Any local client can kill the
+server.
+
+**Change.** Guard the access: `if (event && event.choice)`. Minimal and exact —
+`JSON.parse` can't produce `undefined`, and primitives return `undefined` for
+`.choice` without throwing, so only `null` is the live hazard. (Avoid the
+broader fixes — a top-level `try/catch` or `process.on('uncaughtException')`
+would mask other bugs.)
+
+### A4 — Frame-length bound in `decodeFrame` (adjacent)
+
+Referenced by PR #1504 as #1446. The current code **already** bounds extended
+frame lengths: `MAX_FRAME_PAYLOAD_BYTES = 10MB` (`server.cjs:10`) is enforced at
+`server.cjs:58-67` before any `Buffer.alloc`. Action: verify #1446 against
+current `dev` and close if already resolved, rather than re-implementing.
+
+---
+
+## B. Server robustness / correctness
+
+### B1 — macOS resource-fork dotfiles served as screen content
+
+**Problem.** The newest-screen selector filters on `f.endsWith('.html')` only
+(`server.cjs:127-128`). On macOS/ExFAT, `._screen.html` resource-fork files pass
+that filter and, being written alongside the real file, can sort newest — so the
+browser gets binary metadata instead of the mockup. Four read sites share the
+weak filter: `getNewestScreen` (`server.cjs:127`), `knownFiles` init
+(`server.cjs:279`), the `fs.watch` handler (`server.cjs:286`), and the `/files/`
+endpoint (`server.cjs:154-156`).
+
+**Change.** Reject dotfiles (`!f.startsWith('.')`) at all four sites. Covers
+`._*`, `.DS_Store`, etc.
+
+### B2 — `stop-server.sh` can kill a reused PID
+
+**Problem.** `stop-server.sh` reads the PID from `state/server.pid`
+(`stop-server.sh:20`) and `kill`s it (`:23`, escalating to `-9` at `:35`)
+without confirming the PID still belongs to our server. After a reboot or PID
+wraparound the file can point at an unrelated process, which we'd then SIGKILL.
+
+**Change.** Before signalling, verify ownership — the PID's command is `node`
+running our `server.cjs`, ideally matching this session. If ownership can't be
+proven, fail closed (report `stale_pid`, don't kill). Keep the existing
+`stopped` / `not_running` outputs for the real cases.
+
+### B3 — WebSocket client: silent reconnect, stale "Connected"
+
+**Problem.** `helper.js` reconnects on a fixed 1s timer (`helper.js:21-23`),
+has no `onerror` handler, never nulls `ws` on close, and never clears a pending
+reconnect timer. The frame's status element is hardcoded to "Connected" with the
+dot pinned to `var(--success)` (`frame-template.html:77,200`). When the laptop
+sleeps or the server restarts, the page shows "Connected" over a dead socket and
+queues events with no feedback.
+
+**Change.**
+- `helper.js`: exponential backoff (500ms → ×2 → cap 30s, reset on open);
+  `onerror` delegating to `onclose`; `ws = null` on close; `clearTimeout` before
+  reconnecting.
+- `frame-template.html`: drive the status dot from a `--status-color` custom
+  property so JS can switch Connected (green) / Reconnecting (yellow) /
+  Disconnected (red).
+
+---
+
+## C. Lifecycle / timeout (issue #1237)
+
+### C1 — Idle timeout too short, not configurable, WS keeps process alive
+
+**Problem.** `IDLE_TIMEOUT_MS` is hardcoded to 30 minutes (`server.cjs:258`),
+enforced by the 60s lifecycle check (`server.cjs:329-332`). A single brainstorm
+question can sit longer than 30 min while the user thinks or steps away, so the
+server dies mid-session. Separately, `shutdown()` (`server.cjs:310-321`) calls
+`server.close()` but never closes the upgraded sockets in `clients`
+(`server.cjs:174`), so an open browser connection can keep the Node process
+alive past shutdown.
+
+**Change.**
+- Raise the default to 4 hours and make it configurable:
+  `--idle-timeout-minutes` in `start-server.sh` → an env var → `IDLE_TIMEOUT_MS`,
+  with validation against Node timer overflow.
+- Expose the effective timeout in the startup JSON / `state/server-info`.
+- In `shutdown()`, close every socket in `clients` so the process actually
+  exits.
+
+### C2 — Server death is invisible
+
+**Problem.** When the server exits it writes `state/server-stopped` and removes
+`state/server-info` (`server.cjs:312-317`), and the skill is *told* to check
+those files (`visual-companion.md:108`) — but it's soft guidance the model skips,
+and the browser just shows a generic "can't be reached." The user diagnoses it
+manually; the agent keeps referring to a dead URL.
+
+**Change (two parts, independent of C1):**
+- **Browser-facing tombstone.** Leave something at the last-served URL that says
+  "this companion expired — ask Claude to restart it" instead of a connection
+  error. Options to weigh: `helper.js` rendering a banner when the socket stays
+  down past backoff (works only while the page is loaded), vs. a more involved
+  approach that keeps a minimal responder alive to serve a tombstone page.
+- **Harder skill check.** Tighten `visual-companion.md` / `SKILL.md` so
+  "check `server-info`/`server-stopped` before referring to the URL or pushing a
+  screen" is a required step, not a note. Keep it lightweight — possibly a
+  one-line helper the agent always runs.
+
+---
+
+## D. Features
+
+### D1 — Permanent opt-out of the visual companion (issue #892)
+
+**Problem.** The companion is offered as its own message every session
+(`SKILL.md:25,151-152`). A user who never wants it pays that round-trip — and
+HTML generation — every time. There's no way to say "never offer this."
+
+**Change.** Before the offer step, the skill checks a user-level setting and
+skips the offer entirely when opt-out is set.
+
+**Design choice open.** Mechanism isn't settled:
+- Env var (e.g. `SUPERPOWERS_VISUAL_COMPANION=off`) the skill is told to read —
+  simplest, matches what the issue asks for, lives in `.zshrc`.
+- A plugin-settings file (`.claude/superpowers.local.md` frontmatter) — more
+  structured, per-project capable, but heavier and project-scoped.
+- Reliability caveat from the issue: a separate "no-companion" skill competes on
+  trigger words and isn't reliable — rejected.
+
+Pick the mechanism, then it's a small `SKILL.md` change plus a documented knob.
+
+### D2 — Free-text feedback from the browser (issue #957)
+
+**Problem.** The client only captures clicks on `[data-choice]`
+(`helper.js:36-62`). A user who wants to annotate a mockup ("wrong shade of
+blue") has to switch to the terminal, breaking the visual flow.
+
+**Change.** Add a feedback `<textarea>` whose submit emits
+`{"type":"feedback","text":...,"timestamp":...}` via the existing
+`window.brainstorm.send` path (`helper.js:82-85`).
+
+**Cross-cutting — server change required.** `handleMessage` only persists events
+when `event.choice` is truthy (`server.cjs:243`). A `feedback` event has no
+`choice`, so today it would be logged but **never written to `state/events`**,
+and the agent wouldn't see it. The persistence condition must also accept
+`feedback` events. Document the new event shape in `visual-companion.md`
+(Browser Events Format, `:247-259`). Decide the submit trigger (button vs blur
+vs both) and where the textarea renders (frame-level vs opt-in per screen).
+
+### D3 — Auto-open the companion URL (PR #759, issue #755)
+
+**Problem.** `start-server.sh` only prints the URL; the user opens it manually.
+In WSL2 especially, people expect the browser to open.
+
+**Change.** Best-effort opener after the `server-started` JSON is parsed:
+Windows/WSL → `rundll32.exe url.dll,FileProtocolHandler <url>`, macOS → `open`,
+Linux → `xdg-open` only when `DISPLAY`/`WAYLAND_DISPLAY` is set. Swallow
+failures, never block startup, keep echoing the URL. Document in
+`visual-companion.md`. (Consider an opt-out for headless/remote runs where
+popping a browser is wrong — ties into D1's config mechanism.)
+
+### D4 — Light/dark contrast helpers (PR #1683)
+
+**Problem.** Content fragments are wrapped in the OS-aware frame
+(`frame-template.html`). In dark mode, quick mockups often use white inline
+backgrounds while inheriting low-contrast frame text, making cards/panels hard
+to read.
+
+**Change.** Add `.light-surface` / `.dark-surface` helper classes plus a
+conservative fallback for common inline light backgrounds, and document them in
+`visual-companion.md`'s CSS reference. Pure CSS in `frame-template.html`.
+
+---
+
+## E. Workshop / deferred / dropped
+
+### E1 — Hard-gate terminal-vs-HTML per question (PR #1037) — WORKSHOP
+
+The soft guidance already exists: "decide per-question," with browser-vs-terminal
+tests in `SKILL.md:156-161` and `visual-companion.md:5-25`. The complaint is that
+the model renders HTML for purely textual content (A/B lists, clarifying
+questions), wasting tokens and a turn. PR #1037 wraps the decision in a
+`<HARD-GATE>`. **Per Jesse, we'll workshop the wording/mechanism together** —
+this is behavior-shaping skill content and not specced here.
+
+### E2 — Move session state out of the working tree (issue #975 / PR #977) — DEFERRED
+
+Today `--project-dir` writes session state to `<project>/.superpowers/brainstorm/`
+(`start-server.sh:80-84`) and the skill tells the user to gitignore it
+(`visual-companion.md:58`). The ask is a `--state-dir` / `SUPERPOWERS_STATE_DIR`
+default outside the repo (XDG), keeping `--project-dir` as an alias.
+**Deferred by Jesse for now.** Captured so it isn't lost.
+
+### E3 — Vendor Alpine.js for interactive mockups (PR #1639) — DROPPED
+
+Adds a vendored Alpine build so mockups can be interactive (tabs, accordions,
+forms) without hand-rolled JS. **Dropped per Jesse** — we are not taking on a
+vendored third-party dependency in the companion runtime. The underlying need
+(interactive mockups) is not being pursued via this route.
+
+### E4 — Shell-lint warnings (PR #1677) — OPPORTUNISTIC
+
+SC2034 (and friends) in `start-server.sh` / `stop-server.sh`. Trivial; fold into
+B2/C1/D3 when we're already editing those scripts rather than as its own change.
+
+---
+
+## Suggested grouping for implementation
+
+These cluster into a few coherent passes (each independently testable against
+`tests/brainstorm-server/`):
+
+1. **Security pass** (IN PROGRESS, branch `brainstorm-companion-session-key`) —
+   A1 per-session key (supersedes A2) + A3 null-crash guard. Verify/close A4.
+   *Highest priority.*
+2. **Lifecycle pass** — C1 + C2 together (both touch `shutdown()` and the
+   server-death story).
+3. **Robustness pass** — B1, B2, B3 (independent, small).
+4. **Deferred feature pass** - D1, D2, D4 are not part of PR #1720. D3 is
+   shipped through the `--open` flow.
+
+E1 is a separate workshop session. E2/E3 are out of scope for this round.

docs/superpowers/plans/2026-06-10-visual-companion-auth-hardening.md

@@ -0,0 +1,785 @@
+# Visual Companion Auth Hardening Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Harden the brainstorming visual companion auth and reconnect flow while preserving trusted same-origin screen JavaScript and future vendored UI libraries.
+
+**Architecture:** Keyed root loads become a bootstrap step that sets the cookie, stores the key in tab-scoped `sessionStorage`, and navigates to a bare `/` screen URL. WebSockets require valid auth plus browser same-origin `Origin`, while `/files/*` uses realpath containment to prevent content-directory escapes.
+
+**Tech Stack:** Node.js built-ins (`http`, `fs`, `path`, `crypto`), zero runtime dependencies, existing `ws` test dependency, Bash start/stop scripts, repo shell lint script.
+
+**Important:** Do not commit during execution unless Drew explicitly asks. This repository's instructions override the generic plan template's commit cadence.
+
+---
+
+## File Map
+
+- Modify: `skills/brainstorming/scripts/server.cjs`
+  - Add bootstrap response.
+  - Add shared security headers.
+  - Add WebSocket Origin validation.
+  - Add `/files/*` realpath containment.
+- Modify: `skills/brainstorming/scripts/helper.js`
+  - Read the stored session key and append it to the WebSocket URL.
+- Modify: `tests/brainstorm-server/auth.test.js`
+  - Add bootstrap, header, same-origin WS, cross-origin WS, and cookie/file auth regressions.
+- Modify: `tests/brainstorm-server/helper.test.js`
+  - Add mocked-browser coverage for sessionStorage-backed WS URLs.
+- Modify: `tests/brainstorm-server/server.test.js`
+  - Add symlink containment regression for `/files/*`.
+- Modify: `tests/brainstorm-server/lifecycle.test.js`
+  - Make the start-server timeout flag test force background mode.
+  - Add restart reconnect credential coverage if it fits the existing lifecycle helper.
+- Modify: `skills/brainstorming/scripts/start-server.sh`
+  - Fix shell lint.
+- Modify: `skills/brainstorming/scripts/stop-server.sh`
+  - Fix shell lint.
+- Modify: `.gitignore`
+  - Add `.superpowers/`.
+- Optional docs update: `skills/brainstorming/visual-companion.md`
+  - Mention bootstrap URL stripping and trusted same-origin screen JS if the code behavior changes need operator-facing explanation.
+
+## Task 1: Bootstrap Keyed Root Loads
+
+**Files:**
+- Modify: `tests/brainstorm-server/auth.test.js`
+- Modify: `skills/brainstorming/scripts/server.cjs`
+
+- [ ] **Step 1: Add RED tests for bootstrap behavior**
+
+In `tests/brainstorm-server/auth.test.js`, add tests after the existing valid-key root test:
+
+```js
+    await test('GET / with valid query returns bootstrap instead of screen content', async () => {
+      const res = await get('/', { key: TOKEN });
+      assert.strictEqual(res.status, 200);
+      assert(res.body.includes('sessionStorage'), 'bootstrap should store the session key in tab storage');
+      assert(res.body.includes('location.replace'), 'bootstrap should navigate to the bare root URL');
+      assert(!res.body.includes('Secret screen'), 'bootstrap must not serve screen HTML at the keyed URL');
+    });
+
+    await test('GET / with valid cookie serves the screen after bootstrap', async () => {
+      const res = await get('/', { cookie: `${COOKIE_NAME}=${TOKEN}` });
+      assert.strictEqual(res.status, 200);
+      assert(res.body.includes('Secret screen'), 'cookie-authenticated bare root should serve the screen');
+      assert(!res.body.includes('sessionStorage'), 'bare screen response should not be the bootstrap page');
+    });
+```
+
+Keep the existing cookie test if present; merge assertions rather than duplicating the same test name.
+
+- [ ] **Step 2: Verify RED**
+
+Run:
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
+node auth.test.js
+```
+
+Expected: the new bootstrap test fails because current `GET /?key=...` serves `Secret screen` directly and does not include the bootstrap `sessionStorage`/`location.replace` code.
+
+- [ ] **Step 3: Implement minimal bootstrap response**
+
+In `skills/brainstorming/scripts/server.cjs`, add a helper near the page constants:
+
+```js
+function bootstrapPage(key) {
+  const jsonKey = JSON.stringify(String(key));
+  return `<!DOCTYPE html>
+<html>
+<head><meta charset="utf-8"><title>Opening Brainstorm Companion</title></head>
+<body>
+<script>
+sessionStorage.setItem('brainstorm-session-key', ${jsonKey});
+location.replace('/');
+</script>
+</body>
+</html>`;
+}
+```
+
+Then in `handleRequest`, after authorization and cookie setting but before serving screen HTML, detect a valid query key on root:
+
+```js
+function queryKey(url) {
+  const q = url.indexOf('?');
+  if (q < 0) return null;
+  return new URLSearchParams(url.slice(q + 1)).get('key');
+}
+```
+
+Use it in `handleRequest`:
+
+```js
+  const pathname = pathnameOf(req.url);
+  const keyFromQuery = queryKey(req.url);
+  if (req.method === 'GET' && pathname === '/' && keyFromQuery && timingSafeEqualStr(keyFromQuery, TOKEN)) {
+    res.writeHead(200, securityHeaders({ 'Content-Type': 'text/html; charset=utf-8' }));
+    res.end(bootstrapPage(keyFromQuery));
+    return;
+  }
+```
+
+This assumes Task 4 will introduce `securityHeaders`. If implementing Task 1 first, temporarily use:
+
+```js
+    res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+```
+
+and replace it in Task 4.
+
+- [ ] **Step 4: Verify GREEN**
+
+Run:
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
+node auth.test.js
+```
+
+Expected: all auth tests pass, including the new bootstrap tests.
+
+## Task 2: WebSocket Origin Enforcement
+
+**Files:**
+- Modify: `tests/brainstorm-server/auth.test.js`
+- Modify: `skills/brainstorming/scripts/server.cjs`
+
+- [ ] **Step 1: Add RED tests for same-origin and cross-origin WS**
+
+In `tests/brainstorm-server/auth.test.js`, extend `wsConnect` to accept an `origin` option:
+
+```js
+function wsConnect({ key, cookie, origin } = {}) {
+  const url = `ws://localhost:${TEST_PORT}/` + (key !== undefined ? `?key=${key}` : '');
+  const headers = {};
+  if (cookie) headers['Cookie'] = cookie;
+  if (origin) headers['Origin'] = origin;
+  const ws = new WebSocket(url, Object.keys(headers).length ? { headers } : {});
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (outcome) => { if (!settled) { settled = true; resolve({ outcome, ws }); } };
+    ws.on('open', () => done('opened'));
+    ws.on('error', () => done('rejected'));
+    ws.on('close', () => done('rejected'));
+    setTimeout(() => done('rejected'), 1500);
+  });
+}
+```
+
+Then add:
+
+```js
+    await test('WS upgrade with valid cookie and same-origin Origin opens', async () => {
+      const { outcome, ws } = await wsConnect({
+        cookie: `${COOKIE_NAME}=${TOKEN}`,
+        origin: `http://localhost:${TEST_PORT}`
+      });
+      ws.close();
+      assert.strictEqual(outcome, 'opened');
+    });
+
+    await test('WS upgrade with valid cookie but cross-origin Origin is rejected', async () => {
+      const eventsFile = path.join(TEST_DIR, 'state', 'events');
+      if (fs.existsSync(eventsFile)) fs.unlinkSync(eventsFile);
+
+      const { outcome, ws } = await wsConnect({
+        cookie: `${COOKIE_NAME}=${TOKEN}`,
+        origin: 'http://localhost:9999'
+      });
+      if (outcome === 'opened') {
+        ws.send(JSON.stringify({ type: 'choice', choice: 'attacker-injected', text: 'local attacker probe' }));
+        await sleep(300);
+      }
+      ws.close();
+
+      assert.strictEqual(outcome, 'rejected', 'cross-origin browser WS must not open even with cookie');
+      assert(!fs.existsSync(eventsFile), 'cross-origin WS must not write state/events');
+    });
+```
+
+- [ ] **Step 2: Verify RED**
+
+Run:
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
+node auth.test.js
+```
+
+Expected: cross-origin cookie WS test fails because current server accepts any cookie-authenticated WS regardless of Origin.
+
+- [ ] **Step 3: Implement Origin check**
+
+In `skills/brainstorming/scripts/server.cjs`, add:
+
+```js
+function isAllowedWebSocketOrigin(req) {
+  const origin = req.headers.origin;
+  if (!origin) return true; // non-browser clients still need the session key
+  const host = req.headers.host;
+  if (!host) return false;
+  return origin === 'http://' + host;
+}
+```
+
+Then update `handleUpgrade`:
+
+```js
+function handleUpgrade(req, socket) {
+  if (!isAuthorized(req) || !isAllowedWebSocketOrigin(req)) { socket.destroy(); return; }
+```
+
+- [ ] **Step 4: Verify GREEN**
+
+Run:
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
+node auth.test.js
+```
+
+Expected: auth tests pass; cross-origin WS is rejected; same-origin and direct key WS still open.
+
+## Task 3: Helper Uses Stored Key For Reconnect
+
+**Files:**
+- Modify: `tests/brainstorm-server/helper.test.js`
+- Modify: `skills/brainstorming/scripts/helper.js`
+
+- [ ] **Step 1: Add RED test for WebSocket URL key**
+
+In `tests/brainstorm-server/helper.test.js`, add a mocked-browser test near the reconnect state-machine tests:
+
+```js
+test('uses sessionStorage key in the WebSocket URL when present', () => {
+  const e = makeEnv();
+  e.state.sessionKey = 'stored-key-abc';
+  e.boot();
+  assert.strictEqual(e.sockets[0].url, 'ws://localhost:7777/?key=stored-key-abc');
+});
+```
+
+Update `makeEnv()` so the returned object exposes `sockets`, and the mock window includes sessionStorage:
+
+```js
+    window: {
+      location: { host: 'localhost:7777', reload() { state.reloads++; } },
+      sessionStorage: { getItem: (key) => key === 'brainstorm-session-key' ? state.sessionKey : null }
+    },
+```
+
+Also add a fallback test:
+
+```js
+test('uses cookie-only WebSocket URL when no sessionStorage key is present', () => {
+  const e = makeEnv();
+  e.state.sessionKey = null;
+  e.boot();
+  assert.strictEqual(e.sockets[0].url, 'ws://localhost:7777');
+});
+```
+
+- [ ] **Step 2: Verify RED**
+
+Run:
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
+node helper.test.js
+```
+
+Expected: stored-key test fails because current helper uses `ws://localhost:7777`.
+
+- [ ] **Step 3: Implement stored-key WS URL**
+
+In `skills/brainstorming/scripts/helper.js`, replace:
+
+```js
+  const WS_URL = 'ws://' + window.location.host;
+```
+
+with:
+
+```js
+  function websocketUrl() {
+    let key = null;
+    try { key = window.sessionStorage && window.sessionStorage.getItem('brainstorm-session-key'); } catch (e) {}
+    return 'ws://' + window.location.host + (key ? '/?key=' + encodeURIComponent(key) : '');
+  }
+```
+
+Then replace:
+
+```js
+    ws = new WebSocket(WS_URL);
+```
+
+with:
+
+```js
+    ws = new WebSocket(websocketUrl());
+```
+
+- [ ] **Step 4: Verify GREEN**
+
+Run:
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
+node helper.test.js
+```
+
+Expected: helper tests pass.
+
+## Task 4: Security Headers
+
+**Files:**
+- Modify: `tests/brainstorm-server/auth.test.js`
+- Modify: `skills/brainstorming/scripts/server.cjs`
+
+- [ ] **Step 1: Add RED header tests**
+
+In `tests/brainstorm-server/auth.test.js`, add:
+
+```js
+    await test('HTML responses include leak-reduction and anti-framing headers', async () => {
+      const res = await get('/', { key: TOKEN });
+      assert.strictEqual(res.headers['referrer-policy'], 'no-referrer');
+      assert.strictEqual(res.headers['cache-control'], 'no-store');
+      assert.strictEqual(res.headers['x-frame-options'], 'DENY');
+      assert.strictEqual(res.headers['content-security-policy'], "frame-ancestors 'none'");
+      assert.strictEqual(res.headers['cross-origin-resource-policy'], 'same-origin');
+    });
+
+    await test('403 responses include leak-reduction and anti-framing headers', async () => {
+      const res = await get('/');
+      assert.strictEqual(res.status, 403);
+      assert.strictEqual(res.headers['referrer-policy'], 'no-referrer');
+      assert.strictEqual(res.headers['cache-control'], 'no-store');
+      assert.strictEqual(res.headers['x-frame-options'], 'DENY');
+      assert.strictEqual(res.headers['content-security-policy'], "frame-ancestors 'none'");
+      assert.strictEqual(res.headers['cross-origin-resource-policy'], 'same-origin');
+    });
+```
+
+- [ ] **Step 2: Verify RED**
+
+Run:
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
+node auth.test.js
+```
+
+Expected: header tests fail because current responses do not include these headers.
+
+- [ ] **Step 3: Implement shared header helper**
+
+In `skills/brainstorming/scripts/server.cjs`, add:
+
+```js
+function securityHeaders(headers = {}) {
+  return {
+    'Referrer-Policy': 'no-referrer',
+    'Cache-Control': 'no-store',
+    'X-Frame-Options': 'DENY',
+    'Content-Security-Policy': "frame-ancestors 'none'",
+    'Cross-Origin-Resource-Policy': 'same-origin',
+    ...headers
+  };
+}
+```
+
+Update response writes in `handleRequest`:
+
+```js
+res.writeHead(403, securityHeaders({ 'Content-Type': 'text/html; charset=utf-8' }));
+```
+
+```js
+res.writeHead(200, securityHeaders({ 'Content-Type': 'text/html; charset=utf-8' }));
+```
+
+```js
+res.writeHead(200, securityHeaders({ 'Content-Type': contentType }));
+```
+
+For 404s:
+
+```js
+res.writeHead(404, securityHeaders());
+```
+
+- [ ] **Step 4: Verify GREEN**
+
+Run:
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
+node auth.test.js
+```
+
+Expected: auth tests pass and header assertions are green.
+
+## Task 5: `/files/*` Realpath Containment
+
+**Files:**
+- Modify: `tests/brainstorm-server/server.test.js`
+- Modify: `skills/brainstorming/scripts/server.cjs`
+
+- [ ] **Step 1: Add RED symlink escape test**
+
+In `tests/brainstorm-server/server.test.js`, after the `/files/` empty-name test, add:
+
+```js
+    await test('does not serve symlinks that escape content dir via /files/', async () => {
+      const target = path.join(STATE_DIR, 'server-info');
+      const link = path.join(CONTENT_DIR, 'linked-server-info.txt');
+      try { fs.unlinkSync(link); } catch (e) {}
+      fs.symlinkSync(target, link);
+
+      const res = await fetch(`http://localhost:${TEST_PORT}/files/linked-server-info.txt`);
+      assert.strictEqual(res.status, 404, 'symlink to state/server-info must not be served');
+      assert(!res.body.includes('server-started'), 'response must not include server-info body');
+    });
+```
+
+- [ ] **Step 2: Verify RED**
+
+Run:
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
+node server.test.js
+```
+
+Expected: symlink test fails because current `/files/*` follows symlinks and serves `server-info`.
+
+- [ ] **Step 3: Implement containment helper**
+
+In `skills/brainstorming/scripts/server.cjs`, add:
+
+```js
+function isRegularFileInsideContentDir(filePath) {
+  let stat, realContentDir, realFilePath;
+  try {
+    stat = fs.lstatSync(filePath);
+    if (stat.isSymbolicLink()) return false;
+    if (!stat.isFile()) return false;
+    realContentDir = fs.realpathSync(CONTENT_DIR);
+    realFilePath = fs.realpathSync(filePath);
+  } catch (e) {
+    return false;
+  }
+  return realFilePath.startsWith(realContentDir + path.sep);
+}
+```
+
+Replace the `/files/*` guard with:
+
+```js
+    if (!fileName || fileName.startsWith('.') || !isRegularFileInsideContentDir(filePath)) {
+      res.writeHead(404, securityHeaders());
+      res.end('Not found');
+      return;
+    }
+```
+
+- [ ] **Step 4: Verify GREEN**
+
+Run:
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
+node server.test.js
+```
+
+Expected: server tests pass, including symlink rejection.
+
+## Task 6: Restart Reconnect Regression
+
+**Files:**
+- Modify: `tests/brainstorm-server/lifecycle.test.js`
+- Modify: `skills/brainstorming/scripts/server.cjs`
+- Modify: `skills/brainstorming/scripts/helper.js`
+
+- [ ] **Step 1: Add RED integration test for same key over WS after restart**
+
+In `tests/brainstorm-server/lifecycle.test.js`, add a test after the port/token persistence test:
+
+```js
+  await test('stored key can authenticate WebSocket after same-port restart', async () => {
+    const dir = fs.mkdtempSync('/tmp/bs-reconnect-');
+    const portFile = path.join(dir, '.last-port');
+    const tokenFile = path.join(dir, '.last-token');
+    const env = { ...process.env, BRAINSTORM_PORT_FILE: portFile, BRAINSTORM_TOKEN_FILE: tokenFile, BRAINSTORM_LIFECYCLE_CHECK_MS: 100000 };
+
+    const a = spawn('node', [SERVER], { env: { ...env, BRAINSTORM_DIR: path.join(dir, 's1') } });
+    let outA = ''; a.stdout.on('data', d => outA += d.toString());
+    for (let i = 0; i < 60 && !outA.includes('server-started'); i++) await sleep(50);
+    const infoA = firstServerStarted(outA);
+    const keyA = new URL(infoA.url).searchParams.get('key');
+    a.kill(); await sleep(400);
+
+    const b = spawn('node', [SERVER], { env: { ...env, BRAINSTORM_DIR: path.join(dir, 's2') } });
+    let outB = ''; b.stdout.on('data', d => outB += d.toString());
+    for (let i = 0; i < 60 && !outB.includes('server-started'); i++) await sleep(50);
+    const infoB = firstServerStarted(outB);
+
+    const ws = new WebSocket(`ws://localhost:${infoB.port}/?key=${keyA}`, {
+      headers: { Origin: `http://localhost:${infoB.port}` }
+    });
+    const opened = await new Promise(resolve => {
+      ws.on('open', () => resolve(true));
+      ws.on('error', () => resolve(false));
+      setTimeout(() => resolve(false), 1500);
+    });
+
+    try {
+      assert.strictEqual(infoB.port, infoA.port, 'restart should reuse same port');
+      assert(opened, 'stored key should authenticate WS after restart');
+    } finally {
+      try { ws.close(); } catch (e) {}
+      b.kill(); await sleep(100);
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+```
+
+This test may already pass once Tasks 2 and 3 are implemented. If it passes before code changes, keep it as coverage but do not call it RED. The real browser reconnect behavior is primarily covered by Task 3 plus final manual/headless browser verification.
+
+- [ ] **Step 2: Verify behavior**
+
+Run:
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
+node lifecycle.test.js
+```
+
+Expected after Tasks 2 and 3: lifecycle tests pass. If this fails, fix the auth/restart path before continuing.
+
+## Task 7: Lifecycle Hang And Shell Lint
+
+**Files:**
+- Modify: `tests/brainstorm-server/lifecycle.test.js`
+- Modify: `skills/brainstorming/scripts/start-server.sh`
+- Modify: `skills/brainstorming/scripts/stop-server.sh`
+
+- [ ] **Step 1: Reproduce shell lint failure**
+
+Run:
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers
+scripts/lint-shell.sh skills/brainstorming/scripts/start-server.sh skills/brainstorming/scripts/stop-server.sh tests/brainstorm-server/stop-server.test.sh
+```
+
+Expected current failure:
+
+```text
+SC2164: skills/brainstorming/scripts/start-server.sh line 128: cd "$SCRIPT_DIR"
+SC2034: skills/brainstorming/scripts/start-server.sh line 166: for i in {1..50}
+SC2034: skills/brainstorming/scripts/stop-server.sh line 57: for i in {1..20}
+```
+
+- [ ] **Step 2: Fix shell lint minimally**
+
+In `skills/brainstorming/scripts/start-server.sh`, change:
+
+```bash
+cd "$SCRIPT_DIR"
+```
+
+to:
+
+```bash
+cd "$SCRIPT_DIR" || exit 1
+```
+
+Change unused loop variables from `i` to `_` where they are not read:
+
+```bash
+for _ in {1..50}; do
+```
+
+In `skills/brainstorming/scripts/stop-server.sh`, change:
+
+```bash
+for i in {1..20}; do
+```
+
+to:
+
+```bash
+for _ in {1..20}; do
+```
+
+- [ ] **Step 3: Fix lifecycle start-server hang**
+
+In `tests/brainstorm-server/lifecycle.test.js`, update the `start-server.sh --idle-timeout-minutes sets the timeout` test command:
+
+```js
+const out = execFileSync('bash', [START, '--project-dir', dir, '--idle-timeout-minutes', '5', '--background'], { encoding: 'utf8' });
+```
+
+This keeps the test from hanging when `CODEX_CI` triggers start-server foreground mode.
+
+- [ ] **Step 4: Verify lint and lifecycle**
+
+Run:
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers
+scripts/lint-shell.sh skills/brainstorming/scripts/start-server.sh skills/brainstorming/scripts/stop-server.sh tests/brainstorm-server/stop-server.test.sh
+cd tests/brainstorm-server
+node lifecycle.test.js
+```
+
+Expected: shell lint exits 0; lifecycle tests exit 0 without hanging.
+
+## Task 8: Gitignore Durable Companion State
+
+**Files:**
+- Modify: `.gitignore`
+
+- [ ] **Step 1: Verify current ignore gap**
+
+Run:
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers
+git check-ignore .superpowers/brainstorm/.last-token || true
+```
+
+Expected current output: no matching ignore rule.
+
+- [ ] **Step 2: Add ignore rule**
+
+Add this line to `.gitignore`:
+
+```gitignore
+.superpowers/
+```
+
+- [ ] **Step 3: Verify GREEN**
+
+Run:
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers
+git check-ignore .superpowers/brainstorm/.last-token
+```
+
+Expected output:
+
+```text
+.superpowers/brainstorm/.last-token
+```
+
+## Task 9: Full Automated Verification
+
+**Files:**
+- No code changes in this task.
+
+- [ ] **Step 1: Run focused suites**
+
+Run:
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
+node auth.test.js
+node helper.test.js
+node server.test.js
+node lifecycle.test.js
+```
+
+Expected: all four commands exit 0.
+
+- [ ] **Step 2: Run full brainstorm-server suite**
+
+Run:
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
+npm test
+```
+
+Expected: all tests pass, including ws-protocol, helper, auth, server, lifecycle, and stop-server.
+
+- [ ] **Step 3: Repeat suite for lifecycle/watch flake**
+
+Run:
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers/tests/brainstorm-server
+for i in 1 2 3; do npm test || exit 1; done
+```
+
+Expected: all three repeats pass without hanging.
+
+- [ ] **Step 4: Run shell lint**
+
+Run:
+
+```bash
+cd /Users/drewritter/prime-rad/superpowers
+scripts/lint-shell.sh skills/brainstorming/scripts/start-server.sh skills/brainstorming/scripts/stop-server.sh tests/brainstorm-server/stop-server.test.sh
+```
+
+Expected: exits 0.
+
+## Task 10: Re-run Security Probes
+
+**Files:**
+- No code changes in this task.
+
+- [ ] **Step 1: Recreate the cross-origin attacker probe**
+
+Use the previous scratch probe if available:
+
+```bash
+node /tmp/superpowers-pr1720-security-drewritter/probe-pr1720.cjs
+```
+
+If the scratch probe is unavailable, recreate a minimal probe under `/tmp` that:
+
+- starts the companion with a fixed token
+- loads the keyed URL in headless Chrome
+- starts an attacker page on a different localhost port
+- attempts `new WebSocket('ws://localhost:<companion-port>/')`
+- sends `{"type":"choice","choice":"attacker-injected"}`
+- checks `state/events`
+
+Expected after fixes:
+
+- keyless and wrong-key HTTP still return 403
+- same-origin helper reaches Connected
+- cross-origin WebSocket does not open
+- `state/events` does not contain `attacker-injected`
+- symlink-to-`server-info` returns 404
+- keyed browser load ends on bare `/`
+
+- [ ] **Step 2: Re-run manual/browser flow only after automated probes pass**
+
+Manual flow:
+
+1. start the companion with `--project-dir --open`
+2. push a screen
+3. confirm URL strips to `/`
+4. confirm status reaches Connected
+5. click a choice and verify `state/events`
+6. stop and restart same project
+7. verify the open tab reconnects automatically
+
+Expected: all steps pass without manual URL reload.
+
+## Self-Review Checklist
+
+- Spec coverage: every design requirement maps to at least one task.
+- Placeholder scan: this plan contains no unresolved placeholder markers or unspecified edge-case steps.
+- TDD order: every production change task starts with a focused failing test or a command that demonstrates the current failure.
+- Trust model: the plan preserves trusted same-origin screen JavaScript and future same-origin vendored libraries.
+- No-commit rule: execution does not commit unless Drew explicitly asks.

docs/superpowers/specs/2026-06-10-visual-companion-auth-hardening-design.md

@@ -0,0 +1,225 @@
+# Visual Companion Auth Hardening Design
+
+**Date:** 2026-06-10
+**Status:** Draft for Drew review
+
+## Goal
+
+Fix the security and reliability gaps found in PR #1720's brainstorming visual
+companion without changing the companion's core workflow or adding runtime
+dependencies.
+
+The fixes must be test-first and must leave clear automated evidence for:
+
+- cross-origin browser tabs cannot inject companion events by riding cookies
+- restart reconnect works without depending only on browser cookie behavior
+- bearer keys do not remain in the visible URL after bootstrap
+- `/files/*` cannot serve files outside the content directory
+- future same-origin vendored UI libraries still work
+
+## Threat Model
+
+The companion serves agent-generated local UI for a single brainstorming
+session. The important assets are:
+
+- screen content served from the companion
+- the session key
+- `state/events`, which the agent reads as user feedback
+- local files under the companion session directory
+
+In scope attackers:
+
+- a malicious browser tab on another `localhost` port
+- a browser page that can make requests to the companion but should not be able
+  to authenticate as the companion UI
+- a direct remote client when the server is bound to a non-loopback interface
+- accidental leakage through URL history, referrers, or committed local state
+- content-directory symlinks or path tricks that escape `/files/*`
+
+Out of scope for this fix:
+
+- malicious agent-authored screen HTML
+- malicious same-origin vendored JavaScript loaded by a companion screen
+
+This out-of-scope boundary is intentional. Companion screens are part of the
+agent UI surface. They may use inline scripts today and may someday use
+same-origin vendored libraries such as Alpine or Three.js. Protecting against
+malicious screen HTML would require a larger sandboxed-iframe architecture with
+a narrow message bridge; that is not the scope of this PR hardening pass.
+
+## Current Failures
+
+Automated and headed-browser testing found these failures in the PR branch:
+
+1. A cross-origin localhost page can open a cookie-authenticated WebSocket and
+   write attacker-controlled choices to `state/events` after the real companion
+   page sets the cookie.
+2. `/files/*` serves symlinks that point outside `content/`, including a symlink
+   to `state/server-info` containing the keyed URL.
+3. The session key remains in the URL of the actual screen page, so same-origin
+   screen JavaScript and accidental referrers/history can see it.
+4. The helper reconnects with a keyless `ws://host` URL. In headed Chrome, after
+   a same-port/same-token restart, the browser stopped presenting the cookie to
+   the restarted server, so the open tab stayed stuck on the tombstone until a
+   manual reload.
+5. Shell lint and the lifecycle test need cleanup so the test pass is stable in
+   Codex.
+
+## Design
+
+### 1. Bootstrap Keyed Loads
+
+`GET /?key=<token>` becomes a bootstrap response, not the screen response.
+
+When the key is valid, the server:
+
+1. sets the HttpOnly session cookie as it does today
+2. returns a small HTML bootstrap page
+3. the bootstrap page stores the key in tab-scoped `sessionStorage`
+4. the bootstrap page navigates to `/` using `location.replace('/')`
+
+After this, the visible screen URL is bare `/`, not `/?key=...`.
+
+`GET /` with a valid cookie serves the current screen. `GET /` without a valid
+cookie still returns the friendly 403 page. `GET /?key=<wrong>` returns 403.
+
+Why `sessionStorage`: the helper needs a reconnect credential that survives
+same-port restarts and does not depend only on cookie behavior. Because screen
+HTML is trusted same-origin UI, storing the key in tab-scoped storage is
+acceptable for this threat model. It is materially better than leaving the key
+in the address bar, history, and referrer surface.
+
+### 2. WebSocket Same-Origin Enforcement
+
+WebSocket upgrades must pass both checks:
+
+1. valid session auth by query key or cookie
+2. if an `Origin` header is present, it must match the request target origin
+
+The origin check should compare:
+
+```text
+Origin === "http://" + req.headers.host
+```
+
+Browser attacker page example:
+
+```text
+Origin: http://localhost:9999
+Host: localhost:58088
+```
+
+This must be rejected even if the browser sends the companion cookie.
+
+Legitimate companion page example:
+
+```text
+Origin: http://localhost:58088
+Host: localhost:58088
+```
+
+This should be accepted when the key or cookie is valid.
+
+Direct non-browser clients may omit `Origin`; they still need the session key.
+
+### 3. Helper Reconnect Credential
+
+`helper.js` should read the tab-scoped key from `sessionStorage` and append it
+to the WebSocket URL:
+
+```text
+ws://<host>/?key=<stored-key>
+```
+
+If no stored key exists, the helper falls back to the current cookie-only
+`ws://<host>` behavior. This preserves compatibility for already-loaded pages
+that do have a valid cookie but no storage entry.
+
+### 4. `/files/*` Containment
+
+The file server should continue to reject empty names and dotfiles. It must also
+ensure the file is a real regular file inside `CONTENT_DIR`.
+
+Use realpath containment as the boundary:
+
+- compute `realContentDir = fs.realpathSync(CONTENT_DIR)`
+- compute `realFilePath = fs.realpathSync(filePath)`
+- serve only when `realFilePath` equals a descendant of `realContentDir`
+- reject symlinks and anything outside the content directory with 404
+
+The server should keep using `path.basename` so nested paths remain unsupported.
+
+### 5. Leak-Reduction Headers
+
+Add conservative headers that do not block inline scripts or future same-origin
+vendored libraries:
+
+```text
+Referrer-Policy: no-referrer
+Cache-Control: no-store
+X-Frame-Options: DENY
+Content-Security-Policy: frame-ancestors 'none'
+Cross-Origin-Resource-Policy: same-origin
+```
+
+Do not add a restrictive `script-src` CSP in this pass. The companion currently
+injects inline helper JavaScript and future screens may load same-origin
+vendored libraries.
+
+### 6. Gitignore Durable Session State
+
+Add `.superpowers/` to the repo root `.gitignore` so persisted companion state
+and `.last-token` are not accidentally committed when using `--project-dir`.
+
+### 7. Test Stability And Lint
+
+Clean up shell lint warnings in the touched start/stop scripts.
+
+Update the lifecycle test that invokes `start-server.sh --idle-timeout-minutes`
+so it cannot hang under Codex's `CODEX_CI` foreground auto-detection. The test
+should force background mode with `--background` when it expects the script to
+return startup JSON.
+
+## Testing Strategy
+
+All behavior changes should be TDD:
+
+1. write the failing focused test
+2. run it and confirm it fails for the expected reason
+3. implement the minimum fix
+4. rerun the focused test
+5. rerun the full brainstorm-server suite
+
+Required focused regressions:
+
+- valid keyed `/` returns bootstrap, not screen content
+- bootstrap stores key in `sessionStorage` and strips the URL
+- cookie-only `/` still serves screen content
+- helper uses `sessionStorage` key for WebSocket URL
+- same-origin cookie WebSocket opens
+- cross-origin cookie WebSocket is rejected and writes no events
+- direct key WebSocket still opens without `Origin`
+- symlink under `content/` pointing to `state/server-info` returns 404
+- security headers are present on normal HTML, bootstrap, 403, and file responses
+- restart same port/token can authenticate reconnect with the stored key
+- shell lint passes for touched shell scripts
+- lifecycle suite does not hang under Codex
+
+## Acceptance Criteria
+
+- `cd tests/brainstorm-server && npm test` passes repeatedly without hanging.
+- The security probe that previously wrote `attacker-injected` from another
+  localhost origin now fails to open the WebSocket and leaves `state/events`
+  unchanged.
+- The symlink-to-`server-info` probe returns 404.
+- A headed or headless browser keyed load ends on a bare `/` URL and the status
+  pill reaches Connected.
+- A same-port/same-token restart reconnects automatically without manual reload.
+- `scripts/lint-shell.sh` passes for the touched shell scripts.
+
+## Deferred Work
+
+If the project later needs to treat screen HTML as untrusted, design a separate
+sandboxed iframe architecture. That should isolate generated screens on a
+separate origin or sandboxed frame and expose only a narrow `postMessage` bridge
+for user choices. Do not bundle that into this fix.

docs/superpowers/specs/2026-06-11-visual-companion-final-hardening-fixup-design.md

@@ -0,0 +1,254 @@
+# Visual Companion Final Hardening Fixup Design
+
+**Date:** 2026-06-11
+**Status:** Draft for Drew review
+
+## Goal
+
+Finish the PR #1720 visual companion hardening pass so the branch is ready for
+Jesse review with clean security behavior, deterministic tests, and a PR diff
+that contains only the companion work.
+
+This is a fixup on top of the existing auth hardening design. It should not
+redesign the companion or expand the feature surface.
+
+## Background
+
+The previous hardening pass added keyed sessions, same-origin WebSocket checks,
+URL key stripping, `/files/*` containment, leak-reduction headers, IPv6 URL
+formatting, Windows lifecycle coverage, and PR evidence updates.
+
+The final review pass found five remaining issues:
+
+1. The root `GET /` screen-selection path can still serve symlinks or hardlinks
+   under `content/` that point outside the content directory.
+2. When the preferred port is occupied, fallback servers can reuse a persisted
+   `.last-token`, creating two live same-project companion servers with the same
+   bearer key.
+3. `stop-server.sh` can signal an unrelated `node server.cjs` process when
+   strong ownership proof is unavailable.
+4. Some tests can pass against the wrong fallback process, leak background
+   processes on failure, or assume symlink support on Windows-like hosts.
+5. The PR is currently conflicted because the branch contains an older `evals`
+   submodule bump that was handled separately.
+
+## Non-Goals
+
+- Do not add HTTPS tunnel or `wss://` origin semantics in this pass.
+- Do not implement opt-out, free-text, or contrast-helper companion features.
+- Do not vendor Alpine, Three.js, or any other JavaScript library.
+- Do not attempt to sandbox malicious agent-authored screen HTML.
+- Do not add backward compatibility for stale stop-server PID files unless Drew
+  explicitly approves that tradeoff.
+
+## Inherited Security Invariants
+
+This fixup preserves the auth hardening already designed and implemented:
+
+- `.last-token` and `state/server-info` remain sensitive owner-only state.
+- Fallback tokens may appear in startup JSON and `state/server-info`, but must
+  not be written to `.last-token`.
+- Cookies remain port-named, `HttpOnly`, `SameSite=Strict`, and scoped to `/`.
+- WebSocket upgrades still require a valid key or cookie.
+- WebSocket `Origin` checks remain enforced when the browser supplies an
+  `Origin` header.
+- Direct no-`Origin` clients remain allowed only when they carry the session key.
+- Generated same-origin screen JavaScript and future same-origin vendored
+  libraries are trusted. Sandboxing malicious screen HTML remains deferred.
+
+## Design
+
+### 1. Rebase Onto Current `dev`
+
+Rebase `brainstorming-companion` onto current `origin/dev` before implementation
+work. Resolve the `evals` submodule conflict by taking `dev`.
+
+After the rebase:
+
+- `evals` must not appear in the PR diff.
+- PR #1720 can still mention eval evidence that was run elsewhere, but it must
+  include exact external evidence: eval repo commit, scenario path, command,
+  result artifact path or id, and RED/GREEN outcome.
+- The PR body must not imply the evals submodule bump is part of this PR.
+- Any earlier PR-body text or comment implying the submodule bump is included
+  must be superseded by the final PR-body evidence.
+
+### 2. Root Screen Containment
+
+The root screen route must use the same containment boundary as `/files/*`.
+
+`getNewestScreen()` should ignore any `.html` candidate that does not pass the
+regular-file-inside-content-dir guard. That guard must resolve real paths and
+ensure the served file is inside `CONTENT_DIR`. It must also preserve the
+existing hardlink protection by rejecting files whose link count is not exactly
+one when the platform reports link counts.
+
+Expected behavior:
+
+- A symlink under `content/` pointing outside `content/` is ignored.
+- A hardlink under `content/` to `state/server-info` is ignored when
+  `fs.linkSync` succeeds and `lstat.nlink > 1`.
+- If no safe screen file remains, the waiting page is served.
+- Existing `/files/*` containment behavior remains unchanged: empty names,
+  dotfiles, symlinks, hardlinks, and directories still return 404.
+
+### 3. Fallback Token Isolation
+
+Port fallback must not reuse a token loaded from persisted `.last-token`.
+
+Token source should be explicit in code:
+
+- `BRAINSTORM_TOKEN` from the environment is an intentional operator/test
+  override. If the preferred port is occupied while an explicit environment
+  token is set, the server must fail closed instead of falling back, because the
+  occupied server may be using the same explicit token.
+- `.last-token` is persisted state for same-port reconnect convenience. If the
+  server falls back because the preferred port is occupied, discard that loaded
+  token and generate a fresh unpersisted token for the fallback process.
+- A newly generated token that was not loaded from `.last-token` can be reused
+  within the same process because no other live process is known to have it.
+
+The fallback server must continue to avoid overwriting `.last-port` and
+`.last-token`.
+
+### 4. Stop-Server Ownership Proof
+
+`start-server.sh` should create a per-start server instance id and pass it to
+Node as an inert command-line argument, for example:
+
+```text
+node server.cjs --brainstorm-server-id=<id>
+```
+
+The id is not an auth credential. It is only process-ownership evidence for the
+local lifecycle scripts. `server.cjs` can ignore the argument.
+
+The id must use a shell/MSYS-safe alphabet, such as
+`^[A-Za-z0-9_-]{32,64}$`. Store it in `state/server-instance-id` with
+owner-only permissions.
+
+`stop-server.sh` should read the expected id from state and only signal the PID
+when the target process argv contains the exact argument
+`--brainstorm-server-id=<id>` as a full argv token, not as a loose substring.
+Prefer `/proc/<pid>/cmdline` when available, then fall back to wide `ps` output.
+A matching instance id is sufficient proof even when `server-info` is missing
+or `lsof` is unavailable. Existing port-to-PID checks may remain as additional
+evidence.
+
+Fail closed when ownership cannot be proven:
+
+- missing PID file
+- missing or malformed server id
+- target command line unavailable
+- target command line does not include the expected id
+- old/stale session metadata without the new id
+
+This intentionally prefers leaving a stale process running over killing an
+unrelated process.
+
+Operator-visible outcomes should be explicit:
+
+- missing PID file returns `not_running`
+- missing or malformed server id returns `stale_pid`
+- unavailable command line returns `stale_pid`
+- wrong or absent argv id returns `stale_pid`
+- successful stop returns `stopped`
+
+On `stale_pid` and `stopped` outcomes, remove `server.pid` and
+`server-instance-id` so future stop attempts do not keep targeting the same
+ambiguous process. Do not remove persistent session content.
+
+### 5. Test Hardening
+
+The test pass should be deterministic across macOS and the Windows Git Bash host
+used for validation.
+
+Required changes:
+
+- Fixed-port suites must either fail fast if the server reports a fallback port
+  or drive all clients from the reported startup port.
+- `stop-server.test.sh` needs a top-level cleanup trap before any background
+  process is started.
+- Symlink-specific assertions should probe symlink capability and skip only that
+  assertion when the host cannot create usable test symlinks.
+- Tests that create impostor processes must assert that the impostor survives
+  when lifecycle metadata is missing or insufficient.
+- Windows/MSYS start-server tests must assert that Windows-like detection still
+  clears `BRAINSTORM_OWNER_PID`, still auto-foregrounds when appropriate, and
+  still passes the instance-id argv exactly.
+
+### 6. Docs And PR Consistency
+
+Before Jesse reviews, reconcile reviewer-visible docs and PR metadata:
+
+- Update the issue catalog so dispositions match what this PR actually ships.
+- Keep auto-open docs consistent with the implemented `--open` behavior.
+- Keep the documented default idle timeout at 4 hours everywhere.
+- Review the PR body against the template after the rebase.
+- Record macOS, Windows, browser/manual, and external eval evidence in the PR
+  body with concrete commands and results.
+
+## Testing Strategy
+
+Use TDD for each behavior change:
+
+1. Add or tighten a focused regression test.
+2. Run it and confirm it fails for the expected reason.
+3. Implement the smallest fix.
+4. Rerun the focused test.
+5. Rerun the full brainstorm-server suite.
+
+Required focused regressions:
+
+| Behavior | Test File | Focused Command | Expected RED | Expected GREEN |
+| --- | --- | --- | --- | --- |
+| Root route ignores symlink escape | `tests/brainstorm-server/server.test.js` | `node tests/brainstorm-server/server.test.js` | authenticated `GET /` serves linked outside content | response serves waiting page or safe screen |
+| Root route ignores supported hardlink escape | `tests/brainstorm-server/server.test.js` | `node tests/brainstorm-server/server.test.js` | authenticated `GET /` serves hardlinked `server-info` | hardlink candidate is ignored when `nlink > 1` |
+| `/files/*` containment stays unchanged | `tests/brainstorm-server/server.test.js` | `node tests/brainstorm-server/server.test.js` | existing containment test regresses | empty, dotfile, directory, symlink, hardlink cases remain 404 |
+| Persisted-token fallback rotates token | `tests/brainstorm-server/lifecycle.test.js` | `node tests/brainstorm-server/lifecycle.test.js` | fallback URL key equals persisted preferred-port key | fallback URL key differs and is not written to `.last-token` |
+| Explicit-token fallback fails closed | `tests/brainstorm-server/lifecycle.test.js` | `node tests/brainstorm-server/lifecycle.test.js` | server falls back while `BRAINSTORM_TOKEN` is set | process exits non-zero and does not start fallback |
+| Fallback key cannot authenticate to original server | `tests/brainstorm-server/lifecycle.test.js` | `node tests/brainstorm-server/lifecycle.test.js` | fallback key receives 200 from original port | original port rejects fallback key |
+| Correct instance id permits stop | `tests/brainstorm-server/stop-server.test.sh` | `bash tests/brainstorm-server/stop-server.test.sh` | real start-server-launched server survives | stop returns `stopped` and process exits |
+| Wrong, missing, malformed, or stale id is safe | `tests/brainstorm-server/stop-server.test.sh` | `bash tests/brainstorm-server/stop-server.test.sh` | impostor is signaled | stop returns `stale_pid` and impostor survives |
+| Fixed-port suites cannot pass through fallback | `tests/brainstorm-server/server.test.js`, `tests/brainstorm-server/auth.test.js` | respective `node` commands | test silently talks to fallback port | test fails clearly or uses reported port intentionally |
+| Shell cleanup traps run on failures | `tests/brainstorm-server/stop-server.test.sh` | `bash tests/brainstorm-server/stop-server.test.sh` | failure leaves child processes | trap reaps background children |
+| Windows/MSYS start behavior keeps lifecycle invariants | `tests/brainstorm-server/start-server.test.sh`, `tests/brainstorm-server/windows-lifecycle.test.sh` | `bash` test commands on macOS and `ballmer` | owner PID or argv handling regresses | owner PID is cleared, foreground detection holds, id argv is present |
+
+Each RED/GREEN cycle should leave a short evidence note for the PR body: focused
+command, failing assertion before the fix, passing assertion after the fix, and
+whether the evidence was gathered on macOS or Windows.
+
+## Verification
+
+Before calling the fixup complete, run:
+
+- `git fetch origin dev && git rebase origin/dev`
+- `git diff --quiet origin/dev...HEAD -- evals`
+- `gh pr view 1720 --json mergeStateStatus,statusCheckRollup,headRefOid`
+- `cd tests/brainstorm-server && npm test`
+- relevant focused test commands used during TDD
+- `git diff --check`
+- Node syntax checks for touched JavaScript files
+- shell lint for touched shell files
+- Windows validation on `ballmer`: full runnable brainstorm-server suite plus
+  the standalone Windows lifecycle probe
+
+Manual/browser testing comes only after the automated pass is green.
+
+## Acceptance Criteria
+
+- PR #1720 rebases cleanly onto current `dev`.
+- `evals` is absent from the PR diff.
+- Root screen serving cannot read outside `content/` through symlink or
+  supported hardlink escapes.
+- `/files/*` containment protections remain unchanged.
+- No fallback server runs with a token that may be shared with the occupied
+  preferred-port server.
+- `stop-server.sh` does not signal unrelated processes when ownership proof is
+  missing or ambiguous.
+- `stop-server.sh` can still stop a legitimate server with a matching instance
+  id when `server-info` or `lsof` is unavailable.
+- Focused RED/GREEN evidence is recorded for each regression.
+- macOS and Windows validation evidence is recorded in the PR body.
+- The PR body accurately describes what is in the branch and what evidence was
+  gathered externally.

skills/brainstorming/SKILL.md

@@ -22,7 +22,7 @@ Every project goes through this process. A todo list, a single-function utility,
 You MUST create a task for each of these items and complete them in order:
 
 1. **Explore project context** — check files, docs, recent commits
-2. **Offer visual companion** (if topic will involve visual questions) — this is its own message, not combined with a clarifying question. See the Visual Companion section below.
+2. **Offer the visual companion just-in-time** — NOT upfront. The first time a question would genuinely be clearer shown than described, offer it then (its own message); on approval its browser tab opens for you. If no visual question ever arises, never offer it. See the Visual Companion section below.
 3. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
 4. **Propose 2-3 approaches** — with trade-offs and your recommendation
 5. **Present design** — in sections scaled to their complexity, get user approval after each section
@@ -36,8 +36,6 @@ You MUST create a task for each of these items and complete them in order:
 ```dot
 digraph brainstorming {
     "Explore project context" [shape=box];
-    "Visual questions ahead?" [shape=diamond];
-    "Offer Visual Companion\n(own message, no other content)" [shape=box];
     "Ask clarifying questions" [shape=box];
     "Propose 2-3 approaches" [shape=box];
     "Present design sections" [shape=box];
@@ -47,10 +45,7 @@ digraph brainstorming {
     "User reviews spec?" [shape=diamond];
     "Invoke writing-plans skill" [shape=doublecircle];
 
-    "Explore project context" -> "Visual questions ahead?";
-    "Visual questions ahead?" -> "Offer Visual Companion\n(own message, no other content)" [label="yes"];
-    "Visual questions ahead?" -> "Ask clarifying questions" [label="no"];
-    "Offer Visual Companion\n(own message, no other content)" -> "Ask clarifying questions";
+    "Explore project context" -> "Ask clarifying questions";
     "Ask clarifying questions" -> "Propose 2-3 approaches";
     "Propose 2-3 approaches" -> "Present design sections";
     "Present design sections" -> "User approves design?";
@@ -148,10 +143,10 @@ Wait for the user's response. If they request changes, make them and re-run the
 
 A browser-based companion for showing mockups, diagrams, and visual options during brainstorming. Available as a tool — not a mode. Accepting the companion means it's available for questions that benefit from visual treatment; it does NOT mean every question goes through the browser.
 
-**Offering the companion:** When you anticipate that upcoming questions will involve visual content (mockups, layouts, diagrams), offer it once for consent:
-> "Some of what we're working on might be easier to explain if I can show it to you in a web browser. I can put together mockups, diagrams, comparisons, and other visuals as we go. This feature is still new and can be token-intensive. Want to try it? (Requires opening a local URL)"
+**Offering the companion (just-in-time):** Do NOT offer it upfront. Wait until a question would genuinely be clearer shown than told — a real mockup / layout / diagram question, not merely a UI *topic*. The first time that happens, offer it then, as its own message:
+> "This next part might be easier if I show you — I can put together mockups, diagrams, and comparisons in a browser tab as we go. It's still new and can be token-intensive. Want me to? I'll open it for you."
 
-**This offer MUST be its own message.** Do not combine it with clarifying questions, context summaries, or any other content. The message should contain ONLY the offer above and nothing else. Wait for the user's response before continuing. If they decline, proceed with text-only brainstorming.
+**This offer MUST be its own message.** Only the offer — no clarifying question, summary, or other content. Wait for the user's response. If they accept, start the server with `--open` so their browser opens to the first screen automatically. If they decline, continue text-only and don't offer again unless they raise it.
 
 **Per-question decision:** Even after the user accepts, decide FOR EACH QUESTION whether to use the browser or the terminal. The test: **would the user understand this better by seeing it than reading it?**
 

skills/brainstorming/scripts/frame-template.html

@@ -73,8 +73,8 @@
       flex-shrink: 0;
     }
     .header h1 { font-size: 0.85rem; font-weight: 500; color: var(--text-secondary); }
-    .header .status { font-size: 0.7rem; color: var(--success); display: flex; align-items: center; gap: 0.4rem; }
-    .header .status::before { content: ''; width: 6px; height: 6px; background: var(--success); border-radius: 50%; }
+    .header .status { font-size: 0.7rem; color: var(--status-color, var(--success)); display: flex; align-items: center; gap: 0.4rem; }
+    .header .status::before { content: ''; width: 6px; height: 6px; background: var(--status-color, var(--success)); border-radius: 50%; }
 
     .main { flex: 1; overflow-y: auto; }
     #frame-content { padding: 2rem; min-height: 100%; }
@@ -197,7 +197,7 @@
 <body>
   <div class="header">
     <h1><a href="https://github.com/obra/superpowers" style="color: inherit; text-decoration: none;">Superpowers Brainstorming</a></h1>
-    <div class="status">Connected</div>
+    <div class="status">Connecting…</div>
   </div>
 
   <div class="main">

skills/brainstorming/scripts/helper.js

@@ -1,26 +1,120 @@
 (function() {
-  const WS_URL = 'ws://' + window.location.host;
+  const MIN_RECONNECT_MS = 500;
+  const MAX_RECONNECT_MS = 30000;
+  const TOMBSTONE_AFTER_MS = 15000; // show the "paused" overlay after this long disconnected
+
+  // Pure: next backoff delay (doubles, capped). Exported for unit tests.
+  function nextReconnectDelay(current, max) {
+    return Math.min(current * 2, max);
+  }
+  if (typeof module !== 'undefined' && module.exports) {
+    module.exports = { nextReconnectDelay, MIN_RECONNECT_MS, MAX_RECONNECT_MS, TOMBSTONE_AFTER_MS };
+  }
+
+  // Everything below is browser-only; bail out when loaded in Node (tests).
+  if (typeof window === 'undefined') return;
+
   let ws = null;
   let eventQueue = [];
+  let reconnectDelay = MIN_RECONNECT_MS;
+  let reconnectTimer = null;
+  let disconnectedSince = null;
+  let everConnected = false;
+  let tombstoneShown = false;
+
+  function sessionKey() {
+    try {
+      return window.sessionStorage && window.sessionStorage.getItem('brainstorm-session-key');
+    } catch (e) {}
+    return null;
+  }
+
+  function websocketUrl() {
+    const key = sessionKey();
+    return 'ws://' + window.location.host + (key ? '/?key=' + encodeURIComponent(key) : '');
+  }
+
+  function reloadAfterRecovery() {
+    const key = sessionKey();
+    if (key) {
+      window.location.replace('/?key=' + encodeURIComponent(key));
+    } else {
+      window.location.reload();
+    }
+  }
+
+  // Reflect connection state in the frame's status pill (absent on full-doc screens).
+  function setStatus(state) {
+    const el = document.querySelector('.status');
+    if (!el) return;
+    const map = {
+      connecting:   ['Connecting…',   'var(--text-tertiary)'],
+      connected:    ['Connected',     'var(--success)'],
+      reconnecting: ['Reconnecting…', 'var(--warning)'],
+      disconnected: ['Disconnected',  'var(--error)']
+    };
+    const [text, color] = map[state] || map.disconnected;
+    el.textContent = text;
+    el.style.setProperty('--status-color', color);
+  }
+
+  // Self-styled so it works on framed and full-document screens alike.
+  function showTombstone() {
+    if (tombstoneShown) return;
+    tombstoneShown = true;
+    const el = document.createElement('div');
+    el.id = 'bs-tombstone';
+    el.style.cssText = 'position:fixed;inset:0;z-index:99999;display:flex;' +
+      'align-items:center;justify-content:center;padding:2rem;text-align:center;' +
+      'background:rgba(20,20,22,0.92);color:#f5f5f7;font-family:system-ui,sans-serif';
+    el.innerHTML = '<div style="max-width:480px">' +
+      '<h2 style="margin:0 0 .5rem;font-weight:600">Companion paused</h2>' +
+      '<p style="margin:0;opacity:.85">This brainstorm companion has stopped. ' +
+      'Ask your coding agent to bring it back — this page reconnects automatically.</p></div>';
+    if (document.body) document.body.appendChild(el);
+  }
 
   function connect() {
-    ws = new WebSocket(WS_URL);
+    if (reconnectTimer) { clearTimeout(reconnectTimer); reconnectTimer = null; }
+    setStatus(everConnected ? 'reconnecting' : 'connecting');
+    ws = new WebSocket(websocketUrl());
 
     ws.onopen = () => {
+      const recovered = tombstoneShown;
+      everConnected = true;
+      disconnectedSince = null;
+      reconnectDelay = MIN_RECONNECT_MS;
+      tombstoneShown = false;
+      setStatus('connected');
       eventQueue.forEach(e => ws.send(JSON.stringify(e)));
       eventQueue = [];
+      // Recovered from a tombstoned outage (e.g. the server restarted on the same
+      // port) — reload through the keyed bootstrap when possible so the cookie is
+      // refreshed before the visible URL returns to bare /.
+      if (recovered) reloadAfterRecovery();
     };
 
     ws.onmessage = (msg) => {
-      const data = JSON.parse(msg.data);
-      if (data.type === 'reload') {
-        window.location.reload();
-      }
+      let data;
+      try { data = JSON.parse(msg.data); } catch (e) { return; }
+      if (data.type === 'reload') window.location.reload();
     };
 
     ws.onclose = () => {
-      setTimeout(connect, 1000);
+      ws = null;
+      if (disconnectedSince === null) disconnectedSince = Date.now();
+      if (Date.now() - disconnectedSince >= TOMBSTONE_AFTER_MS) {
+        setStatus('disconnected');
+        showTombstone();
+      } else {
+        setStatus('reconnecting');
+      }
+      reconnectTimer = setTimeout(connect, reconnectDelay);
+      reconnectDelay = nextReconnectDelay(reconnectDelay, MAX_RECONNECT_MS);
     };
+
+    // Let onclose own reconnection so we don't schedule it twice.
+    ws.onerror = () => { try { ws.close(); } catch (e) {} };
   }
 
   function sendEvent(event) {

skills/brainstorming/scripts/server.cjs

@@ -82,7 +82,21 @@ function decodeFrame(buffer) {
 
 // ========== Configuration ==========
 
-const PORT = process.env.BRAINSTORM_PORT || (49152 + Math.floor(Math.random() * 16383));
+const PORT_FILE = process.env.BRAINSTORM_PORT_FILE || null;
+const randomPort = () => 49152 + Math.floor(Math.random() * 16383);
+// Prefer an explicit port, else the port this session last bound (so a restart
+// reuses it and an already-open browser tab reconnects), else a random high port.
+function preferredPort() {
+  if (process.env.BRAINSTORM_PORT) return Number(process.env.BRAINSTORM_PORT);
+  if (PORT_FILE) {
+    try {
+      const p = Number(fs.readFileSync(PORT_FILE, 'utf-8').trim());
+      if (Number.isInteger(p) && p > 1023 && p < 65536) return p;
+    } catch (e) { /* no prior port recorded */ }
+  }
+  return randomPort();
+}
+let PORT = preferredPort();
 const HOST = process.env.BRAINSTORM_HOST || '127.0.0.1';
 const URL_HOST = process.env.BRAINSTORM_URL_HOST || (HOST === '127.0.0.1' ? 'localhost' : HOST);
 const SESSION_DIR = process.env.BRAINSTORM_DIR || '/tmp/brainstorm';
@@ -90,6 +104,44 @@ const CONTENT_DIR = path.join(SESSION_DIR, 'content');
 const STATE_DIR = path.join(SESSION_DIR, 'state');
 let ownerPid = process.env.BRAINSTORM_OWNER_PID ? Number(process.env.BRAINSTORM_OWNER_PID) : null;
 
+// Per-session secret key. The companion is reachable by any local browser tab
+// and, when bound to a non-loopback host, by any host that can route to it.
+// The key authenticates the real client uniformly across loopback, tunnel, and
+// remote binds — and defeats DNS rebinding — where a Host/Origin allowlist
+// cannot. It rides the served URL as ?key= and is mirrored into a cookie on
+// first load so same-origin subresources and the WebSocket carry it for free.
+// Persisted alongside the port (BRAINSTORM_TOKEN_FILE) so a restart keeps the
+// same key and an already-open tab's cookie still validates.
+const TOKEN_FILE = process.env.BRAINSTORM_TOKEN_FILE || null;
+function generateToken() {
+  return crypto.randomBytes(32).toString('hex');
+}
+
+function chmodOwnerOnly(file) {
+  try { fs.chmodSync(file, 0o600); } catch (e) { /* best effort */ }
+}
+
+function initialToken() {
+  if (process.env.BRAINSTORM_TOKEN) {
+    return { value: process.env.BRAINSTORM_TOKEN, source: 'env' };
+  }
+  if (TOKEN_FILE) {
+    try {
+      const t = fs.readFileSync(TOKEN_FILE, 'utf-8').trim();
+      if (/^[0-9a-f]{32,}$/i.test(t)) {
+        chmodOwnerOnly(TOKEN_FILE);
+        return { value: t, source: 'file' };
+      }
+    } catch (e) { /* no prior token recorded */ }
+  }
+  return { value: generateToken(), source: 'generated' };
+}
+
+const tokenInfo = initialToken();
+let TOKEN = tokenInfo.value;
+let tokenSource = tokenInfo.source;
+let COOKIE_NAME = 'brainstorm-key-' + PORT; // refined to the actual bound port in onListen
+
 const MIME_TYPES = {
   '.html': 'text/html', '.css': 'text/css', '.js': 'application/javascript',
   '.json': 'application/json', '.png': 'image/png', '.jpg': 'image/jpeg',
@@ -107,6 +159,30 @@ h1 { color: #333; } p { color: #666; }</style>
 <body><h1>Brainstorm Companion</h1>
 <p>Waiting for the agent to push a screen...</p></body></html>`;
 
+const FORBIDDEN_PAGE = `<!DOCTYPE html>
+<html>
+<head><meta charset="utf-8"><title>Session key required</title>
+<style>body { font-family: system-ui, sans-serif; padding: 2rem; max-width: 800px; margin: 0 auto; }
+h1 { color: #333; } p { color: #666; } code { background: #f0f0f0; padding: 0.1em 0.3em; border-radius: 4px; }</style>
+</head>
+<body><h1>Session key required</h1>
+<p>This page needs the full URL your coding agent gave you, including the
+<code>?key=&hellip;</code> part. Copy the complete URL and open it again.</p></body></html>`;
+
+function bootstrapPage(key) {
+  const jsonKey = JSON.stringify(String(key));
+  return `<!DOCTYPE html>
+<html>
+<head><meta charset="utf-8"><title>Opening Brainstorm Companion</title></head>
+<body>
+<script>
+try { sessionStorage.setItem('brainstorm-session-key', ${jsonKey}); } catch (e) {}
+location.replace('/');
+</script>
+</body>
+</html>`;
+}
+
 const frameTemplate = fs.readFileSync(path.join(__dirname, 'frame-template.html'), 'utf-8');
 const helperScript = fs.readFileSync(path.join(__dirname, 'helper.js'), 'utf-8');
 const helperInjection = '<script>\n' + helperScript + '\n</script>';
@@ -124,20 +200,144 @@ function wrapInFrame(content) {
 
 function getNewestScreen() {
   const files = fs.readdirSync(CONTENT_DIR)
-    .filter(f => f.endsWith('.html'))
+    .filter(f => !f.startsWith('.') && f.endsWith('.html'))
     .map(f => {
       const fp = path.join(CONTENT_DIR, f);
+      if (!isRegularFileInsideContentDir(fp)) return null;
       return { path: fp, mtime: fs.statSync(fp).mtime.getTime() };
     })
+    .filter(Boolean)
     .sort((a, b) => b.mtime - a.mtime);
   return files.length > 0 ? files[0].path : null;
 }
 
+function urlHostForHttp(host) {
+  const h = String(host);
+  if (h.startsWith('[') && h.endsWith(']')) return h;
+  return h.includes(':') ? '[' + h + ']' : h;
+}
+
+function companionUrl() {
+  return 'http://' + urlHostForHttp(URL_HOST) + ':' + PORT + '/?key=' + TOKEN;
+}
+
+function browserLauncherForPlatform(url, {
+  platform = process.platform,
+  osRelease = require('os').release(),
+  env = process.env
+} = {}) {
+  const isWSL = platform === 'linux' && /microsoft/i.test(osRelease);
+  if (platform === 'darwin') return { bin: 'open', args: [url] };
+  if (platform === 'win32' || isWSL) {
+    return { bin: 'rundll32.exe', args: ['url.dll,FileProtocolHandler', url] };
+  }
+  if (env.DISPLAY || env.WAYLAND_DISPLAY) return { bin: 'xdg-open', args: [url] };
+  return null;
+}
+
+function isRegularFileInsideContentDir(filePath) {
+  let stat, realContentDir, realFilePath;
+  try {
+    stat = fs.lstatSync(filePath);
+    if (stat.isSymbolicLink()) return false;
+    if (!stat.isFile()) return false;
+    if (stat.nlink !== 1) return false;
+    realContentDir = fs.realpathSync(CONTENT_DIR);
+    realFilePath = fs.realpathSync(filePath);
+  } catch (e) {
+    return false;
+  }
+  return realFilePath.startsWith(realContentDir + path.sep);
+}
+
+// ========== Authentication ==========
+
+function timingSafeEqualStr(a, b) {
+  const ab = Buffer.from(String(a));
+  const bb = Buffer.from(String(b));
+  if (ab.length !== bb.length) return false;
+  return crypto.timingSafeEqual(ab, bb);
+}
+
+function parseCookies(header) {
+  const out = {};
+  if (!header) return out;
+  for (const part of header.split(';')) {
+    const eq = part.indexOf('=');
+    if (eq < 0) continue;
+    out[part.slice(0, eq).trim()] = part.slice(eq + 1).trim();
+  }
+  return out;
+}
+
+// A request is authorized if it carries the session key as ?key= or as the
+// session cookie. Both are compared in constant time.
+function isAuthorized(req) {
+  const q = req.url.indexOf('?');
+  if (q >= 0) {
+    const params = new URLSearchParams(req.url.slice(q + 1));
+    if (params.has('key')) {
+      const key = params.get('key');
+      return Boolean(key && timingSafeEqualStr(key, TOKEN));
+    }
+  }
+  const cookie = parseCookies(req.headers['cookie'])[COOKIE_NAME];
+  if (cookie && timingSafeEqualStr(cookie, TOKEN)) return true;
+  return false;
+}
+
+function pathnameOf(url) {
+  const q = url.indexOf('?');
+  return q >= 0 ? url.slice(0, q) : url;
+}
+
+function queryKey(url) {
+  const q = url.indexOf('?');
+  if (q < 0) return null;
+  return new URLSearchParams(url.slice(q + 1)).get('key');
+}
+
+function securityHeaders(headers = {}) {
+  return {
+    'Referrer-Policy': 'no-referrer',
+    'Cache-Control': 'no-store',
+    'X-Frame-Options': 'DENY',
+    'Content-Security-Policy': "frame-ancestors 'none'",
+    'Cross-Origin-Resource-Policy': 'same-origin',
+    ...headers
+  };
+}
+
+function isAllowedWebSocketOrigin(req) {
+  const origin = req.headers.origin;
+  if (!origin) return true;
+  const host = req.headers.host;
+  if (!host) return false;
+  return origin === 'http://' + host;
+}
+
 // ========== HTTP Request Handler ==========
 
 function handleRequest(req, res) {
-  touchActivity();
-  if (req.method === 'GET' && req.url === '/') {
+  if (!isAuthorized(req)) {
+    res.writeHead(403, securityHeaders({ 'Content-Type': 'text/html; charset=utf-8' }));
+    res.end(FORBIDDEN_PAGE);
+    return;
+  }
+  touchActivity(); // only authorized requests count as activity
+
+  // Mirror the key into a cookie so same-origin subresources (/files/*) can
+  // authenticate after bootstrap. HttpOnly keeps it away from page scripts; the
+  // WebSocket Origin check below is what blocks cross-origin localhost injection.
+  res.setHeader('Set-Cookie',
+    COOKIE_NAME + '=' + TOKEN + '; HttpOnly; SameSite=Strict; Path=/');
+
+  const pathname = pathnameOf(req.url);
+  const keyFromQuery = queryKey(req.url);
+  if (req.method === 'GET' && pathname === '/' && keyFromQuery && timingSafeEqualStr(keyFromQuery, TOKEN)) {
+    res.writeHead(200, securityHeaders({ 'Content-Type': 'text/html; charset=utf-8' }));
+    res.end(bootstrapPage(keyFromQuery));
+  } else if (req.method === 'GET' && pathname === '/') {
     const screenFile = getNewestScreen();
     let html = screenFile
       ? (raw => isFullDocument(raw) ? raw : wrapInFrame(raw))(fs.readFileSync(screenFile, 'utf-8'))
@@ -149,22 +349,24 @@ function handleRequest(req, res) {
       html += helperInjection;
     }
 
-    res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+    res.writeHead(200, securityHeaders({ 'Content-Type': 'text/html; charset=utf-8' }));
     res.end(html);
-  } else if (req.method === 'GET' && req.url.startsWith('/files/')) {
-    const fileName = req.url.slice(7);
-    const filePath = path.join(CONTENT_DIR, path.basename(fileName));
-    if (!fs.existsSync(filePath)) {
-      res.writeHead(404);
+  } else if (req.method === 'GET' && pathname.startsWith('/files/')) {
+    const fileName = path.basename(pathname.slice(7));
+    const filePath = path.join(CONTENT_DIR, fileName);
+    // Reject empty/dotfile names and anything that isn't a regular file —
+    // `/files/` would otherwise resolve to CONTENT_DIR and crash readFileSync (EISDIR).
+    if (!fileName || fileName.startsWith('.') || !isRegularFileInsideContentDir(filePath)) {
+      res.writeHead(404, securityHeaders());
       res.end('Not found');
       return;
     }
     const ext = path.extname(filePath).toLowerCase();
     const contentType = MIME_TYPES[ext] || 'application/octet-stream';
-    res.writeHead(200, { 'Content-Type': contentType });
+    res.writeHead(200, securityHeaders({ 'Content-Type': contentType }));
     res.end(fs.readFileSync(filePath));
   } else {
-    res.writeHead(404);
+    res.writeHead(404, securityHeaders());
     res.end('Not found');
   }
 }
@@ -174,6 +376,8 @@ function handleRequest(req, res) {
 const clients = new Set();
 
 function handleUpgrade(req, socket) {
+  if (!isAuthorized(req) || !isAllowedWebSocketOrigin(req)) { socket.destroy(); return; }
+
   const key = req.headers['sec-websocket-key'];
   if (!key) { socket.destroy(); return; }
 
@@ -240,7 +444,7 @@ function handleMessage(text) {
   }
   touchActivity();
   console.log(JSON.stringify({ source: 'user-event', ...event }));
-  if (event.choice) {
+  if (event && event.choice) {
     const eventsFile = path.join(STATE_DIR, 'events');
     fs.appendFileSync(eventsFile, JSON.stringify(event) + '\n');
   }
@@ -253,9 +457,44 @@ function broadcast(msg) {
   }
 }
 
+// Best-effort: open the user's browser the first time a screen is actually ready
+// to show. Skips when disabled, on a non-loopback (remote) bind, or when a
+// browser is already connected. Override the launcher with BRAINSTORM_OPEN_CMD.
+let browserOpened = false;
+function maybeOpenBrowser() {
+  if (browserOpened) return;
+  browserOpened = true;
+  if (!process.env.BRAINSTORM_OPEN) return; // opt-in: only after the user approves the companion
+  if (HOST !== '127.0.0.1' && HOST !== 'localhost') return;
+  if (clients.size > 0) return; // the user already opened it
+  const url = companionUrl(); // must carry the key or the gate 403s it
+  const cp = require('child_process');
+  // Operator-provided launcher: run as given (this env var is trusted operator input).
+  if (process.env.BRAINSTORM_OPEN_CMD) {
+    try { cp.exec(process.env.BRAINSTORM_OPEN_CMD + ' ' + JSON.stringify(url), () => {}); } catch (e) { /* best effort */ }
+    return;
+  }
+  // Platform launchers: pass the URL as an argv element via execFile (no shell),
+  // so a url-host containing shell metacharacters can't inject a command.
+  const launcher = browserLauncherForPlatform(url);
+  if (!launcher) return; // headless: nothing to open
+  try { cp.execFile(launcher.bin, launcher.args, () => {}); } catch (e) { /* best effort */ }
+}
+
 // ========== Activity Tracking ==========
 
-const IDLE_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+// Idle timeout: shut down after this long with no activity. Default 4 hours;
+// override with BRAINSTORM_IDLE_TIMEOUT_MS (start-server.sh: --idle-timeout-minutes).
+const IDLE_TIMEOUT_MS = (() => {
+  const ms = Number(process.env.BRAINSTORM_IDLE_TIMEOUT_MS);
+  return Number.isFinite(ms) && ms > 0 ? ms : 4 * 60 * 60 * 1000;
+})();
+// How often the watchdog checks for owner-death / idleness. Configurable mainly
+// so tests can run fast; production default is 60s.
+const LIFECYCLE_CHECK_MS = (() => {
+  const ms = Number(process.env.BRAINSTORM_LIFECYCLE_CHECK_MS);
+  return Number.isFinite(ms) && ms > 0 ? ms : 60 * 1000;
+})();
 let lastActivity = Date.now();
 
 function touchActivity() {
@@ -276,14 +515,14 @@ function startServer() {
   // macOS fs.watch reports 'rename' for both new files and overwrites,
   // so we can't rely on eventType alone.
   const knownFiles = new Set(
-    fs.readdirSync(CONTENT_DIR).filter(f => f.endsWith('.html'))
+    fs.readdirSync(CONTENT_DIR).filter(f => !f.startsWith('.') && f.endsWith('.html'))
   );
 
   const server = http.createServer(handleRequest);
   server.on('upgrade', handleUpgrade);
 
   const watcher = fs.watch(CONTENT_DIR, (eventType, filename) => {
-    if (!filename || !filename.endsWith('.html')) return;
+    if (!filename || filename.startsWith('.') || !filename.endsWith('.html')) return;
 
     if (debounceTimers.has(filename)) clearTimeout(debounceTimers.get(filename));
     debounceTimers.set(filename, setTimeout(() => {
@@ -298,6 +537,7 @@ function startServer() {
         const eventsFile = path.join(STATE_DIR, 'events');
         if (fs.existsSync(eventsFile)) fs.unlinkSync(eventsFile);
         console.log(JSON.stringify({ type: 'screen-added', file: filePath }));
+        maybeOpenBrowser();
       } else {
         console.log(JSON.stringify({ type: 'screen-updated', file: filePath }));
       }
@@ -317,6 +557,11 @@ function startServer() {
     );
     watcher.close();
     clearInterval(lifecycleCheck);
+    // Close any upgraded WebSocket sockets so server.close() can complete and
+    // the process actually exits instead of lingering on an open connection.
+    for (const socket of clients) {
+      try { socket.destroy(); } catch (e) { /* already gone */ }
+    }
     server.close(() => process.exit(0));
   }
 
@@ -325,11 +570,11 @@ function startServer() {
     try { process.kill(ownerPid, 0); return true; } catch (e) { return e.code === 'EPERM'; }
   }
 
-  // Check every 60s: exit if owner process died or idle for 30 minutes
+  // Periodically exit if the owner process died or we've been idle too long.
   const lifecycleCheck = setInterval(() => {
     if (!ownerAlive()) shutdown('owner process exited');
     else if (Date.now() - lastActivity > IDLE_TIMEOUT_MS) shutdown('idle timeout');
-  }, 60 * 1000);
+  }, LIFECYCLE_CHECK_MS);
   lifecycleCheck.unref();
 
   // Validate owner PID at startup. If it's already dead, the PID resolution
@@ -345,19 +590,68 @@ function startServer() {
     }
   }
 
-  server.listen(PORT, HOST, () => {
+  // If the preferred port is already taken (e.g. a previous server is still
+  // alive), fall back to a random port once instead of failing.
+  let triedFallback = false;
+
+  function onListen() {
+    // Cookie name keys on the ACTUAL bound port (may differ from the preferred
+    // one after an EADDRINUSE fallback) so it can't collide with another server's
+    // cookie in the shared localhost jar.
+    COOKIE_NAME = 'brainstorm-key-' + PORT;
+    // Record the bound port AND token so the next restart of this session reuses
+    // them — but ONLY when we got our preferred port. On a fallback we bound a
+    // *different* port because someone else holds the preferred one; persisting
+    // would overwrite the shared files and strand that other session's open tab.
+    if (PORT_FILE && !triedFallback) {
+      try { fs.writeFileSync(PORT_FILE, String(PORT)); } catch (e) { /* best effort */ }
+      if (TOKEN_FILE) {
+        try {
+          fs.writeFileSync(TOKEN_FILE, TOKEN, { mode: 0o600 });
+          chmodOwnerOnly(TOKEN_FILE);
+        } catch (e) { /* best effort */ }
+      }
+    }
     const info = JSON.stringify({
       type: 'server-started', port: Number(PORT), host: HOST,
-      url_host: URL_HOST, url: 'http://' + URL_HOST + ':' + PORT,
-      screen_dir: CONTENT_DIR, state_dir: STATE_DIR
+      url_host: URL_HOST, url: companionUrl(),
+      screen_dir: CONTENT_DIR, state_dir: STATE_DIR, idle_timeout_ms: IDLE_TIMEOUT_MS
     });
     console.log(info);
-    fs.writeFileSync(path.join(STATE_DIR, 'server-info'), info + '\n');
+    // server-info embeds the key — keep it owner-only.
+    fs.writeFileSync(path.join(STATE_DIR, 'server-info'), info + '\n', { mode: 0o600 });
+  }
+
+  server.on('error', (err) => {
+    if (err.code === 'EADDRINUSE' && !triedFallback) {
+      if (tokenSource === 'env') {
+        console.error('Server failed to bind: preferred port is in use and BRAINSTORM_TOKEN is set; refusing fallback with explicit token');
+        process.exit(1);
+      }
+      triedFallback = true;
+      PORT = randomPort();
+      if (tokenSource === 'file') {
+        TOKEN = generateToken();
+        tokenSource = 'generated-fallback';
+      }
+      server.listen(PORT, HOST, onListen);
+    } else {
+      console.error('Server failed to bind:', err.message);
+      process.exit(1);
+    }
   });
+  server.listen(PORT, HOST, onListen);
 }
 
 if (require.main === module) {
   startServer();
 }
 
-module.exports = { computeAcceptKey, encodeFrame, decodeFrame, OPCODES, MAX_FRAME_PAYLOAD_BYTES };
+module.exports = {
+  computeAcceptKey,
+  encodeFrame,
+  decodeFrame,
+  browserLauncherForPlatform,
+  OPCODES,
+  MAX_FRAME_PAYLOAD_BYTES
+};

skills/brainstorming/scripts/start-server.sh

@@ -11,6 +11,9 @@
 #   --host <bind-host>    Host/interface to bind (default: 127.0.0.1).
 #                         Use 0.0.0.0 in remote/containerized environments.
 #   --url-host <host>     Hostname shown in returned URL JSON.
+#   --idle-timeout-minutes <n>  Shut down after n minutes idle (default 240 = 4h).
+#   --open                Auto-open the browser on the first screen (use only
+#                         after the user approves the visual companion).
 #   --foreground          Run server in the current terminal (no backgrounding).
 #   --background          Force background mode (overrides Codex auto-foreground).
 
@@ -22,6 +25,7 @@ FOREGROUND="false"
 FORCE_BACKGROUND="false"
 BIND_HOST="127.0.0.1"
 URL_HOST=""
+IDLE_TIMEOUT_MINUTES=""
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --project-dir)
@@ -36,6 +40,14 @@ while [[ $# -gt 0 ]]; do
       URL_HOST="$2"
       shift 2
       ;;
+    --idle-timeout-minutes)
+      IDLE_TIMEOUT_MINUTES="$2"
+      shift 2
+      ;;
+    --open)
+      export BRAINSTORM_OPEN=1
+      shift
+      ;;
     --foreground|--no-daemon)
       FOREGROUND="true"
       shift
@@ -59,6 +71,29 @@ if [[ -z "$URL_HOST" ]]; then
   fi
 fi
 
+if [[ -n "$IDLE_TIMEOUT_MINUTES" ]]; then
+  if ! [[ "$IDLE_TIMEOUT_MINUTES" =~ ^[0-9]+$ ]] || [[ "$IDLE_TIMEOUT_MINUTES" -lt 1 ]]; then
+    echo "{\"error\": \"--idle-timeout-minutes must be a positive integer\"}"
+    exit 1
+  fi
+  export BRAINSTORM_IDLE_TIMEOUT_MS=$(( IDLE_TIMEOUT_MINUTES * 60 * 1000 ))
+fi
+
+is_windows_like_shell() {
+  case "${OSTYPE:-}" in
+    msys*|cygwin*|mingw*) return 0 ;;
+  esac
+  if [[ -n "${MSYSTEM:-}" ]]; then
+    return 0
+  fi
+  local uname_s
+  uname_s="$(uname -s 2>/dev/null || true)"
+  case "$uname_s" in
+    MSYS*|MINGW*|CYGWIN*) return 0 ;;
+  esac
+  return 1
+}
+
 # Some environments reap detached/background processes. Auto-foreground when detected.
 if [[ -n "${CODEX_CI:-}" && "$FOREGROUND" != "true" && "$FORCE_BACKGROUND" != "true" ]]; then
   FOREGROUND="true"
@@ -66,19 +101,24 @@ fi
 
 # Windows/Git Bash reaps nohup background processes. Auto-foreground when detected.
 if [[ "$FOREGROUND" != "true" && "$FORCE_BACKGROUND" != "true" ]]; then
-  case "${OSTYPE:-}" in
-    msys*|cygwin*|mingw*) FOREGROUND="true" ;;
-  esac
-  if [[ -n "${MSYSTEM:-}" ]]; then
+  if is_windows_like_shell; then
     FOREGROUND="true"
   fi
 fi
 
+# Session files (server.log, server-info, .last-token) embed the session key —
+# keep everything this script and the server create owner-only.
+umask 077
+
 # Generate unique session directory
 SESSION_ID="$$-$(date +%s)"
 
 if [[ -n "$PROJECT_DIR" ]]; then
   SESSION_DIR="${PROJECT_DIR}/.superpowers/brainstorm/${SESSION_ID}"
+  # Persist the bound port and key per project so a restart reuses them and an
+  # already-open browser tab reconnects to the same URL with a valid cookie.
+  export BRAINSTORM_PORT_FILE="${PROJECT_DIR}/.superpowers/brainstorm/.last-port"
+  export BRAINSTORM_TOKEN_FILE="${PROJECT_DIR}/.superpowers/brainstorm/.last-token"
 else
   SESSION_DIR="/tmp/brainstorm-${SESSION_ID}"
 fi
@@ -86,10 +126,21 @@ fi
 STATE_DIR="${SESSION_DIR}/state"
 PID_FILE="${STATE_DIR}/server.pid"
 LOG_FILE="${STATE_DIR}/server.log"
+SERVER_ID_FILE="${STATE_DIR}/server-instance-id"
 
 # Create fresh session directory with content and state peers
 mkdir -p "${SESSION_DIR}/content" "$STATE_DIR"
 
+SERVER_ID=""
+if [[ -r /dev/urandom ]]; then
+  SERVER_ID="$(od -An -N24 -tx1 /dev/urandom 2>/dev/null | tr -d ' \n' || true)"
+fi
+if ! [[ "$SERVER_ID" =~ ^[A-Za-z0-9_-]{32,64}$ ]]; then
+  SERVER_ID="$(printf '%08x%08x%08x%08x' "$$" "$(date +%s)" "${RANDOM:-0}" "${RANDOM:-0}")"
+fi
+printf '%s\n' "$SERVER_ID" > "$SERVER_ID_FILE"
+chmod 600 "$SERVER_ID_FILE" 2>/dev/null || true
+
 # Kill any existing server
 if [[ -f "$PID_FILE" ]]; then
   old_pid=$(cat "$PID_FILE")
@@ -97,7 +148,7 @@ if [[ -f "$PID_FILE" ]]; then
   rm -f "$PID_FILE"
 fi
 
-cd "$SCRIPT_DIR"
+cd "$SCRIPT_DIR" || exit 1
 
 # Resolve the harness PID (grandparent of this script).
 # $PPID is the ephemeral shell the harness spawned to run us — it dies
@@ -111,16 +162,13 @@ fi
 # Passing a PID node cannot verify causes server to log owner-pid-invalid
 # and self-terminate at the 60-second lifecycle check. Clear it so the
 # watchdog is disabled and the idle timeout becomes the only shutdown trigger.
-case "${OSTYPE:-}" in
-  msys*|cygwin*|mingw*) OWNER_PID="" ;;
-esac
-if [[ -n "${MSYSTEM:-}" ]]; then
+if is_windows_like_shell; then
   OWNER_PID=""
 fi
 
 # Foreground mode for environments that reap detached/background processes.
 if [[ "$FOREGROUND" == "true" ]]; then
-  env BRAINSTORM_DIR="$SESSION_DIR" BRAINSTORM_HOST="$BIND_HOST" BRAINSTORM_URL_HOST="$URL_HOST" BRAINSTORM_OWNER_PID="$OWNER_PID" node server.cjs &
+  env BRAINSTORM_DIR="$SESSION_DIR" BRAINSTORM_HOST="$BIND_HOST" BRAINSTORM_URL_HOST="$URL_HOST" BRAINSTORM_OWNER_PID="$OWNER_PID" node server.cjs "--brainstorm-server-id=$SERVER_ID" &
   SERVER_PID=$!
   echo "$SERVER_PID" > "$PID_FILE"
   wait "$SERVER_PID"
@@ -129,13 +177,13 @@ fi
 
 # Start server, capturing output to log file
 # Use nohup to survive shell exit; disown to remove from job table
-nohup env BRAINSTORM_DIR="$SESSION_DIR" BRAINSTORM_HOST="$BIND_HOST" BRAINSTORM_URL_HOST="$URL_HOST" BRAINSTORM_OWNER_PID="$OWNER_PID" node server.cjs > "$LOG_FILE" 2>&1 &
+nohup env BRAINSTORM_DIR="$SESSION_DIR" BRAINSTORM_HOST="$BIND_HOST" BRAINSTORM_URL_HOST="$URL_HOST" BRAINSTORM_OWNER_PID="$OWNER_PID" node server.cjs "--brainstorm-server-id=$SERVER_ID" > "$LOG_FILE" 2>&1 &
 SERVER_PID=$!
 disown "$SERVER_PID" 2>/dev/null
 echo "$SERVER_PID" > "$PID_FILE"
 
 # Wait for server-started message (check log file)
-for i in {1..50}; do
+for _ in {1..50}; do
   if grep -q "server-started" "$LOG_FILE" 2>/dev/null; then
     # Verify server is still alive after a short window (catches process reapers)
     alive="true"

skills/brainstorming/scripts/stop-server.sh

@@ -15,15 +15,78 @@ fi
 
 STATE_DIR="${SESSION_DIR}/state"
 PID_FILE="${STATE_DIR}/server.pid"
+SERVER_ID_FILE="${STATE_DIR}/server-instance-id"
+
+mark_stopped() {
+  local reason="$1"
+  rm -f "${STATE_DIR}/server-info"
+  printf '{"reason":"%s","timestamp":%s}\n' "$reason" "$(date +%s)" > "${STATE_DIR}/server-stopped"
+}
+
+read_expected_server_id() {
+  [[ -f "$SERVER_ID_FILE" ]] || return 1
+  local id
+  id="$(tr -d '\r\n' < "$SERVER_ID_FILE" 2>/dev/null || true)"
+  [[ "$id" =~ ^[A-Za-z0-9_-]{32,64}$ ]] || return 1
+  printf '%s\n' "$id"
+}
+
+command_line_for_pid() {
+  local pid="$1"
+  if [[ -r "/proc/$pid/cmdline" ]]; then
+    tr '\0' '\n' < "/proc/$pid/cmdline" 2>/dev/null || true
+    return 0
+  fi
+  ps -ww -p "$pid" -o command= 2>/dev/null || ps -f -p "$pid" 2>/dev/null | sed '1d' || true
+}
+
+command_has_server_id() {
+  local pid="$1"
+  local expected="$2"
+  local expected_arg="--brainstorm-server-id=$expected"
+  if [[ -r "/proc/$pid/cmdline" ]]; then
+    local arg
+    while IFS= read -r -d '' arg || [[ -n "$arg" ]]; do
+      [[ "$arg" == "$expected_arg" ]] && return 0
+    done < "/proc/$pid/cmdline"
+    return 1
+  fi
+  local command_line
+  command_line="$(command_line_for_pid "$pid")"
+  [[ -n "$command_line" ]] || return 1
+  case " $command_line " in
+    *" $expected_arg "*) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+# Confirm a PID has this session's per-start instance id, not just a familiar
+# process name. Ambiguous or legacy metadata fails closed as stale_pid.
+is_brainstorm_server() {
+  kill -0 "$1" 2>/dev/null || return 1
+  local expected_id
+  expected_id="$(read_expected_server_id)" || return 1
+  command_has_server_id "$1" "$expected_id" || return 1
+  return 0
+}
 
 if [[ -f "$PID_FILE" ]]; then
   pid=$(cat "$PID_FILE")
 
+  # Refuse to signal a PID we can't prove is our server. A stale pid file may
+  # point at an unrelated process after a reboot/PID wraparound.
+  if ! is_brainstorm_server "$pid"; then
+    rm -f "$PID_FILE" "$SERVER_ID_FILE"
+    mark_stopped "stale_pid"
+    echo '{"status": "stale_pid"}'
+    exit 0
+  fi
+
   # Try to stop gracefully, fallback to force if still alive
   kill "$pid" 2>/dev/null || true
 
   # Wait for graceful shutdown (up to ~2s)
-  for i in {1..20}; do
+  for _ in {1..20}; do
     if ! kill -0 "$pid" 2>/dev/null; then
       break
     fi
@@ -43,7 +106,8 @@ if [[ -f "$PID_FILE" ]]; then
     exit 1
   fi
 
-  rm -f "$PID_FILE" "${STATE_DIR}/server.log"
+  rm -f "$PID_FILE" "$SERVER_ID_FILE" "${STATE_DIR}/server.log"
+  mark_stopped "stop-server.sh"
 
   # Only delete ephemeral /tmp directories
   if [[ "$SESSION_DIR" == /tmp/* ]]; then

skills/brainstorming/visual-companion.md

@@ -33,15 +33,25 @@ The server watches a directory for HTML files and serves the newest one to the b
 ## Starting a Session
 
 ```bash
-# Start server with persistence (mockups saved to project)
-scripts/start-server.sh --project-dir /path/to/project
+# Start AFTER the user approves the companion. --open auto-opens their browser on
+# the first screen; --project-dir persists mockups and enables same-port restart.
+scripts/start-server.sh --project-dir /path/to/project --open
 
-# Returns: {"type":"server-started","port":52341,"url":"http://localhost:52341",
+# Returns: {"type":"server-started","port":52341,
+#           "url":"http://localhost:52341/?key=ab12…",
 #           "screen_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000/content",
 #           "state_dir":"/path/to/project/.superpowers/brainstorm/12345-1706000000/state"}
 ```
 
-Save `screen_dir` and `state_dir` from the response. Tell user to open the URL.
+Save `screen_dir` and `state_dir` from the response. With `--open`, the browser opens itself when you push the first screen — you don't need to ask the user to open it, but still share the URL as a fallback (headless/remote setups won't auto-open).
+
+**The URL contains a session key (`?key=…`).** The server rejects any request
+without it, so always give the user the **complete** URL from the `url` field —
+never strip the query string, and never hand out a bare `http://host:port`. The
+key gates HTTP and WebSocket access so a stray browser tab or another machine on
+the network can't read the screens or inject events. After the first load the
+browser remembers the key via a cookie, so reloads and `/files/*` assets work
+without repeating it.
 
 **Finding connection info:** The server writes its startup JSON to `$STATE_DIR/server-info`. If you launched the server in the background and didn't capture stdout, read that file to get the URL and port. When using `--project-dir`, check `<project>/.superpowers/brainstorm/` for the session directory.
 
@@ -52,7 +62,7 @@ Save `screen_dir` and `state_dir` from the response. Tell user to open the URL.
 **Claude Code:**
 ```bash
 # Default mode works — the script backgrounds the server itself.
-scripts/start-server.sh --project-dir /path/to/project
+scripts/start-server.sh --project-dir /path/to/project --open
 ```
 
 On Windows, the script auto-detects and switches to foreground mode (which blocks the tool call). Use `run_in_background: true` on the Bash tool call so the server survives across conversation turns, then read `$STATE_DIR/server-info` on the next turn to get the URL and port.
@@ -61,14 +71,14 @@ On Windows, the script auto-detects and switches to foreground mode (which block
 ```bash
 # Codex reaps background processes. The script auto-detects CODEX_CI and
 # switches to foreground mode. Run it normally — no extra flags needed.
-scripts/start-server.sh --project-dir /path/to/project
+scripts/start-server.sh --project-dir /path/to/project --open
 ```
 
 **Gemini CLI:**
 ```bash
 # Use --foreground and set is_background: true on your shell tool call
 # so the process survives across turns
-scripts/start-server.sh --project-dir /path/to/project --foreground
+scripts/start-server.sh --project-dir /path/to/project --open --foreground
 ```
 
 **Copilot CLI:**
@@ -76,7 +86,7 @@ scripts/start-server.sh --project-dir /path/to/project --foreground
 # Use --foreground and start the server via the bash tool with mode: "async"
 # so the process survives across turns. Capture the returned shellId for
 # read_bash / stop_bash if you need to interact with it later.
-scripts/start-server.sh --project-dir /path/to/project --foreground
+scripts/start-server.sh --project-dir /path/to/project --open --foreground
 ```
 
 **Other environments:** The server must keep running in the background across conversation turns. If your environment reaps detached processes, use `--foreground` and launch the command with your platform's background execution mechanism.
@@ -95,7 +105,7 @@ Use `--url-host` to control what hostname is printed in the returned URL JSON.
 ## The Loop
 
 1. **Check server is alive**, then **write HTML** to a new file in `screen_dir`:
-   - Before each write, check that `$STATE_DIR/server-info` exists. If it doesn't (or `$STATE_DIR/server-stopped` exists), the server has shut down — restart it with `start-server.sh` before continuing. The server auto-exits after 30 minutes of inactivity.
+   - **Required: confirm the server is alive before referring to the URL or pushing a screen.** Check that `$STATE_DIR/server-info` exists and `$STATE_DIR/server-stopped` does not. If it has shut down, restart it with `start-server.sh` using the **same `--project-dir`** — it reuses the same port, so the user's open tab reconnects on its own (it shows a "paused" overlay while the server is down) and you don't need to send a new URL. The server auto-exits after 4 hours idle (configurable with `--idle-timeout-minutes`).
    - Use semantic filenames: `platform.html`, `visual-style.html`, `layout.html`
    - **Never reuse filenames** — each screen gets a fresh file
    - Use your file-creation tool — **never use cat/heredoc** (dumps noise into terminal)

tests/brainstorm-server/auth.test.js

@@ -0,0 +1,312 @@
+/**
+ * Security tests for the brainstorm server's per-session key.
+ *
+ * The companion server is reachable by any local browser tab (default loopback
+ * bind) and by any host that can route to it (remote `--host 0.0.0.0` bind).
+ * A per-session secret key gates every endpoint so that neither a browser
+ * confused-deputy nor a direct remote client can read screens/files or inject
+ * events into state/events (prompt injection into a live agent session).
+ *
+ * Auth = a valid `?key=<token>` query param OR a valid session cookie.
+ *
+ * Uses the `ws` npm package as a test client (test-only dependency).
+ */
+
+const { spawn } = require('child_process');
+const http = require('http');
+const WebSocket = require('ws');
+const fs = require('fs');
+const path = require('path');
+const assert = require('assert');
+
+const SERVER_PATH = path.join(__dirname, '../../skills/brainstorming/scripts/server.cjs');
+const TEST_PORT = 3335;
+const TEST_DIR = '/tmp/brainstorm-auth-test';
+const CONTENT_DIR = path.join(TEST_DIR, 'content');
+const TOKEN = 'testtoken-0123456789abcdef0123456789abcdef';
+const COOKIE_NAME = `brainstorm-key-${TEST_PORT}`;
+const EXPECTED_SECURITY_HEADERS = {
+  'referrer-policy': 'no-referrer',
+  'cache-control': 'no-store',
+  'x-frame-options': 'DENY',
+  'content-security-policy': "frame-ancestors 'none'",
+  'cross-origin-resource-policy': 'same-origin'
+};
+
+function cleanup() {
+  if (fs.existsSync(TEST_DIR)) fs.rmSync(TEST_DIR, { recursive: true });
+}
+
+async function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+// Raw HTTP GET with optional key query and Cookie header.
+function get(pathname, { key, cookie } = {}) {
+  const url = `http://localhost:${TEST_PORT}${pathname}` + (key !== undefined ? `?key=${key}` : '');
+  const headers = {};
+  if (cookie) headers['Cookie'] = cookie;
+  return new Promise((resolve, reject) => {
+    http.get(url, { headers }, (res) => {
+      let data = '';
+      res.on('data', chunk => data += chunk);
+      res.on('end', () => resolve({ status: res.statusCode, headers: res.headers, body: data }));
+    }).on('error', reject);
+  });
+}
+
+// Try to open a WebSocket; resolve 'opened' or 'rejected'.
+function wsConnect({ key, cookie, origin } = {}) {
+  const url = `ws://localhost:${TEST_PORT}/` + (key !== undefined ? `?key=${key}` : '');
+  const headers = {};
+  if (cookie) headers['Cookie'] = cookie;
+  if (origin) headers['Origin'] = origin;
+  const opts = Object.keys(headers).length ? { headers } : {};
+  const ws = new WebSocket(url, opts);
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (outcome) => { if (!settled) { settled = true; resolve({ outcome, ws }); } };
+    ws.on('open', () => done('opened'));
+    ws.on('error', () => done('rejected'));
+    ws.on('close', () => done('rejected'));
+    setTimeout(() => done('rejected'), 1500);
+  });
+}
+
+function startServer() {
+  return spawn('node', [SERVER_PATH], {
+    env: { ...process.env, BRAINSTORM_PORT: TEST_PORT, BRAINSTORM_DIR: TEST_DIR, BRAINSTORM_TOKEN: TOKEN }
+  });
+}
+
+function assertSecurityHeaders(headers) {
+  for (const [name, value] of Object.entries(EXPECTED_SECURITY_HEADERS)) {
+    assert.strictEqual(headers[name], value, `${name} should be ${value}`);
+  }
+}
+
+function runBootstrapScript(html, sessionStorage) {
+  const match = html.match(/<script>\n([\s\S]*?)\n<\/script>/);
+  assert(match, 'bootstrap response should contain a script block');
+  const replacements = [];
+  const location = { replace(url) { replacements.push(url); } };
+  new Function('sessionStorage', 'location', match[1])(sessionStorage, location);
+  return replacements;
+}
+
+async function waitForServer(server) {
+  let stdout = '', stderr = '';
+  return new Promise((resolve, reject) => {
+    server.stdout.on('data', (d) => {
+      stdout += d.toString();
+      if (stdout.includes('server-started')) resolve({ stdout });
+    });
+    server.stderr.on('data', (d) => { stderr += d.toString(); });
+    server.on('error', reject);
+    setTimeout(() => reject(new Error(`Server didn't start. stderr: ${stderr}`)), 5000);
+  });
+}
+
+function serverStartedMessage(out) {
+  const line = out.trim().split('\n').find(l => l.includes('server-started'));
+  assert(line, 'server-started JSON should be present');
+  return JSON.parse(line);
+}
+
+function assertStartedOnExpectedPort(out) {
+  const msg = serverStartedMessage(out);
+  assert.strictEqual(
+    msg.port,
+    TEST_PORT,
+    `auth.test.js expected fixed port ${TEST_PORT}, got ${msg.port}; fixed-port tests must not run through fallback`
+  );
+  return msg;
+}
+
+async function runTests() {
+  cleanup();
+  fs.mkdirSync(CONTENT_DIR, { recursive: true });
+  fs.writeFileSync(path.join(CONTENT_DIR, 'screen.html'), '<h2>Secret screen</h2>');
+  fs.writeFileSync(path.join(CONTENT_DIR, 'asset.txt'), 'secret asset');
+
+  const server = startServer();
+  let stdoutAccum = '';
+  server.stdout.on('data', (d) => { stdoutAccum += d.toString(); });
+
+  let passed = 0, failed = 0;
+  async function test(name, fn) {
+    try { await fn(); console.log(`  PASS: ${name}`); passed++; }
+    catch (e) { console.log(`  FAIL: ${name}`); console.log(`    ${e.message}`); failed++; }
+  }
+
+  try {
+    const { stdout: initialStdout } = await waitForServer(server);
+    assertStartedOnExpectedPort(initialStdout);
+
+    console.log('\n--- Startup URL ---');
+
+    await test('server-started url includes the session key', () => {
+      const msg = serverStartedMessage(initialStdout);
+      assert(msg.url.includes(`key=${TOKEN}`), `url should carry the key, got: ${msg.url}`);
+    });
+
+    console.log('\n--- HTTP / gate ---');
+
+    await test('GET / without key is rejected with 403', async () => {
+      const res = await get('/');
+      assert.strictEqual(res.status, 403, 'no-key request must be 403');
+    });
+
+    await test('403 page names "coding agent" and the key', async () => {
+      const res = await get('/');
+      assert(/coding agent/i.test(res.body), '403 body should reference the coding agent');
+      assert(/key/i.test(res.body), '403 body should mention the key');
+    });
+
+    await test('403 responses include leak-reduction and anti-framing headers', async () => {
+      const res = await get('/');
+      assert.strictEqual(res.status, 403);
+      assertSecurityHeaders(res.headers);
+    });
+
+    await test('GET / with wrong key is rejected with 403', async () => {
+      const res = await get('/', { key: 'wrong-token' });
+      assert.strictEqual(res.status, 403);
+    });
+
+    await test('GET / with wrong key and valid cookie is rejected with 403', async () => {
+      const res = await get('/', { key: 'wrong-token', cookie: `${COOKIE_NAME}=${TOKEN}` });
+      assert.strictEqual(res.status, 403, 'explicit wrong query key must not fall back to cookie auth');
+    });
+
+    await test('GET / with valid query returns bootstrap instead of screen content', async () => {
+      const res = await get('/', { key: TOKEN });
+      assert.strictEqual(res.status, 200);
+      assert(res.body.includes('sessionStorage'), 'bootstrap should store the session key in tab storage');
+      assert(res.body.includes('location.replace'), 'bootstrap should navigate to the bare root URL');
+      assert(!res.body.includes('Secret screen'), 'bootstrap must not serve screen HTML at the keyed URL');
+    });
+
+    await test('bootstrap strips the key URL even when sessionStorage write fails', async () => {
+      const res = await get('/', { key: TOKEN });
+      assert.strictEqual(res.status, 200);
+      let replacements;
+      assert.doesNotThrow(() => {
+        replacements = runBootstrapScript(res.body, {
+        setItem() { throw new Error('storage blocked'); }
+        });
+      });
+      assert.deepStrictEqual(replacements, ['/']);
+    });
+
+    await test('HTML responses include leak-reduction and anti-framing headers', async () => {
+      const res = await get('/', { key: TOKEN });
+      assert.strictEqual(res.status, 200);
+      assertSecurityHeaders(res.headers);
+    });
+
+    await test('valid key load sets an HttpOnly SameSite=Strict cookie', async () => {
+      const res = await get('/', { key: TOKEN });
+      const setCookie = (res.headers['set-cookie'] || []).join('; ');
+      assert(setCookie.includes(`${COOKIE_NAME}=${TOKEN}`), `should set ${COOKIE_NAME}`);
+      assert(/HttpOnly/i.test(setCookie), 'cookie should be HttpOnly');
+      assert(/SameSite=Strict/i.test(setCookie), 'cookie should be SameSite=Strict');
+    });
+
+    await test('GET / with valid cookie (no query key) serves the screen', async () => {
+      const res = await get('/', { cookie: `${COOKIE_NAME}=${TOKEN}` });
+      assert.strictEqual(res.status, 200);
+      assert(res.body.includes('Secret screen'), 'cookie-authenticated bare root should serve the screen');
+      assert(!res.body.includes("location.replace('/');"), 'bare screen response should not be the bootstrap page');
+    });
+
+    console.log('\n--- HTTP /files gate ---');
+
+    await test('GET /files without key is rejected with 403', async () => {
+      const res = await get('/files/asset.txt');
+      assert.strictEqual(res.status, 403);
+    });
+
+    await test('GET /files with valid key serves the file', async () => {
+      const res = await get('/files/asset.txt', { key: TOKEN });
+      assert.strictEqual(res.status, 200);
+      assert(res.body.includes('secret asset'));
+    });
+
+    await test('/files responses include leak-reduction and anti-framing headers', async () => {
+      const res = await get('/files/asset.txt', { key: TOKEN });
+      assert.strictEqual(res.status, 200);
+      assertSecurityHeaders(res.headers);
+    });
+
+    console.log('\n--- WebSocket gate ---');
+
+    await test('WS upgrade without key is rejected', async () => {
+      const { outcome, ws } = await wsConnect();
+      ws.close();
+      assert.strictEqual(outcome, 'rejected', 'unauthenticated WS must not open');
+    });
+
+    await test('WS upgrade with valid key opens', async () => {
+      const { outcome, ws } = await wsConnect({ key: TOKEN });
+      ws.close();
+      assert.strictEqual(outcome, 'opened');
+    });
+
+    await test('WS upgrade with valid cookie opens', async () => {
+      const { outcome, ws } = await wsConnect({ cookie: `${COOKIE_NAME}=${TOKEN}` });
+      ws.close();
+      assert.strictEqual(outcome, 'opened');
+    });
+
+    await test('WS upgrade with valid cookie and same-origin Origin opens', async () => {
+      const { outcome, ws } = await wsConnect({
+        cookie: `${COOKIE_NAME}=${TOKEN}`,
+        origin: `http://localhost:${TEST_PORT}`
+      });
+      ws.close();
+      assert.strictEqual(outcome, 'opened');
+    });
+
+    await test('WS upgrade with valid cookie but cross-origin Origin is rejected', async () => {
+      const eventsFile = path.join(TEST_DIR, 'state', 'events');
+      if (fs.existsSync(eventsFile)) fs.unlinkSync(eventsFile);
+
+      const { outcome, ws } = await wsConnect({
+        cookie: `${COOKIE_NAME}=${TOKEN}`,
+        origin: 'http://localhost:9999'
+      });
+      if (outcome === 'opened') {
+        ws.send(JSON.stringify({ type: 'choice', choice: 'attacker-injected', text: 'local attacker probe' }));
+        await sleep(300);
+      }
+      ws.close();
+
+      assert.strictEqual(outcome, 'rejected', 'cross-origin browser WS must not open even with cookie');
+      assert(!fs.existsSync(eventsFile), 'cross-origin WS must not write state/events');
+    });
+
+    console.log('\n--- Robustness (A3) ---');
+
+    await test('null payload over an authed WS does not crash the server', async () => {
+      const { ws } = await wsConnect({ key: TOKEN });
+      ws.send('null');
+      await sleep(300);
+      const res = await get('/', { key: TOKEN });
+      assert.strictEqual(res.status, 200, 'server must still respond after null payload');
+      ws.close();
+    });
+
+    console.log(`\n--- Results: ${passed} passed, ${failed} failed ---`);
+    if (failed > 0) {
+      process.exitCode = 1;
+      return;
+    }
+  } finally {
+    server.kill();
+    await sleep(100);
+    cleanup();
+  }
+}
+
+runTests().catch(err => { console.error('Test failed:', err); process.exit(1); });

tests/brainstorm-server/browser-launcher.test.js

@@ -0,0 +1,66 @@
+const assert = require('assert');
+const {
+  browserLauncherForPlatform
+} = require('../../skills/brainstorming/scripts/server.cjs');
+
+let passed = 0;
+let failed = 0;
+
+async function test(name, fn) {
+  try {
+    await fn();
+    console.log(`  PASS: ${name}`);
+    passed++;
+  } catch (e) {
+    console.log(`  FAIL: ${name}`);
+    console.log(`    ${e.message}`);
+    failed++;
+  }
+}
+
+(async () => {
+  console.log('\n--- Browser Launcher ---');
+
+  await test('Windows launcher does not route URLs through cmd.exe', () => {
+    const url = 'http://localhost:54122/?key=abc&x=SAFE&echo=INJECTED';
+    const launcher = browserLauncherForPlatform(url, {
+      platform: 'win32',
+      osRelease: '10.0.26200',
+      env: {}
+    });
+
+    assert.deepStrictEqual(launcher, {
+      bin: 'rundll32.exe',
+      args: ['url.dll,FileProtocolHandler', url]
+    });
+    assert(!launcher.args.includes('/c'), 'Windows launcher must not pass /c to a command interpreter');
+  });
+
+  await test('WSL launcher does not route URLs through cmd.exe', () => {
+    const url = 'http://localhost:54122/?key=abc&x=SAFE&echo=INJECTED';
+    const launcher = browserLauncherForPlatform(url, {
+      platform: 'linux',
+      osRelease: '5.15.167.4-microsoft-standard-WSL2',
+      env: {}
+    });
+
+    assert.deepStrictEqual(launcher, {
+      bin: 'rundll32.exe',
+      args: ['url.dll,FileProtocolHandler', url]
+    });
+  });
+
+  await test('Linux launcher stays headless without a display', () => {
+    assert.strictEqual(
+      browserLauncherForPlatform('http://localhost:1/', {
+        platform: 'linux',
+        osRelease: '6.0.0',
+        env: {}
+      }),
+      null
+    );
+  });
+
+  console.log(`\n--- Results: ${passed} passed, ${failed} failed ---`);
+  if (failed > 0) process.exit(1);
+})();

tests/brainstorm-server/helper.test.js

@@ -0,0 +1,197 @@
+/**
+ * Tests for the injected browser client (helper.js).
+ *
+ * helper.js runs in the browser, so its DOM behaviour is exercised live; here we
+ * unit-test the pure reconnect-backoff function it exports and assert that the
+ * reconnect / status / tombstone wiring is present.
+ */
+
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const HELPER = path.join(__dirname, '../../skills/brainstorming/scripts/helper.js');
+
+const src = fs.readFileSync(HELPER, 'utf-8');
+
+// helper.js is browser code, and the repo is an ES module package, so a plain
+// require() won't surface its exports. Evaluate the source in a CommonJS sandbox
+// with no `window`, so only the exported pure helpers run (not the browser code).
+const moduleShim = { exports: {} };
+new Function('module', src)(moduleShim);
+const { nextReconnectDelay, MIN_RECONNECT_MS, MAX_RECONNECT_MS, TOMBSTONE_AFTER_MS } = moduleShim.exports;
+
+let passed = 0, failed = 0;
+function test(name, fn) {
+  try { fn(); console.log(`  PASS: ${name}`); passed++; }
+  catch (e) { console.log(`  FAIL: ${name}`); console.log(`    ${e.message}`); failed++; }
+}
+
+console.log('\n--- Backoff (pure) ---');
+
+test('doubles the delay each call', () => {
+  assert.strictEqual(nextReconnectDelay(500, 30000), 1000);
+  assert.strictEqual(nextReconnectDelay(1000, 30000), 2000);
+  assert.strictEqual(nextReconnectDelay(2000, 30000), 4000);
+});
+
+test('caps at the maximum', () => {
+  assert.strictEqual(nextReconnectDelay(20000, 30000), 30000);
+  assert.strictEqual(nextReconnectDelay(30000, 30000), 30000);
+});
+
+test('full progression from MIN caps at MAX and never exceeds it', () => {
+  const seq = [MIN_RECONNECT_MS];
+  let d = MIN_RECONNECT_MS;
+  for (let i = 0; i < 10; i++) { d = nextReconnectDelay(d, MAX_RECONNECT_MS); seq.push(d); }
+  assert.strictEqual(seq[0], 500);
+  assert.deepStrictEqual(seq.slice(0, 7), [500, 1000, 2000, 4000, 8000, 16000, 30000]);
+  assert(seq.every(v => v <= MAX_RECONNECT_MS), 'never exceeds max');
+  assert.strictEqual(seq[seq.length - 1], 30000, 'settles at the cap');
+});
+
+test('exposes sane constants', () => {
+  assert.strictEqual(MIN_RECONNECT_MS, 500);
+  assert.strictEqual(MAX_RECONNECT_MS, 30000);
+  assert(TOMBSTONE_AFTER_MS >= 5000, 'tombstone grace is at least a few seconds');
+});
+
+console.log('\n--- Wiring (source) ---');
+
+test('reflects all three connection states', () => {
+  assert(/Connected/.test(src) && /Reconnecting/.test(src) && /Disconnected/.test(src),
+    'should set Connected / Reconnecting / Disconnected status');
+  assert(src.includes("setProperty('--status-color'"), 'drives the status dot via --status-color');
+});
+
+test('renders a tombstone overlay when paused', () => {
+  assert(src.includes('bs-tombstone'), 'creates the tombstone element');
+  assert(/Companion paused/.test(src), 'tombstone explains the companion paused');
+});
+
+test('hardens reconnection (onerror, null socket, clears pending timer)', () => {
+  assert(src.includes('onerror'), 'handles onerror');
+  assert(/ws = null/.test(src), 'nulls the socket on close so sendEvent queues');
+  assert(src.includes('clearTimeout'), 'clears a pending reconnect before scheduling another');
+  assert(src.includes('nextReconnectDelay'), 'uses exponential backoff for reconnects');
+});
+
+test('reloads on recovery and on reload messages', () => {
+  assert(/location\.reload\(\)/.test(src), 'reloads to pick up restarted/updated content');
+});
+
+console.log('\n--- Reconnect state machine (mocked browser) ---');
+
+// Drive helper.js's browser code against mocked DOM/WebSocket/timers/clock so we
+// can exercise the actual reconnect/status/tombstone behaviour, not just grep it.
+function makeEnv() {
+  const state = { now: 1000, timers: [], reloads: 0, replacements: [], appended: [], sessionKey: 'stored-key-abc' };
+  const sockets = [];
+  const statusEl = { textContent: '', style: { setProperty() {} } };
+  class FakeWS {
+    constructor(url) { this.url = url; this.readyState = 0; this.onopen = this.onclose = this.onmessage = this.onerror = null; sockets.push(this); }
+    send() {}
+    close() { this.readyState = 3; if (this.onclose) this.onclose(); }
+    open() { this.readyState = 1; if (this.onopen) this.onopen(); }
+  }
+  FakeWS.OPEN = 1;
+  const env = {
+    module: { exports: {} },
+    window: {
+      location: {
+        host: 'localhost:7777',
+        reload() { state.reloads++; },
+        replace(url) { state.replacements.push(url); }
+      },
+      sessionStorage: { getItem: (key) => key === 'brainstorm-session-key' ? state.sessionKey : null }
+    },
+    document: {
+      querySelector: (s) => s === '.status' ? statusEl : null,
+      getElementById: () => null,
+      createElement: () => ({ style: {}, id: '' }),
+      addEventListener() {},
+      body: { appendChild: (el) => state.appended.push(el) }
+    },
+    WebSocket: FakeWS,
+    setTimeout: (fn, ms) => { state.timers.push({ fn, ms, fired: false, cleared: false }); return state.timers.length; },
+    clearTimeout: (id) => { if (state.timers[id - 1]) state.timers[id - 1].cleared = true; },
+    Date: { now: () => state.now },
+    console
+  };
+  return {
+    state, statusEl, sockets,
+    boot() { new Function(...Object.keys(env), src)(...Object.values(env)); },
+    advance(ms) { state.now += ms; },
+    last() { return sockets[sockets.length - 1]; },
+    fireReconnect() {
+      const t = [...state.timers].reverse().find(x => !x.fired && !x.cleared);
+      if (!t) throw new Error('no reconnect scheduled');
+      t.fired = true; t.fn();
+    }
+  };
+}
+
+test('uses sessionStorage key in the WebSocket URL when present', () => {
+  const e = makeEnv();
+  e.state.sessionKey = 'stored-key-abc';
+  e.boot();
+  assert.strictEqual(e.sockets[0].url, 'ws://localhost:7777/?key=stored-key-abc');
+});
+
+test('uses cookie-only WebSocket URL when no sessionStorage key is present', () => {
+  const e = makeEnv();
+  e.state.sessionKey = null;
+  e.boot();
+  assert.strictEqual(e.sockets[0].url, 'ws://localhost:7777');
+});
+
+test('on disconnect shows Reconnecting and schedules a 500ms reconnect', () => {
+  const e = makeEnv(); e.boot();
+  e.last().open();
+  assert.strictEqual(e.statusEl.textContent, 'Connected');
+  e.last().close();
+  assert.strictEqual(e.statusEl.textContent, 'Reconnecting…');
+  assert.strictEqual(e.state.timers[e.state.timers.length - 1].ms, 500);
+});
+
+test('reconnect delay backs off 500 -> 1000 -> 2000', () => {
+  const e = makeEnv(); e.boot();
+  e.last().open(); e.last().close();
+  e.fireReconnect(); e.last().close();
+  e.fireReconnect(); e.last().close();
+  assert.deepStrictEqual(e.state.timers.map(t => t.ms).slice(0, 3), [500, 1000, 2000]);
+});
+
+test('shows the tombstone and Disconnected after the grace period', () => {
+  const e = makeEnv(); e.boot();
+  e.last().open(); e.last().close();
+  e.advance(20000);          // past TOMBSTONE_AFTER_MS while still down
+  e.fireReconnect(); e.last().close();
+  assert.strictEqual(e.statusEl.textContent, 'Disconnected');
+  assert.strictEqual(e.state.appended.length, 1, 'tombstone appended exactly once');
+});
+
+test('rebootstraps with stored key when a tombstoned connection comes back', () => {
+  const e = makeEnv(); e.boot();
+  e.last().open(); e.last().close();
+  e.advance(20000); e.fireReconnect(); e.last().close(); // tombstone now shown
+  assert.deepStrictEqual(e.state.replacements, []);
+  e.fireReconnect(); e.last().open();                    // server back (e.g. same-port restart)
+  assert.strictEqual(e.state.reloads, 0, 'stored-key recovery should not reload bare /');
+  assert.deepStrictEqual(e.state.replacements, ['/?key=stored-key-abc']);
+});
+
+test('reloads to recover when tombstoned and no sessionStorage key is present', () => {
+  const e = makeEnv();
+  e.state.sessionKey = null;
+  e.boot();
+  e.last().open(); e.last().close();
+  e.advance(20000); e.fireReconnect(); e.last().close(); // tombstone now shown
+  assert.strictEqual(e.state.reloads, 0);
+  e.fireReconnect(); e.last().open();                    // server back (e.g. cookie-only page)
+  assert.strictEqual(e.state.reloads, 1, 'reloads once on recovery');
+  assert.deepStrictEqual(e.state.replacements, []);
+});
+
+console.log(`\n--- Results: ${passed} passed, ${failed} failed ---`);
+if (failed > 0) process.exit(1);

tests/brainstorm-server/lifecycle.test.js

@@ -0,0 +1,515 @@
+/**
+ * Tests for the brainstorm server's lifecycle (idle timeout + shutdown).
+ *
+ * - The idle timeout is configurable (default 4h) and reported in server-info.
+ * - Idle shutdown must close any open WebSocket so the process actually exits,
+ *   not hang on a lingering connection.
+ * - start-server.sh exposes the timeout via --idle-timeout-minutes.
+ *
+ * Uses the `ws` npm package as a test client (test-only dependency).
+ */
+
+const { spawn, execFileSync } = require('child_process');
+const WebSocket = require('ws');
+const fs = require('fs');
+const path = require('path');
+const assert = require('assert');
+
+const SERVER = path.join(__dirname, '../../skills/brainstorming/scripts/server.cjs');
+const START = path.join(__dirname, '../../skills/brainstorming/scripts/start-server.sh');
+const STOP = path.join(__dirname, '../../skills/brainstorming/scripts/stop-server.sh');
+const sleep = ms => new Promise(r => setTimeout(r, ms));
+
+function waitForExit(child, timeoutMs = 2000) {
+  if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve(true);
+  return new Promise(resolve => {
+    let settled = false;
+    const finish = (exited) => {
+      if (settled) return;
+      settled = true;
+      resolve(exited);
+    };
+    child.once('exit', () => finish(true));
+    setTimeout(() => finish(false), timeoutMs);
+  });
+}
+
+async function killAndWait(child, timeoutMs = 2000) {
+  if (!child || child.exitCode !== null || child.signalCode !== null) return true;
+  const exited = waitForExit(child, timeoutMs);
+  child.kill();
+  if (await exited) return true;
+
+  child.kill('SIGKILL');
+  return waitForExit(child, 500);
+}
+
+async function waitForFile(file, timeoutMs = 3000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (fs.existsSync(file)) return true;
+    await sleep(50);
+  }
+  return fs.existsSync(file);
+}
+
+function firstServerStarted(out) {
+  return JSON.parse(out.trim().split('\n').find(l => l.includes('server-started')));
+}
+
+function openCaptureCommand(dir, marker) {
+  const scriptPath = path.resolve(dir, 'capture-open.cjs');
+  const markerPath = path.resolve(marker);
+  fs.writeFileSync(scriptPath,
+    "const fs = require('fs');\n" +
+    "fs.appendFileSync(process.argv[2], process.argv[3] + '\\n');\n");
+  return `node ${JSON.stringify(scriptPath)} ${JSON.stringify(markerPath)}`;
+}
+
+function httpStatus(port, key) {
+  return new Promise(resolve => {
+    const pathWithKey = key ? '/?key=' + encodeURIComponent(key) : '/';
+    require('http')
+      .get({ hostname: '127.0.0.1', port, path: pathWithKey }, res => {
+        res.resume();
+        resolve(res.statusCode);
+      })
+      .on('error', () => resolve(0));
+  });
+}
+
+function isWindowsLikeShell() {
+  return process.platform === 'win32' ||
+    /^msys|^cygwin|^mingw/i.test(process.env.OSTYPE || '') ||
+    !!process.env.MSYSTEM;
+}
+
+async function waitForStartedOutput(child, timeoutMs = 5000) {
+  let stdout = '';
+  let stderr = '';
+  child.stdout.on('data', d => { stdout += d.toString(); });
+  child.stderr.on('data', d => { stderr += d.toString(); });
+
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline && !stdout.includes('server-started') && child.exitCode === null) {
+    await sleep(50);
+  }
+
+  if (!stdout.includes('server-started')) {
+    throw new Error(`start-server.sh did not report server-started. exit=${child.exitCode} stdout=${stdout} stderr=${stderr}`);
+  }
+  return stdout;
+}
+
+function makeShellTempDir(prefix) {
+  return execFileSync('bash', ['-lc', `mktemp -d "\${TMPDIR:-/tmp}/${prefix}-XXXXXX"`], { encoding: 'utf8' }).trim();
+}
+
+function removeShellPath(p) {
+  execFileSync('bash', ['-lc', 'rm -rf "$1"', 'bash', p], { stdio: 'ignore' });
+}
+
+function newestSessionDir(projectDir) {
+  const sessionDir = execFileSync('bash', [
+    '-lc',
+    'find "$1/.superpowers/brainstorm" -mindepth 1 -maxdepth 1 -type d -print | sort | tail -1',
+    'bash',
+    projectDir
+  ], { encoding: 'utf8' }).trim();
+  assert(sessionDir, `expected at least one session dir under ${projectDir}/.superpowers/brainstorm`);
+  return sessionDir;
+}
+
+async function runTests() {
+  let passed = 0, failed = 0;
+  async function test(name, fn) {
+    try { await fn(); console.log(`  PASS: ${name}`); passed++; }
+    catch (e) { console.log(`  FAIL: ${name}`); console.log(`    ${e.message}`); failed++; }
+  }
+
+  await test('server-info reports the configured idle_timeout_ms', async () => {
+    const dir = fs.mkdtempSync('/tmp/bs-life-');
+    const srv = spawn('node', [SERVER], { env: { ...process.env, BRAINSTORM_PORT: 3401, BRAINSTORM_DIR: dir, BRAINSTORM_IDLE_TIMEOUT_MS: 1234567 } });
+    let out = ''; srv.stdout.on('data', d => out += d.toString());
+    for (let i = 0; i < 60 && !out.includes('server-started'); i++) await sleep(50);
+    try {
+      const info = firstServerStarted(out);
+      assert.strictEqual(info.idle_timeout_ms, 1234567, 'idle_timeout_ms should reflect the env override');
+    } finally {
+      await killAndWait(srv);
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  await test('idle shutdown closes an open WebSocket and the process exits', async () => {
+    const dir = fs.mkdtempSync('/tmp/bs-life-');
+    const srv = spawn('node', [SERVER], { env: { ...process.env, BRAINSTORM_PORT: 3402, BRAINSTORM_DIR: dir, BRAINSTORM_TOKEN: 'lifetoken', BRAINSTORM_IDLE_TIMEOUT_MS: 200, BRAINSTORM_LIFECYCLE_CHECK_MS: 100 } });
+    let out = ''; srv.stdout.on('data', d => out += d.toString());
+    let exited = false, code = null; srv.on('exit', c => { exited = true; code = c; });
+    for (let i = 0; i < 60 && !out.includes('server-started'); i++) await sleep(50);
+
+    const ws = new WebSocket('ws://localhost:3402/?key=lifetoken');
+    await new Promise((res, rej) => { ws.on('open', res); ws.on('error', rej); });
+
+    // 200ms idle, checked every 100ms — should shut down and exit well within 4s,
+    // *despite* the open WS, only if shutdown() closes client sockets.
+    for (let i = 0; i < 40 && !exited; i++) await sleep(100);
+
+    try {
+      assert(exited, 'process must exit after idle shutdown even with an open WebSocket');
+      assert.strictEqual(code, 0, 'should exit cleanly (0)');
+      assert(fs.existsSync(path.join(dir, 'state', 'server-stopped')), 'should write server-stopped');
+    } finally {
+      try { ws.close(); } catch (e) {}
+      if (!exited) await killAndWait(srv);
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  await test('start-server.sh --idle-timeout-minutes sets the timeout', async () => {
+    const dir = makeShellTempDir('bs-life');
+    let info = null;
+    let startProcess = null;
+    let sessionDir = null;
+    try {
+      if (isWindowsLikeShell()) {
+        startProcess = spawn('bash', [START, '--project-dir', dir, '--idle-timeout-minutes', '5']);
+        info = firstServerStarted(await waitForStartedOutput(startProcess));
+      } else {
+        const out = execFileSync('bash', [START, '--project-dir', dir, '--idle-timeout-minutes', '5', '--background'], { encoding: 'utf8' });
+        info = firstServerStarted(out);
+      }
+      sessionDir = newestSessionDir(dir);
+      assert.strictEqual(info.idle_timeout_ms, 5 * 60 * 1000, '5 minutes -> 300000 ms');
+    } finally {
+      if (sessionDir) execFileSync('bash', [STOP, sessionDir], { stdio: 'ignore' });
+      if (startProcess && !await waitForExit(startProcess, 3000)) {
+        await killAndWait(startProcess);
+      }
+      removeShellPath(dir);
+    }
+  });
+
+  await test('server-started URL brackets IPv6 URL hosts', async () => {
+    const dir = fs.mkdtempSync('/tmp/bs-ipv6-url-');
+    const srv = spawn('node', [SERVER], {
+      env: {
+        ...process.env,
+        BRAINSTORM_PORT: 3421,
+        BRAINSTORM_HOST: '127.0.0.1',
+        BRAINSTORM_URL_HOST: '::1',
+        BRAINSTORM_TOKEN: 'ipv6token',
+        BRAINSTORM_DIR: dir,
+        BRAINSTORM_LIFECYCLE_CHECK_MS: 100000
+      }
+    });
+    let out = ''; srv.stdout.on('data', d => out += d.toString());
+    try {
+      for (let i = 0; i < 60 && !out.includes('server-started'); i++) await sleep(50);
+      const info = firstServerStarted(out);
+      assert.strictEqual(info.url, 'http://[::1]:3421/?key=ipv6token');
+    } finally {
+      await killAndWait(srv);
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  await test('persists the bound port AND key, and restores both on restart', async () => {
+    const dir = fs.mkdtempSync('/tmp/bs-port-');
+    const portFile = path.join(dir, '.last-port');
+    const tokenFile = path.join(dir, '.last-token');
+    const env = { ...process.env, BRAINSTORM_PORT_FILE: portFile, BRAINSTORM_TOKEN_FILE: tokenFile, BRAINSTORM_LIFECYCLE_CHECK_MS: 100000 };
+
+    const a = spawn('node', [SERVER], { env: { ...env, BRAINSTORM_DIR: path.join(dir, 's1') } });
+    let outA = ''; a.stdout.on('data', d => outA += d.toString());
+    for (let i = 0; i < 60 && !outA.includes('server-started'); i++) await sleep(50);
+    const infoA = firstServerStarted(outA);
+    const keyA = new URL(infoA.url).searchParams.get('key');
+    assert(fs.existsSync(portFile) && fs.existsSync(tokenFile), 'should write the port and token files');
+    const exitedA = waitForExit(a);
+    a.kill();
+    assert(await exitedA, 'first server should exit before restart binds its port');
+
+    const b = spawn('node', [SERVER], { env: { ...env, BRAINSTORM_DIR: path.join(dir, 's2') } });
+    let outB = ''; b.stdout.on('data', d => outB += d.toString());
+    for (let i = 0; i < 60 && !outB.includes('server-started'); i++) await sleep(50);
+    const infoB = firstServerStarted(outB);
+    const keyB = new URL(infoB.url).searchParams.get('key');
+    await killAndWait(b);
+    fs.rmSync(dir, { recursive: true, force: true });
+
+    assert.strictEqual(infoB.port, infoA.port, 'restart should reuse the same port');
+    // Same key too — otherwise the open tab's cookie would 403 against the restart.
+    assert.strictEqual(keyB, keyA, 'restart should reuse the same session key');
+  });
+
+  await test('hardens existing persisted token file permissions', async () => {
+    const dir = fs.mkdtempSync('/tmp/bs-token-mode-');
+    const portFile = path.join(dir, '.last-port');
+    const tokenFile = path.join(dir, '.last-token');
+    const token = 'efefefefefefefefefefefefefefefef';
+    let srv = null;
+
+    try {
+      fs.writeFileSync(tokenFile, token, { mode: 0o644 });
+      fs.chmodSync(tokenFile, 0o644);
+      srv = spawn('node', [SERVER], {
+        env: {
+          ...process.env,
+          BRAINSTORM_DIR: path.join(dir, 's1'),
+          BRAINSTORM_PORT_FILE: portFile,
+          BRAINSTORM_TOKEN_FILE: tokenFile,
+          BRAINSTORM_LIFECYCLE_CHECK_MS: 100000
+        }
+      });
+      let out = ''; srv.stdout.on('data', d => out += d.toString());
+      for (let i = 0; i < 60 && !out.includes('server-started'); i++) await sleep(50);
+      assert(out.includes('server-started'), 'server should start with persisted token');
+
+      if (process.platform !== 'win32') {
+        const mode = fs.statSync(tokenFile).mode & 0o777;
+        assert.strictEqual(mode, 0o600, `.last-token mode should be 0600, got ${mode.toString(8)}`);
+      } else {
+        assert(fs.existsSync(tokenFile), 'token file should remain present on Windows');
+      }
+    } finally {
+      await killAndWait(srv);
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  await test('stored key can authenticate WebSocket after same-port restart', async () => {
+    const dir = fs.mkdtempSync('/tmp/bs-reconnect-');
+    const portFile = path.join(dir, '.last-port');
+    const tokenFile = path.join(dir, '.last-token');
+    const env = { ...process.env, BRAINSTORM_PORT_FILE: portFile, BRAINSTORM_TOKEN_FILE: tokenFile, BRAINSTORM_LIFECYCLE_CHECK_MS: 100000 };
+    let a = null, b = null, ws = null;
+
+    try {
+      a = spawn('node', [SERVER], { env: { ...env, BRAINSTORM_DIR: path.join(dir, 's1') } });
+      let outA = ''; a.stdout.on('data', d => outA += d.toString());
+      for (let i = 0; i < 60 && !outA.includes('server-started'); i++) await sleep(50);
+      const infoA = firstServerStarted(outA);
+      const keyA = new URL(infoA.url).searchParams.get('key');
+      const exitedA = waitForExit(a);
+      a.kill();
+      assert(await exitedA, 'first server should exit before restart binds its port');
+      a = null;
+
+      b = spawn('node', [SERVER], { env: { ...env, BRAINSTORM_DIR: path.join(dir, 's2') } });
+      let outB = ''; b.stdout.on('data', d => outB += d.toString());
+      for (let i = 0; i < 60 && !outB.includes('server-started'); i++) await sleep(50);
+      const infoB = firstServerStarted(outB);
+
+      ws = new WebSocket(`ws://localhost:${infoB.port}/?key=${keyA}`, {
+        headers: { Origin: `http://localhost:${infoB.port}` }
+      });
+      const opened = await new Promise(resolve => {
+        ws.on('open', () => resolve(true));
+        ws.on('error', () => resolve(false));
+        setTimeout(() => resolve(false), 1500);
+      });
+
+      assert.strictEqual(infoB.port, infoA.port, 'restart should reuse same port');
+      assert(opened, 'stored key should authenticate WS after restart');
+    } finally {
+      try { if (ws) ws.close(); } catch (e) {}
+      await killAndWait(a);
+      await killAndWait(b);
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  await test('falls back to a random port when the preferred port is taken', async () => {
+    const dir = fs.mkdtempSync('/tmp/bs-port-');
+    const portFile = path.join(dir, '.last-port');
+
+    const a = spawn('node', [SERVER], { env: { ...process.env, BRAINSTORM_DIR: path.join(dir, 'a'), BRAINSTORM_PORT: 3415, BRAINSTORM_LIFECYCLE_CHECK_MS: 100000 } });
+    let outA = ''; a.stdout.on('data', d => outA += d.toString());
+    for (let i = 0; i < 60 && !outA.includes('server-started'); i++) await sleep(50);
+
+    fs.writeFileSync(portFile, '3415'); // preferred port, but it's taken by A
+    const b = spawn('node', [SERVER], { env: { ...process.env, BRAINSTORM_DIR: path.join(dir, 'b'), BRAINSTORM_PORT_FILE: portFile, BRAINSTORM_LIFECYCLE_CHECK_MS: 100000 } });
+    let outB = ''; b.stdout.on('data', d => outB += d.toString());
+    for (let i = 0; i < 60 && !outB.includes('server-started'); i++) await sleep(50);
+    const portB = firstServerStarted(outB).port;
+    const persisted = fs.readFileSync(portFile, 'utf8').trim();
+
+    await killAndWait(a);
+    await killAndWait(b);
+    fs.rmSync(dir, { recursive: true, force: true });
+
+    assert.notStrictEqual(portB, 3415, 'must not bind the already-taken port');
+    assert(portB >= 49152, 'should fall back to a random high port');
+    // The fallback must NOT clobber the shared port file — A still owns 3415 and
+    // its open tab must keep reconnecting there.
+    assert.strictEqual(persisted, '3415', 'fallback must not overwrite .last-port');
+  });
+
+  await test('fallback with persisted token generates a fresh unpersisted key', async () => {
+    const dir = fs.mkdtempSync('/tmp/bs-port-');
+    const portFile = path.join(dir, '.last-port');
+    const tokenFile = path.join(dir, '.last-token');
+    const preferredToken = 'abababababababababababababababab';
+    let a = null, b = null;
+
+    try {
+      a = spawn('node', [SERVER], {
+        env: {
+          ...process.env,
+          BRAINSTORM_DIR: path.join(dir, 'a'),
+          BRAINSTORM_PORT: 3422,
+          BRAINSTORM_TOKEN: preferredToken,
+          BRAINSTORM_LIFECYCLE_CHECK_MS: 100000
+        }
+      });
+      let outA = ''; a.stdout.on('data', d => outA += d.toString());
+      for (let i = 0; i < 60 && !outA.includes('server-started'); i++) await sleep(50);
+      assert(outA.includes('server-started'), 'preferred-port server should start');
+
+      fs.writeFileSync(portFile, '3422');
+      fs.writeFileSync(tokenFile, preferredToken, { mode: 0o600 });
+
+      b = spawn('node', [SERVER], {
+        env: {
+          ...process.env,
+          BRAINSTORM_DIR: path.join(dir, 'b'),
+          BRAINSTORM_PORT_FILE: portFile,
+          BRAINSTORM_TOKEN_FILE: tokenFile,
+          BRAINSTORM_LIFECYCLE_CHECK_MS: 100000
+        }
+      });
+      let outB = ''; b.stdout.on('data', d => outB += d.toString());
+      for (let i = 0; i < 60 && !outB.includes('server-started'); i++) await sleep(50);
+      const infoB = firstServerStarted(outB);
+      const fallbackKey = new URL(infoB.url).searchParams.get('key');
+      const persistedAfter = fs.readFileSync(tokenFile, 'utf8').trim();
+      const originalStatus = await httpStatus(3422, fallbackKey);
+
+      assert.notStrictEqual(infoB.port, 3422, 'fallback should use a different port');
+      assert.notStrictEqual(fallbackKey, preferredToken, 'fallback must not reuse persisted key');
+      assert.strictEqual(persistedAfter, preferredToken, 'fallback must not overwrite .last-token');
+      assert.strictEqual(originalStatus, 403, 'fallback key must not authenticate to original server');
+    } finally {
+      await killAndWait(a);
+      await killAndWait(b);
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  await test('fallback with explicit BRAINSTORM_TOKEN fails closed', async () => {
+    const dir = fs.mkdtempSync('/tmp/bs-port-');
+    const portFile = path.join(dir, '.last-port');
+    const explicitToken = 'cdcdcdcdcdcdcdcdcdcdcdcdcdcdcdcd';
+    let a = null, b = null;
+
+    try {
+      a = spawn('node', [SERVER], {
+        env: {
+          ...process.env,
+          BRAINSTORM_DIR: path.join(dir, 'a'),
+          BRAINSTORM_PORT: 3423,
+          BRAINSTORM_TOKEN: explicitToken,
+          BRAINSTORM_LIFECYCLE_CHECK_MS: 100000
+        }
+      });
+      let outA = ''; a.stdout.on('data', d => outA += d.toString());
+      for (let i = 0; i < 60 && !outA.includes('server-started'); i++) await sleep(50);
+      assert(outA.includes('server-started'), 'preferred-port server should start');
+
+      fs.writeFileSync(portFile, '3423');
+      b = spawn('node', [SERVER], {
+        env: {
+          ...process.env,
+          BRAINSTORM_DIR: path.join(dir, 'b'),
+          BRAINSTORM_PORT_FILE: portFile,
+          BRAINSTORM_TOKEN: explicitToken,
+          BRAINSTORM_LIFECYCLE_CHECK_MS: 100000
+        }
+      });
+      let outB = ''; let errB = '';
+      b.stdout.on('data', d => outB += d.toString());
+      b.stderr.on('data', d => errB += d.toString());
+      for (let i = 0; i < 60 && !outB.includes('server-started') && b.exitCode === null; i++) await sleep(50);
+      const exited = await waitForExit(b, 1500);
+
+      assert(exited, 'explicit-token fallback process should exit');
+      assert.notStrictEqual(b.exitCode, 0, 'explicit-token fallback should fail non-zero');
+      assert(!outB.includes('server-started'), 'explicit-token fallback must not start on a random port');
+      assert(/BRAINSTORM_TOKEN/.test(errB), `stderr should explain explicit token fallback refusal, got: ${errB}`);
+    } finally {
+      await killAndWait(a);
+      await killAndWait(b);
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  await test('auto-opens the browser once, on the first screen', async () => {
+    const dir = fs.mkdtempSync('/tmp/bs-open-');
+    const marker = path.join(dir, 'opened.log');
+    const openCmd = openCaptureCommand(dir, marker); // capture the launch instead of opening a browser
+    const srv = spawn('node', [SERVER], { env: { ...process.env, BRAINSTORM_PORT: 3417, BRAINSTORM_DIR: dir, BRAINSTORM_OPEN: '1', BRAINSTORM_OPEN_CMD: openCmd, BRAINSTORM_LIFECYCLE_CHECK_MS: 100000 } });
+    let out = ''; srv.stdout.on('data', d => out += d.toString());
+    for (let i = 0; i < 60 && !out.includes('server-started'); i++) await sleep(50);
+
+    // First screen, with no browser connected -> should auto-open.
+    fs.writeFileSync(path.join(dir, 'content', 'first.html'), '<h2>First</h2>');
+    await waitForFile(marker);
+    // Second screen -> must NOT open again.
+    fs.writeFileSync(path.join(dir, 'content', 'second.html'), '<h2>Second</h2>');
+    await sleep(700);
+
+    const lines = fs.existsSync(marker) ? fs.readFileSync(marker, 'utf8').trim().split('\n').filter(Boolean) : [];
+    // The opened URL must carry the key AND be reachable — a keyless URL hits 403.
+    let status = 0;
+    if (lines[0]) {
+      status = await new Promise(r => require('http').get(lines[0], res => { res.resume(); r(res.statusCode); }).on('error', () => r(0)));
+    }
+    await killAndWait(srv);
+    fs.rmSync(dir, { recursive: true, force: true });
+
+    assert.strictEqual(lines.length, 1, 'should open exactly once');
+    assert(lines[0].includes('3417'), `should open the server URL, got: ${lines[0]}`);
+    assert(/[?&]key=/.test(lines[0]), `opened URL must carry the session key, got: ${lines[0]}`);
+    assert.strictEqual(status, 200, 'the opened URL must be reachable (valid key), not the 403 page');
+  });
+
+  await test('does NOT auto-open unless approved (BRAINSTORM_OPEN unset)', async () => {
+    const dir = fs.mkdtempSync('/tmp/bs-open-');
+    const marker = path.join(dir, 'opened.log');
+    const openCmd = openCaptureCommand(dir, marker);
+    // BRAINSTORM_OPEN intentionally NOT set — auto-open must stay off.
+    const srv = spawn('node', [SERVER], { env: { ...process.env, BRAINSTORM_PORT: 3418, BRAINSTORM_DIR: dir, BRAINSTORM_OPEN_CMD: openCmd, BRAINSTORM_LIFECYCLE_CHECK_MS: 100000 } });
+    let out = ''; srv.stdout.on('data', d => out += d.toString());
+    for (let i = 0; i < 60 && !out.includes('server-started'); i++) await sleep(50);
+    fs.writeFileSync(path.join(dir, 'content', 'first.html'), '<h2>First</h2>');
+    await sleep(700);
+    await killAndWait(srv);
+    const opened = fs.existsSync(marker);
+    fs.rmSync(dir, { recursive: true, force: true });
+    assert(!opened, 'must not open the browser without explicit approval');
+  });
+
+  await test('unauthenticated requests do not defeat the idle timeout', async () => {
+    const dir = fs.mkdtempSync('/tmp/bs-life-');
+    const srv = spawn('node', [SERVER], { env: { ...process.env, BRAINSTORM_PORT: 3419, BRAINSTORM_DIR: dir, BRAINSTORM_TOKEN: 'authtok', BRAINSTORM_IDLE_TIMEOUT_MS: 400, BRAINSTORM_LIFECYCLE_CHECK_MS: 100 } });
+    let out = ''; srv.stdout.on('data', d => out += d.toString());
+    let exited = false; srv.on('exit', () => { exited = true; });
+    for (let i = 0; i < 60 && !out.includes('server-started'); i++) await sleep(50);
+
+    // Flood with UNAUTHENTICATED (keyless → 403) requests. These must NOT count
+    // as activity, so the idle timeout still fires and the process exits.
+    const hammer = setInterval(() => { require('http').get('http://localhost:3419/', r => r.resume()).on('error', () => {}); }, 60);
+    for (let i = 0; i < 40 && !exited; i++) await sleep(100);
+    clearInterval(hammer);
+    if (!exited) await killAndWait(srv);
+    fs.rmSync(dir, { recursive: true, force: true });
+
+    assert(exited, 'idle shutdown must still fire despite a flood of unauthenticated requests');
+  });
+
+  console.log(`\n--- Results: ${passed} passed, ${failed} failed ---`);
+  if (failed > 0) process.exit(1);
+}
+
+runTests().catch(err => { console.error('Test failed:', err); process.exit(1); });

tests/brainstorm-server/package.json

@@ -2,7 +2,7 @@
   "name": "brainstorm-server-tests",
   "version": "1.0.0",
   "scripts": {
-    "test": "node server.test.js"
+    "test": "node ws-protocol.test.js && node helper.test.js && node browser-launcher.test.js && node auth.test.js && node server.test.js && node lifecycle.test.js && bash start-server.test.sh && bash stop-server.test.sh"
   },
   "dependencies": {
     "ws": "^8.19.0"

tests/brainstorm-server/server.test.js

@@ -20,6 +20,9 @@ const TEST_PORT = 3334;
 const TEST_DIR = '/tmp/brainstorm-test';
 const CONTENT_DIR = path.join(TEST_DIR, 'content');
 const STATE_DIR = path.join(TEST_DIR, 'state');
+// Fixed session key so the test client can authenticate (see auth.test.js for
+// the security behavior itself; here we just need authorized requests).
+const TOKEN = 'testtoken-server-0123456789abcdef';
 
 function cleanup() {
   if (fs.existsSync(TEST_DIR)) {
@@ -33,7 +36,8 @@ async function sleep(ms) {
 
 async function fetch(url) {
   return new Promise((resolve, reject) => {
-    http.get(url, (res) => {
+    const headers = { Cookie: `brainstorm-key-${TEST_PORT}=${TOKEN}` };
+    http.get(url, { headers }, (res) => {
       let data = '';
       res.on('data', chunk => data += chunk);
       res.on('end', () => resolve({
@@ -47,7 +51,7 @@ async function fetch(url) {
 
 function startServer() {
   return spawn('node', [SERVER_PATH], {
-    env: { ...process.env, BRAINSTORM_PORT: TEST_PORT, BRAINSTORM_DIR: TEST_DIR }
+    env: { ...process.env, BRAINSTORM_PORT: TEST_PORT, BRAINSTORM_DIR: TEST_DIR, BRAINSTORM_TOKEN: TOKEN }
   });
 }
 
@@ -69,6 +73,43 @@ async function waitForServer(server) {
   });
 }
 
+class SkipTest extends Error {
+  constructor(message) {
+    super(message);
+    this.skip = true;
+  }
+}
+
+function skip(message) {
+  throw new SkipTest(message);
+}
+
+function serverStartedMessage(out) {
+  const line = out.trim().split('\n').find(l => l.includes('server-started'));
+  assert(line, 'server-started JSON should be present');
+  return JSON.parse(line);
+}
+
+function assertStartedOnExpectedPort(out) {
+  const msg = serverStartedMessage(out);
+  assert.strictEqual(
+    msg.port,
+    TEST_PORT,
+    `server.test.js expected fixed port ${TEST_PORT}, got ${msg.port}; fixed-port tests must not run through fallback`
+  );
+  return msg;
+}
+
+function ensureSymlinkWorks(target, link) {
+  try {
+    fs.symlinkSync(target, link);
+    fs.unlinkSync(link);
+  } catch (e) {
+    try { fs.unlinkSync(link); } catch (ignore) {}
+    skip(`symlink creation unavailable on this host: ${e.message}`);
+  }
+}
+
 async function runTests() {
   cleanup();
 
@@ -76,15 +117,22 @@ async function runTests() {
   let stdoutAccum = '';
   server.stdout.on('data', (data) => { stdoutAccum += data.toString(); });
 
-  const { stdout: initialStdout } = await waitForServer(server);
+  let initialStdout = '';
   let passed = 0;
   let failed = 0;
+  let skipped = 0;
 
   function test(name, fn) {
     return fn().then(() => {
       console.log(`  PASS: ${name}`);
       passed++;
     }).catch(e => {
+      if (e.skip) {
+        console.log(`  SKIP: ${name}`);
+        console.log(`    ${e.message}`);
+        skipped++;
+        return;
+      }
       console.log(`  FAIL: ${name}`);
       console.log(`    ${e.message}`);
       failed++;
@@ -92,11 +140,15 @@ async function runTests() {
   }
 
   try {
+    const { stdout } = await waitForServer(server);
+    initialStdout = stdout;
+    assertStartedOnExpectedPort(initialStdout);
+
     // ========== Server Startup ==========
     console.log('\n--- Server Startup ---');
 
     await test('outputs server-started JSON on startup', () => {
-      const msg = JSON.parse(initialStdout.trim());
+      const msg = serverStartedMessage(initialStdout);
       assert.strictEqual(msg.type, 'server-started');
       assert.strictEqual(msg.port, TEST_PORT);
       assert(msg.url, 'Should include URL');
@@ -179,6 +231,95 @@ async function runTests() {
       assert(!res.body.includes('"not"'), 'Should not serve JSON');
     });
 
+    await test('ignores macOS resource-fork dotfiles (._*.html) when serving', async () => {
+      // On macOS/ExFAT/SMB, the OS writes ._name.html sidecar files holding
+      // binary metadata. They end with .html but must never be served as a screen.
+      fs.writeFileSync(path.join(CONTENT_DIR, 'real-screen.html'), '<h2>Real Screen Content</h2>');
+      await sleep(100);
+      fs.writeFileSync(path.join(CONTENT_DIR, '._real-screen.html'), 'Mac OS X resource fork garbage');
+      await sleep(300);
+
+      const res = await fetch(`http://localhost:${TEST_PORT}/`);
+      assert(res.body.includes('Real Screen Content'), 'should serve the real screen, not the newer ._ sidecar');
+      assert(!res.body.includes('resource fork garbage'), 'must not serve ._*.html dotfile content');
+    });
+
+    await test('does not serve dotfiles via /files/', async () => {
+      fs.writeFileSync(path.join(CONTENT_DIR, '._secret.html'), 'dotfile body should not be served');
+      const res = await fetch(`http://localhost:${TEST_PORT}/files/._secret.html`);
+      assert.strictEqual(res.status, 404, '/files/ must 404 on dotfiles');
+    });
+
+    await test('GET /files/ (empty name) returns 404 and does not crash the server', async () => {
+      const res = await fetch(`http://localhost:${TEST_PORT}/files/`);
+      assert.strictEqual(res.status, 404, '/files/ (the content dir) must 404, not EISDIR-crash');
+      // The server must still be alive afterward.
+      const alive = await fetch(`http://localhost:${TEST_PORT}/`);
+      assert.strictEqual(alive.status, 200, 'server must survive a /files/ request');
+    });
+
+    await test('does not serve symlinks that escape content dir via /files/', async () => {
+      const target = path.join(STATE_DIR, 'server-info');
+      const link = path.join(CONTENT_DIR, 'linked-server-info.txt');
+      try { fs.unlinkSync(link); } catch (e) {}
+      ensureSymlinkWorks(target, link);
+      fs.symlinkSync(target, link);
+
+      const res = await fetch(`http://localhost:${TEST_PORT}/files/linked-server-info.txt`);
+      assert.strictEqual(res.status, 404, 'symlink to state/server-info must not be served');
+      assert(!res.body.includes('server-started'), 'response must not include server-info body');
+    });
+
+    await test('does not serve hard links to files outside content dir via /files/', async () => {
+      const target = path.join(STATE_DIR, 'server-info');
+      const link = path.join(CONTENT_DIR, 'hard-linked-server-info.txt');
+      try { fs.unlinkSync(link); } catch (e) {}
+      fs.linkSync(target, link);
+
+      const res = await fetch(`http://localhost:${TEST_PORT}/files/hard-linked-server-info.txt`);
+      assert.strictEqual(res.status, 404, 'hard link to state/server-info must not be served');
+      assert(!res.body.includes('server-started'), 'response must not include server-info body');
+    });
+
+    await test('does not serve symlinks that escape content dir via root screen selection', async () => {
+      const target = path.join(STATE_DIR, 'server-info');
+      const link = path.join(CONTENT_DIR, 'root-linked-server-info.html');
+      try { fs.unlinkSync(link); } catch (e) {}
+      ensureSymlinkWorks(target, link);
+      fs.symlinkSync(target, link);
+      const future = new Date(Date.now() + 2000);
+      fs.utimesSync(target, future, future);
+      await sleep(300);
+
+      const res = await fetch(`http://localhost:${TEST_PORT}/`);
+      assert.strictEqual(res.status, 200);
+      assert(!res.body.includes('"type":"server-started"'), 'root screen must not serve state/server-info through a symlink');
+      assert(!res.body.includes('"state_dir"'), 'root screen must not include server-info body');
+    });
+
+    await test('does not serve hard links that escape content dir via root screen selection', async () => {
+      const target = path.join(STATE_DIR, 'server-info');
+      const link = path.join(CONTENT_DIR, 'root-hard-linked-server-info.html');
+      try { fs.unlinkSync(link); } catch (e) {}
+      try {
+        fs.linkSync(target, link);
+      } catch (e) {
+        skip(`hardlink creation unavailable on this host: ${e.message}`);
+      }
+      const linkStat = fs.lstatSync(link);
+      if (linkStat.nlink <= 1) {
+        skip(`hardlink nlink did not expose multiple links: ${linkStat.nlink}`);
+      }
+      const future = new Date(Date.now() + 3000);
+      fs.utimesSync(target, future, future);
+      await sleep(300);
+
+      const res = await fetch(`http://localhost:${TEST_PORT}/`);
+      assert.strictEqual(res.status, 200);
+      assert(!res.body.includes('"type":"server-started"'), 'root screen must not serve state/server-info through a hardlink');
+      assert(!res.body.includes('"state_dir"'), 'root screen must not include server-info body');
+    });
+
     await test('returns 404 for non-root paths', async () => {
       const res = await fetch(`http://localhost:${TEST_PORT}/other`);
       assert.strictEqual(res.status, 404);
@@ -188,7 +329,7 @@ async function runTests() {
     console.log('\n--- WebSocket Communication ---');
 
     await test('accepts WebSocket upgrade on /', async () => {
-      const ws = new WebSocket(`ws://localhost:${TEST_PORT}`);
+      const ws = new WebSocket(`ws://localhost:${TEST_PORT}/?key=${TOKEN}`);
       await new Promise((resolve, reject) => {
         ws.on('open', resolve);
         ws.on('error', reject);
@@ -198,7 +339,7 @@ async function runTests() {
 
     await test('relays user events to stdout with source field', async () => {
       stdoutAccum = '';
-      const ws = new WebSocket(`ws://localhost:${TEST_PORT}`);
+      const ws = new WebSocket(`ws://localhost:${TEST_PORT}/?key=${TOKEN}`);
       await new Promise(resolve => ws.on('open', resolve));
 
       ws.send(JSON.stringify({ type: 'click', text: 'Test Button' }));
@@ -214,7 +355,7 @@ async function runTests() {
       const eventsFile = path.join(STATE_DIR, 'events');
       if (fs.existsSync(eventsFile)) fs.unlinkSync(eventsFile);
 
-      const ws = new WebSocket(`ws://localhost:${TEST_PORT}`);
+      const ws = new WebSocket(`ws://localhost:${TEST_PORT}/?key=${TOKEN}`);
       await new Promise(resolve => ws.on('open', resolve));
 
       ws.send(JSON.stringify({ type: 'click', choice: 'b', text: 'Option B' }));
@@ -232,7 +373,7 @@ async function runTests() {
       const eventsFile = path.join(STATE_DIR, 'events');
       if (fs.existsSync(eventsFile)) fs.unlinkSync(eventsFile);
 
-      const ws = new WebSocket(`ws://localhost:${TEST_PORT}`);
+      const ws = new WebSocket(`ws://localhost:${TEST_PORT}/?key=${TOKEN}`);
       await new Promise(resolve => ws.on('open', resolve));
 
       ws.send(JSON.stringify({ type: 'hover', text: 'Something' }));
@@ -244,8 +385,8 @@ async function runTests() {
     });
 
     await test('handles multiple concurrent WebSocket clients', async () => {
-      const ws1 = new WebSocket(`ws://localhost:${TEST_PORT}`);
-      const ws2 = new WebSocket(`ws://localhost:${TEST_PORT}`);
+      const ws1 = new WebSocket(`ws://localhost:${TEST_PORT}/?key=${TOKEN}`);
+      const ws2 = new WebSocket(`ws://localhost:${TEST_PORT}/?key=${TOKEN}`);
       await Promise.all([
         new Promise(resolve => ws1.on('open', resolve)),
         new Promise(resolve => ws2.on('open', resolve))
@@ -270,7 +411,7 @@ async function runTests() {
     });
 
     await test('cleans up closed clients from broadcast list', async () => {
-      const ws1 = new WebSocket(`ws://localhost:${TEST_PORT}`);
+      const ws1 = new WebSocket(`ws://localhost:${TEST_PORT}/?key=${TOKEN}`);
       await new Promise(resolve => ws1.on('open', resolve));
       ws1.close();
       await sleep(100);
@@ -282,7 +423,7 @@ async function runTests() {
     });
 
     await test('handles malformed JSON from client gracefully', async () => {
-      const ws = new WebSocket(`ws://localhost:${TEST_PORT}`);
+      const ws = new WebSocket(`ws://localhost:${TEST_PORT}/?key=${TOKEN}`);
       await new Promise(resolve => ws.on('open', resolve));
 
       // Send invalid JSON — server should not crash
@@ -299,7 +440,7 @@ async function runTests() {
     console.log('\n--- File Watching ---');
 
     await test('sends reload on new .html file', async () => {
-      const ws = new WebSocket(`ws://localhost:${TEST_PORT}`);
+      const ws = new WebSocket(`ws://localhost:${TEST_PORT}/?key=${TOKEN}`);
       await new Promise(resolve => ws.on('open', resolve));
 
       let gotReload = false;
@@ -319,7 +460,7 @@ async function runTests() {
       fs.writeFileSync(filePath, '<h2>Original</h2>');
       await sleep(500);
 
-      const ws = new WebSocket(`ws://localhost:${TEST_PORT}`);
+      const ws = new WebSocket(`ws://localhost:${TEST_PORT}/?key=${TOKEN}`);
       await new Promise(resolve => ws.on('open', resolve));
 
       let gotReload = false;
@@ -335,7 +476,7 @@ async function runTests() {
     });
 
     await test('does NOT send reload for non-.html files', async () => {
-      const ws = new WebSocket(`ws://localhost:${TEST_PORT}`);
+      const ws = new WebSocket(`ws://localhost:${TEST_PORT}/?key=${TOKEN}`);
       await new Promise(resolve => ws.on('open', resolve));
 
       let gotReload = false;
@@ -350,6 +491,22 @@ async function runTests() {
       ws.close();
     });
 
+    await test('does NOT send reload for ._*.html resource-fork dotfiles', async () => {
+      const ws = new WebSocket(`ws://localhost:${TEST_PORT}/?key=${TOKEN}`);
+      await new Promise(resolve => ws.on('open', resolve));
+
+      let gotReload = false;
+      ws.on('message', (data) => {
+        if (JSON.parse(data.toString()).type === 'reload') gotReload = true;
+      });
+
+      fs.writeFileSync(path.join(CONTENT_DIR, '._sidecar.html'), 'resource fork');
+      await sleep(500);
+
+      assert(!gotReload, 'a ._ dotfile appearing must not trigger a reload');
+      ws.close();
+    });
+
     await test('clears state/events on new screen', async () => {
       // Create an events file
       const eventsFile = path.join(STATE_DIR, 'events');
@@ -411,7 +568,7 @@ async function runTests() {
     });
 
     // ========== Summary ==========
-    console.log(`\n--- Results: ${passed} passed, ${failed} failed ---`);
+    console.log(`\n--- Results: ${passed} passed, ${failed} failed, ${skipped} skipped ---`);
     if (failed > 0) process.exit(1);
 
   } finally {

tests/brainstorm-server/start-server.test.sh

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+# Fast tests for start-server.sh shell-only platform decisions.
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+START_SCRIPT="$REPO_ROOT/skills/brainstorming/scripts/start-server.sh"
+
+TEST_DIR="${TMPDIR:-/tmp}/brainstorm-start-test-$$"
+passed=0
+failed=0
+
+cleanup() {
+  rm -rf "$TEST_DIR"
+}
+trap cleanup EXIT
+
+pass() {
+  echo "  PASS: $1"
+  passed=$((passed + 1))
+}
+
+fail() {
+  echo "  FAIL: $1"
+  echo "    $2"
+  failed=$((failed + 1))
+}
+
+make_fake_uname() {
+  local fake_bin="$1"
+  cat > "$fake_bin/uname" <<'EOF'
+#!/usr/bin/env bash
+if [[ "${1:-}" == "-s" ]]; then
+  echo "MINGW64_NT-10.0"
+else
+  /usr/bin/uname "$@"
+fi
+EOF
+  chmod +x "$fake_bin/uname"
+}
+
+echo ""
+echo "--- start-server.sh platform detection ---"
+
+mkdir -p "$TEST_DIR/fake-bin" "$TEST_DIR/project"
+make_fake_uname "$TEST_DIR/fake-bin"
+
+cat > "$TEST_DIR/fake-bin/node" <<'EOF'
+#!/usr/bin/env bash
+echo "CAPTURED_OWNER_PID=${BRAINSTORM_OWNER_PID:-__UNSET__}"
+printf 'CAPTURED_ARGV=%s\n' "$@"
+exit 0
+EOF
+chmod +x "$TEST_DIR/fake-bin/node"
+
+captured=$(
+  PATH="$TEST_DIR/fake-bin:$PATH" \
+    MSYSTEM="" \
+    bash "$START_SCRIPT" --project-dir "$TEST_DIR/project" --foreground 2>/dev/null || true
+)
+owner_pid_value=$(echo "$captured" | grep "CAPTURED_OWNER_PID=" | head -1 | sed 's/CAPTURED_OWNER_PID=//')
+
+if [[ "$owner_pid_value" == "" || "$owner_pid_value" == "__UNSET__" ]]; then
+  pass "clears BRAINSTORM_OWNER_PID when uname reports a Windows-like shell"
+else
+  fail "clears BRAINSTORM_OWNER_PID when uname reports a Windows-like shell" \
+       "expected empty or unset, got '$owner_pid_value'"
+fi
+
+if echo "$captured" | grep -Eq '^CAPTURED_ARGV=--brainstorm-server-id=[A-Za-z0-9_-]{32,64}$'; then
+  pass "passes shell-safe server instance id argv"
+else
+  fail "passes shell-safe server instance id argv" \
+       "expected exact --brainstorm-server-id=<safe id> argv line, got: $captured"
+fi
+
+server_id_file=$(find "$TEST_DIR/project/.superpowers/brainstorm" -name server-instance-id -print 2>/dev/null | head -1)
+server_id_value=""
+if [[ -n "$server_id_file" ]]; then
+  server_id_value="$(tr -d '\r\n' < "$server_id_file")"
+fi
+if [[ "$server_id_value" =~ ^[A-Za-z0-9_-]{32,64}$ ]]; then
+  pass "writes shell-safe server-instance-id state file"
+else
+  fail "writes shell-safe server-instance-id state file" \
+       "expected valid id in state, got '$server_id_value'"
+fi
+
+rm -rf "$TEST_DIR/project"/*
+
+cat > "$TEST_DIR/fake-bin/node" <<'EOF'
+#!/usr/bin/env bash
+echo "FOREGROUND_MODE=true"
+exit 0
+EOF
+chmod +x "$TEST_DIR/fake-bin/node"
+
+captured=$(
+  PATH="$TEST_DIR/fake-bin:$PATH" \
+    MSYSTEM="" \
+    bash "$START_SCRIPT" --project-dir "$TEST_DIR/project" 2>/dev/null || true
+)
+
+if echo "$captured" | grep -q "FOREGROUND_MODE=true"; then
+  pass "auto-foregrounds when uname reports a Windows-like shell"
+else
+  fail "auto-foregrounds when uname reports a Windows-like shell" \
+       "expected foreground node path, got: $captured"
+fi
+
+echo ""
+echo "--- Results: $passed passed, $failed failed ---"
+if [[ $failed -gt 0 ]]; then
+  exit 1
+fi

tests/brainstorm-server/stop-server.test.sh

@@ -0,0 +1,182 @@
+#!/usr/bin/env bash
+# Tests for stop-server.sh PID-ownership safety.
+#
+# A stale server.pid (e.g. after a reboot, when the kernel has recycled the PID)
+# can point at an unrelated, live process. stop-server.sh must verify the PID is
+# actually our brainstorm server before signalling it.
+
+set -u
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+STOP="$SCRIPT_DIR/../../skills/brainstorming/scripts/stop-server.sh"
+SERVER="$SCRIPT_DIR/../../skills/brainstorming/scripts/server.cjs"
+
+PASS=0; FAIL=0
+PIDS=()
+DIRS=()
+
+cleanup() {
+  for pid in "${PIDS[@]}"; do
+    kill -9 "$pid" 2>/dev/null || true
+    wait "$pid" 2>/dev/null || true
+  done
+  for dir in "${DIRS[@]}"; do
+    rm -rf "$dir"
+  done
+}
+trap cleanup EXIT
+
+track_dir() { DIRS+=("$1"); }
+track_pid() { PIDS+=("$1"); }
+untrack_pid() {
+  local remove="$1"
+  local kept=()
+  local pid
+  for pid in "${PIDS[@]}"; do
+    [[ "$pid" == "$remove" ]] || kept+=("$pid")
+  done
+  PIDS=("${kept[@]}")
+}
+new_server_id() {
+  printf 'testid%026d\n' "$RANDOM"
+}
+
+ok() { echo "  PASS: $1"; PASS=$((PASS + 1)); }
+bad() { echo "  FAIL: $1"; echo "    $2"; FAIL=$((FAIL + 1)); }
+
+# --- Test 1: an unrelated, reused PID must NOT be killed ---
+SESS="$(mktemp -d)"; track_dir "$SESS"; mkdir -p "$SESS/state"
+sleep 600 &
+UNRELATED=$!
+track_pid "$UNRELATED"
+disown "$UNRELATED" 2>/dev/null || true
+echo "$UNRELATED" > "$SESS/state/server.pid"
+OUT="$("$STOP" "$SESS")"
+if kill -0 "$UNRELATED" 2>/dev/null; then
+  case "$OUT" in
+    *stale_pid*) ok "unrelated reused PID is left alone (stale_pid)" ;;
+    *) bad "unrelated PID survived but status was not stale_pid" "$OUT" ;;
+  esac
+else
+  bad "unrelated reused PID was KILLED" "$OUT"
+fi
+
+# --- Test 2: a real brainstorm server with matching instance id IS stopped ---
+SESS="$(mktemp -d)"; track_dir "$SESS"; mkdir -p "$SESS/content" "$SESS/state"
+SERVER_ID="$(new_server_id)"
+printf '%s\n' "$SERVER_ID" > "$SESS/state/server-instance-id"
+BRAINSTORM_DIR="$SESS" BRAINSTORM_PORT=3399 node "$SERVER" "--brainstorm-server-id=$SERVER_ID" > /dev/null 2>&1 &
+SRV=$!
+track_pid "$SRV"
+disown "$SRV" 2>/dev/null || true
+for _ in $(seq 1 40); do kill -0 "$SRV" 2>/dev/null && break; sleep 0.1; done
+sleep 0.4
+echo "$SRV" > "$SESS/state/server.pid"
+OUT="$("$STOP" "$SESS")"
+sleep 0.3
+if kill -0 "$SRV" 2>/dev/null; then
+  bad "real brainstorm server still running after stop" "$OUT"
+else
+  wait "$SRV" 2>/dev/null || true
+  untrack_pid "$SRV"
+  case "$OUT" in
+    *stopped*) ok "real brainstorm server with matching instance id is stopped" ;;
+    *) bad "server stopped but status was not 'stopped'" "$OUT" ;;
+  esac
+fi
+
+# --- Test 2b: persistent sessions stop with explicit stopped metadata ---
+SESS="$(mktemp -d "$SCRIPT_DIR/.stop-persistent.XXXXXX")"; track_dir "$SESS"; mkdir -p "$SESS/content" "$SESS/state"
+SERVER_ID="$(new_server_id)"
+printf '%s\n' "$SERVER_ID" > "$SESS/state/server-instance-id"
+BRAINSTORM_DIR="$SESS" BRAINSTORM_PORT=0 node "$SERVER" "--brainstorm-server-id=$SERVER_ID" > /dev/null 2>&1 &
+SRV=$!
+track_pid "$SRV"
+disown "$SRV" 2>/dev/null || true
+for _ in $(seq 1 40); do
+  [[ -f "$SESS/state/server-info" ]] && break
+  sleep 0.1
+done
+echo "$SRV" > "$SESS/state/server.pid"
+OUT="$("$STOP" "$SESS")"
+sleep 0.3
+if kill -0 "$SRV" 2>/dev/null; then
+  bad "persistent brainstorm server still running after stop" "$OUT"
+else
+  wait "$SRV" 2>/dev/null || true
+  untrack_pid "$SRV"
+  if [[ -f "$SESS/state/server-info" ]]; then
+    bad "persistent stop clears server-info" "server-info still exists after: $OUT"
+  elif [[ ! -f "$SESS/state/server-stopped" ]]; then
+    bad "persistent stop writes server-stopped" "server-stopped missing after: $OUT"
+  elif grep -q '"reason":"stop-server.sh"' "$SESS/state/server-stopped"; then
+    ok "persistent stop clears alive metadata and writes server-stopped"
+  else
+    bad "persistent stop writes stop reason" "$(cat "$SESS/state/server-stopped" 2>/dev/null || true)"
+  fi
+fi
+
+# --- Test 3: no pid file ---
+SESS="$(mktemp -d)"; track_dir "$SESS"; mkdir -p "$SESS/state"
+OUT="$("$STOP" "$SESS")"
+case "$OUT" in
+  *not_running*) ok "missing pid file reports not_running" ;;
+  *) bad "missing pid file: unexpected status" "$OUT" ;;
+esac
+
+# --- Test 4: a node server.cjs impostor with missing instance id is spared ---
+SESS="$(mktemp -d)"; track_dir "$SESS"; mkdir -p "$SESS/state"
+( exec -a "node server.cjs" sleep 600 ) &
+IMPOSTOR=$!
+track_pid "$IMPOSTOR"
+disown "$IMPOSTOR" 2>/dev/null || true
+echo "$IMPOSTOR" > "$SESS/state/server.pid"
+OUT="$("$STOP" "$SESS")"
+if kill -0 "$IMPOSTOR" 2>/dev/null; then
+  case "$OUT" in
+    *stale_pid*) ok "missing instance id leaves node server.cjs impostor alone" ;;
+    *) bad "impostor survived but status was not stale_pid" "$OUT" ;;
+  esac
+else
+  bad "killed a node server.cjs impostor with missing instance id" "$OUT"
+fi
+
+# --- Test 5: a node server.cjs impostor with wrong instance id is spared ---
+SESS="$(mktemp -d)"; track_dir "$SESS"; mkdir -p "$SESS/state"
+EXPECTED_ID="$(new_server_id)"
+WRONG_ID="$(new_server_id)"
+printf '%s\n' "$EXPECTED_ID" > "$SESS/state/server-instance-id"
+( exec -a "node server.cjs --brainstorm-server-id=$WRONG_ID" sleep 600 ) &
+IMPOSTOR=$!
+track_pid "$IMPOSTOR"
+disown "$IMPOSTOR" 2>/dev/null || true
+echo "$IMPOSTOR" > "$SESS/state/server.pid"
+OUT="$("$STOP" "$SESS")"
+if kill -0 "$IMPOSTOR" 2>/dev/null; then
+  case "$OUT" in
+    *stale_pid*) ok "wrong instance id leaves node server.cjs impostor alone" ;;
+    *) bad "wrong-id impostor survived but status was not stale_pid" "$OUT" ;;
+  esac
+else
+  bad "killed a node server.cjs impostor with wrong instance id" "$OUT"
+fi
+
+# --- Test 6: malformed instance id is fail-closed ---
+SESS="$(mktemp -d)"; track_dir "$SESS"; mkdir -p "$SESS/state"
+printf '%s\n' 'bad id with spaces' > "$SESS/state/server-instance-id"
+( exec -a "node server.cjs --brainstorm-server-id=bad-id-with-spaces" sleep 600 ) &
+IMPOSTOR=$!
+track_pid "$IMPOSTOR"
+disown "$IMPOSTOR" 2>/dev/null || true
+echo "$IMPOSTOR" > "$SESS/state/server.pid"
+OUT="$("$STOP" "$SESS")"
+if kill -0 "$IMPOSTOR" 2>/dev/null; then
+  case "$OUT" in
+    *stale_pid*) ok "malformed instance id is fail-closed" ;;
+    *) bad "malformed-id impostor survived but status was not stale_pid" "$OUT" ;;
+  esac
+else
+  bad "killed process despite malformed instance id" "$OUT"
+fi
+
+echo "--- Results: $PASS passed, $FAIL failed ---"
+[ "$FAIL" -eq 0 ] || exit 1

tests/brainstorm-server/windows-lifecycle.test.sh

@@ -80,14 +80,23 @@ get_port_from_info() {
   grep -o '"port":[0-9]*' "$1/state/server-info" | head -1 | sed 's/"port"://'
 }
 
+get_key_from_info() {
+  grep -o '"url":"[^"]*key=[^"]*' "$1/state/server-info" | head -1 | sed 's/.*key=//'
+}
+
 http_check() {
   local port="$1"
-  node -e "
+  local key="${2:-}"
+  node - "$port" "$key" <<'NODE'
     const http = require('http');
-    http.get('http://localhost:$port/', (res) => {
+    const port = Number(process.argv[2]);
+    const key = process.argv[3] || '';
+    const path = key ? '/?key=' + encodeURIComponent(key) : '/';
+    http.get({ hostname: '127.0.0.1', port, path }, (res) => {
+      res.resume();
       process.exit(res.statusCode === 200 ? 0 : 1);
     }).on('error', () => process.exit(1));
-  " 2>/dev/null
+NODE
 }
 
 # ========== Platform Detection ==========
@@ -153,6 +162,7 @@ if [[ "$is_windows" == "true" ]]; then
   cat > "$FAKE_NODE_DIR/node" <<'FAKENODE'
 #!/usr/bin/env bash
 echo "CAPTURED_OWNER_PID=${BRAINSTORM_OWNER_PID:-__UNSET__}"
+printf 'CAPTURED_ARGV=%s\n' "$@"
 exit 0
 FAKENODE
   chmod +x "$FAKE_NODE_DIR/node"
@@ -167,6 +177,13 @@ FAKENODE
          "Expected empty or unset, got '$owner_pid_value'"
   fi
 
+  if echo "$captured" | grep -Eq '^CAPTURED_ARGV=--brainstorm-server-id=[A-Za-z0-9_-]{32,64}$'; then
+    pass "start-server.sh passes server instance id argv on Windows"
+  else
+    fail "start-server.sh passes server instance id argv on Windows" \
+         "Expected --brainstorm-server-id=<safe id>, output: $captured"
+  fi
+
   rm -rf "$FAKE_NODE_DIR" "$TEST_DIR/session"
 else
   skip "start-server.sh passes empty BRAINSTORM_OWNER_PID" "not on Windows"
@@ -227,6 +244,7 @@ else
   pass "Server starts successfully with empty OWNER_PID"
 
   SERVER_PORT=$(get_port_from_info "$TEST_DIR/survival")
+  SERVER_KEY=$(get_key_from_info "$TEST_DIR/survival")
 
   sleep 75
 
@@ -237,11 +255,11 @@ else
          "Server died. Log tail: $(tail -5 "$TEST_DIR/survival/.server.log" 2>/dev/null)"
   fi
 
-  if http_check "$SERVER_PORT"; then
+  if http_check "$SERVER_PORT" "$SERVER_KEY"; then
     pass "Server responds to HTTP after lifecycle check window"
   else
     fail "Server responds to HTTP after lifecycle check window" \
-         "HTTP request to port $SERVER_PORT failed"
+         "Authenticated HTTP request to port $SERVER_PORT failed"
   fi
 
   if grep -q "owner process exited" "$TEST_DIR/survival/.server.log" 2>/dev/null; then
@@ -325,23 +343,33 @@ echo ""
 echo "--- Clean Shutdown ---"
 
 mkdir -p "$TEST_DIR/stop-test/state"
+STOP_TEST_ID="$(printf 'windowsstop%021d\n' "$RANDOM")"
+printf '%s\n' "$STOP_TEST_ID" > "$TEST_DIR/stop-test/state/server-instance-id"
 
 BRAINSTORM_DIR="$TEST_DIR/stop-test" \
 BRAINSTORM_HOST="127.0.0.1" \
 BRAINSTORM_URL_HOST="localhost" \
 BRAINSTORM_OWNER_PID="" \
 BRAINSTORM_PORT=$((49152 + RANDOM % 16383)) \
-  node "$SERVER_SCRIPT" > "$TEST_DIR/stop-test/.server.log" 2>&1 &
+  node "$SERVER_SCRIPT" "--brainstorm-server-id=$STOP_TEST_ID" > "$TEST_DIR/stop-test/.server.log" 2>&1 &
 STOP_TEST_PID=$!
+disown "$STOP_TEST_PID" 2>/dev/null || true
 echo "$STOP_TEST_PID" > "$TEST_DIR/stop-test/state/server.pid"
 
 if ! wait_for_server_info "$TEST_DIR/stop-test"; then
   fail "Stop-test server starts" "Server did not start"
   kill "$STOP_TEST_PID" 2>/dev/null || true
+  wait "$STOP_TEST_PID" 2>/dev/null || true
   STOP_TEST_PID=""
 else
   bash "$STOP_SCRIPT" "$TEST_DIR/stop-test" >/dev/null 2>&1 || true
-  sleep 1
+  for _ in $(seq 1 10); do
+    if ! kill -0 "$STOP_TEST_PID" 2>/dev/null; then
+      wait "$STOP_TEST_PID" 2>/dev/null || true
+      break
+    fi
+    sleep 0.1
+  done
 
   if ! kill -0 "$STOP_TEST_PID" 2>/dev/null; then
     pass "stop-server.sh cleanly stops the server"