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

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

@@ -0,0 +1,140 @@
+/**
+ * GET /api/doctor — server-side diagnostic endpoint.
+ *
+ * Calls `runSharedChecks(...)` with server-appropriate `deps`, post-stamps
+ * `section` + `suggestion`, returns `{ checks, summary, generatedAt }`.
+ *
+ * Auth-gated identically to `/api/config`; unauthenticated requests yield
+ * the same status code as `/api/config` (the auth plugin's onRequest hook
+ * intercepts before this handler runs).
+ *
+ * On a thrown error from `runSharedChecks`, returns a 200 with a single
+ * fallback `error` row rather than a 500 — the web client always has
+ * something to render. See change: doctor-rich-output (tasks 4.1–4.5).
+ */
+import type { FastifyInstance } from "fastify";
+import path from "node:path";
+import os from "node:os";
+import { existsSync, readFileSync } from "node:fs";
+import {
+  runSharedChecks,
+  stampSectionsAndSuggestions,
+  safeExec,
+  type DoctorCheck,
+  type DoctorReport,
+  type SharedChecksDeps,
+} from "@blackbelt-technology/pi-dashboard-shared/doctor-core.js";
+
+function getManagedDir(): string {
+  return process.env.MANAGED_DIR || path.join(os.homedir(), ".pi-dashboard");
+}
+
+function detectSystemNode(): { found: boolean; path?: string } {
+  const cmd = process.platform === "win32" ? "where node" : "which node"; // platform-branch-ok: localised PATH-lookup primitive
+  const r = safeExec(cmd, { timeoutMs: 3000 });
+  if (!r.ok) return { found: false };
+  const first = r.stdout.trim().split("\n")[0];
+  return first ? { found: true, path: first } : { found: false };
+}
+
+function detectOnPath(name: string): { found: boolean; path?: string; source?: string } {
+  const cmd = process.platform === "win32" ? `where ${name}` : `which ${name}`; // platform-branch-ok: localised PATH-lookup primitive
+  const r = safeExec(cmd, { timeoutMs: 3000 });
+  if (!r.ok) return { found: false };
+  const first = r.stdout.trim().split("\n")[0];
+  return first ? { found: true, path: first, source: "system" } : { found: false };
+}
+
+function isApiKeyConfigured(): boolean {
+  try {
+    const settings = path.join(os.homedir(), ".pi", "agent", "settings.json");
+    if (!existsSync(settings)) return false;
+    const data = JSON.parse(readFileSync(settings, "utf-8"));
+    if (data?.anthropicApiKey || data?.openaiApiKey || data?.apiKey) return true;
+    if (data?.providers && typeof data.providers === "object") {
+      for (const v of Object.values(data.providers as Record<string, unknown>)) {
+        if (v && typeof v === "object" && "apiKey" in (v as object)) return true;
+      }
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+function buildDefaultDeps(): SharedChecksDeps {
+  return {
+    managedDir: getManagedDir(),
+    detectSystemNode,
+    detectPi: () => detectOnPath("pi"),
+    detectOpenSpec: () => detectOnPath("openspec"),
+    isApiKeyConfigured,
+    probeServer: async () => {
+      const r = safeExec("curl -sf http://localhost:8000/api/health", { timeoutMs: 3000 });
+      if (!r.ok || !r.stdout.trim()) return { running: false };
+      try {
+        const h = JSON.parse(r.stdout);
+        return {
+          running: true,
+          version: typeof h.version === "string" ? h.version : undefined,
+          mode: typeof h.mode === "string" ? h.mode : undefined,
+          starter: typeof h.starter === "string" ? h.starter : null,
+          installable:
+            h.installable && typeof h.installable === "object"
+              ? {
+                  total: h.installable.total ?? 0,
+                  installed: h.installable.installed ?? 0,
+                  failed: Array.isArray(h.installable.failed) ? h.installable.failed : [],
+                }
+              : null,
+        };
+      } catch {
+        return { running: true };
+      }
+    },
+  };
+}
+
+function summarize(checks: DoctorCheck[]): DoctorReport["summary"] {
+  return {
+    ok: checks.filter((c) => c.status === "ok").length,
+    warnings: checks.filter((c) => c.status === "warning").length,
+    errors: checks.filter((c) => c.status === "error").length,
+  };
+}
+
+export interface DoctorRouteDeps {
+  /** Override for tests — substitutes a different `runSharedChecks` deps shape (or throws to exercise fault tolerance). */
+  buildDeps?: () => SharedChecksDeps;
+}
+
+export function registerDoctorRoutes(fastify: FastifyInstance, deps: DoctorRouteDeps = {}): void {
+  fastify.get("/api/doctor", async (_request, _reply): Promise<DoctorReport> => {
+    try {
+      const sharedDeps = deps.buildDeps ? deps.buildDeps() : buildDefaultDeps();
+      const checks = await runSharedChecks(sharedDeps);
+      stampSectionsAndSuggestions(checks);
+      return {
+        checks,
+        summary: summarize(checks),
+        generatedAt: Date.now(),
+      };
+    } catch (err) {
+      const e = err instanceof Error ? err : new Error(String(err));
+      const fallback: DoctorCheck = {
+        name: "Doctor failed to produce a report",
+        section: "diagnostics",
+        status: "error",
+        message: "Unexpected internal failure",
+        detail: `${e.message}\n${(e.stack || "").split("\n").slice(0, 4).join("\n")}`,
+        suggestion:
+          "Check `~/.pi-dashboard/doctor.log` on the server, then file an issue with the captured error.",
+      };
+      return {
+        checks: [fallback],
+        summary: { ok: 0, warnings: 0, errors: 1 },
+        generatedAt: Date.now(),
+      };
+    }
+  });
+}

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/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";
@@ -143,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`
@@ -563,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,
@@ -709,7 +708,9 @@ 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 });
 

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);
+      }
     }),
   );
 }

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

@@ -6,6 +6,7 @@
 import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import os from "node:os";
+import { condenseForFirstMessage } from "@blackbelt-technology/pi-dashboard-shared/skill-block-parser.js";
 
 export interface DiscoveredSession {
   id: string;
@@ -53,15 +54,21 @@ function readSessionHeader(filePath: string): {
         if (entry.type === "session_info" && entry.name) {
           name = entry.name;
         }
-        // Find first user message
+        // Find first user message. Skill invocations are stored as a
+        // `<skill name=...>...</skill>\n\nargs` envelope (~264 chars for typical
+        // absolute paths) which is longer than the 200-char firstMessage budget,
+        // so a naive .slice(0, 200) cuts the wrapper in half. condenseForFirstMessage
+        // returns the condensed slash form (`/skill:name args`) when the input
+        // matches the envelope, falling back to the raw slice otherwise.
+        // See change: render-skill-invocations-collapsibly.
         if (!firstMessage && entry.type === "message" && entry.message?.role === "user") {
           const msg = entry.message;
           if (typeof msg.content === "string") {
-            firstMessage = msg.content.slice(0, 200);
+            firstMessage = condenseForFirstMessage(msg.content, 200);
           } else if (Array.isArray(msg.content)) {
             for (const part of msg.content) {
               if (part.type === "text" && part.text) {
-                firstMessage = part.text.slice(0, 200);
+                firstMessage = condenseForFirstMessage(part.text, 200);
                 break;
               }
             }

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

@@ -8,6 +8,7 @@ import { join } from "node:path";
 import os from "node:os";
 import type { DashboardSession, SessionSource } from "@blackbelt-technology/pi-dashboard-shared/types.js";
 import { type SessionMeta, metaPath, readSessionMeta, writeSessionMeta } from "@blackbelt-technology/pi-dashboard-shared/session-meta.js";
+import { condenseForFirstMessage } from "@blackbelt-technology/pi-dashboard-shared/skill-block-parser.js";
 import { extractSessionStats } from "./session-stats-reader.js";
 
 function getSessionsDir(): string {
@@ -236,14 +237,15 @@ function readJsonlHeaderSync(filePath: string): { id: string; cwd: string; name?
         const entry = JSON.parse(line);
         if (entry.type === "session" && entry.id) header = entry;
         if (entry.type === "session_info" && entry.name) name = entry.name;
+        // See change: render-skill-invocations-collapsibly.
         if (!firstMessage && entry.type === "message" && entry.message?.role === "user") {
           const msg = entry.message;
           if (typeof msg.content === "string") {
-            firstMessage = msg.content.slice(0, 200);
+            firstMessage = condenseForFirstMessage(msg.content, 200);
           } else if (Array.isArray(msg.content)) {
             for (const part of msg.content) {
               if (part.type === "text" && part.text) {
-                firstMessage = part.text.slice(0, 200);
+                firstMessage = condenseForFirstMessage(part.text, 200);
                 break;
               }
             }

package/packages/server/src/spawn-failure-log.ts

@@ -0,0 +1,130 @@
+/**
+ * Rolling NDJSON log of failed pi session spawn attempts.
+ *
+ * Location: ~/.pi/dashboard/sessions/spawn-failures.log
+ * Rotation: single-shot at 10 MB (renames to .log.1, overwrites any prior .log.1).
+ * Format:   one JSON object per line, terminated by \n.
+ *
+ * See change: spawn-failure-diagnostics.
+ */
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+} from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import type { PreflightReason } from "./spawn-preflight.js";
+
+export interface SpawnFailureEntry {
+  /** ISO 8601 UTC timestamp. */
+  ts: string;
+  cwd: string;
+  strategy: string;
+  code: string;
+  message: string;
+  stderrTail?: string;
+  pid?: number;
+  reasons?: PreflightReason[];
+}
+
+const LOG_MAX_BYTES = 10 * 1024 * 1024; // 10 MB
+const DEFAULT_LIMIT = 50;
+const MAX_LIMIT = 500;
+
+let _logDirOverride: string | null = null;
+
+/** Override the log directory — for tests only. See change: spawn-failure-diagnostics. */
+export function _setLogDirForTests(dir: string | null): void {
+  _logDirOverride = dir;
+}
+
+function logDir(): string {
+  return _logDirOverride ?? path.join(os.homedir(), ".pi", "dashboard", "sessions");
+}
+
+function logPath(): string {
+  return path.join(logDir(), "spawn-failures.log");
+}
+
+function logPath1(): string {
+  return path.join(logDir(), "spawn-failures.log.1");
+}
+
+/**
+ * Append a failure entry to the rolling log.
+ * Never throws — errors are caught and reported via `console.error`.
+ */
+export function appendSpawnFailure(entry: SpawnFailureEntry): void {
+  try {
+    const dir = logDir();
+    mkdirSync(dir, { recursive: true });
+
+    const filePath = logPath();
+    const line = JSON.stringify(entry) + "\n";
+
+    // Rotate if file exceeds threshold.
+    if (existsSync(filePath)) {
+      try {
+        const { size } = statSync(filePath);
+        if (size > LOG_MAX_BYTES) {
+          renameSync(filePath, logPath1());
+        }
+      } catch {
+        // If stat/rename fails, just write anyway.
+      }
+    }
+
+    appendFileSync(filePath, line, "utf-8");
+  } catch (err) {
+    console.error("[spawn-failure-log] Failed to append entry:", err);
+  }
+}
+
+/**
+ * Read the last `limit` entries from the rolling log (both .log.1 and .log).
+ * Skips malformed lines. Returns [] when no log exists.
+ */
+export function readSpawnFailures(limit: number = DEFAULT_LIMIT): SpawnFailureEntry[] {
+  const effectiveLimit = Number.isNaN(limit) ? DEFAULT_LIMIT : Math.max(0, Math.min(limit, MAX_LIMIT));
+  if (effectiveLimit === 0) return [];
+
+  const lines: string[] = [];
+
+  // Read older log first, then newer.
+  for (const filePath of [logPath1(), logPath()]) {
+    if (!existsSync(filePath)) continue;
+    try {
+      const content = readFileSync(filePath, "utf-8");
+      lines.push(...content.split("\n").filter((l) => l.trim()));
+    } catch {
+      // Skip unreadable file.
+    }
+  }
+
+  // Parse, skipping malformed lines.
+  const entries: SpawnFailureEntry[] = [];
+  for (const line of lines) {
+    try {
+      const obj = JSON.parse(line) as Record<string, unknown>;
+      // Require the minimum fields.
+      if (
+        typeof obj.ts === "string" &&
+        typeof obj.cwd === "string" &&
+        typeof obj.strategy === "string" &&
+        typeof obj.code === "string" &&
+        typeof obj.message === "string"
+      ) {
+        entries.push(obj as unknown as SpawnFailureEntry);
+      }
+    } catch {
+      // Skip malformed line.
+    }
+  }
+
+  // Return last N in file order.
+  return entries.length <= effectiveLimit ? entries : entries.slice(entries.length - effectiveLimit);
+}

package/packages/server/src/spawn-preflight.ts

@@ -0,0 +1,82 @@
+/**
+ * Synchronous spawn preflight check.
+ *
+ * Runs before every `spawnPiSession` invocation to catch fast-fail conditions
+ * (bad cwd, missing binaries) without racing the spawn itself. All checks run
+ * regardless of earlier failures so the caller gets all reasons in one pass.
+ *
+ * The ToolResolver passed in MUST have `useLoginShell: false` — preflight
+ * must never spawn a login shell on the spawn-click hot path. If a resolver
+ * with `useLoginShell: true` is passed, the check still runs but a one-time
+ * warning is emitted.
+ *
+ * See change: spawn-failure-diagnostics.
+ */
+import { existsSync, accessSync, statSync, constants } from "node:fs";
+import { ToolResolver } from "@blackbelt-technology/pi-dashboard-shared/platform/binary-lookup.js";
+
+export interface PreflightReason {
+  code: string;
+  message: string;
+}
+
+export interface PreflightResult {
+  ok: boolean;
+  reasons: PreflightReason[];
+}
+
+/**
+ * Run all preflight checks for `cwd` and return the accumulated reasons.
+ * `ok` is `true` iff `reasons.length === 0`.
+ *
+ * @param deps.resolver - Must be constructed with `useLoginShell: false`.
+ *   If omitted, a login-shell-disabled resolver is created automatically.
+ *   Passing a resolver with `useLoginShell: true` violates the preflight
+ *   contract; the function still runs but may call into the login shell.
+ */
+export function preflightSpawn(
+  cwd: string,
+  deps?: { resolver?: ToolResolver },
+): PreflightResult {
+  const resolver = deps?.resolver ?? new ToolResolver({ processExecPath: process.execPath, useLoginShell: false });
+
+  const reasons: PreflightReason[] = [];
+
+  // 1. cwd exists
+  const cwdExists = existsSync(cwd);
+  if (!cwdExists) {
+    reasons.push({ code: "DIR_MISSING", message: `Directory does not exist: ${cwd}` });
+    // No point checking isDirectory / writable if it doesn't exist.
+  } else {
+    // 2. cwd is a directory
+    try {
+      const stat = statSync(cwd);
+      if (!stat.isDirectory()) {
+        reasons.push({ code: "DIR_NOT_DIRECTORY", message: `Path is not a directory: ${cwd}` });
+      }
+    } catch (err: any) {
+      reasons.push({ code: "DIR_NOT_DIRECTORY", message: `Cannot stat path: ${err.message}` });
+    }
+
+    // 3. cwd is writable
+    try {
+      accessSync(cwd, constants.W_OK);
+    } catch {
+      reasons.push({ code: "DIR_NOT_WRITABLE", message: `Directory is not writable: ${cwd}` });
+    }
+  }
+
+  // 4. pi resolves
+  const piCmd = resolver.resolvePi();
+  if (piCmd === null) {
+    reasons.push({ code: "PI_NOT_FOUND", message: "pi binary not found via managed install or system PATH" });
+  }
+
+  // 5. node resolves
+  const nodeCmd = resolver.resolveNode();
+  if (nodeCmd === null) {
+    reasons.push({ code: "NODE_NOT_FOUND", message: "node binary not found via managed install or system PATH" });
+  }
+
+  return { ok: reasons.length === 0, reasons };
+}