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

package/packages/server/src/server.ts

@@ -18,6 +18,7 @@ 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";
@@ -34,6 +35,7 @@ import { discoverAndBroadcastSessions } from "./session-bootstrap.js";
 import { scanAllSessions } from "./session-scanner.js";
 import { needsMigration, runMigration } from "./migrate-persistence.js";
 import { detectZrokBinary, cleanupStaleZrok, createTunnel, deleteTunnel, scavengeOrphanZrokProcesses, getTunnelUrl } from "./tunnel.js";
+import { startTunnelWatchdog, stopTunnelWatchdog } from "./tunnel-watchdog.js";
 import { registerAuthPlugin, validateWsUpgrade } from "./auth-plugin.js";
 import { findBundledExtension, registerBridgeExtension } from "@blackbelt-technology/pi-dashboard-shared/bridge-register.js";
 import { createNetworkGuard, isLoopback, isBypassedHost } from "./localhost-guard.js";
@@ -44,18 +46,22 @@ import { registerSessionRoutes } from "./routes/session-routes.js";
 import { registerGitRoutes } from "./routes/git-routes.js";
 import { registerFileRoutes } from "./routes/file-routes.js";
 import { registerOpenSpecRoutes } from "./routes/openspec-routes.js";
+import { registerOpenSpecGroupRoutes } from "./routes/openspec-group-routes.js";
+import { createOpenSpecGroupStore, joinGroupIdsToOpenSpecData } from "./openspec-group-store.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";
 import { registerJjRoutes } from "./routes/jj-routes.js";
 import { registerBootstrapRoutes } from "./routes/bootstrap-routes.js";
 import { createBootstrapState, type BootstrapStateStore } from "./bootstrap-state.js";
+import { detectLegacyPiInstalls } from "./legacy-pi-cleanup.js";
 import { createBootstrapQueue } from "./bootstrap-queue.js";
 import { bootstrapInstall } from "@blackbelt-technology/pi-dashboard-shared/bootstrap-install.js";
 import { getDefaultRegistry } from "@blackbelt-technology/pi-dashboard-shared/tool-registry/index.js";
@@ -66,6 +72,12 @@ 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 { createModelProxyAuthGate } from "./model-proxy/auth-gate.js";
+import { registerModelProxyRoutes } from "./routes/model-proxy-routes.js";
+import { registerModelProxyApiKeyRoutes } from "./routes/model-proxy-api-key-routes.js";
+import { registerModelProxyRefreshRoutes } from "./routes/model-proxy-refresh-routes.js";
+import { getModelRegistry, getStreamSimpleFn } from "./model-proxy/registry-singleton.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";
@@ -81,6 +93,12 @@ export interface ServerConfig {
   shutdownIdleSeconds: number;
   tunnel: boolean;
   tunnelReservedToken?: string;
+  tunnelWatchdog?: {
+    enabled: boolean;
+    intervalMs: number;
+    failureThreshold: number;
+    probeTimeoutMs: number;
+  };
   authConfig?: AuthConfig;
   /** Override WS ping interval for pi-gateway (ms). Default 60000. Set 0 to disable. */
   pingInterval?: number;
@@ -269,6 +287,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();
@@ -472,10 +494,32 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
     knownSessionIds.add(s.id);
   }
 
-  const directoryService = createDirectoryService(preferencesStore, sessionManager, config.openspec);
+  // Create the OpenSpec change-grouping store BEFORE the directory-service so
+  // the latter can join `groupId` into every `OpenSpecChange` it produces.
+  // See change: add-openspec-change-grouping (task 4.2).
+  const openspecGroupStore = createOpenSpecGroupStore();
+
+  const directoryService = createDirectoryService(
+    preferencesStore,
+    sessionManager,
+    config.openspec,
+    {
+      enrichOpenSpecData: async (cwd, data) => {
+        try {
+          const file = await openspecGroupStore.read(cwd);
+          return joinGroupIdsToOpenSpecData(data, file.assignments);
+        } catch {
+          // Bad file (e.g., unsupported schemaVersion) — fall back to unjoined.
+          return data;
+        }
+      },
+    },
+  );
 
   // mDNS peer discovery state
   let mdnsBrowser: DashboardBrowser | null = null;
+  // Optional second-port Fastify instance for model proxy (/v1/*)
+  let secondFastify: Awaited<ReturnType<typeof import("fastify").default>> | null = null;
   const peerServers = new Map<string, DiscoveredServer>();
 
   const piGateway = createPiGateway(sessionManager, {
@@ -521,7 +565,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);
@@ -557,6 +601,7 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
     pendingDashboardSpawns,
     pendingAttachRegistry,
     viewedSessionTracker: browserGateway.viewedSessionTracker,
+    pendingClientCorrelations,
   });
 
   // Auto-shutdown idle timer
@@ -649,6 +694,14 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
   // routes can gate spawn operations on bootstrap status.
   // See change: unified-bootstrap-install.
   const bootstrapState = createBootstrapState();
