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

package/packages/server/src/__tests__/directory-service-openspec-enabled.test.ts

@@ -0,0 +1,187 @@
+/**
+ * Tests for `openspec.enabled` gating in DirectoryService.
+ *
+ * Confirms:
+ *   - `refreshOpenSpec` short-circuits (no CLI spawn, returns cleared shape).
+ *   - `pollDirectoryGated` short-circuits.
+ *   - `scheduleOpenSpecTick` short-circuits.
+ *   - `reconfigurePolling({ enabled: false })` clears every cached cwd and
+ *     broadcasts `openspec_update` via the onChange callback.
+ *
+ * See change: auto-hide-empty-session-subcards.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { createDirectoryService, type DirectoryService } from "../directory-service.js";
+import type { PreferencesStore } from "../preferences-store.js";
+import type { SessionManager } from "../memory-session-manager.js";
+import type { DashboardSession } from "@blackbelt-technology/pi-dashboard-shared/types.js";
+import { DEFAULT_OPENSPEC_POLL } from "@blackbelt-technology/pi-dashboard-shared/config.js";
+
+// Mock CLI entry points so we can spy on whether they get called.
+vi.mock("@blackbelt-technology/pi-dashboard-shared/openspec-poller.js", async (importOriginal) => {
+  const actual = await importOriginal<
+    typeof import("@blackbelt-technology/pi-dashboard-shared/openspec-poller.js")
+  >();
+  return {
+    ...actual,
+    pollOpenSpecAsync: vi.fn(async () => ({ initialized: true, changes: [] })),
+    runOpenSpecList: vi.fn(async () => null),
+    runOpenSpecStatus: vi.fn(async () => null),
+  };
+});
+
+vi.mock("../pi-resource-scanner.js", () => ({
+  scanPiResources: vi.fn(async () => ({
+    local: { extensions: [], skills: [], prompts: [] },
+    global: { extensions: [], skills: [], prompts: [] },
+    packages: [],
+  })),
+}));
+vi.mock("@blackbelt-technology/pi-dashboard-shared/state-replay.js", () => ({
+  replayEntriesAsEvents: vi.fn(() => []),
+}));
+vi.mock("../session-discovery.js", () => ({
+  discoverSessionsForCwd: vi.fn(() => []),
+}));
+vi.mock("../session-file-reader.js", () => ({
+  loadSessionEntries: vi.fn(() => []),
+}));
+vi.mock("@earendil-works/pi-coding-agent", () => ({
+  SessionManager: {
+    list: vi.fn(async () => []),
+    open: vi.fn(() => ({ getBranch: vi.fn(() => []) })),
+  },
+}));
+
+function makePrefs(pinnedDirs: string[] = []): PreferencesStore {
+  return {
+    getPinnedDirectories: () => pinnedDirs,
+    getSessionOrder: () => ({}),
+    setSessionOrder: vi.fn(),
+    setPinnedDirectories: vi.fn(),
+    pinDirectory: vi.fn(),
+    unpinDirectory: vi.fn(),
+    reorderPinnedDirs: vi.fn(),
+    flush: vi.fn(),
+    dispose: vi.fn(),
+  };
+}
+function makeSessionMgr(sessions: DashboardSession[] = []): SessionManager {
+  const map = new Map<string, DashboardSession>();
+  for (const s of sessions) map.set(s.id, s);
+  return {
+    register: vi.fn(),
+    restore: vi.fn(),
+    unregister: vi.fn(),
+    update: vi.fn(),
+    get: (id: string) => map.get(id),
+    listActive: () => Array.from(map.values()).filter(s => s.status !== "ended"),
+    listAll: () => Array.from(map.values()),
+  };
+}
+
+describe("DirectoryService — openspec.enabled gate", () => {
+  let service: DirectoryService;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+  afterEach(() => {
+    service?.stopPolling();
+  });
+
+  it("refreshOpenSpec returns cleared shape and spawns no CLI when disabled", async () => {
+    const prefs = makePrefs(["/repo"]);
+    const sessMgr = makeSessionMgr();
+    service = createDirectoryService(prefs, sessMgr, { ...DEFAULT_OPENSPEC_POLL, enabled: false });
+
+    const { pollOpenSpecAsync, runOpenSpecList, runOpenSpecStatus } = await import(
+      "@blackbelt-technology/pi-dashboard-shared/openspec-poller.js"
+    );
+
+    const data = await service.refreshOpenSpec("/repo");
+    expect(data).toEqual({
+      initialized: false,
+      pending: false,
+      changes: [],
+      hasOpenspecDir: false,
+    });
+    expect(pollOpenSpecAsync).not.toHaveBeenCalled();
+    expect(runOpenSpecList).not.toHaveBeenCalled();
+    expect(runOpenSpecStatus).not.toHaveBeenCalled();
+  });
+
+  it("pollDirectoryGated returns cleared shape and spawns no CLI when disabled", async () => {
+    const prefs = makePrefs();
+    const sessMgr = makeSessionMgr();
+    service = createDirectoryService(prefs, sessMgr, { ...DEFAULT_OPENSPEC_POLL, enabled: false });
+
+    const { runOpenSpecList } = await import(
+      "@blackbelt-technology/pi-dashboard-shared/openspec-poller.js"
+    );
+
+    const data = await service.pollDirectoryGated("/repo");
+    expect(data).toEqual({
+      initialized: false,
+      pending: false,
+      changes: [],
+      hasOpenspecDir: false,
+    });
+    expect(runOpenSpecList).not.toHaveBeenCalled();
+  });
+
+  it("reconfigurePolling({ enabled: false }) broadcasts cleared payload for every cached cwd", async () => {
+    const prefs = makePrefs(["/a", "/b"]);
+    const sessMgr = makeSessionMgr();
+    service = createDirectoryService(prefs, sessMgr); // starts enabled
+
+    // Seed the cache by calling refresh while enabled.
+    const { runOpenSpecList, runOpenSpecStatus } = await import(
+      "@blackbelt-technology/pi-dashboard-shared/openspec-poller.js"
+    );
+    (runOpenSpecList as any).mockResolvedValue({
+      mtimeMs: 1,
+      result: { changes: [], specs: [] },
+    });
+    (runOpenSpecStatus as any).mockResolvedValue(null);
+    await service.refreshOpenSpec("/a");
+    await service.refreshOpenSpec("/b");
+
+    expect(service.getOpenSpecData("/a")).toBeDefined();
+    expect(service.getOpenSpecData("/b")).toBeDefined();
+
+    // Wire the broadcast callback then flip the master gate.
+    const broadcasts: Array<{ cwd: string; data: unknown }> = [];
+    service.startPolling((cwd, data) => broadcasts.push({ cwd, data }));
+
+    service.reconfigurePolling({ ...DEFAULT_OPENSPEC_POLL, enabled: false });
+
+    const cleared = { initialized: false, pending: false, changes: [], hasOpenspecDir: false };
+    const cwds = new Set(broadcasts.map(b => b.cwd));
+    expect(cwds.has("/a")).toBe(true);
+    expect(cwds.has("/b")).toBe(true);
+    for (const b of broadcasts) {
+      expect(b.data).toEqual(cleared);
+    }
+    expect(service.getOpenSpecData("/a")).toEqual(cleared);
+    expect(service.getOpenSpecData("/b")).toEqual(cleared);
+  });
+
+  it("no broadcast on disabled→disabled or enabled→enabled reconfiguration", async () => {
+    const prefs = makePrefs(["/a"]);
+    const sessMgr = makeSessionMgr();
+    service = createDirectoryService(prefs, sessMgr, { ...DEFAULT_OPENSPEC_POLL, enabled: false });
+
+    const broadcasts: Array<{ cwd: string }> = [];
+    service.startPolling((cwd) => broadcasts.push({ cwd }));
+
+    // disabled → disabled with new interval — should not trigger the
+    // disable-broadcast path.
+    service.reconfigurePolling({
+      ...DEFAULT_OPENSPEC_POLL,
+      enabled: false,
+      pollIntervalSeconds: 90,
+    });
+    expect(broadcasts).toHaveLength(0);
+  });
+});

package/packages/server/src/__tests__/directory-service-refresh-force.test.ts

@@ -39,7 +39,7 @@ vi.mock("../session-file-reader.js", () => ({
   loadSessionEntries: vi.fn(() => []),
 }));
 
-vi.mock("@mariozechner/pi-coding-agent", () => ({
+vi.mock("@earendil-works/pi-coding-agent", () => ({
   SessionManager: {
     list: vi.fn(async () => []),
     open: vi.fn(() => ({ getBranch: vi.fn(() => []) })),

package/packages/server/src/__tests__/directory-service-specs-mtime.test.ts

@@ -47,7 +47,7 @@ vi.mock("../session-file-reader.js", () => ({
   loadSessionEntries: vi.fn(() => []),
 }));
 
-vi.mock("@mariozechner/pi-coding-agent", () => ({
+vi.mock("@earendil-works/pi-coding-agent", () => ({
   SessionManager: {
     list: vi.fn(async () => []),
     open: vi.fn(() => ({ getBranch: vi.fn(() => []) })),

package/packages/server/src/__tests__/directory-service-toctou.test.ts

@@ -46,7 +46,7 @@ vi.mock("../session-file-reader.js", () => ({
   loadSessionEntries: vi.fn(() => []),
 }));
 
-vi.mock("@mariozechner/pi-coding-agent", () => ({
+vi.mock("@earendil-works/pi-coding-agent", () => ({
   SessionManager: {
     list: vi.fn(async () => []),
     open: vi.fn(() => ({ getBranch: vi.fn(() => []) })),

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

@@ -42,7 +42,7 @@ vi.mock("../session-file-reader.js", () => ({
 }));
 
 // Mock the pi-coding-agent SessionManager (legacy, kept for compatibility)
-vi.mock("@mariozechner/pi-coding-agent", () => ({
+vi.mock("@earendil-works/pi-coding-agent", () => ({
   SessionManager: {
     list: vi.fn(async () => []),
     open: vi.fn(() => ({
@@ -633,7 +633,7 @@ describe("DirectoryService", () => {
       const sessionManager = createMockSessionManager();
       service = createDirectoryService(stateStore, sessionManager);
       await service.refreshOpenSpec("/x");
-      service.reconfigurePolling({ pollIntervalSeconds: 60, maxConcurrentSpawns: 5, changeDetection: "mtime", jitterSeconds: 0 });
+      service.reconfigurePolling({ enabled: true, pollIntervalSeconds: 60, maxConcurrentSpawns: 5, changeDetection: "mtime", jitterSeconds: 0 });
       expect(service.getOpenSpecData("/x")).toBeDefined();
     });
   });

package/packages/server/src/__tests__/dispatch-extension-command-router.test.ts

@@ -0,0 +1,178 @@
+/**
+ * dispatch-router unit tests (Phase 8 / task 8.7).
+ *
+ * Drives `handleDispatchExtensionCommand` with a mock `headlessPidRegistry`
+ * + browser broadcaster; asserts the optimistic-completion contract from
+ * `extension-rpc-dispatch` Requirement "Server-side dispatch routing to keeper".
+ *
+ * See change: add-rpc-stdin-dispatch-with-keeper-sidecar.
+ */
+import { describe, it, expect, vi } from "vitest";
+import {
+  buildPiRpcLine,
+  handleDispatchExtensionCommand,
+  type DispatchRouterContext,
+} from "../rpc-keeper/dispatch-router.js";
+import type { HeadlessPidRegistry } from "../headless-pid-registry.js";
+
+// ── Mocks ────────────────────────────────────────────────────────────────────
+
+interface FakeRegistryState {
+  writeRpcCalls: Array<{ sessionId: string; line: string }>;
+  writeRpcResult: boolean | Error;
+}
+
+function makeFakeRegistry(opts: { result: boolean | Error }): {
+  registry: HeadlessPidRegistry;
+  state: FakeRegistryState;
+} {
+  const state: FakeRegistryState = {
+    writeRpcCalls: [],
+    writeRpcResult: opts.result,
+  };
+  const registry: Partial<HeadlessPidRegistry> = {
+    writeRpc: async (sessionId, line) => {
+      state.writeRpcCalls.push({ sessionId, line });
+      if (state.writeRpcResult instanceof Error) throw state.writeRpcResult;
+      return state.writeRpcResult;
+    },
+  };
+  return { registry: registry as HeadlessPidRegistry, state };
+}
+
+interface FeedbackBroadcast {
+  sessionId: string;
+  command: string;
+  status: "completed" | "error";
+  message?: string;
+}
+
+function makeContext(registry: HeadlessPidRegistry): {
+  ctx: DispatchRouterContext;
+  broadcasts: FeedbackBroadcast[];
+} {
+  const broadcasts: FeedbackBroadcast[] = [];
+  return {
+    ctx: {
+      headlessPidRegistry: registry,
+      emitCommandFeedback: (sessionId, command, status, message) =>
+        broadcasts.push({ sessionId, command, status, message }),
+    },
+    broadcasts,
+  };
+}
+
+function feedbackData(b: FeedbackBroadcast): FeedbackBroadcast {
+  return b;
+}
+
+// ── Tests ────────────────────────────────────────────────────────────────────
+
+describe("buildPiRpcLine", () => {
+  it("constructs the pi RPC prompt JSON with command and id", () => {
+    const line = buildPiRpcLine("/ctx-stats", "req-1");
+    expect(JSON.parse(line)).toEqual({
+      type: "prompt",
+      message: "/ctx-stats",
+      id: "req-1",
+    });
+  });
+
+  it("preserves command text verbatim (no quoting)", () => {
+    const line = buildPiRpcLine("/ctx-stats verbose=1", "req-2");
+    const parsed = JSON.parse(line);
+    expect(parsed.message).toBe("/ctx-stats verbose=1");
+  });
+});
+
+describe("handleDispatchExtensionCommand", () => {
+  it("success path: writeRpc invoked, optimistic 'completed' broadcast", async () => {
+    const { registry, state } = makeFakeRegistry({ result: true });
+    const { ctx, broadcasts } = makeContext(registry);
+
+    await handleDispatchExtensionCommand(
+      { type: "dispatch_extension_command", sessionId: "S1", command: "/ctx-stats", requestId: "r1" },
+      ctx,
+    );
+
+    expect(state.writeRpcCalls).toHaveLength(1);
+    expect(state.writeRpcCalls[0].sessionId).toBe("S1");
+    expect(JSON.parse(state.writeRpcCalls[0].line)).toEqual({
+      type: "prompt",
+      message: "/ctx-stats",
+      id: "r1",
+    });
+
+    expect(broadcasts).toHaveLength(1);
+    expect(broadcasts[0].sessionId).toBe("S1");
+    expect(broadcasts[0].command).toBe("/ctx-stats");
+    expect(broadcasts[0].status).toBe("completed");
+    expect(broadcasts[0].message).toBeUndefined();
+  });
+
+  it("no-keeper path: writeRpc returns false \u2192 'error' with keeper-unavailable message", async () => {
+    const { registry } = makeFakeRegistry({ result: false });
+    const { ctx, broadcasts } = makeContext(registry);
+
+    await handleDispatchExtensionCommand(
+      { type: "dispatch_extension_command", sessionId: "S2", command: "/curator", requestId: "r2" },
+      ctx,
+    );
+
+    expect(broadcasts).toHaveLength(1);
+    expect(broadcasts[0].status).toBe("error");
+    expect(broadcasts[0].command).toBe("/curator");
+    expect(broadcasts[0].message).toMatch(/RPC keeper unavailable/);
+  });
+
+  it("write-fails path: writeRpc throws \u2192 'error' with reason-prefixed message", async () => {
+    const { registry } = makeFakeRegistry({ result: new Error("EPIPE") });
+    const { ctx, broadcasts } = makeContext(registry);
+
+    await handleDispatchExtensionCommand(
+      { type: "dispatch_extension_command", sessionId: "S3", command: "/agents", requestId: "r3" },
+      ctx,
+    );
+
+    expect(broadcasts).toHaveLength(1);
+    expect(broadcasts[0].status).toBe("error");
+    expect(broadcasts[0].message).toMatch(/Failed to write RPC line/);
+    expect(broadcasts[0].message).toMatch(/EPIPE/);
+  });
+
+  it("never throws even on registry failures", async () => {
+    const { registry } = makeFakeRegistry({ result: new Error("boom") });
+    const { ctx } = makeContext(registry);
+
+    await expect(
+      handleDispatchExtensionCommand(
+        { type: "dispatch_extension_command", sessionId: "S4", command: "/x", requestId: "r4" },
+        ctx,
+      ),
+    ).resolves.toBeUndefined();
+  });
+
+  it("emits exactly one broadcast per dispatch (success)", async () => {
+    const { registry } = makeFakeRegistry({ result: true });
+    const { ctx, broadcasts } = makeContext(registry);
+
+    await handleDispatchExtensionCommand(
+      { type: "dispatch_extension_command", sessionId: "S5", command: "/x", requestId: "r5" },
+      ctx,
+    );
+
+    expect(broadcasts).toHaveLength(1);
+  });
+
+  it("emits exactly one broadcast per dispatch (failure)", async () => {
+    const { registry } = makeFakeRegistry({ result: false });
+    const { ctx, broadcasts } = makeContext(registry);
+
+    await handleDispatchExtensionCommand(
+      { type: "dispatch_extension_command", sessionId: "S6", command: "/x", requestId: "r6" },
+      ctx,
+    );
+
+    expect(broadcasts).toHaveLength(1);
+  });
+});

