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

package/packages/server/src/routes/jj-routes.ts

@@ -0,0 +1,386 @@
+/**
+ * Jujutsu (jj) REST API routes (localhost-only).
+ *
+ * Endpoints:
+ *   POST /api/jj/workspace/add       — create workspace + spawn session
+ *   POST /api/jj/workspace/forget    — refuses on unfolded work; force escape
+ *   POST /api/jj/init-colocated      — refuses on dirty git index
+ *   GET  /api/jj/workspace/list      — enumerate workspaces under cwd
+ *
+ * All endpoints are network-guarded. Workspace add reuses the same
+ * pending-attach + spawnPiSession lever as the OpenSpec attach-and-spawn
+ * flow. See changes: add-jj-workspace-plugin, add-folder-task-checker-and-spawn-attach.
+ */
+import path from "node:path";
+import fs from "node:fs/promises";
+import { existsSync } from "node:fs";
+import type { FastifyInstance } from "fastify";
+import * as jj from "@blackbelt-technology/pi-dashboard-shared/platform/jj.js";
+import * as git from "@blackbelt-technology/pi-dashboard-shared/platform/git.js";
+import { loadConfig } from "@blackbelt-technology/pi-dashboard-shared/config.js";
+import type { ApiResponse } from "@blackbelt-technology/pi-dashboard-shared/types.js";
+import type { BrowserGateway } from "../browser-gateway.js";
+import type { PendingAttachRegistry } from "../pending-attach-registry.js";
+import { spawnPiSession } from "../process-manager.js";
+import type { NetworkGuard } from "./route-deps.js";
+import { safeRealpathSync } from "../resolve-path.js";
+
+/** Workspace name regex per spec (filesystem + bookmark safety). */
+const NAME_RE = /^[a-z0-9-]+$/;
+
+export interface JjRoutesDeps {
+  browserGateway: BrowserGateway;
+  pendingAttachRegistry: PendingAttachRegistry;
+  networkGuard: NetworkGuard;
+  /** Optional plugin config accessor (defaults to current dashboard config). */
+  getWorkspaceRoot?: () => string;
+}
+
+/**
+ * Resolve the workspace-root setting for a given repo. Currently global
+ * via the plugin config; per-repo override is explicitly out of scope
+ * (Decision 14). Falls back to `.shadow` when config is absent.
+ */
+function resolveWorkspaceRoot(deps: JjRoutesDeps): string {
+  if (deps.getWorkspaceRoot) return deps.getWorkspaceRoot();
+  // The plugin config is read from the dashboard config blob's `plugins.jj`
+  // namespace. Until the runtime config-validator wires that path here, we
+  // fall back to the documented default.
+  try {
+    const cfg = loadConfig() as unknown as { plugins?: { jj?: { workspaceRoot?: string } } };
+    return cfg.plugins?.jj?.workspaceRoot ?? ".shadow";
+  } catch {
+    return ".shadow";
+  }
+}
+
+/**
+ * Pure preflight checks for `init-colocated`. Returns `null` on OK,
+ * else a `{ code, message }` object the caller can shape into 4xx.
+ */
+export function checkInitColocatedPreconditions(cwd: string):
+  | null
+  | { code: "INVALID_CWD" | "ALREADY_JJ" | "DIRTY_INDEX" | "NOT_GIT_REPO"; message: string } {
+  if (!cwd) return { code: "INVALID_CWD", message: "cwd is required" };
+  if (!existsSync(cwd)) return { code: "INVALID_CWD", message: `cwd does not exist: ${cwd}` };
+  if (existsSync(path.join(cwd, ".jj"))) {
+    return { code: "ALREADY_JJ", message: "cwd is already a jj repo" };
+  }
+  if (!existsSync(path.join(cwd, ".git"))) {
+    return { code: "NOT_GIT_REPO", message: "cwd is not a git repo" };
+  }
+  // git diff --cached --quiet exits 1 when index is dirty. Recipe-based
+  // helper for clarity and consistency with the rest of the codebase.
+  const indexResult = git.statusPorcelain({ cwd });
+  if (indexResult.ok) {
+    // Lines beginning with M, A, D, R, C, U in column 1 indicate INDEX
+    // changes (column 2 is the working tree). We refuse on any column-1
+    // mutation.
+    const dirty = indexResult.value
+      .split("\n")
+      .filter((l) => l.length >= 2 && /[MADRCU]/.test(l[0]!));
+    if (dirty.length > 0) {
+      return {
+        code: "DIRTY_INDEX",
+        message:
+          `git index has staged changes (${dirty.length} entr${dirty.length === 1 ? "y" : "ies"}); ` +
+          `commit or 'git reset' first. See spec scenario "Init refused on dirty index".`,
+      };
+    }
+  }
+  return null;
+}
+
+export function registerJjRoutes(fastify: FastifyInstance, deps: JjRoutesDeps) {
+  const { browserGateway, pendingAttachRegistry, networkGuard } = deps;
+
+  // ── GET /api/jj/workspace/list?cwd=… ────────────────────────────────────
+  fastify.get<{ Querystring: { cwd?: string } }>(
+    "/api/jj/workspace/list",
+    { preHandler: networkGuard },
+    async (request, reply) => {
+      const cwd = request.query.cwd;
+      if (!cwd) {
+        reply.code(400);
+        return { success: false, error: "cwd is required" } satisfies ApiResponse;
+      }
+      if (!existsSync(path.join(cwd, ".jj"))) {
+        return { success: true, data: { workspaces: [] } } satisfies ApiResponse;
+      }
+      const result = jj.workspaceList({ cwd });
+      if (!result.ok) {
+        reply.code(500);
+        return {
+          success: false,
+          error: `jj workspace list failed: ${describeError(result.error)}`,
+        } satisfies ApiResponse;
+      }
+      const workspaces = jj.parseWorkspaceList(result.value);
+      return { success: true, data: { workspaces } } satisfies ApiResponse;
+    },
+  );
+
+  // ── POST /api/jj/workspace/add ──────────────────────────────────────────
+  fastify.post<{
+    Body: { fromCwd?: string; name?: string; baseRev?: string; taskDescription?: string };
+  }>(
+    "/api/jj/workspace/add",
+    { preHandler: networkGuard },
+    async (request, reply) => {
+      const { fromCwd, name, baseRev, taskDescription } = request.body ?? {};
+
+      if (!fromCwd) {
+        reply.code(400);
+        return { success: false, error: "fromCwd is required" } satisfies ApiResponse;
+      }
+      if (!name || !NAME_RE.test(name)) {
+        reply.code(400);
+        return {
+          success: false,
+          error: "INVALID_NAME: name must match /^[a-z0-9-]+$/",
+        } satisfies ApiResponse;
+      }
+      if (!existsSync(path.join(fromCwd, ".jj"))) {
+        reply.code(400);
+        return {
+          success: false,
+          error: "fromCwd is not a jj repo",
+        } satisfies ApiResponse;
+      }
+
+      const workspaceRoot = resolveWorkspaceRoot(deps);
+      const destPath = path.join(fromCwd, workspaceRoot, name);
+      if (existsSync(destPath)) {
+        reply.code(409);
+        return {
+          success: false,
+          error: `destination already exists: ${destPath}`,
+        } satisfies ApiResponse;
+      }
+      // Ensure the workspace-root parent directory exists. `jj workspace
+      // add` does NOT create intermediate dirs and fails with
+      // "Cannot access <path>" on a missing parent. mkdir -p is safe and
+      // idempotent. The .shadow root should be in .gitignore (the spec's
+      // FolderOpenSpecSection-style hint is tracked as follow-up).
+      const parentDir = path.dirname(destPath);
+      try {
+        await fs.mkdir(parentDir, { recursive: true });
+      } catch (err) {
+        reply.code(500);
+        return {
+          success: false,
+          error: `failed to create workspace parent dir ${parentDir}: ${err instanceof Error ? err.message : String(err)}`,
+        } satisfies ApiResponse;
+      }
+
+      // Resolve the base revision when omitted: current bookmark of fromCwd's
+      // working copy, falling back to `trunk()` revset.
+      let resolvedBase = baseRev;
+      if (!resolvedBase) {
+        const bookmarksResult = jj.logRevset({
+          cwd: fromCwd,
+          revset: "@",
+          template: 'bookmarks ++ "\\n"',
+        });
+        if (bookmarksResult.ok) {
+          const first = bookmarksResult.value.trim().split("\n")[0]?.trim();
+          if (first) resolvedBase = first;
+        }
+        if (!resolvedBase) resolvedBase = "trunk()";
+      }
+
+      const addResult = jj.workspaceAdd({
+        cwd: fromCwd,
+        destPath,
+        baseRev: resolvedBase,
+      });
+      if (!addResult.ok) {
+        reply.code(500);
+        return {
+          success: false,
+          error: `jj workspace add failed: ${describeError(addResult.error)}`,
+        } satisfies ApiResponse;
+      }
+
+      const realDestPath = safeRealpathSync(destPath);
+      pendingAttachRegistry.enqueue(realDestPath, name);
+
+      // Spawn a session in the new workspace. Mirrors the OpenSpec
+      // attach-and-spawn flow; the bridge's `session_register` will
+      // consume the pending-attach intent and apply the auto-rename.
+      try {
+        const config = loadConfig();
+        const spawnResult = await spawnPiSession(realDestPath, {
+          strategy: config.spawnStrategy,
+        });
+        if (spawnResult.process && spawnResult.pid) {
+          browserGateway.headlessPidRegistry.register(
+            spawnResult.pid,
+            realDestPath,
+            spawnResult.process,
+          );
+        }
+        if (!spawnResult.success) {
+          reply.code(202);
+          return {
+            success: true,
+            data: {
+              workspacePath: realDestPath,
+              spawned: false,
+              spawnMessage: spawnResult.message,
+            },
+          } satisfies ApiResponse;
+        }
+        return {
+          success: true,
+          data: {
+            workspacePath: realDestPath,
+            spawned: true,
+            taskDescription: taskDescription ?? null,
+          },
+        } satisfies ApiResponse;
+      } catch (err) {
+        reply.code(202);
+        return {
+          success: true,
+          data: {
+            workspacePath: realDestPath,
+            spawned: false,
+            spawnMessage: err instanceof Error ? err.message : String(err),
+          },
+        } satisfies ApiResponse;
+      }
+    },
+  );
+
+  // ── POST /api/jj/workspace/forget ───────────────────────────────────────
+  fastify.post<{
+    Body: { cwd?: string; name?: string; force?: boolean };
+  }>(
+    "/api/jj/workspace/forget",
+    { preHandler: networkGuard },
+    async (request, reply) => {
+      const { cwd, name, force } = request.body ?? {};
+
+      if (!cwd) {
+        reply.code(400);
+        return { success: false, error: "cwd is required" } satisfies ApiResponse;
+      }
+      if (!name || !NAME_RE.test(name)) {
+        reply.code(400);
+        return {
+          success: false,
+          error: "INVALID_NAME: name must match /^[a-z0-9-]+$/",
+        } satisfies ApiResponse;
+      }
+      if (!existsSync(path.join(cwd, ".jj"))) {
+        reply.code(400);
+        return {
+          success: false,
+          error: "cwd is not a jj repo",
+        } satisfies ApiResponse;
+      }
+
+      // Inspect for unfolded commits: anything in the workspace's `@`
+      // that isn't an ancestor of trunk. `trunk()..<name>@` is the
+      // straight-line revset for that; we filter out empty changes
+      // (`~empty()`) so the empty `@` of a freshly-created workspace
+      // doesn't trigger the unfolded-work refusal.
+      // Note: jj 0.40's `fork_point()` takes a single revset; we use
+      // the simpler `..` range form which works on every supported jj.
+      let unfolded: string[] = [];
+      const logResult = jj.logRevset({
+        cwd,
+        revset: `trunk()..${name}@ & ~empty()`,
+        template: 'change_id.short() ++ " " ++ description.first_line() ++ "\\n"',
+      });
+      if (logResult.ok) {
+        unfolded = logResult.value
+          .split("\n")
+          .map((l) => l.trim())
+          .filter(Boolean);
+      }
+      // A failed revset (e.g. unknown bookmark / fork_point unsupported) is
+      // *not* sufficient to skip the safety check — refuse with a generic
+      // error so the user sees the underlying jj message.
+      if (!logResult.ok) {
+        reply.code(500);
+        return {
+          success: false,
+          error: `jj log probe failed: ${describeError(logResult.error)}`,
+        } satisfies ApiResponse;
+      }
+
+      if (unfolded.length > 0 && !force) {
+        reply.code(409);
+        return {
+          success: false,
+          error: "UNFOLDED_WORK",
+          data: { unfolded },
+        } as unknown as ApiResponse;
+      }
+
+      // Forget + remove directory.
+      const forgetResult = jj.workspaceForget({ cwd, name });
+      if (!forgetResult.ok) {
+        reply.code(500);
+        return {
+          success: false,
+          error: `jj workspace forget failed: ${describeError(forgetResult.error)}`,
+        } satisfies ApiResponse;
+      }
+
+      const workspaceRoot = resolveWorkspaceRoot(deps);
+      const dirPath = path.join(cwd, workspaceRoot, name);
+      try {
+        await fs.rm(dirPath, { recursive: true, force: true });
+      } catch (err) {
+        // Forget already succeeded; surface the rm error but don't fail
+        // the operation overall — the workspace is gone from jj's view.
+        request.log.warn(
+          `jj workspace dir cleanup failed (${dirPath}): ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+
+      return { success: true, data: { name, force: Boolean(force) } } satisfies ApiResponse;
+    },
+  );
+
+  // ── POST /api/jj/init-colocated ─────────────────────────────────────────
+  fastify.post<{ Body: { cwd?: string } }>(
+    "/api/jj/init-colocated",
+    { preHandler: networkGuard },
+    async (request, reply) => {
+      const { cwd } = request.body ?? {};
+      const precheck = checkInitColocatedPreconditions(cwd ?? "");
+      if (precheck) {
+        reply.code(precheck.code === "DIRTY_INDEX" ? 409 : 400);
+        return {
+          success: false,
+          error: precheck.code,
+          data: { message: precheck.message },
+        } as unknown as ApiResponse;
+      }
+      const result = jj.gitInitColocate({ cwd: cwd! });
+      if (!result.ok) {
+        reply.code(500);
+        return {
+          success: false,
+          error: `jj git init --colocate failed: ${describeError(result.error)}`,
+        } satisfies ApiResponse;
+      }
+      return { success: true, data: { cwd } } satisfies ApiResponse;
+    },
+  );
+}
+
+function describeError(error: { kind: string; [k: string]: unknown }): string {
+  if (error.kind === "not-found") return `binary not found: ${String(error.binary ?? "jj")}`;
+  if (error.kind === "timeout") return `timed out after ${String(error.timeoutMs)}ms`;
+  if (error.kind === "exit") {
+    const stderr = typeof error.stderr === "string" ? error.stderr.trim() : "";
+    return stderr.split("\n")[0] || `exited ${String(error.code)}`;
+  }
+  if (error.kind === "spawn-failure") return String(error.message ?? "spawn failed");
+  return error.kind;
+}

package/packages/server/src/routes/provider-auth-routes.ts

@@ -18,6 +18,7 @@ import {
   resolveAuthJsonKey,
   type ApiKeyCredential,
 } from "../provider-auth-storage.js";
+import { getLatestCatalogue } from "../provider-catalogue-cache.js";
 import { startCallbackServer } from "../oauth-callback-server.js";
 import type { PiGateway } from "../pi-gateway.js";
 import type { BrowserGateway } from "../browser-gateway.js";
@@ -98,6 +99,14 @@ export function registerProviderAuthRoutes(
 
   // Full status (OAuth + API key)
   fastify.get("/api/provider-auth/status", async () => {
+    // Cold-cache nudge: if no bridge has pushed a catalogue yet, ask
+    // every connected pi to send one. Best-effort, doesn't block this
+    // response. See change: replace-hardcoded-provider-lists.
+    if (getLatestCatalogue().length === 0) {
+      for (const sid of piGateway.getConnectedSessionIds()) {
+        piGateway.sendToSession(sid, { type: "request_providers", sessionId: sid });
+      }
+    }
     return getAuthStatus();
   });
 

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

@@ -8,7 +8,7 @@ import type { SessionManager } from "../memory-session-manager.js";
 import type { EventStore } from "../memory-event-store.js";
 import type { ApiResponse } from "@blackbelt-technology/pi-dashboard-shared/types.js";
 import type { NetworkGuard } from "./route-deps.js";
-import { extractFileChanges, enrichWithGitDiff } from "../session-diff.js";
+import { extractFileChanges, enrichWithVcsDiff } from "../session-diff.js";
 
 export function registerSessionRoutes(
   fastify: FastifyInstance,
@@ -52,8 +52,17 @@ export function registerSessionRoutes(
       }
       const events = eventStore.getEvents(sessionId, 0).map((e) => e.event);
       const files = extractFileChanges(events, session.cwd);
-      const { enrichedFiles, isGitRepo: isGit } = enrichWithGitDiff(session.cwd, files);
-      return { success: true, data: { files: enrichedFiles, isGitRepo: isGit } } satisfies ApiResponse;
+      const result = enrichWithVcsDiff(session.cwd, files, session.jjState);
+      return {
+        success: true,
+        data: {
+          files: result.enrichedFiles,
+          isGitRepo: result.isGitRepo,
+          vcsKind: result.vcsKind,
+          diffBase: result.diffBase,
+          baseLabel: result.baseLabel,
+        },
+      } satisfies ApiResponse;
     },
   );
 

package/packages/server/src/routes/system-routes.ts

@@ -19,8 +19,10 @@ import { spawn } from "@blackbelt-technology/pi-dashboard-shared/platform/exec.j
 import path from "node:path";
 import os from "node:os";
 import { localhostGuard, netmaskToCidrBits, networkAddress } from "../localhost-guard.js";
+import { readSpawnFailures } from "../spawn-failure-log.js";
 import { getPluginStatusStore } from "@blackbelt-technology/dashboard-plugin-runtime/server";
 import type { NetworkInterface } from "@blackbelt-technology/pi-dashboard-shared/rest-api.js";
+import type { BootstrapStateStore } from "../bootstrap-state.js";
 
 export function registerSystemRoutes(
   fastify: FastifyInstance,
@@ -33,9 +35,10 @@ export function registerSystemRoutes(
     version?: string;
     directoryService?: DirectoryService;
     piGateway?: PiGateway;
+    bootstrapState?: BootstrapStateStore;
   },
 ) {
-  const { sessionManager, preferencesStore, metaPersistence, config, networkGuard, version, directoryService, piGateway } = deps;
+  const { sessionManager, preferencesStore, metaPersistence, config, networkGuard, version, directoryService, piGateway, bootstrapState } = deps;
 
   // Quiesce windows for the bridge `server_restarting` broadcast. See change
   // `fix-restart-bridge-auto-start-race`. Bridges that receive this message
@@ -189,6 +192,8 @@ export function registerSystemRoutes(
     return {
       ok: true,
       pid: process.pid,
+      starter: bootstrapState?.get().starter ?? "Standalone",
+      installable: bootstrapState?.get().installable,
       version: version ?? "unknown",
       uptime: Math.floor((Date.now() - serverStartTime) / 1000),
       mode: config.dev ? "dev" : "production",
@@ -223,6 +228,26 @@ export function registerSystemRoutes(
     },
   );
 
+  // Re-extract endpoint — Electron-only; 403 for Bridge/Standalone, 202 for Electron.
+  // See change: simplify-electron-bootstrap-derived-state (task 6.4).
+  fastify.post(
+    "/api/electron/reextract",
+    { preHandler: networkGuard },
+    async (_request, reply) => {
+      const starter = bootstrapState?.get().starter ?? "Standalone";
+      if (starter !== "Electron") {
+        reply.status(403);
+        return {
+          error: "reextract_not_allowed",
+          message: `Re-extract is only available when the server was started by Electron (current starter: ${starter})`,
+          starter,
+        };
+      }
+      reply.status(202);
+      return { ok: true, message: "Re-extraction scheduled. Electron will restart the server." };
+    },
+  );
+
   // Restart endpoint — flush state, spawn new server, then exit
   fastify.post<{ Body: { dev?: boolean } }>(
     "/api/restart",
@@ -269,6 +294,18 @@ export function registerSystemRoutes(
   );
 
   // Network interfaces for trusted networks UI (localhost-only for security)
+  // GET /api/spawn-failures — rolling log of failed spawn attempts. See change: spawn-failure-diagnostics.
+  fastify.get<{ Querystring: { limit?: string } }>(
+    "/api/spawn-failures",
+    async (request) => {
+      const rawLimit = request.query.limit;
+      const parsed = rawLimit !== undefined ? parseInt(rawLimit, 10) : NaN;
+      const limit = Number.isNaN(parsed) ? 50 : parsed;
+      const entries = readSpawnFailures(limit);
+      return { entries };
+    },
+  );
+
   fastify.get(
     "/api/network-interfaces",
     { preHandler: localhostGuard },

package/packages/server/src/server.ts

@@ -23,7 +23,7 @@ import { createPendingResumeIntentRegistry } from "./pending-resume-intent-regis
 import { applyReattachPolicy } from "./reattach-placement.js";
 
 // pending-load-manager removed — server loads sessions directly via DirectoryService
-import { createDirectoryService, type DirectoryService } from "./directory-service.js";
+import { createDirectoryService, isOpenSpecDataEmpty, type DirectoryService } from "./directory-service.js";
 import { createTerminalManager, type TerminalManager } from "./terminal-manager.js";
 import { createTerminalGateway, type TerminalGateway } from "./terminal-gateway.js";
 import { writePid, removePid } from "./server-pid.js";
@@ -45,6 +45,7 @@ import { registerGitRoutes } from "./routes/git-routes.js";
 import { registerFileRoutes } from "./routes/file-routes.js";
 import { registerOpenSpecRoutes } from "./routes/openspec-routes.js";
 import { registerSystemRoutes } from "./routes/system-routes.js";
+import { registerDoctorRoutes } from "./routes/doctor-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";
@@ -52,6 +53,7 @@ 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 { registerJjRoutes } from "./routes/jj-routes.js";
 import { registerBootstrapRoutes } from "./routes/bootstrap-routes.js";
 import { createBootstrapState, type BootstrapStateStore } from "./bootstrap-state.js";
 import { createBootstrapQueue } from "./bootstrap-queue.js";
@@ -90,6 +92,10 @@ export interface ServerConfig {
   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;
+  /** Reattach-placement policy applied when a bridge re-registers after
+   *  a dashboard restart. Defaults to `"always"`.
+   *  See change: reattach-move-to-front. */
+  reattachPlacement?: import("@blackbelt-technology/pi-dashboard-shared/config.js").ReattachPlacement;
   /** Merged trusted networks from config */
   resolvedTrustedNetworks?: string[];
   /** CORS allowed origins from config */
@@ -138,10 +144,6 @@ export interface PostInstallRepairDeps {
   browserGateway: { broadcastToAll(msg: ServerToBrowserMessage): void };
 }
 
-function isOpenSpecDataEmpty(d: OpenSpecData | undefined): boolean {
-  if (!d) return true;
-  return !d.initialized && (!d.changes || d.changes.length === 0);
-}
 
 /**
  * Centralized post-install repair work fired on every `installing → ready`
@@ -366,7 +368,7 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
           applyReattachPolicy(
             sessionId,
             session.cwd,
-            config.reattachPlacement,
+            config.reattachPlacement ?? "always",
             { sessionManager, sessionOrderManager, browserGateway },
             ctx.priorStatus,
           );
@@ -416,7 +418,7 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
         applyReattachPolicy(
           sessionId,
           session.cwd,
-          config.reattachPlacement,
+          config.reattachPlacement ?? "always",
           { sessionManager, sessionOrderManager, browserGateway },
           ctx.priorStatus,
         );
@@ -558,7 +560,9 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
   });
 
   // Auto-shutdown idle timer
-  const idleTimer = createIdleTimer(config, piGateway);
+  // Active terminals keep the server alive even when no pi sessions are
+  // attached. See change: fix-terminal-half-height-dual-mount.
+  const idleTimer = createIdleTimer(config, piGateway, () => terminalManager.list().length > 0);
 
   const fastify = Fastify({
     logger: false,
@@ -704,8 +708,11 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
       if (data) browserGateway.broadcastToAll({ type: "openspec_update", cwd, data });
     },
   });
-  registerSystemRoutes(fastify, { sessionManager, preferencesStore, metaPersistence, config, networkGuard, version: pkgVersion, directoryService, piGateway });
+  registerSystemRoutes(fastify, { sessionManager, preferencesStore, metaPersistence, config, networkGuard, version: pkgVersion, directoryService, piGateway, bootstrapState });
+  // GET /api/doctor — see change: doctor-rich-output (task 4.2). Auth-gated identically to /api/config.
+  registerDoctorRoutes(fastify);
   registerToolRoutes(fastify, { registry: getDefaultRegistry(), networkGuard });
+  registerJjRoutes(fastify, { browserGateway, pendingAttachRegistry, networkGuard });
 
   // ── Bootstrap REST routes ────────────────────────────────────────
   // The routes module is registered here; state + queue are declared

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

@@ -4,7 +4,7 @@
  */
 import type { SessionManager } from "./memory-session-manager.js";
 import type { BrowserGateway } from "./browser-gateway.js";
-import type { DirectoryService } from "./directory-service.js";
+import { isOpenSpecDataEmpty, type DirectoryService } from "./directory-service.js";
 import { extractSessionStats } from "./session-stats-reader.js";
 
 export interface SessionBootstrapDeps {
@@ -75,20 +75,35 @@ export async function discoverAndBroadcastSessions(deps: SessionBootstrapDeps):
 
   // Initial OpenSpec poll for all known directories.
   //
-  // NOTE: `refreshOpenSpec` / `pollOpenSpec` is currently synchronous internally
-  // (spawnSync per change) — on Windows with many active changes (~19) and
-  // multiple pinned directories this can block the event loop for minutes,
-  // making the HTTP server unresponsive during startup. We intentionally do
-  // NOT await it here so HTTP + WebSocket startup completes immediately;
-  // openspec data populates in the background and pushes `openspec_update`
-  // broadcasts to browsers as each directory finishes.
+  // Fire-and-forget: `refreshOpenSpec` / `pollOpenSpec` is synchronous internally
+  // (spawnSync per change) — on Windows with many active changes and multiple
+  // pinned directories this can block the event loop for minutes, making the
+  // HTTP server unresponsive during startup. We intentionally do NOT await it
+  // here so HTTP + WebSocket startup completes immediately.
   //
-  // A proper fix is to migrate the openspec Recipe to async spawn; tracked
-  // separately. See change: consolidate-tool-resolution.
+  // After each directory's poll completes, broadcast `openspec_update` to all
+  // connected browsers if the prior cache was empty/undefined or the polled
+  // data differs from prior — mirroring the proven `runPostInstallRepair`
+  // pattern in `server.ts`. This is what unblocks cold-boot Electron clients
+  // that connected before the cache was hot.
+  //
+  // A proper fix for the slow `spawnSync` path is to migrate the openspec
+  // Recipe to async spawn; tracked separately. See change:
+  // consolidate-tool-resolution. This change covers the broadcast wiring only.
+  // See change: fix-cold-boot-openspec-protocol.
   void Promise.all(
     directoryService.knownDirectories().map(async (cwd) => {
-      try { await directoryService.refreshOpenSpec(cwd); }
-      catch (err) { console.error(`[dashboard] initial openspec poll failed for ${cwd}:`, err); }
+      try {
+        const prior = directoryService.getOpenSpecData(cwd);
+        const fresh = await directoryService.refreshOpenSpec(cwd);
+        const priorEmpty = isOpenSpecDataEmpty(prior);
+        const dataDiffers = JSON.stringify(prior) !== JSON.stringify(fresh);
+        if (priorEmpty || dataDiffers) {
+          browserGateway.broadcastToAll({ type: "openspec_update", cwd, data: fresh });
+        }
+      } catch (err) {
+        console.error(`[dashboard] initial openspec poll failed for ${cwd}:`, err);
+      }
     }),
   );
 }