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

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";
 
@@ -42,6 +43,14 @@ export interface EventWiringDeps {
    * See change: session-card-unread-stripes.
    */
   viewedSessionTracker?: ViewedSessionTracker;
+  /**
+   * Optional client-correlation registry. When provided, the wiring
+   * consumes the requestId for the resolved spawnToken after a successful
+   * three-tier link and surfaces it on `session_added` as `spawnRequestId`,
+   * letting the client auto-select / dismiss its placeholder by exact
+   * correlation. See change: spawn-correlation-token.
+   */
+  pendingClientCorrelations?: import("./pending-client-correlations.js").PendingClientCorrelations;
 }
 
 /**
@@ -61,6 +70,7 @@ export function wireEvents(deps: EventWiringDeps): void {
     pendingDashboardSpawns,
     pendingAttachRegistry,
     viewedSessionTracker,
+    pendingClientCorrelations,
   } = deps;
 
   // Broadcast placeholder session to browsers when auto-created from early events
@@ -217,10 +227,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> = {};
@@ -442,7 +461,34 @@ export function wireEvents(deps: EventWiringDeps): void {
         }
       }
 
-      browserGateway.headlessPidRegistry.linkSession(sessionId, msg.cwd);
+      // Three-tier link: token → pid → cwd-FIFO. Each tier is independently
+      // correct; `linkByToken` is the strong identity introduced by
+      // `spawn-correlation-token`. cwd-FIFO is the legacy fallback for old
+      // bridges that send neither token nor pid (and is logged so we can see
+      // when it actually triggers).
+      let linked = false;
+      if (msg.spawnToken) {
+        linked = browserGateway.headlessPidRegistry.linkByToken(msg.spawnToken, sessionId, msg.pid);
+      }
+      if (!linked && msg.pid !== undefined) {
+        linked = browserGateway.headlessPidRegistry.linkByPid(sessionId, msg.pid);
+      }
+      if (!linked) {
+        if (msg.spawnToken || msg.pid !== undefined) {
+          console.error(
+            `[event-wiring] cwd-FIFO fallback for session ${sessionId} — token=${msg.spawnToken ?? ""} pid=${msg.pid ?? ""} cwd=${msg.cwd}`,
+          );
+        }
+        browserGateway.headlessPidRegistry.linkSession(sessionId, msg.cwd);
+      }
+
+      // Resolve the originating browser `requestId` (when known) so the
+      // upcoming session_added broadcast can carry spawnRequestId and the
+      // client can auto-select / dismiss its placeholder.
+      // See change: spawn-correlation-token.
+      const spawnRequestId = (msg.spawnToken && pendingClientCorrelations)
+        ? pendingClientCorrelations.consume(msg.spawnToken)
+        : undefined;
 
       const isNewSession = !knownSessionIds.has(sessionId);
       knownSessionIds.add(sessionId);
@@ -459,7 +505,11 @@ export function wireEvents(deps: EventWiringDeps): void {
         }
       }
 
-      const forkParent = pendingForkRegistry.consumeFork(msg.cwd);
+      // Fork-parent lookup is keyed by spawn token (was: cwd, racy on
+      // multi-fork-in-same-cwd). See change: spawn-correlation-token.
+      const forkParent = msg.spawnToken
+        ? pendingForkRegistry.consumeFork(msg.spawnToken)
+        : undefined;
       sessionOrderManager.insert(msg.cwd, sessionId);
 
       if (forkParent) {
@@ -479,7 +529,7 @@ export function wireEvents(deps: EventWiringDeps): void {
 
       const updatedSession = sessionManager.get(sessionId);
       if (updatedSession) {
-        browserGateway.broadcastSessionAdded(updatedSession);
+        browserGateway.broadcastSessionAdded(updatedSession, spawnRequestId ? { spawnRequestId } : undefined);
       }
 
       const isNewCwd = !sessionManager.listAll().some(
@@ -610,6 +660,28 @@ 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.
+      // Broadcast `models_refreshed` ONLY when the catalogue contents
+      // actually changed. Routine state-syncs (every fork/resume/reconnect/
+      // subscribe) re-send identical content; broadcasting unconditionally
+      // wipes every browser's modelsMap and — because App.tsx's
+      // auto-subscribe effect skips re-requesting models for any session
+      // that's already in `subscribedRef`, leaves previously-visited
+      // sessions with an empty model selector until reconnect.
+      //
+      // The catalogue cache is now a pure read consumer for the Settings
+      // UI (`GET /api/provider-auth/status`). No broadcast: the model-
+      // selector dropdown lives on the independent `models_list` channel
+      // which is per-session-broadcast already; per-session updates are
+      // self-healing without a global wipe.
+      // See changes: replace-hardcoded-provider-lists,
+      //              fix-providers-list-spurious-models-refreshed,
+      //              simplify-model-selection-channels.
+      setCatalogueForSession(sessionId, msg.providers);
+    }
+
     if (msg.type === "roles_list") {
       browserGateway.broadcastToAll({
         type: "roles_list",
@@ -678,6 +750,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/headless-pid-registry.ts

@@ -23,6 +23,13 @@ export interface HeadlessEntry {
   process: ChildProcess;
   sessionId?: string;
   spawnedAt: number;
+  /**
+   * Server-minted spawn correlation token. Stored at `register` time.
+   * Used by `linkByToken` (tier 1) to resolve sessionId↔pid mapping
+   * deterministically, replacing the racy cwd-FIFO `linkSession`.
+   * See change: spawn-correlation-token.
+   */
+  spawnToken?: string;
 }
 
 /** Serialized format for disk persistence */
