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

package/packages/server/src/process-manager.ts

@@ -15,13 +15,15 @@
  *
  * See change: consolidate-windows-spawn-and-platform-handlers.
  */
-import { existsSync, mkdirSync, openSync, closeSync } from "node:fs";
+import { existsSync, mkdirSync, openSync, closeSync, readFileSync } from "node:fs";
 import path from "node:path";
 import os from "node:os";
 import type { ChildProcess } from "@blackbelt-technology/pi-dashboard-shared/platform/exec.js";
 import type { SpawnStrategy } from "@blackbelt-technology/pi-dashboard-shared/config.js";
 import { MANAGED_BIN } from "@blackbelt-technology/pi-dashboard-shared/managed-paths.js";
 import { ToolResolver } from "@blackbelt-technology/pi-dashboard-shared/platform/binary-lookup.js";
+import { prependManagedNodeToPath } from "@blackbelt-technology/pi-dashboard-shared/platform/managed-node-path.js";
+import { mintSpawnToken } from "./spawn-token.js";
 import { execSync, spawnSync, buildSafeArgv } from "@blackbelt-technology/pi-dashboard-shared/platform/exec.js";
 import {
   spawnDetached,
@@ -34,6 +36,7 @@ import {
   type SpawnMechanism,
   type UserSpawnStrategy,
 } from "@blackbelt-technology/pi-dashboard-shared/platform/spawn-mechanism.js";
+import type { SpawnFailureCode } from "@blackbelt-technology/pi-dashboard-shared/browser-protocol.js";
 
 // ── Resolver seam (injectable for tests) ────────────────────────────────────
 
@@ -55,6 +58,15 @@ export interface SessionOptions {
   sessionFile?: string;
   mode?: "continue" | "fork";
   strategy?: SpawnStrategy;
+  /**
+   * Server-minted spawn correlation token. When provided, injected into
+   * the spawned process env as `PI_DASHBOARD_SPAWN_TOKEN`. The bridge
+   * echoes it back in the first `session_register` so the server can
+   * resolve identity precisely (linkByToken). When omitted, callers
+   * fall through to pid-link or cwd-FIFO matching.
+   * See change: spawn-correlation-token.
+   */
+  spawnToken?: string;
 }
 
 export interface SpawnResult {
@@ -64,11 +76,46 @@ export interface SpawnResult {
   process?: ChildProcess;
   /** True when spawned from the dashboard (for writing session meta) */
   dashboardSpawned?: boolean;
+  /** Structured failure classifier. Set on every { success: false } path. See change: spawn-failure-diagnostics. */
+  code?: SpawnFailureCode;
+  /** Tail of pi's stderr log (Windows headless PI_CRASHED only). See change: spawn-failure-diagnostics. */
+  stderr?: string;
+  /** Path to the per-session stderr log (Windows headless). Forwarded to watchdog. See change: spawn-failure-diagnostics. */
+  logPath?: string;
+  /**
+   * Token minted by `spawnPiSession` and injected into the spawned process's
+   * env as `PI_DASHBOARD_SPAWN_TOKEN`. Returned so callers can register it
+   * with the headless-pid registry, watchdog, and pending-* registries.
+   * See change: spawn-correlation-token.
+   */
+  spawnToken?: string;
 }
 
-/** Build env with managed install bin + current node binary dir prepended to PATH. */
-export function buildSpawnEnv(baseEnv: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
-  return resolver.buildSpawnEnv(baseEnv);
+/**
+ * Build env for pi-session spawns.
+ *
+ * Order of PATH prepends (highest priority first):
+ *   1. Managed Node runtime (`<managedDir>/node/{bin,}`) when installed.
+ *      See change: embed-managed-node-runtime.
+ *   2. Managed bin (`<managedDir>/node_modules/.bin`).
+ *   3. Current Node binary dir, extra bin dirs, common user bin dirs.
+ *
+ * The managed-Node prepend happens AFTER the resolver's prepends so it
+ * lands at the very head of `PATH` — spawned children invoking plain
+ * `node` / `npm` resolve to the managed runtime first.
+ */
+export function buildSpawnEnv(
+  baseEnv: NodeJS.ProcessEnv = process.env,
+  opts?: { spawnToken?: string },
+): NodeJS.ProcessEnv {
+  const env = prependManagedNodeToPath(resolver.buildSpawnEnv(baseEnv));
+  if (opts?.spawnToken) {
+    // Inject the correlation token so the bridge inside the spawned pi
+    // process can read it and echo back in `session_register`.
+    // See change: spawn-correlation-token.
+    return { ...env, PI_DASHBOARD_SPAWN_TOKEN: opts.spawnToken };
+  }
+  return env;
 }
 
 /**
@@ -256,17 +303,28 @@ export async function spawnPiSession(
   options?: SessionOptions & { electronMode?: boolean },
 ): Promise<SpawnResult> {
   if (!existsSync(cwd)) {
-    return { success: false, message: `Directory does not exist: ${cwd}` };
+    return { success: false, code: "DIR_MISSING", message: `Directory does not exist: ${cwd}` };
   }
 
-  const mechanism = chooseMechanism(options, options?.electronMode ?? false);
+  // Mint a spawn token if the caller didn't provide one. Token is injected
+  // into the spawned process's env (via buildSpawnEnv) and surfaced on
+  // SpawnResult so callers can register it with the registries.
+  // See change: spawn-correlation-token.
+  const spawnToken = options?.spawnToken ?? mintSpawnToken();
+  const opts: SessionOptions & { electronMode?: boolean } = { ...(options ?? {}), spawnToken };
+
+  const mechanism = chooseMechanism(opts, opts?.electronMode ?? false);
 
+  let result: SpawnResult;
   switch (mechanism) {
-    case "tmux":     return spawnTmux(cwd, options);
-    case "wt":       return spawnWt(cwd, options);
-    case "wsl-tmux": return spawnWslTmux(cwd, options);
-    case "headless": return spawnHeadless(cwd, options);
+    case "tmux":     result = spawnTmux(cwd, opts); break;
+    case "wt":       result = await spawnWt(cwd, opts); break;
+    case "wsl-tmux": result = spawnWslTmux(cwd, opts); break;
+    case "headless": result = await spawnHeadless(cwd, opts); break;
   }
+  // Surface the token on every result (success or failure) so callers
+  // can clean up registries deterministically.
+  return { ...result, spawnToken };
 }
 
 // ── Per-mechanism spawn ────────────────────────────────────────────────────
@@ -274,36 +332,41 @@ export async function spawnPiSession(
 function spawnTmux(cwd: string, options?: SessionOptions): SpawnResult {
   const exists = dashboardSessionExists();
   const cmd = buildTmuxCommand(cwd, exists, options);
+  // Pass env explicitly so PI_DASHBOARD_SPAWN_TOKEN reaches the tmux pane's
+  // pi process (tmux inherits the caller's env into new windows/sessions).
+  // See change: spawn-correlation-token.
+  const env = buildSpawnEnv(process.env, { spawnToken: options?.spawnToken });
   try {
-    execSync(cmd, { stdio: "ignore" });
+    execSync(cmd, { stdio: "ignore", env });
     return {
       success: true,
       dashboardSpawned: true,
       message: `Pi session spawned in tmux (${exists ? "new window" : "new session"})`,
     };
   } catch (err: any) {
-    return { success: false, message: `Failed to spawn session: ${err.message}` };
+    return { success: false, code: "TMUX_MISSING", message: `Failed to spawn session: ${err.message}` };
   }
 }
 
 function spawnWslTmux(cwd: string, options?: SessionOptions): SpawnResult {
   try {
     const cmd = `wsl ${buildTmuxCommand(cwd, false, options)}`;
-    execSync(cmd, { stdio: "ignore" });
+    const env = buildSpawnEnv(process.env, { spawnToken: options?.spawnToken });
+    execSync(cmd, { stdio: "ignore", env });
     return { success: true, dashboardSpawned: true, message: "Pi session spawned via WSL tmux" };
   } catch (err: any) {
-    return { success: false, message: `Failed to spawn via WSL tmux: ${err.message}` };
+    return { success: false, code: "TMUX_MISSING", message: `Failed to spawn via WSL tmux (wsl-tmux mechanism): ${err.message}` };
   }
 }
 
 async function spawnWt(cwd: string, options?: SessionOptions): Promise<SpawnResult> {
   const wt = resolver.which("wt");
   if (!wt) {
-    return { success: false, message: "Windows Terminal (wt.exe) not found" };
+    return { success: false, code: "WT_MISSING", message: "Windows Terminal (wt.exe) not found" };
   }
   const piCmd = resolvePiCommand();
   if (!piCmd) {
-    return { success: false, message: `pi binary not found. Checked: ${MANAGED_BIN} and system PATH.` };
+    return { success: false, code: "PI_NOT_FOUND", message: `pi binary not found. Checked: ${MANAGED_BIN} and system PATH.` };
   }
 
   const piArgv = [...piCmd, ...buildInteractivePiArgs(options)];
@@ -313,11 +376,11 @@ async function spawnWt(cwd: string, options?: SessionOptions): Promise<SpawnResu
     cmd: wt,
     args,
     cwd,
-    env: buildSpawnEnv(),
+    env: buildSpawnEnv(process.env, { spawnToken: options?.spawnToken }),
   });
 
   if (!r.ok) {
-    return { success: false, message: `Failed to launch Windows Terminal: ${r.error}` };
+    return { success: false, code: "SPAWN_ERRNO", message: `Failed to launch Windows Terminal: ${r.error}` };
   }
 
   return {
@@ -331,10 +394,10 @@ async function spawnWt(cwd: string, options?: SessionOptions): Promise<SpawnResu
 
 async function spawnHeadless(cwd: string, options?: SessionOptions): Promise<SpawnResult> {
   const args = buildHeadlessArgs(options);
-  const env = buildSpawnEnv();
+  const env = buildSpawnEnv(process.env, { spawnToken: options?.spawnToken });
   const piCmd = resolvePiCommand();
   if (!piCmd) {
-    return { success: false, message: `pi binary not found. Checked: ${MANAGED_BIN} and system PATH.` };
+    return { success: false, code: "PI_NOT_FOUND", message: `pi binary not found. Checked: ${MANAGED_BIN} and system PATH.` };
   }
   const [bin, ...prefixArgs] = piCmd;
 
@@ -356,7 +419,7 @@ async function spawnHeadless(cwd: string, options?: SessionOptions): Promise<Spa
     env,
   });
   if (!r.ok) {
-    return { success: false, message: `Failed to spawn headless (Unix): ${r.error}` };
+    return { success: false, code: "SPAWN_ERRNO", message: `Failed to spawn headless (Unix): ${r.error}` };
   }
   return {
     success: true,
@@ -397,6 +460,7 @@ async function spawnHeadlessDetached(
   if (bin.toLowerCase().endsWith(".cmd") || bin.toLowerCase().endsWith(".bat")) {
     return {
       success: false,
+      code: "WIN_PI_CMD_ONLY",
       message:
         "Windows pi spawn requires node.exe + cli.js (managed install). " +
         "Found only pi.cmd on PATH. Run the dashboard setup wizard or " +
@@ -465,6 +529,8 @@ async function spawnHeadlessDetached(
   if (!r.ok || !r.process || !r.pid) {
     return {
       success: false,
+      code: "SPAWN_ERRNO",
+      logPath: logFd !== undefined ? logPath : undefined,
       message: `Failed to spawn pi: ${r.error ?? "unknown error"}. Command: ${cmdForLog}`,
     };
   }
@@ -473,8 +539,16 @@ async function spawnHeadlessDetached(
   // but still catch immediate crashes (missing modules, config errors).
   const gate = await waitForNoCrash({ child: r.process, windowMs: 300 });
   if (!gate.ok) {
+    // Read last 4 KB of stderr log for diagnostic forwarding. See change: spawn-failure-diagnostics.
+    let stderrTail: string | undefined;
+    if (logFd !== undefined) {
+      stderrTail = readLogTail(logPath);
+    }
     return {
       success: false,
+      code: "PI_CRASHED",
+      logPath: logFd !== undefined ? logPath : undefined,
+      stderr: stderrTail,
       message:
         `Pi process exited immediately (code ${gate.exitCode}). ` +
         `See ${logPath} for details.\nCommand: ${cmdForLog}`,
@@ -487,5 +561,25 @@ async function spawnHeadlessDetached(
     message: `Pi session spawned headless (pid ${r.pid})`,
     pid: r.pid,
     process: r.process,
+    logPath: logFd !== undefined ? logPath : undefined,
   };
 }
+
+/**
+ * Read last `maxBytes` bytes of `filePath`, stripping leading UTF-8 continuation bytes.
+ * Returns `undefined` on any error or if file is empty.
+ * See change: spawn-failure-diagnostics.
+ */
+function readLogTail(filePath: string, maxBytes = 4096): string | undefined {
+  try {
+    const buf = readFileSync(filePath);
+    if (!buf.length) return undefined;
+    const slice = buf.length <= maxBytes ? buf : buf.slice(buf.length - maxBytes);
+    // Strip leading UTF-8 continuation bytes (0x80..0xBF)
+    let start = 0;
+    while (start < slice.length && (slice[start]! & 0xC0) === 0x80) start++;
+    return slice.slice(start).toString("utf-8");
+  } catch {
+    return undefined;
+  }
+}

package/packages/server/src/provider-auth-handlers.ts

@@ -29,6 +29,8 @@ export function generateState(): string {
 export interface AuthCodeHandler {
   flowType: "auth_code";
   providerId: string;
+  /** Human-readable name surfaced to the UI. */
+  displayName: string;
   /** Port registered with the OAuth provider for the redirect URI */
   callbackPort: number;
   /** Path registered with the OAuth provider for the redirect URI */
@@ -40,6 +42,8 @@ export interface AuthCodeHandler {
 export interface DeviceCodeHandler {
   flowType: "device_code";
   providerId: string;
+  /** Human-readable name surfaced to the UI. */
+  displayName: string;
   requestDeviceCode(enterpriseDomain?: string): Promise<DeviceCodeData>;
   pollForToken(deviceCode: string, interval: number, expiresIn: number, extra?: Record<string, unknown>): Promise<OAuthCredential>;
 }
@@ -93,6 +97,7 @@ const ANTHROPIC_SCOPES = "org:create_api_key user:profile user:inference user:se
 export const anthropicHandler: AuthCodeHandler = {
   flowType: "auth_code",
   providerId: "anthropic",
+  displayName: "Anthropic (Claude Pro/Max)",
   callbackPort: 53692,
   callbackPath: "/callback",
 
@@ -146,6 +151,7 @@ const CODEX_SCOPE = "openid profile email offline_access";
 export const codexHandler: AuthCodeHandler = {
   flowType: "auth_code",
   providerId: "openai-codex",
+  displayName: "ChatGPT Plus/Pro (Codex)",
   callbackPort: 1455,
   callbackPath: "/auth/callback",
 
@@ -206,6 +212,7 @@ function githubUrls(domain: string) {
 export const githubCopilotHandler: DeviceCodeHandler = {
   flowType: "device_code",
   providerId: "github-copilot",
+  displayName: "GitHub Copilot",
 
   async requestDeviceCode(enterpriseDomain) {
     const domain = enterpriseDomain || "github.com";
@@ -336,6 +343,7 @@ const GEMINI_SCOPES = [
 export const geminiCliHandler: AuthCodeHandler = {
   flowType: "auth_code",
   providerId: "google-gemini-cli",
+  displayName: "Google Gemini CLI",
   callbackPort: 8085,
   callbackPath: "/oauth2callback",
 
@@ -384,6 +392,7 @@ const AG_SCOPES = [
 export const antigravityHandler: AuthCodeHandler = {
   flowType: "auth_code",
   providerId: "google-antigravity",
+  displayName: "Antigravity",
   callbackPort: 51121,
   callbackPath: "/oauth-callback",
 

package/packages/server/src/provider-auth-storage.ts

@@ -1,11 +1,19 @@
 /**
  * Read/write ~/.pi/agent/auth.json for pi provider credentials.
  * Uses lockfile + atomic write to avoid race conditions with running pi sessions.
+ *
+ * The OAuth provider list derives from the local handler registry
+ * (`getAllHandlers()` in provider-auth-handlers.ts). The API-key list
+ * derives from the bridge-pushed catalogue (provider-catalogue-cache.ts).
+ * See change: replace-hardcoded-provider-lists.
  */
 import fs from "node:fs";
 import path from "node:path";
 import os from "node:os";
 import type { ProviderAuthStatus } from "@blackbelt-technology/pi-dashboard-shared/rest-api.js";
+import type { ProviderInfo } from "@blackbelt-technology/pi-dashboard-shared/types.js";
+import { getAllHandlers, type ProviderHandler } from "./provider-auth-handlers.js";
+import { getLatestCatalogue } from "./provider-catalogue-cache.js";
 
 // ── Constants ────────────────────────────────────────────────────────────────
 
@@ -21,33 +29,12 @@ export type OAuthCredential = { type: "oauth"; refresh: string; access: string;
 export type AuthCredential = ApiKeyCredential | OAuthCredential;
 export type AuthData = Record<string, AuthCredential>;
 
-// ── OAuth provider metadata (for status display) ────────────────────────────
-
 interface OAuthProviderMeta {
   id: string;
   name: string;
   flowType: "auth_code" | "device_code";
 }
 
-const OAUTH_PROVIDERS: OAuthProviderMeta[] = [
-  { id: "anthropic", name: "Anthropic (Claude Pro/Max)", flowType: "auth_code" },
-  { id: "openai-codex", name: "ChatGPT Plus/Pro (Codex)", flowType: "auth_code" },
-  { id: "github-copilot", name: "GitHub Copilot", flowType: "device_code" },
-  { id: "google-gemini-cli", name: "Google Gemini CLI", flowType: "auth_code" },
-  { id: "google-antigravity", name: "Antigravity", flowType: "auth_code" },
-];
-
-const API_KEY_PROVIDERS = [
-  { id: "anthropic-api", authJsonKey: "anthropic", name: "Anthropic (API Key)" },
-  { id: "openai", authJsonKey: "openai", name: "OpenAI" },
-  { id: "google", authJsonKey: "google", name: "Google Gemini (API Key)" },
-  { id: "mistral", authJsonKey: "mistral", name: "Mistral" },
-  { id: "groq", authJsonKey: "groq", name: "Groq" },
-  { id: "xai", authJsonKey: "xai", name: "xAI" },
-  { id: "openrouter", authJsonKey: "openrouter", name: "OpenRouter" },
-  { id: "zai", authJsonKey: "zai", name: "Z.ai" },
-];
-
 // ── Lock helpers ─────────────────────────────────────────────────────────────
 
 function acquireLock(): void {
@@ -114,7 +101,7 @@ function writeAuthJson(data: AuthData): void {
   fs.renameSync(tmp, AUTH_PATH);
 }
 
-// ── Public API ───────────────────────────────────────────────────────────────
+// ── Public API: write/remove ─────────────────────────────────────────────────
 
 export function writeCredential(provider: string, credential: AuthCredential): void {
   acquireLock();
@@ -138,63 +125,108 @@ export function removeCredential(provider: string): void {
   }
 }
 
-export function getAuthStatus(): ProviderAuthStatus[] {
-  const data = readAuthJson();
+// ── Pure status builder (testable) ───────────────────────────────────────────
+
+/**
+ * Pure derivation of `ProviderAuthStatus[]` from auth.json data, the
+ * bridge-pushed provider catalogue, and the local OAuth handler set.
+ * No I/O. See change: replace-hardcoded-provider-lists.
+ */
+export function _buildAuthStatus(
+  catalogue: ProviderInfo[],
+  authData: AuthData,
+  oauthHandlers: ProviderHandler[],
+): ProviderAuthStatus[] {
   const statuses: ProviderAuthStatus[] = [];
+  const oauthIds = new Set(oauthHandlers.map((h) => h.providerId));
 
-  // OAuth providers
-  for (const p of OAUTH_PROVIDERS) {
-    const cred = data[p.id];
+  // OAuth rows from local handler registry.
+  for (const h of oauthHandlers) {
+    const cred = authData[h.providerId];
     if (cred && cred.type === "oauth") {
       statuses.push({
-        id: p.id,
-        name: p.name,
-        flowType: p.flowType,
+        id: h.providerId,
+        name: h.displayName,
+        flowType: h.flowType,
         authenticated: true,
         expires: (cred as OAuthCredential).expires,
       });
     } else {
       statuses.push({
-        id: p.id,
-        name: p.name,
-        flowType: p.flowType,
+        id: h.providerId,
+        name: h.displayName,
+        flowType: h.flowType,
         authenticated: false,
       });
     }
   }
 
-  // API key providers (skip if the same key is already shown as OAuth)
-  for (const p of API_KEY_PROVIDERS) {
-    const cred = data[p.authJsonKey];
-    // If key is already listed as OAuth provider (e.g., "anthropic"), skip the API key variant
-    if (OAUTH_PROVIDERS.some((op) => op.id === p.authJsonKey) && cred?.type === "oauth") continue;
-    const hasKey = !!(cred && cred.type === "api_key" && (cred as ApiKeyCredential).key);
-    const entry: ProviderAuthStatus = {
-      id: p.id,
-      name: p.name,
+  // API-key rows from bridge-pushed catalogue.
+  // Skip custom providers (registered via pi.registerProvider() from
+  // ~/.pi/agent/providers.json) — those are managed by the dedicated
+  // LLM Providers settings section. OAuth rows for custom providers
+  // were already emitted above when the OAuth handler registry has
+  // a matching id.
+  for (const entry of catalogue) {
+    if (entry.custom) continue;
+    const hasOAuthCollision = oauthIds.has(entry.id);
+    const uiId = hasOAuthCollision ? `${entry.id}-api` : entry.id;
+    const displayName = hasOAuthCollision
+      ? `${entry.displayName} (API Key)`
+      : entry.displayName;
+    const authJsonKey = entry.id;
+    const cred = authData[authJsonKey];
+    const hasStoredKey = !!(cred && cred.type === "api_key" && (cred as ApiKeyCredential).key);
+
+    const row: ProviderAuthStatus = {
+      id: uiId,
+      name: displayName,
       flowType: "api_key",
-      authenticated: hasKey,
+      authenticated: hasStoredKey || !!entry.ambient,
     };
-    if (hasKey) {
+    if (hasStoredKey) {
       const key = (cred as ApiKeyCredential).key;
-      entry.maskedKey = key.length >= 12 ? `${key.slice(0, 5)}...${key.slice(-3)}` : "****";
+      row.maskedKey = key.length >= 12 ? `${key.slice(0, 5)}...${key.slice(-3)}` : "****";
+    } else if (entry.ambient) {
+      row.maskedKey = "(ambient)";
     }
-    statuses.push(entry);
+    if (entry.envVar) row.envVar = entry.envVar;
+    if (entry.ambient) row.ambient = true;
+    statuses.push(row);
   }
 
   return statuses;
 }
 
+// ── Public API: status / OAuth meta / id resolution ─────────────────────────
+
+export function getAuthStatus(): ProviderAuthStatus[] {
+  return _buildAuthStatus(getLatestCatalogue(), readAuthJson(), getAllHandlers());
+}
+
 export function getOAuthProvidersMeta(): OAuthProviderMeta[] {
-  return OAUTH_PROVIDERS;
+  return getAllHandlers().map((h) => ({
+    id: h.providerId,
+    name: h.displayName,
+    flowType: h.flowType,
+  }));
 }
 
 /**
  * Resolve a UI provider ID to the auth.json key.
- * API key providers have an `authJsonKey` mapping (e.g., "anthropic-api" → "anthropic").
- * OAuth providers and unknown IDs pass through unchanged.
+ *
+ * The catalogue encodes API-key rows with `<id>-api` suffix when an
+ * OAuth handler exists for the same id. This unwraps the suffix back
+ * to the underlying auth.json key. OAuth ids pass through unchanged
+ * (their UI id == their auth.json key). Unknown ids pass through too,
+ * matching the previous behavior.
  */
 export function resolveAuthJsonKey(providerId: string): string {
-  const apiKeyProvider = API_KEY_PROVIDERS.find(p => p.id === providerId);
-  return apiKeyProvider?.authJsonKey ?? providerId;
+  const oauthIds = new Set(getAllHandlers().map((h) => h.providerId));
+  // <id>-api suffix → strip suffix iff the bare id is an OAuth handler.
+  if (providerId.endsWith("-api")) {
+    const bare = providerId.slice(0, -"-api".length);
+    if (oauthIds.has(bare)) return bare;
+  }
+  return providerId;
 }

package/packages/server/src/provider-catalogue-cache.ts

@@ -0,0 +1,47 @@
+/**
+ * In-memory cache of the most-recently-pushed provider catalogue.
+ *
+ * Each pi process pushes a `providers_list` over WS, derived from its
+ * `ModelRegistry`. The server caches the latest snapshot. `GET
+ * /api/provider-auth/status` reads `getLatestCatalogue()`.
+ *
+ * The catalogue is a property of the machine's auth + provider config,
+ * not of individual sessions: every bridge in the same process tree
+ * derives an identical catalogue from `~/.pi/agent/auth.json` +
+ * `~/.pi/agent/providers.json` + pi-ai's MODELS table. We therefore
+ * keep ONE global snapshot — the last push wins. A previous version
+ * kept a per-session Map plus a `changed` deep-equality gate to avoid
+ * spurious `models_refreshed` broadcasts; that broadcast is gone
+ * (see change: simplify-model-selection-channels), so the gate is
+ * unnecessary and the per-session split was redundant.
+ *
+ * See changes: replace-hardcoded-provider-lists,
+ *              fix-providers-list-spurious-models-refreshed,
+ *              simplify-model-selection-channels.
+ */
+import type { ProviderInfo } from "@blackbelt-technology/pi-dashboard-shared/types.js";
+
+let latest: ProviderInfo[] | null = null;
+
+/**
+ * Replace the cached catalogue. Called from event-wiring.ts on every
+ * `providers_list` arrival. No-op semantically beyond the assignment;
+ * no signal to callers because no caller needs one.
+ */
+export function setCatalogueForSession(_sessionId: string, providers: ProviderInfo[]): void {
+  latest = providers;
+}
+
+/**
+ * Most recent catalogue across any session. Returns [] when no bridge
+ * has pushed yet — callers should treat that as "waiting for pi" and
+ * may issue a `request_providers` nudge to fetch one synchronously.
+ */
+export function getLatestCatalogue(): ProviderInfo[] {
+  return latest ?? [];
+}
+
+/** Test-only: reset all cached state. */
+export function _resetForTests(): void {
+  latest = null;
+}