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

package/AGENTS.md

@@ -227,8 +227,12 @@ This section lists only the **architectural backbone** — the files agents touc
 | `src/shared/types.ts` | Data models (Session, Workspace, Event) |
 | `src/shared/config.ts` | Shared config loader (`~/.pi/dashboard/config.json`) |
 | `src/shared/semaphore.ts` | Tiny FIFO semaphore (`createSemaphore(max)`) |
-| `src/extension/bridge.ts` | Main bridge extension entry; PromptBus patch site, sync/tracker/flow composition |
-| `src/extension/bridge-context.ts` | Shared mutable state type + helpers for bridge modules |
+| `src/extension/bridge.ts` | Main bridge extension entry; PromptBus patch site, sync/tracker/flow composition; sessionPrompt routes through slash-dispatch (extension-cmd dispatch + stopgap) before template fallback. See change: fix-extension-slash-commands-in-dashboard. |
+| `src/extension/bridge-context.ts` | Shared mutable state type + helpers for bridge modules; hosts `isExtensionSlashCommand`, `hasDispatchCommand`, `DASHBOARD_NATIVE_COMMANDS` (= {"roles"}). See change: fix-extension-slash-commands-in-dashboard. |
+| `src/extension/slash-dispatch.ts` | Shared `tryDispatchExtensionCommand` helper: routing-step 9 (three-way decision: pi.dispatchCommand 0.71+ → server-routed via RPC keeper UDS when headless → stopgap). See change: fix-extension-slash-commands-in-dashboard, add-rpc-stdin-dispatch-with-keeper-sidecar. |
+| `packages/server/src/rpc-keeper/dispatch-router.ts` | Handles `dispatch_extension_command` extension→server message. Forwards pi RPC line via `headlessPidRegistry.writeRpc`; emits optimistic `command_feedback {completed}` or {error}. See change: add-rpc-stdin-dispatch-with-keeper-sidecar. |
+| `packages/server/src/rpc-keeper/keeper-manager.ts` | Server-side helper: `spawnKeeperFor`, `writeRpc(sessionId)`, `writeRpcToSockPath`, `killKeeper`, `discoverExistingKeepers`. Singleton via `getKeeperManager()` in process-manager.ts. See change: add-rpc-stdin-dispatch-with-keeper-sidecar. |
+| `packages/server/src/rpc-keeper/keeper.cjs` | CJS-pure RPC keeper sidecar; spawns pi as child, owns stdin pipe, listens on per-session UDS / named pipe; outlives dashboard server. See change: add-rpc-stdin-dispatch-with-keeper-sidecar. |
 | `src/extension/session-sync.ts` | Session register, replay, and switch/fork handling |
 | `src/extension/model-tracker.ts` | Model/thinking-level/git/name change detection |
 | `src/extension/flow-event-wiring.ts` | Flow event listener registration (flow:* → event_forward) |
@@ -237,7 +241,7 @@ This section lists only the **architectural backbone** — the files agents touc
 | `src/shared/server-identity.ts` | Identity-verified health check (`isDashboardRunning`) |
 | `src/shared/mdns-discovery.ts` | mDNS advertise/discover/browse for `_pi-dashboard._tcp` |
 | `src/extension/server-launcher.ts` | Auto-start server as detached process; logs to `~/.pi/dashboard/server.log` |
-| `src/extension/command-handler.ts` | Command routing: `!`/`!!` bash, `/compact`, slash commands |
+| `src/extension/command-handler.ts` | Command routing: `!`/`!!` bash, `/compact`, slash commands; slash else-arm now gates through extension-dispatch helper before `sendUserMessage`. See change: fix-extension-slash-commands-in-dashboard. |
 | `src/extension/prompt-expander.ts` | Slash command → prompt template expansion |
 | `src/extension/dev-build.ts` | Dev build-on-reload helper (client build + server shutdown) |
 | `src/extension/server-auto-start.ts` | mDNS-first → health check → auto-start with concurrent launch detection |
@@ -390,6 +394,22 @@ This section lists only the **architectural backbone** — the files agents touc
 | `src/server/provider-auth-storage.ts` | Read/write `~/.pi/agent/auth.json` with lockfile for pi provider credentials |
 | `src/server/routes/provider-auth-routes.ts` | REST routes: provider OAuth authorize/exchange/callback, device-code, API key CRUD |
 | `src/server/routes/provider-routes.ts` | REST routes: custom LLM provider CRUD + connection probe |
