superpowers-mcp 6.2.3 → 6.3.0

package/README.ja.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | [繁體中文](README.zh-TW.md) | [日本語](README.ja.md) | [한국어](README.ko.md)
 
-[![Version](https://img.shields.io/badge/version-6.2.3-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
+[![Version](https://img.shields.io/badge/version-6.3.0-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 このドキュメントは、オリジナルの Superpowers スキルライブラリを独立した MCP Toolpack にパッケージ化するための情報と使用手順をまとめたものです。
@@ -112,7 +112,7 @@
 これらのスキルは、サポートされている IDE（Antigravity や Cursor など）内で複雑なメタ実行パターンをオーケストレーションするために設計されています。
 
 - **`subagent-driven-development`**: サブエージェントを駆動してタスクを実行
-  - **使用方法**: 定義済みの計画をタスクごとに実行します。システムはタスクごとに新しい「実装」サブエージェントを生成し、その後、統合された **タスクレビューアー**（仕様準拠 + コード品質）サブエージェントと、最後に **全ブランチ最終レビュー** を実行します。**Pre-Flight Plan Review** は、実行開始前のタスク競合をスキャンします。
+  - **使用方法**: 定義済みの計画をタスクごとに実行します。システムはタスクごとに新しい「実装」サブエージェントを生成し、その後、統合された **タスクレビューアー**（仕様準拠 + コード品質）サブエージェントと、最後に **全ブランチ最終レビュー** を実行します。**Pre-Flight Plan Review** は、実行開始前のタスク競合をスキャンします。計画は plan-scoped ワークスペース（`.superpowers/sdd/<plan>/`）で実行され、コントローラーは停止せずに衝突を裁定してレジャーに記録（rulings）し、同じ形の小タスクは 1 回のディスパッチにまとめられます。
   - **モデル選択**: タスクの複雑さに基づいてサブエージェントモデルを選択 — 機械的な作業には低コストモデル、アーキテクチャや微妙な並行性変更には高性能モデル。
   - **例**: 「subagent-driven-development スキルを読み込んで、docs/plans/feature-plan.md にリストされているタスクを 1 つずつ実行して」
 - **`dispatching-parallel-agents`**: タスクを並列エージェントに派遣
@@ -128,6 +128,27 @@
 
 ## 🆕 最近の更新
 
+### v6.3.0（最新）
+
+- **上流 obra/superpowers v6.3.0 との同期** — 適用可能な改善をすべて採用し、フォーク固有のセキュリティ強化と PowerShell サポートは維持。
+  - **brainstorming — 3 パスルーター**: すべてのリクエストを事前に `spike` / `bounded` / `architectural` に分類し、プロセス量をタスクに合わせて調整。ただし承認ゲートは常に全パスに適用されます。実行中に隠れた複雑さが判明した場合はパスをアップグレード — ダウングレードはありません。
+  - **subagent-driven-development — 裁定、停止しない（rulings, not stalls）**: 衝突・曖昧さ・計画の欠陥はコントローラーが直接裁定しレジャーに記録（`Ruling: ...`）。停止するのは明示された 4 条件のみ。Pre-flight 競合スキャンはレジャー表を出力し、同形状の小タスクは単一ディスパッチにバッチ化され、子エージェント待機は境界付きストレッチを使用。3 つのプロンプトすべてに no-subagents 契約を追加。
+  - **Hermes Agent サポート**: 新しい `hermes-tools.md` リファレンスがスキルアクションを Hermes ツール（`delegate_task`、`skill_view` など）にマッピング。
+  - **Codex**: V1/V2 マルチエージェントの違い、`followup_task` による修正ラウンド再開、イベント購読型 `wait_agent` のガイダンス。
+  - **writing-plans**: プランテンプレートに `Spec:` フィールドを追加。
+  - **finishing-a-development-branch**: worktree 削除拒否時の手順 — 自分の判断で `--force` しない。
+- **デュアルエージェント code review による修正**: merged パスで「Commit them to \<branch\>」を選んでもファイルがベースブランチの外に取り残されない（finishing-a-development-branch）。`sdd-workspace.ps1` のスラッグ導出は全プラットフォームで `basename` と一致（`PLAN.MD` は `PLAN.MD` のまま）。
+- **意図的に未採用**: 上流 v6.3.0 のサーバー簡素化（loopback-only バインド、`O_NOFOLLOW` 読み取り、nonce CSP、ローカルブランド SVG の削除）— 本パッケージは強化版サーバーを維持。上流の `.ps1` 削除と plugin-only 再構成もこの MCP サーバー構成には適用されません。
+- **テスト**: MCP フロー、render-graphs（8 アサーション）、PowerShell 完全スイート（64 アサーション）すべて合格。
+
+### v6.2.4
+
+- **上流に合わせた brainstorm セッションの永続化**：`--project-dir` 指定時、companion はセッションキーを `.superpowers/brainstorm/.last-token`（オーナーのみ読み取り可、.gitignore 済み）に保存し、`.last-port` と並んで再起動後も再利用します——開いたままのブラウザタブは再起動後も接続を維持し、URL の再共有は不要です。一時 `/tmp` セッションでは従来どおり起動ごとにキーをローテーションします。明示的な `BRAINSTORM_TOKEN` 環境変数は常に優先され、ファイルには書き込まれません。強制的にローテーションするには、サーバー停止後に `.last-token` を削除してください。
+- **トークンファイル読み取り経路の強化**（`readPrivateFile`）：シンボリックリンクや複数リンクの `.last-token` は拒否され、セッションキーとして採用されなくなります。読み取りは `O_NOFOLLOW` 付き fd 経由で行い、identity を再検証し 0600 に締め付けます——既に強化済みの書き込み経路との非対称性を解消しました（独立したセキュリティレビューで発見）。
+- **診断性**：トークンファイルの書き込み失敗時に `Failed to write private token file:` をログ出力し、起動ごとのローテーションへの静かな縮退を防ぎます。
+- **start-server.ps1 の環境衛生**：`--project-dir` なしの一時起動で、呼び出し元 pwsh セッションに残ったプロジェクトキー/ポートを継承しなくなります。
+- **テスト**：companion スイートは 31 アサーションに——再起動をまたぐキー永続化、事前シード済みファイルの尊重、シンボリックリンクされたトークンファイルの拒否、トークンファイルなしでのローテーション維持。テスト後処理は障害安全（try/finally）。PowerShell スイートは `.last-token` が提供キーと一致することを検証します。
+
 ### v6.2.3（最新）
 
 - **Brainstorm Visual Companion の強化（`server.cjs`）**：ローカル loopback 限定の HTTP+WebSocket サーバーがファイルシステムのレースに耐性を持つようになりました（content ディレクトリの削除や画面ファイルの読み取り中の消失は待機ページ / 404 へフォールバック）。watcher はディレクトリの削除・再作成後に自己修復します（Linux inotify + macOS FSEvents）。WebSocket ハンドシェイクは RFC 6455 に基づき検証され、制御フレームは 125 バイト、idle/partial-frame に期限を設定し、接続上限時は最古の接続を破棄します。nonce CSP、起動ごとのキー更新、画面・スキル・イベントのサイズ上限、private state ファイルを適用しました。

package/README.ko.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | [繁體中文](README.zh-TW.md) | [日本語](README.ja.md) | [한국어](README.ko.md)
 
-[![Version](https://img.shields.io/badge/version-6.2.3-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
+[![Version](https://img.shields.io/badge/version-6.3.0-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 이 문서는 원본 Superpowers 스킬 라이브러리를 독립적인 MCP Toolpack으로 패키징하기 위한 정보와 사용 지침을 요약한 것입니다.
@@ -112,7 +112,7 @@
 이러한 스킬은 지원되는 IDE(Antigravity 또는 Cursor 등) 내에서 복잡한 메타 실행 패턴을 오케스트레이션하기 위해 설계되었습니다.
 
 - **`subagent-driven-development`**: 서브에이전트를 구동하여 작업 실행
-  - **사용법**: 미리 정의된 계획을 작업별로 실행합니다. 시스템은 각 작업마다 새로운 "구현" 서브에이전트를 생성한 후, 통합된 **작업 리뷰어**(명세 준수 + 코드 품질) 서브에이전트와 마지막에 **전체 브랜치 최종 리뷰**를 실행합니다. **Pre-Flight Plan Review**는 실행 시작 전 작업 충돌을 스캔합니다.
+  - **사용법**: 미리 정의된 계획을 작업별로 실행합니다. 시스템은 각 작업마다 새로운 "구현" 서브에이전트를 생성한 후, 통합된 **작업 리뷰어**(명세 준수 + 코드 품질) 서브에이전트와 마지막에 **전체 브랜치 최종 리뷰**를 실행합니다. **Pre-Flight Plan Review**는 실행 시작 전 작업 충돌을 스캔합니다. 계획은 plan-scoped 워크스페이스(`.superpowers/sdd/<plan>/`)에서 실행되며, 컨트롤러는 멈추지 않고 충돌을 재결정하여 레저(ledger)에 기록(rulings)하고, 같은 형태의 작은 작업은 단일 디스패치로 배치 처리됩니다.
   - **모델 선택**: 작업 복잡성에 따라 서브에이전트 모델 선택 — 기계적인 작업에는 저비용 모델, 아키텍처 및 미묘한 동시성 변경에는 고성능 모델
   - **예시**: "subagent-driven-development 스킬을 읽고 docs/plans/feature-plan.md에 나열된 작업을 하나씩 실행해줘"
 - **`dispatching-parallel-agents`**: 작업을 병렬 에이전트에 할당
@@ -128,6 +128,27 @@
 
 ## 🆕 최근 업데이트
 
+### v6.3.0 (최신)
+
+- **상류 obra/superpowers v6.3.0 동기화** — 적용 가능한 개선 사항을 모두 채택하고, 포크 고유의 보안 강화와 PowerShell 지원은 유지.
+  - **brainstorming — 3경로 라우터**: 모든 요청을 사전에 `spike` / `bounded` / `architectural`로 분류하며, 절차의 양은 작업 규모에 맞춰 조정됩니다. 단 승인 게이트는 모든 경로에 동일하게 적용됩니다. 실행 중 숨은 복잡성이 발견되면 경로를 업그레이드 — 다운그레이드는 없습니다.
+  - **subagent-driven-development — 멈추지 않고 재결정(rulings, not stalls)**: 충돌·모호성·계획 결함은 컨트롤러가 직접 재결정하고 레저에 기록(`Ruling: ...`). 명시된 4가지 조건에서만 실행을 중지합니다. Pre-flight 충돌 스캔은 레저 테이블을 산출하고, 같은 형태의 소규모 작업은 단일 디스패치로 배치되며, 서브에이전트 대기는 경계 있는 구간(bounded stretches)을 사용합니다. 세 프롬프트 모두 no-subagents 계약 추가.
+  - **Hermes Agent 지원**: 새 `hermes-tools.md` 참조 파일이 스킬 액션을 Hermes 도구(`delegate_task`, `skill_view` 등)에 매핑.
+  - **Codex**: V1/V2 멀티에이전트 차이, `followup_task` 수정 라운드 재개, 이벤트 구독형 `wait_agent` 가이드.
+  - **writing-plans**: 계획 템플릿에 `Spec:` 필드 추가.
+  - **finishing-a-development-branch**: worktree 제거 거부 시 절차 — 임의로 `--force`하지 않음.
+- **이중 에이전트 code review 수정**: 병합 경로에서 "Commit them to \<branch\>"를 선택해도 파일이 베이스 브랜치 밖에 남지 않음(finishing-a-development-branch). `sdd-workspace.ps1`의 슬러그 도출은 모든 플랫폼에서 `basename`과 일치(`PLAN.MD`는 `PLAN.MD` 유지).
+- **의도적으로 미채택**: 상류 v6.3.0의 서버 단순화(loopback-only 바인딩, `O_NOFOLLOW` 읽기, nonce CSP, 로컬 브랜드 SVG 제거) — 본 패키지는 강화된 서버를 유지합니다. 상류의 `.ps1` 삭제와 plugin-only 재구성도 이 MCP 서버 구성에는 적용되지 않습니다.
+- **테스트**: MCP 플로우, render-graphs(8개 어서션), PowerShell 전체 스위트(64개 어서션) 모두 통과.
+
+### v6.2.4
+
+- **업스트림 정렬 — brainstorm 세션 영속화**: `--project-dir` 사용 시 companion이 세션 키를 `.superpowers/brainstorm/.last-token`(소유자 전용, .gitignore 적용)에 저장하고 `.last-port`와 함께 재시작 후에도 재사용합니다 — 이미 열린 브라우저 탭은 재시작 후에도 연결이 유지되며 URL을 다시 공유할 필요가 없습니다. 임시 `/tmp` 세션은 기존처럼 호출마다 키를 교체하며, 명시적 `BRAINSTORM_TOKEN` 환경 변수는 항상 우선하고 파일에 기록되지 않습니다. 강제 교체를 원하면 서버 중지 후 `.last-token`을 삭제하세요.
+- **토큰 파일 읽기 경로 강화** (`readPrivateFile`): 심볼릭 링크 또는 다중 링크 `.last-token`은 거부되어 세션 키로 채택되지 않습니다. 읽기는 `O_NOFOLLOW` fd를 통해 수행되고 identity를 재검증하며 0600으로 강화됩니다 — 이미 강화된 쓰기 경로와의 비대칭을 해소했습니다(독립 보안 리뷰에서 발견).
+- **진단 가능성**: 토큰 파일 쓰기 실패 시 `Failed to write private token file:`을 로그로 남겨 조용한 키 교체로의 퇴화를 방지합니다.
+- **start-server.ps1 환경 위생**: `--project-dir` 없는 임시 실행에서 호출한 pwsh 세션의 잔여 프로젝트 키/포트를 상속하지 않습니다.
+- **테스트**: companion 스위트가 31개 assertion으로 — 재시작 간 키 영속화, 사전 시드 파일 준수, 심볼릭 링크 토큰 파일 거부, 토큰 파일 없이도 키 교체 유지. 테스트 정리는 실패 안전(try/finally). PowerShell 스위트는 `.last-token`이 제공된 키와 일치함을 검증합니다.
+
 ### v6.2.3 (최신)
 
 - **Brainstorm Visual Companion 강화 (`server.cjs`)**：로컬 loopback 전용 HTTP+WebSocket 서버가 파일시스템 레이스에 안전하게 대응합니다（content 디렉터리 삭제 또는 화면 파일 소실 시 대기 페이지 / 404로 폴백）。watcher는 디렉터리 삭제·재생성 후 자가 치유됩니다（Linux inotify + macOS FSEvents）。WebSocket 핸드셰이크는 RFC 6455로 검증하고, 제어 프레임은 125바이트, idle/partial-frame deadline을 적용하며, 상한 도달 시 가장 오래된 연결을 제거합니다. nonce CSP, 시작별 키 로테이션, 화면·스킬·이벤트 크기 제한, private state 파일을 적용했습니다.

package/README.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | [繁體中文](README.zh-TW.md) | [日本語](README.ja.md) | [한국어](README.ko.md)
 
-[![Version](https://img.shields.io/badge/version-6.2.3-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
+[![Version](https://img.shields.io/badge/version-6.3.0-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 This document summarizes the information and usage instructions for packaging the original Superpowers skills library into an independent MCP Toolpack.
@@ -112,7 +112,7 @@ To help you choose the right skill, we've categorized them into 6 logical phases
 These skills are designed for orchestrating complex meta-execution patterns within supported IDEs (like Antigravity or Cursor).
 
 - **`subagent-driven-development`**: Driving sub-agents to execute tasks
-  - **Usage**: Used to execute a predefined plan task-by-task. The system spawns a fresh "implementer" sub-agent per task, followed by a consolidated **task reviewer** (spec compliance + code quality) sub-agent, plus a **whole-branch final review** at the end. A **Pre-Flight Plan Review** scans for task conflicts before execution begins.
+  - **Usage**: Used to execute a predefined plan task-by-task. The system spawns a fresh "implementer" sub-agent per task, followed by a consolidated **task reviewer** (spec compliance + code quality) sub-agent, plus a **whole-branch final review** at the end. A **Pre-Flight Plan Review** scans for task conflicts before execution begins. Plans run in plan-scoped workspaces (`.superpowers/sdd/<plan>/`), the controller rules on conflicts and records them in the ledger instead of stopping, and small same-shape tasks are batched into a single dispatch.
   - **Model Selection**: Choose sub-agent models based on task complexity — cheaper models for mechanical work, capable models for architecture and subtle concurrency changes.
   - **Example**: "Read the subagent-driven-development skill, then execute the tasks listed in docs/plans/feature-plan.md one by one."
 - **`dispatching-parallel-agents`**: Dispatching tasks to parallel agents
@@ -128,7 +128,28 @@ These skills are designed for orchestrating complex meta-execution patterns with
 
 ## 🆕 Recent Updates
 
-### v6.2.3 (Latest)
+### v6.3.0 (Latest)
+
+- **Upstream sync with obra/superpowers v6.3.0** — all applicable improvements adopted, fork-specific security hardening and PowerShell support preserved.
+  - **brainstorming — three-path router**: every request is classified `spike` / `bounded` / `architectural` up front; the ceremony scales with the task but the approval gate never does. Hidden complexity upgrades the path mid-task — never downgrades.
+  - **subagent-driven-development — rulings, not stalls**: conflicts, ambiguities, and plan defects are ruled on and ledgered (`Ruling: ...`) instead of parking the session on a human; only four named conditions stop execution. Pre-flight conflict scans produce a ledgered table, small same-shape tasks batch into one dispatch, subagent waits use bounded stretches, and all three prompts carry the no-subagents contract.
+  - **Hermes Agent support**: new `hermes-tools.md` reference maps skill actions to Hermes tools (`delegate_task`, `skill_view`, …).
+  - **Codex**: V1/V2 multi-agent differences, `followup_task` fix-round resume, and event-subscription `wait_agent` guidance.
+  - **writing-plans**: plan template now carries a `Spec:` field.
+  - **finishing-a-development-branch**: worktree removal-refused procedure — never `--force` on your own initiative.
+- **Fixes from dual-agent code review**: merged-path "commit them to \<branch\>" no longer strands files outside the base branch (finishing-a-development-branch); `sdd-workspace.ps1` slug derivation matches `basename` on all platforms (`PLAN.MD` stays `PLAN.MD`).
+- **Not adopted (deliberate)**: upstream's v6.3.0 server simplification (it removed loopback-only enforcement, `O_NOFOLLOW` reads, nonce CSP, and the local brand SVG) — this package keeps its hardened server; upstream's `.ps1` deletions and plugin-only restructuring also don't apply to this MCP server layout.
+- **Tests**: MCP flow, render-graphs (8 assertions), and the full PowerShell suite (64 assertions) all pass.
+
+### v6.2.4
+
+- **Upstream alignment — persistent brainstorm sessions**: with `--project-dir`, the companion now persists its session key to `.superpowers/brainstorm/.last-token` (owner-only, gitignored) alongside `.last-port` and reuses it across restarts — an already-open browser tab stays connected after a restart, no URL re-sharing needed. Ephemeral `/tmp` sessions keep rotating the key per invocation, and an explicit `BRAINSTORM_TOKEN` env var still wins and is never persisted. Delete `.last-token` (server stopped) to force a fresh key.
+- **Token-file read path hardened** (`readPrivateFile`): symlinked or multi-link `.last-token` files are rejected instead of being adopted as the session key, with the read performed through an `O_NOFOLLOW` fd whose identity is re-checked and tightened to 0600 — closing the asymmetry with the already-hardened write path (found by independent security review).
+- **Diagnosability**: a failed token-file write now logs `Failed to write private token file:` instead of silently degrading to per-start key rotation.
+- **start-server.ps1 env hygiene**: an ephemeral (no `--project-dir`) launch no longer inherits a stale project key/port from the invoking pwsh session.
+- **Tests**: companion suite now 31 assertions — token persistence across restarts, pre-seeded file honored, symlinked token file rejected, rotation preserved without a token file; test cleanup is failure-safe (try/finally). PowerShell suite asserts `.last-token` matches the served key.
+
+### v6.2.3
 
 - **Hardened Brainstorming Visual Companion (`server.cjs`)**: the local loopback-only HTTP+WebSocket server is crash-resistant against filesystem races (a deleted content dir or a screen vanishing mid-read degrades to the waiting page / 404 instead of killing the process), and its watcher self-heals after the content dir is deleted and recreated (Linux inotify + macOS FSEvents). WebSocket handshakes are validated against RFC 6455 (version/upgrade/connection/key), control-frame payloads are capped at 125 bytes, clients have idle/partial-frame deadlines, and the oldest connection is evicted when the cap is full. Security headers now include `nosniff` and a nonce CSP; generated keys rotate per invocation; screen, skill, event, and user-event reads/logs are size-capped and state files are private.
 - **Companion security defaults**: the server only binds to loopback HTTP, rotates its key on every invocation, stores browser authentication only in an HttpOnly/SameSite cookie after the initial URL, and blocks unnonce'd scripts in screen HTML. Remote browsers must use an authenticated SSH tunnel; a restart requires sharing the new `server-info` URL.

package/README.zh-TW.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | [繁體中文](README.zh-TW.md) | [日本語](README.ja.md) | [한국어](README.ko.md)
 
-[![版本](https://img.shields.io/badge/version-6.2.3-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
+[![版本](https://img.shields.io/badge/version-6.3.0-blue.svg)](https://github.com/Poseidoncode/superpowers-mcp)
 [![授權](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 
 本文檔總結了將原始 Superpowers 技能庫打包成獨立 MCP Toolpack 的相關資訊與使用說明。
@@ -112,7 +112,7 @@
 這是特別針對在支援多重代理 (Multi-Agent) 協作或具備強大推論能力的 IDE（如 Antigravity 或 Cursor）中所設計的高階操作技巧。
 
 - **`subagent-driven-development`**: 驅動子代理執行複雜任務
-  - **具體用法**：適用於「執行已規劃好的詳細計畫」。針對每一個小任務，AI 會派發全新的「實作代理」去寫 Code，完成後啟動合併的 **task reviewer**（規格 + 品質一次審查），並在最後執行 **whole-branch final review**（全分支最終審查）。在執行前還會進行 **Pre-Flight Plan Review**，掃描任務之間的潛在衝突。
+  - **具體用法**：適用於「執行已規劃好的詳細計畫」。針對每一個小任務，AI 會派發全新的「實作代理」去寫 Code，完成後啟動合併的 **task reviewer**（規格 + 品質一次審查），並在最後執行 **whole-branch final review**（全分支最終審查）。在執行前還會進行 **Pre-Flight Plan Review**，掃描任務之間的潛在衝突。計畫在 plan-scoped 工作區（`.superpowers/sdd/<plan>/`）執行；控制器對衝突直接裁決並記錄於 ledger（rulings），不再停擺等待；相同形狀的小任務會批次合併為單次派發。
   - **模型選擇**：根據任務複雜度選擇子代理模型 — 機械性工作用低成本模型，架構設計與細微併發變更需要強大模型。
   - **指令範例**：「用 read_skill 讀取 subagent-driven-development 技能，然後依照 docs/plans/feature-plan.md 的內容逐一派發子代理實作。」
 - **`dispatching-parallel-agents`**: 派發平行代理同步執行任務
@@ -128,6 +128,27 @@
 
 ## 🆕 最近更新
 
+### v6.3.0 (最新版)
+
+- **對齊上游 obra/superpowers v6.3.0** — 採用所有適用改進，保留本 fork 的安全強化與 PowerShell 支援。
+  - **brainstorming — 三路分類流程（three-path router）**：每個請求先分類為 `spike` / `bounded` / `architectural`；流程深度隨任務規模調整，但審批門檻永遠不變。隱藏複雜度會在執行途中升級路徑——絕不降級。
+  - **subagent-driven-development — 裁決而非停擺（rulings, not stalls）**：衝突、歧義與計畫缺陷由控制器直接裁決並記錄於 ledger（`Ruling: ...`），不再等待人類；僅四種明列情況會停止執行。Pre-flight 衝突掃描產出 ledger 表格，相同形狀的小任務批次合併為單次派發，子代理等待改用有界區間，三個 prompt 都帶有 no-subagents 契約。
+  - **Hermes Agent 支援**：新增 `hermes-tools.md` 參考檔，將技能動作對應到 Hermes 工具（`delegate_task`、`skill_view` 等）。
+  - **Codex**：V1/V2 多代理差異、`followup_task` 修復輪恢復、事件訂閱式 `wait_agent` 指引。
+  - **writing-plans**：計畫範本新增 `Spec:` 欄位。
+  - **finishing-a-development-branch**：worktree 移除被拒時的處理程序——絕不擅自 `--force`。
+- **雙代理 code review 修復**：merged path 下「Commit them to \<branch\>」不再讓檔案遺留在 base branch 之外（finishing-a-development-branch）；`sdd-workspace.ps1` 的 slug 推導在所有平台與 `basename` 一致（`PLAN.MD` 維持 `PLAN.MD`）。
+- **刻意未採用**：上游 v6.3.0 的 server 簡化（移除 loopback-only 綁定、`O_NOFOLLOW` 讀取、nonce CSP、本地品牌 SVG）——本套件保留加固版 server；上游刪除 `.ps1` 及轉為 plugin-only 架構亦不適用於本 MCP server 佈局。
+- **測試**：MCP 流程、render-graphs（8 斷言）、完整 PowerShell 套件（64 斷言）全部通過。
+
+### v6.2.4
+
+- **對齊上游 — brainstorm 持久化 session**：搭配 `--project-dir` 時，companion 現在會把 session 金鑰持久化到 `.superpowers/brainstorm/.last-token`（僅擁有者可讀、已列入 .gitignore），與 `.last-port` 並存並在重啟後重用——已開啟的瀏覽器分頁在重啟後依然保持連線，無需重新分享 URL。暫存 `/tmp` session 仍維持每次啟動輪換金鑰；明確設定的 `BRAINSTORM_TOKEN` env 依然優先且永不寫入檔案。若要強制輪換，請在停止伺服器後刪除 `.last-token`。
+- **Token 檔讀取路徑加固**（`readPrivateFile`）：symlink 或多重連結的 `.last-token` 現在會被拒絕，不再被採納為 session 金鑰；讀取透過 `O_NOFOLLOW` fd 進行，身份複查並收緊為 0600——補上與已加固寫入路徑之間的不對稱（由獨立資安審查發現）。
+- **可診斷性**：token 檔寫入失敗現在會記錄 `Failed to write private token file:`，不再靜默退化為每次啟動輪換金鑰。
+- **start-server.ps1 環境衛生**：無 `--project-dir` 的暫存啟動不再繼承呼叫端 pwsh session 中殘留的專案金鑰/埠號。
+- **測試**：companion 套件現為 31 個斷言——重啟後金鑰持久化、預置檔原樣採用、symlink token 檔被拒絕、無 token 檔時仍輪換；測試清理具失敗安全性（try/finally）。PowerShell 套件斷言 `.last-token` 與伺服器提供之金鑰一致。
+
 ### v6.2.3 (最新版)
 
 - **Brainstorm Visual Companion 強化 (`server.cjs`)**：本機 loopback 限定的 HTTP+WebSocket 伺服器可安全處理檔案系統競態（content 目錄被刪除或畫面檔消失時降級為等待頁 / 404）；watcher 在目錄刪除重建後自動自癒（Linux inotify + macOS FSEvents）。WebSocket handshake 依 RFC 6455 驗證，控制訊框上限 125 bytes，並加入 idle/partial-frame deadline，滿額時淘汰最舊連線。套用 nonce CSP、每次啟動輪換金鑰、畫面/技能/事件大小上限與私有 state 檔案。

package/out/server.js

@@ -49,7 +49,7 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
 `}var vs=class{constructor(t=hf.default.stdin,r=hf.default.stdout){this._stdin=t,this._stdout=r,this._readBuffer=new gs,this._started=!1,this._ondata=n=>{this._readBuffer.append(n),this.processReadBuffer()},this._onerror=n=>{this.onerror?.(n)}}async start(){if(this._started)throw new Error("StdioServerTransport already started! If using Server class, note that connect() calls start() automatically.");this._started=!0,this._stdin.on("data",this._ondata),this._stdin.on("error",this._onerror)}processReadBuffer(){for(;;)try{let t=this._readBuffer.readMessage();if(t===null)break;this.onmessage?.(t)}catch(t){this.onerror?.(t)}}async close(){this._stdin.off("data",this._ondata),this._stdin.off("error",this._onerror),this._stdin.listenerCount("data")===0&&this._stdin.pause(),this._readBuffer.clear(),this.onclose?.()}send(t){return new Promise(r=>{let n=j_(t);this._stdout.write(n)?r():this._stdout.once("drain",r)})}};var ze=sr(require("fs/promises")),ye=sr(require("path")),$n=10*1024*1024,ys=class{skillsPath;cachedSkills=null;loadingPromise=null;skillMap=new Map;contentCache=new Map;constructor(t){this.skillsPath=t}stripQuotes(t){return t.replace(/^"(.*)"$|^'(.*)'$/,"$1$2").trim()}parseFrontmatter(t){let r=t;if(r.charCodeAt(0)===65279&&(r=r.slice(1)),!r.startsWith("---"))return{name:"",description:""};let n=r.split(/\r?\n/),o=[],i=!1;for(let u=1;u<n.length;u++){if(n[u].trim()==="---"){i=!0;break}o.push(n[u])}if(!i)return{name:"",description:""};let a="",s="",c=!1;for(let u of o){let l=u.match(/^name:\s*(.*?)\s*$/);if(l){a=this.stripQuotes(l[1]),c=!1;continue}let d=u.match(/^description:\s*(.*?)\s*$/);if(d){s=this.stripQuotes(d[1]),c=!0;continue}c&&/^\s+/.test(u)?s+=" "+u.trim():c=!1}return{name:a,description:s}}async exists(t){try{return await ze.access(t),!0}catch{return!1}}async listSkills(t=!1){if(this.cachedSkills&&!t)return this.cachedSkills;if(this.loadingPromise&&!t)return this.loadingPromise;t&&this.contentCache.clear();let r=this.internalListSkills();this.loadingPromise=r;try{return await r}finally{this.loadingPromise===r&&(this.loadingPromise=null)}}async internalListSkills(){if(!await this.exists(this.skillsPath))return this.cachedSkills??[];let t=[],r=new Map,n=!1;try{let o=await ze.readdir(this.skillsPath,{withFileTypes:!0});for(let i of o){if(!i.isDirectory()&&!i.isSymbolicLink())continue;let a=ye.join(this.skillsPath,i.name),s=ye.join(a,"SKILL.md");if(await this.exists(s))try{let c=await this.readFileNoFollow(s,this.skillsPath),{name:u,description:l}=this.parseFrontmatter(c),m={name:u||i.name,description:l,skillPath:s};t.push(m),r.set(m.name.toLowerCase(),m);let p=ye.basename(ye.dirname(m.skillPath)).toLowerCase();r.set(p,m)}catch{process.stderr.write(`Warning: Failed to read skill file in directory "${i.name}"
 `)}}n=!0}catch(o){process.stderr.write(`Error reading skills directory: ${String(o)}
 `)}return n&&(this.skillMap=r,this.cachedSkills=t.sort((o,i)=>o.name.localeCompare(i.name))),this.cachedSkills??[]}async findSkill(t){let r=typeof t=="string"?t.trim():"";if(!(!r||r==="."||r===".."||r.includes("/")||r.includes("\\")||r.includes("\0")))return this.cachedSkills||await this.listSkills(),this.skillMap.get(r.toLowerCase())}async readFileNoFollow(t,r){let n=ye.resolve(t),o=ye.resolve(r),i=async()=>{let l=await ze.realpath(n),d=await ze.realpath(o);if(!(await ze.stat(d)).isDirectory())throw new Error("Skills directory must be a directory");let p=ye.relative(d,l);if(p===".."||p.startsWith(`..${ye.sep}`)||ye.isAbsolute(p))throw new Error("File is outside skills directory");let h=await ze.stat(l);if(!h.isFile()||h.nlink!==1)throw new Error("Skill path is not a regular file");if(h.size>$n)throw new Error("Skill file exceeds size limit");return{realFilePath:l,stat:h}},a=await i(),s=await i();if(a.realFilePath!==s.realFilePath||a.stat.dev!==s.stat.dev||a.stat.ino!==s.stat.ino)throw new Error("File changed while validating its path");let c=process.platform==="win32"?0:ze.constants.O_NOFOLLOW,u=await ze.open(s.realFilePath,ze.constants.O_RDONLY|c);try{let l=await u.stat();if(!l.isFile()||l.nlink!==1||l.dev!==s.stat.dev||l.ino!==s.stat.ino||l.size>$n)throw new Error("File changed while opening");let d=[],m=64*1024,p=0;for(;p<=$n;){let v=Buffer.allocUnsafe(Math.min(m,$n+1-p)),{bytesRead:$}=await u.read(v,0,v.length,null);if($===0)break;if(p+=$,d.push(v.subarray(0,$)),p>$n)throw new Error("Skill file exceeds size limit")}let h=await u.stat();if(h.size>$n||h.dev!==s.stat.dev||h.ino!==s.stat.ino)throw new Error("File changed while reading");return Buffer.concat(d,p).toString("utf-8")}finally{await u.close()}}async readSkillContent(t,r=!1){let n=ye.resolve(t),o=ye.resolve(this.skillsPath),i=n,a=o;try{i=await ze.realpath(n),a=await ze.realpath(o)}catch{}let s=ye.relative(a,i);if(s.startsWith("..")||ye.isAbsolute(s))throw new Error(`Access denied: path "${t}" is outside skills directory`);if(this.contentCache.has(i)&&!r)return this.contentCache.get(i);try{let c=await this.readFileNoFollow(t,this.skillsPath);c.charCodeAt(0)===65279&&(c=c.slice(1));let u=c.replace(/^---\s*\r?\n[\s\S]*?\r?\n---\s*\r?\n?/,"").trim();return this.contentCache.set(i,u),u}catch(c){throw new Error(`Failed to read skill content: ${c instanceof Error?c.message:String(c)}`)}}clearCache(){this.cachedSkills=null,this.loadingPromise=null,this.skillMap.clear(),this.contentCache.clear()}};function jT(){let e=process.env.SKILLS_PATH;if(e){let r=ct.resolve(e),n=ct.normalize(r).toLowerCase(),o=ct.parse(r).root.toLowerCase();if(n===o||["/etc","/var","/bin","/sbin","/usr","/root","/sys","/proc","/dev","c:\\windows","c:\\program files","c:\\program files (x86)"].some(s=>n===s||n.startsWith(s+ct.sep)))process.stderr.write(`Warning: Potentially unsafe SKILLS_PATH: "${e}". Fallback to default.
-`);else return r}let t=ct.join(__dirname,"..","skills");return E_.existsSync(t)?t:ct.join(__dirname,"skills")}var O_=jT(),It=new ys(O_),Pr=new hs({name:"superpowers-mcp",version:"6.2.3"},{capabilities:{resources:{subscribe:!1},prompts:{},tools:{}}});Pr.setRequestHandler(od,async()=>({resources:(await It.listSkills()).map(t=>({uri:`skill://superpowers/${encodeURIComponent(t.name)}`,name:t.name,description:t.description,mimeType:"text/markdown"}))}));Pr.setRequestHandler(ad,async e=>{let t=e.params.uri,r=t.match(/^skill:\/\/superpowers\/(.+)$/);if(!r)throw new D(M.InvalidRequest,`Invalid skill URI: ${t}`);let n;try{n=decodeURIComponent(r[1])}catch{throw new D(M.InvalidRequest,`Invalid skill URI: ${t}`)}let o=await It.findSkill(n);if(!o)throw new D(M.InvalidRequest,`Skill not found: ${n}`);try{let i=await It.readSkillContent(o.skillPath);return{contents:[{uri:t,mimeType:"text/markdown",text:i}]}}catch{throw new D(M.InternalError,"Failed to read skill content safely.")}});Pr.setRequestHandler(sd,async()=>({prompts:[{name:"session-start",description:"Inject the Superpowers context into an AI agent session. Tells the agent it has superpowers and how to use the skill system."}]}));Pr.setRequestHandler(cd,async e=>{if(e.params.name!=="session-start")throw new D(M.InvalidRequest,`Unknown prompt: ${e.params.name}`);let t=await It.findSkill("using-superpowers"),r="";if(t)try{r=await It.readSkillContent(t.skillPath)}catch{r=`# Superpowers
+`);else return r}let t=ct.join(__dirname,"..","skills");return E_.existsSync(t)?t:ct.join(__dirname,"skills")}var O_=jT(),It=new ys(O_),Pr=new hs({name:"superpowers-mcp",version:"6.3.0"},{capabilities:{resources:{subscribe:!1},prompts:{},tools:{}}});Pr.setRequestHandler(od,async()=>({resources:(await It.listSkills()).map(t=>({uri:`skill://superpowers/${encodeURIComponent(t.name)}`,name:t.name,description:t.description,mimeType:"text/markdown"}))}));Pr.setRequestHandler(ad,async e=>{let t=e.params.uri,r=t.match(/^skill:\/\/superpowers\/(.+)$/);if(!r)throw new D(M.InvalidRequest,`Invalid skill URI: ${t}`);let n;try{n=decodeURIComponent(r[1])}catch{throw new D(M.InvalidRequest,`Invalid skill URI: ${t}`)}let o=await It.findSkill(n);if(!o)throw new D(M.InvalidRequest,`Skill not found: ${n}`);try{let i=await It.readSkillContent(o.skillPath);return{contents:[{uri:t,mimeType:"text/markdown",text:i}]}}catch{throw new D(M.InternalError,"Failed to read skill content safely.")}});Pr.setRequestHandler(sd,async()=>({prompts:[{name:"session-start",description:"Inject the Superpowers context into an AI agent session. Tells the agent it has superpowers and how to use the skill system."}]}));Pr.setRequestHandler(cd,async e=>{if(e.params.name!=="session-start")throw new D(M.InvalidRequest,`Unknown prompt: ${e.params.name}`);let t=await It.findSkill("using-superpowers"),r="";if(t)try{r=await It.readSkillContent(t.skillPath)}catch{r=`# Superpowers
 
 You have superpowers. Use the read_skill and list_skills tools to discover and load skills.`}else{let o=ct.join(O_,"using-superpowers","SKILL.md");try{r=await It.readSkillContent(o)}catch{r=`# Superpowers
 

package/package.json

@@ -2,7 +2,7 @@
   "name": "superpowers-mcp",
   "displayName": "Superpowers MCP",
   "description": "Superpowers skills library (TDD, debugging, collaboration workflows) as an MCP server for VSCode and Antigravity",
-  "version": "6.2.3",
+  "version": "6.3.0",
   "publisher": "superpowers",
   "license": "MIT",
   "repository": {

package/skills/brainstorming/SKILL.md

@@ -7,20 +7,91 @@ description: "You MUST use this before any creative work - creating features, bu
 
 Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
 
-Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and get user approval.
+Start by classifying how much process the request needs, then work
+through your path: understand the context, refine the idea, present a
+design, and get your human partner's approval.
 
 <HARD-GATE>
-Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
+Do NOT invoke any implementation skill, write any code, scaffold any
+project, or take any implementation action until you have told your
+human partner what you intend and they have approved it. This applies
+to EVERY task on EVERY path below — the ceremony scales with the task;
+the approval gate never does.
 </HARD-GATE>
 
-## Anti-Pattern: "This Is Too Simple To Need A Design"
-
-Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.
+## Three Paths
+
+Before your first question, classify the request and say the
+classification out loud — "this looks bounded, so I'll present a short
+design here rather than write a spec" — so your human partner can
+override it:
+
+- **Spike** — a feasibility question ("can we...", "is it possible...",
+  "quick and dirty is fine") whose output is an answer, not code you
+  keep. Present the question and what you'll try in 2-3 sentences, get
+  a nod, then find out as cheaply as correctness allows. No design
+  doc, no spec file. Report findings as a recommendation; anything you
+  built stays labeled throwaway.
+- **Bounded** — a well-scoped change to code that already exists in
+  this repo: a new flag, a small endpoint, a one-file fix.
+  Understanding the kind of app is not enough — bounded means the flow
+  you are changing is already here to read. If there is no existing
+  flow to change, the task is not bounded. Ask the clarifying
+  questions that matter, present a short design IN CHAT (a few
+  sentences to a few short paragraphs), and STOP. Implementation
+  starts only after your human partner says yes to that design — a
+  bounded task's approval is as hard a gate as an architectural
+  one. No spec file, no implementation plan document.
+- **Architectural** — new projects, new subsystems, changes that
+  restructure how components fit together or alter interfaces others
+  depend on. Follow the full process: questions, approaches, sectioned
+  design, written spec, then the writing-plans skill.
+
+When in doubt between two paths, take the heavier one. The ratchet is
+one-way: hidden complexity discovered mid-task upgrades the path —
+stop, say so, and step up. Nothing downgrades mid-task.
+
+## Anti-Pattern: "Too Simple To Need Approval"
+
+Every path ends with your human partner approving your intent before
+implementation. A todo list, a single-function utility, a config
+change — the design may be two sentences in chat, but you MUST present
+it and get approval. "Simple" tasks are where unexamined assumptions
+cause the most wasted work. What scales with simplicity is the
+artifact, never the approval.
+
+## Red Flags
+
+| Thought | Reality |
+|---------|---------|
+| "This is too simple to need a design" | Simple means a short design, not no design. Two sentences in chat, then approval. |
+| "I'll call it bounded and skip the spec" | Reaching for a label to skip work IS the doubt — take the heavier path. |
+| "It's bounded and the design is obvious — I'll start while they read it" | The gate is the approval, not the design's length. Present, then stop until you hear yes. |
+| "I understand this kind of app, so it's bounded" | Bounded measures the repo, not your familiarity. A new project has no existing flow — it is architectural. |
+| "The spike works, so I'll keep the code" | A spike's output is an answer. Keeping the code is a new request — classify it. |
+| "It grew, but I'm almost done — no need to re-classify" | Hidden complexity upgrades the path mid-task. Stop and say so. |
+| "They approved the spike, so the follow-up change is approved too" | Each task gets its own classification and its own approval. |
 
 ## Checklist
 
-You MUST create a task for each of these items and complete them in order:
+Classify first, announce the path, then create a task for each item on
+your path and complete them in order.
+
+**Spike:**
+1. **Explore project context** — enough to frame the probe
+2. **Present question + probe plan** — 2-3 sentences
+3. **Get approval** — a nod is enough
+4. **Investigate** — as cheaply as correctness allows
+5. **Report findings** — a recommendation; label anything built as throwaway
+
+**Bounded:**
+1. **Explore project context** — check files, docs, recent commits
+2. **Ask clarifying questions** — one at a time, the ones that matter
+3. **Present short design in chat** — approach, files touched, testing
+4. **Get approval** — STOP and wait for an explicit yes; presenting the design and starting in the same breath is skipping the gate
+5. **Implement** — proceed with the normal development workflow (TDD applies); no plan document
 
+**Architectural:**
 1. **Explore project context** — check files, docs, recent commits
 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
@@ -35,6 +106,13 @@ You MUST create a task for each of these items and complete them in order:
 
 ```dot
 digraph brainstorming {
+    "Classify: spike / bounded / architectural" [shape=diamond];
+    "Present question + probe (2-3 sentences)" [shape=box];
+    "Ask clarifying questions (bounded)" [shape=box];
+    "Present short design in chat" [shape=box];
+    "Human approves?" [shape=diamond];
+    "Investigate; report recommendation" [shape=doublecircle];
+    "Implement via normal workflow (no plan doc)" [shape=doublecircle];
     "Explore project context" [shape=box];
     "Ask clarifying questions" [shape=box];
     "Propose 2-3 approaches" [shape=box];
@@ -44,7 +122,17 @@ digraph brainstorming {
     "Spec self-review\n(fix inline)" [shape=box];
     "User reviews spec?" [shape=diamond];
     "Invoke writing-plans skill" [shape=doublecircle];
-
+    "Hidden complexity? Upgrade path" [shape=box];
+
+    "Classify: spike / bounded / architectural" -> "Present question + probe (2-3 sentences)" [label="spike"];
+    "Classify: spike / bounded / architectural" -> "Ask clarifying questions (bounded)" [label="bounded"];
+    "Classify: spike / bounded / architectural" -> "Explore project context" [label="architectural"];
+    "Present question + probe (2-3 sentences)" -> "Human approves?";
+    "Ask clarifying questions (bounded)" -> "Present short design in chat";
+    "Present short design in chat" -> "Human approves?";
+    "Human approves?" -> "Investigate; report recommendation" [label="spike: yes"];
+    "Human approves?" -> "Implement via normal workflow (no plan doc)" [label="bounded: yes"];
+    "Hidden complexity? Upgrade path" -> "Classify: spike / bounded / architectural";
     "Explore project context" -> "Ask clarifying questions";
     "Ask clarifying questions" -> "Propose 2-3 approaches";
     "Propose 2-3 approaches" -> "Present design sections";
@@ -58,10 +146,21 @@ digraph brainstorming {
 }
 ```
 
-**The terminal state is invoking writing-plans.** Do NOT invoke frontend-design, mcp-builder, or any other implementation skill. The ONLY skill you invoke after brainstorming is writing-plans.
+**Terminal states are path-bound.** Architectural: the ONLY skill you
+invoke after brainstorming is writing-plans — never frontend-design,
+mcp-builder, or any other implementation skill. Bounded: after
+approval, implementation proceeds directly through the normal
+development workflow; no plan document. Spike: the terminal state is a
+reported recommendation.
 
 ## The Process
 
+The subsections below serve the bounded and architectural paths (a
+spike stops at "present the probe, get a nod"). Sections from
+**Exploring approaches** onward are architectural-path depth — for
+bounded work, context plus a few questions plus a short in-chat design
+is the whole process.
+
 **Understanding the idea:**
 
 - Check out the current project state first (files, docs, recent commits)
@@ -100,7 +199,7 @@ digraph brainstorming {
 - Where existing code has problems that affect the work (e.g., a file that's grown too large, unclear boundaries, tangled responsibilities), include targeted improvements as part of the design - the way a good developer improves code they're working in.
 - Don't propose unrelated refactoring. Stay focused on what serves the current goal.
 
-## After the Design
+## After the Design (architectural path)
 
 **Documentation:**
 

package/skills/brainstorming/scripts/server.cjs

@@ -101,9 +101,17 @@ function decodeFrame(buffer) {
 // ========== Configuration ==========
 
 const PORT_FILE = process.env.BRAINSTORM_PORT_FILE || null;
+// Per-session secret key. The companion is reachable by any local browser tab.
+// The key authenticates the client, rides the served URL as ?key=, and is
+// mirrored into a HttpOnly cookie on first load so the WebSocket and /files/*
+// subresources authenticate for free. When BRAINSTORM_TOKEN_FILE is set (the
+// persistent --project-dir launcher mode), the key is persisted alongside the
+// port so a restart reuses it and an already-open browser tab's cookie keeps
+// validating. Without a token file the key is rotated on every server start.
+const TOKEN_FILE = process.env.BRAINSTORM_TOKEN_FILE || null;
 const randomPort = () => 49152 + Math.floor(Math.random() * 16383);
 // Prefer an explicit port, else the port this session last bound, else a random
-// high port. Authentication is intentionally rotated on every server start.
+// high port.
 function preferredPort() {
   if (process.env.BRAINSTORM_PORT) {
     const p = Number(process.env.BRAINSTORM_PORT);
@@ -137,7 +145,10 @@ const SESSION_DIR = process.env.BRAINSTORM_DIR || '/tmp/brainstorm';
 const CONTENT_DIR = path.join(SESSION_DIR, 'content');
 const STATE_DIR = path.join(SESSION_DIR, 'state');
 const SUPERPOWERS_VERSION = readSuperpowersVersion();
-const SUPERPOWERS_BRAND_IMAGE_URL = 'https://primeradiant.com/brand/superpowers-visual-brainstorming-logo.png';
+// The brand mark is served locally from /brand-logo.svg so the page never
+// contacts a third-party host; the SVG payload is generated inline below.
+const SUPERPOWERS_BRAND_IMAGE_URL = '/brand-logo.svg';
+const BRAND_LOGO_SVG = "<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 180 24' role='img' aria-label='Superpowers'><g fill='#fff'><path d='M11 21h-1l1-7H7.5c-.58 0-.57-.32-.38-.66.19-.34.05-.08.07-.12C8.48 10.94 10.42 7.54 13 3h1l-1 7h3.5c.49 0 .56.33.47.51l-.07.15C12.96 17.55 11 21 11 21z' transform='translate(0 2.5) scale(0.62)'/><text x='24' y='17.5' font-family='system-ui, sans-serif' font-size='15' font-weight='700' letter-spacing='2.5'>SUPERPOWERS</text></g></svg>";
 const TELEMETRY_DISABLE_ENV_VARS = [
   'SUPERPOWERS_DISABLE_TELEMETRY',
   'DISABLE_TELEMETRY',
@@ -146,21 +157,68 @@ const TELEMETRY_DISABLE_ENV_VARS = [
 const SUPERPOWERS_TELEMETRY_DISABLED = TELEMETRY_DISABLE_ENV_VARS.some(name => isTruthyEnv(process.env[name]));
 let ownerPid = process.env.BRAINSTORM_OWNER_PID ? Number(process.env.BRAINSTORM_OWNER_PID) : null;
 
-// Each server invocation gets a fresh 256-bit secret. An explicitly supplied
-// BRAINSTORM_TOKEN is retained for controlled integrations, but launchers never
-// persist it across logical sessions.
+// A 256-bit secret. An explicitly supplied BRAINSTORM_TOKEN is retained for
+// controlled integrations. In persistent launcher mode (BRAINSTORM_TOKEN_FILE)
+// the key is reused across restarts so already-open tabs stay authenticated;
+// otherwise each server invocation gets a fresh key. Persistence is best effort:
+// a write failure must never prevent the server from starting.
 function generateToken() {
   return crypto.randomBytes(32).toString('hex');
 }
 
+// Mirror of writePrivateFile for the read path: the token file must be a
+// regular, single-link, non-symlink file. The fd is opened with O_NOFOLLOW and
+// its identity re-checked, and it is tightened to 0600 via the fd — never a
+// path-based chmod, which would follow a symlink to an attacker-chosen target.
+// Returns the file content or null on any violation/error.
+function readPrivateFile(filePath) {
+  const noFollow = fs.constants.O_NOFOLLOW || 0;
+  try {
+    const before = fs.lstatSync(filePath);
+    if (before.isSymbolicLink() || !before.isFile() || before.nlink !== 1) return null;
+    const fd = fs.openSync(filePath, fs.constants.O_RDONLY | noFollow);
+    try {
+      const stat = fs.fstatSync(fd);
+      if (!stat.isFile() || stat.nlink !== 1 || !sameFileIdentity(before, stat)) return null;
+      fs.fchmodSync(fd, 0o600);
+      return fs.readFileSync(fd, 'utf-8');
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch (e) {
+    return null;
+  }
+}
+
 function initialToken() {
   if (process.env.BRAINSTORM_TOKEN) {
     const t = String(process.env.BRAINSTORM_TOKEN).trim();
     if (/^[0-9a-f]{32,}$/i.test(t)) {
+      // A file path is not touched when the env token wins: the env value is a
+      // transient override for controlled integrations, and persisting it would
+      // turn a one-off secret into a durable one. Note the interaction: a later
+      // launch without the env var falls back to whatever .last-token holds.
       return { value: t, source: 'env' };
     }
   }
-  return { value: generateToken(), source: 'generated' };
+  if (TOKEN_FILE && path.isAbsolute(TOKEN_FILE)) {
+    // No prior token recorded (or the file fails the regular-file checks below)
+    // — either way, fall through to generating a fresh key.
+    const t = readPrivateFile(TOKEN_FILE);
+    if (t !== null && /^[0-9a-f]{32,}$/i.test(t.trim())) {
+      return { value: t.trim(), source: 'file' };
+    }
+  }
+  const generated = { value: generateToken(), source: 'generated' };
+  if (TOKEN_FILE && path.isAbsolute(TOKEN_FILE)) {
+    // Persist the key so a restart reuses it; best effort only — a write
+    // failure must never prevent the server from starting, but it silently
+    // degrades "restart keeps the tab alive" into per-start rotation.
+    if (!writePrivateFile(TOKEN_FILE, generated.value + '\n')) {
+      console.error('Failed to write private token file:', TOKEN_FILE);
+    }
+  }
+  return generated;
 }
 
 const tokenInfo = initialToken();
@@ -252,7 +310,7 @@ function brandMarkup() {
     : 'Superpowers v' + version;
   const logo = SUPERPOWERS_TELEMETRY_DISABLED
     ? ''
-    : '<img class="brand-logo" src="' + SUPERPOWERS_BRAND_IMAGE_URL + '?v=' + encodeURIComponent(SUPERPOWERS_VERSION) + '" alt="Prime Radiant" referrerpolicy="no-referrer" decoding="async">';
+    : '<img class="brand-logo" src="' + SUPERPOWERS_BRAND_IMAGE_URL + '" alt="Prime Radiant" referrerpolicy="no-referrer" decoding="async">';
 
   return '<div class="brand"><a href="https://github.com/obra/superpowers">' + logo + '<span class="brand-copy">' + text + '</span></a></div>';
 }
@@ -571,7 +629,7 @@ function securityHeaders(headers = {}, scriptNonce = null) {
     'Cache-Control': 'no-store',
     'X-Frame-Options': 'DENY',
     'X-Content-Type-Options': 'nosniff',
-    'Content-Security-Policy': "default-src 'none'; script-src " + scriptSource + "; style-src 'unsafe-inline'; img-src 'self' https://primeradiant.com data:; connect-src 'self' ws: wss:; frame-ancestors 'none'; base-uri 'none'; object-src 'none'; form-action 'none'",
+    'Content-Security-Policy': "default-src 'none'; script-src " + scriptSource + "; style-src 'unsafe-inline'; img-src 'self'; connect-src 'self' ws: wss:; frame-ancestors 'none'; base-uri 'none'; object-src 'none'; form-action 'none'",
     'Cross-Origin-Resource-Policy': 'same-origin',
     ...headers
   };
@@ -619,6 +677,10 @@ function handleRequest(req, res) {
 
     res.writeHead(200, securityHeaders({ 'Content-Type': 'text/html; charset=utf-8' }, nonce));
     res.end(html);
+  } else if (req.method === 'GET' && pathname === '/brand-logo.svg') {
+    // Locally-generated brand mark; same-origin so img-src 'self' suffices.
+    res.writeHead(200, securityHeaders({ 'Content-Type': 'image/svg+xml; charset=utf-8' }));
+    res.end(BRAND_LOGO_SVG);
   } else if (req.method === 'GET' && pathname.startsWith('/files/')) {
     const fileName = path.basename(pathname.slice(7));
     const filePath = path.join(CONTENT_DIR, fileName);
@@ -1067,8 +1129,11 @@ function startServer() {
     // 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 only when we got our preferred port. Authentication
-    // is deliberately not persisted, so a new logical session gets a new key.
+    // Record the bound port only when we got our preferred port, so a stale
+    // port file from a crashed fallback can't pin a future session to a port
+    // another server owns. The session key, by contrast, is persisted whenever
+    // BRAINSTORM_TOKEN_FILE is set (see initialToken) — the pair is what keeps
+    // an already-open tab's cookie valid across a restart.
     if (PORT_FILE && !triedFallback) {
       if (!writePrivateFile(PORT_FILE, String(PORT))) {
         console.error('Failed to write private port file');

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

@@ -156,9 +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"
@@ -247,6 +255,7 @@ $envValues = @{
     BRAINSTORM_URL_HOST = $urlHost
     BRAINSTORM_OWNER_PID = ""
     BRAINSTORM_PORT_FILE = $env:BRAINSTORM_PORT_FILE
+    BRAINSTORM_TOKEN_FILE = $env:BRAINSTORM_TOKEN_FILE
     BRAINSTORM_IDLE_TIMEOUT_MS = $env:BRAINSTORM_IDLE_TIMEOUT_MS
     BRAINSTORM_OPEN = $env:BRAINSTORM_OPEN
 }

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

@@ -135,9 +135,10 @@ SESSION_ID="$$-$(date +%s)"
 
 if [[ -n "$PROJECT_DIR" ]]; then
   SESSION_DIR="${PROJECT_DIR}/.superpowers/brainstorm/${SESSION_ID}"
-  # Reusing a port is safe because the server rotates its authentication key
-  # for every logical session.
+  # 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
   SESSION_DIR="/tmp/brainstorm-${SESSION_ID}"
 fi