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

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

@@ -15,7 +15,44 @@ import { createHeadlessPidRegistry, type HeadlessPidRegistry } from "./headless-
 import type { PendingForkRegistry } from "./pending-fork-registry.js";
 import type { SessionOrderManager } from "./session-order-manager.js";
 import type { PreferencesStore } from "./preferences-store.js";
-import type { DirectoryService } from "./directory-service.js";
+import { hasOpenSpecDir, type DirectoryService } from "./directory-service.js";
+
+/**
+ * Pure helper: build the per-cwd `openspec_update` messages a freshly
+ * connecting browser should receive. One message per known cwd.
+ * Disambiguates three states:
+ *   - cache populated         → cached payload
+ *   - openspec dir but cold   → { initialized: false, pending: true }
+ *   - no openspec dir         → { initialized: false, pending: false }
+ *
+ * Exported so cold-boot snapshot semantics can be unit-tested without
+ * spinning up a WS server. See change: fix-cold-boot-openspec-protocol.
+ */
+export function buildOpenSpecConnectSnapshot(
+  directoryService: Pick<DirectoryService, "knownDirectories" | "getOpenSpecData">,
+  hasDir: (cwd: string) => boolean,
+): Array<ServerToBrowserMessage> {
+  const out: Array<ServerToBrowserMessage> = [];
+  for (const cwd of directoryService.knownDirectories()) {
+    const cached = directoryService.getOpenSpecData(cwd);
+    if (cached && cached.initialized) {
+      out.push({ type: "openspec_update", cwd, data: cached });
+    } else if (hasDir(cwd)) {
+      out.push({
+        type: "openspec_update",
+        cwd,
+        data: { initialized: false, pending: true, changes: [] },
+      });
+    } else {
+      out.push({
+        type: "openspec_update",
+        cwd,
+        data: { initialized: false, pending: false, changes: [] },
+      });
+    }
+  }
+  return out;
+}
 import { createPendingResumeRegistry, type PendingResumeRegistry } from "./pending-resume-registry.js";
 import { createViewedSessionTracker, type ViewedSessionTracker } from "./viewed-session-tracker.js";
 import type { TerminalManager } from "./terminal-manager.js";