+  // Scan for legacy `@mariozechner/pi-coding-agent` installs so the UI can
+  // offer a one-click cleanup. See: legacy-pi-cleanup.ts. Best-effort —
+  // detection failure is non-fatal (returns []).
+  try {
+    bootstrapState.set({ legacyPiInstalls: detectLegacyPiInstalls() });
+  } catch (err: any) {
+    console.warn("[legacy-pi] detection failed:", err?.message ?? err);
+  }
   const bootstrapQueue = createBootstrapQueue();
   // Centralized post-install repair: full ToolRegistry rescan +
   // OpenSpec / pi-resources force-refresh on every `installing → ready`
@@ -688,6 +741,7 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
     bootstrapState,
     bootstrapQueue,
     pendingResumeIntents,
+    pendingAttachRegistry,
   });
 
   // Register route modules
@@ -708,6 +762,29 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
       if (data) browserGateway.broadcastToAll({ type: "openspec_update", cwd, data });
     },
   });
+  // OpenSpec change-grouping routes (store created earlier next to
+  // directory-service so the join can run during polls).
+  // See change: add-openspec-change-grouping.
+  openspecGroupStore.subscribe((cwd, payload) => {
+    browserGateway.broadcastToAll({
+      type: "openspec_groups_update",
+      cwd,
+      groups: payload.groups,
+      assignments: payload.assignments,
+    });
+    // Refresh OpenSpecData so the joined `groupId` field reflects the new
+    // assignments on subscribers that don't consume `openspec_groups_update`
+    // directly. Fire-and-forget; failures are logged inside refreshOpenSpec.
+    directoryService.refreshOpenSpec(cwd).then((data) => {
+      browserGateway.broadcastToAll({ type: "openspec_update", cwd, data });
+    }).catch(() => {});
+  });
+  registerOpenSpecGroupRoutes(fastify, {
+    sessionManager,
+    preferencesStore,
+    networkGuard,
+    store: openspecGroupStore,
+  });
   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);
@@ -721,11 +798,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 {
@@ -779,7 +856,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"];
       bootstrapState.set({
         status: "installing",
         progress: { step: "retry", output: `restarting install (${packages.length} pkg${packages.length === 1 ? "" : "s"})…` },
@@ -900,6 +977,8 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
       message: event.message,
     });
   });
+  registerPiChangelogRoutes(fastify, { bootstrapState });
+
   registerPiCoreRoutes(fastify, {
     piCoreChecker,
     piCoreUpdater,
@@ -938,7 +1017,51 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
     networkGuard,
     broadcast: (msg) => browserGateway.broadcast(msg),
   });
-  registerProviderRoutes(fastify, { networkGuard, piGateway, browserGateway });
+  registerProviderRoutes(fastify, { networkGuard, piGateway, browserGateway, port: config.port });
+
+  // ── Model Proxy ───────────────────────────────────────────────────
+  {
+    const fullCfg = loadConfig();
+    if (fullCfg.modelProxy.enabled) {
+      // Register proxy auth gate (runs BEFORE JWT hook for /v1/* routes)
+      const proxyAuthGate = createModelProxyAuthGate({
+        getConfig: () => loadConfig().modelProxy,
+        persistKeyUsage: (apiKeys) => {
+          writeConfigPartial({ modelProxy: { apiKeys } });
+        },
+      });
+      fastify.addHook("onRequest", proxyAuthGate);
+
+      // Register /v1/* routes
+      registerModelProxyRoutes(fastify, {
+        getConfig: () => loadConfig().modelProxy,
+        getRegistry: async () => {
+          try {
+            return await getModelRegistry();
+          } catch {
+            return null;
+          }
+        },
+        streamSimple: (opts: any) => {
+          const fn = getStreamSimpleFn();
+          if (!fn) throw new Error("streamSimple not available");
+          return fn(opts.model, { messages: opts.messages, system: opts.system, tools: opts.tools }, opts);
+        },
+      });
+
+      // Register API key management routes (JWT-gated)
+      registerModelProxyApiKeyRoutes(fastify, {
+        networkGuard,
+        getModelProxyConfig: () => loadConfig().modelProxy,
+        writeModelProxyApiKeys: async (apiKeys) => {
+          writeConfigPartial({ modelProxy: { apiKeys } });
+        },
+      });
+
+      // Register refresh route (JWT-gated)
+      registerModelProxyRefreshRoutes(fastify);
+    }
+  }
 
   // Serve static files / SPA fallback.
   //
@@ -1071,12 +1194,82 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
       // Clean up orphan headless processes from a previous server instance
       browserGateway.headlessPidRegistry.cleanupOrphans();
 
+      // Wire the singleton KeeperManager into the headless-pid registry so
+      // `writeRpc` can forward `dispatch_extension_command` lines to the
+      // session's keeper UDS, and so `cleanupKeeperOrphans` can reattach
+      // surviving keepers after a server restart. Same instance the spawn
+      // path uses. See change: add-rpc-stdin-dispatch-with-keeper-sidecar.
+      try {
+        const { getKeeperManager } = await import("./process-manager.js");
+        browserGateway.headlessPidRegistry.setKeeperWriter(getKeeperManager());
+        await browserGateway.headlessPidRegistry.cleanupKeeperOrphans();
+      } catch (err) {
+        console.warn("[dashboard] keeper-manager wire-up failed (RPC dispatch disabled):", err);
+      }
+
       // Clean up orphan code-server processes from a previous server instance.
       // Runs before fastify.listen, so no editor start request can race with the sweep.
       await editorPidRegistry.cleanupOrphans();
 
       piGateway.start(config.piPort);
 
