@blackbelt-technology/pi-agent-dashboard 0.2.9 → 0.4.0

package/packages/server/src/server.ts

@@ -4,6 +4,7 @@
 import Fastify from "fastify";
 import fastifyStatic from "@fastify/static";
 import cors from "@fastify/cors";
+import compress from "@fastify/compress";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import os from "node:os";
@@ -29,7 +30,7 @@ import { createIdleTimer } from "./idle-timer.js";
 import { discoverAndBroadcastSessions } from "./session-bootstrap.js";
 import { scanAllSessions } from "./session-scanner.js";
 import { needsMigration, runMigration } from "./migrate-persistence.js";
-import { detectZrokBinary, cleanupStaleZrok, createTunnel, deleteTunnel } from "./tunnel.js";
+import { detectZrokBinary, cleanupStaleZrok, createTunnel, deleteTunnel, scavengeOrphanZrokProcesses, getTunnelUrl } from "./tunnel.js";
 import { registerAuthPlugin, validateWsUpgrade } from "./auth-plugin.js";
 import { findBundledExtension, registerBridgeExtension } from "@blackbelt-technology/pi-dashboard-shared/bridge-register.js";
 import { createNetworkGuard, isLoopback, isBypassedHost } from "./localhost-guard.js";
@@ -42,9 +43,20 @@ import { registerOpenSpecRoutes } from "./routes/openspec-routes.js";
 import { registerSystemRoutes } from "./routes/system-routes.js";
 import { registerProviderAuthRoutes } from "./routes/provider-auth-routes.js";
 import { registerPackageRoutes } from "./routes/package-routes.js";
+import { registerRecommendedRoutes, invalidateRecommendedCache } from "./routes/recommended-routes.js";
+import { registerPiCoreRoutes } from "./routes/pi-core-routes.js";
+import { PiCoreChecker } from "./pi-core-checker.js";
+import { PiCoreUpdater } from "./pi-core-updater.js";
+import { registerToolRoutes } from "./routes/tool-routes.js";
+import { registerBootstrapRoutes } from "./routes/bootstrap-routes.js";
+import { createBootstrapState, type BootstrapStateStore } from "./bootstrap-state.js";
+import { createBootstrapQueue } from "./bootstrap-queue.js";
+import { bootstrapInstall } from "@blackbelt-technology/pi-dashboard-shared/bootstrap-install.js";
+import { getDefaultRegistry } from "@blackbelt-technology/pi-dashboard-shared/tool-registry/index.js";
 import { registerProviderRoutes } from "./routes/provider-routes.js";
 import { PackageManagerWrapper } from "./package-manager-wrapper.js";
 import { createEditorManager, type EditorManager } from "./editor-manager.js";
+import { createEditorPidRegistry } from "./editor-pid-registry.js";
 import { registerEditorRoutes } from "./routes/editor-routes.js";
 import { registerKnownServersRoutes } from "./routes/known-servers-routes.js";
 import { registerEditorProxy, handleEditorUpgrade } from "./editor-proxy.js";
