superpowers-mcp 6.2.2 → 6.2.4

package/skills/brainstorming/scripts/start-server.ps1

@@ -1,6 +1,6 @@
 #!/usr/bin/env pwsh
 # Start the brainstorm server and output connection info.
-# Usage: ./start-server.ps1 [--project-dir <path>] [--host <bind-host>] [--url-host <display-host>] [--foreground] [--background]
+# Usage: ./start-server.ps1 [--project-dir <path>] [--host <loopback-host>] [--url-host <loopback-host>] [--foreground] [--background]
 
 $ErrorActionPreference = "Stop"
 
@@ -29,11 +29,15 @@ function Set-ProcessEnvironment {
 
 function Protect-PathForCurrentUser {
     param([string]$Path)
-    if ([System.Environment]::OSVersion.Platform -ne [System.PlatformID]::Win32NT) {
-        return
-    }
+    $isWindowsPlatform = [System.Environment]::OSVersion.Platform -eq [System.PlatformID]::Win32NT
     try {
         $item = Get-Item -LiteralPath $Path -ErrorAction Stop
+        if (-not $isWindowsPlatform) {
+            $mode = if ($item.PSIsContainer) { "700" } else { "600" }
+            & chmod $mode $item.FullName
+            if ($LASTEXITCODE -ne 0) { throw "chmod failed" }
+            return
+        }
         $acl = Get-Acl -LiteralPath $item.FullName
         $acl.SetAccessRuleProtection($true, $false)
         $identity = [System.Security.Principal.WindowsIdentity]::GetCurrent().Name
@@ -112,6 +116,28 @@ if ($urlHost -eq "") {
     }
 }
 
+function Test-LoopbackHost {
+    param([string]$HostValue)
+    $normalized = $HostValue.Trim().TrimStart('[').TrimEnd(']').ToLowerInvariant()
+    if ($normalized -eq "localhost" -or $normalized -eq "::1" -or $normalized.StartsWith("127.")) {
+        return $true
+    }
+    $address = $null
+    if ([System.Net.IPAddress]::TryParse($normalized, [ref]$address)) {
+        return [System.Net.IPAddress]::IsLoopback($address)
+    }
+    return $false
+}
+
+if (-not (Test-LoopbackHost $bindHost)) {
+    Write-JsonError "Refusing insecure non-loopback HTTP bind; use a TLS reverse proxy or tunnel to 127.0.0.1"
+    exit 1
+}
+if (-not (Test-LoopbackHost $urlHost)) {
+    Write-JsonError "--url-host must be a loopback hostname or address"
+    exit 1
+}
+
 if ($idleTimeoutMinutes -ne "") {
     $parsedIdle = 0
     if ((-not [int]::TryParse($idleTimeoutMinutes, [ref]$parsedIdle)) -or $parsedIdle -lt 1) {
@@ -130,10 +156,17 @@ $brainstormRoot = ""
 if ($projectDir -ne "") {
     $brainstormRoot = Join-Path $projectDir ".superpowers/brainstorm"
     $sessionDir = Join-Path $brainstormRoot $sessionId
+    # Reuse the last bound port and session key so a restart keeps an
+    # already-open browser tab connected to the same URL with a valid cookie.
     $env:BRAINSTORM_PORT_FILE = Join-Path $brainstormRoot ".last-port"
     $env:BRAINSTORM_TOKEN_FILE = Join-Path $brainstormRoot ".last-token"
 } else {
     $sessionDir = Join-Path ([System.IO.Path]::GetTempPath()) "brainstorm-$sessionId"
+    # $env: assignments persist in the invoking pwsh session; a stale project
+    # token/port file from an earlier --project-dir run must not leak into an
+    # ephemeral session (it would defeat key rotation and could overwrite the
+    # project's .last-token).
+    Remove-Item Env:BRAINSTORM_TOKEN_FILE, Env:BRAINSTORM_PORT_FILE -ErrorAction SilentlyContinue
 }
 
 $stateDir = Join-Path $sessionDir "state"
@@ -151,17 +184,71 @@ Protect-PathForCurrentUser -Path $contentDir
 Protect-PathForCurrentUser -Path $stateDir
 
 $serverId = New-ServerId
-Set-Content -Path $serverIdFile -Value $serverId -NoNewline -Encoding utf8
-Protect-PathForCurrentUser -Path $serverIdFile
 
+function Read-ExpectedServerId {
+    if (-not (Test-Path -LiteralPath $serverIdFile)) { return $null }
+    $id = (Get-Content -LiteralPath $serverIdFile -Raw -ErrorAction SilentlyContinue).Trim()
+    if ($id -match '^[A-Za-z0-9_-]{32,64}$') { return $id }
+    return $null
+}
+
+function Test-BrainstormServer {
+    param([int]$ProcessId)
+    $expected = Read-ExpectedServerId
+    if (-not $expected) { return $false }
+    # $IsWindows is undefined on Windows PowerShell 5.1; fall back to the
+    # OSVersion check so the Windows branch is taken there too.
+    $isWinPlatform = ($IsWindows -or [System.Environment]::OSVersion.Platform -eq [System.PlatformID]::Win32NT)
+    if ($isWinPlatform) {
+        $process = Get-CimInstance Win32_Process -Filter "ProcessId = $ProcessId" -ErrorAction SilentlyContinue
+        if (-not $process) { return $false }
+        return ($process.CommandLine -like "*--brainstorm-server-id=$expected*")
+    }
+    # Unix: ps -p prints the full command line; the id is validated
+    # hex above, so no regex escaping is needed.
+    $cmd = (& ps -p $ProcessId -o command= 2>$null)
+    if (-not $cmd) { return $false }
+    return ($cmd -match "--brainstorm-server-id=$expected")
+}
+
+function Get-ProcessStartToken {
+    param([int]$ProcessId)
+    $isWinPlatform = ($IsWindows -or [System.Environment]::OSVersion.Platform -eq [System.PlatformID]::Win32NT)
+    if ($isWinPlatform) {
+        $process = Get-CimInstance Win32_Process -Filter "ProcessId = $ProcessId" -ErrorAction SilentlyContinue
+        if (-not $process) { return $null }
+        return [string]$process.CreationDate
+    }
+    $start = (& ps -p $ProcessId -o lstart= 2>$null)
+    if (-not $start) { return $null }
+    return (($start | Out-String).Trim())
+}
+
+# Kill any existing server — only after proving the PID and its process start
+# identity are ours. The final identity re-check narrows the PID-reuse window.
+# Must run BEFORE the new server-instance-id below overwrites serverIdFile.
 if (Test-Path -LiteralPath $pidFile) {
-    $oldPid = (Get-Content -LiteralPath $pidFile -ErrorAction SilentlyContinue | Select-Object -First 1)
-    if ($oldPid) {
-        Stop-Process -Id ([int]$oldPid) -ErrorAction SilentlyContinue
+    $oldPidText = (Get-Content -LiteralPath $pidFile -ErrorAction SilentlyContinue | Select-Object -First 1)
+    $oldPid = 0
+    $oldStartToken = $null
+    if ([int]::TryParse($oldPidText, [ref]$oldPid) -and (Test-BrainstormServer -ProcessId $oldPid)) {
+        $oldStartToken = Get-ProcessStartToken -ProcessId $oldPid
+    }
+    if ($oldStartToken -and (Test-BrainstormServer -ProcessId $oldPid) -and
+        ((Get-ProcessStartToken -ProcessId $oldPid) -eq $oldStartToken)) {
+        Stop-Process -Id $oldPid -ErrorAction SilentlyContinue
+    } else {
+        Write-Warning "stale server.pid ignored: PID is not a running brainstorm server"
     }
     Remove-Item -LiteralPath $pidFile -Force -ErrorAction SilentlyContinue
 }
 
+# WriteAllText: UTF-8 without BOM on every PowerShell version (PS 5.1's
+# Set-Content -Encoding utf8 emits a BOM, which breaks the bash-side
+# read_expected_server_id regex when a session dir is shared across shells).
+[System.IO.File]::WriteAllText($serverIdFile, $serverId)
+Protect-PathForCurrentUser -Path $serverIdFile
+
 $envValues = @{
     BRAINSTORM_DIR = $sessionDir
     BRAINSTORM_HOST = $bindHost
@@ -199,6 +286,9 @@ if ($foreground) {
 
 Set-ProcessEnvironment -Values $envValues
 $errFile = Join-Path $stateDir "server.err"
+New-Item -ItemType File -Force -Path $logFile, $errFile | Out-Null
+Protect-PathForCurrentUser -Path $logFile
+Protect-PathForCurrentUser -Path $errFile
 $process = Start-Process `
     -FilePath "node" `
     -ArgumentList @("server.cjs", "--brainstorm-server-id=$serverId") `

package/skills/brainstorming/scripts/start-server.sh

@@ -8,9 +8,9 @@
 # Options:
 #   --project-dir <path>  Store session files under <path>/.superpowers/brainstorm/
 #                         instead of /tmp. Files persist after server stops.
-#   --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.
+#   --host <bind-host>    Loopback host/interface to bind (default: 127.0.0.1).
+#                         Use an SSH tunnel or TLS reverse proxy for remote access.
+#   --url-host <host>     Loopback 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).
@@ -71,6 +71,26 @@ if [[ -z "$URL_HOST" ]]; then
   fi
 fi
 
+# Resolve a relative --project-dir against the caller's cwd up front. Later
+# steps cd into SCRIPT_DIR, and a relative session path would then resolve
+# against the wrong directory (or the server would inherit a relative
+# BRAINSTORM_DIR it can't locate).
+if [[ -n "$PROJECT_DIR" && "$PROJECT_DIR" != /* ]]; then
+  requested_project_dir="$PROJECT_DIR"
+  if [[ -d "$requested_project_dir" ]]; then
+    resolved_project_dir="$(cd "$requested_project_dir" 2>/dev/null && pwd -P || true)"
+    if [[ -n "$resolved_project_dir" ]]; then
+      PROJECT_DIR="$resolved_project_dir"
+    else
+      # cd failed (e.g. permission) — fall back to a lexical join against the
+      # caller's cwd instead of silently dropping the requested project dir.
+      PROJECT_DIR="$(pwd -P 2>/dev/null || pwd)/${requested_project_dir#./}"
+    fi
+  else
+    PROJECT_DIR="$(pwd -P 2>/dev/null || pwd)/$requested_project_dir"
+  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\"}"
@@ -106,8 +126,8 @@ if [[ "$FOREGROUND" != "true" && "$FORCE_BACKGROUND" != "true" ]]; then
   fi
 fi
 
-# Session files (server.log, server-info, .last-token) embed the session key —
-# keep everything this script and the server create owner-only.
+# Session files (server.log and server-info) embed the session key — keep
+# everything this script and the server create owner-only.
 umask 077
 
 # Generate unique session directory
@@ -115,8 +135,8 @@ 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.
+  # Reuse the last bound port and session key so a restart keeps an
+  # already-open browser tab connected 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
@@ -129,7 +149,83 @@ 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"
+if ! mkdir -p "${SESSION_DIR}/content" "$STATE_DIR"; then
+  echo '{"error": "Failed to create brainstorm session directory"}'
+  exit 1
+fi
+
+# --- Process identity verification (shared with stop-server.sh) -----------
+# A stale server.pid may point at an unrelated process after a reboot or PID
+# wraparound. Before signalling a PID, prove it is actually a brainstorm
+# server belonging to this session via the per-start server-instance-id.
+
+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_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="$(ps -ww -p "$pid" -o command= 2>/dev/null || ps -f -p "$pid" 2>/dev/null | sed '1d' || true)"
+  [[ -n "$command_line" ]] || return 1
+  case " $command_line " in
+    *" $expected_arg "*) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+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
+}
+
+process_start_token() {
+  local pid="$1"
+  if [[ -r "/proc/$pid/stat" ]]; then
+    local stat_line
+    stat_line="$(cat "/proc/$pid/stat" 2>/dev/null || true)"
+    # After the comm field, /proc/<pid>/stat field 20 is the process start
+    # time (the original field 22), measured in clock ticks since boot.
+    [[ -n "$stat_line" ]] || return 1
+    printf '%s\n' "${stat_line##*) }" | awk '{print $20}'
+    return 0
+  fi
+  ps -ww -p "$pid" -o lstart= 2>/dev/null | sed 's/^ *//' || true
+}
+
+# Kill any existing server — only after proving the PID and its process start
+# identity are ours. The final identity re-check narrows the PID-reuse window.
+# This must run before the new server-instance-id overwrites SERVER_ID_FILE.
+if [[ -f "$PID_FILE" ]]; then
+  old_pid=$(cat "$PID_FILE")
+  old_start_token=""
+  if [[ "$old_pid" =~ ^[0-9]+$ ]] && is_brainstorm_server "$old_pid"; then
+    old_start_token="$(process_start_token "$old_pid")"
+  fi
+  if [[ -n "$old_start_token" ]] && is_brainstorm_server "$old_pid" &&
+     [[ "$(process_start_token "$old_pid")" == "$old_start_token" ]]; then
+    kill "$old_pid" 2>/dev/null
+  else
+    echo '{"warn": "stale server.pid ignored: PID is not a running brainstorm server"}' >&2
+  fi
+  rm -f "$PID_FILE"
+fi
 
 SERVER_ID=""
 if [[ -r /dev/urandom ]]; then
@@ -141,13 +237,6 @@ 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")
-  kill "$old_pid" 2>/dev/null
-  rm -f "$PID_FILE"
-fi
-
 cd "$SCRIPT_DIR" || exit 1
 
 # Resolve the harness PID (grandparent of this script).

package/skills/brainstorming/scripts/stop-server.ps1

@@ -34,7 +34,10 @@ function Test-BrainstormServer {
     param([int]$ProcessId)
     $expected = Read-ExpectedServerId
     if (-not $expected) { return $false }
-    if ($IsWindows) {
+    # $IsWindows is undefined on Windows PowerShell 5.1; fall back to the
+    # OSVersion check so the Windows branch is taken there too.
+    $isWinPlatform = ($IsWindows -or [System.Environment]::OSVersion.Platform -eq [System.PlatformID]::Win32NT)
+    if ($isWinPlatform) {
         $process = Get-CimInstance Win32_Process -Filter "ProcessId = $ProcessId" -ErrorAction SilentlyContinue
         if (-not $process) { return $false }
         return ($process.CommandLine -like "*--brainstorm-server-id=$expected*")
@@ -47,10 +50,38 @@ function Test-BrainstormServer {
     return ($cmd -match "--brainstorm-server-id=$expected")
 }
 
+function Get-ProcessStartToken {
+    param([int]$ProcessId)
+    $isWinPlatform = ($IsWindows -or [System.Environment]::OSVersion.Platform -eq [System.PlatformID]::Win32NT)
+    if ($isWinPlatform) {
+        $process = Get-CimInstance Win32_Process -Filter "ProcessId = $ProcessId" -ErrorAction SilentlyContinue
+        if (-not $process) { return $null }
+        return [string]$process.CreationDate
+    }
+    $start = (& ps -p $ProcessId -o lstart= 2>$null)
+    if (-not $start) { return $null }
+    return (($start | Out-String).Trim())
+}
+
 if (Test-Path -LiteralPath $pidFile) {
     $pidText = (Get-Content -LiteralPath $pidFile -ErrorAction SilentlyContinue | Select-Object -First 1)
     $serverPid = 0
-    if ((-not [int]::TryParse($pidText, [ref]$serverPid)) -or -not (Test-BrainstormServer -ProcessId $serverPid)) {
+    $startToken = $null
+    if ([int]::TryParse($pidText, [ref]$serverPid) -and (Test-BrainstormServer -ProcessId $serverPid)) {
+        $startToken = Get-ProcessStartToken -ProcessId $serverPid
+    }
+    if (-not $startToken -or -not (Test-BrainstormServer -ProcessId $serverPid) -or
+        ((Get-ProcessStartToken -ProcessId $serverPid) -ne $startToken)) {
+        Remove-Item -LiteralPath $pidFile, $serverIdFile -Force -ErrorAction SilentlyContinue
+        Mark-Stopped "stale_pid"
+        [pscustomobject]@{ status = "stale_pid" } | ConvertTo-Json -Compress
+        exit 0
+    }
+
+    # Re-check identity immediately before signalling to narrow the PID-reuse
+    # window as much as shell-level process management permits.
+    if (-not (Test-BrainstormServer -ProcessId $serverPid) -or
+        ((Get-ProcessStartToken -ProcessId $serverPid) -ne $startToken)) {
         Remove-Item -LiteralPath $pidFile, $serverIdFile -Force -ErrorAction SilentlyContinue
         Mark-Stopped "stale_pid"
         [pscustomobject]@{ status = "stale_pid" } | ConvertTo-Json -Compress

package/skills/brainstorming/scripts/stop-server.sh

@@ -70,12 +70,38 @@ is_brainstorm_server() {
   return 0
 }
 
+process_start_token() {
+  local pid="$1"
+  if [[ -r "/proc/$pid/stat" ]]; then
+    local stat_line
+    stat_line="$(cat "/proc/$pid/stat" 2>/dev/null || true)"
+    [[ -n "$stat_line" ]] || return 1
+    printf '%s\n' "${stat_line##*) }" | awk '{print $20}'
+    return 0
+  fi
+  ps -ww -p "$pid" -o lstart= 2>/dev/null | sed 's/^ *//' || true
+}
+
 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
+  start_token=""
+  if is_brainstorm_server "$pid"; then
+    start_token="$(process_start_token "$pid")"
+  fi
+  if [[ -z "$start_token" ]] || ! is_brainstorm_server "$pid" ||
+     [[ "$(process_start_token "$pid")" != "$start_token" ]]; then
+    rm -f "$PID_FILE" "$SERVER_ID_FILE"
+    mark_stopped "stale_pid"
+    echo '{"status": "stale_pid"}'
+    exit 0
+  fi
+
+  # Re-check identity immediately before signalling to narrow the PID-reuse
+  # window as much as shell-level process management permits.
+  if ! is_brainstorm_server "$pid" || [[ "$(process_start_token "$pid")" != "$start_token" ]]; then
     rm -f "$PID_FILE" "$SERVER_ID_FILE"
     mark_stopped "stale_pid"
     echo '{"status": "stale_pid"}'
@@ -109,9 +135,15 @@ if [[ -f "$PID_FILE" ]]; then
   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
-    rm -rf "$SESSION_DIR"
+  # Only delete ephemeral /tmp directories. Resolve both paths canonically
+  # (cd + pwd -P, like stop-server.ps1) so a session dir such as
+  # "/tmp/../home/user/project" can't trick the prefix check into deleting
+  # a directory outside the temp root. (Plain variables: this code runs at
+  # top level, where `local` is a syntax error on bash 3.2 / macOS.)
+  tmp_root="$(cd /tmp 2>/dev/null && pwd -P || true)"
+  resolved="$(cd "$SESSION_DIR" 2>/dev/null && pwd -P || true)"
+  if [[ -n "$tmp_root" && -n "$resolved" && "$resolved" == "$tmp_root/"* ]]; then
+    rm -rf "$resolved"
   fi
 
   echo '{"status": "stopped"}'

package/skills/brainstorming/visual-companion.md

@@ -28,7 +28,7 @@ A question *about* a UI topic is not automatically a visual question. "What kind
 
 The server watches a directory for HTML files and serves the newest one to the browser. You write HTML content to `screen_dir`, the user sees it in their browser and can click to select options. Selections are recorded to `state_dir/events` that you read on your next turn.
 
-**Content fragments vs full documents:** If your HTML file starts with `<!DOCTYPE` or `<html`, the server serves it as-is (just injects the helper script). Otherwise, the server automatically wraps your content in the frame template — adding the header, CSS theme, connection status, and all interactive infrastructure. **Write content fragments by default.** Only write full documents when you need complete control over the page.
+**Content fragments vs full documents:** If your HTML file starts with `<!DOCTYPE` or `<html`, the server serves it as-is (just injects the helper script). Otherwise, the server automatically wraps your content in the frame template — adding the header, CSS theme, connection status, and all interactive infrastructure. **Write content fragments by default.** Only write full documents when you need complete control over the page. Screen scripts are blocked by the server's nonce CSP; use `data-choice` elements and the injected helper instead of inline scripts or event handlers.
 
 ## Starting a Session
 
@@ -49,12 +49,15 @@ scripts/start-server.ps1 --project-dir C:\path\to\project --open
 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.
+without it, so always give the user the **complete** URL from the `url` field for
+the first load — never strip the query string. The key gates HTTP access, then
+moves into an `HttpOnly`/`SameSite=Strict` cookie; the browser's same-origin
+WebSocket automatically sends that cookie. The key is never stored in
+page-readable storage. With `--project-dir`, the key is persisted to
+`.superpowers/brainstorm/.last-token` and reused across restarts, so an
+already-open tab stays connected; delete that file (with the server stopped)
+to force a fresh key. Without it, a new server invocation rotates the key and
+a restarted server requires the new URL.
 
 **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.
 
@@ -96,21 +99,15 @@ 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.
 
-If the URL is unreachable from your browser (common in remote/containerized setups), bind a non-loopback host:
-
-```bash
-scripts/start-server.sh \
-  --project-dir /path/to/project \
-  --host 0.0.0.0 \
-  --url-host localhost
-```
-
-Use `--url-host` to control what hostname is printed in the returned URL JSON.
+The server only permits loopback HTTP binds. For a remote browser, keep the
+server on `127.0.0.1` and use an authenticated SSH tunnel; do not expose the
+companion's plain HTTP port directly to a network interface.
+The `--url-host` value must also be a loopback hostname or address.
 
 ## The Loop
 
 1. **Check server is alive**, then **write HTML** to a new file in `screen_dir`:
-   - **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`).
+   - **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 and session key (from `.last-token`), so an already-open tab keeps working; without `--project-dir` the key rotates, so share the new URL from `server-info` with the user. 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)
@@ -152,14 +149,14 @@ Write just the content that goes inside the page. The server wraps it in the fra
 <p class="subtitle">Consider readability and visual hierarchy</p>
 
 <div class="options">
-  <div class="option" data-choice="a" onclick="toggleSelect(this)">
+  <div class="option" data-choice="a">
     <div class="letter">A</div>
     <div class="content">
       <h3>Single Column</h3>
       <p>Clean, focused reading experience</p>
     </div>
   </div>
-  <div class="option" data-choice="b" onclick="toggleSelect(this)">
+  <div class="option" data-choice="b">
     <div class="letter">B</div>
     <div class="content">
       <h3>Two Column</h3>
@@ -179,7 +176,7 @@ The frame template provides these CSS classes for your content:
 
 ```html
 <div class="options">
-  <div class="option" data-choice="a" onclick="toggleSelect(this)">
+  <div class="option" data-choice="a">
     <div class="letter">A</div>
     <div class="content">
       <h3>Title</h3>
@@ -201,7 +198,7 @@ The frame template provides these CSS classes for your content:
 
 ```html
 <div class="cards">
-  <div class="card" data-choice="design1" onclick="toggleSelect(this)">
+  <div class="card" data-choice="design1">
     <div class="card-image"><!-- mockup content --></div>
     <div class="card-body">
       <h3>Name</h3>