+| `src/server/model-proxy/auth-gate.ts` | Fastify `onRequest` hook for `/v1/*`: uniform proxy-key auth, backoff, scope check |
+| `src/server/model-proxy/api-key-store.ts` | Pure helpers: `hashKey`, `verifyKey`, `generateKey`, `findApiKey`, `recordKeyUsage`, `keyHasScope` |
+| `src/server/model-proxy/concurrency.ts` | `ConcurrencyTracker`: server-wide + per-key + per-provider caps; throws `ConcurrencyError` |
+| `src/server/model-proxy/failed-auth-backoff.ts` | Per-IP exponential backoff (10ms→10s cap) for failed proxy-key auth |
+| `src/server/model-proxy/internal-registry.ts` | Server-resident model registry: reads auth/providers/models.json + pi-ai built-ins |
+| `src/server/model-proxy/internal-auth-storage.ts` | Wraps `provider-auth-storage.ts`; handles OAuth-refresh-on-expiry via pi-ai per-provider helpers |
+| `src/server/model-proxy/registry-singleton.ts` | Lazy singleton: `getModelRegistry()`, `refreshModelRegistry()`, `getModelProxyStatus()` |
+| `src/server/model-proxy/recursion-guard.ts` | `isSelfPointing(baseUrl, origins)`: detects dashboard-pointing custom provider baseUrls |
+| `src/server/model-proxy/request-log.ts` | Append-mode JSONL request log at `~/.pi/dashboard/model-proxy.jsonl`; 50MB rotation |
+| `src/server/model-proxy/streamer.ts` | `streamCompletion(opts, streamSimple, registry?)`: resolves creds then streams via pi-ai |
+| `src/server/model-proxy/convert/` | Lifted MIT converters: OpenAI↔pi-ai, Anthropic↔pi-ai (format conversions, SSE output) |
+| `src/server/routes/model-proxy-routes.ts` | Route handlers: `GET /v1/models`, `POST /v1/chat/completions`, `POST /v1/messages` |
+| `src/server/routes/model-proxy-api-key-routes.ts` | REST CRUD for proxy API keys: list, create, revoke, purge (JWT-gated) |
+| `src/server/routes/model-proxy-refresh-routes.ts` | `POST /api/model-proxy/refresh`: JWT-gated manual registry refresh |
+| `src/client/components/ModelProxySection.tsx` | Settings section: proxy toggle, second-port, API key table + reveal-once banner |
+| `src/client/lib/model-proxy-api.ts` | Client fetch helpers: `listApiKeys`, `createApiKey`, `revokeApiKey`, `deleteApiKey`, `refreshRegistry` |
 | `src/server/provider-probe.ts` | Pure per-API probe builders + I/O `probeProvider` (8s timeout, no apiKey echo) |
 | `src/extension/provider-register.ts` | Reads `providers.json`, calls `pi.registerProvider`, hot-reload on credentials change |
 | `src/client/lib/providers-api.ts` | Client fetch helper for `/api/providers/test` connection probe |
@@ -420,7 +440,7 @@ This section lists only the **architectural backbone** — the files agents touc
 | `src/client/components/ZrokInstallGuide.tsx` | OS-aware zrok installation guide view |
 | `src/server/cli.ts` | CLI entry: start/stop/restart/status; `cmdRestart` delegates to `/api/restart` when up |
 | `src/server/restart-helper.ts` | Cross-platform `/api/restart` orchestrator (detached node-built-ins-only spawner) |
-| `src/shared/resolve-jiti.ts` | Resolves pi's jiti register hook as a `file://` URL |
+| `packages/shared/src/server-launcher.ts` | `launchDashboardServer` — single shared spawn primitive (jiti loader, argv, env, log header, readiness) used by Bridge / Standalone / Electron starters |
 | `src/shared/platform/paths.ts` | OS-aware path primitives (`normalizePath`, `samePath`, `parsePathInput`) |
 | `src/client/lib/session-grouping.ts` | Sessions grouped by directory; `resolveSessionGroupPath` (pin > jjState.workspaceRoot > cwd) |
 | `src/shared/platform/` | Unified cross-OS primitives barrel (exec/runner/git/openspec/npm/process/binary-lookup/...) |