@@ -67,6 +79,8 @@ export interface ServerConfig {
   maxWsBufferBytes?: number;
   /** Editor (code-server) config */
   editor: import("@blackbelt-technology/pi-dashboard-shared/config.js").EditorConfig;
+  /** OpenSpec polling config (interval, concurrency, change detection, jitter) */
+  openspec?: import("@blackbelt-technology/pi-dashboard-shared/config.js").OpenSpecPollConfig;
   /** Merged trusted networks from config */
   resolvedTrustedNetworks?: string[];
   /** CORS allowed origins from config */
@@ -79,14 +93,37 @@ export interface DashboardServer {
   sessionManager: SessionManager;
   eventStore: EventStore;
   browserGateway: BrowserGateway;
+  /**
+   * Bootstrap state store. Exposed so the CLI can flip status during
+   * degraded-mode first-run (`pi-dashboard` without pi installed) and
+   * so the REST handler for `/api/bootstrap/upgrade-pi` can orchestrate
+   * async installs without reaching back through closures.
+   * See change: unified-bootstrap-install.
+   */
+  bootstrapState: BootstrapStateStore;
+  /** Resolved HTTP port after start() (useful for port:0 in tests). Returns null if not listening. */
+  httpPort(): number | null;
+  /** Resolved pi gateway port after start(). Returns null if not listening. */
+  piPort(): number | null;
 }
 
 export async function createServer(config: ServerConfig): Promise<DashboardServer> {
   // Ensure bridge extension is registered in pi's global settings
   // (needed for bundled installs where pi can't discover it from package.json)
+  //
+  // __serverDir = <repo>/packages/server/src
+  // baseDir MUST be <repo>/ so findBundledExtension resolves
+  // <repo>/packages/extension. Three levels up, not two.
   const __serverDir = path.dirname(fileURLToPath(import.meta.url));
-  const extPath = findBundledExtension(path.resolve(__serverDir, "..", ".."));
-  if (extPath) registerBridgeExtension(extPath);
+  const extPath = findBundledExtension(path.resolve(__serverDir, "..", "..", ".."));
+  if (extPath) {
+    registerBridgeExtension(extPath);
+    console.log(`[dashboard] Bridge extension registered: ${extPath}`);
+  } else {
+    console.warn(`[dashboard] Bridge extension NOT found (searched from ${__serverDir}). ` +
+      `Sessions will spawn but never connect to the gateway. ` +
+      `Manually add the extension path to ~/.pi/agent/settings.json packages[] as a workaround.`);
+  }
 
   // Run migration from sessions.json + state.json if needed
   if (needsMigration()) {
@@ -151,7 +188,7 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
     knownSessionIds.add(s.id);
   }
 
-  const directoryService = createDirectoryService(preferencesStore, sessionManager);
+  const directoryService = createDirectoryService(preferencesStore, sessionManager, config.openspec);
 
   // mDNS peer discovery state
   let mdnsBrowser: DashboardBrowser | null = null;
@@ -190,9 +227,11 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
 
   // Create editor manager for code-server instances
   const editorDetection = detectCodeServerBinary(config.editor);
+  const editorPidRegistry = createEditorPidRegistry();
   const editorManager = createEditorManager({
     config: config.editor,
     detection: editorDetection,
+    pidRegistry: editorPidRegistry,
     onStatusChange: (cwd, id, status) => {
       browserGateway.broadcastToAll({ type: "editor_status", cwd, id, status });
     },
@@ -243,23 +282,62 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
     connectionTimeout: 10_000,
   });
 
-  // CORS: allow localhost by default + configured origins
+  // Compression: gzip/deflate for HTTP responses. Critical for large client
+  // bundles (~3 MB JS) served over tunnels like zrok which abort big transfers.
+  // Brotli is intentionally disabled — zrok's free public proxy has been
+  // observed to truncate/stream-reset `content-encoding: br` responses under
+  // parallel browser load (curl succeeds, Chrome reports ERR_ABORTED 500).
+  // gzip is universally supported and round-trips cleanly through zrok.
+  // threshold=1024 skips tiny responses; global=true compresses all routes.
+  await fastify.register(compress, {
+    global: true,
+    threshold: 1024,
+    encodings: ["gzip", "deflate"],
+  });
+
+  // CORS: allow localhost, the active zrok tunnel URL, any *.share.zrok.io
+  // host (so tunnel URL rotation doesn't break loads), and configured origins.
+  //
+  // Two critical correctness notes:
+  // (1) Vite emits `<script type="module" crossorigin>` tags, which browsers
+  //     always request in CORS mode — even when same-origin. If the server
+  //     doesn't emit `Access-Control-Allow-Origin` for the request's own
+  //     origin, the browser aborts the script with ERR_ABORTED 500. So when
+  //     accessed via a tunnel URL, that URL MUST be in the allow list or all
+  //     asset loads fail in the browser (while curl — which sends no Origin
+  //     header — works fine). This is the exact failure mode that looked
+  //     like a zrok problem for hours of debugging.
+  // (2) On origin mismatch, return `cb(null, false)` (no CORS headers) rather
+  //     than `cb(new Error(…), false)`. The latter causes @fastify/cors to
+  //     surface the error as HTTP 500 on every asset — far worse than
+  //     silently omitting CORS headers and letting the browser enforce its
+  //     own same-origin policy.
   const corsAllowedOrigins = config.corsAllowedOrigins ?? [];
   await fastify.register(cors, {
     origin: (origin, cb) => {
-      // Same-origin (no Origin header) — always allow
+      // Same-origin navigation (no Origin header) — always allow.
       if (!origin) return cb(null, true);
-      // Localhost / 127.0.0.1 / [::1] — any port
       try {
         const u = new URL(origin);
         const host = u.hostname;
+        // Loopback — any port.
         if (host === "localhost" || host === "127.0.0.1" || host === "[::1]" || host === "::1") {
           return cb(null, true);
         }
-      } catch { /* ignore parse errors */ }
-      // Configured origins
+        // Active zrok tunnel URL — checked dynamically so URL rotation is
+        // picked up without a server restart.
+        const tunnelUrl = getTunnelUrl();
+        if (tunnelUrl && origin === tunnelUrl) return cb(null, true);
+        // Any *.share.zrok.io host — covers the brief window between a new
+        // reservation being created and the in-memory `activeTunnelUrl`
+        // being populated, plus any other zrok share the user points at us.
+        if (host.endsWith(".share.zrok.io")) return cb(null, true);
+      } catch { /* ignore URL parse errors */ }
+      // Explicitly configured origins.
       if (corsAllowedOrigins.includes(origin)) return cb(null, true);
-      cb(new Error("CORS origin not allowed"), false);
+      // Unknown cross-origin request — don't emit CORS headers, but don't
+      // 500 either. Browser will block the request for us.
+      cb(null, false);
     },
     credentials: true,
   });
@@ -278,6 +356,33 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
     fastify.get("/auth/status", async () => ({ authenticated: true, authEnabled: false }));
   }
 
