@blackbelt-technology/pi-agent-dashboard 0.4.6 → 0.5.1

package/AGENTS.md

@@ -5,9 +5,134 @@
 
 Web-based dashboard for monitoring and interacting with pi agent sessions remotely. Three-component architecture: bridge extension + Node.js server + React web client.
 
+## STOP — Docs-First Gate
+
+**Before any build / run / install / setup / release / "how do I X" question: `grep -i <keyword> docs/faq.md README.md docs/` FIRST. No source reads until that returns nothing.**
+
+If you read a script, config, or source file before grepping docs on a how-to, what-is question, you violated the protocol. Re-grep, then answer.
+
+- ❌ User: "how do I ..." → read `<src files>` → guess answer
+- ✅ User: "how do I ..." → `grep -ni '<words>' docs/faq.md` → quote the FAQ entry
+
+- ❌ User: "what is ..." → read `scripts/build-installer.sh`, `forge.config.ts` → guess answer
+- ✅ User: "what is ..." → `grep -ni '<words>' docs/index-*.md` → quote the entry
+
+Full protocol (index-first for code questions, file-index splits, etc.) is in [Investigation Protocol — Index First](#investigation-protocol--index-first) below.
+
+## Code Instructions
+
+Behavioral guidelines to reduce common LLM coding mistakes. Bias toward caution over speed. For trivial tasks, use judgment.
+
+### 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask via `ask_user`.
+- If multiple interpretations exist, present them — don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+- **Never speculate about code you have not opened.** If the user references a specific file, read it before answering. No claims about the codebase without investigation — grounded, hallucination-free answers only.
+- Before any major change, check in with the user and confirm the plan.
+
+### 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+- **DRY:** if the same pattern appears in multiple places, extract a shared helper/class/component. Don't pre-extract for a single call site.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+### 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it — don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: every changed line should trace directly to the user's request.
+
+### 4. Goal-Driven Execution (TDD)
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For implementation, use **TDD**: write or update tests first to define expected behaviour, verify they fail, then write the minimal implementation to make them pass.
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+### 5. Communication
+
+- At every step, give a high-level explanation of what changed — don't dump diffs without summary.
+- Use `ask_user` (not plain-text questions) when you need clarification, confirmation, or a choice.
+
+---
+
+**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.
+
+## Documentation Update Protocol
+
+**Default assumption: your update does NOT belong in AGENTS.md.** AGENTS.md loads into every agent's context on every turn — every byte costs tokens. Route by kind:
+
+| Kind of update | Goes in |
+|---|---|
+| New file, or per-file detail / change-history / contract / "See change: …" annotation | Matching per-area split `docs/file-index-<area>.md` (see `docs/file-index.md`). Add row in path-alphabetical order. |
+| New top-level area / new split file | New row in `docs/file-index.md` splits table. Pointer in AGENTS.md only if architectural backbone. |
+| Data flow, persistence, reconnection, protocol, config reference | `docs/architecture.md` |
+| End-user / developer setup, prerequisites, CI badges, project structure | `README.md` |
+| Cross-cutting rule EVERY agent needs on EVERY turn (rare) | AGENTS.md, ≤ 200 chars per row, no inline change history |
+
+Rules:
+
+1. **AGENTS.md "Key Files" rows MUST stay ≤ 200 characters** — one terse purpose, no change-history, no contracts, no "See change: …" parentheticals.
+
+2. **Per-file detail goes into `docs/file-index-<area>.md`.** Search the matching split for the path; if a row exists, append/update; else add in path-alphabetical order.
+
+3. **If a split grows past ~50 KB**, sub-split it (e.g. `file-index-server-routes.md`) and update `docs/file-index.md`.
+
+4. **Long-form docs** (architecture decisions, rationale, protocol details) belong in `docs/architecture.md` or `docs/<topic>.md`. Reference from AGENTS.md with a one-line pointer, never inline.
+
+5. **When you create a new split doc**, add a one-line pointer in AGENTS.md so future agents find it.
+
+6. **Every write under `docs/` MUST be delegated to a general-purpose subagent with the caveman-style rule passed verbatim in its prompt.** Main agent orchestrates, never edits `docs/` directly.
+
+   **Caveman style** (all `docs/` prose — file-index rows, architecture notes, topic docs):
+   - Short declarative fragments. Drop articles (a/an/the) and most copulas (is/are/was) when meaning survives.
+   - Subject → verb → object, present tense. No hedging, no marketing voice, no "we", no "you".
+   - One fact per line/row. No restating context the file already establishes.
+   - Prefer concrete tokens (paths, function names, env vars, ports, exit codes) over prose.
+   - Keep symbols/identifiers verbatim; only connective tissue compresses.
+   - Example — verbose: "This module is responsible for parsing the user's input and then dispatching it to the correct handler based on the command prefix." Caveman: "Parses user input. Dispatches to handler by command prefix."
+
+Why this exists: AGENTS.md ballooned to 107 KB (~27k tokens) by accreting per-change annotations on every row over months. Split was already done (file-index.md exists) but agents kept appending to AGENTS.md instead.
+
 ## Architecture
 
 See [docs/architecture.md](docs/architecture.md) for full details.
+- See [docs/electron-bootstrap-flow.md](docs/electron-bootstrap-flow.md) for the Electron app→server bootstrap state machine and end states.
 
 - **Bridge Extension** (`src/extension/`) — Runs in every pi session, forwards events via WebSocket
 - **Dashboard Server** (`src/server/`) — Aggregates events, in-memory + JSON persistence, dual WebSocket servers
@@ -65,264 +190,301 @@ make clean              # Destroy all cloned VMs
 | `qa/tests/` | Test suite (install, server, websocket, terminal, git) |
 | `qa/README.md` | Full setup and usage documentation |
 
+## Investigation Protocol — Index First
+
+**Before reading source, consult `docs/file-index.md` and the relevant `docs/file-index-<area>.md` split.** The index is the cheapest map of the codebase — every architecturally significant file has a one-line purpose plus change-history pointers. Reading source blind wastes tokens and risks hallucination.
+
+**For "how do I X" / build / run / setup questions: grep `README.md` + `docs/` first.** These already document every supported workflow (build, install, release, QA, troubleshooting). Reading source before checking docs wastes tokens and produces wrong answers (e.g. claiming a feature is missing when it ships). Check `docs/faq.md` for recurring questions.
+
+Workflow for any non-trivial "where is X" / "how does Y work" question:
+
+1. **Pick the split** from `docs/file-index.md` table (shared / extension / server / client / electron / plugins / skills-misc) by path prefix or topic.
+2. **Delegate harvesting to a subagent** (`Explore` preferred). Give it:
+   - the user's question,
+   - the split file(s) to read,
+   - explicit instruction: *"return only rows + file paths relevant to the question — no source reads, no speculation."*
+3. **Receive a short list** of candidate files (≤ ~10 rows). Only then open source for the ones that matter.
+4. If the split lacks coverage, fall back to `rg` / `Explore` over the source tree — and add the missing row per the Documentation Update Protocol.
+
+Why subagents: the splits are large (`file-index-server.md`, `file-index-client.md` each > 20 KB). Loading them into the main context on every question pollutes the budget. A subagent reads the split, returns the 5–10 relevant rows, and discards the rest.
+
+Do **not**:
+- Grep source before checking the index.
+- Read a whole split file into the main agent's context — delegate.
+- Trust the AGENTS.md "Key Files" backbone as exhaustive; it is a subset.
+
 ## Key Files
 
-> **Full file map**: see [`docs/file-index.md`](docs/file-index.md) — read it on demand when locating a file or understanding its full responsibilities (incl. change-history annotations).
+> **Full file map**: see [`docs/file-index.md`](docs/file-index.md) — a thin index of per-area split files (`docs/file-index-<area>.md`). Read the relevant split on demand when locating a file or understanding its full responsibilities (incl. change-history annotations).
 
-This section lists only the **architectural backbone** — the files agents touch most often or need to know about for any non-trivial change. For everything else (renderers, individual tool cards, narrow helpers, build/CI internals) consult `docs/file-index.md`.
+This section lists only the **architectural backbone** — the files agents touch most often or need to know about for any non-trivial change. For everything else (renderers, individual tool cards, narrow helpers, build/CI internals) consult the appropriate split via `docs/file-index.md`.
 
 ### Protocol & types
 | File | Purpose |
 |------|---------|
-| `src/shared/protocol.ts` | Extension↔Server WebSocket messages. Phase-1 Extension UI System adds `ui_modules_list` / `ui_data_list` (extension → server) and `ui_management` (server → extension); these messages MUST stay in `ExtensionToServerMessage` / `ServerToExtensionMessage` unions or esbuild strips the switch cases in production. See change: add-extension-ui-modal. |
-| `src/shared/browser-protocol.ts` | Server↔Browser WebSocket messages (all message types including PromptBus `prompt_request`/`prompt_dismiss`/`prompt_cancel` and Extension UI System Phase-1 `ui_modules_list`/`ui_data_list` (server → browser) + `ui_management` (browser → server) must be in the `ServerToBrowserMessage` / `BrowserToServerMessage` unions — `as any` switch cases are stripped by esbuild in production). **`prompt_request.metadata.toolCallId`** (change: fix-interactive-ui-reorder): optional field set by the bridge's `ctx.ui.{select, input, confirm, editor}` wrappers when the prompt is bound to a tool execution; consumed by the client reducer's `addInteractiveRequest` to pair the resulting `interactiveUi` row with its parent `toolResult`. The `metadata` field is typed `Record<string, unknown>`, so the addition is opt-in and forward/backward-compatible. **`SessionViewBrowserMessage` / `SessionUnviewBrowserMessage`** (change: session-card-unread-stripes): browser → server messages declaring the currently-displayed session id (`/session/:id`). Both must stay in the `BrowserToServerMessage` union. The browser is required to re-send `session_view` for the active session on every WebSocket reconnect (handled by `useViewDispatcher`). |
-| `src/shared/types.ts` | Data models (Session, Workspace, Event). **`DashboardSession.lastActivityAt?: number`** (epoch ms) is server-stamped on activity events via `isActivityEvent` in `event-status-extraction.ts`; cold-start seeded from `events.jsonl` mtime in `session-scanner.ts`; consumed by client `selectBadgeTimestamp` to render the session-card relative-time badge as time-since-last-activity instead of time-since-spawn. NOT persisted to `.meta.json`. See change: session-card-last-activity-badge. **`DashboardSession.unread?: boolean`** (change: session-card-unread-stripes): server-managed per-session unread bit. Set to `true` by `event-wiring.ts` when `isUnreadTrigger(...)` fires AND no browser is currently viewing the session AND the event is not part of a replay. Cleared when any browser sends `session_view`. Persisted to `.meta.json` so unread sessions stay flagged across server restarts. Bridges SHALL NOT send this field. Consumed by `SessionCard.tsx::getCardPulseClass` to render the cyan-stripes (`card-unread-pulse`, Tailwind `cyan-400`) decoration with lower priority than `card-input-pulse` (purple) and `card-working-pulse` (yellow). |
-| `src/shared/config.ts` | Shared config loader (`~/.pi/dashboard/config.json`). Exports `ReattachPlacement = "preserve" | "streaming-only" | "always"` + `parseReattachPlacement(raw)` validator (default `"always"`); the `reattachPlacement` config field controls how the server places re-registering bridges in `sessionOrder` after a dashboard restart. See change: reattach-move-to-front. Includes `openspec: OpenSpecPollConfig` block (`pollIntervalSeconds` 5–3600, `maxConcurrentSpawns` 1–16, `changeDetection` `"mtime"\|"always"`, `jitterSeconds` 0–60) with clamping via `parseOpenSpecPollConfig`. See change: optimize-openspec-poll-burst |
-| `src/shared/semaphore.ts` | Tiny FIFO semaphore (`createSemaphore(max)` → `{run, setMax, size}`). Used by `directory-service.ts` to cap concurrent `openspec` CLI spawns. Supports live resize via `setMax(n)` for runtime reconfig. |
-| `src/extension/bridge.ts` | **`hasRegisteredOnce: boolean`** local (default `false`, synced through `BridgeContext`) flips to `true` after the first `sendStateSync`; consumed by `session-sync.ts` to tag the `session_register` message with `registerReason: "spawn" | "reattach"` so the server can apply the configured `reattachPlacement` policy on dashboard-restart reattaches. See change: reattach-move-to-front. Main extension entry point (composes sync/tracker/flow modules, tracks `isAgentStreaming` in persistent BridgeState). **Invariant**: bridge code MUST NOT call `pi.newSession(...)` / `ctx.fork(...)` / `ctx.switchSession(...)` — enforced by `packages/extension/src/__tests__/no-session-replacement-calls.test.ts`. pi 0.69+ invalidates captured `pi`/`ctx` after these calls; the bridge re-captures state in `session_start` keyed on `event.reason ∈ {"new","fork","resume"}`. **PromptBus patch site**: patches `ctx.ui.select/input/confirm/editor/multiselect` in `session_start`; the TUI adapter handles `select/input/confirm/editor` only. `multiselect` is bridge-attached (pi has no native API) and routed exclusively through the bus to the `DashboardDefaultAdapter`'s browser dialog — decoded via `decodeMultiselectAnswer`. There is intentionally NO TUI adapter arm for multiselect: pi 0.70 RPC mode's `ctx.ui.custom` is a no-op, so any TUI arm awaiting it would auto-cancel the dashboard render in <1s (changes: fix-multiselect-auto-cancel-on-dashboard, fix-multiselect-tui-arm-self-cancel; regression-pinned by `no-tui-multiselect-arm-regression.test.ts`). **Per-message-fork entryId stamping** (change: fix-per-message-fork): `message_start` events now stamp a `nonce` (no entryId, since the user entry isn't persisted yet on pi 0.69+); `message_end` enrichment is deferred via `setTimeout(0)` (NOT `queueMicrotask`, which resolves inside pi's awaited extension dispatcher and misses `appendMessage`); a wrapped `ctx.sessionManager.appendMessage` emits `entry_persisted { entryId, nonce }` so the client reducer can back-fill the user-message bubble's `entryId`. |
+| `src/shared/protocol.ts` | Extension↔Server WebSocket message types |
+| `src/shared/browser-protocol.ts` | Server↔Browser WebSocket message types |
+| `src/shared/types.ts` | Data models (Session, Workspace, Event) |
+| `src/shared/config.ts` | Shared config loader (`~/.pi/dashboard/config.json`) |
+| `src/shared/semaphore.ts` | Tiny FIFO semaphore (`createSemaphore(max)`) |
+| `src/extension/bridge.ts` | Main bridge extension entry; PromptBus patch site, sync/tracker/flow composition |
 | `src/extension/bridge-context.ts` | Shared mutable state type + helpers for bridge modules |
-| `src/extension/session-sync.ts` | Session register, replay, and switch/fork handling. `sendStateSync` tags `session_register.registerReason` as `"spawn"` on first invocation per process and `"reattach"` thereafter, flipping `bc.hasRegisteredOnce`. `handleSessionChange` (new/fork/resume — fresh sessionId) ALWAYS tags `"spawn"` regardless of the flag. See change: reattach-move-to-front. |
+| `src/extension/session-sync.ts` | Session register, replay, and switch/fork handling |
 | `src/extension/model-tracker.ts` | Model/thinking-level/git/name change detection |
 | `src/extension/flow-event-wiring.ts` | Flow event listener registration (flow:* → event_forward) |
-| `src/extension/connection.ts` | WebSocket with exponential backoff. **Auto-start suppression** (change: fix-restart-bridge-auto-start-race): exposes `pauseAutoStart(ms)` (idempotent extend-only) + `shouldSuppressAutoStart()`. The bridge calls `pauseAutoStart(quiesceMs)` on receipt of `server_restarting`; `server-auto-start.ts` consults `shouldSuppressAutoStart()` and skips the spawn step while the window is active so bridges never race the `restart-helper.ts` orchestrator. Discovery + reconnection are NOT suppressed. |
+| `src/extension/connection.ts` | WebSocket with exponential backoff; auto-start suppression on `server_restarting` |
 | `src/extension/server-probe.ts` | TCP probe to detect running server |
-| `src/shared/server-identity.ts` | Identity-verified health check (`isDashboardRunning`) replacing bare TCP probes |
-| `src/shared/mdns-discovery.ts` | mDNS advertise/discover/browse for `_pi-dashboard._tcp` services. Exports `pickBestHost(service)` which returns `service.host` only when it matches the DNS-safe pattern `/^[A-Za-z0-9.-]+$/` (no leading/trailing hyphen); otherwise falls back to the first IPv4 address in `service.addresses`, then to any address, finally to the original host. Bonjour on macOS advertises the OS computer-name verbatim (e.g. `"MacBook 242"`) which contains spaces — without this fallback, saved known-server entries are unresolvable in the browser. `serviceToServer` calls `pickBestHost` so discovered servers always carry a host the browser can resolve. |
-| `src/extension/server-launcher.ts` | Auto-start server as detached process; captures **both stdout AND stderr** to `~/.pi/dashboard/server.log` (append mode) by passing `stdoutFd: logFd` alongside `logFd` — parity with `pi-dashboard start`'s `stdio: ["ignore", logFd, logFd]`. Exports pure `buildSpawnDetachedOptions` and `buildReadyTimeoutMessage`; the latter appends a `nodejs/node#58515` upgrade hint when `isKnownBadNode(process.version)` is true. |
+| `src/shared/server-identity.ts` | Identity-verified health check (`isDashboardRunning`) |
+| `src/shared/mdns-discovery.ts` | mDNS advertise/discover/browse for `_pi-dashboard._tcp` |
+| `src/extension/server-launcher.ts` | Auto-start server as detached process; logs to `~/.pi/dashboard/server.log` |
 | `src/extension/command-handler.ts` | Command routing: `!`/`!!` bash, `/compact`, slash commands |
-| `src/extension/prompt-expander.ts` | Slash command → prompt template expansion (supports colon-to-hyphen aliasing: `/opsx:cmd` → `opsx-cmd.md`) |
+| `src/extension/prompt-expander.ts` | Slash command → prompt template expansion |
 | `src/extension/dev-build.ts` | Dev build-on-reload helper (client build + server shutdown) |
-| `src/extension/server-auto-start.ts` | mDNS-first discovery → health check fallback → auto-start with concurrent launch detection |
-| `src/shared/session-meta.ts` | Session metadata sidecar (.meta.json) read/write helpers. **`SessionMeta.unread?: boolean`** (change: session-card-unread-stripes) mirrors `DashboardSession.unread`; persisted by `metaPersistence.save(...)` in `server.ts onChange` and restored by `session-scanner.ts::sessionFromMeta` so the unread bit survives server reboot. Backwards compatible — absent field reads as `undefined` (treated as `false`). |
-| `src/extension/process-metrics.ts` | Lightweight CPU/memory/event-loop metrics collector for heartbeats |
-| `src/extension/process-scanner.ts` | Child process detection via ps + PGID tracking (leaf-only, grandchild recursion) and PGID-based kill |
-| `src/client/components/ProcessList.tsx` | Session card process list with elapsed time and red ✕ kill button |
+| `src/extension/server-auto-start.ts` | mDNS-first → health check → auto-start with concurrent launch detection |
+| `src/shared/session-meta.ts` | Session metadata sidecar (.meta.json) read/write helpers |
+| `src/extension/process-metrics.ts` | Lightweight CPU/memory/event-loop metrics for heartbeats |
+| `src/extension/process-scanner.ts` | Child process detection via ps + PGID tracking and PGID-based kill |
+| `src/client/components/ProcessList.tsx` | Session card process list with elapsed time and kill button |
 | `src/extension/git-info.ts` | Git branch/remote/PR detection (polled every 30s) |
 | `src/extension/git-link-builder.ts` | Git remote URL parsing and platform-specific links |
 | `src/server/git-operations.ts` | Server-side git commands: branch listing, checkout, init, stash pop |
 | `src/client/components/BranchPicker.tsx` | Typeahead branch picker with keyboard navigation |
 | `src/client/components/BranchSwitchDialog.tsx` | Checkout orchestration: dirty-state stash, pop prompt |
 | `src/client/lib/git-api.ts` | Client-side fetch helpers for git API endpoints |
-| `src/client/hooks/useImagePaste.ts` | Reusable clipboard-image-paste hook with controlled/uncontrolled modes. Uncontrolled (`useImagePaste()` with no args): hook owns `pendingImages` in local `useState` — used by `ExploreDialog` whose lifetime IS the dialog. Controlled (`useImagePaste({ images, onImagesChange })`): caller owns the array — used by `<CommandInput>` so App can key pending images by `sessionId`. `imageError` stays local in BOTH modes (auto-clears after 3 s, no value in lifting). Supports image/png, image/jpeg, image/gif, image/webp; 10 MB base64 cap. See change: lift-pending-images-to-app |
-| `src/extension/prompt-bus.ts` | PromptBus — unified prompt routing to registered adapters (TUI, dashboard, custom). First-response-wins, cross-adapter dismissal. |
-| `src/extension/dashboard-default-adapter.ts` | Built-in PromptBus adapter that renders prompts as generic interactive dialogs in dashboard chat |
-| `src/extension/ui-modules.ts` | Extension UI System Phases 1+2: `refreshUiModules(ctx)` partitions `probe.modules` by `kind` — `management-modal` → `ui_modules_list` (Phase 1, last-write-wins on duplicate `id`); `footer-segment`/`agent-metric`/`breadcrumb`/`gate`/`toast` → one `ext_ui_decorator` per descriptor (Phase 2, last-write-wins on `(kind,namespace,id)`; `namespace` validated against `/^[a-z0-9-]+$/`; `removed: true` forwarded verbatim). `subscribeUiInvalidate(ctx)` throttles `ui:invalidate` re-probes to 20/sec (50 ms leading + trailing) and emits one warning per offending burst (`INVALIDATE_RATE_CAP_PER_SEC = 20`). `handleUiManagement(ctx, msg)` re-emits browser-originated `ui_management` on `pi.events` with `_reply` injected and forwards synchronous `data.items` as `ui_data_list`. Wired into `bridge.ts` at `session_start` and the `onReconnect` callback. See changes: add-extension-ui-modal, add-extension-ui-decorations. |
-| `src/client/components/extension-ui/GenericExtensionDialog.tsx` | Phase-1 modal renderer for `ExtensionUiModule`. Supports `view.kind ∈ {table, grid, form}`, dispatches `ui_management { action: "list", event: dataEvent }` on mount for table/grid, gates `UiAction.confirm` through `ConfirmDialog`. MDI icons resolved via `mdi-icon-lookup.ts` (unknown keys render no icon). |
-| `src/client/components/extension-ui/decorator-utils.ts` | Phase-2 helper: `decoratorsOfKind(decorators, kind)` — typed filter over `Session.uiDecorators` returning only descriptors of the requested `DecoratorKind`. Used by every Phase-2 slot component. See change: add-extension-ui-decorations. |
-| `src/client/components/extension-ui/FooterSegmentSlot.tsx` | Phase-2 slot. Renders all `kind: "footer-segment"` descriptors as inline pills mounted inside `SessionHeader.tsx` to the right of the model/thinking-level info. Supports MDI `payload.icon` (resolved via `mdi-icon-lookup`) and `payload.tooltip` (HTML title attribute). |
-| `src/client/components/extension-ui/AgentMetricSlot.tsx` | Phase-2 slot. Renders `agent-metric` descriptors whose `payload.agentId` matches the `FlowAgentCard.agent.agentName` of the parent. Mounted inside `FlowAgentCard.tsx`. Orphan descriptors (no matching agent) render nothing. |
-| `src/client/components/extension-ui/BreadcrumbSlot.tsx` | Phase-2 slot. Renders the most-recently-cached `breadcrumb` descriptor as a horizontal step indicator at the top of `FlowDashboard.tsx`. Steps with `status: "done"` show a check; `"error"` show a red alert; the active step is matched against `payload.current` (or first `status: "active"`). |
-| `src/client/components/extension-ui/GateSlot.tsx` | Phase-2 slot. Aggregates `gate` descriptors targeting the same `flowId` via the pure helper `aggregateGateState(decorators, flowId)`: most-restrictive-wins (any `available: false` blocks; reasons concatenated). Mounted inline in `FlowLaunchDialog.tsx`; the dialog also reads `aggregateGateState` directly to disable the Run button. |
-| `src/client/components/extension-ui/ToastSlot.tsx` | Phase-2 slot. Top-right fixed tray mounted in `App.tsx`. Reads toast descriptors across every session in the `sessions` Map, stacks without deduplication, auto-dismisses each toast after `payload.durationMs` (default 5000ms; `0` = sticky), caps simultaneous-display at 5 (FIFO eviction — cache is unaffected). Manual dismiss via the close button latches the descriptor key into a local `dismissed` set so cache replay does not resurrect dismissed toasts. |
-| `src/client/lib/mdi-icon-lookup.ts` | `resolveMdiIcon(key) → string \| null` — looks up an MDI key string against `@mdi/js` exports; allowlists by `mdi`-prefix, returns `null` for unknown keys (no error). XSS-safe icon vocabulary for extension descriptors. |
-| `src/client/lib/prompt-component-registry.ts` | Client-side component registry mapping prompt type strings to render metadata (placement, component) |
-| `src/extension/ask-user-tool.ts` | `ask_user` tool registration (bundled in bridge, registered at session_start to avoid static tool-name conflicts with other extensions). `multiselect` dispatches through `polyfillMultiselect` (since pi-coding-agent's `ExtensionUIContext` has no native `multiselect` method). Tool description instructs agents: *"UI provides a Select all toggle; do not add one."* **Schema shape**: `parameters` is a single flat `Type.Object` (root `type: "object"`) — NOT a root `Type.Union` — because OpenAI's function-calling validator rejects root-level `anyOf` with *"schema must be a JSON Schema of 'type: \"object\"'"*. To restore Anthropic-friendly per-method strictness after commit a53933f, the root object now carries a body-level `oneOf` discriminator over `method` (confirm/select/multiselect/input/batch) with per-arm `required` + `minItems` constraints; sub-questions use the same flat-object + `oneOf` pattern with no `batch` arm (no nesting). `prepareArguments` still provides runtime rescue/normalization (`params` unwrap, `question`→`title`, stringified `options`/`questions`, batch synthesis/title backfill, `{label,value}` → labels), and `execute` retains empty-options guardrails. See changes: ask-user-multiselect-polyfill, refactor(schema)-restructure-ask-user-tool-schemas, fix-multiselect-auto-cancel-on-dashboard. |
-| `src/extension/multiselect-polyfill.ts` | `polyfillMultiselect(ctx, title, options, opts)` — primary path delegates to bridge-patched `ctx.ui.multiselect` (PromptBus → `DashboardDefaultAdapter` → client `MultiselectRenderer`). Legacy fallback uses `ctx.ui.custom<T>()` + `MultiSelectList` for older / non-bridge contexts; this fallback is **a no-op in pi 0.70 RPC mode** (dashboard headless sessions) — pi-coding-agent defines `custom` as `async () => undefined` there — and is only effective in pure-TUI sessions if a future pi version restores `ctx.ui.custom` in RPC mode. Resolves to `string[]` (confirmed, including empty `[]`) or `undefined` (cancelled). Used for both single-question and batch sub-question `multiselect` paths in `ask-user-tool.ts`. See changes: fix-multiselect-auto-cancel-on-dashboard, fix-multiselect-tui-arm-self-cancel. |
-| `src/extension/multiselect-list.ts` | `MultiSelectList` component implementing pi-tui's `Component` interface. Keyboard contract: `↑↓`/`k`/`j` navigate, `Space` toggles current, `Enter` confirms (selected values in original option order), `Escape` cancels. **No "select all" binding in TUI** — the dashboard adapter provides that affordance. |
-| `src/shared/openspec-activity-detector.ts` | Detects OpenSpec activity from tool events; auto-attach requires only changeName (phase optional). Bash arm rejects flag-shaped capture tokens (`name.startsWith("-")` → `null`) so `openspec archive --help` and similar discovery commands no longer rename unnamed sessions to `--help`. See change: fix-openspec-flag-rename-bug. |
-| `src/shared/openspec-poller.ts` | OpenSpec CLI polling (shared, used by server DirectoryService). `buildOpenSpecData(listResult, statusResults, designProbeFactory?, specsProbeFactory?)` accepts two optional probe factories: a `DesignProbeFactory` that promotes the `design` artifact's status from `"ready"` to `"done"` when local file evidence (R1/R2/R3) satisfies design (see change: fix-openspec-design-detection), and a `SpecsProbeFactory` that promotes the `specs` artifact from `"ready"` to `"done"` when at least one `specs/**/*.md` file exists locally (see change: fix-openspec-specs-mtime-gate-blind-spot). Both overrides are promote-only, single-artifact-only, never demote; the post-override loop re-derives change-level `isComplete`. `pollOpenSpec` (sync) and `pollOpenSpecAsync` (async) wire real-fs probes via `createFsProbeFactory(cwd)` and `createFsSpecsProbeFactory(cwd)`. `directory-service.ts` does the same on the mtime-gated path. |
-| `src/shared/openspec-design-evidence.ts` | Pure rule evaluator + real-fs probe factory for the OpenSpec design-artifact override. `evaluateLocalDesignSatisfaction(changeDir, probe)` short-circuits R1 (`^design.*\.md$` file present) → R2 (`design/` folder with `*.md`) → R3 (`tasks.md` contains a `^\s*-\s+\[[ xX]\]\s` checkbox). `createFsDesignEvidenceProbe()` returns a defensive sync probe (try/catch on every fs call). Probe-injection keeps `buildOpenSpecData` pure and unit-testable without filesystem mocks. See change: fix-openspec-design-detection. |
-| `src/shared/openspec-specs-evidence.ts` | Pure rule evaluator + real-fs probe factory for the OpenSpec specs-artifact override. `evaluateLocalSpecsSatisfaction(changeDir, probe)` returns true iff at least one `*.md` file exists under `<changeDir>/specs/` (iterative DFS, short-circuits on first match). `createFsSpecsEvidenceProbe()` returns a defensive sync probe — every `readdirSync` is wrapped in try/catch so missing dirs / permission errors / symlink loops yield `false` rather than throwing. Mirror-shape of `openspec-design-evidence.ts`; consumed by `buildOpenSpecData` as a defense-in-depth layer over the `directory-service.ts` mtime gate (which now also watches `specs/**`). See change: fix-openspec-specs-mtime-gate-blind-spot. |
-| `.pi/skills/openspec-shared/scripts/effective-status.sh` | Bash wrapper around `openspec status --change <name> --json` that applies the same R1/R2/R3 promotion as the dashboard so OpenSpec workflow skills (`openspec-{continue,ff,apply,verify}-change`) and dashboard session-card buttons cannot disagree about a change's next-ready artifact. Inlines the rule logic via `find` + `grep -E` and uses `jq` for JSON mutation; falls back to raw CLI output if `jq` is absent. **Repo-lint** `packages/shared/src/__tests__/no-raw-openspec-status-in-skills.test.ts` blocks raw `openspec status ... --json` calls in any of the four governed skills (opt-out: `ban:openspec-status-ok`). Parity test: `packages/shared/src/__tests__/openspec-effective-status-script.test.ts`. See change: fix-openspec-design-detection. |
+| `src/client/hooks/useImagePaste.ts` | Reusable clipboard-image-paste hook (controlled/uncontrolled modes) |
+| `src/extension/prompt-bus.ts` | PromptBus — unified prompt routing to registered adapters |
+| `src/extension/dashboard-default-adapter.ts` | Built-in PromptBus adapter rendering prompts as dashboard chat dialogs |
+| `src/extension/ui-modules.ts` | Extension UI System Phase 1+2: refresh, throttle, manage |
+| `src/client/components/extension-ui/GenericExtensionDialog.tsx` | Phase-1 modal renderer for `ExtensionUiModule` (table/grid/form) |
+| `src/client/components/extension-ui/decorator-utils.ts` | Phase-2 helper `decoratorsOfKind` filter over `Session.uiDecorators` |
+| `src/client/components/extension-ui/FooterSegmentSlot.tsx` | Phase-2 slot rendering footer-segment descriptors as inline pills |
+| `src/client/components/extension-ui/AgentMetricSlot.tsx` | Phase-2 slot rendering agent-metric descriptors inside FlowAgentCard |
+| `src/client/components/extension-ui/BreadcrumbSlot.tsx` | Phase-2 slot rendering breadcrumb as step indicator at FlowDashboard top |
+| `src/client/components/extension-ui/GateSlot.tsx` | Phase-2 slot aggregating gate descriptors per flowId (most-restrictive-wins) |
+| `src/client/components/extension-ui/ToastSlot.tsx` | Phase-2 slot rendering toast descriptors top-right with auto-dismiss + cap-of-5 |
+| `src/client/lib/mdi-icon-lookup.ts` | `resolveMdiIcon(key)` against `@mdi/js` exports; null on unknown key |
+| `src/client/lib/prompt-component-registry.ts` | Client component registry for prompt types (placement, component) |
+| `src/extension/ask-user-tool.ts` | `ask_user` tool registration (confirm/select/multiselect/input/batch via flat oneOf schema) |
+| `src/extension/multiselect-polyfill.ts` | `polyfillMultiselect` — bridge-patched multiselect with TUI fallback |
+| `src/extension/multiselect-list.ts` | `MultiSelectList` pi-tui Component (↑↓/Space/Enter/Esc keyboard contract) |
+| `src/shared/openspec-activity-detector.ts` | Detects OpenSpec activity from tool events; rejects flag-shaped tokens |
+| `src/shared/openspec-poller.ts` | OpenSpec CLI polling: `buildOpenSpecData` with optional design + specs probe factories |
+| `src/shared/openspec-design-evidence.ts` | Pure rule evaluator + fs probe for OpenSpec design-artifact override (R1/R2/R3) |
+| `src/shared/openspec-specs-evidence.ts` | Pure rule evaluator + fs probe for OpenSpec specs-artifact override |
+| `.pi/skills/openspec-shared/scripts/effective-status.sh` | Bash wrapper around `openspec status` applying R1/R2/R3 promotion |
 | `src/shared/state-replay.ts` | Synthesizes events from pi entries (shared, used by server + bridge) |
-| `src/shared/dashboard-plugin/slot-types.ts` | Frozen slot taxonomy: `SlotId` union, `Multiplicity`, `PayloadTier` enums, `SLOT_DEFINITIONS` record. Adding a slot = minor; removing = major. |
-| `src/shared/dashboard-plugin/manifest-types.ts` | `PluginManifest` and `PluginClaim` interfaces; includes `tab` field for `settings-section` claims and `fixture` flag for test-only plugins. |
-| `src/shared/dashboard-plugin/slot-props.ts` | `SlotPropsMap` and `SlotProps<SlotId>` — typed prop contracts per slot id. Type-level test asserts all slot ids are covered. |
-| `src/shared/dashboard-plugin/plugin-status.ts` | `PluginStatus` (for `/api/health`) and `PluginConfigUpdate` (WebSocket broadcast payload). |
-| `src/shared/plugin-bridge-register.ts` | Plugin bridge entry management: `registerPluginBridge`, `deregisterPluginBridge`, `registerAllPluginBridges`. Manages `dashboard-<plugin-id>` keys in `settings.json#dashboardPluginBridges`; never touches user-owned `packages[]` entries. Atomic write (tmp+rename). |
-| `packages/dashboard-plugin-runtime/src/slot-registry.ts` | `createSlotRegistry()` — typed `Map<SlotId, ClaimEntry[]>` pre-sorted by `(priority, pluginId)`. Filter helpers: `forSession`, `forFolder`, `forCommand`, `forTab`, `forToolName`. |
-| `packages/dashboard-plugin-runtime/src/manifest-validator.ts` | Hand-rolled manifest validator. Throws `ManifestValidationError` with `pluginId` and `reason`. No Zod dependency. |
-| `packages/dashboard-plugin-runtime/src/plugin-context.tsx` | `PluginContextProvider`, `CurrentPluginLayer`, `usePluginConfig<T>()`, `useAllSessions`, `useSessionState`, `usePluginLogger`, `usePluginSend`, `usePluginRouter`, `useSlotRegistry`, `applyPluginConfigUpdate`. Per-plugin context layer scopes hooks to the contributing plugin's id. |
-| `packages/dashboard-plugin-runtime/src/slot-consumers.tsx` | One component per slot id: `SidebarFolderSectionSlot`, `SessionCardBadgeSlot`, `SessionCardActionBarSlot`, `ContentViewSlot`, `ContentHeaderStickySlot`, `ContentInlineFooterSlot`, `AnchoredPopoverSlot`, `CommandRouteSlot`, `SettingsSectionSlot`, `ToolRendererSlot`. Each wraps contributions in `SlotErrorBoundary`. |
-| `packages/dashboard-plugin-runtime/src/slot-error-boundary.tsx` | Per-claim React error boundary. Logs `[slot-error-boundary] Plugin "<id>" slot "<slot>" threw:` and renders nothing for the failing claim without suppressing siblings. |
-| `packages/dashboard-plugin-runtime/src/vite-plugin/index.ts` | `viteDashboardPluginsPlugin(repoRoot?)` — generates `packages/client/src/generated/plugin-registry.tsx` with named imports (for tree-shaking). Watches manifests during dev; regenerates + triggers HMR on changes. Filters `fixture:true` plugins in production. |
-| `packages/dashboard-plugin-runtime/src/server/loader.ts` | `discoverPlugins(repoRoot?)` (single-process-cache glob), `loadServerEntries(deps)` (per-plugin dynamic-import + `registerPlugin` invocation, failure-isolated), `getPluginStatusStore()`. |
-| `packages/dashboard-plugin-runtime/src/server/server-context.ts` | `createServerPluginContext(deps, pluginId)` factory — creates a `ServerPluginContext` scoped to a plugin with namespaced logger and typed config accessors. |
-| `packages/dashboard-plugin-runtime/src/server/config-validator.ts` | `validatePluginConfig`, `applySchemaDefaults` — Ajv JSON-Schema 7 validation for plugin config writes. |
-| `packages/dashboard-plugin-runtime/src/server/plugin-status-store.ts` | In-memory `PluginStatusStore` — consumed by `/api/health.plugins[]`. |
-| `src/server/routes/plugin-config-routes.ts` | `POST /api/config/plugins/:id` — validates `:id`, validates body against `configSchema`, merges into `plugins.<id>.*`, atomic-writes, broadcasts `plugin_config_update`. Auth-gated. |
-| `packages/demo-plugin/` | Private workspace (`"private": true`, `"fixture": true`). Exercises `settings-section` (DemoSettings form) and `tool-renderer` (DemoToolRenderer green box for `toolName: "DashboardDemo"`). Excluded from production bundles. |
+| `src/shared/dashboard-plugin/slot-types.ts` | Frozen slot taxonomy: `SlotId`, `Multiplicity`, `PayloadTier`, `SLOT_DEFINITIONS` |
+| `src/shared/dashboard-plugin/manifest-types.ts` | `PluginManifest` and `PluginClaim` interfaces |
+| `src/shared/dashboard-plugin/slot-props.ts` | `SlotPropsMap` and `SlotProps<SlotId>` typed prop contracts per slot id |
+| `src/shared/dashboard-plugin/plugin-status.ts` | `PluginStatus` (for `/api/health`) and `PluginConfigUpdate` (WS payload) |
+| `src/shared/plugin-bridge-register.ts` | Plugin bridge entry registration in pi `settings.json#dashboardPluginBridges` |
+| `packages/dashboard-plugin-runtime/src/slot-registry.ts` | `createSlotRegistry()` typed `Map<SlotId, ClaimEntry[]>` with filter helpers |
+| `packages/dashboard-plugin-runtime/src/manifest-validator.ts` | Hand-rolled manifest validator throwing `ManifestValidationError` |
+| `packages/dashboard-plugin-runtime/src/plugin-context.tsx` | PluginContextProvider + per-plugin hook layer (config/log/send/router/registry) |
+| `packages/dashboard-plugin-runtime/src/slot-consumers.tsx` | One component per slot id, wrapping contributions in `SlotErrorBoundary` |
+| `packages/dashboard-plugin-runtime/src/slot-error-boundary.tsx` | Per-claim React error boundary; isolates failing claim from siblings |
+| `packages/dashboard-plugin-runtime/src/vite-plugin/index.ts` | `viteDashboardPluginsPlugin` — generates plugin-registry.tsx, watches manifests |
+| `packages/dashboard-plugin-runtime/src/server/loader.ts` | `discoverPlugins` + `loadServerEntries` (failure-isolated) + `getPluginStatusStore` |
+| `packages/dashboard-plugin-runtime/src/server/server-context.ts` | `createServerPluginContext` — per-plugin scoped logger + config |
+| `packages/dashboard-plugin-runtime/src/server/config-validator.ts` | Ajv JSON-Schema 7 validation for plugin config writes |
+| `packages/dashboard-plugin-runtime/src/server/plugin-status-store.ts` | In-memory `PluginStatusStore` for `/api/health.plugins[]` |
+| `src/server/routes/plugin-config-routes.ts` | `POST /api/config/plugins/:id` — validates and merges plugin config (auth-gated) |
+| `packages/demo-plugin/` | Private fixture plugin exercising settings-section + tool-renderer slots |
+| `packages/dashboard-plugin-skill/` | Pi skill `dashboard-plugin-scaffold`. Modes: `new` (scaffold packages/<id>-plugin/), `augment` (inject manifest + src/dashboard/ into pi-extension at cwd). |
 | `src/shared/stats-extractor.ts` | Extracts token/cost stats from turn_end events |
-| `src/server/session-stats-reader.ts` | Reads cumulative stats + context usage from session JSONL files at startup |
-| `src/server/server.ts` | HTTP + WebSocket server (composes route modules + wiring). Exports two pure helpers consumed by the bootstrap-state subscribe callback: `makeBootstrapTransitionHandler({ flushQueue, onTransitionToReady })` (stateful gate — fires both callbacks once per `installing → ready` transition, ignores the initial `ready` snapshot) and `runPostInstallRepair({ registry, directoryService, browserGateway })` (full `registry.rescan()` + per-cwd `refreshOpenSpec` with selective `openspec_update` broadcast on prior-empty / data-differs + per-cwd `refreshPiResources`; per-cwd failures isolated). The centralized hook covers all three install entry points (`runDegradedModeBootstrap`, REST `triggerUpgradePi`, REST `triggerRetry`). DEBUG-gated single-line diagnostic on completion. See change: fix-openspec-buttons-after-bootstrap-install. |
+| `src/server/session-stats-reader.ts` | Reads cumulative stats + context usage from session JSONL files |
+| `src/server/server.ts` | HTTP + WebSocket server (composes route modules + wiring) |
 | `src/server/routes/session-routes.ts` | REST routes: sessions, events, session-diff |
 | `src/server/routes/git-routes.ts` | REST routes: git branches, checkout, init, stash-pop |
-| `src/server/routes/file-routes.ts` | REST routes: file read, browse (with `detect=0\|1` opt-in classifier), browse-flags (bulk classifier), browse-mkdir, readme, pinned-dirs. See change: split-browse-flags |
+| `src/server/routes/file-routes.ts` | REST routes: file read, browse, browse-flags, browse-mkdir, readme, pinned-dirs |
 | `src/server/routes/openspec-routes.ts` | REST routes: openspec-archive, pi-resources, pi-resource-file |
 | `src/server/routes/system-routes.ts` | REST routes: config, health, shutdown, tunnel, editors |
-| `src/server/event-wiring.ts` | Pi gateway → browser gateway event forwarding (replay suppression with `skipReplayInsert` dedup, flows refresh dedup, context usage extraction). Phase-1 Extension UI System: caches `ui_modules_list` on `Session.uiModules` and broadcasts; caches `ui_data_list` on `Session.uiDataMap[event]` with a per-event item cap (default 1000, last-write-wins on overflow) and broadcasts. Phase-2: `ext_ui_decorator` switch arm caches descriptors under `Session.uiDecorators[`${kind}:${namespace}:${id}`]` (upsert, or delete when `removed: true`) and broadcasts the message verbatim to subscribers; deleting an absent key is a no-op but still broadcasts. **Last-activity stamping** (change: session-card-last-activity-badge): every live (non-replay) `event_forward` whose `eventType` passes `isActivityEvent(...)` (`event-status-extraction.ts` allowlist — `prompt_send`, `message_*`, `turn_end`, `tool_execution_*`, `agent_*`, `bash_output`, `flow_*`, `architect_*`) updates `session.lastActivityAt = Date.now()` in memory and broadcasts at most once per 30 s per session via `lastActivityBroadcastAt: Map<sessionId, ms>`; the map entry is dropped on `session_unregister` so a subsequent re-register does not silently suppress its first broadcast. See changes: add-extension-ui-modal, add-extension-ui-decorations, session-card-last-activity-badge. **Unread-trigger evaluation** (change: session-card-unread-stripes): right after the `extractSessionUpdates` block, snapshots `{status, currentTool}` before/after and calls `isUnreadTrigger(eventType, before, after, payload)`; if true AND `viewedSessionTracker.isViewedByAnyone(sessionId) === false` AND `!replayingSessions.has(sessionId)`, stamps `session.unread = true` and broadcasts `session_updated`. The `viewedSessionTracker` dep is optional on `EventWiringDeps` for backward compatibility — wiring is opt-in. |
+| `src/server/event-wiring.ts` | Pi gateway → browser gateway event forwarding; UI cache + activity stamping + unread trigger |
 | `src/server/idle-timer.ts` | Auto-shutdown idle timer with sleep-wake resilience |
 | `src/server/session-bootstrap.ts` | Startup session discovery and OpenSpec polling init |
 | `src/server/pi-gateway.ts` | Extension WebSocket gateway (port 9999) |
 | `src/server/browser-gateway.ts` | Browser WebSocket gateway (dispatches to handler modules) |
 | `src/server/browser-handlers/handler-context.ts` | Shared context type for browser message handlers |
-| `src/server/browser-handlers/subscription-handler.ts` | Subscribe/unsubscribe with async batched replay, backpressure, lazy loading. Exports `replayUiState(ws, sessionId, ctx)` for the Extension UI System; called immediately after every `replayPendingUiRequests` site (4 sites). Replay sends the cached `ui_modules_list` (Phase 1) → one `ui_data_list` per `(event, items)` entry (Phase 1) → one `ext_ui_decorator` per `Session.uiDecorators` cache entry (Phase 2; never with `removed: true` since deleted entries are absent). Replay ordering: events → pending UI requests → ui_modules_list → ui_data_list → ext_ui_decorator. See changes: add-extension-ui-modal, add-extension-ui-decorations. |
-| `src/server/browser-handlers/session-action-handler.ts` | Send prompt, abort, resume, spawn, shutdown, force kill, flow control. `handleSpawnSession` accepts an optional `SpawnSessionBrowserMessage.attachProposal` and enqueues it into `pendingAttachRegistry` BEFORE awaiting `spawnPiSession(...)` so a fast `session_register` cannot lose the intent (see change: add-folder-task-checker-and-spawn-attach). `handleForceKill` delegates the SIGTERM→wait→SIGKILL escalation to `killProcess` from `platform/process.ts` so Windows gets `taskkill /F /T /PID` (genuine tree kill). No direct `process.kill()` anywhere (enforced by `no-direct-process-kill.test.ts`). `handleSendPrompt` also intercepts `/reload` on headless sessions (gated by `headlessPidRegistry.getPid`) and delegates to `handleHeadlessReload`, which SIGTERMs the pi process and respawns with `--session <file> --mode continue` — pi 0.68.0 has no extension-accessible reload path in RPC mode, so kill-and-respawn is the only way to reload settings/extensions/skills for headless sessions. See changes: route-kill-paths-through-platform, headless-reload-via-respawn. |
-| `src/server/browser-handlers/session-action-helpers.ts` | Pure helpers for session-action-handler. `shouldInterceptReload(msg, headlessPidRegistry)` gates the headless-reload interception: exact `/reload` text, no images, PID tracked in registry. Extracted for testability. |
-| `src/client/components/ImageLightbox.tsx` | Full-size image lightbox with zoom/pan (useZoomPan), Esc/backdrop close |
+| `src/server/browser-handlers/subscription-handler.ts` | Subscribe/unsubscribe with batched replay; replays UI state |
+| `src/server/browser-handlers/session-action-handler.ts` | Send prompt, abort, resume, spawn, shutdown, force kill, flow control |
+| `src/server/browser-handlers/session-action-helpers.ts` | Pure helpers for session-action-handler (`shouldInterceptReload`) |
+| `src/client/components/ImageLightbox.tsx` | Full-size image lightbox with zoom/pan, Esc/backdrop close |
 | `src/client/components/CollapsedToolGroup.tsx` | Collapsed group of repeated tool calls with expand toggle |
 | `src/client/lib/group-tool-calls.ts` | Groups consecutive identical tool calls for chat display |
-| `src/client/lib/collapse-retried-errors.ts` | Two pure helpers used by `ChatView` to remove duplicate tool cards: `findRetriedErrorIds(messages)` returns ids of error `toolResult`s immediately superseded by a successful retry of the same tool (skipping `assistant`/`thinking`/`turnSeparator`/`rawEvent`/`commandFeedback`); `findActiveInteractiveToolResultIds(messages)` returns ids of `running` `toolResult`s paired with a *pending* `interactiveUi` message that follows them, so the running tool card can be hidden while the `InteractiveUiCard` is the sole interactive surface. See change: collapse-duplicate-tool-cards |
-| `src/client/components/RetriedErrorBadge.tsx` | One-line `⚠ <toolName> failed — retried ›` pill rendered by `ChatView` in place of full `ToolCallStep` for ids returned by `findRetriedErrorIds`. Click toggles an expanded view that re-uses `<ToolCallStep status="error">` with a "Hide failed attempt" toggle so the original validation message + `Received arguments:` JSON is still recoverable. See change: collapse-duplicate-tool-cards |
-| `src/server/browser-handlers/session-meta-handler.ts` | Rename, hide, unhide, attach/detach proposal, fetch, list. Attach/detach apply an **idempotent auto-rename rule** via the pure helpers in `packages/server/src/proposal-attach-naming.ts`: attach renames when name is empty OR equals the current `attachedProposal` (auto-set witness); detach reverts the name only when that equality holds. The same helpers are reused by the REST endpoints in `session-api.ts` to keep WS and REST in lockstep. See change: fix-mobile-attach-proposal-display. |
-| `src/server/proposal-attach-naming.ts` | Pure decision-matrix helpers `attachRenameTarget(session, changeName)` and `detachShouldClearName(session)` used by both the WS handler and the REST endpoint to compute the idempotent auto-rename / auto-revert. Equality witness: `name === attachedProposal`. See change: fix-mobile-attach-proposal-display. |
+| `src/client/lib/collapse-retried-errors.ts` | Pure helpers `findRetriedErrorIds` + `findActiveInteractiveToolResultIds` for chat dedup |
+| `src/client/components/RetriedErrorBadge.tsx` | One-line "tool failed — retried" pill replacing collapsed errored ToolCallStep |
+| `src/server/browser-handlers/session-meta-handler.ts` | Rename, hide, unhide, attach/detach proposal, fetch, list |
+| `src/server/proposal-attach-naming.ts` | Pure helpers `attachRenameTarget` + `detachShouldClearName` (idempotent auto-rename) |
 | `src/server/browser-handlers/terminal-handler.ts` | Create, kill, rename terminals |
 | `src/server/browser-handlers/directory-handler.ts` | Pin/unpin dirs, reorder, openspec refresh, pi-gateway forwards |
 | `src/server/memory-event-store.ts` | In-memory event buffer with LRU eviction, per-session cap, payload truncation |
 | `src/server/memory-session-manager.ts` | Pure in-memory session registry |
-| `src/client/components/FolderOpenSpecSection.tsx` | Folder-level OpenSpec UI: collapsible change list, refresh, bulk archive, archive button. Each change row's `N/M tasks` indicator is a button that opens the existing `TasksPopover` (one popover at a time; opening another row swaps the popover); a `mdiPlay` icon button rendered after the artifact letters invokes `onSpawnAttached(cwd, changeName)` to spawn a pi session with the change pre-attached. Both buttons stop propagation so the surrounding folder collapse is unaffected. See change: add-folder-task-checker-and-spawn-attach. |
-| `src/server/pending-attach-registry.ts` | In-memory FIFO queue of pending `attachProposal` intents per cwd. `enqueue(cwd, changeName)` is called from `handleSpawnSession` when the browser sets `SpawnSessionBrowserMessage.attachProposal`; `consume(cwd)` is called from `event-wiring.ts`'s `pi-gateway.onSessionRegistered` hook on every `session_register`, and the resolved name is applied via the shared `applyAttachProposal(sessionId, changeName, ctx)` helper in `session-meta-handler.ts` (same code as `handleAttachProposal`). Per-cwd cap = 8 (silent drop + warn), 60 s TTL on every read/write to avoid stranded intents from failed spawns. Cwd is normalized via `safeRealpathSync` + trailing-sep strip so `/p`, `/p/`, and symlink variants share a queue. In-memory only — not persisted. See change: add-folder-task-checker-and-spawn-attach. |
-| `src/client/components/ArchiveBrowserView.tsx` | Searchable archive browser: date-grouped list, two-level nav to artifact reader |
-| `src/client/hooks/useArchiveListing.ts` | Fetch hook + pure helpers (groupByDate, filterEntries) for archive endpoint |
-| `src/server/openspec-archive.ts` | Scans `openspec/changes/archive/` and returns structured ArchiveEntry list |
+| `src/client/components/FolderOpenSpecSection.tsx` | Folder-level OpenSpec UI: change list, refresh, bulk archive, attach-spawn |
+| `src/server/pending-attach-registry.ts` | In-memory FIFO queue of pending `attachProposal` intents per cwd (60s TTL) |
+| `src/client/components/ArchiveBrowserView.tsx` | Searchable archive browser: date-grouped list, two-level nav |
+| `src/client/hooks/useArchiveListing.ts` | Fetch hook + pure helpers for archive endpoint |
+| `src/server/openspec-archive.ts` | Scans `openspec/changes/archive/` and returns ArchiveEntry list |
 | `src/client/components/SessionOpenSpecActions.tsx` | Session-level OpenSpec: searchable attach dialog, action buttons, detach |
 | `src/client/components/DialogPortal.tsx` | Portal wrapper rendering dialogs at document.body with scroll lock |
 | `src/client/components/PinDirectoryDialog.tsx` | Dialog to pin a directory (wraps PathPicker) |
 | `src/client/components/PathPicker.tsx` | Reusable keyboard-first path picker with typeahead directory list |
 | `src/client/lib/browse-api.ts` | Client-side browse API helper for PathPicker |
-| `src/server/browse.ts` | Directory listing + classification for the browse API. Two responsibilities kept deliberately separate: `listDirectories(dir, q, { detect })` does enumeration (cheap, single `readdir`; per-entry `.git`/`.pi` probes only when `detect: true`), and `classifyPaths(paths)` does bulk classification (≤ `MAX_FLAG_PATHS = 100`, `fs.access` fan-out bounded by `createSemaphore(32)`, any error → `{ isGit: false, isPi: false }`). `parseFlagsQuery(rawPaths)` validates the `paths=<json-array>` query for `GET /api/browse/flags`. Worktree-safe: detection uses `fs.access` (never `readdir`) so `.git` regular-files in worktrees still classify correctly. See change: split-browse-flags |
-| `src/server/pi-resource-scanner.ts` | Discovers pi extensions, skills, prompts from local, global, and package sources |
-| `src/server/package-manager-wrapper.ts` | Thin adapter around pi's `DefaultPackageManager` with operation serialization, progress forwarding, and session reload; delegates module resolution to `ToolRegistry.resolveModule("pi-coding-agent")`. Includes `move(req)` for scope-to-scope package moves: hybrid execution — npm/git/https sources reinstall at dest then remove from origin (single `busy` lock, coalesced reload), filesystem-path sources settings-edit only (uses `settingsManager.getGlobalSettings/getProjectSettings/setPackages/setProjectPackages` to preserve filter objects). Identity preflight via `computeIdentity` before any side-effect; partial-success (install OK, remove failed) is delivered through the `package_operation_complete` WS event's `partialSuccess` field. See change: unify-package-management-ui. |
-| `src/server/package-source-helpers.ts` | Pure helpers `parseSourceKind(source)` (npm/git/https/abs-path/rel-path) and `computeIdentity(source, settingsDir?)` (npm = bare name, git/https = url-no-ref, path = resolved absolute) mirroring pi's source-kind and dedup rules from `docs/packages.md`. Used by `package-manager-wrapper`'s `move()` arm-selection and identity preflight; safe for cross-platform tests (no `process.platform` branching). See change: unify-package-management-ui. |
-| `src/shared/tool-registry/registry.ts` | `ToolRegistry` service — single-source resolver for every external binary/module (pi, pi-coding-agent, openspec, npm, node, tsx, git, zrok, pi-dashboard). Ordered strategy chain per tool, per-resolution diagnostic trail, in-memory cache, override-aware |
-| `src/shared/tool-registry/definitions.ts` | Registers the standard tool set. Each definition declares an ordered strategy chain (override → bare-import → managed → npm-global → where) and a classifier (strategy → source). Includes build-time tools `electron` and `node-pty` (registered as `kind: "module"` returning the package directory; resolved hoist-aware via `bareImportPackageDirStrategy` with optional `searchPaths`). See change: register-build-time-tools |
-| `packages/shared/bin/pi-dashboard-resolve-tool.cjs` | Shell-callable resolver wrapper for the tool registry. CommonJS, dependency-free, invokable as `node packages/shared/bin/pi-dashboard-resolve-tool.cjs <tool-name> [--json]`. Mirrors the `override` + `bare-import` strategy semantics for build-time tools (electron, node-pty) so CI workflows / Dockerfiles / postinstall scripts can resolve hoisted-vs-nested layouts without depending on the shared package's TS build. **Strategy chain MUST stay in sync with `tool-registry/definitions.ts`** — enforced socially via cross-reference comments and via `no-hardcoded-node-modules-paths.test.ts`. See change: register-build-time-tools |
-| `src/shared/__tests__/no-hardcoded-node-modules-paths.test.ts` | Repo-level lint: scans `.github/workflows/publish.yml`, `.github/workflows/ci.yml`, `packages/electron/scripts/Dockerfile.build`, and the two `fix-pty-permissions.cjs` postinstalls for hardcoded `node_modules/electron` / `node_modules/node-pty` substrings outside the explicit allowlist. Fails with `file:line:col` citation. Replaces hand-rolled inline `require.resolve(...)` patterns with the registered tool registry. Mirrors `no-direct-process-kill.test.ts` and `no-raw-node-import.test.ts`. See change: register-build-time-tools |
-| `src/shared/tool-registry/strategies.ts` | Reusable resolution strategies: `overrideStrategy`, `managedBinStrategy`, `managedModuleStrategy`, `npmGlobalStrategy`, `whereStrategy`, `bareImportStrategy` (uses `createRequire` for sync probe). All take injectable `StrategyDeps` for tests |
-| `src/shared/tool-registry/overrides.ts` | Read/write `~/.pi/dashboard/tool-overrides.json` (machine-local, separate from `config.json`). Lazy-loaded, atomic write via tmp+rename, malformed-file tolerant |
-| `src/shared/tool-registry/types.ts` | `ToolDefinition`, `Strategy`, `StrategyResult`, `Resolution`, `Source`, `UnknownToolError`, `ModuleResolutionError` |
+| `src/server/browse.ts` | Directory listing + classification for the browse API |
+| `src/server/pi-resource-scanner.ts` | Discovers pi extensions, skills, prompts from local/global/package sources |
+| `src/server/package-manager-wrapper.ts` | Wraps pi's DefaultPackageManager; adds `move()` for scope-to-scope moves |
+| `src/server/package-source-helpers.ts` | Pure `parseSourceKind` + `computeIdentity` (npm/git/https/path identity rules) |
+| `src/shared/tool-registry/registry.ts` | `ToolRegistry` — single-source resolver for every external binary/module |
+| `src/shared/tool-registry/definitions.ts` | Registers standard tool set with ordered strategy chains |
+| `packages/shared/bin/pi-dashboard-resolve-tool.cjs` | Shell-callable resolver wrapper (CommonJS, no TS deps) for build-time tools |
+| `src/shared/__tests__/no-hardcoded-node-modules-paths.test.ts` | Repo-lint: forbid hardcoded `node_modules/electron` / `node_modules/node-pty` |
+| `src/shared/tool-registry/strategies.ts` | Reusable resolution strategies (override / managed / npm-global / where / bare-import) |
+| `src/shared/tool-registry/overrides.ts` | Read/write `~/.pi/dashboard/tool-overrides.json` with atomic write |
+| `src/shared/tool-registry/types.ts` | `ToolDefinition`, `Strategy`, `Resolution`, error classes |
 | `src/shared/tool-registry/index.ts` | Barrel export + `getDefaultRegistry()` singleton accessor |
-| `src/server/routes/tool-routes.ts` | REST routes: `GET /api/tools`, `GET /api/tools/:name`, `POST /api/tools/rescan`, `PUT/DELETE /api/tools/:name`, `POST /api/tools/diagnostics` (text/plain export) |
-| `packages/shared/src/bootstrap-install.ts` | Shared bootstrap installer (`bootstrapInstall({ packages, managedDir?, progress?, npmArgv?, env?, registry? })`, `bootstrapInstallDefaults`, `ensureManagedDir`, `resolveNpmArgv`). Single entry point for pi/openspec/tsx install into `~/.pi-dashboard/` — called from the Electron wizard (via `packages/electron/src/lib/dependency-installer.ts` wrapper that adds bundled-node + offline-cacache concerns) and from the CLI first-run path (`cli.ts runDegradedModeBootstrap`). See change: unified-bootstrap-install. |
-| `packages/server/src/bootstrap-state.ts` | In-memory bootstrap state store (`createBootstrapState()`, `BootstrapState { status, progress, error, version, compatibility, bridgeRegistrationError }`, `BootstrapStateStore` with get/set/subscribe/dispose plus side-channel `setLastInstallPackages` / `getLastInstallPackages` so `POST /api/bootstrap/retry` re-runs the exact failed set instead of a hard-coded default). Partial `set()` supports `undefined` = clear semantics; `setLastInstallPackages` does NOT trigger subscribers (it's not part of the broadcast snapshot). |
-| `packages/server/src/routes/bootstrap-routes.ts` | REST routes: `GET /api/bootstrap/status`, `POST /api/bootstrap/upgrade-pi` (202+ticketId or 409), `POST /api/bootstrap/retry` (202 if failed, else 409). Trigger callbacks are injected so CLI wires them to `bootstrapInstall` while tests wire them to spies. |
-| `packages/server/src/bootstrap-queue.ts` | In-memory ticket queue (`createBootstrapQueue()`, `enqueue(handler)`, `flushAll()`, `size()`, `clear(reason)`, `onTicketComplete(listener)`). `server.ts` flushes on bootstrap-state transition to "ready" and wires `onTicketComplete` → `bootstrap_ticket_complete` WS broadcast so browsers holding a 202 ticketId learn the queued op's outcome. `session-api.ts gateOrEnqueue` uses the queue to defer session spawn during installs. On `clear`, pending tickets are rejected directly (reject closure stored on the entry) so no caller hangs at shutdown. |
-| `packages/server/src/pi-version-skew.ts` | Pi compatibility range reader (`readPiCompatibility` reads `piCompatibility` from `packages/server/package.json`; `readCurrentPiVersion` via `createRequire`, with `fs.realpathSync` on the registry-resolved bin path so symlinked npm-global launchers resolve to the real module's `package.json`), comparator (`parseVersion`, `compareVersions`, `isBelow`, `isAbove` supporting `0.x` wildcard), + `updateBootstrapCompatibility(store, pkgPath)` that writes the result into `bootstrapState.compatibility` with a 60 s cache. Below-minimum adds a 503-blocking `error` message. **CLI surface**: `cli.ts` calls `logCompatibilityWarning(bootstrapState)` after each `updateBootstrapCompatibility(...)` site and emits a stderr warning — 3-line red block on below-minimum (`⚠ pi X is below the required minimum Y … Run: pi-dashboard upgrade-pi`), single-line advisory on below-recommended, silent when in range. **Currently pinned**: `minimum: "0.70.0"`, `recommended: "0.70.0"`, `maximum: null` (lockstep — no backward compatibility for older pi versions). See changes: pi-zero-seventy-compat, warn-pi-version-skew-in-cli. |
-| `packages/client/src/hooks/useBootstrapStatus.ts` | Client hook for bootstrap state. Fetches `/api/bootstrap/status` on mount, subscribes to `bootstrap-status` `CustomEvent` dispatched by `useMessageHandler` on `bootstrap_status_update` WS broadcasts. Exposes `{ state, isLoading, error, refresh, retry, upgradePi }`. |
-| `packages/client/src/components/BootstrapBanner.tsx` | Banner mounted in `App.tsx` above `<MobileShell>`. Hidden at status="ready" with no compatibility hints; blue "Installing pi…" when installing; red "pi install failed — [Retry]" when failed; amber upgrade hints when `compatibility.upgradeRecommended` or `upgradeDashboard` is true. |
-| `src/client/lib/tools-api.ts` | Client-side fetch helpers for `/api/tools*` (`fetchTools`, `rescanAll`, `rescanOne`, `setOverride`, `clearOverride`, `downloadDiagnostics`) |
-| `src/client/components/ToolsSection.tsx` | Settings → General → **Tools** section. One row per registered tool: status badge, source, truncated path, expand-to-trail, override input, per-row rescan. Top-level: Rescan all / Reset overrides / Export diagnostics |
-| `src/server/npm-search-proxy.ts` | Cached proxy for npm registry search (`keywords:pi-package`) and README fetch |
+| `src/server/routes/tool-routes.ts` | REST routes for `/api/tools*` (list, rescan, override, diagnostics) |
+| `packages/shared/src/bootstrap-install.ts` | Shared bootstrap installer for pi/openspec/tsx into `~/.pi-dashboard/` |
+| `packages/server/src/bootstrap-state.ts` | In-memory bootstrap state store (status/progress/error/version/compatibility) |
+| `packages/server/src/routes/bootstrap-routes.ts` | REST routes: bootstrap status, upgrade-pi, retry |
+| `packages/server/src/bootstrap-queue.ts` | In-memory ticket queue, flushes on bootstrap-state ready transition |
+| `packages/server/src/pi-version-skew.ts` | Pi compatibility range reader + comparator + bootstrap compatibility writer |
+| `packages/client/src/hooks/useBootstrapStatus.ts` | Client hook for bootstrap state (fetch + WS subscribe) |
+| `packages/client/src/components/BootstrapBanner.tsx` | Banner above MobileShell for installing/failed/upgrade states |
+| `src/client/lib/tools-api.ts` | Client-side fetch helpers for `/api/tools*` |
+| `src/client/components/ToolsSection.tsx` | Settings → General → Tools section (per-tool status/source/override UI) |
+| `src/server/npm-search-proxy.ts` | Cached proxy for npm registry search (`keywords:pi-package`) and README |
 | `src/server/routes/package-routes.ts` | REST routes: search, readme, installed, install, remove, update, check-updates |
 | `src/client/components/SortablePinnedGroup.tsx` | Drag-to-reorder wrapper for pinned directory groups |
 | `src/server/preferences-store.ts` | Global UI preferences (pinned dirs, session order) in `preferences.json` |
 | `src/server/meta-persistence.ts` | Per-session debounced `.meta.json` writer |
-| `src/server/session-scanner.ts` | Startup session discovery by scanning `~/.pi/agent/sessions/`. Each restored `DashboardSession` has `lastActivityAt` cold-start-seeded from the `events.jsonl` mtime (one `fs.statSync` per session, defensive try/catch — returns `undefined` on error so the badge falls back to `startedAt`). See change: session-card-last-activity-badge. The restored session also carries `unread` from `meta.unread` so unread sessions stay flagged across server restart. The `server.ts:273-279` cold-start "force status=ended" override only mutates `status` and `endedAt`, leaving `unread` intact — a session that was unread when the server stopped is still unread when it starts back up, even before its bridge reattaches. See change: session-card-unread-stripes. |
+| `src/server/session-scanner.ts` | Startup session discovery scanning `~/.pi/agent/sessions/` |
 | `src/server/migrate-persistence.ts` | One-time migration from `sessions.json` + `state.json` to `.meta.json` |
-| `src/server/session-order-manager.ts` | Per-cwd session ordering with persistence. **Move-to-front semantic** (change: top-of-tier-on-status-change): exports `moveToFront(cwd, sessionId)` — idempotent `remove + unshift` used by `server.ts onChange`'s ended→alive user-intent branch so the just-resumed card always surfaces at the top of the alive tier, even on repeated end→resume cycles. Bridge auto-reattach short-circuits before any mutation via `pendingResumeIntents.consume()`. |
-| `src/server/directory-service.ts` | Server-side session discovery, event loading, and OpenSpec polling. Uses mtime-gated per-directory cache (`DirCache`), shared FIFO semaphore, and deterministic per-cwd `phaseOffsetMs(cwd, jitterSeconds)` jitter (FNV-1a 32-bit hash). **Per-change watch set** (`perChangeArtifactPaths`) covers `<change>/`, `tasks.md`, `proposal.md`, `design.md`, plus `specs/`, every immediate `specs/<cap>/`, and every `specs/<cap>/spec.md` — `readdirSync` of `specs/` is try/catch-wrapped so missing dirs yield an empty fan-out (change: fix-openspec-specs-mtime-gate-blind-spot, which also wires `createFsSpecsProbeFactory(cwd)` into `buildOpenSpecData` as a second probe-factory argument so multi-spec authoring lights up green even when the gate misfires). **TOCTOU-safe stamping** (change: fix-openspec-mtime-gate-toctou): the per-change status loop captures `preCallMtime` *before* awaiting `runOpenSpecStatus` and stamps THAT value into the cache; if the post-call effective mtime differs, the entry is racy and the cache is left untouched (next gated tick re-polls). DEBUG-gated `console.warn` cites this change name when the discard branch fires. **Refresh contract**: `refreshOpenSpec(cwd)` is the user-clicked path and bypasses the gate via `pollOne(cwd, true)` — it's the manual escape hatch when the gate's heuristic is wrong. `pollDirectoryGated`, `onDirectoryAdded`, and the post-archive refresh in `handleOpenSpecBulkArchive` all call `pollOne(cwd, false)` so periodic / internal paths stay O(1) status spawns. `reconfigurePolling(cfg)` applies live config changes without a restart. Pi-resources scan lives on its own 5×-interval timer so it doesn't stack with the openspec burst. See changes: fix-openspec-specs-mtime-gate-blind-spot, fix-openspec-mtime-gate-toctou, fix-openspec-mtime-gate-blind-spots, optimize-openspec-poll-burst |
+| `src/server/session-order-manager.ts` | Per-cwd session ordering with persistence; `moveToFront` semantic |
+| `src/server/directory-service.ts` | Server-side session discovery, event loading, OpenSpec polling (mtime-gated) |
 | `src/server/pending-fork-registry.ts` | Tracks pending fork operations for session placement |
 | `src/server/pending-resume-registry.ts` | Queues prompts for auto-resume of ended sessions |
-| `src/server/pending-resume-intent-registry.ts` | In-memory `Map<sessionId, timestamp>` (default 60 s TTL, lazy expiry on read). `record(id)` is called by `handleResumeSession` (WS) and the REST `POST /api/session/:id/resume` handler immediately before `spawnPiSession`; `consume(id)` is called by `server.ts`'s `sessionManager.onChange` hook in the ended→alive branch. **4-way intent contract** (change: reattach-move-to-front): when `consume` returns `null` (no user intent tagged) the branch checks `OnChangeContext.registerReason`; if `"reattach"` it applies the configured `reattachPlacement` policy via `reattach-placement.ts::applyReattachPolicy`, otherwise (legacy bridge or genuine spawn) it returns early without mutation. Registry intents (`"front"` / `"keep"`) always win over `registerReason` per spec. The `if (!order.includes(sessionId))` guard inside the branch keeps drag-to-resume's dropped slot intact when the intent is present. In-memory only — NOT persisted across server restarts. See changes: preserve-session-order-on-reboot, reattach-move-to-front. |
-| `src/server/reattach-placement.ts` | Pure `decideReattachAction(policy, status)` + I/O `applyReattachPolicy(sessionId, cwd, policy, deps, priorStatus?)` for the bridge-reattach placement policy. Mapping: `"always"` → `moveToFront`; `"streaming-only"` → `moveToFront` iff `effectiveStatus === "streaming"` where `effectiveStatus = priorStatus ?? session.status`; `"preserve"` → no-op. **`priorStatus` is required for `streaming-only` to work**: `memory-session-manager.ts::register` unconditionally sets `status: "active"`, so without the prior value the policy would silently behave as `"preserve"`. Captured by `register()` from `existing?.status` BEFORE assembling the new session and forwarded via `OnChangeContext.priorStatus`. `applyReattachPolicy` is wired from `server.ts onChange` at TWO sites: (a) the existing ended→alive branch when the consumed registry intent is `null` and `ctx.registerReason === "reattach"`, and (b) a new alive→alive branch (`!isEnded && !wasEnded && ctx?.registerReason === "reattach"`) that handles the common case where the session was persisted as `"active"` so neither end-state transition fires. See change: reattach-move-to-front. |
+| `src/server/pending-resume-intent-registry.ts` | In-memory user-resume intent map (60s TTL); 4-way intent contract on reattach |
+| `src/server/reattach-placement.ts` | Pure `decideReattachAction` + I/O `applyReattachPolicy` for bridge-reattach placement |
 | `src/server/json-store.ts` | Atomic JSON file read/write helpers |
-| `src/server/process-manager.ts` | Session spawning: dispatches via `platform/spawn-mechanism.ts` `selectMechanism` → `tmux` / `wt` / `wsl-tmux` / `headless`. All mechanisms forward `sessionFile`/`mode` uniformly via `sessionFlagsToArgv`. Windows headless uses `spawnDetached` primitive with `detached: true` (PGID-equivalent via libuv) and stderr-to-file-fd (crash-visible). |
-| `src/shared/platform/detached-spawn.ts` | Three primitives: `spawnDetached` (libuv-correct detached defaults on every OS), `waitForNoCrash` (negative liveness — did it survive the window?), `waitForReady` (positive liveness — did a probe turn true?). All spawn sites with long-lived detached children delegate here. `SpawnDetachedOptions` exposes optional `stdoutFd` (defaults to `"ignore"`) and `logFd` (stderr, defaults to `"ignore"`); the bridge server-launcher sets both to the same fd for parity with the CLI. |
-| `src/shared/platform/node-version-check.ts` | Pure predicate `isKnownBadNode(version)` + message builder `buildNodeVersionWarning(version)` for Node ranges affected by [nodejs/node#58515](https://github.com/nodejs/node/issues/58515) (22.0.0–22.17.x and 24.1.0–24.2.x). Consumed by `packages/server/src/cli.ts` (preflight warning), `packages/extension/src/server-launcher.ts` (ready-timeout hint), and `packages/electron/src/lib/doctor.ts` (Node runtime compatibility row). |
-| `src/shared/platform/preload-fastify.ts` | Shared resolver `resolvePreloadFastifyPath(): string \| null` — returns absolute native path (never `file://`) to `packages/server/preload-fastify.cjs`. Used by all four server-spawn sites (cli daemon, bridge launcher, Electron lifecycle, restart-helper orchestrator) to inject `--require <preloadPath>` BEFORE `--import <jitiLoader>` so Fastify's CJS chain is cached before any ESM hook runs — sidesteps nodejs/node#58515 race-independently. See change: `preload-fastify-cjs`. |
-| `packages/server/preload-fastify.cjs` | CommonJS preload file — loaded by Node's legacy synchronous CJS loader via `--require`. Populates `require.cache` with `fastify` + `@fastify/ajv-compiler` + `@fastify/ajv-compiler/standalone` so the ESM→CJS translator short-circuits on later imports. MUST stay `.cjs`; MUST NOT use ESM syntax. |
-| `src/shared/platform/spawn-mechanism.ts` | `SpawnMechanism` enum (`tmux`/`wt`/`wsl-tmux`/`headless`) + pure `selectMechanism({ platform, userStrategy, electronMode, available })` selector. `buildWtArgs` builds argv for Windows Terminal `new-tab`. `sessionFlagsToArgv` is the uniform flag builder every mechanism MUST call. |
-| `src/shared/platform/process-identify.ts` | `findPidByMarker` + `isProcessLikePi` + `isPiCommandLine` — consolidates the three `process.platform === "win32"` branches that previously lived inside `session-action-handler.ts`. Windows stubs are documented (command-line lookup goes via `headlessPidRegistry` instead). |
-| `src/shared/platform/process.ts` | **Sole source of process termination + liveness primitives**: `isProcessAlive(pid)` (signal 0), `killProcess(pid, {timeoutMs})` (Windows `taskkill /F /T /PID`, POSIX `SIGTERM` → wait → `SIGKILL` tree kill), `killPidWithGroup(pid, sig)` (POSIX `kill(-pid, sig)`, Windows direct kill). Every `process.kill(...)` call outside this file is banned by `no-direct-process-kill.test.ts`. See change: route-kill-paths-through-platform. |
-| `src/shared/platform/node-spawn.ts` | **Sole source of `node --import <loader> <entry>` argv construction**: `toFileUrl(pathOrUrl)` (idempotent path → file:// URL, handles Windows drive letters on POSIX hosts), `spawnNodeScript(opts)` (wraps both loader and entry positions as file:// URLs before delegating to `platform/exec.ts::spawn`). Every `spawn(process.execPath, ["--import", ...])` call outside this file with raw path arguments is banned by `no-raw-node-import.test.ts`. Fixes `ERR_UNSUPPORTED_ESM_URL_SCHEME` on non-C: Windows drives (e.g. `B:\`) where Node's drive-letter heuristic for entry-script paths has known gaps. See change: fix-windows-entry-script-url. **Jiti version contract** (change: fix-electron-windows-installer-and-server-bootstrap, Defect 2): `shouldUrlWrapEntry()`'s Windows-non-tsx arm assumes the jiti loader is from `@mariozechner/pi-coding-agent@0.70.x` (jiti 2.x with the `file:///` triple-slash URL handling fix). Newer jiti versions (e.g. jiti 2.6.5 in pi 0.71.x) misnormalize triple-slash URLs and break the contract. The contract is defended by Defect 1's fix (managed-dir population from the offline cacache pins pi to 0.70.0); regression-pinned by `node-spawn-jiti-contract.test.ts` which asserts `offline-packages.json` keeps the pin in the supported `0.70.x` range AND the docstring documents the contract. |
-| `src/shared/__tests__/no-raw-node-import.test.ts` | Repo-level lint: scans `packages/*/src/` (excluding `platform/node-spawn.ts` + `resolve-jiti.ts` + `__tests__/`) for `spawn(...)` argv with `"--import"` / `"--loader"` followed by raw identifiers not wrapped in `toFileUrl(...)` / `pathToFileURL(...)`. Mirrors `no-direct-process-kill.test.ts` pattern. |
-| `src/shared/__tests__/no-direct-process-kill.test.ts` | Repo-level lint: scans `packages/*/src/` (excluding platform/ and `__tests__/`) for `process.kill(` calls and fails with file:line if any are found. Mirrors `no-direct-child-process.test.ts`. |
-| `src/shared/__tests__/bootstrap/` | In-memory bootstrap resolution harness (memfs-backed). `harness.ts` (withFakeEnv + layer), `fixtures/` (managed/npm-g/electron/dev-monorepo/settings-json layouts), `assertions.ts` (snapshotTrail + snapshotSettingsDelta with `<HOME>` / `<NPM_ROOT>` normalization), `scenarios.ts` (1080-cell cube: platform × dash × pi × settings × env), `scenarios-skipped.ts` (bulk-skip manifest with documented reasons), `cube.test.ts` (fail-closed sweep), `families/*.test.ts` (30+ registered scenario cells across A-K). Run via `npm run test:bootstrap`. See change: bootstrap-resolution-harness. |
+| `src/server/process-manager.ts` | Session spawning via `selectMechanism` → tmux/wt/wsl-tmux/headless |
+| `src/shared/platform/detached-spawn.ts` | `spawnDetached` + `waitForNoCrash` + `waitForReady` primitives |
+| `src/shared/platform/node-version-check.ts` | `isKnownBadNode` + `buildNodeVersionWarning` (nodejs/node#58515 ranges) |
+| `src/shared/platform/preload-fastify.ts` | Resolver returning native path to `preload-fastify.cjs` for `--require` injection |
+| `packages/server/preload-fastify.cjs` | CJS preload populating `require.cache` with fastify + ajv-compiler |
+| `src/shared/platform/spawn-mechanism.ts` | `SpawnMechanism` enum + `selectMechanism` selector + `sessionFlagsToArgv` |
+| `src/shared/platform/process-identify.ts` | `findPidByMarker` + `isProcessLikePi` + `isPiCommandLine` |
+| `src/shared/platform/process.ts` | Sole source of process termination + liveness primitives (kill/alive/group) |
+| `src/shared/platform/node-spawn.ts` | Sole source of `node --import <loader> <entry>` argv construction |
+| `src/shared/__tests__/no-raw-node-import.test.ts` | Repo-lint: forbid raw `--import`/`--loader` argv outside `node-spawn.ts` |
+| `src/shared/__tests__/no-direct-process-kill.test.ts` | Repo-lint: forbid `process.kill(` outside `platform/` |
+| `src/shared/__tests__/bootstrap/` | In-memory bootstrap resolution harness (memfs-backed); 1080-cell scenario cube |
 | `src/server/editor-registry.ts` | Detects available native editors (running processes + CLI) |
-| `src/server/editor-manager.ts` | Lifecycle manager for code-server child processes (spawn, stop, idle, heartbeat) |
+| `src/server/editor-manager.ts` | Lifecycle manager for code-server child processes |
 | `src/server/editor-proxy.ts` | Reverse proxy for `/editor/:id/*` to code-server instances |
 | `src/server/editor-detection.ts` | Auto-detect code-server/openvscode-server binary on PATH |
 | `src/server/routes/editor-routes.ts` | REST routes: editor start, stop, heartbeat, status, detect |
-| `src/server/event-status-extraction.ts` | Extracts session status/tool updates from events (incl. flow metadata). Hosts two pure classifiers consumed by `event-wiring.ts`: `isActivityEvent(eventType)` (allowlist driving `lastActivityAt` stamping; see change: session-card-last-activity-badge) and `isUnreadTrigger(eventType, before, after, payload)` (returns true on `streaming→idle\|active`, on `currentTool→"ask_user"`, and on `agent_end` with truthy `payload.error`; see change: session-card-unread-stripes). |
-| `src/server/viewed-session-tracker.ts` | In-memory `Map<sessionId, Set<WebSocket>>` registry of which browser has which session displayed (`/session/:id`). Created by `browser-gateway.ts`, exposed on `BrowserGateway.viewedSessionTracker`, and threaded into `wireEvents({ ..., viewedSessionTracker })`. `view`/`unview` are called from the `session_view`/`session_unview` switch arms; `unviewAll(ws)` is called on every WS `close` so disconnected browsers cannot hold sessions in the viewed state. `isViewedByAnyone(sessionId)` gates the unread-trigger stamp in `event-wiring.ts`. Read state is GLOBAL across browsers — mirrors mail/Slack. In-memory only. See change: session-card-unread-stripes. |
+| `src/server/event-status-extraction.ts` | Extracts session status/tool updates; hosts `isActivityEvent` + `isUnreadTrigger` |
+| `src/server/viewed-session-tracker.ts` | Per-browser viewed-session map; gates unread-trigger stamping |
 | `src/server/headless-pid-registry.ts` | Maps headless child PIDs to session IDs |
 | `src/server/auth.ts` | OAuth2 authentication: provider registry, JWT helpers, user allowlist |
 | `src/server/provider-auth-handlers.ts` | Pi provider OAuth handlers (Anthropic, Codex, GitHub Copilot, Gemini CLI, Antigravity) |
-| `src/server/provider-auth-storage.ts` | Read/write ~/.pi/agent/auth.json with lockfile for pi provider credentials |
+| `src/server/provider-auth-storage.ts` | Read/write `~/.pi/agent/auth.json` with lockfile for pi provider credentials |
 | `src/server/routes/provider-auth-routes.ts` | REST routes: provider OAuth authorize/exchange/callback, device-code, API key CRUD |
-| `src/server/routes/provider-routes.ts` | REST routes: custom LLM provider CRUD (`GET/PUT /api/providers`) + **`POST /api/providers/test`** connection probe (reuses `provider-probe.ts`). See change: `hot-reload-custom-providers` |
-| `src/server/provider-probe.ts` | Pure per-API-type probe builders (`buildProbeRequest` for `openai-completions`/`openai-responses`/`anthropic-messages`/`google-generative-ai`) + `resolveProbeApiKey` (handles literal, `$ENV_VAR`, and `***` REDACTED sentinel via injected providers reader) + I/O-bearing `probeProvider` (8 s timeout, never echoes apiKey in error text, caps body excerpts at 500 chars). Used by the `/api/providers/test` route and shared with the bridge's discovery path |
-| `src/extension/provider-register.ts` | Reads `~/.pi/agent/providers.json`, calls `pi.registerProvider()` with auto-discovered models, exports `reloadProviders(pi)` + `onProviderChanged(cb)`. `reloadProviders` diffs the current file against a module-level `lastRegistered` snapshot and applies add/remove/change via `registerEntry` / `pi.unregisterProvider`. Called from the bridge's `credentials_updated` handler BEFORE `modelRegistry.refresh()` so new providers appear in `/model` without a session restart. Every discovered model is enriched via `enrichModelMetadata(id, api, probe)` where `probe` wraps pi's `modelRegistry.find()` (captured from `ctx.modelRegistry` at the first `session_start` event; `model_select` is a fallback capture point) — this resolves accurate `contextWindow`, `maxTokens`, `reasoning`, `cost`, and `input` for catalog-known models (e.g., `proxy/cc/claude-opus-4-7` → 1M ctx / reasoning / Opus pricing) and falls back to api-appropriate defaults otherwise (`anthropic-messages` → 200k/64k, `google-generative-ai` → 1M/65k, `openai-completions` → 128k/16k). The fallback path keeps `input: ["text", "image"]` so pasted images reach vision-capable models without pi-ai's `downgradeUnsupportedImages` stripping them client-side; text-only models either ignore the image silently or return a 400 that the user sees. See changes: enrich-custom-provider-model-metadata, enable-image-input-custom-providers |
-| `src/client/lib/providers-api.ts` | Client-side fetch helper: `testProvider({ name?, baseUrl, apiKey, api })` → structured `{ ok, status?, modelCount?, sample?, error? }`. Used by the **Test** button on the LLM Providers card |
+| `src/server/routes/provider-routes.ts` | REST routes: custom LLM provider CRUD + connection probe |
+| `src/server/provider-probe.ts` | Pure per-API probe builders + I/O `probeProvider` (8s timeout, no apiKey echo) |
+| `src/extension/provider-register.ts` | Reads `providers.json`, calls `pi.registerProvider`, hot-reload on credentials change |
+| `src/client/lib/providers-api.ts` | Client fetch helper for `/api/providers/test` connection probe |
 | `src/client/components/ProviderAuthSection.tsx` | Settings section: OAuth login buttons, device-code modal, API key inputs |
 | `src/server/auth-plugin.ts` | Fastify plugin: auth routes, onRequest hook, WS upgrade validation |
-| `src/server/config-api.ts` | Config REST API: read (redacted), write (partial merge), secret preservation. `writeConfigPartial` auth-merge propagates `secret`, `providers`, `allowedUsers`, `bypassHosts`, `bypassUrls` (the last two added by change `fix-trusted-networks-no-oauth` — silently dropped before, breaking Trusted Networks saves for users without OAuth). |
+| `src/server/config-api.ts` | Config REST API: read (redacted), write (partial merge), secret preservation |
 | `src/client/components/SettingsPanel.tsx` | Settings UI: all dashboard config fields, grouped form, save to server |
 | `src/client/hooks/useAuthStatus.ts` | Client auth status hook and login redirect helper |
-| `src/server/localhost-guard.ts` | Network access guard: `createNetworkGuard` (loopback/trusted/authenticated), `isBypassedHost` (CIDR/wildcard/exact), netmask-to-CIDR helpers |
+| `src/server/localhost-guard.ts` | Network access guard (loopback/trusted/authenticated, CIDR/wildcard bypass) |
 | `src/server/server-pid.ts` | PID file management for daemon mode |
-| `src/client/components/ServerSelector.tsx` | Server selector dropdown showing persisted known servers. Availability probing runs **only on dropdown open** (once per open, not on mount, not on a timer, not while closed). Accepts `inFlightSwitchKey` to render a spinner on the entry being switched to. Unreachable entries are `disabled`, rendered with `opacity-50` + `cursor-not-allowed`, and clicks are no-ops. Reachable clicks delegate to the transactional staging-socket switch (see `server-switch.ts`). See change: safe-server-switch |
-| `packages/client/src/lib/staging-socket.ts` | `openStagingSocket(url, {timeoutMs}): Promise<WebSocket>` — single-settle helper that resolves on first `OPEN`, rejects on error/close/timeout, and closes the socket on timeout to avoid leaks. Used by the transactional server-switch. |
-| `packages/client/src/lib/server-switch.ts` | `performServerSwitch(target, deps)` — extracted two-phase transaction (stage → commit) from `App.tsx`'s `handleServerSwitch`. Guarantees the ordering `clearInMemoryState` → `setWsUrl` → `persistLastServer`, and never persists localStorage or clears state on staging failure. Fully unit-tested. |
-| `packages/client/src/components/ConnectionStatusBanner.tsx` | Disconnection banner: appears only after the active WebSocket has been non-`OPEN` for &gt;3s continuously; hidden immediately on reconnect; suppressed during in-flight staging switch. Mounted above `<MobileShell>` in `App.tsx`. |
+| `src/client/components/ServerSelector.tsx` | Server selector dropdown (open-only probing, transactional staging-socket switch) |
+| `packages/client/src/lib/staging-socket.ts` | `openStagingSocket(url, {timeoutMs})` — single-settle WS staging helper |
+| `packages/client/src/lib/server-switch.ts` | `performServerSwitch` two-phase transaction (stage → commit) |
+| `packages/client/src/components/ConnectionStatusBanner.tsx` | Disconnection banner (>3s non-OPEN, hidden during staging switch) |
 | `src/client/components/KnownServersSection.tsx` | Settings section: list/add/remove persisted known remote servers |
-| `src/client/components/NetworkDiscoverySection.tsx` | Settings section: mDNS network scan with "Add" action and label prompt. When the scan finds zero servers (common — Wi-Fi AP isolation, mesh routers, VLANs, VPN, firewall), renders a diagnostic block listing failure causes plus an inline manual-add form that accepts a free-form host input parsed via `parseHostInput()`. Surfaces scan errors instead of swallowing them. See change: diagnose-empty-mdns-scan |
-| `src/client/lib/parse-host-input.ts` | Pure helper `parseHostInput(input, defaultPort = 8000) → {host, port} \| null` accepting full URLs (`http://192.168.16.202:8000`), `host:port`, bare hostnames, and bracketed IPv6 (`[::1]:8000`). Rejects empty input, bare IPv6 (ambiguous with `host:port`), invalid ports, malformed URLs. 12 unit tests in `parse-host-input.test.ts`. See change: diagnose-empty-mdns-scan |
+| `src/client/components/NetworkDiscoverySection.tsx` | Settings section: mDNS network scan with manual-add fallback on empty result |
+| `src/client/lib/parse-host-input.ts` | Pure `parseHostInput(input, defaultPort)` accepting URLs/host:port/IPv6 |
 | `src/client/lib/known-servers-api.ts` | Client-side fetch helpers for known servers CRUD and discovery endpoints |
 | `src/server/routes/known-servers-routes.ts` | REST routes: known servers CRUD, on-demand mDNS discovery scan |
 | `src/server/terminal-manager.ts` | PTY lifecycle, ring buffer, spawn/attach/kill terminals |
 | `src/server/terminal-gateway.ts` | Binary WebSocket upgrade handler for `/ws/terminal/:id` |
 | `scripts/fix-pty-permissions.cjs` | Postinstall: fix node-pty spawn-helper execute permissions |
-| `src/server/tunnel.ts` | Zrok tunnel with reserved shares for persistent URLs, binary detection, PID tracking, stale cleanup |
-| `src/client/components/TunnelButton.tsx` | Unified tunnel/QR button — tunnel icon when not set up, QR icon when inactive, green QR icon when connected; opens QR dialog with disconnect/setup |
-| `src/client/components/QrCodeDialog.tsx` | QR code dialog showing tunnel URL as scannable QR code with copy, disconnect, and setup buttons |
+| `src/server/tunnel.ts` | Zrok tunnel with reserved shares, binary detection, PID tracking |
+| `src/client/components/TunnelButton.tsx` | Unified tunnel/QR button (icon state varies by tunnel status) |
+| `src/client/components/QrCodeDialog.tsx` | QR code dialog showing tunnel URL with copy/disconnect/setup |
 | `public/manifest.json` | PWA web app manifest for installability |
 | `public/sw.js` | Minimal service worker for PWA installability |
-| `src/client/components/ZrokInstallGuide.tsx` | OS-aware zrok installation guide view (macOS/Linux/Windows) |
-| `src/server/cli.ts` | CLI entry point with subcommands (start/stop/restart/status); `findPortHolders` is cross-platform (netstat/taskkill on Windows, lsof on Unix) and `server.log` is opened append-mode with timestamped headers. The local post-install `registry.rescan("pi")` block was removed and ownership of the post-install rescan + force-refresh moved to the centralized `bootstrapState.subscribe` hook in `server.ts`. See change: fix-openspec-buttons-after-bootstrap-install. **`cmdRestart(config, injected?)`** (change: fix-restart-bridge-auto-start-race): probes `isDashboardRunning(port)`; if up, POSTs `/api/restart` with `{dev}` and exits, delegating the entire stop/start to `restart-helper.ts`'s detached orchestrator; if down or HTTP fails, falls back to local `cmdStop()` + `cmdStart()`. Eliminates the in-process race where `cmdStop` killed the daemon and bridges' auto-start beat the subsequent `cmdStart`'s `isServerRunning` check (silently early-returning, leaving the user offline). The optional `injected` arg is for unit tests — production callers always use the real defaults. |
-| `src/server/restart-helper.ts` | Cross-platform `/api/restart` orchestrator: spawns a detached `node -e` child using only Node built-ins (net, http) — no sh/lsof/curl dependency; exports pure `buildOrchestratorScript(params)` for testing. **Explicit prior-daemon kill** (change: fix-restart-bridge-auto-start-race): the embedded script reads `~/.pi/dashboard/dashboard.pid`, sends `SIGTERM` to the recorded PID if alive, polls for exit (3 s deadline), then `SIGKILL`. Removes the "wait for self-exit" ambiguity that let bridges race the orchestrator before this change. The `portFree` poll is reduced from 10 s to 5 s since step 0 already guarantees the previous server is dead. |
-| `src/shared/resolve-jiti.ts` | Resolves pi's jiti register hook as a `file://` URL (required for `node --import` on Windows); exports pure `buildJitiRegisterUrl(pkgJsonPath)` helper and `resolveJitiFromAnchor(anchorPath)` for managed-install/system-pi callers |
-| `src/shared/platform/paths.ts` | OS-aware path primitives: `normalizePath`, `samePath` (filesystem-level equality), `parsePathInput` (picker input), `withTrailingSep`, `isFilesystemRoot`. All accept optional trailing `platform: NodeJS.Platform` for testability. Windows multi-drive invariant: A:\, B:\, C:\ never merge; bare `B:` input treated as drive root, not cwd-relative. Exported from `platform/index.ts` as `paths.*` namespace alongside `git.*`, `openspec.*`, `npm.*` |
-| `src/client/lib/session-grouping.ts` | `inferPlatform(samples)` heuristic (backslash/drive-letter = Windows, leading `/` = POSIX) + `groupSessionsByDirectory` that uses `normalizePath`-keyed Maps so sessions group under their pinned folder across separator/case/trailing drift. **Per-session group-key precedence** (change: add-jj-workspace-plugin, Decision 15): exported pure helper `resolveSessionGroupPath(session, pinnedKeys, platform)` resolves the group key as **explicit pin > `jjState.workspaceRoot` > `cwd`** — a session inside a `.shadow/<name>/` jj workspace collapses under its parent repo's group, but an explicit pin on the workspace path still wins. Within a group, sessions are pre-sorted by `clusterByWorkspaceName` so all rows sharing the same `(jjState?.workspaceName ?? "")` cluster adjacently (empty / main-tree first, then ws-A, ws-B, …); the existing `sortSessionsByOrder` ranking still applies inside each cluster. Tests: `packages/client/src/lib/__tests__/session-grouping.test.ts` (5 tests) covers the four scenarios from the spec plus the default-workspace regression guard. |
-| `src/shared/platform/` | Unified cross-OS primitives (see `index.ts` barrel). Sub-modules: `exec.ts` (**the only module that imports `node:child_process`** — wraps `execSync`/`exec`/`execFile`/`spawn`/`spawnSync` with `windowsHide: true` by default; enforced by `no-direct-child-process.test.ts`), `runner.ts` (the Recipe engine — `run(recipe, input)` resolves binaries via `ToolResolver`, applies timeout / tolerate / error normalization, returns `Result<T>`), `git.ts` / `openspec.ts` / `npm.ts` (Recipe-based tool modules — typed functions like `git.diff(...)`, `openspec.list(...)`, `npm.rootGlobal()` that never touch `child_process` or `process.platform`), `binary-lookup.ts` (`where`/`which`, `.cmd` ext, `ToolResolver` class; **`isAppImageSelfHit(path, opts?)`** — pure helper that flags a candidate binary path as the running Electron AppImage launcher when `realpath(path) === realpath(process.execPath)`, when `path` lives under `process.env.APPDIR` (squashfs mount), or when `realpath(path) === realpath(process.env.APPIMAGE)`. Defensive try/catch around every `realpath`. Consumed by `whereStrategy` (Layer 2 — every registry-resolved tool inherits the guard) and `detectPiDashboardCli` / `detectPi` / `detectSystemNode` (Layer 1 — belt-and-braces). See change: fix-electron-appimage-cli-self-detection), `process.ts` (`findPortHolders`, `killProcess`, `isProcessAlive`, `killPidWithGroup`, `parseNetstatListeners`), `process-scan.ts` (`isProcessRunning` via pgrep/tasklist, `parseEtime`), `shell.ts` (`detectShell` for SHELL/COMSPEC, `getTerminalEnvHints`), `commands.ts` (`openBrowser`, `isVirtualMachine`). All exported helpers that depend on OS take an optional `platform: NodeJS.Platform` parameter so tests can exercise both branches without mutating `process.platform`. See changes: consolidate-platform-handlers, platform-command-executor. |
+| `src/client/components/ZrokInstallGuide.tsx` | OS-aware zrok installation guide view |
+| `src/server/cli.ts` | CLI entry: start/stop/restart/status; `cmdRestart` delegates to `/api/restart` when up |
+| `src/server/restart-helper.ts` | Cross-platform `/api/restart` orchestrator (detached node-built-ins-only spawner) |
+| `src/shared/resolve-jiti.ts` | Resolves pi's jiti register hook as a `file://` URL |
+| `src/shared/platform/paths.ts` | OS-aware path primitives (`normalizePath`, `samePath`, `parsePathInput`) |
+| `src/client/lib/session-grouping.ts` | Sessions grouped by directory; `resolveSessionGroupPath` (pin > jjState.workspaceRoot > cwd) |
+| `src/shared/platform/` | Unified cross-OS primitives barrel (exec/runner/git/openspec/npm/process/binary-lookup/...) |
 | `src/shared/rest-api.ts` | REST API type definitions |
-
-| `.pi/skills/release-cut/SKILL.md` | Cuts a new release: promotes `## [Unreleased]` in CHANGELOG to a dated section, bumps every workspace package.json, commits, tags, pushes (which fires `publish.yml`). The skill's `Next steps (human)` block enumerates the **7 platform artifacts** the human releaser should expect on the draft GitHub Release: `PI-Dashboard-darwin-arm64-<ver>.dmg` (Apple Silicon), `PI-Dashboard-darwin-x64-<ver>.dmg` (Intel), Linux `.deb` × 2 (x64+arm64), Linux `.AppImage` (x64 only — appimagetool has no arm64 build), Windows NSIS+ZIP+portable (x64), Windows ZIP+portable (arm64, no NSIS cross-compile). Missing artifacts in the draft = a CI failure; do NOT click Publish. (change: add-darwin-x64-build updated the count from 6 → 7 and split the macOS DMG into two arches.) |
-| `.pi/skills/spec-coherence-check/SKILL.md` | Skill: sweep proposals for staleness, conflicts, obsolescence against codebase |
+| `.pi/skills/release-cut/SKILL.md` | Release-cut skill: bump versions, promote CHANGELOG, tag, push (fires publish.yml) |
+| `.pi/skills/spec-coherence-check/SKILL.md` | Skill: sweep proposals for staleness, conflicts, obsolescence |
 | `.pi/skills/spec-coherence-check/references/proposal-queue-schema.md` | JSON schema for `.pi/proposal-queue.json` |
-| `.pi/skills/code-review/SKILL.md` | Skill: comprehensive code review with severity labels, four-phase process, language-specific guides |
-| `.pi/skills/code-review/references/` | On-demand language guides (React, TypeScript, Vue, Rust, Go, Java, Python, C/C++, CSS, Qt) + architecture/performance/security reviews |
+| `.pi/skills/code-review/SKILL.md` | Skill: comprehensive code review with severity labels |
+| `.pi/skills/code-review/references/` | Language guides + architecture/performance/security review references |
 | `.pi/skills/nano-banana-imagegen/SKILL.md` | Skill: AI image generation/editing via Google Gemini (nano-banana CLI) |
-| `.pi/skills/nano-banana-imagegen/references/` | Prompting guide, example prompts (headers, icons, illustrations, photography) |
-| `.pi/skills/browser-visual-debug/SKILL.md` | Skill: visual debugging with a real browser (screenshots, interaction, responsive testing) via pi-agent-browser |
-| `.pi/skills/browser-visual-debug/references/` | Dashboard recipes, responsive testing presets, agent-browser commands cheatsheet |
-| `.pi/skills/browser-visual-debug/scripts/detect-dashboard.sh` | Auto-detect dashboard URL, mode, and Vite dev server status |
-| `packages/electron/src/main.ts` | Electron main process: single-instance, wizard, server launch, loading page, tray. **Power-user-mode managed install** (change: fix-electron-windows-installer-and-server-bootstrap, Defect 1): the firstRun `pi.found && bridge.found` auto-skip path no longer skips `installStandalone()`. Auto-skip removes the wizard UI; the managed install (tsx + pi@0.70.0 + openspec from the offline cacache) runs anyway so the bundled server's runtime can resolve its TS loader from `~/.pi-dashboard/`. Decision logic extracted into the pure `decideStartupAction(state)` helper in `lib/power-user-install.ts` and pinned by `wizard-power-user-managed-install.test.ts`. **External-link hardening (change: harden-external-link-handling, #13)**: `createMainWindow` registers `webContents.setWindowOpenHandler` + `will-navigate` BEFORE `loadURL` so `target="_blank"` / `window.open` and bare-`<a>` external navigation both route through `shell.openExternal` (system browser) instead of replacing the dashboard. The `will-navigate` callback is **OAuth-aware** via `decideWillNavigate(serverUrl, webContents.getURL(), url)` (change: fix-oauth-blocked-by-external-link-guard) so the trap-guard fires only when leaving the dashboard — while the user is mid-login on an OAuth provider page (Google, GitHub, generic OIDC), provider-internal multi-step navigation is allowed and the eventual callback redirect lands cleanly. `setWindowOpenHandler` is unchanged. |
-| `packages/electron/src/lib/link-handling.ts` | Pure helpers used by the Electron shell. **`isSameOriginUrl(href, serverOrigin)`** — classifies URLs as same-origin vs external (handles absolute, relative, fragment-only, and malformed inputs; see change: harden-external-link-handling, #13). **`decideWillNavigate(serverOrigin, currentUrl, targetUrl) → "allow" | "open-external" | "cancel"`** — OAuth-aware decision wrapper for the `will-navigate` callback: while the BrowserWindow shows a non-dashboard origin (mid-OAuth) it returns `"allow"` so provider login flows proceed; on the dashboard it composes `isSameOriginUrl` to decide between `"allow"` (same-origin) and `"open-external"` (external trap-guard); fail-closes to `"cancel"` on unparseable `serverOrigin` (see change: fix-oauth-blocked-by-external-link-guard). No Electron imports; 23 unit tests in `packages/electron/src/__tests__/link-handling.test.ts`. |
-| `packages/client/src/components/MarkdownContent.tsx` | ReactMarkdown-based renderer for chat bodies, thinking blocks, flow agent detail, package READMEs, markdown previews. **External-link hardening (change: harden-external-link-handling, #13)**: exports pure `isExternalHref(href)` and overrides the `a` component so external URLs render with `target="_blank" rel="noopener noreferrer"` while fragment-only and same-origin hrefs stay in-document. |
-| `packages/client/src/__tests__/no-bare-external-anchor.test.ts` | Repo-level lint: scans client `.tsx` files for `<a href="http(s)://...">` tags missing `target="_blank"`. Per-line opt-out via `// ban:bare-anchor-ok`. See change: harden-external-link-handling. |
-| `packages/electron/src/lib/server-lifecycle.ts` | Health check → tsx binary spawn (inlined config/health, no shared pkg imports). **60-second startup deadline + cause-aware error wording** (change: fix-electron-windows-installer-and-server-bootstrap, Defect 4): exports `SERVER_READY_DEADLINE_MS = 60_000` (was inline `15_000`) and a pure helper `buildServerStartupError(...)` that renders "Server child process exited prematurely (...)" when `ready.error` mentions an exit, vs. "Server did not respond within 60 seconds (...)" when the deadline elapsed. The pre-fix message conflated both cases and was misleading when the child died in <1s. Both `launchViaCli` and `launchServer` use the same constant + helper. |
-| `packages/server/src/extension-register.ts` | Auto-registers bundled bridge extension in pi's global settings on startup |
+| `.pi/skills/nano-banana-imagegen/references/` | Prompting guide, example prompts |
+| `.pi/skills/browser-visual-debug/SKILL.md` | Skill: visual debugging with a real browser via pi-agent-browser |
+| `.pi/skills/browser-visual-debug/references/` | Dashboard recipes, responsive presets, agent-browser cheatsheet |
+| `.pi/skills/browser-visual-debug/scripts/detect-dashboard.sh` | Auto-detect dashboard URL, mode, Vite dev server status |
+| `packages/electron/src/main.ts` | Electron main: single-instance, wizard, server launch, loading page, tray |
+| `packages/electron/src/lib/link-handling.ts` | Pure `isSameOriginUrl` + OAuth-aware `decideWillNavigate` for external-link guard |
+| `packages/client/src/components/MarkdownContent.tsx` | ReactMarkdown renderer (chat/thinking/READMEs/previews); external-link hardening + KaTeX math + `pi-asset:` image scheme |
+| `packages/client/src/lib/SessionAssetsContext.tsx` | Per-session image-asset registry context resolving `pi-asset:<hash>` srcs in `MarkdownContent` |
+| `packages/extension/src/markdown-image-inliner.ts` | Bridge helper rewriting assistant `![alt](path)` → `![alt](pi-asset:<hash>)` (SHA-256/16, MIME allowlist, 5 MB/img + 20 MB/msg caps) |
+| `packages/client/src/__tests__/no-bare-external-anchor.test.ts` | Repo-lint: forbid bare `<a href="http(s)://">` without `target="_blank"` |
+| `packages/electron/src/lib/pick-node.ts` | Pure `pickNodeForServer` — prefer system Node when version-safe, else bundled |
+| `packages/electron/src/lib/ensure-windows-path.ts` | `ensureWindowsSystemPath` — prepend System32/npm/Git dirs on Windows; no-op on POSIX |
+| `packages/electron/src/lib/server-lifecycle.ts` | Health check → server spawn; `setSpawnedPid` + `decideShutdownOnQuit` for V2 ownership rule |
+| `packages/electron/src/lib/launch-source.ts` | `selectLaunchSource()` resolver: attach→devMonorepo→piExtension→npmGlobal→extracted; `spawnFromSource` |
+| `packages/electron/src/lib/bundle-extract.ts` | `needsExtraction`, `migrateConfigs`, `extractBundle` with survive-extract whitelist for `~/.pi-dashboard/` |
+| `packages/shared/src/installable-list.ts` | `InstallablePackage`/`InstallableList` types; `readInstallableList`, `writeInstallableList`, `mergeInstallableList` |
+| `packages/server/src/bootstrap-install-from-list.ts` | Per-package reconcile loop reading `~/.pi/dashboard/installable.json`; no-op when file absent |
+| `packages/shared/src/bridge-register.ts` | Shared bridge registration: `findBundledExtension(baseDir)` + `registerBridgeExtension(path)`; non-destructive cleanup, AppImage guard. Used by server startup and Electron wizard. |
 | `packages/electron/src/lib/doctor.ts` | Doctor diagnostic: checks all binaries, versions, server status, offers setup |
+| `packages/shared/src/doctor-core.ts` | Shared doctor primitives: types, SECTION_OF, SUGGESTIONS, safeExec/safeCheck/assumedMandatory, runSharedChecks, formatDoctorReportMarkdown |
+| `packages/electron/src/lib/doctor-bridge-contract.ts` | Typed `DoctorBridge` interface + frozen `DOCTOR_IPC_CHANNELS` (channel-name-drift lint) |
+| `packages/electron/src/lib/doctor-window.ts` | `openDoctorWindow()` factory + IPC handlers (`doctor:run` etc.); concurrent-run serialization; closed→null leak fix |
+| `packages/electron/src/preload/doctor-preload.ts` | Preload bridge exposing `window.electron.doctor` to `doctor.html` |
+| `packages/electron/src/renderer/doctor.html` | Hand-rolled Doctor renderer — sections, status pills, suggestion callouts, toolbar |
+| `packages/server/src/routes/doctor-routes.ts` | `GET /api/doctor` route — auth-gated; runs `runSharedChecks`; 200 + fallback row on internal failure |
+| `packages/client/src/lib/doctor-api.ts` | Client fetch helper for `/api/doctor` with `DoctorFetchError` typed envelope |
+| `packages/client/src/components/DiagnosticsSection.tsx` | Settings → Diagnostics — fetch, sections, suggestions, copy-to-clipboard with textarea fallback |
 | `packages/electron/src/lib/app-menu.ts` | App menu with About dialog and Doctor on all platforms |
-| `packages/electron/src/lib/tray.ts` | System tray with platform-specific icons (template on macOS, ico/png on Win/Linux) |
-| `packages/electron/src/lib/dependency-installer.ts` | Async npm install of pi, openspec, tsx into ~/.pi-dashboard/ using bundled Node |
-| `packages/electron/src/lib/dependency-detector.ts` | Detects pi, openspec, Node.js on system PATH and managed install. **AppImage self-recursion guard** (change: fix-electron-appimage-cli-self-detection): `detectPiDashboardCli` rejects any candidate that matches `isAppImageSelfHit(path)` (in addition to the existing `_npx` filter) so power-user mode falls through to the standalone tsx + `cli.ts` path when the only `pi-dashboard` on PATH is the AppImage's own launcher (`packagerConfig.executableName: "pi-dashboard"` collides by design). `detectPi` and `detectSystemNode` apply the same guard symmetrically on the registry-resolved path — belt-and-braces beyond the `whereStrategy` filter. **Windows extension filter** (change: fix-electron-windows-installer-and-server-bootstrap, Defect 3): exports a pure helper `pickSpawnableShim(rawWhereOutput, platform)` that, on `win32`, prefers candidates ending in `.cmd`/`.exe`/`.bat`/`.ps1` over an extensionless POSIX shim from npm-global. `spawn()` without `shell:true` cannot invoke an extensionless shim on Windows, so the pre-fix `lines[0]` pick produced `ENOENT`. POSIX behaviour (single-line `which`) unchanged. Locked by `dependency-detector-windows-extensions.test.ts`. |
+| `packages/electron/src/lib/tray.ts` | System tray with platform-specific icons |
+| `packages/electron/src/lib/dependency-installer.ts` | Async npm install of pi/openspec/tsx into `~/.pi-dashboard/` (Windows-hardened) |
+| `packages/electron/src/lib/dependency-detector.ts` | Detects pi/openspec/Node on PATH and managed install (AppImage + Win-ext guards) |
 | `packages/electron/src/lib/bundled-node.ts` | Resolves bundled Node.js/npm paths in Electron resources |
 | `packages/electron/src/lib/wizard-window.ts` | First-run setup wizard window with preload bridge |
-| `packages/electron/forge.config.ts` | Electron Forge config: DMG, DEB, AppImage, NSIS makers, icon, extraResources. **NSIS naming overrides** (change: fix-electron-windows-installer-and-server-bootstrap): the NSIS maker's `getAppBuilderConfig` callback explicitly pins `productName`, `appId`, `nsis.artifactName`, `nsis.shortcutName`, `nsis.uninstallDisplayName` all to `pi-dashboard`. Without this override, electron-builder's NSIS install-dir fallback chain reads npm `name` slash-stripped and produces `@blackbelt-technologypi-dashboard-electron`. Locked by `forge-config-naming.test.ts`. **macOS deployment-target floor** (change: add-darwin-x64-build, 6b): `packagerConfig.extendInfo.LSMinimumSystemVersion = "10.15"` pins the user-visible minimum macOS version in the produced `Info.plist`. Pairs with `MACOSX_DEPLOYMENT_TARGET=10.15` exported by the `Make Electron distributables` step in `publish.yml` (every Mach-O the build produces declares 10.15 as its `LC_BUILD_VERSION.minos`) and a CI verification step that mounts the DMG and asserts both values match — a future runner-image upgrade or source-built native module cannot silently raise the floor without failing the job. **Arch-tagged DMG basename** (change: fix-darwin-dmg-arch-collision): the `@electron-forge/maker-dmg` config's `name` field is composed at config-evaluation time as `` `PI-Dashboard-darwin-${process.arch}-${pkgVersion}` `` (with `pkgVersion` read from `packages/electron/package.json` once at module top). Both macOS matrix legs (`macos-14`/arm64, `macos-15-intel`/x64) previously emitted a static `PI Dashboard.dmg`, causing `softprops/action-gh-release@v2` to silently overwrite one arch with the other on release-asset upload (it dedups by basename). The arch-tagged basename also ensures parity with deb (`_amd64`/`_arm64`) and Windows portable (`-arm64`/`-x64`) artifact-naming conventions. The `title` field stays `"PI Dashboard"` so the mounted-volume window title remains friendly. Locked by `forge-config-dmg-naming.test.ts` (6 tests covering both arches, version interpolation, title preservation, exact pattern match). |
-| `packages/electron/scripts/build-installer.sh` | Build script: native + Docker cross-platform (--linux, --windows, --all). **`--mac-both`** (change: add-darwin-x64-build) builds BOTH macOS DMGs (arm64 + x64) on an Apple Silicon host in one invocation: orchestrates two sequential `build_native_one_arch` calls with sentinel-driven cache invalidation between them (`resources/.last-arch`); refuses on Intel hosts (Rosetta is one-way, x64 → arm64 cross-compile is not supported locally) and on non-darwin hosts. Cross-arch x64 builds on Apple Silicon hosts auto-detect Rosetta 2 via `arch -x86_64 /usr/bin/true` (fail-fast with `softwareupdate --install-rosetta --agree-to-license` hint if missing) and wrap `bundle-server.mjs` in `arch -x86_64` + sets `TARGET_ARCH=x64` env so node-pty's prebuilt x64 binary is downloaded. The `--mac-both` post-build smoke summary mounts each DMG and reports the inner Mach-O arch tag (`arm64` / `x86_64`) via `file` so silent arch-mismatch artifacts cannot ship undetected. The arch-aware cache wipe also fires on single-arch back-to-back invocations (`--arch arm64` then `--arch x64`) so manual cache cleanup is no longer required. Pure helpers: `maybe_wipe_arch_caches`, `verify_rosetta_or_fail`, `build_native_one_arch`. |
-| `packages/electron/scripts/docker-make.sh` | Docker entrypoint: platform-aware native module handling, ZIP for Windows |
-| `packages/electron/scripts/Dockerfile.build` | Docker image for cross-platform builds (node:22-bookworm-slim + build tools) |
-| `packages/electron/scripts/bundle-server.mjs` | Bundles dashboard server source + deps into resources/server/ (`--source-only` for cross-builds). Node-native ESM script (replaces `bundle-server.sh`) so Windows electron CI runs without MSYS/bash. Uses `fs.cpSync` / `fs.chmodSync` / recursive `readdir` instead of `cp -R`/`find`/`chmod`/`du`. Verified bit-parity with the old shell script: identical 2251-file layout, identical structure. See change: eliminate-bash-on-windows-runners. **Architectural lock**: synthetic `package.json` deliberately does NOT declare `@mariozechner/pi-coding-agent` (or any managed-dir-resident dep). The bundled tree only contains workspace deps (`fastify`, `ws`, `node-pty`, etc.) directly imported by the bundled `cli.ts`. pi/openspec/tsx live in the managed dir (`~/.pi-dashboard/`) and are installed there by `installStandalone()` from the offline cacache pinned in `offline-packages.json`. An earlier `/opsx:apply` session against `fix-electron-windows-installer-and-server-bootstrap` proposed adding a `dependencies: { "@mariozechner/pi-coding-agent": "0.70.0" }` block here — reverted as architecturally wrong (would duplicate ~10MB and create version-drift risk vs. the offline cacache). Bundle stays at ~80MB; if it ever climbs to ~160MB, that's the regression marker. See change: fix-electron-windows-installer-and-server-bootstrap (D5 reconsidered). |
-| `packages/electron/offline-packages.json` | Pinned versions of pi-coding-agent / openspec / tsx that get bundled as an offline npm cacache per release (see change: `electron-offline-bundled-packages`) |
-| `packages/electron/scripts/bundle-offline-packages.sh` | Build-time script that runs `npm install --os=<os> --cpu=<cpu> --ignore-scripts` for the pinned versions, tars the resulting `_cacache/` (pax format — ustar is too narrow), writes `manifest.json` with SHA-256, and enforces a 100 MB hard budget. Opt-in via `BUNDLE_OFFLINE_PACKAGES=1`. |
-| `packages/electron/resources/offline-packages/manifest.json` | Offline-cache manifest (`{bundledAt, targetPlatform, tarball, tarballBytes, sha256, packages}`). Consumed at runtime by `dependency-installer.ts` via `resolveOfflinePackages()`. |
-| `packages/electron/resources/offline-packages/npm-cache.tar.gz` | gzipped npm cacache used by the first-run offline install. Extracted to `~/.pi-dashboard/.offline-cache/`, verified by SHA-256, consumed by `npm install --offline`, then deleted to reclaim ~140 MB. |
-| `packages/electron/src/lib/offline-packages.ts` | Pure helpers: `parseOfflineManifest`, `resolveOfflinePackages`, `fileSha256`, `extractOfflineCache`, `buildOfflineInstallArgs`, `selectInstallStrategy`. 19 unit tests in `packages/electron/src/__tests__/offline-packages.test.ts`. |
-| `packages/electron/scripts/bundle-recommended-extensions.sh` | Opt-in (via `BUNDLE_RECOMMENDED_EXTENSIONS=1`) build-time bundler that clones each id in `BUNDLED_EXTENSION_IDS` into `packages/electron/resources/bundled-extensions/<id>/`, records `.bundled-sha`, enforces SPDX allowlist (MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC) and a 15 MB total size budget. See change: bundle-first-party-extensions. |
-| `packages/electron/src/lib/dependency-installer.ts` → `installBundledExtensions` | First-run activation of pre-bundled extensions. Copies `<resourcesPath>/bundled-extensions/<id>/` into pi's git cache (`~/.pi/agent/git/<host>/<path>/`), runs `npm install --omit=dev` if runtime deps declared, then calls `manager.addSourceToSettings(gitUrl)` + `settingsManager.flush()`. Returns activated ids so `installRecommendedExtensions` can skip them with `output: "Already installed (bundled)"`. |
-| `packages/electron/src/lib/wizard-badge.ts` | Pure `classifyProgressBadge(output)` helper (`bundled` / `system` / null) shared between wizard HTML inline JS and unit tests. |
-| `packages/shared/src/recommended-extensions.ts` → `BUNDLED_EXTENSION_IDS` | Single source of truth for which recommended ids ship bundled in the Electron installer. **Currently `["pi-anthropic-messages"]` only** — `"pi-flows"` was removed in commit b9b3d7e because the upstream repo (BlackBeltTechnology/pi-flows) declares no SPDX license (no `LICENSE` file, no `package.json#license`), and `bundle-recommended-extensions.sh`'s allowlist (MIT/Apache-2.0/BSD-2-Clause/BSD-3-Clause/ISC) correctly rejects it — which was blocking every electron build matrix variant. Re-add `"pi-flows"` once upstream declares a license. The npm publish path is unaffected (only electron build was broken). See `openspec/changes/archive/2026-04-21-bundle-first-party-extensions/design.md` for original design + license-blocker discussion. |
-| `packages/electron/scripts/docker-make.sh` | Docker entrypoint: bundles server, installs native deps, runs Forge make |
-| `packages/electron/scripts/Dockerfile.build` | Docker image for cross-platform builds (node:22-bookworm-slim + build tools) |
+| `packages/electron/forge.config.ts` | Electron Forge config: DMG/DEB/AppImage/NSIS makers; arch-tagged DMG; macOS 10.15 floor |
+| `packages/electron/scripts/build-installer.sh` | Build script: native + Docker cross-platform; `--mac-both` arm64+x64 sequence |
+| `packages/electron/scripts/docker-make.sh` | Docker entrypoint: bundles server, native deps, runs Forge make |
+| `packages/electron/scripts/Dockerfile.build` | Docker image for cross-platform builds (node:22-bookworm-slim) |
+| `packages/electron/scripts/bundle-server.mjs` | Bundles dashboard server + workspace deps into `resources/server/` (Node-native ESM) |
+| `packages/electron/offline-packages.json` | Pinned versions of pi/openspec/tsx for offline npm cacache |
+| `packages/electron/scripts/bundle-offline-packages.sh` | Build-time script: pack pinned versions into cacache tarball with SHA-256 |
+| `packages/electron/resources/offline-packages/manifest.json` | Offline-cache manifest consumed at runtime by `dependency-installer.ts` |
+| `packages/electron/resources/offline-packages/npm-cache.tar.gz` | gzipped npm cacache for first-run offline install |
+| `packages/electron/src/lib/offline-packages.ts` | Pure offline-cache helpers (parse, resolve, verify SHA-256, extract) |
+| `packages/electron/scripts/bundle-recommended-extensions.sh` | Opt-in: clone bundled-extension ids with SPDX allowlist + 15MB budget |
+| `packages/electron/src/lib/dependency-installer.ts` → `installBundledExtensions` | First-run activation of pre-bundled extensions into pi git cache |
+| `packages/electron/src/lib/wizard-badge.ts` | Pure `classifyProgressBadge(output)` (`bundled`/`system`/null) |
+| `packages/shared/src/recommended-extensions.ts` → `BUNDLED_EXTENSION_IDS` | Single source of truth for bundled extension ids in Electron installer |
 | `packages/electron/scripts/test-server-launch.sh` | Docker-based test for server launch on clean Linux |
 | `packages/electron/scripts/test-electron-install.sh` | Full e2e Docker test: install, wizard, server launch, health check |
 | `packages/electron/scripts/test-electron-install-inner.sh` | Inner test script run inside Docker container |
-| `packages/electron/resources/icon.png` | Master 1024×1024 app icon (π on dark navy) |
-| `.github/workflows/publish.yml` | CI: builds DMG × 2 (macOS arm64 + x64), DEB+AppImage (Linux), NSIS+ZIP+portable (Windows) on native runners; publishes npm + GitHub Release. **Build matrix covers 6 (platform, arch) tuples** — darwin/arm64 (`macos-14`), darwin/x64 (`macos-15-intel` — GitHub's last hosted Intel x86_64 image after `macos-13` was retired on 2025-12-08; EOL announced 2027-08; change: add-darwin-x64-build), linux/x64 (`ubuntu-latest`), linux/arm64 (`ubuntu-24.04-arm`), win32/x64 (`windows-latest`), win32/arm64 (`windows-latest`). Missing rows are a regression — the spec requirement `electron-build-pipeline > CI build matrix` enumerates each scenario explicitly to prevent silent drift. **Two triggers**: (a) push of any `v*` tag (the original path — release-cut skill / hand tag), (b) `workflow_dispatch` from the GitHub Actions UI with a single required `version` input (e.g. `"0.4.1"`). The `prepare` job branches on `github.event_name`: tag-push extracts the version from `GITHUB_REF_NAME`; dispatch validates the input as semver, checks tag uniqueness on origin, bumps every workspace `package.json` via `npm version -ws`, syncs cross-ref specifiers via `scripts/sync-versions.js`, promotes `## [Unreleased]` to a dated `## [<version>]` section in `CHANGELOG.md`, commits + tags + pushes the branch. The publish, electron, and github-release jobs all `needs: prepare` and check out `ref: ${{ needs.prepare.outputs.tag }}` so both trigger paths publish the same tree. **Idempotent ordered npm publish (commit b9fcea9)**: the publish step replaced the bulk `npm publish --workspaces --include-workspace-root` call with a per-package loop that (a) **skips** already-published versions via `npm view <pkg>@<ver>` (so a re-run after partial-publish failure resumes cleanly instead of aborting on "cannot publish over previously published"), (b) publishes the **4 stable sub-packages first** (`pi-dashboard-shared` → `extension` → `server` → `web`), then the brand-new `dashboard-plugin-runtime`, then the **root metapackage last** so the registry already serves matching sub-package versions before the root tarball lands and resolves dependents like `@blackbelt-technology/pi-dashboard-extension@^X.Y.Z`. v0.4.0 and v0.4.1 shipped broken because the bulk call aborted on the first error and only the root tarball landed — `npm install @blackbelt-technology/pi-agent-dashboard@0.4.1` returned ETARGET on the sub-deps. Single-failure isolation: any non-skip failure marks the step failed via a `FAIL=1` accumulator but lets the loop finish so logs show every package's outcome. Also (commit b9fcea9): `packages/server/package.json#dependencies` now declares `@blackbelt-technology/dashboard-plugin-runtime: ^<ver>` — previously imported via workspace symlinks but missing from the published tarball, so a clean `npm install` of just the server crashed with `MODULE_NOT_FOUND` on first start. Also (commit 2728c31): every workspace `package.json` (`shared`, `extension`, `server`, `client`, `dashboard-plugin-runtime`, plus `electron`) now declares a `repository` field — required for npm provenance attestation validation when publishing with `--provenance` from GitHub Actions OIDC. **Electron-publish dependency-graph contract** (change: publish-fix-macos): the `electron` matrix job declares `needs: [prepare, publish]` and `strategy.fail-fast: false`. The `needs: publish` gate closes the ETARGET race that broke release run #34 — `bundle-server.mjs` runs `npm install --omit=dev` against the live npm registry and resolves `@blackbelt-technology/dashboard-plugin-runtime@^<ver>` (added in commit b9fcea9 to fix `MODULE_NOT_FOUND` on clean server installs), so it must run AFTER publish has uploaded the just-bumped sub-packages. `fail-fast: false` keeps a single-OS failure from cancelling the other four matrix variants — release engineers see the full diagnostic per OS instead of one error and four cancellations. Locked by `packages/shared/src/__tests__/publish-workflow-contract.test.ts`. **No-bash-on-Windows invariant** (change: eliminate-bash-on-windows-runners): no step in `publish.yml` or `ci.yml` combines `shell: bash` with a runtime configuration that can run on a `windows-latest` runner. Cross-OS build orchestration lives in `.mjs` scripts invoked by `node`; POSIX-only steps use `shell: bash` gated by `if: matrix.platform != 'win32'`; Windows-only steps use `shell: pwsh`. The bundle scripts (`bundle-server.mjs`, `bundle-offline-packages.mjs`, `bundle-recommended-extensions.mjs`) are Node-native, eliminating the bash↔Node bridge that produced the `MODULE_NOT_FOUND` regression on Windows runners. Locked by `packages/shared/src/__tests__/no-bash-on-windows.test.ts`. |
-| `packages/shared/src/__tests__/publish-workflow-contract.test.ts` | Repo-level lint: parses `.github/workflows/publish.yml`, asserts the electron job's `needs:` array contains both `prepare` and `publish` AND `strategy.fail-fast` is the literal `false`. Failure messages cite change `publish-fix-macos` so the contributor knows where to look. Mirrors `no-direct-process-kill.test.ts` and `no-raw-node-import.test.ts`. See change: publish-fix-macos. |
-| `packages/shared/src/__tests__/no-bash-on-windows.test.ts` | Repo-level lint: parses every workflow YAML, computes per-step Windows reachability from `electron` matrix × each step's `if:` filter (small grammar: `matrix.platform == 'X'`, `matrix.platform != 'X'`, `&&`, `||`, `!(...)` , parens), and fails when any `shell: bash` step is reachable on a Windows runner. Failure messages cite change `eliminate-bash-on-windows-runners` plus the offending `file:line` + step name. Unrecognised `if:` expressions fail closed (force the contributor to write a recognisable form or extend the evaluator). See change: eliminate-bash-on-windows-runners. |
+| `packages/electron/resources/icon.png` | Master 1024×1024 app icon |
+| `.github/workflows/publish.yml` | CI: build matrix × 6 (platform,arch); idempotent ordered npm publish; no-bash-on-Windows |
+| `packages/shared/src/__tests__/publish-workflow-contract.test.ts` | Repo-lint: pin electron job's `needs:` array and `fail-fast: false` |
+| `packages/shared/src/__tests__/no-bash-on-windows.test.ts` | Repo-lint: forbid `shell: bash` on steps reachable on Windows runners |
 
 ## Build & Restart Workflow
 
@@ -389,17 +551,4 @@ When creating OpenSpec change artifacts, always place them at `openspec/changes/
 
 When creating diagrams, use Mermaid syntax (```mermaid blocks) instead of ASCII box drawings. This applies to explore mode, design documents, and all other artifacts.
 
-## Code Instructions
-
-1. First think through the problem, read the codebase for relevant files.
-2. Before you make any major changes, check in with me and I will verify the plan.
-3. Please every step of the way just give me a high level explanation of what changes you made.
-4. Make every task and code change you do as simple as possible. We want to avoid making any massive or complex changes. Every change should impact as little code as possible. Everything is about simplicity.
-5. Maintain a documentation file that describes how the architecture of the app works inside and out.
-6. Never speculate about code you have not opened. If the user references a specific file, you MUST read the file before answering. Make sure to investigate and read relevant files BEFORE answering questions about the codebase. Never make any claims about code before investigating unless you are certain of the correct answer - give grounded and hallucination-free answers.
-7. For implementation use TDD (Test-Driven Development): write or update tests first to define the expected behaviour, verify they fail, then write the minimal implementation to make them pass.
-8. Use DRY (Don't Repeat Yourself): extract reusable logic into separate classes, utilities, or components. If the same pattern appears in multiple places, refactor it into a shared helper.
-
-## Document changes
 
-When an implementation is ready, update AGENTS.md, README.md, and docs/architecture.md. AGENTS.md contains instructions for AI agents, key files, and commands needed to build and operate. README.md contains end-user and developer documentation with CI badges, prerequisites, configuration, and project structure. docs/architecture.md contains detailed data flows, persistence model, reconnection logic, and configuration reference.