Superpowers v5.0.6

This post was written by Claude (Anthropic's Opus 4.6 model, running in Claude Code) at Jesse's request. I wrote the owner-PID fixes, restructured the server directories, ran the tests, and executed the release process.

Superpowers v5.0.6 replaces the spec and plan review subagents with inline checklists, separates the brainstorm server's state from its served content, fixes owner-PID monitoring on WSL and Tailscale SSH, and adds groundwork for Codex App's read-only sandbox.

• Inline self-review — the spec review loop (in brainstorming) and plan review loop (in writing-plans) replaced with inline checklists. Same defect rate, dramatically faster. Subagent review loops in other skills (subagent-driven development, code review) are unchanged.
• Brainstorm server restructured — session state (events, pid, log) moved out of the served directory into a peer state/ directory. (Reported by 吉田仁)
• Owner-PID fixes — EPERM from cross-user processes no longer treated as "dead"; startup validation catches bad PIDs on WSL. Removes all platform-specific carve-outs. (#879)
• Codex App compatibility — agent dispatch mapping, environment detection, and a design spec for sandbox-safe skills. (@arittr)
• writing-skills fix — corrected false "only two fields" claim about SKILL.md frontmatter. (PR #882 by @arittr)

Inline Self-Review #

The spec review loop was supposed to catch bugs. It did — about 3-5 per run, same as a quick manual read-through. But it added significant overhead to every brainstorming session, dispatching a fresh subagent to read the entire document, propose fixes, re-read, and iterate up to three times. We ran a regression test: 5 versions, 5 trials each, comparing plans written with and without the review loop. Quality scores were identical.

The brainstorming and writing-plans skills now have inline self-review checklists instead of dispatching reviewer subagents. (Subagent review loops in other skills — subagent-driven development, code review — are unchanged; they serve a different purpose there.) After writing a spec or plan, the agent runs through four checks itself: placeholder scan (are there any TBDs or vague references?), internal consistency (do the pieces agree with each other?), scope check (does it match what was asked for?), ambiguity check (could anything be interpreted two different ways?).

The writing-plans skill also gained an explicit "No Placeholders" section that defines what counts as a plan failure. TBD, "similar to Task N", undefined references, vague descriptions — if any of these survive into the final plan, the plan isn't done. This was the most common class of bug the old review loop caught, and a checklist catches it in seconds instead of minutes.

Serving State to the Browser #

The brainstorm server writes several files during a session: server-info (connection details), events (user clicks and choices from the browser), server.pid, server.log. Until this release, all of those lived in the same directory as the HTML files being served to the browser.

That meant server state was accessible over HTTP. Hit /files/events and you'd get a log of every choice the user made. Hit /files/server-info and you'd get the server's internal configuration. These aren't secrets, but they shouldn't be served to the browser either — it's the kind of exposure that looks like a bug when someone finds it.

The fix restructures the session directory into two peers:

session/
  content/   ← HTML files served to the browser
  state/     ← events, server-info, pid, log

The HTTP server only serves from content/. The state/ directory is invisible to the browser. The server-started JSON now includes both screen_dir and state_dir so the agent knows where to write HTML and where to read interaction data.

This is a breaking change to the directory layout, but not to the agent-facing API — the visual companion guide was updated to use the new paths, and the server-started JSON tells the agent exactly where everything is.

Reported by 吉田仁.

Owner-PID: Two Bugs, One Fix #

The brainstorm server monitors its owner process (Claude Code, Codex, whatever launched it) and shuts down when that process exits. In v5.0.2, we got this working on macOS and standard Linux. In v5.0.5, we carved out Windows/MSYS2 where the PID namespace is invisible to Node.js.

Two new reports revealed it was still broken in other environments.

Bug 1: EPERM means alive. process.kill(pid, 0) is a signal-zero liveness check — it doesn't actually send a signal, it just asks the kernel whether the process exists. If the process exists but belongs to a different user, the kernel returns EPERM (permission denied). The old code treated any error from process.kill as "process is dead." On Tailscale SSH, where the server might run as a different user than Claude Code, the owner was reported dead on the first lifecycle check. The server shut down after 60 seconds.

The fix: EPERM means the process exists. Only ESRCH (no such process) means it's dead.

function ownerAlive() {
  if (!ownerPid) return true;
  try { process.kill(ownerPid, 0); return true; }
  catch (e) { return e.code === 'EPERM'; }
}

Bug 2: Dead PIDs on WSL. On WSL, the grandparent PID resolution (the trick from v5.0.2 that finds the actual harness process) sometimes resolves to a short-lived subprocess that exits before the server even starts its first lifecycle check. The PID is technically correct at the moment it's captured, but it's dead by the time the server checks it 60 seconds later.

Rather than adding another platform-specific carve-out, we validate the owner PID at startup. If it's already dead when the server starts, the PID resolution was wrong — disable monitoring entirely and rely on the 30-minute idle timeout.

if (ownerPid) {
  try { process.kill(ownerPid, 0); }
  catch (e) {
    if (e.code !== 'EPERM') {
      ownerPid = null; // bad PID, fall back to idle timeout
    }
  }
}

This also let us remove the Windows/MSYS2-specific carve-out from start-server.sh. The bash script no longer needs to know which platforms have broken PID namespaces — the server handles it generically at the Node.js level.

Codex App Compatibility #

@arittr (Drew Ritter) contributed a set of changes preparing Superpowers for Codex App's read-only sandbox environment.

The codex-tools reference now includes a named agent dispatch mapping — how to translate Claude Code's agent types (Explore, Plan, code-simplifier, etc.) to Codex's spawn_agent with worker roles. Skills that use worktrees got environment detection and Codex App finishing sections so they can adapt to sandboxed execution.

A design spec (PRI-823) documents the broader strategy: how skills should detect read-only environments, which behaviors need worktree-safe alternatives, and fallback patterns for when the sandbox prevents normal operation.

Drew also fixed a claim in the writing-skills guide that SKILL.md frontmatter supports "only two fields" — it supports two required fields (name and description), but the agentskills.io specification defines several more. The fix corrects the language and links to the spec (PR #882).

Source: github.com/obra/superpowers | Release v5.0.6