+  // ── Bootstrap state + queue ──────────────────────────────────────
+  // Declared here (before session-api registration) so the session
+  // routes can gate spawn operations on bootstrap status.
+  // See change: unified-bootstrap-install.
+  const bootstrapState = createBootstrapState();
+  const bootstrapQueue = createBootstrapQueue();
+  let lastBootstrapStatus: "ready" | "installing" | "failed" = "ready";
+  const unsubscribeBootstrap = bootstrapState.subscribe((snapshot) => {
+    browserGateway.broadcastToAll({
+      type: "bootstrap_status_update",
+      state: snapshot,
+    });
+    // Flush queued pi-dependent operations on ready transition.
+    if (lastBootstrapStatus !== "ready" && snapshot.status === "ready") {
+      void bootstrapQueue.flushAll();
+    }
+    lastBootstrapStatus = snapshot.status;
+  });
+  const unsubscribeQueueComplete = bootstrapQueue.onTicketComplete((evt) => {
+    browserGateway.broadcastToAll({
+      type: "bootstrap_ticket_complete",
+      ticketId: evt.ticketId,
+      success: evt.success,
+      error: evt.error,
+    });
+  });
+
   // Session control REST API (wraps WebSocket-only operations)
   registerSessionApi(fastify, {
     sessionManager,
@@ -285,6 +390,8 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
     browserGateway,
     pendingForkRegistry,
     pendingDashboardSpawns,
+    bootstrapState,
+    bootstrapQueue,
   });
 
   // Register route modules
@@ -294,8 +401,123 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
   registerSessionRoutes(fastify, { sessionManager, eventStore, networkGuard });
   registerGitRoutes(fastify, { networkGuard });
   registerFileRoutes(fastify, { sessionManager, preferencesStore, networkGuard });