@@ -37,9 +44,31 @@ interface PidFileData {
 }
 
 export interface HeadlessPidRegistry {
-  /** Register a newly spawned headless process. */
-  register(pid: number, cwd: string, proc: ChildProcess): void;
-  /** Link a session ID to a tracked PID by matching cwd (FIFO). */
+  /**
+   * Register a newly spawned headless process. The optional `spawnToken`
+   * is the server-minted UUID injected into the spawned process's env;
+   * storing it lets `linkByToken` resolve identity precisely later.
+   * See change: spawn-correlation-token.
+   */
+  register(pid: number, cwd: string, proc: ChildProcess, spawnToken?: string): void;
+  /**
+   * Tier 1 link: find entry by `spawnToken`, set its `sessionId`. Returns
+   * `true` on match. The strongest identity — used when the bridge sent
+   * `session_register.spawnToken`. See change: spawn-correlation-token.
+   */
+  linkByToken(spawnToken: string, sessionId: string, pid?: number): boolean;
+  /**
+   * Tier 2 link: find entry by `pid` (where `!sessionId`), set its
+   * `sessionId`. Returns `true` on match. Used when the bridge sent
+   * `session_register.pid` but no token. See change: spawn-correlation-token.
+   */
+  linkByPid(sessionId: string, pid: number): boolean;
+  /**
+   * Tier 3 (legacy) link: find first entry by `cwd` where `!sessionId`,
+   * set its `sessionId`. Returns `true` on match. Cwd-FIFO fallback for
+   * old bridges that send neither token nor pid. Race-prone for
+   * concurrent same-cwd spawns; tiers 1–2 should pre-empt this.
+   */
   linkSession(sessionId: string, cwd: string): boolean;
   /** Get the PID linked to a session ID. */
   getPid(sessionId: string): number | undefined;
@@ -84,8 +113,8 @@ export function createHeadlessPidRegistry(options?: HeadlessPidRegistryOptions):
   }
 
   return {
-    register(pid: number, cwd: string, proc: ChildProcess) {
-      entries.set(pid, { pid, cwd, process: proc, spawnedAt: Date.now() });
+    register(pid: number, cwd: string, proc: ChildProcess, spawnToken?: string) {
+      entries.set(pid, { pid, cwd, process: proc, spawnedAt: Date.now(), spawnToken });
       proc.on("exit", () => {
         entries.delete(pid);
         persist();
@@ -93,6 +122,26 @@ export function createHeadlessPidRegistry(options?: HeadlessPidRegistryOptions):
       persist();
     },
 
+    linkByToken(spawnToken: string, sessionId: string, _pid?: number): boolean {
+      if (!spawnToken) return false;
+      for (const entry of entries.values()) {
+        if (entry.spawnToken === spawnToken && !entry.sessionId) {
+          entry.sessionId = sessionId;
+          return true;
+        }
+      }
+      return false;
+    },
+
+    linkByPid(sessionId: string, pid: number): boolean {
+      const entry = entries.get(pid);
+      if (entry && !entry.sessionId) {
+        entry.sessionId = sessionId;
+        return true;
+      }
+      return false;
+    },
+
     linkSession(sessionId: string, cwd: string): boolean {
       for (const entry of entries.values()) {
         if (entry.cwd === cwd && !entry.sessionId) {

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;