@@ -31,7 +68,7 @@ import { handlePinDirectory, handleUnpinDirectory, handleReorderPinnedDirs, hand
 export interface BrowserGateway {
   wss: WebSocketServer;
   broadcastEvent(sessionId: string, seq: number, event: any): void;
-  broadcastSessionAdded(session: any): void;
+  broadcastSessionAdded(session: any, opts?: { spawnRequestId?: string }): void;
   broadcastSessionUpdated(sessionId: string, updates: any): void;
   broadcastSessionRemoved(sessionId: string): void;
   sendToSubscribers(sessionId: string, msg: ServerToBrowserMessage): void;
@@ -82,6 +119,7 @@ export function createBrowserGateway(
   maxWsBufferBytes?: number,
   pendingAttachRegistry?: import("./pending-attach-registry.js").PendingAttachRegistry,
   pendingResumeIntents?: import("./pending-resume-intent-registry.js").PendingResumeIntentRegistry,
+  pendingClientCorrelations?: import("./pending-client-correlations.js").PendingClientCorrelations,
 ): BrowserGateway {
   const wss = new WebSocketServer({ noServer: true });
 
@@ -208,10 +246,21 @@ export function createBrowserGateway(
     const subs = new Set<string>();
     subscriptions.set(ws, subs);
 
-    // Send all sessions on connect (client filters by hidden flag)
-    const allSessions = sessionManager.listAll();
-    for (const session of allSessions) {
-      sendTo(ws, { type: "session_added", session });
+    // Atomic snapshot of the full session registry + per-cwd orders.
+    // Replaces the legacy per-session `session_added` loop and per-cwd
+    // `sessions_reordered` loop. Client REPLACES (not merges) its
+    // `sessions` Map and `sessionOrderMap` on receipt so stale ids from a
+    // previous server lifetime are dropped atomically.
+    // See change: fix-stale-sessions-on-reconnect.
+    {
+      const sessionsSnapshot = sessionManager.listAll();
+      const orders: Record<string, string[]> = {};
+      if (sessionOrderManager) {
+        for (const [cwd, sessionIds] of Object.entries(sessionOrderManager.getAllOrders())) {
+          if (sessionIds.length > 0) orders[cwd] = sessionIds;
+        }
+      }
+      sendTo(ws, { type: "sessions_snapshot", sessions: sessionsSnapshot, orders });
     }
 
     // Send pinned directories on connect
@@ -219,23 +268,12 @@ export function createBrowserGateway(
       sendTo(ws, { type: "pinned_dirs_updated", paths: preferencesStore.getPinnedDirectories() });
     }
 
-    // Send session orders for all cwds
-    if (sessionOrderManager) {
-      const allOrders = sessionOrderManager.getAllOrders();
-      for (const [cwd, sessionIds] of Object.entries(allOrders)) {
-        if (sessionIds.length > 0) {
-          sendTo(ws, { type: "sessions_reordered", cwd, sessionIds });
-        }
-      }
-    }
-
-    // Send cached OpenSpec data for all known directories
+    // Send OpenSpec data for every known directory — exactly one
+    // `openspec_update` per cwd, never silently omit.
+    // See change: fix-cold-boot-openspec-protocol.
     if (directoryService) {
-      for (const cwd of directoryService.knownDirectories()) {
-        const data = directoryService.getOpenSpecData(cwd);
-        if (data && data.initialized) {
-          sendTo(ws, { type: "openspec_update", cwd, data });
-        }
+      for (const msg of buildOpenSpecConnectSnapshot(directoryService, hasOpenSpecDir)) {
+        sendTo(ws, msg);
       }
     }
 
@@ -270,6 +308,7 @@ export function createBrowserGateway(
           headlessPidRegistry, pendingResumeRegistry, pendingDashboardSpawns,
           pendingAttachRegistry,
           pendingResumeIntents,
+          pendingClientCorrelations,
           sendTo, broadcast, getSubscribers, replayPendingUiRequests,
           trackUiRequest: trackUiRequest,
           markReplaying(targetWs, sessionId) {
@@ -537,8 +576,15 @@ export function createBrowserGateway(
       }
     },
 
-    broadcastSessionAdded(session: any) {
-      broadcast({ type: "session_added", session });
+    broadcastSessionAdded(session: any, opts?: { spawnRequestId?: string }) {
+      // Carry the originating client `requestId` (when known) so the
+      // browser can auto-select / dismiss its placeholder by exact
+      // correlation. See change: spawn-correlation-token.
+      broadcast({
+        type: "session_added",
+        session,
+        ...(opts?.spawnRequestId ? { spawnRequestId: opts.spawnRequestId } : {}),
+      });
     },
 
     broadcastSessionUpdated(sessionId: string, updates: any) {

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

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

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

@@ -16,6 +16,7 @@ import type { HeadlessPidRegistry } from "../headless-pid-registry.js";
 import type { PendingResumeRegistry } from "../pending-resume-registry.js";
 import type { PendingAttachRegistry } from "../pending-attach-registry.js";
 import type { PendingResumeIntentRegistry } from "../pending-resume-intent-registry.js";
+import type { PendingClientCorrelations } from "../pending-client-correlations.js";
 
 export interface BrowserHandlerContext {
   ws: WebSocket;
@@ -43,6 +44,14 @@ export interface BrowserHandlerContext {
    * See change: preserve-session-order-on-reboot.
    */
   pendingResumeIntents?: PendingResumeIntentRegistry;
+  /**
+   * Optional registry mapping `spawnToken → requestId` for client-side
+   * correlation. When set, browser-initiated spawns/resumes that carry a
+   * `requestId` are recorded so the eventual `session_added` broadcast
+   * carries `spawnRequestId` for auto-select / placeholder dismissal.
+   * See change: spawn-correlation-token.
+   */
+  pendingClientCorrelations?: PendingClientCorrelations;
   /** Send message to a specific WebSocket */
   sendTo(ws: WebSocket, msg: ServerToBrowserMessage): void;
   /** Broadcast to all connected browsers */

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

@@ -1,10 +1,15 @@
 /**
  * Session action handlers: send_prompt, abort, resume, spawn, shutdown, flow_control.
  */
+import { existsSync } from "node:fs";
 import type { BrowserToServerMessage } from "@blackbelt-technology/pi-dashboard-shared/browser-protocol.js";
 import type { BrowserHandlerContext } from "./handler-context.js";
 import { spawnPiSession } from "../process-manager.js";
+import { ToolResolver } from "@blackbelt-technology/pi-dashboard-shared/platform/binary-lookup.js";
 import { loadConfig } from "@blackbelt-technology/pi-dashboard-shared/config.js";
+import { preflightSpawn } from "../spawn-preflight.js";
+import { getSpawnRegisterWatchdog } from "../spawn-register-watchdog.js";
+import { appendSpawnFailure } from "../spawn-failure-log.js";
 import { createBranchedSessionFile } from "../session-file-reader.js";
 import {
   killPidWithGroup,
@@ -15,6 +20,19 @@ import {
 } from "@blackbelt-technology/pi-dashboard-shared/platform/process-identify.js";
 import { shouldInterceptReload } from "./session-action-helpers.js";
 
+/**
+ * Status message + code emitted when fork is attempted on a session whose
+ * `.jsonl` does not exist on disk yet (empty session, no persisted entries).
+ * The dashboard silently degrades to a fresh spawn in the same cwd — fork
+ * has no history to copy, so the user-meaningful semantic of "fork" and
+ * "new" is identical here. The structured code lets the client surface a
+ * non-blocking toast.
+ * See change: fix-fork-empty-session-silent-timeout.
+ */
+export const FORK_DEGRADED_TO_NEW_MESSAGE =
+  "Started a fresh session \u2014 the source had no persisted history to fork from.";
+export const FORK_DEGRADED_TO_NEW_CODE = "FORK_DEGRADED_TO_NEW";
+
 /**
  * Find headless pi PIDs associated with a session-id marker and kill them.
  * Delegates platform branching to `platform/process-identify.ts` — Windows
@@ -236,10 +254,10 @@ export async function handleResumeSession(
   msg: Extract<BrowserToServerMessage, { type: "resume_session" }>,
   ctx: BrowserHandlerContext,
 ): Promise<void> {
-  const { ws, sessionManager, pendingForkRegistry, headlessPidRegistry, pendingDashboardSpawns, pendingResumeIntents, sendTo } = ctx;
+  const { ws, sessionManager, pendingForkRegistry, headlessPidRegistry, pendingDashboardSpawns, pendingResumeIntents, pendingClientCorrelations, sendTo } = ctx;
   const session = sessionManager.get(msg.sessionId);
   if (!session) {
-    sendTo(ws, { type: "resume_result", sessionId: msg.sessionId, success: false, message: "Session not found" });
+    sendTo(ws, { type: "resume_result", sessionId: msg.sessionId, success: false, message: "Session not found", requestId: msg.requestId });
     return;
   }
   // Resolve placement intent. Old browsers omit the field; default to
@@ -248,28 +266,71 @@ export async function handleResumeSession(
   // See change: differentiate-resume-intent-by-trigger.
   const placement: "front" | "keep" = msg.placement ?? "front";
   if (!session.sessionFile) {
-    sendTo(ws, { type: "resume_result", sessionId: msg.sessionId, success: false, message: "Session file is unknown (pre-migration session)" });
+    sendTo(ws, { type: "resume_result", sessionId: msg.sessionId, success: false, message: "Session file is unknown (pre-migration session)", requestId: msg.requestId });
     return;
   }
   if (msg.mode === "continue" && session.status !== "ended") {
-    sendTo(ws, { type: "resume_result", sessionId: msg.sessionId, success: false, message: "Session is already active" });
+    sendTo(ws, { type: "resume_result", sessionId: msg.sessionId, success: false, message: "Session is already active", requestId: msg.requestId });
     return;
   }
   if (session.resuming) {
-    sendTo(ws, { type: "resume_result", sessionId: msg.sessionId, success: false, message: "Session is already being resumed" });
+    sendTo(ws, { type: "resume_result", sessionId: msg.sessionId, success: false, message: "Session is already being resumed", requestId: msg.requestId });
     return;
   }
-  if (msg.mode === "fork" && pendingForkRegistry) {
-    pendingForkRegistry.recordFork(session.cwd, msg.sessionId);
+  // Fork preflight: silent-degrade when the source session has no on-disk
+  // JSONL yet (empty session, no persisted entries). `pi --fork <missing>`
+  // would crash silently and produce a 30s register-timeout; instead we
+  // spawn a fresh pi in the same cwd and surface `code: FORK_DEGRADED_TO_NEW`
+  // so the client can render a non-blocking toast. The parent's
+  // attachedProposal (if any) is inherited via `pendingAttachRegistry`
+  // since fork's own inheritance path doesn't run on this branch.
+  // See change: fix-fork-empty-session-silent-timeout.
+  if (msg.mode === "fork" && session.sessionFile && !existsSync(session.sessionFile)) {
+    // Inherit attachedProposal from parent so the new session still
+    // tracks the change the user was working on.
+    const pendingAttachRegistry = ctx.pendingAttachRegistry;
+    if (session.attachedProposal && pendingAttachRegistry) {
+      pendingAttachRegistry.enqueue(session.cwd, session.attachedProposal);
+    }
+    const degradeConfig = loadConfig();
+    // Fresh spawn: no sessionFile, no mode — just `pi --mode rpc`.
+    const degradeResult = await spawnPiSession(session.cwd, {
+      strategy: degradeConfig.spawnStrategy,
+    });
+    if (degradeResult.process && degradeResult.pid) {
+      headlessPidRegistry.register(
+        degradeResult.pid,
+        session.cwd,
+        degradeResult.process,
+        degradeResult.spawnToken,
+      );
+    }
+    if (msg.requestId && degradeResult.spawnToken && pendingClientCorrelations) {
+      pendingClientCorrelations.record(degradeResult.spawnToken, msg.requestId);
+    }
+    if (degradeResult.dashboardSpawned && degradeResult.success) {
+      pendingDashboardSpawns?.set(
+        session.cwd,
+        (pendingDashboardSpawns?.get(session.cwd) ?? 0) + 1,
+      );
+    }
+    sendTo(ws, {
+      type: "resume_result",
+      sessionId: msg.sessionId,
+      success: degradeResult.success,
+      message: degradeResult.success ? FORK_DEGRADED_TO_NEW_MESSAGE : degradeResult.message,
+      requestId: msg.requestId,
+      ...(degradeResult.success ? { code: FORK_DEGRADED_TO_NEW_CODE } : {}),
+    });
+    return;
   }
-
   // For fork-from-message: create a pruned session file first
   let forkSessionFile = session.sessionFile;
   if (msg.mode === "fork" && msg.entryId) {
     try {
       forkSessionFile = createBranchedSessionFile(session.sessionFile, msg.entryId);
     } catch (err: any) {
-      sendTo(ws, { type: "resume_result", sessionId: msg.sessionId, success: false, message: `Fork from entry failed: ${err.message}` });
+      sendTo(ws, { type: "resume_result", sessionId: msg.sessionId, success: false, message: `Fork from entry failed: ${err.message}`, requestId: msg.requestId });
       return;
     }
   }
@@ -289,30 +350,61 @@ export async function handleResumeSession(
     mode: msg.mode,
     strategy: resumeConfig.spawnStrategy,
   });
+  // Record fork parent keyed by spawn token (was: keyed by cwd, racy on
+  // multi-fork-in-same-cwd). See change: spawn-correlation-token.
+  if (msg.mode === "fork" && pendingForkRegistry && result.spawnToken) {
+    pendingForkRegistry.recordFork(result.spawnToken, msg.sessionId);
+  }
+  // Record client-correlation so the eventual session_added carries
+  // spawnRequestId. See change: spawn-correlation-token.
+  if (msg.requestId && result.spawnToken && pendingClientCorrelations) {
+    pendingClientCorrelations.record(result.spawnToken, msg.requestId);
+  }
   if (result.dashboardSpawned && result.success) {
     pendingDashboardSpawns?.set(session.cwd, (pendingDashboardSpawns?.get(session.cwd) ?? 0) + 1);
   }
   if (result.process && result.pid) {
-    headlessPidRegistry.register(result.pid, session.cwd, result.process);
+    headlessPidRegistry.register(result.pid, session.cwd, result.process, result.spawnToken);
   }
-  sendTo(ws, { type: "resume_result", sessionId: msg.sessionId, success: result.success, message: result.message });
+  sendTo(ws, { type: "resume_result", sessionId: msg.sessionId, success: result.success, message: result.message, requestId: msg.requestId });
 }
 
 export async function handleSpawnSession(
   msg: Extract<BrowserToServerMessage, { type: "spawn_session" }>,
   ctx: BrowserHandlerContext,
 ): Promise<void> {
-  const { ws, headlessPidRegistry, pendingDashboardSpawns, pendingAttachRegistry, sendTo } = ctx;
+  const { ws, headlessPidRegistry, pendingDashboardSpawns, pendingAttachRegistry, pendingClientCorrelations, sendTo } = ctx;
   const config = loadConfig();
   const strategy = config.spawnStrategy ?? "tmux";
 
   // Queue the optional attach intent BEFORE awaiting the spawn so a fast
   // bridge `session_register` cannot lose the intent. See change:
-  // add-folder-task-checker-and-spawn-attach.
+  // add-folder-task-checker-and-spawn-attach. NOTE: at this point we don't
+  // yet have a spawnToken (spawn hasn't run); we enqueue by cwd-FIFO and
+  // re-record by token after spawnPiSession returns. See change:
+  // spawn-correlation-token.
   if (typeof msg.attachProposal === "string" && msg.attachProposal.length > 0) {
     pendingAttachRegistry?.enqueue(msg.cwd, msg.attachProposal);
   }
 
+  // ── Preflight: fast synchronous checks before spawning. See change: spawn-failure-diagnostics.
+  const preflightResolver = new ToolResolver({ processExecPath: process.execPath, useLoginShell: false });
+  const preflight = preflightSpawn(msg.cwd, { resolver: preflightResolver });
+  if (!preflight.ok) {
+    const message = preflight.reasons.map((r) => r.message).join("; ");
+    sendTo(ws, { type: "spawn_result", cwd: msg.cwd, success: false, message, requestId: msg.requestId });
+    sendTo(ws, { type: "spawn_error", cwd: msg.cwd, strategy, message, code: "PREFLIGHT_FAILED", reasons: preflight.reasons });
+    appendSpawnFailure({
+      ts: new Date().toISOString(),
+      cwd: msg.cwd,
+      strategy,
+      code: "PREFLIGHT_FAILED",
+      message,
+      reasons: preflight.reasons,
+    });
+    return;
+  }
+
   // Catch both thrown exceptions and { success: false } results; surface as
   // spawn_error so the UI can render a retryable banner instead of failing
   // silently. Previous behaviour left the user staring at an empty state
@@ -320,20 +412,69 @@ export async function handleSpawnSession(
   try {
     const spawnResult = await spawnPiSession(msg.cwd, { strategy });
     if (spawnResult.process && spawnResult.pid) {
-      headlessPidRegistry.register(spawnResult.pid, msg.cwd, spawnResult.process);
+      headlessPidRegistry.register(spawnResult.pid, msg.cwd, spawnResult.process, spawnResult.spawnToken);
+    }
+    // Record client-correlation so the eventual session_added carries
+    // spawnRequestId. See change: spawn-correlation-token.
+    if (msg.requestId && spawnResult.spawnToken && pendingClientCorrelations) {
+      pendingClientCorrelations.record(spawnResult.spawnToken, msg.requestId);
     }
     if (spawnResult.dashboardSpawned && spawnResult.success) {
       pendingDashboardSpawns?.set(msg.cwd, (pendingDashboardSpawns?.get(msg.cwd) ?? 0) + 1);
     }
-    sendTo(ws, { type: "spawn_result", cwd: msg.cwd, success: spawnResult.success, message: spawnResult.message });
+    sendTo(ws, {
+      type: "spawn_result",
+      cwd: msg.cwd,
+      success: spawnResult.success,
+      message: spawnResult.message,
+      requestId: msg.requestId,
+      ...(spawnResult.pid ? { pid: spawnResult.pid } : {}),
+    });
     if (!spawnResult.success) {
-      sendTo(ws, { type: "spawn_error", cwd: msg.cwd, strategy, message: spawnResult.message });
+      sendTo(ws, {
+        type: "spawn_error",
+        cwd: msg.cwd,
+        strategy,
+        message: spawnResult.message,
+        ...(spawnResult.code ? { code: spawnResult.code } : {}),
+        ...(spawnResult.stderr ? { stderr: spawnResult.stderr } : {}),
+      });
+      appendSpawnFailure({
+        ts: new Date().toISOString(),
+        cwd: msg.cwd,
+        strategy,
+        code: spawnResult.code ?? "SPAWN_ERRNO",
+        message: spawnResult.message,
+        ...(spawnResult.stderr ? { stderrTail: spawnResult.stderr } : {}),
+      });
+    } else {
+      // Arm watchdog for every successful spawn. See change: spawn-failure-diagnostics.
+      const watchdog = getSpawnRegisterWatchdog();
+      watchdog.arm({
+        pid: spawnResult.pid,
+        cwd: msg.cwd,
+        mechanism: strategy as import("@blackbelt-technology/pi-dashboard-shared/platform/spawn-mechanism.js").SpawnMechanism,
+        logPath: spawnResult.logPath,
+        // Read-on-arm: pass current config value so a Settings change takes effect
+        // on the next spawn without a server restart. See change: spawn-failure-diagnostics (fix W1).
+        timeoutMs: config.spawnRegisterTimeoutMs,
+        ws,
+        spawnToken: spawnResult.spawnToken,
+      });
     }
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     const stderr = err instanceof Error && "stderr" in err ? String((err as { stderr: unknown }).stderr).slice(-2048) : undefined;
-    sendTo(ws, { type: "spawn_result", cwd: msg.cwd, success: false, message });
-    sendTo(ws, { type: "spawn_error", cwd: msg.cwd, strategy, message, stderr });
+    sendTo(ws, { type: "spawn_result", cwd: msg.cwd, success: false, message, requestId: msg.requestId });
+    sendTo(ws, { type: "spawn_error", cwd: msg.cwd, strategy, message, code: "SPAWN_ERRNO", stderr });
+    appendSpawnFailure({
+      ts: new Date().toISOString(),
+      cwd: msg.cwd,
+      strategy,
+      code: "SPAWN_ERRNO",
+      message,
+      ...(stderr ? { stderrTail: stderr } : {}),
+    });
   }
 }
 

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

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