@blackbelt-technology/pi-agent-dashboard 0.5.3 → 0.5.4

package/docs/architecture.md

@@ -358,7 +358,7 @@ Descriptor-only slots (existing in `extension-ui-system`): `management-modal`, `
 
 **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".
+**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. `pi-dashboard-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
 
@@ -382,124 +382,69 @@ A repository-level lint (`packages/client/src/__tests__/no-jsx-slot-nullish-fall
 
 **Authoring on-ramp:** Skill package `packages/dashboard-plugin-skill/` ships `@blackbelt-technology/pi-dashboard-plugin-skill` (publishable). Skill name `dashboard-plugin-scaffold`. Hybrid contract: `ask_user` batch up front, prescriptive steps after. Two modes. `new` mode: scaffolds `packages/<id>-plugin/` matching `packages/demo-plugin/` layout. Per-slot stubs for 10 React slots. Optional server entry. Optional bridge entry, default off. `augment` mode: runs in pi session at cwd of existing pi-extension. Grep prelude scans `ctx.ui.*`, `pi.registerTool`, banned `ctx.fork`. LLM analysis vs canonical TUI→dashboard mapping table. Per-callsite `ask_user` multiselect. Injects `pi-dashboard-plugin` field into `package.json`. Writes `src/dashboard/`. Purely additive: no existing source modified. SDK = runtime + shared package exports. No separate SDK package. Skill adds both as deps. Forward-compat contract enforced at scaffold time: top-level manifest field, package-relative paths, no `workspace:*`, exports subpaths match, `requiredApi` set. Augmented external extensions resolve under future `node_modules` discovery scan. Canonical on-ramp. `demo-plugin` = runtime fixture. Skill = authoring fixture.
 
-### 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(<tool>)` 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`.
-
-#### Managed Node runtime
-
-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.
+#### Plugin Bridge Registration
+
+Dual-write contract. `registerPluginBridge` writes BOTH locations in `~/.pi/agent/settings.json`:
+
+- `dashboardPluginBridges["dashboard-<id>"]` — legacy key. Kept for forward compat.
+- `packages[]` — user-visible package list. pi-coding-agent reads only this.
+- `_dashboardManagedPackages` — ownership map. Tracks which `packages[]` entries owned by dashboard vs user. Prevents clobbering user-added entries.
+
+pi-coding-agent ignores `dashboardPluginBridges` entirely. Bridge extensions invisible to pi until written to `packages[]`. Symptom of single-write bug: plugin bridge loaded by dashboard but never invoked by pi runtime; `/api/flows-anthropic-bridge/status` reports "no sessions reporting".
+
+Reconciliation: one-shot `reconcilePluginBridgePackages` runs at server start. Replays current plugin manifests through `ensurePackageEntry` for every claim with a `bridge` entry. Drops dangling managed entries via `removePackageEntry` when manifest gone. Atomic settings write (tmp + rename).
+
+Escape hatch: env `PI_DASHBOARD_DISABLE_PLUGIN_BRIDGE_PACKAGES_WRITE=1` skips `packages[]` write. Legacy key still written. Used for forward-compat testing against pi versions that own `packages[]` differently.
+
+Classification helper `classifyBridgeSource(settings, id)` returns `"packages[]"` / `"dashboardPluginBridges"` / `"both"` / `"none"`. `/api/health.plugins[].bridgeLoadedFrom` surfaces it. `"both"` = healthy post-0.5.4. `"dashboardPluginBridges"` only = stale install pre-reconcile.
+
+#### Plugin Staleness Detection
+
+Detects when client bundle predates installed plugin set. No new REST route. No new WS message.
+
+Build time: vite-plugin emits `export const PLUGIN_REGISTRY_HASH = "<sha256>"` into `packages/client/src/generated/plugin-registry.tsx`. Hash computed by `pluginRegistryHash(discoverPlugins())` over `deterministicSerializePlugins` output (sorted manifest fields, stable JSON).
+
+Runtime: `/api/health` returns `bundleHash` field. Server computes via same `pluginRegistryHash(discoverPlugins())`. Hash mismatch ⇒ disk has plugins client bundle does not know about (or vice versa).
+
+Client: `PluginStalenessBanner` fetches `/api/health` on mount. Compares `bundleHash` against imported `PLUGIN_REGISTRY_HASH`. Mismatch ⇒ render banner with Refresh + Dismiss buttons. Refresh calls `location.reload()`. Dismiss persists in `sessionStorage` key `pi-plugin-staleness-dismissed` (tab-scoped, clears on browser close). Dismissed banner stays hidden until next session.
+
+#### Plugin Activation UI
+
+Settings ▸ Plugins tab lists every discovered plugin (enabled or not) with display name, description, enable/disable toggle, missing-requirement chips, inline Install affordances.
+
+**Toggle workflow.** `PluginsSection` calls `POST /api/plugins/:id/toggle` (`packages/server/src/routes/plugin-activation-routes.ts`). Route writes `plugins.<id>.enabled` via config-api partial merge, broadcasts `plugin_config_update { id, config }` to every browser. Effect is **restart-required**: runtime claim filter (`SlotRegistry.setEnabledSet`) only re-reads enabled-set when client mounts or receives `plugin-config-update` event for the bundle's current plugin set; flipping `enabled` for a plugin whose server entry already loaded doesn't unload it. UI surfaces restart-required banner by comparing toggle timestamp to `/api/health.startedAt`.
+
+**Declarative requirements.** Plugins declare `requires: { piExtensions?, binaries?, services? }` in their manifest (`PluginManifest.requires`, validated by `manifest-validator.ts`). At plugin load, `loader.ts` runs `runRequirementProbes(manifest.requires, requirementDeps)` from `packages/dashboard-plugin-runtime/src/server/requirement-probes.ts`. Probes:
+
+- `probePiExtension(id)` cross-refs installed pi-extension set (deps.listInstalled).
+- `probeBinary(name)` resolves via tool registry.
+- `probeService(name)` dispatches to service-probe map (e.g. `service-probes/pi-model-proxy.ts::detectPiModelProxy`).
+
+Results populate `PluginStatus.requirements` + flat `missingRequirements: string[]`; surfaced via `GET /api/plugins`. 30s in-process cache keyed by category+name. `server.ts` invokes `refreshRequirementProbesFor(pluginIds)` on every successful `package_operation_complete` + broadcasts `plugin_config_update` for any plugin whose missing-set changed — install/uninstall of a pi-extension lights up dependent plugin without restart.
+
+**UI cross-references.** `RecommendedExtensions.tsx` reads `EnrichedRecommendedExtension.dashboardPluginInstalled` (computed server-side in `recommended-routes.ts::enrichEntry` from `RecommendedExtension.dashboardPlugin`) + renders `+plugin: <id>` badge linking to Plugins tab. `pi-memory-honcho` declares `dashboardPlugin: "honcho"`; `honcho-plugin` declares `requires.piExtensions: ["pi-memory-honcho"]` so install paths converge.
+
+**Restart-required model.** `usePluginEnabledSet` snapshots `/api/health.startedAt` ISO timestamp on first load. Subsequent `plugin_config_update` events update enabled-set live for claim filtering, but components that consumed plugin server entries (already loaded) require a restart to drop. `PluginsSection` compares toggle time to snapshot and renders "Restart required" banner when divergent.
+
+**Settings consolidation.** Plugin-contributed `settings-section` claims render only under owning plugin row in Settings ▸ Plugins. Legacy `claim.tab` manifest field preserved for back-compat manifests; `SettingsPanel` no longer consumes it. See change: add-plugin-activation-ui (settings-consolidation).
+
+### Bootstrap & First Run (R3, immutable bundle)
+
+pi/openspec/tsx are regular npm dependencies of `@blackbelt-technology/pi-dashboard-server`. There is no runtime install pyramid. All three arms (Electron, standalone `npm i -g`, bridge) start ready.
+
+- **Electron** — reads server resources from `<resourcesPath>/server/node_modules/` (immutable, read-only). Updates land via electron-updater whole-app replacement. See [electron-immutable-bundle.md](./electron-immutable-bundle.md) and [electron-bootstrap-flow.md](./electron-bootstrap-flow.md) for the 6-state startup machine.
+- **Standalone (`npm i -g @blackbelt-technology/pi-agent-dashboard`)** — npm resolves pi/openspec/tsx at install time via regular `dependencies`. Server binds port 8000 immediately; `cli.ts runForeground` logs `[bootstrap] ready (pi resolved via <source>)` after a single `ToolRegistry.resolve("pi")` call. Failure throws hard citing corrupted `node_modules/`.
+- **Bridge** — pi loads the bridge extension; bridge auto-starts the server. pi-core update path remains via `pi-core-routes.ts` (writable target).
+
+`launchSource` (returned by `/api/health`) is `"electron" | "standalone" | "bridge"`, derived from `DASHBOARD_STARTER`. Client uses it via `useLaunchSource()` to hide pi-core update UI on Electron (immutable bundle has no writable target).
+
+Compatibility skew helpers in `pi-version-skew.ts` (`readPiCompatibility`, `readCurrentPiVersion`, `computeCompatibility`) survive as pure helpers. The pinned range is `minimum: "0.70.0"`, `recommended: "0.70.0"`, `maximum: null` (lockstep — one supported pi means no conditional code paths in the bridge).
+
+#### Legacy `~/.pi-dashboard/` advisory
+
+Pre-R3 builds installed pi/openspec/tsx into `~/.pi-dashboard/node_modules/` at runtime. R3 leaves that directory untouched. `detectLegacyManagedDir({ homedir })` in `packages/shared/src/legacy-managed-dir.ts` returns `{present, path, pkgCount, sizeMb}`. Doctor surfaces a warning-severity row "Legacy install directory" with a `rm -rf <path>` suggestion. Server `cli.ts` logs the path once at startup after the `[bootstrap] ready` line. Repo-lint `no-managed-dir-reference.test.ts` blocks any new write into the legacy directory from `packages/electron/src/lib/`, `packages/server/src/`, or `packages/shared/src/` outside the explicit allowlist.
+
+See change: eliminate-electron-runtime-install.
 
 ### Force Kill Escalation
 The Stop button supports two-click escalation for stuck sessions:
@@ -651,15 +596,21 @@ The sidebar splits each folder's session cards into two tiers (alive on top, end
 
 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`.
+### Shell overlay routing
+Shell-owned content overlays URL-driven via wouter routes. Supersedes priority-chain helper from `fix-desktop-back-navigation`.
 
-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.
+Routes:
+- `/folder/:encodedCwd/openspec/:changeName/:artifactId` — OpenSpec preview.
+- `/folder/:encodedCwd/openspec/archive` — archive browser.
+- `/folder/:encodedCwd/openspec/specs` — specs browser.
+- `/folder/:encodedCwd/readme` — README preview.
+- `/folder/:encodedCwd/pi-resources` — pi resources view.
+- `/session/:id/diff` — file diff view.
+- `/pi-resource?path=&title=` — cross-folder file preview.
 
-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`.
+`App.tsx` matches via `useRoute`. URL builders in `packages/client/src/lib/route-builders.ts`. Back-arrow (desktop + mobile) calls `goBackOrHome(navigate)` from `packages/client/src/lib/history-back.ts` — `window.history.back()` when `history.length > 1`, else `navigate("/")`. No priority chain, no overlay state.
+
+Plugin content-view claims (e.g. flows-plugin) remain predicate-driven, out of scope for shell routing. See change `overlay-url-routing`.
 
 ### Model & Thinking Level Flow
 1. Bridge sends current model and thinking level in `session_register` on connect
@@ -817,7 +768,7 @@ Package operations use pi's `DefaultPackageManager` API on the server, serialize
 
 **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 <pkg>` (global) or `npm update <pkg>` in `~/.pi-dashboard/` (managed). Shares the `PackageManagerWrapper.runExclusive()` busy-lock with extension operations — returns 409 on contention.
+- `POST` to the pi-core update endpoint with `{ packages?: string[] }` — updates the listed packages, or all packages with `updateAvailable` when omitted. Runs `npm update -g <pkg>` (global) or `npm update <pkg>` against a managed install when present. Shares the `PackageManagerWrapper.runExclusive()` busy-lock with extension operations — returns 409 on contention. **Standalone + bridge arms only**; Electron hides this UI under R3 because the bundle is read-only (immutable; updates land via electron-updater whole-app replacement).
 
 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.
 
@@ -827,7 +778,7 @@ Core update progress delivered via typed `pi_core_update_progress` / `pi_core_up
 
 - Settings tab renders single `<UnifiedPackagesSection>`.
 - Three sub-groups in priority order: Core → Recommended → Other.
-- **Core**: strict whitelist from `pi-core-checker.ts#CORE_PACKAGE_NAMES`. Update via `/api/pi-core/update`. No Uninstall.
+- **Core**: strict whitelist from `pi-core-checker.ts#CORE_PACKAGE_NAMES`. Update via the pi-core update endpoint. No Uninstall. Hidden when `launchSource === "electron"` (immutable bundle).
 - **Recommended Extensions**: rows where `isRecommended` true on `/api/packages/installed` response (server-side cross-reference against `RECOMMENDED_EXTENSIONS` manifest).
 - **Other Packages**: every remaining installed row.
 - Each package classified into exactly one group. Core wins over Recommended wins over Other (dedupe).
@@ -876,15 +827,11 @@ The `ArchiveBrowserView` provides a searchable, date-grouped listing of archived
 
 ### 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.
+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, FlowAgentDetail.
 
-**Sub-navigation**: `handleViewPiResourceFile` (viewing a file within PiResourcesView) does not clear other views — it's sub-navigation within an already-active content view.
+Shell overlays dispatch by route match (see Shell overlay routing). Mutual exclusivity intrinsic — only one route active at a time. No `clearAllContentViews` helper, no `onBeforeOpen`. Session switch navigates; route change unmounts previous 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.
+Plugin content-view claims (flows-plugin) still predicate-driven via SlotRegistry. See change `overlay-url-routing`.
 
 ### Network Access Control
 
@@ -1365,7 +1312,7 @@ The dashboard supports browser-based authentication with pi's LLM providers, ena
 
 ### Model metadata enrichment for custom providers
 
-Custom-provider `/v1/models` endpoints only advertise `{id, owned_by}` — do not expose `context_window`, `max_tokens`, `cost`, `reasoning`. Rather than hardcode flat 200k / 16k / $0 / no-reasoning on every discovered model (silently wrong for proxied frontier models like `proxy/cc/claude-opus-4-7` → Opus 4.7's 1M window), bridge's `registerEntry()` runs each discovered id through pure `enrichModelMetadata(id, api, probe)` helper. Helper: (a) strips common proxy prefixes (`cc/`, `anthropic/`, `openrouter/openai/…`) so bare id tried; (b) probes pi's `modelRegistry.find(provider, id)` via ordered api-appropriate candidate list (`anthropic-messages` → `["anthropic", "opencode"]`, `google-generative-ai` → `["google", "google-vertex"]`, `openai-completions` → `["openai", "openrouter", "groq", "xai", "mistral"]`); (c) returns registry's full metadata when matched. Registry reference captured from `ctx.modelRegistry` first time pi fires `session_start` on extension (`model_select` as fallback capture point) — no direct `@mariozechner/pi-ai` import. Since `activate()` registers providers before any event handler fires, first pass uses fallback defaults; `session_start` handler re-registers all providers with enriched metadata via `pi.registerProvider`'s idempotent "replace" semantics. When registry never available or no match, fallback keeps `input: ["text","image"]` so image-capable-by-default contract preserved. Built-in + OAuth providers bypass entirely — metadata comes from pi's bundled `models.generated.js`. See `packages/extension/src/provider-register.ts` + change `enrich-custom-provider-model-metadata`.
+Custom-provider `/v1/models` endpoints only advertise `{id, owned_by}` — do not expose `context_window`, `max_tokens`, `cost`, `reasoning`. Rather than hardcode flat 200k / 16k / $0 / no-reasoning on every discovered model (silently wrong for proxied frontier models like `proxy/cc/claude-opus-4-7` → Opus 4.7's 1M window), bridge's `registerEntry()` runs each discovered id through pure `enrichModelMetadata(id, api, probe)` helper. Helper: (a) strips common proxy prefixes (`cc/`, `anthropic/`, `openrouter/openai/…`) so bare id tried; (b) probes pi's `modelRegistry.find(provider, id)` via ordered api-appropriate candidate list (`anthropic-messages` → `["anthropic", "opencode"]`, `google-generative-ai` → `["google", "google-vertex"]`, `openai-completions` → `["openai", "openrouter", "groq", "xai", "mistral"]`); (c) returns registry's full metadata when matched. Registry reference captured from `ctx.modelRegistry` first time pi fires `session_start` on extension (`model_select` as fallback capture point) — no direct `@earendil-works/pi-ai` import. Since `activate()` registers providers before any event handler fires, first pass uses fallback defaults; `session_start` handler re-registers all providers with enriched metadata via `pi.registerProvider`'s idempotent "replace" semantics. When registry never available or no match, fallback keeps `input: ["text","image"]` so image-capable-by-default contract preserved. Built-in + OAuth providers bypass entirely — metadata comes from pi's bundled `models.generated.js`. See `packages/extension/src/provider-register.ts` + change `enrich-custom-provider-model-metadata`.
 
 ### Testing a custom provider (Test button)
 
@@ -1675,33 +1622,6 @@ Settings → General → **Tools** renders one row per registered tool: status b
 
 See change: `consolidate-tool-resolution`.
 
-### Testing the bootstrap state space
-
-Resolution behavior intersects with HOME, platform, install layout, and pi's `settings.json` state across ~1000 combinations. Rather than hope CI on three runners plus manual QA cover all of them, the dashboard ships an in-memory harness at `packages/shared/src/__tests__/bootstrap/` that models the full cube:
-
-```
-  3 platforms  (win32, darwin, linux)
-× 5 dash-locations  (electron, npm-g, dev, managed, absent)
-× 6 pi-states  (absent, present-no-ext, present-stale-ext, present-valid, malformed, appimage-tmp)
-× 4 settings-states  (missing, empty, valid, malformed)
-× 3 env-states  (normal, spaces-unicode, home-drift)
-= 1080 cells
-```
-
-Each cell is **either** a registered test (writing a trail snapshot via `snapshotTrail`) **or** an explicit skip with a documented reason (in `scenarios-skipped.ts`). `cube.test.ts` fails CI when any cell is neither — a forcing function so that adding a new platform, a new install mechanic, or a new pi-state silently never happens.
-
-The harness is memfs-backed (no real fs, no subprocesses, no network) and runs in ~2 seconds via `npm run test:bootstrap`. The primary assertion is a normalized trail snapshot that captures strategy order, failure reasons, and `toArgv` output — which catches most bootstrap regressions before CI even reaches a real OS.
-
-Key locked-in invariants (from current snapshots):
-
-- Unix pi chain: `override → managed-bin → where` (no bare-import, no npm-g — a real limitation for GUI-launched minimal-PATH scenarios).
-- Win32 pi chain: 5-level fallback including the no-cmd-flash `.cmd` probe and `node.exe` prepend for `.js` targets.
-- Override strategy is first in every chain; invalid overrides fall through with `invalid: ...` reason.
-- Path normalization cross-OS via `<HOME>` / `<NPM_ROOT>` placeholders — snapshots stable on macOS and Linux CI.
-- **Windows bug captured**: `npm i -g pi-dashboard` + no pi → pi unresolved. Trail snapshot locks in the current broken state; `unified-bootstrap-install` will update it when the fix lands.
-
-See change: `bootstrap-resolution-harness`. Full walkthrough in `packages/shared/src/__tests__/bootstrap/README.md`.
-
 ## Path Handling (`platform/paths.ts`)
 
 Filesystem paths are OS-aware, and the dashboard touches them in three user-visible places: pin-directory storage (server), session-grouping (client), and the path picker UI (client). All three go through a single module — `packages/shared/src/platform/paths.ts` — rather than inventing their own logic.
@@ -1810,7 +1730,7 @@ See change: `eliminate-bash-on-windows-runners`.
 
 1. `attach` — health probe returns 200 within 3s on the configured port.
 2. `devMonorepo` — `!app.isPackaged AND existsSync(cwd/packages/server/src/cli.ts)`.
-3. `piExtension` — `~/.pi/agent/settings.json` has a bridge extension with resolvable server package >= `bundledMinVersion`.
+3. `piExtension` — `~/.pi/agent/settings.json#packages[]` has a bridge entry with resolvable server package >= `bundledMinVersion`. Walks `settings.packages[]` via `listPiPackages` from `pi-package-resolver.ts` (legacy `settings.extensions[]` never existed in pi schema; pre-fix probe read non-existent field and always returned null).
 4. `npmGlobal` — `which pi-dashboard` returns a real-path not under `process.resourcesPath`, version >= `bundledMinVersion`.
 5. `extracted` — always succeeds (fallback). May trigger bundle extraction from `process.resourcesPath` when version marker mismatches.
 
@@ -1820,6 +1740,10 @@ The spawned server receives `DASHBOARD_STARTER=Electron`. Lifecycle ownership ru
 
 The `LAUNCH_SOURCE_V2=false` escape hatch reverts to the legacy `mode.json` path (documented below). The flag and its legacy path will be removed in a follow-up change.
 
+**Diagnostics dual-write.** Launch-source probe diagnostics route through `logLaunchSource(level, msg)` + `appendDashboardLog(line)`. Every probe outcome writes both to stderr AND to `~/.pi/dashboard/server.log` with `[<ts>] [launch-source] <msg>` prefix. Packaged-Electron `.desktop` launches discard stderr, so the log file is the sole post-mortem trail for cold-launch probe-cascade bugs. See change: `fix-electron-cold-launch-probe-cascade`.
+
+**Extract self-heal.** `buildExtractedSource` passes `extractFs: Partial<ExtractFs>` (no no-op overrides) so `extractBundle`'s `buildFs` fills real-fs defaults for `mkdirSync`/`readdirSync`/`rmSync`/`statSync`. Selective-wipe step now clears stale absolute symlinks under `~/.pi-dashboard/node_modules/.../node_modules/.bin/X` before `cpSync`, self-healing `ERR_FS_CP_EINVAL` on any user's corrupt managed dir. See change: `fix-electron-cold-launch-probe-cascade`.
+
 ### Legacy first-launch flow (LAUNCH_SOURCE_V2=false)
 
 The Electron app's first-launch flow has three branches (escape-hatch only):
@@ -1844,7 +1768,7 @@ The Electron app's first-launch flow has three branches (escape-hatch only):
                      install
 ```
 
-The `auto-skip-wizard-with-install` branch was the source of Defect 1 in change `fix-electron-windows-installer-and-server-bootstrap`. Pre-fix, this branch wrote `mode.json` as power-user but **skipped `installStandalone()`**, leaving `~/.pi-dashboard/node_modules/` empty. The bundled server's runtime then fell back to the user's system pi for the TS loader, which on machines with `pi-coding-agent@0.71.x` ships jiti 2.6.5 — a version that misnormalizes triple-slash file:// URLs on Windows and crashes the server child with `MODULE_NOT_FOUND`.
+**Historical note** (pre-R3 only; superseded by `eliminate-electron-runtime-install`): the pre-R3 auto-skip-wizard branch wrote `mode.json` as power-user but skipped the managed install step, leaving `~/.pi-dashboard/node_modules/` empty. The bundled server's runtime then fell back to the user's system pi for the TS loader, which on machines with `pi-coding-agent@0.71.x` ships jiti 2.6.5 — misnormalizes triple-slash file:// URLs on Windows, crashes server child with `MODULE_NOT_FOUND`. Under R3, the runtime install pyramid is eliminated entirely: pi/openspec/tsx ship inside the immutable bundle, no system-pi fallback path exists.
 
 The fix:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blackbelt-technology/pi-agent-dashboard",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "description": "Web dashboard for monitoring and interacting with pi agent sessions",
   "repository": {
     "type": "git",
@@ -30,6 +30,7 @@
     ]
   },
   "files": [
+    "scripts/maybe-patch-package.cjs",
     "packages/server/src/",
     "packages/server/scripts/",
     "packages/server/package.json",
@@ -47,16 +48,17 @@
     "LICENSE"
   ],
   "scripts": {
-    "postinstall": "node packages/server/scripts/fix-pty-permissions.cjs",
+    "postinstall": "node scripts/maybe-patch-package.cjs && node packages/server/scripts/fix-pty-permissions.cjs",
     "dev": "npm run dev --workspace=@blackbelt-technology/pi-dashboard-web",
     "build": "npm run build --workspace=@blackbelt-technology/pi-dashboard-web",
     "test": "HOME=$(mktemp -d -t pi-test-XXXXXX) NODE_OPTIONS=\"--localstorage-file=$(mktemp -t pi-test-ls-XXXXXX)\" vitest run",
     "test:watch": "HOME=$(mktemp -d -t pi-test-XXXXXX) NODE_OPTIONS=\"--localstorage-file=$(mktemp -t pi-test-ls-XXXXXX)\" vitest",
-    "test:bootstrap": "HOME=$(mktemp -d -t pi-test-XXXXXX) NODE_OPTIONS=\"--localstorage-file=$(mktemp -t pi-test-ls-XXXXXX)\" vitest run packages/shared/src/__tests__/bootstrap",
-    "test:bootstrap:watch": "HOME=$(mktemp -d -t pi-test-XXXXXX) vitest packages/shared/src/__tests__/bootstrap",
+    "generate:plugin-registry": "node scripts/generate-plugin-registry.mjs",
     "lint": "tsc --noEmit",
     "reload": "./scripts/reload-all.sh",
     "reload:check": "./scripts/reload-all.sh --check",
+    "link:local": "npm link --workspace=@blackbelt-technology/pi-dashboard-server",
+    "unlink:local": "npm rm -g @blackbelt-technology/pi-dashboard-server",
     "electron:dev": "npm run start:dev --workspace=@blackbelt-technology/pi-dashboard-electron",
     "electron:start": "npm run start --workspace=@blackbelt-technology/pi-dashboard-electron",
     "electron:make": "npm run make --workspace=@blackbelt-technology/pi-dashboard-electron",
@@ -74,15 +76,16 @@
     "node": ">=22.12.0 <25"
   },
   "dependencies": {
-    "@blackbelt-technology/pi-dashboard-extension": "^0.5.3",
-    "@blackbelt-technology/pi-dashboard-server": "^0.5.3",
-    "@blackbelt-technology/pi-dashboard-web": "^0.5.3"
+    "@blackbelt-technology/pi-dashboard-extension": "^0.5.4",
+    "@blackbelt-technology/pi-dashboard-server": "^0.5.4",
+    "@blackbelt-technology/pi-dashboard-web": "^0.5.4"
   },
   "optionalDependencies": {
     "appdmg": "^0.6.6"
   },
   "devDependencies": {
     "jsdom": "^29.0.2",
+    "patch-package": "^8.0.1",
     "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.3",
+  "version": "0.5.4",
   "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.3",
+    "@blackbelt-technology/pi-dashboard-shared": "^0.5.4",
     "ws": "^8.18.0"
   },
   "peerDependencies": {

package/packages/extension/src/__tests__/bridge-default-model-gate.test.ts

@@ -0,0 +1,47 @@
+import { describe, it, expect } from "vitest";
+import { shouldApplyDefaultModel } from "../bridge-default-model-gate.js";
+
+describe("shouldApplyDefaultModel", () => {
+  const base = { hasModelRegistry: true, hasDefaultModel: true };
+
+  it("applies for a brand-new session (reason=startup, entries=0)", () => {
+    expect(shouldApplyDefaultModel({ ...base, reason: "startup", entryCount: 0 })).toBe(true);
+  });
+
+  it("does NOT apply for resumed sessions (entries>0, reason=startup)", () => {
+    expect(shouldApplyDefaultModel({ ...base, reason: "startup", entryCount: 5 })).toBe(false);
+  });
+
+  it("does NOT apply for in-process new (reason=new)", () => {
+    // pi handles its own default for in-process /new — bridge stays out
+    expect(shouldApplyDefaultModel({ ...base, reason: "new", entryCount: 0 })).toBe(false);
+  });
+
+  it("does NOT apply for in-process resume (reason=resume)", () => {
+    expect(shouldApplyDefaultModel({ ...base, reason: "resume", entryCount: 5 })).toBe(false);
+  });
+
+  it("does NOT apply for in-process fork (reason=fork)", () => {
+    expect(shouldApplyDefaultModel({ ...base, reason: "fork", entryCount: 5 })).toBe(false);
+  });
+
+  it("does NOT apply for reload of in-flight session (reason=reload, entries>0)", () => {
+    expect(shouldApplyDefaultModel({ ...base, reason: "reload", entryCount: 5 })).toBe(false);
+  });
+
+  it("does NOT apply when defaultModel is not configured", () => {
+    expect(
+      shouldApplyDefaultModel({ ...base, hasDefaultModel: false, reason: "startup", entryCount: 0 }),
+    ).toBe(false);
+  });
+
+  it("does NOT apply when model registry not yet available", () => {
+    expect(
+      shouldApplyDefaultModel({ ...base, hasModelRegistry: false, reason: "startup", entryCount: 0 }),
+    ).toBe(false);
+  });
+
+  it("does NOT apply when reason is undefined", () => {
+    expect(shouldApplyDefaultModel({ ...base, reason: undefined, entryCount: 0 })).toBe(false);
+  });
+});