-  registerOpenSpecRoutes(fastify, { sessionManager, preferencesStore, directoryService, networkGuard });
-  registerSystemRoutes(fastify, { sessionManager, preferencesStore, metaPersistence, config, networkGuard, version: pkgVersion });
+  registerOpenSpecRoutes(fastify, {
+    sessionManager,
+    preferencesStore,
+    directoryService,
+    networkGuard,
+    bootstrapState,
+    onOpenSpecChanged: (cwd) => {
+      const data = directoryService.getOpenSpecData(cwd);
+      if (data) browserGateway.broadcastToAll({ type: "openspec_update", cwd, data });
+    },
+  });
+  registerSystemRoutes(fastify, { sessionManager, preferencesStore, metaPersistence, config, networkGuard, version: pkgVersion, directoryService });
+  registerToolRoutes(fastify, { registry: getDefaultRegistry(), networkGuard });
+
+  // ── Bootstrap REST routes ────────────────────────────────────────
+  // The routes module is registered here; state + queue are declared
+  // above (before session-api) so session routes can see them.
+  registerBootstrapRoutes(fastify, {
+    bootstrapState,
+    networkGuard,
+    triggerUpgradePi: async () => {
+      const packages = ["@mariozechner/pi-coding-agent"];
+      bootstrapState.setLastInstallPackages(packages);
+      bootstrapState.set({
+        status: "installing",
+        progress: { step: "@mariozechner/pi-coding-agent", output: "starting upgrade…" },
+        error: undefined,
+      });
+      try {
+        const res = await bootstrapInstall({
+          packages,
+          progress: (p) => {
+            bootstrapState.set({
+              progress: { step: p.step, output: p.output },
+            });
+          },
+        });
+        if (res.ok) {
+          bootstrapState.set({
+            status: "ready",
+            progress: undefined,
+            error: undefined,
+          });
+          // Broadcast /reload to connected sessions so they pick up the
+          // new pi version. Mirrors the pi-core update pattern above.
+          const connectedIds = piGateway.getConnectedSessionIds();
+          for (const sid of connectedIds) {
+            const session = sessionManager.get(sid);
+            if (session && session.status !== "ended") {
+              piGateway.sendToSession(sid, {
+                type: "send_prompt",
+                sessionId: sid,
+                text: "/reload",
+              });
+            }
+          }
+        } else {
+          bootstrapState.set({
+            status: "failed",
+            error: { message: res.error },
+            progress: undefined,
+          });
+        }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        bootstrapState.set({
+          status: "failed",
+          error: { message },
+          progress: undefined,
+        });
+      }
+    },
+    triggerRetry: async () => {
+      // Retry re-runs the EXACT package set from the last failed install.
+      // Falls back to the default first-run set if no prior install was
+      // recorded (edge case: manual retry before any install attempt).
+      const prev = bootstrapState.getLastInstallPackages();
+      const packages = prev.length > 0
+        ? prev
+        : ["@mariozechner/pi-coding-agent", "@fission-ai/openspec", "tsx"];
+      bootstrapState.set({
+        status: "installing",
+        progress: { step: "retry", output: `restarting install (${packages.length} pkg${packages.length === 1 ? "" : "s"})…` },
+        error: undefined,
+      });
+      try {
+        const res = await bootstrapInstall({
+          packages,
+          progress: (p) => {
+            bootstrapState.set({
+              progress: { step: p.step, output: p.output },
+            });
+          },
+        });
+        if (res.ok) {
+          bootstrapState.set({
+            status: "ready",
+            progress: undefined,
+            error: undefined,
+          });
+        } else {
+          bootstrapState.set({
+            status: "failed",
+            error: { message: res.error },
+            progress: undefined,
+          });
+        }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        bootstrapState.set({
+          status: "failed",
+          error: { message },
+          progress: undefined,
+        });
+      }
+    },
+  });
   // Package management
   const packageManagerWrapper = new PackageManagerWrapper();
 
@@ -304,7 +526,7 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
     browserGateway.broadcastToAll({ type: "package_progress", operationId, event } as any);
   });
 
-  // On completion: broadcast to browsers
+  // On completion: broadcast to browsers + invalidate the recommended cache
   packageManagerWrapper.setCompleteListener((result) => {
     browserGateway.broadcastToAll({
       type: "package_operation_complete",
@@ -314,8 +536,10 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
       scope: result.scope,
       success: result.success,
       error: result.error,
+      diagnostics: result.diagnostics,
       sessionsReloaded: (result as any).sessionsReloaded,
     } as any);
+    if (result.success) invalidateRecommendedCache();
   });
 
   // Reload all active sessions after a successful package operation
@@ -337,26 +561,105 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
   });
 
   registerPackageRoutes(fastify, { packageManagerWrapper });