@@ -482,7 +502,8 @@ This section lists only the **architectural backbone** — the files agents touc
 | `packages/electron/scripts/test-electron-install.sh` | Full e2e Docker test: install, wizard, server launch, health check |
 | `packages/electron/scripts/test-electron-install-inner.sh` | Inner test script run inside Docker container |
 | `packages/electron/resources/icon.png` | Master 1024×1024 app icon |
-| `.github/workflows/publish.yml` | CI: build matrix × 6 (platform,arch); idempotent ordered npm publish; no-bash-on-Windows |
+| `.github/workflows/publish.yml` | CI: build matrix × 6 (platform,arch); idempotent ordered npm publish; lockfile regen + verify in prepare; no-bash-on-Windows |
+| `scripts/verify-lockfile-versions.mjs` | Sanity gate: asserts every cross-ref in `package-lock.json` is `^<root.version>`; runs after `npm install --package-lock-only` in `prepare` |
 | `packages/shared/src/__tests__/publish-workflow-contract.test.ts` | Repo-lint: pin electron job's `needs:` array and `fail-fast: false` |
 | `packages/shared/src/__tests__/no-bash-on-windows.test.ts` | Repo-lint: forbid `shell: bash` on steps reachable on Windows runners |
 

package/README.md

@@ -62,6 +62,15 @@ On first launch a setup wizard walks you through mode selection (standalone vs.
 
 **Picking the right macOS DMG:** run `uname -m` in Terminal — `arm64` means Apple Silicon (M1/M2/M3/M4), `x86_64` means Intel. Or open   Apple menu → About This Mac and read the chip name. Download the matching DMG; if you grab the wrong one macOS will refuse to launch the app with a "cannot be opened" error.
 
+**First-run unblocking (unsigned binaries):**
+
+- **macOS** — the DMGs are not yet notarized. Either right-click `PI-Dashboard.app` → *Open* the first time, or clear all extended attributes from Terminal:
+  ```bash
+  xattr -cr /Applications/PI-Dashboard.app
+  ```
+  Use `-cr` (clear, recursive) rather than `-d com.apple.quarantine` — it's idempotent and won't print `No such xattr: com.apple.quarantine` when the attribute isn't there. That message is harmless; it just means quarantine was never set or already cleared.
+- **Windows** — SmartScreen warns on first launch. Click *More info → Run anyway*, or right-click the downloaded `.exe` / `.zip` → *Properties* → tick *Unblock* → *OK* before running. For ZIPs, unblock the archive before extracting.
+
 > **Note:** A future release will rename the macOS DMGs to `PI-Dashboard-darwin-arm64-<ver>.dmg` and `PI-Dashboard-darwin-x64-<ver>.dmg` (previously a single `PI Dashboard.dmg` was produced and silently overwrote one arch on each release). Direct download links pointing at the unsuffixed filename will 404 from that release onward; please link to the [Releases page](https://github.com/BlackBeltTechnology/pi-agent-dashboard/releases) instead. See OpenSpec change `fix-darwin-dmg-arch-collision`.
 
 ### B — pi package (recommended for CLI users)
@@ -275,6 +284,27 @@ The file is deliberately separate from `config.json` so machine-specific paths d
 
 ---
 
+## Using the model proxy
+
+The dashboard exposes an OpenAI-compatible HTTP proxy on the same port as the dashboard UI (`/v1/...`). Any LLM client that accepts a custom `base_url` can use it.
+
+```bash
+# Example: point an OpenAI-compatible client at the dashboard
+export OPENAI_BASE_URL=http://localhost:8000/v1
+export OPENAI_API_KEY=pi-proxy-<your-proxy-key>
+```
+
+**Setup:** open Settings → API Proxy in the dashboard UI, enable the proxy, and create an API key.
+
+**Endpoints:**
+- `GET /v1/models` — list available models (requires `models:list` scope or `all`)
+- `POST /v1/chat/completions` — OpenAI chat completions, streaming + non-streaming
+- `POST /v1/messages` — Anthropic messages, streaming + non-streaming
+
+**Auth:** proxy API keys only (`pi-proxy-*` prefix). Dashboard JWT is never accepted on `/v1/*`.
+
+For migration from `@blackbelt-technology/pi-model-proxy`, see [`docs/migration/from-pi-model-proxy.md`](docs/migration/from-pi-model-proxy.md).
+
 ## Usage
 
 ### Auto-start (default)

package/docs/architecture.md

@@ -483,6 +483,24 @@ See changes: `unified-bootstrap-install`, `pi-zero-seventy-compat`, `warn-pi-ver
 
 Electron resources ship bundled Node under `resources/node/` (Windows: `node.exe` + `npm.cmd` + `npx.cmd` at root; Unix: `bin/node` + `bin/npm` + `bin/npx`). `installManagedNode` (`packages/shared/src/bootstrap-install.ts`) `fs.cp`-copies bundle into `<managedDir>/node/` (default `~/.pi-dashboard/node/`), writes `.version` marker for idempotency. `installStandalone` calls it BEFORE first `bootstrapInstall` so npm shims exist when registry install runs; Doctor calls it unconditionally on every launch as a self-repair step. ToolRegistry `node` + `npm` strategy chains prefer `<managedDir>/node/` ahead of system PATH; `prependManagedNodeToPath(env, managedDir)` (`packages/shared/src/platform/managed-node-path.ts`) injects same dir at HEAD of every spawned child's `PATH` (pi-session, pi-core-updater, headless RPC, server-launcher) so `npm.cmd`/`npx.cmd` resolve without `where npm` returning empty on Windows. Standalone CLI / dev / builds without `resources/node/`: bundled source absent, both helpers no-op, resolver falls through to system PATH. See change: embed-managed-node-runtime.
 
+#### Legacy pi detection & cleanup
+
+Pi renamed `@mariozechner/pi-coding-agent` → `@earendil-works/pi-coding-agent` at v0.74. Old scope ships only up to v0.73.x; new scope's `bin/pi` symlink collides with legacy install on `npm install -g` (EEXIST), producing silent "no spawning" failures when both exist.
+
+`packages/server/src/legacy-pi-cleanup.ts` scans 3 locations: npm-global (`npm root -g` → `<root>/@mariozechner/pi-coding-agent`), npx-cache (`~/.npm/_npx/*/node_modules/@mariozechner/pi-coding-agent`, all hashed entries), managed (`~/.pi-dashboard/node_modules/@mariozechner/pi-coding-agent`). Detection cost: one `npm root -g` (~50ms) + `fs.statSync` per candidate. Read-only.
+
+Startup scan: `server.ts` calls `detectLegacyPiInstalls()` once at boot, writes result to `bootstrapState.legacyPiInstalls`. Broadcast via `bootstrap_status_update` WS.
+
+REST: `GET /api/bootstrap/legacy-pi` force-refreshes detection. `POST /api/bootstrap/legacy-pi/cleanup` removes all detected installs, re-scans, returns `{results, remaining}`. Both auth-gated.
+
+UI: `BootstrapBanner` renders amber "Remove legacy pi (N)" sub-banner when `legacyPiInstalls.length > 0` AND `status === "ready"`. Takes precedence over upgrade-recommended hint (legacy install blocks `upgrade-pi`). Wired via `useBootstrapStatus().cleanupLegacyPi()`.
+
+Cleanup actions: npm-global removed via `npm uninstall -g @mariozechner/pi-coding-agent --no-fund --no-audit` so bin symlinks unwound; npx-cache + managed via `fs.rmSync({recursive, force})`. Per-install try/catch — one failure does not abort siblings.
+
+Idempotent: empty pre-scan short-circuits the POST without invoking npm; missing path under `fs.rmSync({force:true})` returns `removed: true`. Tests in `packages/server/src/__tests__/legacy-pi-cleanup.test.ts` (12 cases) cover pure helpers, fs-backed detection under HOME-tempdir isolation, and removal idempotency.
+
+See change: legacy-pi-cleanup.
+
 ### 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".
@@ -697,6 +715,12 @@ Fold-back is **a skill, not a server route**. The dashboard's `JjFoldBackDialog`
 7. Session cards display processes with elapsed time and a kill button (sends SIGTERM to process group)
 
 ### OpenSpec Polling (Server-Side)
+
+**Master gate**: `DashboardConfig.openspec.enabled` (boolean, default `true`).
+- `false` disables all polling. Hides OPENSPEC subcards across dashboard.
+- Tuning fields below (`pollIntervalSeconds`, `maxConcurrentSpawns`, `changeDetection`, `jitterSeconds`) ignored at runtime when `false`. Values preserved.
+- Runtime-reconfigurable via `PUT /api/config`. Disable transition clears per-cwd `OpenSpecData` cache + broadcasts cleared payload `{ initialized: false, pending: false, changes: [] }` per cwd so client predicate `openspecInitialized === false && pending === false` collapses subcards uniformly. Same broadcast shape covers "no openspec/ dir" + "openspec.enabled === false".
+
 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 }`.
@@ -1012,6 +1036,24 @@ To disable: set `tunnel.enabled` to `false` in `~/.pi/dashboard/config.json` or
 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`.
 
+### Tunnel watchdog
+
+Long-lived `zrok share` goes stale on edge. Watchdog detects + recycles.
+
+- Probe target: `GET ${publicUrl}/api/health` through public zrok URL (real edge round-trip, not localhost).
+- Cadence: every `intervalMs` (default 60000).
+- Failure classes: HTTP 5xx, network error, timeout (`probeTimeoutMs`, default 10000). 4xx + 2xx count as healthy reachability.
+- Threshold: `failureThreshold` consecutive failures (default 2) triggers recycle.
+- Recycle action: `deleteTunnel()` then `createTunnel(port, reservedToken)`. Reserved token preserved — URL stable.
+- Counter resets to 0 on success or after successful recycle.
+- Recycle-failure backoff: next retry delay ×2 each consecutive recycle failure, capped ×8 `intervalMs`. Resets to base on first successful probe.
+- Config: `tunnel.watchdog.{enabled, intervalMs, failureThreshold, probeTimeoutMs}` in `~/.pi/dashboard/config.json`. Defaults: enabled true, 60s, 2 failures, 10s timeout.
+- Status: `GET /api/tunnel-status` active variant carries `watchdog: {lastProbeAt, lastSuccessAt, lastFailureAt, lastFailureReason, consecutiveFailures, lastRecycleAt, recycleCount}`.
+- Lifecycle: `startTunnelWatchdog` called in `server.ts` after `createTunnel` succeeds at startup + in `/api/tunnel-connect` after on-demand connect. `stopTunnelWatchdog` called before `deleteTunnel` in graceful shutdown + `/api/tunnel-disconnect`.
+- Module: `packages/server/src/tunnel-watchdog.ts`. Tests: `packages/server/src/__tests__/tunnel-watchdog.test.ts`.
+- Settings UI: Settings → Tunnel exposes watchdog enable + intervalMs + failureThreshold + probeTimeoutMs.
+- Live reload: `PUT /api/config` with `partial.tunnel` stops + restarts watchdog against new config when tunnel active. No server restart required for watchdog tweaks.
+- `writeConfigPartial` deep-merges `tunnel.watchdog` so partial UI saves preserve unspecified fields.
 
 
 ### CORS
@@ -1179,6 +1221,42 @@ Every mechanism branch forwards `sessionFile` + `mode` via the shared `sessionFl
 
 On Windows, `spawnDetached` uses `detached: true` which (via libuv's `src/win/process.c`) emits `DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP` and critically does NOT call `AssignProcessToJobObject` on the parent's global Job Object. This excludes the child from the parent's `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE` job, so pi sessions survive when the dashboard server exits — matching Unix PGID behavior. The `headlessPidRegistry` reconciles these survivors on server restart.
 
+### RPC keeper sidecar
+
+Introduced by change `add-rpc-stdin-dispatch-with-keeper-sidecar`. Experimental, gated by `useRpcKeeper` config flag (default `false`). Resolves typed extension slash commands (`/ctx-stats`, `/curator`, `/agents`, `/flows:*`) in headless dashboard sessions despite pi 0.74 `ExtensionAPI` exposing no `dispatchCommand`.
+
+Per-session keeper process owns pi's stdin pipe. Server writes RPC lines to keeper via UDS (Unix) or named pipe (Windows). Keeper forwards verbatim to pi's stdin. Pi's `--mode rpc` reader runs `session.prompt(text, {expandPromptTemplates: true})` which dispatches slash commands.
+
+Keeper outlives dashboard server restarts. Replaces Unix `tail -f /dev/null | pi` wrapper. Brings Windows to durability parity (today Windows loses pi on server death).
+
+Three-process topology + dual-channel boundary:
+
+```mermaid
+flowchart LR
+  S["dashboard server"]
+  K["keeper.cjs<br/>(1 per session)"]
+  P["pi --mode rpc"]
+  B["bridge.ts<br/>(loaded inside pi)"]
+
+  S -->|"UDS /<sessionId>.rpc.sock<br/>(slash dispatch only)"| K
+  K -->|"pi.stdin pipe<br/>(forward JSON lines)"| P
+  P --- B
+  B -->|"bridge WS<br/>(events, send_prompt non-slash, abort, model, etc.)"| S
+```
+
+UDS path: `~/.pi/dashboard/sessions/<sessionId>.rpc.sock`. Windows pipe: `\\.\pipe\pi-rpc-<sessionId>`. Keeper PID sidecar: `<sockPath>.pid`. Server scans on startup for orphan-cleanup + reattach.
+
+Protocol: line-framed JSON, fire-and-forget. Server writes `{"type":"prompt","message":"/cmd","id":"<requestId>"}\n`. Keeper forwards raw line; no parsing, no response. Acknowledgement implicit (UDS write success).
+
+Dual-channel boundary explicit:
+- **Bridge WS** owns: send_prompt non-slash, abort, model switch, thinking-level, compaction, rename, events, flow control.
+- **Server → keeper UDS** owns: extension slash dispatch only.
+- **headlessPidRegistry kill** owns: kill-by-pid for shutdown / force-kill / reload.
+
+Bridge cannot reach `session.prompt` from inside pi 0.74. Server can (owns spawn + keeper). Routing slash dispatch through the channel that has the capability is correct given the constraint.
+
+Lifecycle: pi exits → keeper exits 0, unlinks socket + pid sidecar. Keeper crashes → pi reads EOF on stdin → exits. Force-kill → server kills pi PID first, schedules 200 ms keeper-fallback SIGTERM. Tmux / Windows-Terminal sessions retain the existing `command_feedback {error}` stopgap (terminal owns pi's stdin, no UDS route).
+
 ### Server Log Hygiene
 
 The daemon log at `~/.pi/dashboard/server.log` is opened in **append mode** (`"a"`) so crash output from prior start attempts survives subsequent retries — essential for diagnosing silent failures. Each attempt writes a timestamped header to distinguish runs:
@@ -1522,7 +1600,7 @@ Every external binary, module, and directory the dashboard depends on is resolve
 | Tool | Kind | Strategy chain |
 |---|---|---|
 | `pi` | binary | override → managed (`MANAGED_BIN/pi[.cmd]`) → where |
-| `pi-coding-agent` | module | override → bare-import → managed (`MANAGED_DIR/node_modules/.../dist/index.js`) → npm-global; probes both `@mariozechner/*` and `@oh-my-pi/*` aliases |
+| `pi-coding-agent` | module | override → bare-import → managed (`MANAGED_DIR/node_modules/.../dist/index.js`) → npm-global; probes `@earendil-works/*` (primary) and `@mariozechner/*` (legacy) aliases |
 | `openspec`, `npm`, `node`, `tsx`, `git`, `zrok` | binary | override → managed → where |
 | `pi-dashboard` | module | override → managed → npm-global (presence of `package.json` is enough) |
 | `electron` | module | override → bare-import (`paths: ["packages/electron"]`) → managed; resolves the package directory containing `install.js`, hoist-aware. See change: register-build-time-tools |
@@ -1998,3 +2076,53 @@ Diagnostics MUST never crash the app. `doctor-core.ts` enforces this with three
 - **`assumedMandatory(label, fn, deps)`** — wraps "should-never-fail" ops (e.g. reading bundled-Node version, listing `~/.pi-dashboard/`). On throw it appends a structured entry to `<managedDir>/doctor.log` (1MB ring rotation) AND surfaces a row in the `Diagnostics` section so the user sees something went wrong instead of a silent gap. The log is opened from the toolbar (`Open doctor log`); the IPC handler returns `{exists:false}` when the file is absent so the renderer can show "no entries yet" instead of erroring.
 
 See change: `doctor-rich-output`.
+
+## Model Proxy
+
+Dashboard-resident LLM proxy: `GET /v1/models`, `POST /v1/chat/completions`, `POST /v1/messages`.
+
+```mermaid
+sequenceDiagram
+    participant C as External client<br/>(Honcho, LangChain, curl)
+    participant D as Dashboard :8000/v1/*
+    participant R as InternalRegistry
+    participant P as Upstream provider<br/>(Anthropic, OpenAI, Google…)
+
+    C->>D: Authorization: Bearer pi-proxy-*
+    D->>D: Auth gate: verify key, scope, backoff
+    D->>R: getAvailable() / find(provider, model)
+    R->>R: auth.json + providers.json + models.json
+    D->>R: getApiKeyAndHeaders(model)
+    R->>D: { apiKey, headers }
+    D->>P: streamSimple(model, context, opts)
+    P-->>D: SSE stream
+    D-->>C: SSE stream (OpenAI or Anthropic shape)
+```
+
+### API-key auth data flow
+
+1. Client sends `Authorization: Bearer pi-proxy-<48-char-base64url>`.
+2. Auth gate (`model-proxy/auth-gate.ts`) prefix-checks `pi-proxy-`, looks up `sha256(token)` in `config.json#modelProxy.apiKeys[]`.
+3. On hit: checks `revokedAt`, `expiresAt`, scope vs. route path.
+4. On success: attaches `request.proxyApiKeyId`, resets per-IP backoff, debounced `lastUsedAt` write.
+
+### Refresh trigger map
+
+| Trigger | Site |
+|---|---|
+| `PUT /api/providers` | `routes/provider-routes.ts` → `refreshModelRegistry()` |
+| OAuth callback completes | `routes/provider-auth-routes.ts` → `refreshModelRegistry()` |
+| Config save | `config-api.ts#writeConfigPartial` → `refreshModelRegistry()` |
+| Bridge `credentials_updated` | `event-wiring.ts` → `refreshModelRegistry()` |
+| `POST /api/model-proxy/refresh` | manual trigger (JWT-gated) |
+
+### auth.json write contract
+
+Two writer processes for `~/.pi/agent/auth.json`:
+
+- **Dashboard**: `provider-auth-storage.ts#writeCredential` (mkdir-based lock). Used by OAuth-flow completion routes AND `InternalAuthStorage` OAuth-refresh-on-expiry.
+- **Pi sessions**: `pi-coding-agent`'s `AuthStorage` (proper-lockfile). Runs in each connected pi session.
+
+Last-writer-wins on overlapping provider keys; non-overlapping providers preserved by merge. Acceptable — both writers re-read before writing; churn only occurs during concurrent OAuth refreshes (rare in practice).
+
+See change: `add-dashboard-model-proxy`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blackbelt-technology/pi-agent-dashboard",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Web dashboard for monitoring and interacting with pi agent sessions",
   "repository": {
     "type": "git",
@@ -19,7 +19,7 @@
   ],
   "main": "packages/server/src/cli.ts",
   "bin": {
-    "pi-dashboard": "packages/server/src/cli.ts"
+    "pi-dashboard": "packages/server/bin/pi-dashboard.mjs"
   },
   "pi": {
     "extensions": [
@@ -31,6 +31,7 @@
   },
   "files": [
     "packages/server/src/",
+    "packages/server/scripts/",
     "packages/server/package.json",
     "packages/server/tsconfig.json",
     "packages/shared/src/",
@@ -73,16 +74,15 @@
     "node": ">=22.12.0 <25"
   },
   "dependencies": {
-    "@blackbelt-technology/pi-dashboard-extension": "^0.5.1",
-    "@blackbelt-technology/pi-dashboard-server": "^0.5.1",
-    "@blackbelt-technology/pi-dashboard-web": "^0.5.1"
+    "@blackbelt-technology/pi-dashboard-extension": "^0.5.2",
+    "@blackbelt-technology/pi-dashboard-server": "^0.5.2",
+    "@blackbelt-technology/pi-dashboard-web": "^0.5.2"
   },
   "optionalDependencies": {
     "appdmg": "^0.6.6"
   },
   "devDependencies": {
     "jsdom": "^29.0.2",
-    "tsx": "^4.21.0",
     "typescript": "^5.7.0",
     "vitest": "^4.0.0"
   },

package/packages/extension/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blackbelt-technology/pi-dashboard-extension",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Pi bridge extension for pi-dashboard",
   "type": "module",
   "repository": {
@@ -24,7 +24,7 @@
     ".pi/skills/pi-dashboard/"
   ],
   "dependencies": {
-    "@blackbelt-technology/pi-dashboard-shared": "^0.5.1",
+    "@blackbelt-technology/pi-dashboard-shared": "^0.5.2",
     "ws": "^8.18.0"
   },
   "peerDependencies": {