package/packages/server/src/__tests__/e2e/model-proxy-google-flash.test.ts

@@ -0,0 +1,184 @@
+/**
+ * End-to-end smoke test for the model proxy using Google Gemini Flash (task 16.1).
+ *
+ * Skipped by default in CI. Enable with:
+ *   E2E_MODEL_PROXY=1 GEMINI_API_KEY=<key> npm test -- model-proxy-google-flash
+ *
+ * Steps:
+ *   1. Boot dashboard server on a random port
+ *   2. POST /api/model-proxy/api-keys → get a proxy key
+ *   3. GET /v1/models with the key → expect ≥1 model
+ *   4. If google/gemini-2.5-flash* model present:
+ *      a. POST /v1/chat/completions non-streaming → 200 + non-empty assistant text
+ *      b. POST /v1/chat/completions streaming → SSE chunks with delta.content
+ *      c. POST /v1/messages (Anthropic shape) → 200
+ *   5. Delete the API key → re-use → expect 401
+ *   6. Shutdown
+ *
+ * See change: add-dashboard-model-proxy, task 16.2.
+ */
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { createTestServer, type TestServerHandle } from "../../test-support/test-server.js";
+
+const ENABLED = process.env["E2E_MODEL_PROXY"] === "1";
+
+let handle: TestServerHandle | null = null;
+let httpPort: number;
+let proxyKey: string;
+
+beforeAll(async () => {
+  if (!ENABLED) return;
+  handle = await createTestServer();
+  httpPort = handle.httpPort;
+});
+
+afterAll(async () => {
+  if (handle) {
+    try { await handle.stop(); } catch {}
+    handle = null;
+  }
+});
+
+describe.skipIf(!ENABLED)("model-proxy e2e: google gemini flash", () => {
+  it("creates a proxy API key", async () => {
+    const res = await fetch(`http://localhost:${httpPort}/api/model-proxy/api-keys`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ label: "e2e-test" }),
+    });
+    expect(res.ok).toBe(true);
+    const body = await res.json() as any;
+    proxyKey = body.data.key;
+    expect(proxyKey).toMatch(/^pi-proxy-/);
+  });
+
+  it("GET /v1/models returns at least 1 model", async () => {
+    const res = await fetch(`http://localhost:${httpPort}/v1/models`, {
+      headers: { authorization: `Bearer ${proxyKey}` },
+    });
+    expect(res.ok).toBe(true);
+    const body = await res.json() as any;
+    expect(body.object).toBe("list");
+    expect(body.data.length).toBeGreaterThanOrEqual(1);
+  });
+
+  it("POST /v1/chat/completions non-streaming with google flash", async () => {
+    const modelsRes = await fetch(`http://localhost:${httpPort}/v1/models`, {
+      headers: { authorization: `Bearer ${proxyKey}` },
+    });
+    const modelsBody = await modelsRes.json() as any;
+    const flashModel = modelsBody.data.find((m: any) =>
+      m.id.includes("google/gemini-2.5-flash") || m.id.includes("gemini-2.5-flash"),
+    );
+
+    if (!flashModel) {
+      console.warn("No google/gemini-2.5-flash model available — skipping");
+      return;
+    }
+
+    const res = await fetch(`http://localhost:${httpPort}/v1/chat/completions`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        authorization: `Bearer ${proxyKey}`,
+      },
+      body: JSON.stringify({
+        model: flashModel.id,
+        messages: [{ role: "user", content: "Reply with just the word: ok" }],
+        stream: false,
+        max_tokens: 20,
+      }),
+    });
+
+    expect(res.ok).toBe(true);
+    const body = await res.json() as any;
+    const content = body.choices?.[0]?.message?.content ?? "";
+    expect(content.length).toBeGreaterThan(0);
+  });
+
+  it("POST /v1/chat/completions streaming with google flash", async () => {
+    const modelsRes = await fetch(`http://localhost:${httpPort}/v1/models`, {
+      headers: { authorization: `Bearer ${proxyKey}` },
+    });
+    const modelsBody = await modelsRes.json() as any;
+    const flashModel = modelsBody.data.find((m: any) =>
+      m.id.includes("google/gemini-2.5-flash") || m.id.includes("gemini-2.5-flash"),
+    );
+
+    if (!flashModel) {
+      console.warn("No google/gemini-2.5-flash model available — skipping");
+      return;
+    }
+
+    const res = await fetch(`http://localhost:${httpPort}/v1/chat/completions`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        authorization: `Bearer ${proxyKey}`,
+      },
+      body: JSON.stringify({
+        model: flashModel.id,
+        messages: [{ role: "user", content: "Reply with just the word: ok" }],
+        stream: true,
+        max_tokens: 20,
+      }),
+    });
+
+    expect(res.ok).toBe(true);
+    expect(res.headers.get("content-type")).toContain("text/event-stream");
+
+    const text = await res.text();
+    // Should contain at least one data chunk
+    expect(text).toContain("data:");
+    // Should end with [DONE]
+    expect(text).toContain("[DONE]");
+  });
+
+  it("POST /v1/messages (Anthropic shape) with google flash", async () => {
+    const modelsRes = await fetch(`http://localhost:${httpPort}/v1/models`, {
+      headers: { authorization: `Bearer ${proxyKey}` },
+    });
+    const modelsBody = await modelsRes.json() as any;
+    const flashModel = modelsBody.data.find((m: any) =>
+      m.id.includes("google/gemini-2.5-flash") || m.id.includes("gemini-2.5-flash"),
+    );
+
+    if (!flashModel) {
+      console.warn("No google/gemini-2.5-flash model available — skipping");
+      return;
+    }
+
+    const res = await fetch(`http://localhost:${httpPort}/v1/messages`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        authorization: `Bearer ${proxyKey}`,
+      },
+      body: JSON.stringify({
+        model: flashModel.id,
+        messages: [{ role: "user", content: "Reply with just the word: ok" }],
+        max_tokens: 20,
+      }),
+    });
+
+    expect(res.ok).toBe(true);
+  });
+
+  it("deleted API key returns 401 on re-use", async () => {
+    // Revoke the key first
+    const keysRes = await fetch(`http://localhost:${httpPort}/api/model-proxy/api-keys`);
+    const keysBody = await keysRes.json() as any;
+    const keyId = keysBody.data?.keys?.[0]?.id;
+    if (!keyId) return;
+
+    await fetch(`http://localhost:${httpPort}/api/model-proxy/api-keys/${keyId}/revoke`, {
+      method: "POST",
+    });
+
+    // Re-use should now fail
+    const res = await fetch(`http://localhost:${httpPort}/v1/models`, {
+      headers: { authorization: `Bearer ${proxyKey}` },
+    });
+    expect(res.status).toBe(401);
+  });
+});

