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

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

@@ -4,7 +4,11 @@
 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,
@@ -313,6 +317,24 @@ export async function handleSpawnSession(
     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 });
+    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
@@ -327,13 +349,49 @@ export async function handleSpawnSession(
     }
     sendTo(ws, { type: "spawn_result", cwd: msg.cwd, success: spawnResult.success, message: spawnResult.message });
     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,
+      });
     }
   } 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_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);

package/packages/server/src/cli.ts

@@ -53,6 +53,8 @@ import {
 import type { DashboardServer } from "./server.js";
 import { updateBootstrapCompatibility } from "./pi-version-skew.js";
 import type { BootstrapStateStore } from "./bootstrap-state.js";
+import { parseDashboardStarter } from "@blackbelt-technology/pi-dashboard-shared/dashboard-starter.js";
+import { bootstrapInstallFromList } from "./bootstrap-install-from-list.js";
 
 /**
  * Emit a stderr warning at CLI startup when the resolved pi version is
@@ -145,6 +147,7 @@ export function buildConfig(flags: Partial<ServerConfig>): ServerConfig {
     maxWsBufferBytes: fileConfig.memoryLimits.maxWsBufferBytes,
     editor: fileConfig.editor,
     openspec: fileConfig.openspec,
+    reattachPlacement: fileConfig.reattachPlacement,
     resolvedTrustedNetworks: fileConfig.resolvedTrustedNetworks,
     corsAllowedOrigins: fileConfig.cors.allowedOrigins,
   };
@@ -165,6 +168,12 @@ async function runForeground(config: ServerConfig): Promise<void> {
   assertNodeVersionSupported();
   const server = await createServer(config);
 
+  // Stamp the bootstrap state with who started this server process.
+  // parseDashboardStarter defaults to "Standalone" when DASHBOARD_STARTER is unset.
+  const starter = parseDashboardStarter(process.env);
+  server.bootstrapState.set({ starter });
+  console.log(`[bootstrap] starter=${starter}`);
+
   let shuttingDown = false;
   const shutdown = async () => {
     if (shuttingDown) {
@@ -180,6 +189,19 @@ async function runForeground(config: ServerConfig): Promise<void> {
   process.on("SIGINT", shutdown);
   process.on("SIGTERM", shutdown);
 
+  // Reconcile installable.json before binding the port.
+  // Required-package failures throw and prevent server start.
+  // Optional failures are logged and continue.
+  // File-absent is a no-op (Bridge/Standalone starters don't seed installable.json).
+  // See change: simplify-electron-bootstrap-derived-state.
+  try {
+    await bootstrapInstallFromList(server.bootstrapState);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`[bootstrap] installable reconcile failed (required package): ${message}`);
+    process.exit(1);
+  }
+
   await server.start();
 
   // Kick off the degraded-mode first-run bootstrap if pi is unresolvable.

package/packages/server/src/directory-service.ts

@@ -45,6 +45,37 @@ export interface DirectoryAddedResult {
   openspecData: OpenSpecData;
 }
 
+/**
+ * `true` if `OpenSpecData` represents "no useful data yet" — either
+ * absent, or `{ initialized: false, changes: [] }` (cold cache).
+ * Used by broadcast call-sites to decide whether a transition from
+ * empty→populated warrants firing `openspec_update`. Pulled into
+ * shared scope so `server.ts` (post-install repair) and
+ * `session-bootstrap.ts` (initial poll) both use the same predicate.
+ *
+ * See change: fix-cold-boot-openspec-protocol.
+ */
+export function isOpenSpecDataEmpty(d: OpenSpecData | undefined): boolean {
+  if (!d) return true;
+  return !d.initialized && (!d.changes || d.changes.length === 0);
+}
+
+/**
+ * Synchronous, spawn-free probe for `<cwd>/openspec/changes`. Returns
+ * `true` iff the path exists and is a directory. Used by the WS
+ * on-connect snapshot to disambiguate "no openspec here" from
+ * "openspec here, polling pending". ~10 μs per call.
+ *
+ * See change: fix-cold-boot-openspec-protocol.
+ */
+export function hasOpenSpecDir(cwd: string): boolean {
+  try {
+    return fs.statSync(path.join(cwd, "openspec", "changes")).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
 export interface DirectoryService {
   knownDirectories(): string[];
   discoverSessions(cwd: string): DiscoveredSession[];

package/packages/server/src/event-wiring.ts

@@ -11,11 +11,12 @@ import type { PendingForkRegistry } from "./pending-fork-registry.js";
 import type { DirectoryService } from "./directory-service.js";
 import { extractSessionUpdates, isActivityEvent, isUnreadTrigger } from "./event-status-extraction.js";
 import type { ViewedSessionTracker } from "./viewed-session-tracker.js";
+import { setCatalogueForSession } from "./provider-catalogue-cache.js";
 import { spawnPiSession } from "./process-manager.js";
 import { loadConfig } from "@blackbelt-technology/pi-dashboard-shared/config.js";
 import { writeSessionMeta } from "@blackbelt-technology/pi-dashboard-shared/session-meta.js";
 import type { DashboardSession } from "@blackbelt-technology/pi-dashboard-shared/types.js";
-import { detectOpenSpecActivity } from "@blackbelt-technology/pi-dashboard-shared/openspec-activity-detector.js";
+import { detectOpenSpecActivity, isValidOpenSpecChangeSlug } from "@blackbelt-technology/pi-dashboard-shared/openspec-activity-detector.js";
 import { extractTurnStats } from "@blackbelt-technology/pi-dashboard-shared/stats-extractor.js";
 import { attachRenameTarget, isNameAutoSetFromAttachment } from "./proposal-attach-naming.js";
 
@@ -217,10 +218,19 @@ export function wireEvents(deps: EventWiringDeps): void {
       // Server-side OpenSpec activity detection from forwarded events
       // Skip during replay — replayed events from a forked session would set stale phase/change
       if (msg.event.eventType === "tool_execution_start" && !replayingSessions.has(sessionId)) {
-        const detected = detectOpenSpecActivity(
+        const detectedRaw = detectOpenSpecActivity(
           msg.event.data.toolName as string,
           msg.event.data.args as Record<string, unknown> | undefined,
         );
+        // Defense-in-depth (see change: fix-uuid-rename-bug). Even if a future
+        // detector regression returns a junk-shaped `changeName` (UUID, mixed
+        // case, etc.), refuse to stamp openspecChange / attachedProposal /
+        // name. Manual attach paths (browser handler, REST) bypass this and
+        // accept any name from a server-curated list.
+        const detected =
+          detectedRaw && (!detectedRaw.changeName || isValidOpenSpecChangeSlug(detectedRaw.changeName))
+            ? detectedRaw
+            : null;
         if (detected) {
           const session = sessionManager.get(sessionId);
           const activityUpdates: Partial<DashboardSession> = {};
@@ -582,6 +592,15 @@ export function wireEvents(deps: EventWiringDeps): void {
       browserGateway.broadcastSessionUpdated(sessionId, gitUpdates);
     }
 
+    if (msg.type === "jj_state_update") {
+      // jjState is intentionally allowed to be `undefined` (no jj) when
+      // the bridge sends `null`; the session-manager update applies the
+      // value verbatim. See change: add-jj-workspace-plugin.
+      const jjUpdates = { jjState: msg.jjState ?? undefined };
+      sessionManager.update(sessionId, jjUpdates);
+      browserGateway.broadcastSessionUpdated(sessionId, jjUpdates);
+    }
+
     if (msg.type === "files_list") {
       browserGateway.sendToSubscribers(sessionId, {
         type: "files_list",
@@ -601,6 +620,14 @@ export function wireEvents(deps: EventWiringDeps): void {
       } as any);
     }
 
+    if (msg.type === "providers_list") {
+      // Cache the bridge-pushed catalogue. Browsers don't subscribe to it
+      // directly; they read via GET /api/provider-auth/status.
+      // See change: replace-hardcoded-provider-lists.
+      setCatalogueForSession(sessionId, msg.providers);
+      browserGateway.broadcastToAll({ type: "models_refreshed" } as any);
+    }
+
     if (msg.type === "roles_list") {
       browserGateway.broadcastToAll({
         type: "roles_list",
@@ -669,6 +696,34 @@ export function wireEvents(deps: EventWiringDeps): void {
       } as any);
     }
 
+    // ── Asset register: per-session image asset cache + broadcast ──
+    // See change: chat-markdown-local-images-and-math.
+    if (msg.type === "asset_register") {
+      const { hash, mimeType, data } = msg;
+      // Reject malformed messages defensively. The bridge always populates
+      // these fields; this guard is purely defense-in-depth so a
+      // misbehaving extension cannot inject placeholder asset entries.
+      if (typeof hash === "string" && hash.length > 0 &&
+          typeof mimeType === "string" && mimeType.length > 0 &&
+          typeof data === "string" && data.length > 0) {
+        const session = sessionManager.get(sessionId);
+        if (session) {
+          const next = { ...(session.assets ?? {}) };
+          next[hash] = { data, mimeType };
+          sessionManager.update(sessionId, { assets: next });
+        }
+        // Broadcast verbatim regardless of whether the session is known —
+        // mirrors the Phase-1 / Phase-2 contract for extension UI messages.
+        browserGateway.sendToSubscribers(sessionId, {
+          type: "asset_register",
+          sessionId,
+          hash,
+          mimeType,
+          data,
+        } as any);
+      }
+    }
+
     // ── Extension UI System (Phase 2): live decorator cache + broadcast ──
     // See change: add-extension-ui-decorations.
     if (msg.type === "ext_ui_decorator") {

package/packages/server/src/home-lock.d.ts

@@ -0,0 +1,124 @@
+/** Metadata written alongside the lock file. JSON-serialized. */
+export interface LockMetadata {
+    pid: number;
+    ppid: number;
+    httpPort: number;
+    piPort: number;
+    startedAt: number;
+    /** Stable per-instance identifier. Verified against /api/health to detect
+     *  "port in use by unrelated dashboard or stale process with same pid." */
+    identity: string;
+    version: string;
+    url: string;
+    hostname: string;
+}
+/** Result of `acquireOrAttach`. Callers branch on `mode`. */
+export type LockAcquireResult = {
+    mode: "acquired";
+    meta: LockMetadata;
+    /** Release the lock + remove the metadata sidecar. Idempotent. */
+    release: () => Promise<void>;
+} | {
+    mode: "attach";
+    meta: LockMetadata;
+};
+/** Thrown when port is held by an unrelated process. Non-fatal to this
+ *  module; caller decides (exit with message / retry / override). */
+export declare class InstanceLockMismatchError extends Error {
+    readonly meta: LockMetadata;
+    readonly observedIdentity: string | null;
+    readonly code = "E_INSTANCE_MISMATCH";
+    constructor(meta: LockMetadata, observedIdentity: string | null);
+}
+export interface AcquireConfig {
+    httpPort: number;
+    piPort: number;
+    version: string;
+    identity?: string;
+    /** Injection hooks for tests. Production callers pass no options. */
+    hooks?: AcquireHooks;
+}
+export interface AcquireHooks {
+    now?: () => number;
+    hostname?: () => string;
+    lockPath?: string;
+    metaPath?: string;
+    probeHealth?: (port: number) => Promise<{
+        running: boolean;
+        pid?: number;
+        identity?: string;
+    } | null>;
+    isProcessAlive?: (pid: number) => boolean;
+    /** Stale threshold forwarded to `proper-lockfile`. Default 10s. */
+    staleMs?: number;
+}
+/**
+ * Canonical HOME directory.
+ *
+ * Uses `os.userInfo().homedir` in preference to `os.homedir()` because on
+ * POSIX the latter honors the `$HOME` environment variable (Node docs say:
+ * "On POSIX, it uses the `$HOME` environment variable if defined"), which
+ * the design (§4) explicitly prohibits — a GUI-launched process and a
+ * shell-launched process would otherwise disagree on "where HOME is".
+ * `userInfo().homedir` consults `getpwuid(3)` on POSIX, immune to `$HOME`.
+ *
+ * On Windows, both APIs ultimately use `USERPROFILE`, so the Git Bash
+ * drift case (`$HOME=/c/Users/R` vs `USERPROFILE=C:\Users\R`) is handled
+ * either way; keeping `userInfo().homedir` first is still correct.
+ *
+ * Result is then passed through `fs.realpathSync` to collapse symlinks,
+ * FileVault migrations, and other canonicalization drift. Tolerant: falls
+ * back to the raw path if realpath fails.
+ */
+export declare function canonicalHomedir(): string;
+/**
+ * Lock file path. This is what `proper-lockfile` locks.
+ */
+export declare function getLockPath(homedir?: string): string;
+/**
+ * Metadata sidecar path (`<lockPath>.meta.json`).
+ */
+export declare function getMetaPath(lockPath?: string): string;
+/**
+ * Atomically write the metadata sidecar via tmp + rename.
+ * Never leaves a partial file visible.
+ */
+export declare function writeMetadataAtomic(meta: LockMetadata, metaPath?: string): void;
+/**
+ * Read the metadata sidecar. Returns null on any failure (missing, corrupt,
+ * permission-denied). Callers MUST treat null as "assume stale."
+ */
+export declare function readMetadata(metaPath?: string): LockMetadata | null;
+/**
+ * Remove the metadata sidecar. Silent on any error (missing is fine).
+ */
+export declare function removeMetadata(metaPath?: string): void;
+/**
+ * Determine if the recorded lock holder is a responsive, identity-matching
+ * dashboard. Returns:
+ *   - `"alive-match"`: attach to it
+ *   - `"alive-mismatch"`: someone else is on that port
+ *   - `"dead"`: treat as stale, proceed to acquire
+ */
+export declare function isLockHolderResponsive(meta: LockMetadata, hooks?: Pick<AcquireHooks, "probeHealth" | "isProcessAlive">): Promise<"alive-match" | "alive-mismatch" | "dead">;
+/**
+ * Acquire the per-HOME lock, or fall back to attach semantics if a live
+ * dashboard already holds it.
+ *
+ * Flow:
+ *   1. Ensure `~/.pi/dashboard/` exists (proper-lockfile requires parent).
+ *   2. `proper-lockfile.lock(path, { stale, retries: 0 })`
+ *      ↪ on success: write metadata, return { mode: "acquired", release }
+ *      ↪ on ELOCKED: read metadata, check liveness
+ *         - dead: steal via `proper-lockfile.lock({ realpath:false, stale: 0 })`
+ *                 (Note: proper-lockfile already does stale-stealing when
+ *                 `stale` is configured — we just retry once.)
+ *         - alive-match: return { mode: "attach", meta }
+ *         - alive-mismatch: throw InstanceLockMismatchError
+ */
+export declare function acquireOrAttach(config: AcquireConfig): Promise<LockAcquireResult>;
+/**
+ * True when the user has opted out of the per-HOME lock. Caller should
+ * log a warning and skip acquireOrAttach when set.
+ */
+export declare function isLockDisabled(env?: NodeJS.ProcessEnv): boolean;