+  registerRecommendedRoutes(fastify, { packageManagerWrapper });
+
+  // Pi core version check + update (complements the extension package manager).
+  const piCoreChecker = new PiCoreChecker();
+  const piCoreUpdater = new PiCoreUpdater({
+    packageManagerWrapper,
+    onAllComplete: async () => {
+      const connectedIds = piGateway.getConnectedSessionIds();
+      let count = 0;
+      for (const sid of connectedIds) {
+        const session = sessionManager.get(sid);
+        if (session && session.status !== "ended") {
+          piGateway.sendToSession(sid, {
+            type: "send_prompt",
+            sessionId: sid,
+            text: "/reload",
+          });
+          count++;
+        }
+      }
+      return count;
+    },
+  });
+  piCoreUpdater.setProgressListener((event) => {
+    browserGateway.broadcastToAll({
+      type: "pi_core_update_progress",
+      name: event.name,
+      phase: event.phase,
+      message: event.message,
+    });
+  });
+  registerPiCoreRoutes(fastify, {
+    piCoreChecker,
+    piCoreUpdater,
+    bootstrapState,
+    onUpdateComplete: (payload) => {
+      browserGateway.broadcastToAll({
+        type: "pi_core_update_complete",
+        results: payload.results,
+        sessionsReloaded: payload.sessionsReloaded,
+      });
+    },
+  });
 
-  // Editor (code-server) routes and proxy
+  // Warm pi-coding-agent module import + DefaultPackageManager instances
+  // on startup so the first user request to /api/packages/* doesn't pay
+  // the 3-5s cold-load cost. Runs in background; errors are swallowed
+  // (user-visible flow surfaces any real problem with the full diagnostic
+  // trail via the OperationResult.diagnostics field).
+  // See change: consolidate-tool-resolution.
+  void Promise.allSettled([
+    packageManagerWrapper.listInstalled("global"),
+    packageManagerWrapper.listInstalled("local"),
+  ]);
+
+  // Editor (code-server) routes and proxy.
+  // NOTE: routes are *registered* here but cannot dispatch until fastify.listen runs
+  // inside server.start(). The orphan sweep in editorPidRegistry.cleanupOrphans()
+  // runs at the top of server.start() BEFORE fastify.listen, so any
+  // POST /api/editor/start call is guaranteed to see a post-sweep clean state.
   registerEditorRoutes(fastify, editorManager, { networkGuard });
   registerEditorProxy(fastify, editorManager);
 
-  registerProviderAuthRoutes(fastify, { piGateway });
+  registerProviderAuthRoutes(fastify, { piGateway, browserGateway });
   registerKnownServersRoutes(fastify, { networkGuard, getPeerServers: () => peerServers });
-  registerProviderRoutes(fastify, { networkGuard });
-
-  // Serve static files / SPA fallback
-  // Search order: npm package → workspace sibling → legacy dist/client
+  registerProviderRoutes(fastify, { networkGuard, piGateway, browserGateway });
+
+  // Serve static files / SPA fallback.
+  //
+  // Resolution strategies, in order:
+  //  1. Node module resolver — works in ANY install layout
+  //     (flat `node_modules/`, scoped, nested, pnpm, whatever).
+  //  2. Sibling-to-server in the installed @scope layout.
+  //  3. Monorepo workspace sibling.
+  //  4. Legacy dist/client.
+  //
+  // Same class of bug as commits 40a1319 (bridge auto-registration)
+  // and e11f5eb (server-launcher.ts resolve): sibling-path arithmetic
+  // that works in the dev repo silently returns wrong paths in the
+  // installed node_modules layout. require.resolve identifies packages
+  // by name, which is the only canonical identity across layouts.
   const __dirname = path.dirname(fileURLToPath(import.meta.url));
