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

package/packages/server/src/server.ts

@@ -18,12 +18,13 @@ import { createPreferencesStore, type PreferencesStore } from "./preferences-sto
 import { createMetaPersistence, type MetaPersistence } from "./meta-persistence.js";
 import { createSessionOrderManager, type SessionOrderManager } from "./session-order-manager.js";
 import { createPendingForkRegistry, type PendingForkRegistry } from "./pending-fork-registry.js";
+import { createPendingClientCorrelations } from "./pending-client-correlations.js";
 import { createPendingAttachRegistry } from "./pending-attach-registry.js";
 import { createPendingResumeIntentRegistry } from "./pending-resume-intent-registry.js";
 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,10 +46,12 @@ 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";
 import { registerPiCoreRoutes } from "./routes/pi-core-routes.js";
+import { registerPiChangelogRoutes } from "./routes/pi-changelog-routes.js";
 import { PiCoreChecker } from "./pi-core-checker.js";
 import { PiCoreUpdater } from "./pi-core-updater.js";
 import { registerToolRoutes } from "./routes/tool-routes.js";
@@ -65,6 +68,7 @@ import { createEditorPidRegistry } from "./editor-pid-registry.js";
 import { registerEditorRoutes } from "./routes/editor-routes.js";
 import { registerKnownServersRoutes } from "./routes/known-servers-routes.js";
 import { registerPluginConfigRoutes } from "./routes/plugin-config-routes.js";
+import { writeConfigPartial } from "./config-api.js";
 import { loadServerEntries, discoverPlugins, getPluginStatusStore } from "@blackbelt-technology/dashboard-plugin-runtime/server";
 import { createServerPluginContext } from "@blackbelt-technology/dashboard-plugin-runtime/server";
 import { getPluginConfig as getPluginConfigFromFile } from "@blackbelt-technology/pi-dashboard-shared/config.js";
