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

package/packages/server/src/pi-core-updater.ts

@@ -11,6 +11,8 @@ import path from "node:path";
 import os from "node:os";
 import { existsSync } from "node:fs";
 import type { PiCorePackage, PiCoreUpdateResult } from "@blackbelt-technology/pi-dashboard-shared/rest-api.js";
+import { getDefaultRegistry } from "@blackbelt-technology/pi-dashboard-shared/tool-registry/index.js";
+import { prependManagedNodeToPath } from "@blackbelt-technology/pi-dashboard-shared/platform/managed-node-path.js";
 import type { PackageManagerWrapper } from "./package-manager-wrapper.js";
 
 const UPDATE_TIMEOUT_MS = 5 * 60 * 1000; // 5 min per package
@@ -33,10 +35,44 @@ export interface PiCoreUpdaterOptions {
 	onAllComplete?: () => Promise<number>;
 }
 
-/** Default npm-update runner. */
-function defaultRunNpmUpdate(
+/**
+ * Test seams for `defaultRunNpmUpdate`. Production callers omit
+ * `_seams`; tests inject fakes to avoid real spawns.
+ *
+ * `_resolveNpm` defaults to `getDefaultRegistry().resolveExecutor("npm")`.
+ * `_spawn` defaults to `node:child_process` `spawn`.
+ * `_envBuilder` defaults to `prependManagedNodeToPath(process.env)`.
+ */
+export interface DefaultRunNpmUpdateSeams {
+	_resolveNpm?: () =>
+		| { ok: true; argv: string[] }
+		| { ok: false; reason: string };
+	_spawn?: typeof spawn;
+	_envBuilder?: () => NodeJS.ProcessEnv;
+}
+
+/**
+ * Default npm-update runner.
+ *
+ * After change `embed-managed-node-runtime`:
+ *   - Resolves the `npm` binary via `ToolRegistry.resolve("npm")` so
+ *     the managed-Node runtime (when installed) is preferred over the
+ *     system PATH — the user-visible regression class this change
+ *     exists to prevent (`npm update exited with code 1` on a fresh
+ *     Windows install with no system Node).
+ *   - Refuses to spawn a bare `"npm"` if the registry can't resolve
+ *     it. Surfaces a clear `npm` unresolved error per the spec
+ *     scenario "ToolRegistry resolution failure surfaces a clear
+ *     error".
+ *   - Prepends the managed Node directory to the spawned child's
+ *     `PATH` via `prependManagedNodeToPath`, so any nested `node` /
+ *     `npm` invocation inside the npm subprocess also resolves to the
+ *     managed runtime.
+ */
+export function defaultRunNpmUpdate(
 	pkg: PiCorePackage,
 	onOutput: (line: string) => void,
+	seams: DefaultRunNpmUpdateSeams = {},
 ): Promise<void> {
 	return new Promise((resolve, reject) => {
 		const args =
@@ -50,15 +86,35 @@ function defaultRunNpmUpdate(
 			return;
 		}
 
-		// On Windows, system npm is npm.cmd (batch wrapper) — spawn("npm")
-		// without the .cmd extension fails with ENOENT. shell:true routes
-		// the invocation through cmd.exe which resolves via PATHEXT.
-		// See change: route-kill-paths-through-platform (same class of bug).
-		const child = spawn("npm", args, {
+		// Resolve npm via ToolRegistry: managed runtime > override > PATH.
+		// On unresolved, refuse — do not fall back to bare spawn("npm").
+		const resolveNpm =
+			seams._resolveNpm ??
+			(() => {
+				const r = getDefaultRegistry().resolveExecutor("npm");
+				return r.ok && r.path
+					? { ok: true as const, argv: r.argv }
+					: { ok: false as const, reason: "no override, no managed runtime, no npm on PATH" };
+			});
+		const npmRes = resolveNpm();
+		if (!npmRes.ok) {
+			reject(new Error(
+				`npm could not be resolved (${npmRes.reason}). ` +
+				"Install Node.js or run `pi-dashboard repair` to restore the managed Node runtime.",
+			));
+			return;
+		}
+
+		// `argv` is ready-to-spawn: on Windows + an npm-cli.js resolution
+		// it is `[node.exe, npm-cli.js]` (bypasses the .cmd shim and the
+		// cmd.exe console flash); elsewhere it is `[npm]`.
+		const [cmd, ...argvPrefix] = npmRes.argv;
+		const spawnFn = seams._spawn ?? spawn;
+		const envFn = seams._envBuilder ?? (() => prependManagedNodeToPath(process.env));
+		const child = spawnFn(cmd, [...argvPrefix, ...args], {
 			cwd,
 			stdio: ["ignore", "pipe", "pipe"],
-			env: process.env,
-			shell: process.platform === "win32", // platform-branch-ok: shell:true required on Windows so PATHEXT resolves npm.cmd (spawn('npm') without .cmd ENOENTs)
+			env: envFn(),
 			windowsHide: true,
 		});
 

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

@@ -5,6 +5,7 @@ import { WebSocketServer, WebSocket } from "ws";
 import type { ExtensionToServerMessage, ServerToExtensionMessage } from "@blackbelt-technology/pi-dashboard-shared/protocol.js";
 import type { DashboardSession } from "@blackbelt-technology/pi-dashboard-shared/types.js";
 import type { SessionManager } from "./memory-session-manager.js";
+import { getSpawnRegisterWatchdog } from "./spawn-register-watchdog.js";
 
 export const HEARTBEAT_TIMEOUT = 180_000;
 export const WS_PING_INTERVAL = 60_000;
@@ -273,6 +274,11 @@ export function createPiGateway(
             }
 
             if (msg.type === "session_register") {
+              // Clear spawn-register watchdog BEFORE any throwing logic. See change: spawn-failure-diagnostics.
+              const watchdog = getSpawnRegisterWatchdog();
+              if (msg.pid !== undefined) watchdog.clearByPid(msg.pid);
+              watchdog.clearByCwd(msg.cwd);
+
               // If session ID changed (e.g., after /reload), clean up the old placeholder
               if (currentSessionId && currentSessionId !== msg.sessionId) {
                 const oldSession = sessionManager.get(currentSessionId);

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

@@ -15,13 +15,14 @@
  *
  * 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 { execSync, spawnSync, buildSafeArgv } from "@blackbelt-technology/pi-dashboard-shared/platform/exec.js";
 import {
   spawnDetached,
@@ -34,6 +35,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) ────────────────────────────────────
 
@@ -64,11 +66,29 @@ 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;
 }
 
-/** Build env with managed install bin + current node binary dir prepended to PATH. */
+/**
+ * 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): NodeJS.ProcessEnv {
-  return resolver.buildSpawnEnv(baseEnv);
+  return prependManagedNodeToPath(resolver.buildSpawnEnv(baseEnv));
 }
 
 /**
@@ -256,7 +276,7 @@ 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);
@@ -282,7 +302,7 @@ function spawnTmux(cwd: string, options?: SessionOptions): SpawnResult {
       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}` };
   }
 }
 
@@ -292,18 +312,18 @@ function spawnWslTmux(cwd: string, options?: SessionOptions): SpawnResult {
     execSync(cmd, { stdio: "ignore" });
     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)];
@@ -317,7 +337,7 @@ async function spawnWt(cwd: string, options?: SessionOptions): Promise<SpawnResu
   });
 
   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 {
@@ -334,7 +354,7 @@ async function spawnHeadless(cwd: string, options?: SessionOptions): Promise<Spa
   const env = buildSpawnEnv();
   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 +376,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 +417,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 +486,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 +496,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 +518,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,41 @@
+/**
+ * In-memory cache of provider catalogues pushed by bridges.
+ *
+ * Each pi process pushes a `providers_list` over WS, derived from its
+ * `ModelRegistry`. The server caches per-session and tracks the most-recent
+ * snapshot. `GET /api/provider-auth/status` reads `getLatestCatalogue()`.
+ *
+ * See change: replace-hardcoded-provider-lists.
+ */
+import type { ProviderInfo } from "@blackbelt-technology/pi-dashboard-shared/types.js";
+
+const bySession = new Map<string, ProviderInfo[]>();
+let latest: ProviderInfo[] | null = null;
+
+export function setCatalogueForSession(sessionId: string, providers: ProviderInfo[]): void {
+  bySession.set(sessionId, providers);
+  latest = providers;
+}
+
+export function getCatalogueForSession(sessionId: string): ProviderInfo[] | undefined {
+  return bySession.get(sessionId);
+}
+
+/**
+ * Most recent catalogue across any session. Returns [] when no bridge
+ * has pushed yet — callers should treat that as "waiting for pi".
+ */
+export function getLatestCatalogue(): ProviderInfo[] {
+  return latest ?? [];
+}
+
+export function clearForSession(sessionId: string): void {
+  bySession.delete(sessionId);
+  if (bySession.size === 0) latest = null;
+}
+
+/** Test-only: reset all cached state. */
+export function _resetForTests(): void {
+  bySession.clear();
+  latest = null;
+}