+      // 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 || "";
@@ -1112,6 +1305,40 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
       console.log(`Dashboard server running at http://localhost:${config.port}`);
       console.log(`Pi gateway listening on port ${config.piPort}`);
 
+      // ── Optional second port for model proxy (/v1/*) ──────────────
+      {
+        const proxyCfg = loadConfig().modelProxy;
+        if (proxyCfg.enabled && proxyCfg.secondPort) {
+          try {
+            const F = (await import("fastify")).default;
+            const sf = F({ logger: false });
+            const proxyAuthGate = createModelProxyAuthGate({
+              getConfig: () => loadConfig().modelProxy,
+              persistKeyUsage: (apiKeys) => {
+                writeConfigPartial({ modelProxy: { apiKeys } });
+              },
+            });
+            sf.addHook("onRequest", proxyAuthGate);
+            registerModelProxyRoutes(sf, {
+              getConfig: () => loadConfig().modelProxy,
+              getRegistry: async () => {
+                try { return await getModelRegistry(); } catch { return null; }
+              },
+              streamSimple: (opts: any) => {
+                const fn = getStreamSimpleFn();
+                if (!fn) throw new Error("streamSimple not available");
+                return fn(opts.model, { messages: opts.messages, system: opts.system, tools: opts.tools }, opts);
+              },
+            });
+            await sf.listen({ port: proxyCfg.secondPort, host: "127.0.0.1" });
+            secondFastify = sf as any;
+            console.log(`Model proxy second port listening at http://127.0.0.1:${proxyCfg.secondPort}`);
+          } catch (err) {
+            console.warn(`Model proxy second port bind failed (continuing without):`, err);
+          }
+        }
+      }
+
       // Advertise via mDNS
       try {
         advertiseDashboard(config.port, config.piPort);
@@ -1153,6 +1380,21 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
           const tunnelUrl = await createTunnel(config.port, config.tunnelReservedToken);
           if (tunnelUrl) {
             console.log(`🌐 Tunnel: ${tunnelUrl}`);
+            // Start the watchdog so a stale zrok edge connection is detected
+            // and recycled automatically (preserves reserved token / URL).
+            const wd = config.tunnelWatchdog;
+            if (wd?.enabled !== false) {
+              startTunnelWatchdog(
+                {
+                  getUrl: getTunnelUrl,
+                  recycle: async () => {
+                    await deleteTunnel(config.port);
+                    return await createTunnel(config.port, config.tunnelReservedToken);
+                  },
+                },
+                wd,
+              );
+            }
           }
         }
       }
@@ -1160,60 +1402,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
@@ -1259,6 +1447,7 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
       unsubscribeQueueComplete();
       bootstrapState.dispose();
       bootstrapQueue.clear("server shutting down");
+      stopTunnelWatchdog();
       await deleteTunnel(config.port);
       piGateway.stop();
       for (const client of browserGateway.wss.clients) {
@@ -1274,6 +1463,11 @@ export async function createServer(config: ServerConfig): Promise<DashboardServe
       editorManager.stopAll();
       // Close any pending OAuth callback servers
       try { const { closeAllCallbackServers } = await import("./oauth-callback-server.js"); await closeAllCallbackServers(); } catch {}
+      // Close second port before main server
+      if (secondFastify) {
+        try { await secondFastify.close(); } catch { /* ignore */ }
+        secondFastify = null;
+      }
       await fastify.close();
     },
   };

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,8 @@ 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";
+import { keeperOptsFromSpawnResult } from "./headless-pid-registry.js";
 
 export interface SessionApiDeps {
   sessionManager: SessionManager;
@@ -36,6 +39,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 +58,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:
@@ -230,7 +240,13 @@ export function registerSessionApi(fastify: FastifyInstance, deps: SessionApiDep
         const config = loadConfig();
         const spawnResult = await spawnPiSession(cwd, { strategy: config.spawnStrategy });
         if (spawnResult.process && spawnResult.pid) {
-          browserGateway.headlessPidRegistry.register(spawnResult.pid, cwd, spawnResult.process);
+          browserGateway.headlessPidRegistry.register(
+            spawnResult.pid,
+            cwd,
+            spawnResult.process,
+            spawnResult.spawnToken,
+            keeperOptsFromSpawnResult(spawnResult),
+          );
         }
         if (spawnResult.dashboardSpawned && spawnResult.success) {
           pendingDashboardSpawns?.set(cwd, (pendingDashboardSpawns?.get(cwd) ?? 0) + 1);
@@ -282,8 +298,45 @@ 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,
+            keeperOptsFromSpawnResult(degradeResult),
+          );
+        }
+        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 +350,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-discovery.ts

@@ -1,6 +1,6 @@
 /**
  * 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";

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";