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

package/packages/server/src/bootstrap-install-from-list.ts

@@ -0,0 +1,232 @@
+/**
+ * Bootstrap install reconciler driven by ~/.pi/dashboard/installable.json.
+ * Invoked by cli.ts before app.listen.
+ *
+ * File-absent path is a deliberate no-op: Bridge and Standalone starters
+ * never write installable.json; only Electron seeds it on first run.
+ * When the file is absent, this function logs and returns immediately so
+ * bootstrap.status transitions to "ready" without delay.
+ *
+ * See change: simplify-electron-bootstrap-derived-state.
+ */
+import os from "node:os";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { getManagedDir } from "@blackbelt-technology/pi-dashboard-shared/managed-paths.js";
+import {
+  readInstallableList,
+  type InstallablePackage,
+} from "@blackbelt-technology/pi-dashboard-shared/installable-list.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 type { BootstrapStateStore } from "./bootstrap-state.js";
+
+// ── Injectable helpers (overridable in tests) ──────────────────────────────
+
+export type InstallProgressCallback = (line: string) => void;
+export type PackageInstaller = (
+  pkg: InstallablePackage,
+  onOutput: InstallProgressCallback,
+) => Promise<void>;
+
+// ── Installed-check ────────────────────────────────────────────────────────
+
+/**
+ * Return true if `pkgName` is resolvable from `managedDir/node_modules`.
+ * Version satisfies check is intentionally omitted (no semver dep) —
+ * we treat "resolves at all" as satisfied. This is sufficient for the
+ * Phase B bootstrap use case.
+ */
+export function isNpmPackageInstalled(pkgName: string, managedDir: string): boolean {
+  try {
+    // createRequire resolves from the given path; look in managedDir/node_modules.
+    const req = createRequire(path.join(managedDir, "package.json"));
+    req.resolve(pkgName + "/package.json");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ── Default installers ─────────────────────────────────────────────────────
+
+async function defaultNpmInstall(
+  pkg: InstallablePackage,
+  managedDir: string,
+  onOutput: InstallProgressCallback,
+): Promise<void> {
+  const spec =
+    pkg.version && pkg.version !== "*"
+      ? `${pkg.name}@${pkg.version}`
+      : pkg.name;
+  const res = await bootstrapInstall({
+    packages: [spec],
+    managedDir,
+    progress: (p) => {
+      if (p.output) onOutput(p.output);
+    },
+  });
+  if (!res.ok) {
+    throw new Error(res.error);
+  }
+}
+
+async function defaultPiExtensionInstall(
+  pkg: InstallablePackage,
+  onOutput: InstallProgressCallback,
+): Promise<void> {
+  const registry = getDefaultRegistry();
+  const { module: piModule } = await registry.resolveModule<{
+    DefaultPackageManager: any;
+    SettingsManager: any;
+  }>("pi-coding-agent");
+  const agentDir = path.join(os.homedir(), ".pi", "agent");
+  const settingsManager = piModule.SettingsManager.create(process.cwd(), agentDir);
+  const pm = new piModule.DefaultPackageManager({
+    cwd: process.cwd(),
+    agentDir,
+    settingsManager,
+  });
+  pm.setProgressCallback((event: { message?: string }) => {
+    if (event.message) onOutput(event.message);
+  });
+  await pm.installAndPersist(pkg.name, { local: false });
+}
+
+// ── Options ────────────────────────────────────────────────────────────────
+
+export interface BootstrapInstallFromListOptions {
+  /** Override config dir for installable.json (default: ~/.pi/dashboard/). */
+  configDir?: string;
+  /** Override managed dir for npm installs (default: ~/.pi-dashboard/). */
+  managedDir?: string;
+  /**
+   * Injectable npm installer. Defaults to bootstrapInstall.
+   * Receives the InstallablePackage and a streaming output callback.
+   */
+  npmInstall?: PackageInstaller;
+  /**
+   * Injectable pi-extension installer. Defaults to pi DefaultPackageManager.
+   * Receives the InstallablePackage and a streaming output callback.
+   */
+  piInstall?: PackageInstaller;
+  /**
+   * Injectable installed-check for npm packages.
+   * Defaults to isNpmPackageInstalled.
+   */
+  isInstalled?: (pkg: InstallablePackage, managedDir: string) => boolean;
+}
+
+// ── Main reconciler ────────────────────────────────────────────────────────
+
+/**
+ * Reconcile packages from installable.json against the managed directory.
+ *
+ * - File absent: log and return immediately (not a failure).
+ * - Per package: check installed → skip or install.
+ * - Required failure: set bootstrap status=failed, throw (abort server start).
+ * - Optional failure: log, record in failed[], continue.
+ */
+export async function bootstrapInstallFromList(
+  bootstrapState: BootstrapStateStore,
+  opts?: BootstrapInstallFromListOptions,
+): Promise<void> {
+  const configDir =
+    opts?.configDir ?? path.join(os.homedir(), ".pi", "dashboard");
+  const managedDir = opts?.managedDir ?? getManagedDir();
+
+  // Read installable.json; absent file is a deliberate no-op.
+  const list = await readInstallableList(configDir);
+  if (list === null) {
+    console.log(
+      "[bootstrap] bootstrap.installable.skipped reason=file-not-found",
+    );
+    return;
+  }
+
+  // Only process packages that are active (not deprecated, not defaultOff).
+  const packages = list.packages.filter((p) => !p.deprecated && !p.defaultOff);
+  const total = packages.length;
+  let installedCount = 0;
+  const failed: string[] = [];
+
+  // Stamp initial installable progress into bootstrap state.
+  bootstrapState.set({ installable: { total, installed: 0, failed: [] } });
+
+  const checkInstalled =
+    opts?.isInstalled ?? ((p, dir) => isNpmPackageInstalled(p.name, dir));
+  const doNpmInstall: PackageInstaller =
+    opts?.npmInstall ??
+    ((p, cb) => defaultNpmInstall(p, managedDir, cb));
+  const doPiInstall: PackageInstaller =
+    opts?.piInstall ?? defaultPiExtensionInstall;
+
+  for (const pkg of packages) {
+    // Fast path: already installed (npm packages only; pi-extension always attempts).
+    if (pkg.kind === "npm" && checkInstalled(pkg, managedDir)) {
+      console.log(
+        `[bootstrap] bootstrap.installable.package name=${pkg.name} status=satisfied`,
+      );
+      installedCount++;
+      bootstrapState.set({
+        installable: { total, installed: installedCount, failed },
+      });
+      continue;
+    }
+
+    // Emit installing progress.
+    bootstrapState.set({
+      progress: { step: pkg.name, output: "installing..." },
+      installable: { total, installed: installedCount, failed },
+    });
+
+    try {
+      const onOutput = (line: string): void => {
+        bootstrapState.set({ progress: { step: pkg.name, output: line } });
+      };
+
+      if (pkg.kind === "npm") {
+        await doNpmInstall(pkg, onOutput);
+      } else {
+        await doPiInstall(pkg, onOutput);
+      }
+
+      installedCount++;
+      bootstrapState.set({
+        progress: undefined,
+        installable: { total, installed: installedCount, failed },
+      });
+      console.log(
+        `[bootstrap] bootstrap.installable.package name=${pkg.name} status=done`,
+      );
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error(
+        `[bootstrap] bootstrap.installable.package name=${pkg.name} status=error error=${message}`,
+      );
+      failed.push(pkg.name);
+      bootstrapState.set({
+        progress: undefined,
+        installable: { total, installed: installedCount, failed: [...failed] },
+      });
+
+      if (pkg.required) {
+        const errorMessage = `Required package "${pkg.name}" failed to install: ${message}`;
+        bootstrapState.set({
+          status: "failed",
+          error: { message: errorMessage },
+        });
+        throw new Error(errorMessage);
+      }
+      // Optional package failure: log, continue to next package.
+    }
+  }
+
+  // Final state snapshot.
+  bootstrapState.set({
+    installable: { total, installed: installedCount, failed },
+  });
+  console.log(
+    `[bootstrap] bootstrap.installable.done total=${total} installed=${installedCount} failed=${failed.length}`,
+  );
+}

package/packages/server/src/bootstrap-state.ts

@@ -1,3 +1,5 @@
+import type { DashboardStarter } from "@blackbelt-technology/pi-dashboard-shared/dashboard-starter.js";
+
 /**
  * In-memory bootstrap state store for the dashboard server.
  *
@@ -51,6 +53,22 @@ export interface BootstrapState {
   compatibility?: BootstrapCompatibility;
   /** Set when `registerBridgeExtension` fails after a successful install. */
   bridgeRegistrationError?: string;
+  /**
+   * Who started this server process. Defaults to "Standalone" (direct CLI).
+   * Set at boot time from `parseDashboardStarter(process.env)`.
+   */
+  starter?: DashboardStarter;
+  /**
+   * Installable list reconciliation progress.
+   * Set by bootstrapInstallFromList during Phase B reconcile.
+   * See change: simplify-electron-bootstrap-derived-state.
+   */
+  installable?: {
+    total: number;
+    installed: number;
+    /** Package names that failed to install. */
+    failed: string[];
+  };
 }
 
 export type BootstrapListener = (state: BootstrapState) => void;

package/packages/server/src/browser-gateway.ts

@@ -15,7 +15,44 @@ import { createHeadlessPidRegistry, type HeadlessPidRegistry } from "./headless-
 import type { PendingForkRegistry } from "./pending-fork-registry.js";
 import type { SessionOrderManager } from "./session-order-manager.js";
 import type { PreferencesStore } from "./preferences-store.js";
-import type { DirectoryService } from "./directory-service.js";
+import { hasOpenSpecDir, type DirectoryService } from "./directory-service.js";
+
+/**
+ * Pure helper: build the per-cwd `openspec_update` messages a freshly
+ * connecting browser should receive. One message per known cwd.
+ * Disambiguates three states:
+ *   - cache populated         → cached payload
+ *   - openspec dir but cold   → { initialized: false, pending: true }
+ *   - no openspec dir         → { initialized: false, pending: false }
+ *
+ * Exported so cold-boot snapshot semantics can be unit-tested without
+ * spinning up a WS server. See change: fix-cold-boot-openspec-protocol.
+ */
+export function buildOpenSpecConnectSnapshot(
+  directoryService: Pick<DirectoryService, "knownDirectories" | "getOpenSpecData">,
+  hasDir: (cwd: string) => boolean,
+): Array<ServerToBrowserMessage> {
+  const out: Array<ServerToBrowserMessage> = [];
+  for (const cwd of directoryService.knownDirectories()) {
+    const cached = directoryService.getOpenSpecData(cwd);
+    if (cached && cached.initialized) {
+      out.push({ type: "openspec_update", cwd, data: cached });
+    } else if (hasDir(cwd)) {
+      out.push({
+        type: "openspec_update",
+        cwd,
+        data: { initialized: false, pending: true, changes: [] },
+      });
+    } else {
+      out.push({
+        type: "openspec_update",
+        cwd,
+        data: { initialized: false, pending: false, changes: [] },
+      });
+    }
+  }
+  return out;
+}
 import { createPendingResumeRegistry, type PendingResumeRegistry } from "./pending-resume-registry.js";
 import { createViewedSessionTracker, type ViewedSessionTracker } from "./viewed-session-tracker.js";
 import type { TerminalManager } from "./terminal-manager.js";
@@ -208,10 +245,21 @@ export function createBrowserGateway(
     const subs = new Set<string>();
     subscriptions.set(ws, subs);
 
-    // Send all sessions on connect (client filters by hidden flag)
-    const allSessions = sessionManager.listAll();
-    for (const session of allSessions) {
-      sendTo(ws, { type: "session_added", session });
+    // Atomic snapshot of the full session registry + per-cwd orders.
+    // Replaces the legacy per-session `session_added` loop and per-cwd
+    // `sessions_reordered` loop. Client REPLACES (not merges) its
+    // `sessions` Map and `sessionOrderMap` on receipt so stale ids from a
+    // previous server lifetime are dropped atomically.
+    // See change: fix-stale-sessions-on-reconnect.
+    {
+      const sessionsSnapshot = sessionManager.listAll();
+      const orders: Record<string, string[]> = {};
+      if (sessionOrderManager) {
+        for (const [cwd, sessionIds] of Object.entries(sessionOrderManager.getAllOrders())) {
+          if (sessionIds.length > 0) orders[cwd] = sessionIds;
+        }
+      }
+      sendTo(ws, { type: "sessions_snapshot", sessions: sessionsSnapshot, orders });
     }
 
     // Send pinned directories on connect
@@ -219,23 +267,12 @@ export function createBrowserGateway(
       sendTo(ws, { type: "pinned_dirs_updated", paths: preferencesStore.getPinnedDirectories() });
     }
 
-    // Send session orders for all cwds
-    if (sessionOrderManager) {
-      const allOrders = sessionOrderManager.getAllOrders();
-      for (const [cwd, sessionIds] of Object.entries(allOrders)) {
-        if (sessionIds.length > 0) {
-          sendTo(ws, { type: "sessions_reordered", cwd, sessionIds });
-        }
-      }
-    }
-
-    // Send cached OpenSpec data for all known directories
+    // Send OpenSpec data for every known directory — exactly one
+    // `openspec_update` per cwd, never silently omit.
+    // See change: fix-cold-boot-openspec-protocol.
     if (directoryService) {
-      for (const cwd of directoryService.knownDirectories()) {
-        const data = directoryService.getOpenSpecData(cwd);
-        if (data && data.initialized) {
-          sendTo(ws, { type: "openspec_update", cwd, data });
-        }
+      for (const msg of buildOpenSpecConnectSnapshot(directoryService, hasOpenSpecDir)) {
+        sendTo(ws, msg);
       }
     }
 

package/packages/server/src/browser-handlers/directory-handler.ts

@@ -148,6 +148,10 @@ export function handlePiGatewayForward(
     case "request_models":
       piGateway.sendToSession(msg.sessionId, { type: "request_models", sessionId: msg.sessionId });
       break;
+    case "request_providers":
+      // See change: replace-hardcoded-provider-lists.
+      piGateway.sendToSession(msg.sessionId, { type: "request_providers", sessionId: msg.sessionId });
+      break;
     case "set_thinking_level":
       piGateway.sendToSession(msg.sessionId, { type: "set_thinking_level", sessionId: msg.sessionId, level: msg.level });
       break;

package/packages/server/src/browser-handlers/session-action-handler.ts

@@ -4,7 +4,11 @@
 import type { BrowserToServerMessage } from "@blackbelt-technology/pi-dashboard-shared/browser-protocol.js";
 import type { BrowserHandlerContext } from "./handler-context.js";
 import { spawnPiSession } from "../process-manager.js";
+import { ToolResolver } from "@blackbelt-technology/pi-dashboard-shared/platform/binary-lookup.js";
 import { loadConfig } from "@blackbelt-technology/pi-dashboard-shared/config.js";
+import { preflightSpawn } from "../spawn-preflight.js";
+import { getSpawnRegisterWatchdog } from "../spawn-register-watchdog.js";
+import { appendSpawnFailure } from "../spawn-failure-log.js";
 import { createBranchedSessionFile } from "../session-file-reader.js";
 import {
   killPidWithGroup,
@@ -313,6 +317,24 @@ export async function handleSpawnSession(
     pendingAttachRegistry?.enqueue(msg.cwd, msg.attachProposal);
   }
 
+  // ── Preflight: fast synchronous checks before spawning. See change: spawn-failure-diagnostics.
+  const preflightResolver = new ToolResolver({ processExecPath: process.execPath, useLoginShell: false });
+  const preflight = preflightSpawn(msg.cwd, { resolver: preflightResolver });
+  if (!preflight.ok) {
+    const message = preflight.reasons.map((r) => r.message).join("; ");
+    sendTo(ws, { type: "spawn_result", cwd: msg.cwd, success: false, message });
+    sendTo(ws, { type: "spawn_error", cwd: msg.cwd, strategy, message, code: "PREFLIGHT_FAILED", reasons: preflight.reasons });
+    appendSpawnFailure({
+      ts: new Date().toISOString(),
+      cwd: msg.cwd,
+      strategy,
+      code: "PREFLIGHT_FAILED",
+      message,
+      reasons: preflight.reasons,
+    });
+    return;
+  }
+
   // Catch both thrown exceptions and { success: false } results; surface as
   // spawn_error so the UI can render a retryable banner instead of failing
   // silently. Previous behaviour left the user staring at an empty state
@@ -327,13 +349,49 @@ export async function handleSpawnSession(
     }
     sendTo(ws, { type: "spawn_result", cwd: msg.cwd, success: spawnResult.success, message: spawnResult.message });
     if (!spawnResult.success) {
-      sendTo(ws, { type: "spawn_error", cwd: msg.cwd, strategy, message: spawnResult.message });
+      sendTo(ws, {
+        type: "spawn_error",
+        cwd: msg.cwd,
+        strategy,
+        message: spawnResult.message,
+        ...(spawnResult.code ? { code: spawnResult.code } : {}),
+        ...(spawnResult.stderr ? { stderr: spawnResult.stderr } : {}),
+      });
+      appendSpawnFailure({
+        ts: new Date().toISOString(),
+        cwd: msg.cwd,
+        strategy,
+        code: spawnResult.code ?? "SPAWN_ERRNO",
+        message: spawnResult.message,
+        ...(spawnResult.stderr ? { stderrTail: spawnResult.stderr } : {}),
+      });
+    } else {
+      // Arm watchdog for every successful spawn. See change: spawn-failure-diagnostics.
+      const watchdog = getSpawnRegisterWatchdog();
+      watchdog.arm({
+        pid: spawnResult.pid,
+        cwd: msg.cwd,
+        mechanism: strategy as import("@blackbelt-technology/pi-dashboard-shared/platform/spawn-mechanism.js").SpawnMechanism,
+        logPath: spawnResult.logPath,
+        // Read-on-arm: pass current config value so a Settings change takes effect
+        // on the next spawn without a server restart. See change: spawn-failure-diagnostics (fix W1).
+        timeoutMs: config.spawnRegisterTimeoutMs,
+        ws,
+      });
     }
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     const stderr = err instanceof Error && "stderr" in err ? String((err as { stderr: unknown }).stderr).slice(-2048) : undefined;
     sendTo(ws, { type: "spawn_result", cwd: msg.cwd, success: false, message });
-    sendTo(ws, { type: "spawn_error", cwd: msg.cwd, strategy, message, stderr });
+    sendTo(ws, { type: "spawn_error", cwd: msg.cwd, strategy, message, code: "SPAWN_ERRNO", stderr });
+    appendSpawnFailure({
+      ts: new Date().toISOString(),
+      cwd: msg.cwd,
+      strategy,
+      code: "SPAWN_ERRNO",
+      message,
+      ...(stderr ? { stderrTail: stderr } : {}),
+    });
   }
 }
 

package/packages/server/src/browser-handlers/subscription-handler.ts

@@ -68,7 +68,7 @@ async function sendEventBatches(
  * Called immediately after every `replayPendingUiRequests` site so the full
  * replay ordering is:
  *
- *   events → pending UI requests → ui_modules_list → ui_data_list → ext_ui_decorator
+ *   asset_register batch → events → pending UI requests → ui_modules_list → ui_data_list → ext_ui_decorator
  *
  * Exported so unit tests can drive it without standing up a full subscribe
  * pipeline. See changes: add-extension-ui-modal, add-extension-ui-decorations.
@@ -96,6 +96,35 @@ export function replayUiState(
   }
 }
 
+/**
+ * Replay the per-session image asset registry to a single browser. Sends one
+ * `asset_register` message per `(hash, { data, mimeType })` entry in
+ * `Session.assets`. Called BEFORE `sendEventBatches` so any `pi-asset:<hash>`
+ * tokens in replayed `message_update` / `message_end` events have their
+ * referent in the client's session map by the time they're reduced.
+ *
+ * See change: chat-markdown-local-images-and-math.
+ */
+export function replaySessionAssets(
+  ws: WebSocket,
+  sessionId: string,
+  ctx: Pick<BrowserHandlerContext, "sessionManager" | "sendTo">,
+): void {
+  const { sessionManager, sendTo } = ctx;
+  const session = sessionManager.get(sessionId);
+  if (!session?.assets) return;
+  for (const [hash, asset] of Object.entries(session.assets)) {
+    if (!asset || typeof asset.data !== "string" || typeof asset.mimeType !== "string") continue;
+    sendTo(ws, {
+      type: "asset_register",
+      sessionId,
+      hash,
+      mimeType: asset.mimeType,
+      data: asset.data,
+    } as any);
+  }
+}
+
 export function handleSubscribe(
   msg: Extract<BrowserToServerMessage, { type: "subscribe" }>,
   subs: Set<string>,
@@ -108,6 +137,8 @@ export function handleSubscribe(
   // while the browser is actually subscribed (responses use sendToSubscribers).
   piGateway.sendToSession(msg.sessionId, { type: "request_commands", sessionId: msg.sessionId });
   piGateway.sendToSession(msg.sessionId, { type: "request_models", sessionId: msg.sessionId });
+  // See change: replace-hardcoded-provider-lists.
+  piGateway.sendToSession(msg.sessionId, { type: "request_providers", sessionId: msg.sessionId });
   piGateway.sendToSession(msg.sessionId, { type: "request_roles", sessionId: msg.sessionId });
 
   if (eventStore.hasEvents(msg.sessionId)) {
@@ -122,6 +153,10 @@ export function handleSubscribe(
       if (MAX_REPLAY_EVENTS > 0 && events.length > MAX_REPLAY_EVENTS) {
         events = events.slice(events.length - MAX_REPLAY_EVENTS);
       }
+      // Replay asset registry BEFORE events so pi-asset:<hash> tokens in
+      // message_update / message_end resolve on first reduce.
+      // See change: chat-markdown-local-images-and-math.
+      replaySessionAssets(ws, msg.sessionId, ctx);
       markReplaying(ws, msg.sessionId);
       sendEventBatches(ws, msg.sessionId, events, sendTo).then((lastSent) => {
         clearReplaying(ws, msg.sessionId, lastSent);
@@ -133,8 +168,18 @@ export function handleSubscribe(
       if (MAX_REPLAY_EVENTS > 0 && events.length > MAX_REPLAY_EVENTS) {
         events = events.slice(events.length - MAX_REPLAY_EVENTS);
       }
-      // Suppress live events during delta replay to prevent out-of-order delivery
-      if (lastSeq > 0 && events.length > 0) {
+      // Replay asset registry on every subscribe (delta or full). Cheap when
+      // empty; assets already known to the client are simply re-overwritten
+      // with identical bytes. See change: chat-markdown-local-images-and-math.
+      replaySessionAssets(ws, msg.sessionId, ctx);
+      // Suppress live events during paginated replay to prevent out-of-order
+      // delivery. The client's `event_replay` reset rule (firstSeq <= maxSeq)
+      // misfires if a live `event` arrives between batches and bumps maxSeq
+      // past the next batch's firstSeq — wiping state to a fresh build of
+      // only the last batch. Suppression+catch-up via clearReplaying preserves
+      // ordering for both cold (lastSeq=0) and warm (lastSeq>0) subscribes.
+      // See change: fix-cold-subscribe-replay-interleave.
+      if (events.length > 0) {
         markReplaying(ws, msg.sessionId);
         sendEventBatches(ws, msg.sessionId, events, sendTo).then((lastSent) => {
           clearReplaying(ws, msg.sessionId, lastSent);
@@ -172,6 +217,8 @@ export function handleSubscribe(
           }
           const subscribers = getSubscribers(msg.sessionId);
           for (const sub of subscribers) {
+            // Asset registry first — see change: chat-markdown-local-images-and-math.
+            replaySessionAssets(sub, msg.sessionId, ctx);
             await sendEventBatches(sub, msg.sessionId, stored, sendTo);
             replayPendingUiRequests(sub, msg.sessionId);
             replayUiState(sub, msg.sessionId, ctx);

package/packages/server/src/cli.ts

@@ -53,6 +53,8 @@ import {
 import type { DashboardServer } from "./server.js";
 import { updateBootstrapCompatibility } from "./pi-version-skew.js";
 import type { BootstrapStateStore } from "./bootstrap-state.js";
+import { parseDashboardStarter } from "@blackbelt-technology/pi-dashboard-shared/dashboard-starter.js";
+import { bootstrapInstallFromList } from "./bootstrap-install-from-list.js";
 
 /**
  * Emit a stderr warning at CLI startup when the resolved pi version is
@@ -166,6 +168,12 @@ async function runForeground(config: ServerConfig): Promise<void> {
   assertNodeVersionSupported();
   const server = await createServer(config);
 
+  // Stamp the bootstrap state with who started this server process.
+  // parseDashboardStarter defaults to "Standalone" when DASHBOARD_STARTER is unset.
+  const starter = parseDashboardStarter(process.env);
+  server.bootstrapState.set({ starter });
+  console.log(`[bootstrap] starter=${starter}`);
+
   let shuttingDown = false;
   const shutdown = async () => {
     if (shuttingDown) {
@@ -181,6 +189,19 @@ async function runForeground(config: ServerConfig): Promise<void> {
   process.on("SIGINT", shutdown);
   process.on("SIGTERM", shutdown);
 
+  // Reconcile installable.json before binding the port.
+  // Required-package failures throw and prevent server start.
+  // Optional failures are logged and continue.
+  // File-absent is a no-op (Bridge/Standalone starters don't seed installable.json).
+  // See change: simplify-electron-bootstrap-derived-state.
+  try {
+    await bootstrapInstallFromList(server.bootstrapState);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`[bootstrap] installable reconcile failed (required package): ${message}`);
+    process.exit(1);
+  }
+
   await server.start();
 
   // Kick off the degraded-mode first-run bootstrap if pi is unresolvable.

package/packages/server/src/directory-service.ts

@@ -45,6 +45,37 @@ export interface DirectoryAddedResult {
   openspecData: OpenSpecData;
 }
 
+/**
+ * `true` if `OpenSpecData` represents "no useful data yet" — either
+ * absent, or `{ initialized: false, changes: [] }` (cold cache).
+ * Used by broadcast call-sites to decide whether a transition from
+ * empty→populated warrants firing `openspec_update`. Pulled into
+ * shared scope so `server.ts` (post-install repair) and
+ * `session-bootstrap.ts` (initial poll) both use the same predicate.
+ *
+ * See change: fix-cold-boot-openspec-protocol.
+ */
+export function isOpenSpecDataEmpty(d: OpenSpecData | undefined): boolean {
+  if (!d) return true;
+  return !d.initialized && (!d.changes || d.changes.length === 0);
+}
+
+/**
+ * Synchronous, spawn-free probe for `<cwd>/openspec/changes`. Returns
+ * `true` iff the path exists and is a directory. Used by the WS
+ * on-connect snapshot to disambiguate "no openspec here" from
+ * "openspec here, polling pending". ~10 μs per call.
+ *
+ * See change: fix-cold-boot-openspec-protocol.
+ */
+export function hasOpenSpecDir(cwd: string): boolean {
+  try {
+    return fs.statSync(path.join(cwd, "openspec", "changes")).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
 export interface DirectoryService {
   knownDirectories(): string[];
   discoverSessions(cwd: string): DiscoveredSession[];