-  const clientSearchPaths = [
-    // Installed as npm dependency
-    path.join(__dirname, "../../node_modules/@blackbelt-technology/pi-dashboard-web/dist"),
+  const clientSearchPaths: string[] = [];
+  try {
+    const webPkgJson = createRequire(import.meta.url).resolve("@blackbelt-technology/pi-dashboard-web/package.json");
+    clientSearchPaths.push(path.join(path.dirname(webPkgJson), "dist"));
+  } catch {
+    // Web package not resolvable — fall through to path-based search.
+  }
+  clientSearchPaths.push(
+    // Installed as scoped sibling of server
+    path.join(__dirname, "..", "..", "pi-dashboard-web", "dist"),
+    // Installed in a parent node_modules (hoisted)
+    path.join(__dirname, "..", "..", "..", "@blackbelt-technology", "pi-dashboard-web", "dist"),
     // Monorepo workspace sibling
     path.join(__dirname, "../../client/dist"),
     // Legacy path
     path.join(__dirname, "../../dist/client"),
-  ];
+  );
   const clientDir = clientSearchPaths.find(p => existsSync(path.join(p, "index.html"))) ?? "";
   const hasProductionBuild = !!clientDir;
   if (!hasProductionBuild) {
@@ -371,6 +674,13 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
     await fastify.register(fastifyStatic, {
       root: clientDir,
       prefix: "/",
+      // Serve pre-compressed sibling files (assets/foo.js.gz alongside foo.js)
+      // directly when the client accepts gzip. This gives every compressed
+      // response a stable Content-Length header — dynamic compression via
+      // @fastify/compress streams responses without Content-Length, which
+      // some HTTP/2 proxy chains (notably zrok free-tier) occasionally
+      // stream-reset as ERR_ABORTED 500 in browsers.
+      preCompressed: true,
       setHeaders: (res, filePath) => {
         if (filePath.endsWith(".html")) {
           res.setHeader("Cache-Control", "no-cache, no-store, must-revalidate");
@@ -434,11 +744,25 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
     sessionManager,
     eventStore,
     browserGateway,
+    bootstrapState,
+
+    httpPort() {
+      const addr = fastify.server.address();
+      if (addr && typeof addr === "object") return addr.port;
+      return null;
+    },
+    piPort() {
+      return piGateway.address();
+    },
 
     async start() {
       // Clean up orphan headless processes from a previous server instance
       browserGateway.headlessPidRegistry.cleanupOrphans();
 
+      // Clean up orphan code-server processes from a previous server instance.
+      // Runs before fastify.listen, so no editor start request can race with the sweep.
+      await editorPidRegistry.cleanupOrphans();
+
       piGateway.start(config.piPort);
 
       fastify.server.on("upgrade", (request, socket, head) => {
@@ -501,10 +825,19 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
         console.warn(`mDNS browser failed (peer discovery disabled):`, err);
       }
 
+      // Always sweep leftover zrok processes on startup, even when tunnel is
+      // disabled (--no-tunnel). Orphans from a previous run hold reservations
+      // on the zrok edge and keep old URLs "alive but broken" until their
+      // agents are killed. Scavenge runs unconditionally when the binary is
+      // present; the tunnel-creation branch below is gated separately.
+      const hasZrok = detectZrokBinary();
+      if (hasZrok) {
+        cleanupStaleZrok();
+        scavengeOrphanZrokProcesses(config.port);
+      }
+
       if (config.tunnel) {
-        const hasZrok = detectZrokBinary();
         if (hasZrok) {
-          cleanupStaleZrok();
           const tunnelUrl = await createTunnel(config.port, config.tunnelReservedToken);
           if (tunnelUrl) {
             console.log(`🌐 Tunnel: ${tunnelUrl}`);
@@ -534,7 +867,11 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
       preferencesStore.flush();
       preferencesStore.dispose();
 
-      await deleteTunnel();
+      unsubscribeBootstrap();
+      unsubscribeQueueComplete();
+      bootstrapState.dispose();
+      bootstrapQueue.clear("server shutting down");
+      await deleteTunnel(config.port);
       piGateway.stop();
       for (const client of browserGateway.wss.clients) {
         client.terminate();

package/packages/server/src/session-api.ts

@@ -11,6 +11,8 @@ import type { ApiResponse } from "@blackbelt-technology/pi-dashboard-shared/type
 import { spawnPiSession } from "./process-manager.js";
 import { loadConfig } from "@blackbelt-technology/pi-dashboard-shared/config.js";
 import type { PendingForkRegistry } from "./pending-fork-registry.js";
+import type { BootstrapStateStore } from "./bootstrap-state.js";
+import type { BootstrapQueue } from "./bootstrap-queue.js";
 
 export interface SessionApiDeps {
   sessionManager: SessionManager;
@@ -18,6 +20,13 @@ export interface SessionApiDeps {
   browserGateway: BrowserGateway;
   pendingForkRegistry?: PendingForkRegistry;
   pendingDashboardSpawns?: Map<string, number>;
+  /**
+   * Bootstrap state + queue for degraded-mode gating. When omitted,
+   * session operations run normally (legacy behavior for tests that
+   * don't exercise the bootstrap flow). See change: unified-bootstrap-install.
+   */
+  bootstrapState?: BootstrapStateStore;
+  bootstrapQueue?: BootstrapQueue;
 }
 
 type IdParams = { Params: { id: string } };
@@ -30,7 +39,54 @@ function getSessionOrFail(sessionManager: SessionManager, id: string): { session
 }
 
 export function registerSessionApi(fastify: FastifyInstance, deps: SessionApiDeps) {
-  const { sessionManager, piGateway, browserGateway, pendingForkRegistry, pendingDashboardSpawns } = deps;
+  const { sessionManager, piGateway, browserGateway, pendingForkRegistry, pendingDashboardSpawns, bootstrapState, bootstrapQueue } = deps;
+
+  /**
+   * Gate pi-dependent operations on bootstrap status. Returns:
+   *   - null when ready (proceed).
+   *   - `{ code: 202, body: { status: "queued", ticketId } }` when installing;
+   *     the operation is enqueued and will run once status flips to "ready".
+   *   - `{ code: 503, body: { error } }` when failed.
+   * See change: unified-bootstrap-install §5.
+   */
+  function gateOrEnqueue<T>(handler: () => Promise<T>):
+    | null
+    | { code: 202; body: { status: "queued"; ticketId: string } }
+    | { code: 503; body: { error: string; bootstrap: "failed" | "version-too-old" } } {
+    if (!bootstrapState) return null;
+    const snap = bootstrapState.get();
+    // Block when pi version is below the configured minimum —
+    // even when status is "ready", a too-old pi must not run sessions.
+    // See change: unified-bootstrap-install §9.3.
+    if (
+      snap.status === "ready"
+      && snap.error?.message?.startsWith("pi version ")
+    ) {
+      return {
+        code: 503,
+        body: { error: snap.error.message, bootstrap: "version-too-old" },
+      };
+    }
+    if (snap.status === "ready") return null;
+    if (snap.status === "installing") {
+      if (!bootstrapQueue) {
+        return {
+          code: 202,
+          body: { status: "queued", ticketId: "" },
+        };
+      }
+      const ticket = bootstrapQueue.enqueue(handler);
+      return {
+        code: 202,
+        body: { status: "queued", ticketId: ticket.ticketId },
+      };
+    }
+    // status === "failed"
+    return {
+      code: 503,
+      body: { error: "pi not installed (bootstrap failed)", bootstrap: "failed" },
+    };
+  }
 
   // POST /api/session/:id/prompt
   fastify.post<IdParams & { Body: { text?: string; images?: any[] } }>(
@@ -160,14 +216,27 @@ export function registerSessionApi(fastify: FastifyInstance, deps: SessionApiDep
         reply.code(400);
         return { success: false, error: "cwd is required" } satisfies ApiResponse;
       }
-      const config = loadConfig();
-      const spawnResult = await spawnPiSession(cwd, { strategy: config.spawnStrategy });
-      if (spawnResult.process && spawnResult.pid) {
-        browserGateway.headlessPidRegistry.register(spawnResult.pid, cwd, spawnResult.process);
-      }
-      if (spawnResult.dashboardSpawned && spawnResult.success) {
-        pendingDashboardSpawns?.set(cwd, (pendingDashboardSpawns?.get(cwd) ?? 0) + 1);
+
+      const doSpawn = async () => {
+        const config = loadConfig();
+        const spawnResult = await spawnPiSession(cwd, { strategy: config.spawnStrategy });
+        if (spawnResult.process && spawnResult.pid) {
+          browserGateway.headlessPidRegistry.register(spawnResult.pid, cwd, spawnResult.process);
+        }
+        if (spawnResult.dashboardSpawned && spawnResult.success) {
+          pendingDashboardSpawns?.set(cwd, (pendingDashboardSpawns?.get(cwd) ?? 0) + 1);
+        }
+        return spawnResult;
+      };
+
+      // Bootstrap gate: if pi isn't ready, queue the spawn and return 202.
+      const gate = gateOrEnqueue(doSpawn);
+      if (gate) {
+        reply.code(gate.code);
+        return gate.body;
       }
+
+      const spawnResult = await doSpawn();
       if (!spawnResult.success) {
         reply.code(500);
         return { success: false, error: spawnResult.message } satisfies ApiResponse;