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

package/packages/server/src/__tests__/pi-core-updater-managed-path.test.ts

@@ -20,7 +20,7 @@ import type { PiCorePackage } from "@blackbelt-technology/pi-dashboard-shared/re
 
 function makePkg(overrides: Partial<PiCorePackage> = {}): PiCorePackage {
 	return {
-		name: "@mariozechner/pi-coding-agent",
+		name: "@earendil-works/pi-coding-agent",
 		displayName: "pi",
 		currentVersion: "0.1.0",
 		latestVersion: "0.2.0",
@@ -90,8 +90,11 @@ describe("defaultRunNpmUpdate — registry resolution + managed PATH", () => {
 		expect(capturedCmd).toBe("C:\\node\\node.exe");
 		expect(capturedArgs.slice(0, 2)).toEqual([
 			"C:\\node\\node_modules\\npm\\bin\\npm-cli.js",
-			"update",
+			"install",
 		]);
+		// Anchor the @latest suffix — the regression guard for
+		// fix-pi-core-update-cross-minor.
+		expect(capturedArgs).toContain("@earendil-works/pi-coding-agent@latest");
 	});
 
 	it("rejects with a clear 'npm' error when registry can't resolve", async () => {
@@ -152,7 +155,63 @@ describe("defaultRunNpmUpdate — registry resolution + managed PATH", () => {
 					_envBuilder: () => ({}),
 				},
 			),
-		).rejects.toThrow(/sudo npm update -g @example\/pkg/);
+		).rejects.toThrow(/sudo npm install -g @example\/pkg@latest/);
+	});
+
+	it("spawns npm install with @latest suffix for managed install (regression guard)", async () => {
+		// fix-pi-core-update-cross-minor: managed updates must not run
+		// `npm update` (which respects the consuming package.json range)
+		// — they must run `npm install <pkg>@latest`.
+		let capturedArgs: readonly string[] = [];
+		const spawnFn = makeFakeSpawn({
+			exitCode: 0,
+			captureSpawn: (_c, args) => {
+				capturedArgs = args;
+			},
+		});
+		// Pre-create the managed dir so the existence check passes.
+		const managedDir = path.join(os.homedir(), ".pi-dashboard");
+		fs.mkdirSync(managedDir, { recursive: true });
+
+		await defaultRunNpmUpdate(
+			makePkg({ name: "@mariozechner/pi-coding-agent", installSource: "managed" }),
+			() => {},
+			{
+				_resolveNpm: () => ({ ok: true, argv: ["/usr/bin/npm"] }),
+				_spawn: spawnFn,
+				_envBuilder: () => ({}),
+			},
+		);
+
+		expect(capturedArgs[0]).toBe("install");
+		// NOT "-g" for managed installs.
+		expect(capturedArgs).not.toContain("-g");
+		// The hot bit: @latest suffix.
+		expect(capturedArgs.some((a) => a === "@mariozechner/pi-coding-agent@latest")).toBe(true);
+	});
+
+	it("spawns npm install -g with @latest suffix for global install (regression guard)", async () => {
+		let capturedArgs: readonly string[] = [];
+		const spawnFn = makeFakeSpawn({
+			exitCode: 0,
+			captureSpawn: (_c, args) => {
+				capturedArgs = args;
+			},
+		});
+
+		await defaultRunNpmUpdate(
+			makePkg({ name: "@mariozechner/pi-coding-agent", installSource: "global" }),
+			() => {},
+			{
+				_resolveNpm: () => ({ ok: true, argv: ["/usr/bin/npm"] }),
+				_spawn: spawnFn,
+				_envBuilder: () => ({}),
+			},
+		);
+
+		expect(capturedArgs[0]).toBe("install");
+		expect(capturedArgs).toContain("-g");
+		expect(capturedArgs.some((a) => a.endsWith("@latest"))).toBe(true);
 	});
 
 	it("rejects up front when managed install dir does not exist", async () => {

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

@@ -8,7 +8,7 @@ import type { PiCorePackage } from "@blackbelt-technology/pi-dashboard-shared/re
 
 // Pi PM is mocked in other tests via vi.mock; we don't need it here because
 // we never call the install/remove/update methods — only runExclusive().
-vi.mock("@mariozechner/pi-coding-agent", () => ({
+vi.mock("@earendil-works/pi-coding-agent", () => ({
 	DefaultPackageManager: function () {
 		return {};
 	},

package/packages/server/src/__tests__/pi-dashboard-bin-wrapper.test.ts

@@ -0,0 +1,84 @@
+/**
+ * Tests for `packages/server/bin/pi-dashboard.mjs` — the published CLI
+ * bin entry. Spawns the wrapper as a child process to exercise the
+ * real jiti-resolution + re-exec behaviour.
+ *
+ * See change: replace-tsx-with-jiti.
+ */
+import { describe, it, expect, beforeAll } from "vitest";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import url from "node:url";
+
+const here = path.dirname(url.fileURLToPath(import.meta.url));
+const wrapperPath = path.resolve(here, "..", "..", "bin", "pi-dashboard.mjs");
+const repoNodeModules = path.resolve(here, "..", "..", "..", "..", "node_modules");
+const repoJitiRegister = path.join(repoNodeModules, "jiti", "lib", "jiti-register.mjs");
+
+describe("bin/pi-dashboard.mjs wrapper", () => {
+  beforeAll(() => {
+    if (!existsSync(wrapperPath)) {
+      throw new Error(`Wrapper missing at ${wrapperPath}`);
+    }
+  });
+
+  it("exits 1 with install-hint when jiti cannot be resolved", () => {
+    // Build an isolated anchor with NO node_modules tree — createRequire on
+    // it will fail to resolve `jiti/package.json`, triggering the miss path.
+    const tmp = mkdtempSync(path.join(tmpdir(), "pi-dashboard-bin-test-"));
+    try {
+      const fakeAnchor = path.join(tmp, "fake-anchor.js");
+      writeFileSync(fakeAnchor, "// no-op anchor with no node_modules\n");
+
+      // Spawn the wrapper. We override process.argv[1] indirectly by
+      // invoking node with `<wrapper>` then forcing argv[1] to the fake
+      // anchor via a tiny preamble — but the wrapper reads its OWN
+      // process.argv[1] which is the wrapper path itself when invoked
+      // directly. Strategy: copy the wrapper into the isolated tmp dir so
+      // its argv[1] resolves there with no jiti adjacency.
+      const isolatedWrapper = path.join(tmp, "pi-dashboard.mjs");
+      const wrapperSrc = require("node:fs").readFileSync(wrapperPath, "utf-8");
+      writeFileSync(isolatedWrapper, wrapperSrc);
+
+      const result = spawnSync(process.execPath, [isolatedWrapper, "--version"], {
+        encoding: "utf-8",
+        env: { ...process.env, NODE_PATH: "" },
+        timeout: 10_000,
+      });
+
+      expect(result.status).toBe(1);
+      expect(result.stderr).toContain("pi-dashboard: cannot find jiti");
+      expect(result.stderr).toContain("npm install -g @earendil-works/pi-coding-agent");
+      // No tsx mention — proposal mandates no-fallback wrapper.
+      expect(result.stderr).not.toMatch(/tsx/i);
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  it("resolves jiti from process.argv[1] anchor and re-execs cli.ts", () => {
+    // Repo root has jiti at node_modules/jiti — wrapper invoked with its
+    // real path SHOULD walk createRequire(realpath(argv[1])) up into the
+    // repo's node_modules and find jiti.
+    if (!existsSync(repoJitiRegister)) {
+      // CI / fresh clone without `npm install` — skip rather than fail.
+      return;
+    }
+
+    // Use `status` — it doesn't bind ports and exits quickly regardless
+    // of whether a server is running. We don't care about exit code (0 if
+    // a dashboard is up, 1 if not — both are valid outcomes that prove
+    // the wrapper successfully resolved jiti and re-execed cli.ts). What
+    // we DO care about: (a) no jiti-miss error on stderr, (b) cli.ts
+    // produced its own "Dashboard server" output (running OR not running).
+    const result = spawnSync(process.execPath, [wrapperPath, "status"], {
+      encoding: "utf-8",
+      timeout: 30_000,
+    });
+
+    expect(result.stderr).not.toContain("pi-dashboard: cannot find jiti");
+    expect(result.stdout).toMatch(/Dashboard server/i);
+  }, 60_000);
+});

package/packages/server/src/__tests__/pi-dev-version-check.test.ts

@@ -0,0 +1,184 @@
+/**
+ * Tests for `pi-dev-version-check.ts`.
+ *
+ * See change: improve-pi-update-detection.
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import {
+  parsePackageVersion,
+  comparePackageVersions,
+  isNewerPackageVersion,
+  getPiUserAgent,
+  getLatestPiRelease,
+} from "../pi-dev-version-check.js";
+
+describe("parsePackageVersion", () => {
+  it("parses plain semver", () => {
+    expect(parsePackageVersion("0.70.6")).toEqual({
+      major: 0,
+      minor: 70,
+      patch: 6,
+      prerelease: undefined,
+    });
+  });
+
+  it("parses semver with v prefix", () => {
+    expect(parsePackageVersion("v1.2.3")).toEqual({
+      major: 1,
+      minor: 2,
+      patch: 3,
+      prerelease: undefined,
+    });
+  });
+
+  it("parses semver with prerelease", () => {
+    expect(parsePackageVersion("0.71.0-rc.1")).toEqual({
+      major: 0,
+      minor: 71,
+      patch: 0,
+      prerelease: "rc.1",
+    });
+  });
+
+  it("returns undefined for unparseable", () => {
+    expect(parsePackageVersion("not-a-version")).toBeUndefined();
+    expect(parsePackageVersion("")).toBeUndefined();
+  });
+});
+
+describe("comparePackageVersions", () => {
+  it("orders by major then minor then patch", () => {
+    expect(comparePackageVersions("0.70.6", "0.74.0")).toBeLessThan(0);
+    expect(comparePackageVersions("1.0.0", "0.99.99")).toBeGreaterThan(0);
+    expect(comparePackageVersions("0.70.6", "0.70.6")).toBe(0);
+  });
+
+  it("treats prerelease as less than full release", () => {
+    expect(comparePackageVersions("0.71.0-rc.1", "0.71.0")).toBeLessThan(0);
+    expect(comparePackageVersions("0.71.0", "0.71.0-rc.1")).toBeGreaterThan(0);
+  });
+
+  it("returns undefined for unparseable", () => {
+    expect(comparePackageVersions("nope", "0.0.1")).toBeUndefined();
+  });
+});
+
+describe("isNewerPackageVersion", () => {
+  it("true when candidate is strictly newer", () => {
+    expect(isNewerPackageVersion("0.74.0", "0.70.6")).toBe(true);
+  });
+
+  it("false when candidate is same or older", () => {
+    expect(isNewerPackageVersion("0.70.6", "0.70.6")).toBe(false);
+    expect(isNewerPackageVersion("0.70.5", "0.70.6")).toBe(false);
+  });
+
+  it("falls back to string-inequality when unparseable", () => {
+    expect(isNewerPackageVersion("nightly-abc", "nightly-abc")).toBe(false);
+    expect(isNewerPackageVersion("nightly-xyz", "nightly-abc")).toBe(true);
+  });
+});
+
+describe("getPiUserAgent", () => {
+  it("formats as pi/<version> (<platform>; <runtime>; <arch>)", () => {
+    const ua = getPiUserAgent("0.70.6", "node/v22.20.0");
+    expect(ua).toMatch(/^pi\/0\.70\.6 \([a-z0-9]+; node\/v22\.20\.0; [a-z0-9]+\)$/);
+  });
+
+  it("auto-detects current Node runtime when not provided", () => {
+    const ua = getPiUserAgent("0.70.6");
+    expect(ua).toContain("pi/0.70.6");
+    // process.version is something like "v22.x.y"
+    expect(ua).toContain(`node/${process.version}`);
+  });
+});
+
+describe("getLatestPiRelease", () => {
+  let originalSkip: string | undefined;
+  let originalOffline: string | undefined;
+
+  beforeEach(() => {
+    originalSkip = process.env.PI_SKIP_VERSION_CHECK;
+    originalOffline = process.env.PI_OFFLINE;
+    delete process.env.PI_SKIP_VERSION_CHECK;
+    delete process.env.PI_OFFLINE;
+  });
+
+  afterEach(() => {
+    if (originalSkip !== undefined) process.env.PI_SKIP_VERSION_CHECK = originalSkip;
+    else delete process.env.PI_SKIP_VERSION_CHECK;
+    if (originalOffline !== undefined) process.env.PI_OFFLINE = originalOffline;
+    else delete process.env.PI_OFFLINE;
+  });
+
+  it("returns parsed { version, packageName } on success", async () => {
+    const fetchImpl = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ version: "0.74.0", packageName: "@earendil-works/pi-coding-agent" }),
+    });
+    const out = await getLatestPiRelease("0.70.6", { fetchImpl });
+    expect(out).toEqual({ version: "0.74.0", packageName: "@earendil-works/pi-coding-agent" });
+  });
+
+  it("returns undefined when packageName is absent", async () => {
+    const fetchImpl = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ version: "0.70.6" }),
+    });
+    const out = await getLatestPiRelease("0.70.6", { fetchImpl });
+    expect(out).toEqual({ version: "0.70.6", packageName: undefined });
+  });
+
+  it("sends User-Agent matching pi's format", async () => {
+    let capturedUA: string | undefined;
+    const fetchImpl = vi.fn().mockImplementation((_url: string, opts: any) => {
+      capturedUA = opts.headers?.["User-Agent"];
+      return Promise.resolve({
+        ok: true,
+        json: async () => ({ version: "0.74.0" }),
+      });
+    });
+    await getLatestPiRelease("0.70.6", { fetchImpl });
+    expect(capturedUA).toMatch(/^pi\/0\.70\.6 \([a-z0-9]+; node\/v[\d.]+; [a-z0-9]+\)$/);
+  });
+
+  it("returns undefined on non-2xx", async () => {
+    const fetchImpl = vi.fn().mockResolvedValue({ ok: false, status: 503, json: async () => ({}) });
+    expect(await getLatestPiRelease("0.70.6", { fetchImpl })).toBeUndefined();
+  });
+
+  it("returns undefined on network error", async () => {
+    const fetchImpl = vi.fn().mockRejectedValue(new Error("ECONNRESET"));
+    expect(await getLatestPiRelease("0.70.6", { fetchImpl })).toBeUndefined();
+  });
+
+  it("returns undefined on missing version field", async () => {
+    const fetchImpl = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ packageName: "@x/y" }),
+    });
+    expect(await getLatestPiRelease("0.70.6", { fetchImpl })).toBeUndefined();
+  });
+
+  it("returns undefined on empty version field", async () => {
+    const fetchImpl = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ version: "   " }),
+    });
+    expect(await getLatestPiRelease("0.70.6", { fetchImpl })).toBeUndefined();
+  });
+
+  it("skips request when PI_OFFLINE is set", async () => {
+    process.env.PI_OFFLINE = "1";
+    const fetchImpl = vi.fn();
+    expect(await getLatestPiRelease("0.70.6", { fetchImpl })).toBeUndefined();
+    expect(fetchImpl).not.toHaveBeenCalled();
+  });
+
+  it("skips request when PI_SKIP_VERSION_CHECK is set", async () => {
+    process.env.PI_SKIP_VERSION_CHECK = "1";
+    const fetchImpl = vi.fn();
+    expect(await getLatestPiRelease("0.70.6", { fetchImpl })).toBeUndefined();
+    expect(fetchImpl).not.toHaveBeenCalled();
+  });
+});

package/packages/server/src/__tests__/pi-version-skew.test.ts

@@ -187,17 +187,17 @@ describe("pi-version-skew", () => {
     }
 
     it("npm-global symlinked bin launcher resolves to the real package.json", () => {
-      // Simulate ~/.nvm/.../bin/pi → ../lib/node_modules/@mariozechner/pi-coding-agent/dist/cli.js
+      // Simulate ~/.nvm/.../bin/pi → ../lib/node_modules/@earendil-works/pi-coding-agent/dist/cli.js
       const nodeRoot = path.join(tmpDir, "node-install");
       const binDir = path.join(nodeRoot, "bin");
-      const pkgDir = path.join(nodeRoot, "lib", "node_modules", "@mariozechner", "pi-coding-agent");
+      const pkgDir = path.join(nodeRoot, "lib", "node_modules", "@earendil-works", "pi-coding-agent");
       const distDir = path.join(pkgDir, "dist");
       fs.mkdirSync(binDir, { recursive: true });
       fs.mkdirSync(distDir, { recursive: true });
       fs.writeFileSync(path.join(distDir, "cli.js"), "// stub");
       fs.writeFileSync(
         path.join(pkgDir, "package.json"),
-        JSON.stringify({ name: "@mariozechner/pi-coding-agent", version: "0.70.0" }),
+        JSON.stringify({ name: "@earendil-works/pi-coding-agent", version: "0.74.0" }),
       );
       // The bad path (what old code computed) must NOT exist.
       // That is: nodeRoot/package.json. We leave it absent.
@@ -210,7 +210,7 @@ describe("pi-version-skew", () => {
       );
 
       const registry = stubRegistry(binLink);
-      expect(readCurrentPiVersion(registry)).toBe("0.70.0");
+      expect(readCurrentPiVersion(registry)).toBe("0.74.0");
     });
 
     it("non-symlinked path is a no-op under realpath", () => {

package/packages/server/src/__tests__/process-manager-keeper-spawn.test.ts

@@ -0,0 +1,206 @@
+/**
+ * Tests for the `useRpcKeeper: true` branch in `spawnHeadless` (Phase 5).
+ *
+ * Drives `spawnPiSession({strategy: "headless"})` with the keeper-flag
+ * override on, an injected fake KeeperManager, and verifies:
+ *   - keeper branch fires (KeeperManager.spawnKeeperFor called, NOT pi resolved)
+ *   - returned SpawnResult.pid is the keeper PID
+ *   - env passed to the keeper includes `PI_DASHBOARD_SPAWN_TOKEN`
+ *   - keeper failure surfaces as `PI_CRASHED` or `SPAWN_ERRNO`
+ *   - flag OFF (default) → keeper is NOT used
+ */
+import { EventEmitter } from "node:events";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type {
+  KeeperManager,
+  KeeperSpawnResult,
+} from "../rpc-keeper/keeper-manager.js";
+import {
+  setKeeperManager,
+  _setUseRpcKeeperOverrideForTests,
+  spawnPiSession,
+} from "../process-manager.js";
+
+class FakeKeeperChild extends EventEmitter {
+  pid: number;
+  unref = vi.fn();
+  kill = vi.fn();
+  // Never emits "exit" → waitForNoCrash window completes cleanly.
+  constructor(pid: number) { super(); this.pid = pid; }
+}
+
+interface FakeKeeperManagerState {
+  spawnCalls: Array<{ sessionId: string; cwd: string; env: NodeJS.ProcessEnv; piArgs?: string[] }>;
+  writeCalls: Array<{ sessionId: string; line: string }>;
+  killCalls: string[];
+  spawnResult: KeeperSpawnResult;
+}
+
+function makeFakeKeeperManager(
+  state: Partial<FakeKeeperManagerState> & { spawnResult: KeeperSpawnResult },
+): { km: KeeperManager; state: FakeKeeperManagerState } {
+  const full: FakeKeeperManagerState = {
+    spawnCalls: state.spawnCalls ?? [],
+    writeCalls: state.writeCalls ?? [],
+    killCalls: state.killCalls ?? [],
+    spawnResult: state.spawnResult,
+  };
+  const km: KeeperManager = {
+    sessionsDir: "/fake/sessions",
+    spawnKeeperFor: async (sessionId, cwd, env, piArgs) => {
+      full.spawnCalls.push({ sessionId, cwd, env, piArgs });
+      return full.spawnResult;
+    },
+    writeRpc: async (sessionId, line) => {
+      full.writeCalls.push({ sessionId, line });
+      return true;
+    },
+    writeRpcToSockPath: async (_sockPath, _line) => true,
+    killKeeper: (sessionId) => {
+      full.killCalls.push(sessionId);
+      return true;
+    },
+    discoverExistingKeepers: async () => [],
+  };
+  return { km, state: full };
+}
+
+let tmpCwd: string;
+
+beforeEach(() => {
+  tmpCwd = mkdtempSync(path.join("/tmp", "km-cwd-"));
+});
+afterEach(() => {
+  setKeeperManager(null);
+  _setUseRpcKeeperOverrideForTests(null);
+  rmSync(tmpCwd, { recursive: true, force: true });
+});
+
+describe("spawnHeadless (useRpcKeeper: true)", () => {
+  it("routes through KeeperManager when flag is on", async () => {
+    const fakeChild = new FakeKeeperChild(11111);
+    const { km, state } = makeFakeKeeperManager({
+      spawnResult: {
+        success: true,
+        pid: 11111,
+        sockPath: "/fake/sessions/sid.rpc.sock",
+        process: fakeChild as unknown as import("node:child_process").ChildProcess,
+      },
+    });
+    setKeeperManager(km);
+    _setUseRpcKeeperOverrideForTests(true);
+
+    const result = await spawnPiSession(tmpCwd, { strategy: "headless" });
+
+    expect(result.success).toBe(true);
+    expect(result.pid).toBe(11111);
+    expect(state.spawnCalls).toHaveLength(1);
+    expect(state.spawnCalls[0].cwd).toBe(tmpCwd);
+
+    // spawnToken contract (task 5.3): the env passed to the keeper carries
+    // PI_DASHBOARD_SPAWN_TOKEN, which the keeper forwards to pi via
+    // process.env inheritance.
+    expect(state.spawnCalls[0].env.PI_DASHBOARD_SPAWN_TOKEN).toBeDefined();
+    expect(typeof state.spawnCalls[0].env.PI_DASHBOARD_SPAWN_TOKEN).toBe("string");
+    expect(state.spawnCalls[0].env.PI_DASHBOARD_SPAWN_TOKEN!.length).toBeGreaterThan(0);
+
+    // The returned spawnToken matches what was injected into env.
+    expect(result.spawnToken).toBe(state.spawnCalls[0].env.PI_DASHBOARD_SPAWN_TOKEN);
+
+    // Bare-spawn piArgs are at least `--mode rpc`.
+    expect(state.spawnCalls[0].piArgs).toBeDefined();
+    expect(state.spawnCalls[0].piArgs).toContain("--mode");
+    expect(state.spawnCalls[0].piArgs).toContain("rpc");
+
+    // SpawnResult.keeperSockPath populated so callers can pass it to
+    // `headlessPidRegistry.register(..., {keeperPid, keeperSockPath})`
+    // (Phase 6 contract). See change: add-rpc-stdin-dispatch-with-keeper-sidecar.
+    expect(result.keeperSockPath).toBe("/fake/sessions/sid.rpc.sock");
+  });
+
+  it("forwards resume flags (sessionFile / mode) to the keeper as piArgs", async () => {
+    const fakeChild = new FakeKeeperChild(33333);
+    const { km, state } = makeFakeKeeperManager({
+      spawnResult: {
+        success: true,
+        pid: 33333,
+        sockPath: "/fake/x.sock",
+        process: fakeChild as unknown as import("node:child_process").ChildProcess,
+      },
+    });
+    setKeeperManager(km);
+    _setUseRpcKeeperOverrideForTests(true);
+
+    const sessionFile = "/tmp/sess-resume.jsonl";
+    const result = await spawnPiSession(tmpCwd, {
+      strategy: "headless",
+      sessionFile,
+      mode: "continue",
+    });
+
+    expect(result.success).toBe(true);
+    expect(state.spawnCalls).toHaveLength(1);
+    const piArgs = state.spawnCalls[0].piArgs ?? [];
+    // piArgs MUST carry the session-file flag so resume actually resumes
+    // (regression guard: in the first Phase-5 cut the keeper hardcoded
+    // ["--mode","rpc"] and resume created a fresh session instead).
+    expect(piArgs).toContain("--mode");
+    expect(piArgs).toContain("rpc");
+    // sessionFlagsToArgv emits the session-file path; the exact flag name
+    // (`--session-file`) is verified in spawn-mechanism unit tests; here
+    // we only assert the path token is present so we don't double-bind to
+    // upstream argv shape.
+    expect(piArgs).toContain(sessionFile);
+  });
+
+  it("returns SPAWN_ERRNO when KeeperManager.spawnKeeperFor reports !success", async () => {
+    const { km } = makeFakeKeeperManager({
+      spawnResult: { success: false, error: "EACCES on socket bind" },
+    });
+    setKeeperManager(km);
+    _setUseRpcKeeperOverrideForTests(true);
+
+    const result = await spawnPiSession(tmpCwd, { strategy: "headless" });
+    expect(result.success).toBe(false);
+    expect(result.code).toBe("SPAWN_ERRNO");
+    expect(result.message).toMatch(/RPC keeper/);
+    expect(result.message).toMatch(/EACCES/);
+  });
+
+  it("returns PI_CRASHED when keeper exits within the crash window", async () => {
+    // A child that emits "exit" inside 300 ms triggers the waitForNoCrash gate.
+    const fakeChild = new FakeKeeperChild(22222);
+    setTimeout(() => fakeChild.emit("exit", 1, null), 20);
+
+    const { km } = makeFakeKeeperManager({
+      spawnResult: {
+        success: true,
+        pid: 22222,
+        sockPath: "/fake/sessions/sid.rpc.sock",
+        process: fakeChild as unknown as import("node:child_process").ChildProcess,
+      },
+    });
+    setKeeperManager(km);
+    _setUseRpcKeeperOverrideForTests(true);
+
+    const result = await spawnPiSession(tmpCwd, { strategy: "headless" });
+    expect(result.success).toBe(false);
+    expect(result.code).toBe("PI_CRASHED");
+    expect(result.message).toMatch(/crash window/);
+  });
+
+  it("does NOT route through KeeperManager when flag is off (default)", async () => {
+    const { km, state } = makeFakeKeeperManager({
+      spawnResult: { success: true, pid: 99999, sockPath: "/fake/x.sock" },
+    });
+    setKeeperManager(km);
+    _setUseRpcKeeperOverrideForTests(false);
+
+    // We don't care about the actual headless spawn result here — only that
+    // it does NOT call the fake KeeperManager.
+    await spawnPiSession(tmpCwd, { strategy: "headless" });
+    expect(state.spawnCalls).toEqual([]);
+  });
+});

package/packages/server/src/__tests__/provider-auth-routes.test.ts

@@ -114,7 +114,14 @@ describe("provider-auth-routes", () => {
 
   // /exchange endpoint removed — token exchange happens in the callback server's onCode
 
-  it("PUT /api/provider-auth/api-key saves and notifies bridges and browsers", async () => {
+  // notifyBridges semantics changed: it now ONLY broadcasts
+  // `credentials_updated` to bridges. The previous `models_refreshed`
+  // broadcast to browsers was removed because the per-session
+  // `models_list` channel is self-healing: each bridge pushes a fresh
+  // models_list for its session on credentials_updated, and browsers
+  // update modelsMap[sid] incrementally without a global wipe. See
+  // change: simplify-model-selection-channels.
+  it("PUT /api/provider-auth/api-key saves and broadcasts credentials_updated to bridges", async () => {
     const { writeCredential } = await import("../provider-auth-storage.js");
     const res = await app.inject({
       method: "PUT",
@@ -125,10 +132,11 @@ describe("provider-auth-routes", () => {
     expect(JSON.parse(res.payload).ok).toBe(true);
     expect(writeCredential).toHaveBeenCalledWith("openai", { type: "api_key", key: "sk-test" });
     expect(piGateway.broadcast).toHaveBeenCalledWith({ type: "credentials_updated" });
-    expect(browserGateway.broadcastToAll).toHaveBeenCalledWith({ type: "models_refreshed" });
+    // No models_refreshed broadcast — see simplify-model-selection-channels.
+    expect(browserGateway.broadcastToAll).not.toHaveBeenCalledWith({ type: "models_refreshed" });
   });
 
-  it("DELETE /api/provider-auth/:provider removes and notifies bridges and browsers", async () => {
+  it("DELETE /api/provider-auth/:provider removes and broadcasts credentials_updated", async () => {
     const { removeCredential } = await import("../provider-auth-storage.js");
     const res = await app.inject({
       method: "DELETE",
@@ -137,7 +145,7 @@ describe("provider-auth-routes", () => {
     expect(res.statusCode).toBe(200);
     expect(removeCredential).toHaveBeenCalledWith("anthropic");
     expect(piGateway.broadcast).toHaveBeenCalledWith({ type: "credentials_updated" });
-    expect(browserGateway.broadcastToAll).toHaveBeenCalledWith({ type: "models_refreshed" });
+    expect(browserGateway.broadcastToAll).not.toHaveBeenCalledWith({ type: "models_refreshed" });
   });
 
   // /callback/:provider route removed — temp callback server handles this directly