# PI Dashboard Architecture > **Adjacent artifact:** the public marketing site lives at `/site` and is > product-adjacent, not part of the dashboard runtime. It has its own Astro > build, its own Playwright screenshot pipeline, and its own GitHub Pages > deploy workflow (`.github/workflows/deploy-site.yml`). See > `/site/README.md` for details. ## Overview The PI Dashboard is a web-based dashboard for monitoring and interacting with pi agent sessions. It consists of three components: ``` ┌─────────────┐ WebSocket ┌──────────────┐ WebSocket ┌─────────────┐ │ Bridge │ ◄─────────────────► │ Dashboard │ ◄───────────────► │ Web Client │ │ Extension │ (port 9999) │ Server │ (port 8000) │ (React) │ │ (per pi) │ │ (Node.js) │ │ (Browser) │ └─────────────┘ └──────────────┘ └─────────────┘ │ ┌─────┴─────┐ │ In-Memory │ │ + JSON │ └───────────┘ ``` ## Components ### 1. Bridge Extension (`src/extension/`) A global pi extension that runs in every pi session. It: - Detects session source (TUI, Zed, tmux, dashboard-spawned) via `.meta.json` sidecar files and environment variables - Forwards all pi events to the dashboard server via WebSocket - Relays commands from the dashboard back to pi - Handles reconnection with exponential backoff and event buffering - Sends heartbeats every 15s with process metrics (CPU%, RSS, heap, event loop max delay, load average); server responds with `heartbeat_ack` - Server liveness watchdog: forces reconnect if no message received for 60s - Server-side WS ping/pong (60s interval) detects dead TCP connections; requires 2 consecutive missed pongs before killing (tolerates long-running bash commands that block the event loop) - Detects OpenSpec activity (phase/change) from tool events; server auto-attaches the change when `changeName` is detected (phase is not required — skills loaded via prompt templates don't emit a SKILL.md read event). The session card's OpenSpec activity badge displays when either `openspecPhase` or `openspecChange` is detected (not just phase). - **Attached-proposal artifact summary** in the content-window header (`SessionHeader.tsx`, both desktop branch and `MobileHeader`): when `session.attachedProposal` matches an entry in the polled `openspecChanges` list, the header renders the `ArtifactLettersButton` (P/D/T/S letters colored by per-artifact status, single button → opens the proposal artifact) plus a `(completedTasks/totalTasks)` counter. Surface is gated on the explicit user attach only — auto-detected `openspecChange` does not trigger it. Wired via the new `onReadArtifact` prop, threaded from `App.tsx` (`handleReadArtifact` from `useContentViews`). See change: add-attached-proposal-header-summary. - **Duplicate bridge prevention**: Uses `process`-level shared state (not `globalThis`) with a monotonic generation counter. When the extension is loaded multiple times (e.g., local + global npm package), only the latest instance's event handlers are active — stale listeners bail out immediately. All previous connections and timers are tracked and cleaned up on re-init. - **Subagent re-entry guard**: When pi-subagents launches an Agent tool, the subagent creates its own `AgentSession` which loads extensions (including the bridge) in the same process. Without protection, this would overwrite the parent bridge's global state, disconnect its WebSocket, and prevent `tool_execution_end`/`agent_end` from being forwarded — leaving the parent session stuck at "streaming" forever. The bridge stores a reference to its owning `pi` instance and skips initialization when called from a different instance (subagent). - Routes `ctx.ui` dialog methods (confirm, select, input, editor, multiselect, notify) through `PromptBus` (`prompt-bus.ts`) - Adapters register to handle prompts: `DashboardDefaultAdapter` renders generic dialogs inline; extensions (e.g. pi-flows) can register custom adapters via `prompt:register-adapter` event - First-response-wins: multiple adapters (TUI, dashboard, custom) can claim a prompt; the first to respond resolves it, others are dismissed - Bridge's TUI adapter is registered inline (captures original `ctx.ui` methods before patching) and presents `select`/`input`/`confirm`/`editor` prompts in the terminal with AbortController-based cancellation. Multiselect bypasses the TUI adapter entirely and uses the bus-routed `ctx.ui.multiselect` patch → `DashboardDefaultAdapter` → client `MultiselectRenderer` exclusively (pi 0.70 RPC's `ctx.ui.custom` is a no-op, so a TUI arm would auto-cancel the dashboard render in <1s). See changes: fix-multiselect-auto-cancel-on-dashboard, fix-multiselect-tui-arm-self-cancel. - Patched `ctx.ui` methods forward the `message` field (from opts) via `metadata` in the PromptBus request - Client-side `prompt-component-registry.ts` maps component type strings to render placement (inline, widget-bar, overlay) - Protocol messages: `prompt_request`, `prompt_dismiss`, `prompt_cancel`, `prompt_response` ### 2. Dashboard Server (`src/server/`) A Node.js HTTP + WebSocket server that: - Accepts connections from bridge extensions (Pi Gateway, port 9999) - Accepts connections from web browsers (Browser Gateway, port 8000) - Stores events in an in-memory buffer with LRU eviction (max 100 sessions, 5000 events per session) - Truncates large event payloads (tool results, file content, thinking blocks) to bound memory - Applies WebSocket backpressure on browser connections (drops messages when send buffer > 4MB) - Manages sessions in a pure in-memory registry (populated from bridge connections and direct disk discovery) - Persists global preferences (pinned directories, session order) in `~/.pi/dashboard/preferences.json` - Discovers historical sessions directly from disk via `SessionManager.list()` (DirectoryService) - Loads session events on demand directly from disk via `SessionManager.open()` (DirectoryService) - Polls OpenSpec CLI per directory every 30s, broadcasting changes to browsers (DirectoryService). - **Design-artifact override**: After receiving the CLI's per-change `status`, `buildOpenSpecData` post-processes the `design` artifact: when CLI says `design: ready`, the dashboard checks local file-system evidence (R1: `^design.*\.md$` present; R2: `design/*.md` present; R3: `tasks.md` contains a Markdown checkbox) and promotes `design.status` to `"done"` if any rule fires. The override is **promote-only and design-only** — never demotes, never touches other artifact ids, never promotes from `"blocked"`. Change-level `isComplete` is re-derived locally; CLI `isComplete: true` is never demoted. The same R1/R2/R3 rules are mirrored in `.pi/skills/openspec-shared/scripts/effective-status.sh` so OpenSpec workflow skills and dashboard session-card buttons cannot disagree about a change's next-ready artifact. See change: fix-openspec-design-detection. - Serves the built web client as static files (production) or proxies to Vite dev server (dev mode) - Writes per-session `.meta.json` sidecar files with dashboard state and cached stats - Exposes REST API for session management, event content fetch, pinned directories, and file reading - Provides session control REST endpoints (`/api/session/:id/*`) wrapping WebSocket-only operations (prompt, abort, spawn, resume, rename, hide, flow-control, model, thinking-level, attach/detach-proposal) — see `src/server/session-api.ts` **Server decomposition:** The server is split into focused modules: - `server.ts` — Orchestrator: creates services, composes modules, manages lifecycle - `routes/` — REST API routes grouped by domain (session, git, file, openspec, system) - `event-wiring.ts` — Pi gateway → browser gateway event forwarding - `idle-timer.ts` — Auto-shutdown idle timer - `session-bootstrap.ts` — Startup session discovery and OpenSpec polling init - `extension-register.ts` — Auto-registers bundled bridge extension in pi's global settings (`~/.pi/agent/settings.json`) on startup; no-op in dev mode - `browser-handlers/` — Browser WebSocket message handlers by domain (subscription, session-actions, session-meta, terminal, directory) ### 3. Web Client (`src/client/`) A React-based responsive web UI that: - Shows all active sessions organized by directory, with pinned directories always visible at the top - Renders chat messages with markdown, syntax highlighting, streaming, and a small raw-HTML pass that strips React-only `ref` attributes before render - Persists scroll position per session — switching sessions restores exact scroll position if locked, or scrolls to bottom if following - Displays collapsed tool call steps with lazy-loaded content and elapsed time badges - Shows live ticking elapsed counters on running operations (thinking, tool calls) and final duration on completed ones - Provides command autocomplete with `/` prefix - Supports bidirectional interaction (send prompts, run commands) - Works on mobile with responsive layout and swipe gestures - Shows an onboarding `LandingPage` whenever the main pane is empty, narrating the three steps needed to go from install → first running session (Setup credentials → Add folder → Start session). Each step is a card in **pending**, **done**, or **locked** state, derived purely from client state: `useProvidersReady()` (from `GET /api/providers`), `pinnedDirectories.length`, and `sessions.size`. Satisfied steps collapse to single-line ✔ rows, so returning users see a compact status strip rather than a full onboarding wall. The `PinDirectoryDialog` used by Step ② is mounted once at the app root in `App.tsx` and shared with the sidebar "Add folder" button via a single `onOpenPinDialog` callback. ### 4. Shared Types (`src/shared/`) TypeScript type definitions shared across all components: - `protocol.ts` - Extension↔Server WebSocket messages - `browser-protocol.ts` - Server↔Browser WebSocket messages (includes PromptBus messages: `prompt_request`, `prompt_dismiss`, `prompt_cancel`) - `types.ts` - Data models (Session, Workspace, Event, etc.) ## Data Flow ### Event Flow (pi → browser) 1. Pi emits event (e.g., `message_update`) 2. Bridge extension converts to `event_forward` protocol message 3. Server receives, stores in in-memory buffer, assigns sequence number 4. Server broadcasts to all subscribed browsers via `event` message 5. Browser's event reducer processes event, React renders update **Last-activity stamping** (change: session-card-last-activity-badge): inside step 3, before any other event-derived updates, the server checks `isActivityEvent(eventType)` against a curated allowlist (`prompt_send`, `message_*`, `turn_end`, `tool_execution_*`, `agent_*`, `bash_output`, `flow_*`, `architect_*`). On a match — and only when the session is NOT in replay — it stamps `session.lastActivityAt = Date.now()`. The in-memory write is unconditional; the `session_updated` broadcast is throttled to **at most one per 30 s per session** via `lastActivityBroadcastAt: Map`. The map entry is dropped on `session_unregister` so a fast re-register cannot lose its first broadcast. Heartbeat / metrics / UI-state events (`process_metrics`, `git_info_update`, `model_select`, `ui_data_list`, `ext_ui_decorator`, …) are excluded so an idle pi process emitting periodic metrics does not keep the badge artificially fresh. At server boot, `session-scanner.ts` cold-start-seeds `lastActivityAt` from the `events.jsonl` file mtime so existing idle sessions retain a meaningful relative-time label across restarts. The client's `selectBadgeTimestamp(session)` (in `packages/client/src/lib/session-card-time.ts`) renders `endedAt ?? lastActivityAt ?? startedAt` for ended sessions and `lastActivityAt ?? startedAt` for active ones. **Unread state machine** (change: session-card-unread-stripes): every session carries a `unread: boolean` field that flips to `true` when an attention-worthy event fires while no browser has the session displayed, and clears to `false` when any browser opens the session. The visual is cyan scrolling stripes (`card-unread-pulse`, Tailwind `cyan-400`) on the session card, lower priority than the yellow streaming and purple ask_user pulses. - **Triggers** (evaluated by the pure helper `isUnreadTrigger(eventType, before, after, payload)` in `event-status-extraction.ts`): 1. Session status transitions from `streaming` to `idle` or `active` — a turn finished. 2. Session's `currentTool` becomes `"ask_user"` — input is requested. 3. An `agent_end` event arrives with a truthy `payload.error` — something broke. Other events (assistant `message_end`, tool execution start/end, model/git/metrics noise) deliberately do NOT trigger unread — they would be too noisy on long turns. - **"Currently viewing" registry**: `viewed-session-tracker.ts` exposes `Map>`. Browsers populate it via two new browser→server messages, `session_view` and `session_unview`, sent by the client hook `useViewDispatcher` (mounted in `App.tsx`). The hook watches the `/session/:id` route and the WebSocket connection status; on every transition INTO `connected` it re-sends `session_view` for the current id so server-side state re-syncs after reconnect. On WS `close`, the gateway calls `tracker.unviewAll(ws)` so disconnected browsers cannot hold sessions in the viewed state. Read state is GLOBAL across browsers (mirrors mail/Slack: opening on phone clears unread on laptop). - **State transitions** in `event-wiring.ts`: right after the `extractSessionUpdates` block, the wiring snapshots `{status, currentTool}` before/after the update and calls `isUnreadTrigger`. If true AND `viewedSessionTracker.isViewedByAnyone(sessionId) === false` AND `!replayingSessions.has(sessionId)`, the wiring stamps `session.unread = true` and broadcasts `session_updated`. The browser-gateway's `session_view` arm clears the bit (`unread: false`) and broadcasts. The clear-on-already-read path is a no-op (no spurious broadcast). - **Persistence**: the bit lives in `.meta.json` (`SessionMeta.unread`). `server.ts onChange` writes it on every session update; `session-scanner.ts::sessionFromMeta` restores it on cold start. The cold-start "force `status = ended`" override at `server.ts:273-279` is intentionally non-destructive on `unread` — a session that was unread when the server stopped is still unread when it starts back up, even before its bridge reattaches. - **Render precedence** (`SessionCard.tsx::getCardPulseClass`): `ask_user` (purple) > `streaming || resuming` (yellow) > `unread` (cyan) > none. Streaming with `unread: true` shows yellow stripes; when streaming ends with the session still unviewed, the trigger fires, the card flips to cyan. The `card-unread-pulse` CSS class reuses the `card-working-stripes-scroll` and `card-working-opacity-pulse` keyframes verbatim — only the stripe and tint colors change to cool cyan (`rgba(34, 211, 238, 0.18)` and `rgba(34, 211, 238, 0.07)`). Cyan was selected to occupy its own corner of the dashboard palette (distant from yellow, purple, green, red). Reduced-motion users see a static cyan-tinted background, matching the working-pulse arm. ### Interactive UI Flow (PromptBus — extension dialog → browser → response) 1. Extension calls `ctx.ui.confirm()` / `select()` / `input()` / `editor()` / bridge-patched `multiselect()` 2. Bridge PromptBus intercepts via patched `ctx.ui` methods, creates a `PromptRequest` with a unique `promptId` and `pipeline` tag (e.g. `"command"`, `"architect"`) 3. Registered adapters claim the prompt: - `DashboardDefaultAdapter` (always registered) returns a `PromptClaim` with `component: { type: "generic-dialog", props }` and `placement: "inline"` - Custom adapters (e.g. `ArchitectUIAdapter` from pi-flows) can claim with custom component types and widget-bar placement - TUI adapters (registered via `prompt:register-adapter` event) can claim to show a terminal dialog 4. Bus sends `prompt_request` to server with the winning adapter's component info 5. Server forwards to subscribed browsers 6. Browser's `prompt-component-registry.ts` resolves the component type to a React renderer and placement 7. User responds in browser → `prompt_response` sent to server → routed to bridge 8. Bus resolves the original dialog promise and calls `onResponse()` on all adapters for cleanup **Multiselect note:** pi's upstream `ExtensionUIContext` has no native `multiselect` method, so the bridge attaches `ctx.ui.multiselect` during `session_start`. `ask_user` dispatches multiselect through `polyfillMultiselect`, which delegates to that patched PromptBus method when present and falls back to `ctx.ui.custom` + `MultiSelectList` for legacy / non-bridge contexts (the fallback is a no-op in pi 0.70 RPC mode — dashboard headless — because pi-coding-agent defines `custom` as `async () => undefined` there). The bridge intentionally registers NO TUI adapter arm for multiselect; routing is bus-only. Browser responses encode `{ values: string[] }` as `JSON.stringify(values)` in `prompt_response.answer`, preserving `[]` as a real empty selection distinct from cancellation. **First-response-wins (multi-adapter):** - Multiple adapters can claim the same prompt (e.g. TUI + dashboard) - The first adapter to respond wins; the bus sends `prompt_dismiss` to the server for the losing adapter's dashboard component - Adapters implement `onCancel()` for cleanup when another adapter wins **Custom UI components:** - Extensions register adapters via `pi.events.emit("prompt:register-adapter", adapter)` - Adapters return custom `PromptClaim` with arbitrary component types (e.g. `"architect-prompt"`) - Client-side registry maps type strings to render placement; unknown types fall back to `"generic-dialog"` **Message passthrough:** - The `message` field from `ask_user` tool (and other `ctx.ui` callers) is forwarded via `metadata.message` in the PromptBus request, through the `prompt_request` protocol message, and extracted by the client into the interactive renderer's `params.message`. **Type safety:** - `prompt_request`, `prompt_dismiss`, and `prompt_cancel` **must** be in the `ServerToBrowserMessage` union in `browser-protocol.ts`. If they are only handled via `case "..." as any:` in switch statements, esbuild's dead-code elimination will strip the handlers in production builds, silently breaking the interactive UI. **Resilience:** - **Page refresh**: Server replays pending `prompt_request` messages when a browser subscribes. Client deduplicates by `requestId` or pending title match. - **Bridge reconnect**: Bridge replays pending PromptBus requests on WebSocket reconnect so dashboard dialogs survive server restarts. ### Command Flow (browser → pi) 1. User types prompt or command in browser 2. Browser sends `send_prompt` via WebSocket 3. Server routes to correct bridge extension by sessionId 4. Bridge extension's command handler parses input for pi command prefixes: - `!!` → silent bash execution via `pi.exec()`, result as `bash_output` event - `!` → bash execution via `pi.exec()`, result as `bash_output` event + send to LLM - `/compact [instructions]` → `ctx.compact()`, feedback as `command_feedback` event - `/` → `session.prompt()` for extension commands/skills/templates (fallback to `sendUserMessage()`) - Colon-to-hyphen aliasing: `/opsx:continue` resolves to `opsx-continue.md` template (both `:` and `-` forms work) - Plain text → `pi.sendUserMessage()` (default) 5. Pi processes the command, events flow back via event flow ### Flow Dashboard Data Flow (pi-flows → browser) pi-flows runs multi-agent workflows in-process. Subagent sessions use `SessionManager.inMemory()` and don't bootstrap the bridge, so flow data must be explicitly forwarded by the parent session's bridge. 1. pi-flows `EventEmitObserver` emits `flow:*` events on `pi.events` (all 10 `FlowObserver` callbacks) 2. Bridge extension listens to `flow:*` events and forwards as `event_forward` messages with `flow_*` event types 3. Server stores events, extracts flow metadata to `DashboardSession` fields (`activeFlowName`, `flowAgentsDone`, `flowAgentsTotal`, `flowStatus`) 4. Browser event reducer builds client-side `FlowState` (agents map, tool history, detail entries) — reducer code lives in `packages/flows-plugin/src/flow-reducer.ts` (re-exported via `@blackbelt-technology/pi-dashboard-flows-plugin/reducer`); `event-reducer.ts` imports `isFlowEvent` + `reduceFlowEvent` from there. 5. React renders `FlowDashboard` (sticky card grid above ChatView), `FlowAgentDetail` (replaces chat), `FlowSummary` (post-completion). Component code lives in `packages/flows-plugin/src/client/` and is imported by the shell via `@blackbelt-technology/pi-dashboard-flows-plugin/client`. Slot-consumer-based mounting is tracked as the follow-up change `migrate-flows-jsx-to-slots`; the current shell imports the components directly. See change: extract-flows-as-plugin. **Flow controls (browser → pi-flows):** - Abort: browser sends `flow_control { action: "abort" }` → server → bridge → `pi.events.emit("flow:abort")` → `flowManager.abort()` - Autonomous toggle: browser sends `flow_control { action: "toggle_autonomous" }` → same path → `setAutonomousMode()` ### Extension UI System (Phases 1 + 2 shipped) A generalized mechanism for extensions to declare dashboard UIs as data without authoring React or importing a runtime SDK. Phase 1 (`management-modal` slot) shipped in change `add-extension-ui-modal`. Phase 2 (live in-page decorations) shipped in change `add-extension-ui-decorations`. Phase 4 RJSF is tracked in `add-extension-ui-rjsf-form`. **Mechanism (pull-based discovery, synchronous probe):** ```mermaid sequenceDiagram participant Ext as Extension (e.g. pi-judo) participant Bridge as Bridge (pi process) participant Server as Dashboard Server participant Browser as Dashboard Browser Note over Bridge: session_start (reason ∈ {new,fork,resume}) Bridge->>Ext: pi.events.emit("ui:list-modules", probe) Ext-->>Bridge: probe.modules.push({ kind, id, command, view, … }) Bridge->>Server: ui_modules_list { sessionId, modules } Server->>Browser: ui_modules_list (cache + forward) Note over Browser: user types /judo:status Browser->>Server: ui_management { action: "list", event: "judo:status-rows" } Server->>Bridge: ui_management Bridge->>Ext: pi.events.emit("judo:status-rows", { action, _reply }) Ext-->>Bridge: data.items = […] Bridge->>Server: ui_data_list { sessionId, event, items } Server->>Browser: ui_data_list (cache + forward) Note over Ext: state changes Ext->>Bridge: pi.events.emit("ui:invalidate", { id }) Bridge->>Ext: pi.events.emit("ui:list-modules", probe) Bridge->>Server: ui_modules_list (refreshed) Server->>Browser: ui_modules_list ``` Key properties: 1. The probe is **synchronous** — listeners push into `probe.modules` while `pi.events.emit` is running. The bridge never polls and never caches across probes; idempotent re-registration just produces a fresh probe on the next trigger. 2. **No SDK package** — extensions only need `pi.events` (already provided by the host). Schema types live in `@blackbelt-technology/pi-dashboard-shared`. 3. **Last-write-wins on duplicate `id`** within a single probe; bridge logs one warning per collision. **Phase-1 surface (shipped):** - `kind: "management-modal"` — slash-command-triggered modal. - `view.kind` ∈ `"table" | "grid" | "form"`. - `UiField.kind` ∈ `"text" | "number" | "boolean" | "select" | "code" | "datetime" | "textarea"`. - `UiAction.confirm` polish via the existing Tailwind `ConfirmDialog` (no `window.confirm()`). - Icons resolved against `@mdi/js` keys; unknown keys render no icon (no error). - Slash-command interception in `App.tsx`'s `wrappedHandleSend`; built-in collisions (`/model`, `/compact`, `/flows`, etc.) drop the module with a `console.warn`. - "Modules" entry point in `SessionHeader` shows when `session.uiModules?.length > 0`. **Phase-1 wire protocol:** | Direction | Type | Purpose | |---|---|---| | extension → server → browser | `ui_modules_list { sessionId, modules }` | Cached schemas. | | extension → server → browser | `ui_data_list { sessionId, event, items }` | Row data for `table`/`grid` views. | | browser → server → extension | `ui_management { sessionId, action, event, params }` | Data fetch (`action: "list"`) or user action. | **Replay on reconnect:** Server caches `Session.uiModules` and `Session.uiDataMap` (per-event item cap = 1000, last-write-wins on overflow). The replay site is `replayUiState(ws, sessionId, ctx)` in `packages/server/src/browser-handlers/subscription-handler.ts`, called immediately after every existing `replayPendingUiRequests(ws, sessionId)` site (4 sites: stale-lastSeq full replay, delta replay, no-events path, lazy load from disk). Replay ordering: events → pending UI requests → UI module state. **Phase-2 surface (shipped):** Five live in-page decoration kinds reuse the same `ui:list-modules` probe primitive. Decorators carry an explicit `namespace: string` (must match `/^[a-z0-9-]+$/`) plus `id`, partitioned at the bridge and forwarded as one `ext_ui_decorator` message per descriptor. Server caches under `Session.uiDecorators[`${kind}:${namespace}:${id}`]` and replays after the Phase-1 batches. | Kind | Mount site | Filter | Closure? | |---|---|---|---| | `footer-segment` | `SessionHeader.tsx`, right of git/model info | `kind === "footer-segment"` | Yes — extension supplies fresh `payload.text` per probe | | `agent-metric` | Inside `FlowAgentCard.tsx` (one per card) | `kind === "agent-metric" && payload.agentId === card.agentName` | Yes | | `breadcrumb` | Top of `FlowDashboard.tsx` | `kind === "breadcrumb"` (most recent wins) | No (snapshot) | | `gate` | Inline in each `FlowLaunchDialog` | `kind === "gate" && payload.flowId === item.flowId` (most-restrictive aggregate) | No | | `toast` | `App.tsx` (top-right fixed tray) | `kind === "toast"` (stacks; auto-dismiss; FIFO display cap = 5) | No | Decorator removal is **explicit**: extensions push a descriptor with `removed: true` and the bridge forwards it verbatim; the server deletes the cache entry under the matching key (no-op if absent) and broadcasts the removal so client slots can unmount the matching descriptor without affecting siblings. **Phase-2 wire protocol:** | Direction | Type | Purpose | |---|---|---| | extension → server → browser | `ext_ui_decorator { sessionId, descriptor, removed? }` | Live decoration upsert (or removal when `removed: true`). | The message is a discriminated union over `descriptor.kind`. `ExtUiDecoratorMessage` is a member of both `ExtensionToServerMessage` and `ServerToBrowserMessage` (verified by a type-level test in `packages/shared/src/__tests__/browser-protocol-types.test.ts` — esbuild silently strips switch arms whose message types are not in the production union). **Phase-2 sequence (invalidate → probe → ext_ui_decorator → slot re-render):** ```mermaid sequenceDiagram participant Ext as Extension (e.g. pi-judo) participant Bridge as Bridge (pi process) participant Server as Dashboard Server participant Browser as Dashboard Browser Note over Ext: state changes (e.g. judo workspace mutation count incremented) Ext->>Bridge: pi.events.emit("ui:invalidate", { id }) Bridge->>Ext: pi.events.emit("ui:list-modules", probe) Ext-->>Bridge: probe.modules.push({ kind: "footer-segment", namespace, id, payload }) Note over Bridge: partition by kind — modal kinds → ui_modules_list,
decorator kinds → one ext_ui_decorator each Bridge->>Server: ext_ui_decorator { sessionId, descriptor } Server->>Server: cache under `${kind}:${namespace}:${id}` on Session.uiDecorators Server->>Browser: ext_ui_decorator (broadcast verbatim) Browser->>Browser: per-kind slot component re-renders Note over Ext: state cleared Ext->>Bridge: probe.modules.push({ kind, namespace, id, payload, removed: true }) Bridge->>Server: ext_ui_decorator { ..., removed: true } Server->>Server: delete cache entry; broadcast removal Server->>Browser: ext_ui_decorator { ..., removed: true } Browser->>Browser: slot unmounts the matching descriptor only ``` **Rate cap:** to prevent runaway extensions, the bridge throttles `ui:invalidate` re-probes per session to one probe every 50 ms (= 20/sec). Excess events coalesce into a single trailing-edge probe; a single warning is emitted per offending burst, latched until a quiet window passes. **Replay ordering** (extended from Phase 1): events → pending UI requests → `ui_modules_list` → `ui_data_list` (per event) → `ext_ui_decorator` (per cache key). Replay decorator messages never carry `removed: true` — only live entries are replayed. **Phase 4 (optional):** `rjsf-form` JSON-Schema escape hatch for rich forms; see `add-extension-ui-rjsf-form`. **Relationship to existing capabilities:** - `interactive-ui-dialogs` / `ui-proxy` / PromptBus — handle one-shot `ctx.ui.*` dialogs (request/response, awaited). The extension-ui-system handles persistent push-based descriptors (no awaiting). Orthogonal mechanisms; both ship. - `extension-ui-forwarding` (catch-all `pi.events.emit` forwarding) — kept for arbitrary extension events; the new system is the *declarative* path for UI specifically. - pi-flows: in Phase 3 pi-flows itself adopts the system to surface registered workflows (breadcrumb), gates, and cards (agent-metric) for any flow-using extension automatically. **No-dashboard fallback:** When no bridge is connected, `ui:list-modules` is never emitted; extension listeners are dormant; slash commands fall back to existing text-output behavior. Extensions remain pi-runnable in pure-pi mode without code changes. ### Plugin Architecture (runtime implemented in `add-dashboard-shell-slots-runtime`) A planned **two-tier rendering model** that lets first-party features (OpenSpec, pi-flows, pi-subagents tool renderers, git integration) live as standalone plugin packages instead of being baked into the dashboard core. Tracked under OpenSpec change `dashboard-plugin-architecture` (design-only umbrella); the runtime lands in `add-dashboard-shell-slots-runtime`; concrete migrations land in `extract-openspec-as-plugin`, `extract-flows-as-plugin`, `extract-subagents-as-plugin`, and `extract-git-as-plugin`. **The two tiers, one slot contract:** - **Tier 1 — first-party plugins** (this proposal): React + server contributions co-located in `packages/-plugin/`. Bundled and tree-shaken into the dashboard's web build. Trusted because they live in the same repo and pass the same review. - **Tier 2 — third-party extensions** (`extension-ui-system`): descriptor-only protocol over the existing pi event bus. Sandboxed, declarative, no React. Both tiers fill the **same** named regions — the **slot taxonomy**. The shell knows about slots; only plugins/extensions know about specific features. **Slot taxonomy (frozen for v0.x):** First-party slots (React, possibly also descriptor): - `sidebar-folder-section` — collapsible block above the per-workspace session list (replaces `FolderOpenSpecSection`). - `session-card-badge` — compact info chips in the session card (replaces `OpenSpecActivityBadge`, `FlowActivityBadge`). Descriptor variant reuses `agent-metric`. - `session-card-action-bar` — action buttons in the session card (replaces `SessionOpenSpecActions`, `SessionFlowActions`). React-only in v0.x. - `content-view` — full-screen content area (replaces every conditional branch in `App.tsx` for `ArchiveBrowserView`, `SpecsBrowserView`, `OpenSpecPreview`, `FlowAgentDetail`, `FlowArchitectDetail`, `MarkdownPreviewView`, `FileDiffView`, `FlowYamlPreview`). Descriptor variant reuses `management-modal`. - `content-header-sticky` — sticky element above content-view (replaces sticky `FlowArchitect`/`FlowDashboard`). Descriptor variant reuses `breadcrumb`. - `content-inline-footer` — inline element below content-view (replaces `FlowSummary`). React-only. - `anchored-popover` — popover anchored to a triggering UI element (replaces `TasksPopover`). - `command-route` — maps a slash command or URL route to a `content-view` (replaces today's hand-wired routing in `App.tsx`). - `settings-section` — a section in the Settings page (replaces today's hardcoded `Background polling (OpenSpec)` section). React for first-party plugins; descriptor (RJSF/UiField) for third-party extensions. - `tool-renderer` — React component for a specific `tool_call` by `toolName` (replaces today's hardcoded `tool-renderers/registry.ts`). Descriptor-only slots (existing in `extension-ui-system`): `management-modal`, `footer-segment`, `agent-metric`, `breadcrumb`, `gate`, `toast`, `rjsf-form`. **Plugin loader (runtime):** `packages/dashboard-plugin-runtime/` is a new workspace package containing all runtime pieces: - **`src/slot-registry.ts`** — `createSlotRegistry()` returns a typed `Map` sorted by `(priority, pluginId)`. Filter helpers: `forSession`, `forFolder`, `forTab`, `forCommand`, `forToolName`. - **`src/manifest-validator.ts`** — hand-rolled manifest validator; throws `ManifestValidationError` with `pluginId` and `reason`. - **`src/plugin-context.tsx`** — `PluginContextProvider` wraps the entire app. A nested `CurrentPluginLayer` is pushed per contribution so `usePluginConfig()` and `logger` resolve to the contributing plugin's id. `applyPluginConfigUpdate` updates the in-memory config store and re-renders subscribers. - **`src/slot-consumers.tsx`** — one component per slot id. Each wraps contributions in a `SlotErrorBoundary` (per-claim scope). Reads registry from the provider. - **`src/slot-error-boundary.tsx`** — React error boundary scoped to one claim. Logs with plugin id and slot id; renders nothing for the failing claim without suppressing siblings. - **`src/vite-plugin/index.ts`** — `viteDashboardPluginsPlugin` generates `packages/client/src/generated/plugin-registry.tsx` with named imports (tree-shaking). Watches manifests during dev and triggers HMR. - **`src/server/loader.ts`** — `discoverPlugins(repoRoot?)` (single module-level cache), `loadServerEntries(deps)` (per-plugin dynamic-import, failure isolated), `getPluginStatusStore()`. - **`src/server/server-context.ts`** — `createServerPluginContext(deps, pluginId)` — namespaced logger, typed config accessors. - **`src/server/config-validator.ts`** — Ajv JSON-Schema 7 validate + defaults. 1. **Discovery** — server globs `packages/*/package.json` on startup, parses the `pi-dashboard-plugin` field, validates against schema, sorts by `priority` (lower first; first-party = 100; default 1000). 2. **Server load** — dynamic-imports each plugin's `server` entry, invokes `registerPlugin(ctx)` with a typed `ServerPluginContext` (Fastify, session manager, event store, broadcast helper, scoped logger). 3. **Client bundle** — a Vite plugin (`vite-plugin-dashboard-plugins`) generates `packages/client/src/generated/plugin-registry.tsx` with static imports per plugin manifest; Vite tree-shakes unused exports and code-splits per plugin. 4. **Runtime registration** — client boot calls `getSlotRegistry()` once; slot consumer components (``, ``, etc.) iterate the registry and render contributions in priority order with per-slot error boundaries. 5. **Bridge auto-register** — plugins declaring a `bridge` entry are auto-registered into `~/.pi/agent/settings.json` under managed `dashboard-` keys; user-owned entries are never touched. **Plugin settings persistence:** - All plugin settings live under `plugins..*` in `~/.pi/dashboard/config.json`. The dashboard core never reads or writes another plugin's namespace. - Each manifest may declare a `configSchema` (JSON Schema 7); the loader validates on read (with defaults applied) and on write (rejects invalid). - `POST /api/config/plugins/:id` accepts a partial config for a single plugin and broadcasts `plugin_config_update { id, config }` to all subscribed browsers. - The client-side `pluginContext.usePluginConfig()` hook is reactive — consumers re-render within one frame of a write. - Legacy top-level keys (e.g. `openspec.*`) auto-migrate to `plugins..*` on the plugin's first server boot. **Failure isolation:** - A plugin failing to load (server throw, client import error, missing entry) does NOT crash the shell. - Failures are logged with full context and surfaced via `/api/health.plugins[]` (`{ id, enabled, loaded, error?, claims }`). - Slot consumers wrap each contribution in a React error boundary so a runtime crash in one plugin's component doesn't take down the page. **Bundled-by-default plugins:** The plugin loader treats all plugins identically (same manifest, same discovery, same `enabled` flag, same failure isolation). What distinguishes "bundled-by-default" plugins (initial set: `git-plugin`) is purely operational — the build pipeline always includes them in `packages/`. Their absence is a deliberate user opt-out, not a normal state. OpenSpec, Flows, and Subagents plugins are bundled in standard builds but their absence is a normal use case (e.g. a workspace without OpenSpec). **Future Work — external plugin discovery:** Phase 1 scans `packages/*/package.json` only. The manifest format (`pi-dashboard-plugin` field in any `package.json`) is intentionally **format-compatible with arbitrary npm packages**, which unblocks an eventual progression where stable plugins can be PR'd into upstream packages (e.g. `@tintinweb/pi-subagents/dashboard/`) and discovered from `node_modules`. The deferred work (trust model, SemVer pinning of the plugin context API, build integration with `node_modules` paths) is documented in `dashboard-plugin-architecture/design.md` §"Future Work: external plugin discovery". #### JSX slot wrappers and `??` fallback chains — anti-pattern Slot consumer components (``, ``, etc.) return `null` when no plugin claims the slot. **They MUST NOT be placed directly as the left operand of a `??` operator** in JSX route fallback chains. The `??` operator evaluates the JSX *element* (always truthy), not its rendered output, so a fallback like ```tsx // BROKEN — sessionDetail and LandingPage are unreachable ?? sessionDetail ?? ``` renders nothing visible whenever zero plugins claim `content-view` (the slot's `null` return is masked by `??`'s value-based semantics). The bug is silent and ships fine in CI when fixture plugins are bundled — but breaks every user the moment fixtures are excluded from production. The fix gates the JSX element on a registry claim count *before* construction: ```tsx // CORRECT — ?? falls through to sessionDetail when claimCount === 0 (claimCount > 0 ? : null) ?? sessionDetail ?? ``` A repository-level lint (`packages/client/src/__tests__/no-jsx-slot-nullish-fallback.test.ts`) scans the dashboard shell entry points for the anti-pattern and fails CI with the offending file:line. The lint is enforced for `packages/client/src/App.tsx` today; downstream changes that wire new slot consumers (`extract-flows-as-plugin`, `extract-openspec-as-plugin`, `extract-subagents-as-plugin`, `extract-git-as-plugin`) MUST add their shell file to the lint's `SCAN_FILES` allowlist. See change `fix-slot-fallback-masks-content` for the rationale, regression test, and the exact production bug shape (encountered during deployment of `add-extension-ui-decorations`). ### Bootstrap & First Run The dashboard has three install paths that all converge on the shared `bootstrapInstall` in `packages/shared/src/bootstrap-install.ts`: 1. **Electron wizard** (first-run in the desktop app) — `packages/electron/src/lib/dependency-installer.ts installStandalone` wraps the shared installer with Electron-specific concerns (bundled Node + `npm-cli.js`, offline npm cacache bundle extracted from `resourcesPath/offline-packages/`, bundled-extension activation into pi's git cache). The registry-install loop itself is the shared function. 2. **`pi-dashboard` CLI first-run** (degraded-mode) — when `pi-dashboard` (or `pi-dashboard start`) launches and `ToolRegistry.resolve("pi")` fails, `cli.ts runDegradedModeBootstrap` flips `bootstrapState.status` to `"installing"`, kicks off `bootstrapInstall({ packages: ["@mariozechner/pi-coding-agent", "@fission-ai/openspec", "tsx"] })` asynchronously, and returns immediately so the server's `fastify.listen` remains responsive. The UI renders `BootstrapBanner` above the main layout. `session-api.ts gateOrEnqueue` queues `POST /api/session/spawn` requests while installing; the `server.ts` subscribe hook flushes the queue on transition to `"ready"`. On success, `registerBridgeExtension(findBundledExtension())` auto-wires the bridge so no manual step is required. 3. **`pi-dashboard upgrade-pi` CLI subcommand** — runs `bootstrapInstall({ packages: ["@mariozechner/pi-coding-agent"] })` either directly (when no dashboard is listening) or via `POST /api/bootstrap/upgrade-pi` (when one is). The REST path flips state through the existing broadcast hook so open dashboard tabs see the progress; on completion, `/reload` is broadcast to all connected bridges, matching the pi-core-update session-reload pattern. Compatibility skew is checked on every ready transition via `updateBootstrapCompatibility` which reads `piCompatibility` from `packages/server/package.json` and populates `bootstrapState.compatibility` with `upgradeRecommended` / `upgradeDashboard` flags consumed by `BootstrapBanner`. Versions below `minimum` set a blocking `error` message that `session-api gateOrEnqueue` translates to 503 responses. The pinned range is `minimum: "0.70.0"`, `recommended: "0.70.0"`, `maximum: null` — deliberately in lockstep. The dashboard does NOT carry backward-compatibility shims for older pi releases; one supported pi means no conditional code paths in the bridge and no dual-import fallbacks (e.g. `@sinclair/typebox` vs `typebox`). Bumping `recommended` in a future change SHOULD be matched by an equal bump to `minimum` and a lockstep bump of the offline-bundled pi version in `packages/electron/offline-packages.json`. The CLI also surfaces skew on stderr at startup: `cli.ts::logCompatibilityWarning` emits a three-line red block on below-minimum (including the exact `pi-dashboard upgrade-pi` remediation command) and a single advisory line on below-recommended. Silent when in range. This is in addition to the browser banner and the 503 gating, so terminal-only users (headless servers, CI) don't miss the signal. Note: `readCurrentPiVersion` uses `fs.realpathSync` on the registry-resolved bin path so the common npm-global symlink layout (`~/.nvm/.../bin/pi` → `../lib/node_modules/@mariozechner/pi-coding-agent/dist/cli.js`) resolves to the real `package.json` — without this, `compatibility.current` was silently `undefined` in every response. #### Post-install repair (centralized hook) On every `bootstrapState` transition from `"installing"` to `"ready"`, `server.ts`'s subscribe callback runs a one-shot repair phase via the exported helpers `makeBootstrapTransitionHandler` (gating) and `runPostInstallRepair` (the work): 1. **Full `ToolRegistry.rescan()` (no arg)** — every cached `Resolution` is dropped so the next `resolve()` call re-runs the entire strategy chain against the post-install filesystem. Restores the literal contract from `unified-bootstrap-install` task 4.3 ("registry rescan") that was previously narrowed to `rescan("pi")` and left `openspec` / `tsx` cached as `not-found` forever. 2. **Force-refresh OpenSpec for every known directory** — iterates `directoryService.knownDirectories()` and for each cwd calls `refreshOpenSpec(cwd)` (bypasses the mtime gate per the `fix-openspec-mtime-gate-toctou` design's escape-hatch contract). Compares the returned `OpenSpecData` against the prior cache; emits `openspec_update` to all browsers when the prior was empty or the payload differs. Per-cwd failures are isolated via try/catch so one cwd cannot block the others. Concurrency is bounded by the existing `OpenSpecPollConfig.maxConcurrentSpawns` semaphore inside `directory-service.ts` (default 4). 3. **Force-refresh pi-resources for every known directory** — same iteration; silent on failure (matches `directory-service.ts::schedulePiResourcesTick`). The hook fires once per transition, fire-and-forget so the subscribe callback returns synchronously. Because all three install entry points (`runDegradedModeBootstrap`, REST `triggerUpgradePi`, REST `triggerRetry`) flip the same state, the centralized hook covers every caller — the local `registry.rescan("pi")` block in `cli.ts` was removed as part of this change. Without this hook, the OpenSpec session-card buttons (`P/D/T/S` letters, attach combo, refresh) stayed hidden after a fresh first-run install until either the user manually reloaded or up to 30 s elapsed — and even then the mtime gate could decline to re-poll if no file actually changed since boot. See changes: `unified-bootstrap-install`, `pi-zero-seventy-compat`, `warn-pi-version-skew-in-cli`, `fix-openspec-buttons-after-bootstrap-install`. ### Force Kill Escalation The Stop button supports two-click escalation for stuck sessions: 1. **Click 1 (Abort)**: Sends `abort` → bridge → `ctx.abort()`. Button transitions to orange pulsing "Force Stop". 2. **Click 2 (Force Kill)**: Sends `force_kill` → server delegates termination to the **platform layer** (`packages/shared/src/platform/process.ts::killProcess(pid, { timeoutMs: 2000 })`), which: - on **Windows** runs `taskkill /F /T /PID ` (genuine tree kill — descendant `node.exe`, pi children, tmux panes, `wt` tabs, code-server subtrees all die together), - on **POSIX** sends `SIGTERM`, polls liveness every 200ms for up to 2s, then escalates to `SIGKILL` if the process is still alive. Session marked "ended" (not removed), resumable via fork/continue. The bridge includes `process.pid` in `session_register` so the server can kill the process. The server also force-closes the bridge WebSocket and uses the headless PID registry as a fallback. If no PID is available, only the WebSocket is closed. ### Platform-routed kill paths All process termination across the codebase goes through `packages/shared/src/platform/process.ts`. No code outside that module may call `process.kill(...)` directly — enforcement is handled by `packages/shared/src/__tests__/no-direct-process-kill.test.ts`, a repo-level lint that scans every `.ts` file under `packages/*/src/` and fails CI if a direct call slips in. The three canonical helpers are: | Helper | POSIX | Windows | |--------|-------|---------| | `isProcessAlive(pid)` | `kill(pid, 0)` | same | | `killProcess(pid, {timeoutMs})` | SIGTERM → wait → SIGKILL (tree via pgroup) | `taskkill /F /T /PID ` | | `killPidWithGroup(pid, sig)` | `kill(-pid, sig)` (process group) | `kill(pid, sig)` (leaf) | Sites routed through these helpers: `session-action-handler.ts::handleForceKill`, `process-scanner.ts::killProcessByPgid`, `tunnel.ts::cleanupStaleZrok` + `deleteTunnel`, `editor-manager.ts::stop`, `headless-pid-registry.ts`, `server-pid.ts`. See specs: [`command-executor`](../openspec/specs/command-executor/spec.md), [`force-kill-handler`](../openspec/specs/force-kill-handler/spec.md). `taskkill` is invoked via the platform's `execSync` wrapper (`platform/exec.ts`) so it inherits `windowsHide: true` — no console flash — and stays consistent with the `no-direct-child_process-import` invariant. Inline stop buttons also appear on running tool cards in `ToolCallStep`, providing contextual abort access right where the stuck command is visible. ### Repeated Tool Call Collapsing Consecutive tool calls with the same name and identical args (e.g. health check polling loops) are collapsed into a single expandable group showing a count badge (e.g. "×24"). Implemented via `groupConsecutiveToolCalls()` in the chat rendering pipeline. Groups require 3+ calls; running tools are never grouped. ### Edit Tool Diff Rendering (desktop vs mobile) `ToolCallStep` gates renderer mounting with `{expanded && }` — Edit cards default to collapsed, so no diff tokenization runs until the user expands. On expand, `EditToolRenderer` branches on `useMobile()` (the project-wide `width < 768px OR height < 600px` predicate): - **Desktop** (`!isMobile`): renders `` — syntax-highlighted via `@git-diff-view/react` + lowlight, matching `FileDiffView` quality; height capped for chat scroll UX. - **Mobile**: renders the homegrown CSS-colored unified patch (`createTwoFilesPatch` from `diff`, no syntax highlighting) — cheap and narrow-viewport-friendly. The shared `` component is also consumed by `DiffPanel` (Path A / change-derived diffs), centralising the `EXT_LANG_MAP`, `generateDiffFile` call, and `` prop set. See change: rich-diff-in-chat. **Fork decisions and subagent ask_user:** - Work through PromptBus — `TuiFlowIOAdapter` calls `ctx.ui.select/confirm/input` which the bridge routes through the bus to registered adapters (dashboard, TUI, or custom) **Flow launcher:** - Available flows detected from session commands list (heuristic: `source: "extension"`, excluding management commands) - Launch dispatched as `send_prompt` with `/ ` - Commands list auto-refreshed on `flow:rediscover` and `flow:complete` events **pi-flows local patches required** (upstream report prepared): - `EventEmitObserver`: 5 missing methods added (flow-started, agent-started, agent-complete, assistant-text, thinking-text) - `index.ts`: `flow:abort` and `flow:toggle-autonomous` event listeners added - `flow-tui.ts`: `autonomousMode` included in `flow:flow-started` event data ### `/reload` Flow (two code paths) Reload from the dashboard (via `npm run reload`, the reload button, or `/reload` typed into the chat composer) follows one of two paths depending on how the pi session was spawned. The server transparently selects the right path: ```mermaid flowchart TD A[Browser sends send_prompt text="/reload"] --> B[server handleSendPrompt] B --> C{shouldInterceptReload?
text === "/reload"
no images
headlessPidRegistry.getPid defined} C -->|Yes — headless session| D[handleHeadlessReload] D --> D1[Emit command_feedback 'started'] D1 --> D2[headlessPidRegistry.killBySessionId
SIGTERMs old pi] D2 --> D3[spawnPiSession with
sessionFile+mode:'continue'
strategy:'headless'] D3 --> D4[headlessPidRegistry.register new PID] D4 --> D5[Emit command_feedback 'completed'] D5 --> D6[New pi bridge re-registers
with same sessionId —
sessionManager preserves
tokens/cost/context/attachedProposal] C -->|No — tmux/wt/wsl-tmux| E[piGateway.sendToSession→bridge] E --> F[bridge command-handler parses /reload] F --> G[Calls globalThis-RELOAD_KEY fn] G --> H{Was /__dashboard_reload
typed in TUI first?} H -->|Yes| I[session.reload in-place] H -->|No| J[Error logged to bridge stderr
User must bootstrap via TUI] ``` **Why two paths?** pi-coding-agent's `ExtensionContext` (delivered to `session_start` handlers) has no `reload()` method — only `ExtensionCommandContext` (given to command handlers) does. The bridge works around this by registering `__dashboard_reload` as a command and capturing `ctx.reload` into `globalThis[RELOAD_KEY]` when a user first invokes it in pi's TUI. Headless sessions have no TUI, so the capture never happens. The server-side interception is a transparent kill-and-respawn that achieves the same user-visible outcome (fresh settings, fresh extensions, fresh skills/prompts/themes) without needing an in-process reload. Since `memorySessionManager.register` carries accumulated state when the same `sessionId` re-registers, the user sees a brief reconnect flicker but keeps their tokens, cost, context usage, and attached proposal. See change: headless-reload-via-respawn. ### Server Restart (single-orchestrator path) The dashboard previously had three independent restart paths (CLI in-process `cmdStop`+`cmdStart`, `POST /api/restart` orchestrator, bridge auto-start), and they raced each other on every restart: when the listening server died, every connected pi bridge fired `server-auto-start.ts` to spawn a replacement, racing whatever else was trying to bring the server back up. Symptoms ranged from "`pi-dashboard restart` left the server offline" (cmdStart's `isServerRunning` check returned true after a bridge won the race, so it silently early-returned without starting anything itself) to "Electron's restart respawned the server outside the Job Object" (the orchestrator-spawned new server is `detached: true`, severing Electron's lifecycle supervision). The `fix-restart-bridge-auto-start-race` change collapses the three paths into a single orchestrator path: 1. **CLI delegation** — `pi-dashboard restart` (`cmdRestart` in `cli.ts`) probes `isDashboardRunning(port)`. If up, POSTs `/api/restart` with `{dev}` and exits. If the dashboard is down or the HTTP call fails, falls back to local `cmdStop` + `cmdStart` (the offline-bootstrap case where there is no orchestrator to delegate to). This eliminates the in-process race, mirroring the existing `cmdUpgradePi` pattern. 2. **`server_restarting` broadcast** — before `process.exit(0)`, both `/api/restart` and `/api/shutdown` broadcast `server_restarting { reason, quiesceMs }` to every connected bridge via `piGateway.broadcast`. `quiesceMs` is 5000 for restart and 60000 for shutdown (longer because deliberate shutdown should not auto-resurrect for a minute). The broadcast is non-blocking and runs before the existing 100–200 ms `setTimeout(process.exit, ...)` deferral so the WS frame has time to flush. 3. **Bridge quiesce window** — on receipt of `server_restarting`, the bridge calls `connection.pauseAutoStart(quiesceMs)` (idempotent extend-only). `autoStartServer` consults `connection.shouldSuppressAutoStart()` and **skips only the `launchServer(...)` spawn step**; mDNS discovery + health-check probes still run, so the bridge picks up the orchestrator-spawned replacement as soon as it advertises. After the window expires, normal auto-start resumes (so a real server crash is still handled by the cold-start path). 4. **Explicit prior-daemon kill in the orchestrator** — `restart-helper.ts::buildOrchestratorScript` now reads `~/.pi/dashboard/dashboard.pid`, sends `SIGTERM` to the recorded PID, polls `kill(pid, 0)` for up to 3 s, then `SIGKILL` if still alive. The subsequent `portFree` poll deadline drops from 10 s to 5 s since step 0 already guarantees the previous server is dead. Older bridges that don't understand `server_restarting` ignore the message and fall back to today's behaviour — the CLI fix in step 1 already eliminates the worst-case path even for them. There is no flag day; the protocol message is additive on the `ServerToExtensionMessage` discriminated union. ### Auto-Resume on Prompt When a user sends a prompt to an ended session, the server automatically resumes it: 1. Server detects `send_prompt` for a session with `status === "ended"` and a valid `sessionFile` 2. Prompt is queued in `PendingResumeRegistry` (keyed by cwd, 30s expiry) 3. Session is set to `resuming: true`, card shows pulsing yellow dot + "Resuming…" 4. Server spawns `pi --session ` (continue mode) 5. `pi --session` reconnects with the same session ID — `session_register` sets status back to `"active"` 6. Server flushes queued prompt to the session and clears `resuming` flag 7. No navigation needed — user is already viewing the same session 8. On timeout (30s) or spawn failure, `resuming` flag is cleared and session returns to normal ended state 9. If user sends another prompt while already resuming, the queued prompt is updated without spawning a second process ### Sidebar session ordering: top-of-tier on status change The sidebar splits each folder's session cards into two tiers (alive on top, ended at the bottom). Cards within each tier sort independently: - **Alive tier** uses the persisted `sessionOrder` per cwd (drag-reorder, prepend on new spawn). On user-intent resume (Resume button, drag-to-resume, REST resume), the server calls `sessionOrderManager.moveToFront(cwd, sessionId)` so the just-resumed card surfaces at index 0 of the alive tier — even on repeated `end → resume → end → resume` cycles where the id might already be in the order list. **Bridge auto-reattach after a dashboard restart** is governed by the `reattachPlacement` config (`"always"` default / `"streaming-only"` / `"preserve"`): the bridge tags every `session_register` after its first call as `registerReason: "reattach"`, and `server.ts onChange` routes those into `reattach-placement.ts::applyReattachPolicy` to `moveToFront` according to policy. The `"preserve"` setting reproduces the legacy behavior of leaving order untouched. Registry intents (`pendingResumeIntents.consume()` returning `"front"` or `"keep"`) always override the reattach policy. See change: reattach-move-to-front. - **Ended tier** sorts by `(endedAt ?? startedAt)` descending, computed at render time inside `SessionList.renderGroup` (no persisted `endedSessionOrder` list — pure function of session timestamps). The most-recently-ended card surfaces at the top of the ended bucket regardless of cause (✕ shutdown, natural pi exit, force-kill). Legacy sessions without a recorded `endedAt` fall back to `startedAt` so pre-migration entries keep their previous ordering. Both halves share one mental model: "the session you just acted on appears at the top of its new tier." No protocol changes — the existing `sessions_reordered` broadcast carries the new order. See change `top-of-tier-on-status-change`. ### Desktop back-arrow priority chain The desktop session-header back button used to call `window.history.back()`, which was a silent no-op on cold loads / hard refreshes / deep links. It also ignored the eight content-area overlay states (archive browser, specs browser, flow YAML preview, diff view, pi resource file preview, README preview, pi resources state, OpenSpec preview) owned by `App.tsx`. The fix introduces: - **`packages/client/src/lib/desktop-back.ts`** — pure helper `selectDesktopBackTarget(state) → { kind: "clear", target } | { kind: "navigate", to: "/" }` that mirrors the priority chain mobile's inline `onBack` switch already uses. Pinned by a 256-combination parity test against the mobile reference implementation so the two never drift. - **`packages/client/src/hooks/useDesktopBack.ts`** — thin React hook that reads the live overlay state, calls the helper, and dispatches to the right setter or `navigate("/")`. - **Sidebar overlay auto-close** — `useOpenSpecActions.handleReadArtifact`, `useContentViews.handleViewPiResourceFile`, and `useContentViews.handleViewReadme` accept `navigate`/`settingsMatch`/`tunnelSetupMatch` and call `navigate("/")` BEFORE setting overlay state when the user is on a URL-route view (Settings / Tunnel Setup) that takes over the content area. Without this, the JSX gate `!settingsMatch && !tunnelSetupMatch` would mask the just-opened overlay until the user clicked back twice. The priority chain (alive on click): `archiveBrowserCwd → specsBrowserCwd → flowYamlPreview → diffViewSessionId → piResourceFilePreview → readmePreview → piResourcesState → previewState → navigate("/")`. Mobile is unchanged — it keeps its own inline `onBack` switch covering the same chain. See change `fix-desktop-back-navigation`. ### Model & Thinking Level Flow 1. Bridge sends current model and thinking level in `session_register` on connect 2. When user changes model (via `/model`), pi emits `model_select` event 3. Bridge enriches the event with current `thinkingLevel` from context before forwarding 4. Bridge also sends a `model_update` protocol message for session-level tracking 5. Server extracts model/thinkingLevel from events and `model_update`, broadcasts to browsers 6. Thinking level changes (via pi keybinding) are detected when `model_select` events fire, on reconnect, and immediately after `set_thinking_level` commands 7. Browser can send `set_thinking_level` to change thinking level remotely ### Context Usage Tracking 1. On each `turn_end`, the bridge calls pi's `ctx.getContextUsage()` API to get real-time context usage (tokens used + actual context window from the provider) 2. Bridge enriches the `turn_end` event with this `contextUsage` data before forwarding to the server 3. Server extracts `contextUsage` from the event data and passes it to `extractTurnStats()`, which includes it in the synthesized `stats_update` event 4. Server updates `session.contextTokens` and `session.contextWindow` and broadcasts to browsers 5. The `onChange` handler persists these values to `.meta.json` (debounced 1s) 6. On server restart, the scanner restores `contextTokens`/`contextWindow` from `.meta.json` 7. Client's event reducer stores `contextUsage` from `stats_update` events; `App.tsx` falls back to `session.contextTokens/contextWindow` for sessions without live reducer state 8. When real data is unavailable (e.g., old sessions without persisted context data), `state-replay.ts` and `session-stats-reader.ts` use `inferContextWindow()` to estimate context window from the model name ### VCS Polling (Git + Jujutsu) 1. Bridge polls VCS info every 30s (`vcs-info.ts`, was `git-info.ts`): branch, remote URL, PR number, plus jj workspace state when `.jj/` is present. 2. Git half (`gatherGitInfo`): unchanged — emits `git_info_update` only when branch/PR change. 3. Jj half (`gatherJjInfo`): emits `jj_state_update` only when the serialized `JjState` changes. **Fast path**: a single `fs.existsSync("/.jj")` check runs before any subprocess. Sessions outside a jj repo pay zero subprocess cost. The probe also short-circuits when the tool registry can't resolve `jj` (cached at module level after first miss). 4. Server forwards both update types via `session_updated` to subscribed browsers. #### Jujutsu workspaces The jj-plugin (`packages/jj-plugin/`) renders UI slots gated by predicates that read `Session.jjState`. When the bridge probe never populates `jjState` — because `jj` isn't installed or `.jj/` doesn't exist — every predicate returns `false` and the plugin contributes nothing to the UI. Activation is silent. Server-side jj routes (`packages/server/src/routes/jj-routes.ts`): - `POST /api/jj/workspace/add` — reuses the existing `pendingAttachRegistry` + `spawnPiSession` lever (same code path as openspec attach-and-spawn). The new session boots inside the workspace cwd and the bridge probe populates its `jjState.workspaceName` on the next tick. - `POST /api/jj/workspace/forget` — two-step contract: first request returns 409 `UNFOLDED_WORK` listing the unfolded commits; only an explicit `force:true` re-issue actually deletes (and `rm -rf`'s the directory). - `POST /api/jj/init-colocated` — refuses 409 `DIRTY_INDEX` only on staged changes; allows working-tree dirt (jj snapshots unstaged edits as the new `@` non-destructively). - `GET /api/jj/workspace/list?cwd=` — enumerates workspaces. The `/api/session-diff` route is **regime-aware**: when `jjState.isJjRepo` is true, it routes through `enrichWithJjDiff` which uses `fork_point(@, trunk())` as the diff base for non-default workspaces (cumulative diff across every agent commit) and `@-` for the default workspace. Older clients that don't read `vcsKind`/`baseLabel`/`diffBase` continue to work unchanged. Fold-back is **a skill, not a server route**. The dashboard's `JjFoldBackDialog` builds a skill-invocation prompt; the agent's bash tool then drives `.pi/skills/jj-workspace-fold-back/SKILL.md`, which never invokes mutating git commands and uses `jj op restore` to roll back on conflicts. ### Git Polling (legacy entry, see VCS Polling above) 1. Bridge polls git info every 30s (`vcs-info.ts`): branch, remote URL, PR number 2. Changes are sent to the server only when values differ from last poll 3. Server broadcasts updates to subscribed browsers ### Child Process Scanning 1. Bridge scans child processes every 10s via `process-scanner.ts` (two-phase: capture new PGIDs during active bash calls, then check tracked PGIDs) 2. Only processes running ≥30s are reported (filters out short-lived commands) 3. Bash/sh wrapper processes are excluded (only leaf commands shown) 4. Bridge sends `process_list` to server only when the PID set changes (dedup) 5. Server stores processes on the session object and forwards to subscribed browsers as `process_list_update` 6. New browser connections receive current processes via the initial `session_added` message 7. Session cards display processes with elapsed time and a kill button (sends SIGTERM to process group) ### OpenSpec Polling (Server-Side) 1. Server's DirectoryService polls `openspec` CLI for each known directory (union of pinned dirs + session cwds) at a **configurable interval** (`DashboardConfig.openspec.pollIntervalSeconds`, default 30 s, range 5–3600 s). 2. OpenSpec data is keyed by directory (cwd), not by session — one poll per directory regardless of session count. 3. Changes are broadcast to all connected browsers via `openspec_update { cwd, data }`. 4. Browsers can request immediate refresh via `openspec_refresh { cwd }`. User-initiated refresh **bypasses the mtime gate** (force-mode) but still respects the concurrency cap — see *Refresh paths* below. 5. New directories (pinned or from new sessions) trigger immediate discovery + polling (eager; bypasses jitter + mtime gate). 6. Each `OpenSpecChange` carries an optional `isComplete?: boolean` field forwarded straight through from `openspec status --change --json`. It indicates artifact-authoring completeness only — orthogonal to the task tally — and never feeds `deriveChangeState`. The dashboard uses it solely to gate the **Archive anyway** escape hatch (see “OpenSpec session card”). #### OpenSpec polling cost model A naive `for each cwd: list + for each change: status` fan-out explodes quickly: 4 pinned dirs with 63 total active changes → **67 `openspec` CLI spawns per 30 s tick**, each costing ~0.5 s user CPU just for Node + module load. On an 8-core host that produces a rectangular ~10 s plateau at 100 % CPU every cycle. The scheduler in `packages/server/src/directory-service.ts` applies four layers of throttling (all configurable under `DashboardConfig.openspec`): 1. **mtime gate** (`changeDetection: "mtime" | "always"`, default `mtime`) — skips `openspec list` and `openspec status --change X` when no tracked artifact has changed since the last successful poll. The gate uses **file-aware effective mtime** (the max over a fixed file set) rather than directory mtime alone, because POSIX directory mtime advances only on entry create/delete/rename and misses in-place file edits. The list-step signal unions `/` with each known `/tasks.md`; the per-change signal unions `/` with `tasks.md`, `proposal.md`, `design.md`, **plus the entire `specs/**` subtree** (the `specs/` directory itself, every immediate `specs//` directory, and every `specs//spec.md`). Missing files or directories (e.g. a change with no `design.md` or no `specs/` yet) are skipped, not zero — `readdirSync` on `specs/` is try/catch-wrapped so absence yields an empty fan-out. A `stat` is ~10 µs vs. ~500 ms per CLI spawn; in steady state this drops 67 spawns/tick to 0–2. The gate is **TOCTOU-safe**: each per-change iteration 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 (the next gated tick re-polls because the post-write mtime no longer matches the preserved cached value). Without this guard, a write landing during the CLI call would stamp `{ mtimeMs: post-write, status: pre-write }` and latch the stale status indefinitely — trivially triggered by `/opsx:ff` mid-poll. **Defense in depth**: `buildOpenSpecData` also accepts a `SpecsProbeFactory` (parallel to the existing `DesignProbeFactory`) that promotes `specs: ready → done` whenever any `specs/**/*.md` file is found locally — promote-only, never demote, never `blocked → done`. So even if a future blind spot creeps into the gate, the dashboard cannot under-report `specs` as ready when at least one spec file exists. See changes: `fix-openspec-specs-mtime-gate-blind-spot`, `fix-openspec-mtime-gate-toctou`, `fix-openspec-mtime-gate-blind-spots`. 2. **Concurrency cap** (`maxConcurrentSpawns`, default 3, range 1–16) — an in-repo semaphore (`packages/shared/src/semaphore.ts`) serializes CLI spawns across all directories. Burst-work spreads uniformly over the interval instead of pinning every core. 3. **Per-cwd jitter** (`jitterSeconds`, default 5) — each known directory is assigned a deterministic phase offset `fnv1a32(cwd) % (jitterSeconds * 1000)` within the interval so polls don't all align on the same scheduling boundary. 4. **Split pi-resources timer** — `scanPiResources(cwd)` no longer rides the openspec tick; it has its own interval at 5× the openspec cadence (pi extensions/skills change far less often than OpenSpec artifacts). Cache shape (per cwd): `{ listMtimeMs, listResult, changes: Map, data }`. Cache is updated atomically per directory — a partial failure leaves the previous snapshot intact and the next tick retries. Refresh paths split into two camps: - **User-initiated** (`openspec_refresh` WebSocket message → `refreshOpenSpec(cwd)`) **bypasses** the gate via `pollOne(cwd, true)`. The gate is heuristic; the CLI is authoritative. When the user clicks the refresh icon they expect fresh data, never silently-cached data — force-mode is the manual escape hatch for any future gate blind spot. Cost: `1 + N` spawns per click. Per-click is rare and the user is already waiting. - **Internal / periodic** (`pollDirectoryGated(cwd)`, `onDirectoryAdded(cwd)`, `handleOpenSpecBulkArchive` post-archive refresh) **honor** the gate via `pollOne(cwd, false)`. Post-archive refresh on a folder with N active changes used to cost `1 + N` spawns (when these paths went through the user-facing `refreshOpenSpec`); it now costs `1` (list) plus only the few status spawns whose artifact files actually moved. All paths still go through the semaphore, so a refresh-button storm cannot overload the host. See changes: `fix-openspec-mtime-gate-toctou` (current contract), `fix-openspec-mtime-gate-blind-spots` (file-aware gate). Live reconfiguration: `PUT /api/config` with an `openspec` block calls `directoryService.reconfigurePolling(cfg)` — the timer cadence and semaphore max are updated without a server restart; in-flight polls finish on their old config. Observability: `DEBUG=pi-dashboard:openspec-poll` (or any `DEBUG=...pi-dashboard...`) emits one line per tick with dir count, queue size, and wall time. Any tick over 5 s logs a WARN hinting at `pollIntervalSeconds` / `maxConcurrentSpawns` as knobs. ### OpenSpec session card UI The attached-change row on every session card has four affordances driven by the polled `OpenSpecChange`: - **State pill** — `StatePill.tsx` renders `deriveChangeState(change)` as a small color-coded pill (`PLANNING`=zinc, `READY`=blue, `IMPLEMENTING`=amber, `COMPLETE`=green) next to the `📋 ` badge. Hidden when the attached change isn't present in OpenSpec data (e.g. archived under another name). - **Tasks popover** — a `Tasks N/M` action button appears whenever the change has at least one parseable task. Clicking opens `TasksPopover.tsx`, a portal-rendered popover that lists every `- [ ] / - [x]` line in `tasks.md`, grouped by `## ` heading, with native checkboxes. Toggling a checkbox issues an optimistic `POST /api/openspec/tasks/toggle`; HTTP 409 (the file changed under us) refetches and surfaces a “File changed — please try again” banner. After every successful toggle the server re-polls openspec for that cwd and broadcasts the standard `openspec_update`, so card counts (`30/33` → `31/33`) refresh without a manual reload. - **Archive anyway** — when `state === IMPLEMENTING && change.isComplete === true && allArtifactsDone`, an overflow `⋯` button appears on the action row. The single menu item opens a `ConfirmDialog` reading `" of tasks are unchecked. Archive anyway?"`. Confirming dispatches `/opsx:archive ` through the normal `onSendPrompt` path. The default Apply button is unaffected; this is purely an escape hatch for changes whose remaining tasks are manual-verification items the user owns. - **Bulk Archive relocation** — the Bulk Archive button now appears **only on unattached sessions** that have at least one folder change with `status === "complete"`. It is removed from the attached-session action row to free up space; the folder-level Bulk Archive in `FolderOpenSpecSection` is unchanged. **Server endpoints (localhost-guarded, registered alongside the existing openspec routes in `packages/server/src/routes/openspec-routes.ts`):** - `GET /api/openspec/tasks?cwd=&change=` — parses `/openspec/changes//tasks.md` via `parseTasksMarkdown` (top-level `- [ ] ` / `- [x] ` only; everything else is ignored). Returns `{ success: true, data: { tasks: OpenSpecTask[], groups: string[] } }`. 404 when the file is missing, 403 when the network guard denies. - `POST /api/openspec/tasks/toggle` — body `{ cwd, change, id, done, line }`. Reads the file, validates that `line` still contains the requested `id` and the *opposite* state (optimistic-concurrency check), rewrites only that one line's `[ ]`/`[x]` marker, and atomic-writes via `tmp + rename` so other lines are preserved byte-for-byte. Maps typed errors to HTTP: `NotFoundError` → 404, `LineMismatchError` → 409, `NotACheckboxError` → 400. On success, fires a fire-and-forget `directoryService.refreshOpenSpec(cwd)` followed by an `openspec_update` broadcast. ### File Read API The server exposes `GET /api/file?cwd=...&path=...` for reading files or listing directories from session working directories. Guards: localhost-only, cwd must match a known session, resolved path must stay inside cwd. Returns `{ type: "file", content }` or `{ type: "directory", entries }`. ### Filesystem Browser (PathPicker) The dashboard's reusable directory chooser (`PathPicker`) is backed by three localhost-only endpoints: - `GET /api/browse?path=&q=&detect=<0|1>` — lists subdirectories of `` (or `$HOME` when omitted). By default this is a single-`readdir` enumeration with no per-entry filesystem probes; `isGit` / `isPi` are absent from each `BrowseEntry`. Pass `detect=1` (only the literal string `"1"` is truthy) to opt into eager `.git` / `.pi` classification on every entry — useful for skill recipes that consumed the legacy shape. When `q` is non-empty, entries are case-insensitive substring-filtered and ranked: - **Tier 0** exact match → **Tier 1** prefix → **Tier 2** word-boundary substring (after `-`, `_`, `.`, space, `/`) → **Tier 3** plain substring. - Alphabetical within each tier. The 200-entry cap is applied **after** filter+rank so best matches always survive truncation. See change: split-browse-flags. - `GET /api/browse/flags?paths=` — bulk classifier for paths produced by `/api/browse`. The `paths` query is a URL-encoded JSON array of absolute path strings (length ≤ 100). Returns `{ flags: { [path]: { isGit, isPi } } }`. Per-path probe failures (ENOENT, EACCES, ELOOP, race-on-deletion, anything) map to `{ isGit: false, isPi: false }` for that key — only malformed input or over-cap arrays produce a top-level error (`invalid paths` / `too many paths`, both HTTP 400). Internal `fs.access` fan-out is bounded at 32 in-flight calls. The `PathPicker` calls this lazily after each `/api/browse` enumeration and merges the flag map into the rendered rows so badges fade in without blocking the initial paint. See change: split-browse-flags. - `POST /api/browse/mkdir` body `{ parent, name }` — creates a new directory non-recursively (`fs.mkdir` without `recursive: true`). Name validation rejects `/`, `\`, `\0`, `.`, `..`, empty, and leading/trailing whitespace. Errors map to 400 (`invalid name`, `parent is not a directory`), 404 (`parent not found`), 409 (`already exists`). Client-side, `PathPicker` debounces the `q` request at 150ms and cancels in-flight requests via `AbortController`. Enter/Select follow a strict state machine instead of confirming arbitrary input: 1. Exact case-insensitive match against a visible entry → `onSelect()` + close. 2. Input ends with `/` and its parsed parent equals the fetched directory → `onSelect(inputValue)` + close. 3. Exactly one filtered candidate → complete to `/` (do not close). 4. Otherwise → no-op with a 300ms red-border flash. If a debounced query is still pending when Enter fires, the client flushes it synchronously before evaluating the rules so the freshest server result is considered. New folders can be created from two entry points — a footer **＋ New folder** button (inline name entry), or an inline **＋ Create "" here** row shown when the typed partial has no exact match. The create-here row is suppressed if the parsed parent differs from the last-successfully-fetched directory (prevents creating inside a stale parent after a mid-path typo). On success the picker refetches and descends into the new directory. ### Pi Resources Browser The dashboard can display pi extensions, skills, and prompts installed for each workspace. The server-side scanner (`pi-resource-scanner.ts`) discovers resources from three sources: 1. **Local**: `/.pi/extensions/`, `.pi/skills/`, `.pi/prompts/` 2. **Global**: `~/.pi/agent/extensions/`, `skills/`, `prompts/` 3. **Packages**: Resolved from `packages[]` in both `/.pi/settings.json` and `~/.pi/agent/settings.json` — supports npm, git, and local path packages with pi manifest or conventional directory fallback Metadata is parsed from SKILL.md YAML frontmatter (`name`, `description`), prompt frontmatter, and `package.json`. Results are cached in DirectoryService and polled every 30s alongside OpenSpec. **API endpoints:** - `GET /api/pi-resources?cwd=...` — returns grouped resources (local, global, packages) from cache - `GET /api/pi-resource-file?path=...` — reads resource files from allowed locations (`.pi/`, `~/.pi/agent/`, `node_modules/`, `.pi/git/`) **Package Management:** - `GET /api/packages/search?q=&type=` — proxied npm search for `keywords:pi-package`, cached 5min - `GET /api/packages/readme?pkg=` — fetch package README from npm registry - `GET /api/packages/installed?scope=global|local&cwd=` — list installed packages via pi's `PackageManager` - `POST /api/packages/install` — install package (returns 202 + operationId, streams progress via WS) - `POST /api/packages/remove` — remove package (same async pattern) - `POST /api/packages/update` — update packages (same async pattern) - `POST /api/packages/check-updates` — check for available updates (on-demand) Package operations use pi's `DefaultPackageManager` API on the server, serialized (one at a time, 409 on concurrent). Progress events are forwarded to browsers via `package_progress` WebSocket messages. After any successful operation, the server sends `/reload` to all connected pi sessions. **Pi Core Version Check (separate from extension management):** - `GET /api/pi-core/versions[?refresh=true]` — returns `PiCoreStatus` with all discovered pi ecosystem CLI packages (pi itself, pi-dashboard, pi-model-proxy, bare `pi-*` and scoped `@x/pi-*`), their installed version, latest npm-registry version, `updateAvailable` flag, and `installSource` (`"global"` via `npm list -g --depth=0 --json` vs `"managed"` in `~/.pi-dashboard/node_modules/`). Cached 5 min. - `POST /api/pi-core/update` with `{ packages?: string[] }` — updates the listed packages, or all packages with `updateAvailable` when omitted. Runs `npm update -g ` (global) or `npm update ` in `~/.pi-dashboard/` (managed). Shares the `PackageManagerWrapper.runExclusive()` busy-lock with extension operations — returns 409 on contention. Why a separate system? Pi's `DefaultPackageManager` only manages packages listed in `settings.json packages[]` (extensions/skills/prompts/themes). The pi CLI binary itself and the dashboard server package are installed directly via `npm -g` (or into `~/.pi-dashboard/` in the Electron case) and are invisible to pi's manager. `PiCoreChecker` + `PiCoreUpdater` (`pi-core-checker.ts` + `pi-core-updater.ts`) fill that gap. Progress for core updates is delivered via typed `pi_core_update_progress` / `pi_core_update_complete` browser-protocol messages (not the `package_progress` channel) and fanned out to `PiCoreVersionsSection` and `PiUpdateBadge` via a `pi-core-event` DOM event. After any successful core update the server sends `/reload` to connected pi sessions just like extension updates. **Header badge**: `PiUpdateBadge` polls `/api/pi-core/versions` on mount + every 30 min. When `updatesAvailable > 0` it renders a small pill-shaped button next to the `ServerSelector` that navigates to `/settings?tab=packages`. **Client navigation stack:** - Puzzle icon button in folder header → PiResourcesView (content area, "Installed" / "Packages" tabs) - "View" button on resource → MarkdownPreviewView (`.md` as markdown, `.ts` as code block) - Settings → Packages tab → inline PackageBrowser for global package management - Back buttons pop the stack: Preview → Resources → Chat ### Git Branch Selector The dashboard provides a git branch selector at the folder group level. Clicking the branch icon in `GroupGitInfo` opens a typeahead `BranchPicker` dialog. The flow supports three states: 1. **No git repo**: Dimmed icon labeled "Init git" — clicking triggers `POST /api/git/init` 2. **Detached HEAD**: Shows short commit SHA — clicking opens the branch picker 3. **Normal branch**: Shows branch name — clicking opens the branch picker **Server API endpoints** (all localhost-only in `git-operations.ts`): - `GET /api/git/branches?cwd=...` — lists local + remote branches sorted by committer date - `POST /api/git/checkout` — switches branch; returns 409 with dirty file list if working tree is dirty - `POST /api/git/init` — initializes a git repository - `POST /api/git/stash-pop` — pops the most recent stash, reports conflicts **Checkout flow**: Clean checkout closes immediately. Dirty working tree → client shows file list + "Stash & Switch" button → stash + checkout → asks "Pop stash on new branch?" with explicit Yes/No. Remote branches auto-create local tracking branches. ### Session File Diff View The dashboard provides a GitHub-style file diff viewer for sessions. It shows what files a session has changed, with per-change drill-down. **Data flow**: `GET /api/session-diff?sessionId=xxx` (localhost-only) scans session events for Write/Edit tool calls, extracts file paths and change data, optionally enriches with `git diff HEAD` output. Returns `SessionDiffResponse` with files, per-file change events (timestamps + context messages), and optional git diffs. **UI**: Split-pane content-area view (replaces ChatView when active). Left panel shows a two-level file tree — files with status indicators, expandable to show individual change events with timestamps and assistant message context. Right panel renders diffs via `@git-diff-view/react` with `@git-diff-view/lowlight` syntax highlighting. Supports split/unified diff modes and a file content view toggle. **Entry point**: "Changed Files" button in SessionHeader (only visible when Write/Edit tool events exist). Works for both active and ended sessions. ### Markdown Preview View The web client includes a generic `MarkdownPreviewView` component that replaces the chat area. It supports a back button, title, optional tab bar, and loading/error states. For OpenSpec artifacts, the `useOpenSpecReader` hook maps artifact IDs (P/S/D/T) to file paths, fetches content via the file API, and concatenates specs from subdirectories. ### Archive Browser The `ArchiveBrowserView` provides a searchable, date-grouped listing of archived OpenSpec changes. It uses a dedicated `GET /api/openspec-archive?cwd=` endpoint that scans `openspec/changes/archive/` and returns entry metadata (name, date, artifacts). The view uses two-level navigation: the list is the first level, and clicking an artifact letter (P/D/S/T) opens the reader as the second level. Back from the reader returns to the list (preserving search and scroll), and back from the list returns to the session view. Entry point is the `[Archive]` button in `FolderOpenSpecSection`. ### Content View Management The content area (right panel) shows one view at a time: ChatView, ArchiveBrowserView, SpecsBrowserView, PiResourcesView, MarkdownPreviewView (readme, pi resource file, flow YAML, OpenSpec artifact), FileDiffView, FlowArchitectDetail, or FlowAgentDetail. Each view is controlled by independent state in `App.tsx` and `useContentViews`. A priority chain in the JSX determines which view renders (first truthy state wins). **Mutual exclusivity**: A `clearAllContentViews()` helper resets all content view states. It is called before opening any new content view, ensuring the previous view is always dismissed. This combines `clearAppContentViews()` (App-level states: preview, specs browser, archive browser, diff view, flow YAML, architect detail, flow agent detail) with `clearContentViews()` from `useContentViews` (pi resources, pi resource file preview, readme preview). **Session switch**: When the selected session changes, `clearAllContentViews()` is called to dismiss any open content view. **Sub-navigation**: `handleViewPiResourceFile` (viewing a file within PiResourcesView) does not clear other views — it's sub-navigation within an already-active content view. **`onBeforeOpen` callback**: `useContentViews` accepts an optional `onBeforeOpen` callback. When `handleOpenPiResources` or `handleViewReadme` opens a new top-level view, it calls `onBeforeOpen` first so App.tsx can clear its own states, then clears the hook's sibling states internally. ### Network Access Control The server has a two-layer access model: **Layer 1: Network Guard (`createNetworkGuard`)** — Fastify `preHandler` on all sensitive routes. Allows requests via three paths: 1. **Loopback** — `127.0.0.1`, `::1`, `::ffff:127.0.0.1` (always allowed) 2. **Trusted networks** — IPs matching `resolvedTrustedNetworks` (CIDR, wildcard, exact). `resolvedTrustedNetworks` is computed at load time by merging two config sources: the Settings UI writes new entries to `auth.bypassHosts` (canonical path on the Security tab, surfaced as the "Trusted Networks" section), while the legacy top-level `trustedNetworks` field remains readable for backward compatibility with hand-edited `config.json` files. Both honor the same matching logic; the UI does not modify the legacy field. **Both fields work independently of whether `auth.providers` is configured** — a config with `auth: { providers: {}, bypassHosts: [...] }` is honored as-is; the auth plugin no-ops when the provider registry is empty and the network guard serves the bypass path directly. See `openspec/changes/archive/` for `fix-trusted-networks-no-oauth` which restored this behavior after it regressed in `consolidate-trusted-networks`. 3. **Authenticated** — `request.isAuthenticated === true` (set by auth `onRequest` hook via `decorateRequest`) Otherwise → 403. The guard strips `::ffff:` IPv4-mapped prefixes before matching. **Layer 2: Auth Plugin (`onRequest` hook)** — Only registered when `auth` is configured. Skips loopback, trusted networks, `/auth/*`, `/api/health`, and `bypassUrls`. Validates JWT cookie for all other requests. Tags valid requests with `request.isAuthenticated = true`. **Execution order**: `onRequest` (auth) → `preHandler` (guard) → handler. This means the auth hook tags the request before the guard checks it. **WebSocket upgrades** follow the same logic: loopback → trusted network → JWT cookie validation. **Zrok tunnel** connections appear as `127.0.0.1` (zrok proxies to localhost), so both layers pass automatically. **`GET /api/network-interfaces`** returns detected non-internal IPv4 interfaces with computed CIDRs. Used by the Settings UI "Add Local Network" button. This endpoint uses the legacy `localhostGuard` (localhost-only, not network-guard-aware) since it exposes machine network topology. ### OAuth Authentication Flow Optional OAuth2 authentication protects the dashboard when accessed remotely. 1. Server loads `auth` config from `~/.pi/dashboard/config.json` at startup 2. If `auth.providers` has entries, the auth plugin registers routes, the `isAuthenticated` request decorator, and an `onRequest` hook 3. The `onRequest` hook skips localhost requests (`isLoopback`), trusted network IPs (`resolvedTrustedNetworks`), `/auth/*` paths, `/api/health`, and configured `bypassUrls` path prefixes 4. External requests without a valid `pi_dash_token` JWT cookie are redirected to `/auth/login` 5. `/auth/login` shows a provider picker (or auto-redirects if single provider) 6. OAuth callback exchanges code for token, fetches user info, validates against `allowedEmails` 7. On success, a signed JWT cookie is set (7-day expiry) and user is redirected back 8. WebSocket upgrade requests are also validated — external connections without valid cookie or trusted network get 401 9. Supported providers: GitHub (hardcoded endpoints), Google/Keycloak/OIDC (via OIDC discovery) ### Settings Panel The web client includes a Settings panel (gear icon in sidebar header → `/settings` route) that lets users view and edit all dashboard configuration. The panel: 1. Loads config via `GET /api/config` (secrets redacted as `***`) 2. Renders grouped form fields per tab — General: Server, Sessions, Tunnel, Developer; Security: Authentication (OAuth providers, Allowed Users, Bypass URL Prefixes) and Trusted Networks (writes `auth.bypassHosts`, with "+ Add Local Network" auto-detect + manual IP/wildcard/CIDR entry) 3. Sends only changed fields via `PUT /api/config` (partial merge) 4. Server preserves `***` secrets (doesn't overwrite real values), writes to disk, and applies runtime-safe changes 5. Port/piPort changes flag `restartRequired` in the response ### Reconnection Flow 1. Browser reconnects with `subscribe` message including `lastSeq` 2. Server replays missed events from in-memory buffer in async batches of 50 with backpressure handling 3. Browser's event reducer processes replay, rebuilding state ### Bridge Reconnection (State Reset) When a bridge extension reconnects (e.g., after `npm run reload` or network recovery): 1. Bridge sends `session_register` with `eventCount` to re-register the session 2. Server checks `canSkipWipe`: if the bridge's `eventCount` matches the server's `lastEntryCount` and events exist in the store, the wipe is skipped (fast reconnect path) 3. **Full replay path** (`canSkipWipe = false`): Server clears the in-memory event store, broadcasts `session_state_reset` to browsers, stores replayed events, and sends them as `event_replay` batch after `replay_complete` 4. **Skip replay path** (`canSkipWipe = true`): Server keeps existing events in the store, marks the session in `skipReplayInsert` set so replayed events are NOT re-inserted (preventing exponential duplication). Status updates are still processed for session state accuracy. After `replay_complete`, the `event_replay` batch is skipped since browsers already have the events. 5. Bridge replays full session history as individual `event_forward` messages 6. Bridge sends `replay_complete` to signal replay is done 7. If the agent is currently mid-turn (bridge tracks `isAgentStreaming` flag in persistent `BridgeState`), a synthetic `agent_start` event is sent after `replay_complete` so the session card shows "Thinking…" instead of "Waiting for input" 8. Server clears the replaying flag, broadcasts the final accumulated session status 9. Browser rebuilds state cleanly from the replayed events (full replay) or continues with existing state (skip replay) Without the `session_state_reset` message (full replay path), replayed events would duplicate existing messages in the browser's accumulated state. **Replay status suppression**: During step 5, replayed events like `agent_start`/`agent_end` would normally trigger rapid `session_updated` broadcasts (e.g., `status: "streaming"` → `status: "idle"` for each turn), causing visible flicker on session cards. The server suppresses these status broadcasts while replaying, accumulating them in the session manager. Only the final status is broadcast after `replay_complete`. A 5-second safety timeout ensures the flag is cleared even if `replay_complete` never arrives (e.g., older bridge versions). **Agent streaming state recovery**: The bridge tracks `isAgentStreaming` in process-level `BridgeState` (survives reload). Set `true` on `agent_start`, `false` on `agent_end`/`session_shutdown`. Since the replay doesn't include `agent_start`/`agent_end` events, the session status would otherwise stay "active" (displayed as "Waiting for input") when the agent is mid-turn during reconnect. ### Session File Deduplication When pi continues a session via `--session `, it reuses the same JSONL file but may create a new session ID. The server detects this: when a new session registers with a `sessionFile` already associated with another session, the old session's `sessionFile` is cleared. This prevents the Resume button from loading the wrong conversation. ### Ghost Session Cleanup When the bridge extension is loaded multiple times (e.g., local project + global npm package), duplicate connections can create "ghost" sessions — active sessions with no sessionFile and no events. The server detects and removes these: - **Pi gateway**: When a `session_register` changes the connection's session ID, the old session is cleaned up if it has `source: "unknown"` or no `sessionFile` - **Event wiring**: When `session_register` arrives, any active sessions in the same cwd that have no sessionFile, no events, aren't connected, and were created within 30s are removed as ghosts ### On-Demand Session Loading (Server-Side) When a browser subscribes to a session whose events have been evicted from memory: 1. Server sends empty `event_replay` with `isLast: false` to indicate loading 2. Server's DirectoryService loads the session file directly via `SessionManager.open(sessionFile).getBranch()` 3. Entries are converted via `replayEntriesAsEvents()` and stored in the event buffer (truncated, capped at 5000/session) 4. Server sends `event_replay` in async batches with backpressure to all waiting browsers 5. If the session file is missing or corrupt, server sends `dataUnavailable: true` 6. Concurrent loads for the same session are deduplicated ### Flows Refresh Deduplication When a session sends `flows_list`, the server notifies other sessions in the same cwd to rediscover flows. To prevent infinite loops (A→refresh B→B sends flows→refresh A→...), a per-session 5-second cooldown (`recentFlowsRefresh` set) suppresses duplicate refresh requests. ### Event Broadcast During Replay During bridge session replay (while `replayingSessions` set contains the session), `event_forward` messages are stored but NOT broadcast individually to browser subscribers. Instead, when `replay_complete` arrives (or the 5s safety timeout fires), the server sends all accumulated events as a single `event_replay` batch to subscribers. This prevents per-event serialization overhead during replay while still delivering the full history to browsers. ### Per-message entry id stamping (live vs replay) The per-message ⤘ Fork button needs each chat bubble to carry the entry id of the entry it represents in the persisted JSONL. Two paths populate this: - **Replay path** (`packages/shared/src/state-replay.ts`): reads from the persisted JSONL directly, so each `message_start` / `message_end` event carries the stable `entryId` from the source entry. No back-fill needed. - **Live path** (`packages/extension/src/bridge.ts`): pi 0.69+ awaits extension handlers BEFORE calling `sessionManager.appendMessage`, which means an entry id does NOT exist at the bridge's emit time. The bridge instead: 1. Stamps a per-event `nonce` on `message_start` / `message_end` events so the client can correlate later. 2. Defers the `message_end` SEND via `setTimeout(0)` (a macrotask) so pi's awaited dispatcher unwinds and `appendMessage` runs in between — by the time the timeout fires, pi has mutated `event.message.id` in place. 3. Wraps `ctx.sessionManager.appendMessage` once per session at `session_start`. After a successful append, the wrapper emits an `entry_persisted { entryId, nonce }` event so the client reducer back-fills the matching ChatMessage's `entryId` (covers user messages, whose `message_start` fires before persistence). `queueMicrotask` was used previously but no longer works: on pi 0.69+ the microtask resolves *inside* the awaited `_emitExtensionEvent`, before persistence. See change `fix-per-message-fork`. ## Persistence | Data | Storage | Details | |------|---------|---------| | Events | In-memory Map | LRU eviction, max 100 sessions. Pinned if active bridge or browser subscribers. | | Sessions | In-memory Map + `.meta.json` | In-memory registry. Each session's state cached in per-session `.meta.json` sidecar next to `.jsonl`. On startup, `session-scanner.ts` scans `~/.pi/agent/sessions/*/` to restore all sessions from cached meta. | | Session meta | `~/.pi/agent/sessions/…/.meta.json` | Per-session sidecar: dashboard-owned state (name, attachedProposal, hidden, source) + cached stats (tokens, cost, model, status). Debounced per-session writes (max 1/sec). Stale cache detected via `cachedAt` vs `.jsonl` mtime. | | Pinned directories | `~/.pi/dashboard/preferences.json` | Ordered array of cwd paths. Pinned dirs always visible in sidebar. | | Session order | `~/.pi/dashboard/preferences.json` | Per-cwd ordering managed by `session-order-manager.ts`. | | Server PID | `~/.pi/dashboard/server.pid` | Tracks running server process for daemon management. | | Headless PIDs | `~/.pi/dashboard/headless-pids.json` | Maps spawned headless processes to sessions. Unix: `tail -f /dev/null \| pi --mode rpc` (uses tail instead of sleep to avoid stdin pipeline bug). Windows: `pi.cmd --mode rpc` with `shell: true` and quoted paths for spaces in usernames. | | Bridge extension | `~/.pi/agent/settings.json` | On bundled installs (Electron DEB/DMG), the server auto-registers the bridge extension path in pi's global settings so all spawned pi sessions discover and load it. No-op in dev mode. | | Session files | `~/.pi/agent/sessions/` (pi's own) | Source of truth. Bridge loads on demand. | ## Configuration Precedence: CLI flags → environment variables → config file (`~/.pi/dashboard/config.json`) | Setting | Default | Description | |---------|---------|-------------| | `port` | 8000 | HTTP + Browser WebSocket port | | `piPort` | 9999 | Pi extension WebSocket port | | `autoStart` | true | Bridge extension auto-starts server if not running | | `autoShutdown` | false | Server shuts down after idle period (disabled by default; enable for TUI auto-start scenarios) | | `shutdownIdleSeconds` | 300 | Idle timeout before auto-shutdown | | `spawnStrategy` | `"headless"` | How to spawn new sessions: `"headless"` or `"tmux"` | | `tunnel.enabled` | true | Enable zrok tunnel for remote access | | `tunnel.reservedToken` | _(auto)_ | Reserved zrok share token for persistent URL (auto-created on first run) | ### Tunnel Lifecycle The tunnel is **enabled by default** (`tunnel.enabled: true`). When the server starts: 1. **Binary detection** — `detectZrokBinary()` checks if `zrok` is on PATH via `which`/`where` 2. **Environment check** — `loadZrokEnv()` reads zrok's own config (`~/.zrok2/environment.json` or `~/.zrok/environment.json`) to verify enrollment. The dashboard never stores zrok API keys — they live entirely in zrok's config directory, created by `zrok enable `. 3. **Stale cleanup** — Runs **unconditionally on startup** whenever the zrok binary is present (even in `--no-tunnel` mode) so leftovers from a previous run are always swept: - `cleanupStaleZrok()` reads `~/.pi/dashboard/zrok.pid` and SIGTERMs the tracked process - `scavengeOrphanZrokProcesses(port)` scans `ps -ax` for any `zrok share … --override-endpoint http://localhost:` processes that escaped pid-file tracking (previous crashes, failed retries) and SIGTERMs them. Never kills the current process. 4. **Reserved share** — If `tunnel.reservedToken` is not set, `zrok reserve public` is called to create a persistent share token. The token is saved to config so the URL stays the same across restarts. If a saved token fails (e.g., expired or orphaned on the zrok edge), `releaseShare(token)` explicitly releases it and a new reservation is created automatically (capped at 1 retry to prevent cascades). 5. **Subprocess spawn** — `createTunnel(port, reservedToken?)` spawns `zrok share reserved --headless` (or `zrok share public --headless` as fallback) as a child process. Concurrent calls are serialized via an in-flight promise (`pendingCreate`) so a UI double-click or a race between startup auto-connect and `/api/tunnel-connect` can’t create two parallel reservations. 6. **URL parsing** — The public URL is parsed from stdout/stderr (30s timeout). On timeout: SIGTERM → SIGKILL after 2s grace, plus `releaseShare(token)` if the token was reserved just-in-time within the call (prevents leaking a dead reservation that would leave a "live but broken" URL on the zrok edge). 7. **PID tracking** — The subprocess PID is written to `~/.pi/dashboard/zrok.pid` 8. **Shutdown** — `deleteTunnel(port?)` SIGTERMs the active subprocess, removes the PID file, and (when `port` is supplied) re-runs `scavengeOrphanZrokProcesses(port)` as belt-and-braces cleanup. The reserved token is preserved for next restart. Called from graceful shutdown, `/api/shutdown`, `/api/restart`, and `/api/tunnel-disconnect`. To disable: set `tunnel.enabled` to `false` in `~/.pi/dashboard/config.json` or pass `--no-tunnel` on the CLI. When disabled, step 3 still runs so orphan processes are cleaned up even if the tunnel is turned off. The client can query `GET /api/tunnel-status` which returns `{ status: "active"|"inactive"|"unavailable", url?, serverOs }`. The client can connect/disconnect the tunnel via `POST /api/tunnel-connect` and `POST /api/tunnel-disconnect`. ### CORS The Fastify CORS callback in `server.ts` allows: - Same-origin navigations (no `Origin` header). - `localhost`, `127.0.0.1`, `[::1]` on any port. - The currently-active zrok tunnel URL (looked up dynamically via `getTunnelUrl()` so URL rotation picks up without a restart). - Any `*.share.zrok.io` host (covers stale tabs, new reservations, and the brief window before `activeTunnelUrl` is populated on startup). - Explicitly-configured `corsAllowedOrigins` from config. On a mismatch the callback returns `cb(null, false)` — **not** `cb(new Error(…), false)`. The `Error` form causes `@fastify/cors` to surface the error as HTTP 500 on every asset response, which is exactly what caused the long-running “zrok returns 500 on assets” debugging saga: Vite emits `