@@ -143,10 +147,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`
@@ -272,6 +272,10 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
   const metaPersistence = createMetaPersistence();
   const sessionOrderManager = createSessionOrderManager(preferencesStore);
   const pendingForkRegistry = createPendingForkRegistry();
+  // Maps spawnToken → originating browser requestId. Surfaced as
+  // session_added.spawnRequestId so the client can auto-select / dismiss
+  // its placeholder by exact correlation. See change: spawn-correlation-token.
+  const pendingClientCorrelations = createPendingClientCorrelations();
 
   // Restore sessions from per-session .meta.json files (scans ~/.pi/agent/sessions/)
   const scanResult = scanAllSessions();
@@ -475,7 +479,11 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
     knownSessionIds.add(s.id);
   }
 
-  const directoryService = createDirectoryService(preferencesStore, sessionManager, config.openspec);
+  const directoryService = createDirectoryService(
+    preferencesStore,
+    sessionManager,
+    config.openspec,
+  );
 
   // mDNS peer discovery state
   let mdnsBrowser: DashboardBrowser | null = null;
@@ -524,7 +532,7 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
     },
   });
 
-  const browserGateway = createBrowserGateway(sessionManager, eventStore, piGateway, undefined, pendingForkRegistry, sessionOrderManager, preferencesStore, directoryService, terminalManager, pendingDashboardSpawns, config.maxWsBufferBytes, pendingAttachRegistry, pendingResumeIntents);
+  const browserGateway = createBrowserGateway(sessionManager, eventStore, piGateway, undefined, pendingForkRegistry, sessionOrderManager, preferencesStore, directoryService, terminalManager, pendingDashboardSpawns, config.maxWsBufferBytes, pendingAttachRegistry, pendingResumeIntents, pendingClientCorrelations);
 
   // Resolve package version once at startup
   const __require = createRequire(import.meta.url);
@@ -560,10 +568,13 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
     pendingDashboardSpawns,
     pendingAttachRegistry,
     viewedSessionTracker: browserGateway.viewedSessionTracker,
+    pendingClientCorrelations,
   });
 
   // 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,
@@ -689,6 +700,7 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
     bootstrapState,
     bootstrapQueue,
     pendingResumeIntents,
+    pendingAttachRegistry,
   });
 
   // Register route modules
@@ -709,7 +721,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 });
 
@@ -720,11 +734,11 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
     bootstrapState,
     networkGuard,
     triggerUpgradePi: async () => {
-      const packages = ["@mariozechner/pi-coding-agent"];
+      const packages = ["@earendil-works/pi-coding-agent"];
       bootstrapState.setLastInstallPackages(packages);
       bootstrapState.set({
         status: "installing",
-        progress: { step: "@mariozechner/pi-coding-agent", output: "starting upgrade…" },
+        progress: { step: "@earendil-works/pi-coding-agent", output: "starting upgrade…" },
         error: undefined,
       });
       try {
@@ -778,7 +792,7 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
       const prev = bootstrapState.getLastInstallPackages();
       const packages = prev.length > 0
         ? prev
-        : ["@mariozechner/pi-coding-agent", "@fission-ai/openspec", "tsx"];
+        : ["@earendil-works/pi-coding-agent", "@fission-ai/openspec", "tsx"];
       bootstrapState.set({
         status: "installing",
         progress: { step: "retry", output: `restarting install (${packages.length} pkg${packages.length === 1 ? "" : "s"})…` },
@@ -899,6 +913,8 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
       message: event.message,
     });
   });
+  registerPiChangelogRoutes(fastify, { bootstrapState });
+
   registerPiCoreRoutes(fastify, {
     piCoreChecker,
     piCoreUpdater,
@@ -1076,6 +1092,63 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
 
       piGateway.start(config.piPort);
 
+      // Load plugin server entries BEFORE fastify.listen() so plugins can
+      // register routes. Fastify rejects route registration after listen().
+      // Failure-isolated per-plugin via loader; awaited so all routes are
+      // mounted before requests can arrive.
+      try {
+        await loadServerEntries({
+          isEnabled: (pluginId) => {
+            const cfg = loadConfig();
+            const pluginCfg = getPluginConfigFromFile(cfg, pluginId) as Record<string, unknown>;
+            return pluginCfg.enabled !== false;
+          },
+          createContext: (plugin) => createServerPluginContext(
+            {
+              fastify,
+              sessionManager: {
+                listActive: () => sessionManager.listActive(),
+                listAll: () => sessionManager.listAll(),
+                getSession: (id: string) => sessionManager.get(id),
+              },
+              eventStore: {
+                getEvents: (sessionId) => eventStore.getEvents(sessionId, 0),
+                getLatestEvent: (sessionId) => {
+                  const events = eventStore.getEvents(sessionId, 0);
+                  return events.length > 0 ? events[events.length - 1] : undefined;
+                },
+              },
+              broadcastToSubscribers: (msg) => browserGateway.broadcast(msg as any),
+              registerPiHandler: (_type, _handler) => {},
+              registerBrowserHandler: (_type, _handler) => {},
+              getPluginConfig: (id) => {
+                const cfg = loadConfig();
+                return getPluginConfigFromFile(cfg, id);
+              },
+              updatePluginConfig: async (id, partial) => {
+                const cfg = loadConfig();
+                const current = getPluginConfigFromFile(cfg, id);
+                const merged = { ...current, ...partial };
+                let rawConfig: Record<string, unknown> = {};
+                try {
+                  const raw = (await import('node:fs')).default.readFileSync(CONFIG_FILE, 'utf-8');
+                  rawConfig = JSON.parse(raw);
+                } catch { /* start fresh */ }
+                rawConfig.plugins = { ...(rawConfig.plugins as Record<string, unknown> ?? {}), [id]: merged };
+                const fs = (await import('node:fs')).default;
+                const tmpFile = CONFIG_FILE + '.tmp.' + process.pid;
+                fs.writeFileSync(tmpFile, JSON.stringify(rawConfig, null, 2) + '\n');
+                fs.renameSync(tmpFile, CONFIG_FILE);
+                browserGateway.broadcast({ type: 'plugin_config_update', id, config: merged } as any);
+              },
+            },
+            plugin.manifest.id,
+          ),
+        });
+      } catch (err) {
+        console.error('[plugin-loader] Unexpected error during pre-listen load:', err);
+      }
+
       fastify.server.on("upgrade", (request, socket, head) => {
         // Access check for WebSocket upgrades
         const remoteAddress = request.socket.remoteAddress || "";
@@ -1159,60 +1232,6 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
       // Discover sessions and start OpenSpec polling (async, non-blocking)
       discoverAndBroadcastSessions({ sessionManager, browserGateway, directoryService });
 
-      // Load plugin server entries (non-blocking; failures isolated per plugin)
-      loadServerEntries({
-        isEnabled: (pluginId) => {
-          const cfg = loadConfig();
-          const pluginCfg = getPluginConfigFromFile(cfg, pluginId) as Record<string, unknown>;
-          return pluginCfg.enabled !== false; // default: enabled
-        },
-        createContext: (plugin) => createServerPluginContext(
-          {
-            fastify,
-            sessionManager: {
-              listActive: () => sessionManager.listActive(),
-              listAll: () => sessionManager.listAll(),
-              getSession: (id: string) => sessionManager.get(id),
-            },
-            eventStore: {
-              getEvents: (sessionId) => eventStore.getEvents(sessionId, 0),
-              getLatestEvent: (sessionId) => {
-                const events = eventStore.getEvents(sessionId, 0);
-                return events.length > 0 ? events[events.length - 1] : undefined;
-              },
-            },
-            broadcastToSubscribers: (msg) => browserGateway.broadcast(msg as any),
-            // Plugin pi/browser handler registration — stub for now;
-            // full dynamic handler registration requires a registry refactor
-            // tracked in extract-*-as-plugin changes.
-            registerPiHandler: (_type, _handler) => {},
-            registerBrowserHandler: (_type, _handler) => {},
-            getPluginConfig: (id) => {
-              const cfg = loadConfig();
-              return getPluginConfigFromFile(cfg, id);
-            },
-            updatePluginConfig: async (id, partial) => {
-              // Inline partial write (reuses CONFIG_FILE path from shared config)
-              const cfg = loadConfig();
-              const current = getPluginConfigFromFile(cfg, id);
-              const merged = { ...current, ...partial };
-              let rawConfig: Record<string, unknown> = {};
-              try {
-                const raw = (await import('node:fs')).default.readFileSync(CONFIG_FILE, 'utf-8');
-                rawConfig = JSON.parse(raw);
-              } catch { /* start fresh */ }
-              rawConfig.plugins = { ...(rawConfig.plugins as Record<string, unknown> ?? {}), [id]: merged };
-              const fs = (await import('node:fs')).default;
-              const tmpFile = CONFIG_FILE + '.tmp.' + process.pid;
-              fs.writeFileSync(tmpFile, JSON.stringify(rawConfig, null, 2) + '\n');
-              fs.renameSync(tmpFile, CONFIG_FILE);
-              browserGateway.broadcast({ type: 'plugin_config_update', id, config: merged } as any);
-            },
-          },
-          plugin.manifest.id,
-        ),
-      }).catch((err) => console.error('[plugin-loader] Unexpected error:', err));
-
       // Auto-register plugin bridge entries
       const discoveredPlugins = discoverPlugins();
       const pluginsWithBridges = discoveredPlugins

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

@@ -3,6 +3,7 @@
  * These expose WebSocket-only operations as HTTP endpoints
  * for use by skills, scripts, and external tooling.
  */
+import { existsSync } from "node:fs";
 import type { FastifyInstance } from "fastify";
 import type { SessionManager } from "./memory-session-manager.js";
 import type { PiGateway } from "./pi-gateway.js";
@@ -15,6 +16,7 @@ import type { PendingResumeIntentRegistry } from "./pending-resume-intent-regist
 import type { BootstrapStateStore } from "./bootstrap-state.js";
 import type { BootstrapQueue } from "./bootstrap-queue.js";
 import { attachRenameTarget, detachShouldClearName } from "./proposal-attach-naming.js";
+import { FORK_DEGRADED_TO_NEW_MESSAGE, FORK_DEGRADED_TO_NEW_CODE } from "./browser-handlers/session-action-handler.js";
 
 export interface SessionApiDeps {
   sessionManager: SessionManager;
@@ -36,6 +38,13 @@ export interface SessionApiDeps {
    * See change: preserve-session-order-on-reboot.
    */
   pendingResumeIntents?: PendingResumeIntentRegistry;
+  /**
+   * Optional pending-attach registry. When provided, the resume endpoint's
+   * fork-empty-session degradation path inherits the parent's
+   * `attachedProposal` for the new spawn.
+   * See change: fix-fork-empty-session-silent-timeout.
+   */
+  pendingAttachRegistry?: import("./pending-attach-registry.js").PendingAttachRegistry;
 }
 
 type IdParams = { Params: { id: string } };
@@ -48,7 +57,7 @@ function getSessionOrFail(sessionManager: SessionManager, id: string): { session
 }
 
 export function registerSessionApi(fastify: FastifyInstance, deps: SessionApiDeps) {
-  const { sessionManager, piGateway, browserGateway, pendingForkRegistry, pendingDashboardSpawns, bootstrapState, bootstrapQueue, pendingResumeIntents } = deps;
+  const { sessionManager, piGateway, browserGateway, pendingForkRegistry, pendingDashboardSpawns, bootstrapState, bootstrapQueue, pendingResumeIntents, pendingAttachRegistry } = deps;
 
   /**
    * Gate pi-dependent operations on bootstrap status. Returns:
@@ -282,8 +291,44 @@ export function registerSessionApi(fastify: FastifyInstance, deps: SessionApiDep
         reply.code(409);
         return { success: false, error: "session is already being resumed" } satisfies ApiResponse;
       }
-      if (mode === "fork" && pendingForkRegistry) {
-        pendingForkRegistry.recordFork(session.cwd, id);
+      // Fork preflight: silent-degrade when the source has no on-disk JSONL.
+      // Mirrors the WS-handler logic. See change:
+      // fix-fork-empty-session-silent-timeout.
+      if (mode === "fork" && !existsSync(session.sessionFile)) {
+        // Inherit attachedProposal from parent.
+        if (session.attachedProposal && pendingAttachRegistry) {
+          pendingAttachRegistry.enqueue(session.cwd, session.attachedProposal);
+        }
+        const degradeConfig = loadConfig();
+        const degradeResult = await spawnPiSession(session.cwd, {
+          strategy: degradeConfig.spawnStrategy,
+        });
+        if (degradeResult.process && degradeResult.pid) {
+          browserGateway.headlessPidRegistry.register(
+            degradeResult.pid,
+            session.cwd,
+            degradeResult.process,
+            degradeResult.spawnToken,
+          );
+        }
+        if (degradeResult.dashboardSpawned && degradeResult.success) {
+          pendingDashboardSpawns?.set(
+            session.cwd,
+            (pendingDashboardSpawns?.get(session.cwd) ?? 0) + 1,
+          );
+        }
+        if (!degradeResult.success) {
+          reply.code(500);
+          return {
+            success: false,
+            error: degradeResult.message,
+          } satisfies ApiResponse;
+        }
+        return {
+          success: true,
+          data: { message: FORK_DEGRADED_TO_NEW_MESSAGE },
+          code: FORK_DEGRADED_TO_NEW_CODE,
+        } satisfies ApiResponse<{ message: string }>;
       }
       // Tag the user-resume intent BEFORE spawning. REST resume always
       // uses "front" placement — the only "keep" path is drag-to-resume
@@ -297,6 +342,12 @@ export function registerSessionApi(fastify: FastifyInstance, deps: SessionApiDep
         mode,
         strategy: config.spawnStrategy,
       });
+      // Fork bookkeeping uses the spawn token (not cwd) so two concurrent
+      // forks in the same cwd correlate correctly. See change:
+      // spawn-correlation-token.
+      if (mode === "fork" && pendingForkRegistry && spawnResult.spawnToken) {
+        pendingForkRegistry.recordFork(spawnResult.spawnToken, id);
+      }
       if (spawnResult.dashboardSpawned && spawnResult.success) {
         pendingDashboardSpawns?.set(session.cwd, (pendingDashboardSpawns?.get(session.cwd) ?? 0) + 1);
       }

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

@@ -1,11 +1,12 @@
 /**
  * Standalone session discovery — lists pi sessions for a given cwd
- * without requiring @mariozechner/pi-coding-agent.
+ * without requiring @earendil-works/pi-coding-agent.
  * Reads session JSONL files from ~/.pi/agent/sessions/<encoded-cwd>/.
  */
 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-file-reader.ts

@@ -1,6 +1,6 @@
 /**
  * Standalone JSONL session file reader.
- * Reads pi session files without requiring @mariozechner/pi-coding-agent.
+ * Reads pi session files without requiring @earendil-works/pi-coding-agent.
  * Falls back to linear entry order (no tree branching support).
  */
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";

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