Two bugs caused the brainstorm server to self-terminate within 60s:
1. ownerAlive() treated EPERM (permission denied) as "process dead".
When the owner PID belongs to a different user (Tailscale SSH,
system daemons), process.kill(pid, 0) throws EPERM — but the
process IS alive. Fixed: return e.code === 'EPERM'.
2. On WSL, the grandparent PID resolves to a short-lived subprocess
that exits before the first 60s lifecycle check. The PID is
genuinely dead (ESRCH), so the EPERM fix alone doesn't help.
Fixed: validate the owner PID at server startup — if it's already
dead, it was a bad resolution, so disable monitoring and rely on
the 30-minute idle timeout.
This also removes the Windows/MSYS2-specific OWNER_PID="" carve-out
from start-server.sh, since the server now handles invalid PIDs
generically at startup regardless of platform.
Tested on Linux (magic-kingdom) via Tailscale SSH:
- Root-owned owner PID (EPERM): server survives ✓
- Dead owner PID at startup (WSL sim): monitoring disabled, survives ✓
- Valid owner that dies: server shuts down within 60s ✓
Fixes#879
ownerAlive() treated EPERM (permission denied) the same as ESRCH
(process not found), causing the server to self-terminate within 60s
whenever the owner process ran as a different user. This affected WSL
(owner is a Windows process), Tailscale SSH, and any cross-user
scenario.
The fix: `return e.code === 'EPERM'` — if we get permission denied,
the process is alive; we just can't signal it.
Tested on Linux via Tailscale SSH with a root-owned grandparent PID:
- Server survives past the 60s lifecycle check (EPERM = alive)
- Server still shuts down when owner genuinely dies (ESRCH = dead)
Fixes#879
The session directory now contains two peers: content/ (HTML served to
the browser) and state/ (events, server-info, pid, log). Previously
all files shared a single directory, making server state and user
interaction data accessible over the /files/ HTTP route.
Also fixes stale test assertion ("Waiting for Claude" → "Waiting for
the agent").
Reported-By: 吉田仁
Metadata files (.server-info, .events, .server.pid, .server.log,
.server-stopped) were stored in the same directory served over HTTP,
making them accessible via the /files/ route. They now live in a .meta/
subdirectory that is not web-accessible.
Also fixes a stale test assertion ("Waiting for Claude" → "Waiting for
the agent").
Reported-By: 吉田仁
- Skip OWNER_PID monitoring on Windows/MSYS2 where the PID namespace is
invisible to Node.js, preventing server self-termination after 60s (#770)
- Document run_in_background: true for Claude Code on Windows (#767)
- Restore user choice between subagent-driven and inline execution after
plan writing; subagent-driven is recommended but no longer mandatory
- Add Windows lifecycle test script verified on Windows 11 VM
- Note #723 (stop-server.sh reliability) as already fixed
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Replace #!/bin/bash with #!/usr/bin/env bash in 13 scripts. The
hardcoded path fails on NixOS, FreeBSD, and macOS with Homebrew bash.
#!/usr/bin/env bash is the portable POSIX-friendly alternative.
Tested on Linux and Windows (Git Bash + CMD). macOS is the primary
beneficiary since Homebrew installs bash to /opt/homebrew/bin/bash.
Based on #700, closes#700.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Windows/Git Bash reaps nohup background processes, causing the brainstorm
server to die silently after launch. Auto-detect Windows via OSTYPE
(msys/cygwin/mingw) and MSYSTEM env vars, switching to foreground mode
automatically. Tested on Windows 11 from CMD, PowerShell, and Git Bash —
all route through Git Bash and hit the same issue.
Based on #740, fixes#737. Also adds CHANGELOG.md documenting the fix and
a known OWNER_PID/WINPID mismatch on the main branch.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
$PPID inside start-server.sh is the ephemeral shell the harness spawns
to run the script — it dies immediately when the script exits, causing
the server to shut down after ~60s. Now resolves grandparent PID via
`ps -o ppid= -p $PPID` to get the actual harness process (e.g. claude).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
start-server.sh passes $PPID as BRAINSTORM_OWNER_PID to the server.
The server checks every 60s if the owner process is still alive
(kill -0). If it's gone, the server shuts down immediately —
deletes .server-info, writes .server-stopped, exits cleanly.
Works across all harnesses (CC, Codex, Gemini CLI) since it
tracks the shell process that launched the script, which dies
when the harness dies.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Server tracks activity (HTTP requests, WebSocket messages, file
changes) and exits after 30 minutes of inactivity. On exit, deletes
.server-info and writes .server-stopped with reason. Visual companion
guide now instructs agents to check .server-info before each screen
push and restart if needed. Works on all harnesses, not just CC.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Delete 717 files: index.js, package.json, package-lock.json, and
the entire node_modules directory (express, ws, chokidar + deps).
Update start-server.sh to use server.js. Remove gitignore exception.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Complete zero-dep brainstorm server. Uses knownFiles set to
distinguish new screens from updates (macOS fs.watch reports
'rename' for both). All 56 tests pass (31 unit + 25 integration).
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Implements RFC 6455 handshake, frame encoding/decoding for text
frames. All 31 unit tests pass.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
start-server.sh now runs npm install if node_modules is missing.
Fixes broken server when superpowers is installed as a plugin (node_modules
are in .gitignore and not included in the clone).
The server now writes its startup JSON to $SCREEN_DIR/.server-info.
Agents that launch the server via background execution (where stdout is
hidden) can read this file to get the URL, port, and screen_dir.
The visual companion docs now give concrete launch commands per platform:
Claude Code (default mode), Codex (auto-foreground via CODEX_CI), Gemini CLI
(--foreground with is_background), and a fallback for other environments.
Moves lib/brainstorm-server/ → skills/brainstorming/scripts/ so the
brainstorming skill uses relative paths (scripts/start-server.sh) instead
of ${CLAUDE_PLUGIN_ROOT}/lib/brainstorm-server/. This follows the
agentskills.io specification for portable, cross-platform skills.
Updates visual-companion.md references and test paths. All tests pass.