package/packages/server/src/__tests__/event-wiring-providers-list.test.ts

@@ -1,7 +1,13 @@
 /**
  * End-to-end test: `providers_list` arriving from a (fake) bridge updates
  * the provider-catalogue cache, and `getAuthStatus()` reflects it.
- * See change: replace-hardcoded-provider-lists.
+ * Pins the contract that the server emits NO `models_refreshed` broadcast
+ * on `providers_list` arrival — the catalogue is a pure read consumer for
+ * the Settings UI, the model-selector dropdown lives on the independent
+ * `models_list` channel which is per-session-broadcast already.
+ * See changes: replace-hardcoded-provider-lists,
+ *              fix-providers-list-spurious-models-refreshed,
+ *              simplify-model-selection-channels.
  */
 import { describe, it, expect, beforeEach, afterEach } from "vitest";
 import { WebSocket } from "ws";
@@ -84,4 +90,65 @@ describe("providers_list — server wiring", () => {
 
     piWs.close();
   });
+
+  // Regression — see change: simplify-model-selection-channels.
+  // The server MUST NOT emit `models_refreshed` on routine providers_list
+  // arrivals. The previous implementation broadcast on every push (or, in
+  // the interim fix, on content change), which globally wiped browsers'
+  // modelsMap and left previously-visited sessions with empty model
+  // selectors. Per-session `models_list` updates are now the sole signal
+  // for dropdown contents.
+  it("never broadcasts models_refreshed on providers_list arrival (any flavour)", async () => {
+    const piWs = await connectSession(piPort, "p1");
+    const browserWs = new WebSocket(`ws://localhost:${browserPort}/ws`);
+    const browserMessages: any[] = [];
+    await new Promise<void>((resolve) => {
+      browserWs.on("open", () => resolve());
+    });
+    browserWs.on("message", (raw) => {
+      try {
+        const m = JSON.parse(raw.toString());
+        browserMessages.push(m);
+      } catch { /* ignore */ }
+    });
+    // Drain initial snapshot/handshake messages.
+    await wait(80);
+    browserMessages.length = 0;
+
+    const cat1 = [
+      { id: "deepseek", displayName: "DeepSeek", hasOAuth: false, configured: false },
+      { id: "fireworks", displayName: "Fireworks", hasOAuth: false, configured: false, envVar: "FIREWORKS_API_KEY" },
+    ];
+    const cat2 = [
+      { id: "deepseek", displayName: "DeepSeek", hasOAuth: false, configured: false, custom: true },
+      { id: "fireworks", displayName: "Fireworks", hasOAuth: false, configured: false, envVar: "FIREWORKS_API_KEY" },
+    ];
+
+    // First push — no broadcast.
+    piWs.send(JSON.stringify({ type: "providers_list", sessionId: "p1", providers: cat1 }));
+    await wait(80);
+    expect(browserMessages.filter((m) => m.type === "models_refreshed").length).toBe(0);
+
+    // Identical re-push — no broadcast.
+    piWs.send(JSON.stringify({ type: "providers_list", sessionId: "p1", providers: cat1 }));
+    await wait(80);
+    expect(browserMessages.filter((m) => m.type === "models_refreshed").length).toBe(0);
+
+    // Content change (custom flag flip) — still no broadcast.
+    piWs.send(JSON.stringify({ type: "providers_list", sessionId: "p1", providers: cat2 }));
+    await wait(80);
+    expect(browserMessages.filter((m) => m.type === "models_refreshed").length).toBe(0);
+
+    // New session sending its first push — still no broadcast (this was the
+    // exact scenario that defeated the per-session `changed` gate from the
+    // previous fix).
+    const piWs2 = await connectSession(piPort, "p2");
+    piWs2.send(JSON.stringify({ type: "providers_list", sessionId: "p2", providers: cat1 }));
+    await wait(80);
+    expect(browserMessages.filter((m) => m.type === "models_refreshed").length).toBe(0);
+
+    piWs.close();
+    piWs2.close();
+    browserWs.close();
+  });
 });