@blackbelt-technology/pi-agent-dashboard 0.2.9 → 0.4.0

package/packages/server/src/__tests__/cors.test.ts

@@ -2,10 +2,16 @@ import { describe, it, expect } from "vitest";
 
 /**
  * Unit tests for CORS origin validation logic.
- * Tests the same logic used in server.ts CORS callback.
+ * Mirrors the callback used in server.ts — kept in sync by hand. The tunnel
+ * URL is injected via a thunk so tests can simulate an active tunnel without
+ * importing the full server.
  */
 
-function isAllowedOrigin(origin: string | undefined, configuredOrigins: string[]): boolean {
+function isAllowedOrigin(
+  origin: string | undefined,
+  configuredOrigins: string[],
+  getTunnelUrl: () => string | null = () => null,
+): boolean {
   if (!origin) return true;
   try {
     const u = new URL(origin);
@@ -13,6 +19,9 @@ function isAllowedOrigin(origin: string | undefined, configuredOrigins: string[]
     if (host === "localhost" || host === "127.0.0.1" || host === "[::1]" || host === "::1") {
       return true;
     }
+    const tunnelUrl = getTunnelUrl();
+    if (tunnelUrl && origin === tunnelUrl) return true;
+    if (host.endsWith(".share.zrok.io")) return true;
   } catch { /* ignore */ }
   return configuredOrigins.includes(origin);
 }
@@ -45,4 +54,27 @@ describe("CORS origin validation", () => {
   it("rejects non-localhost remote origins without config", () => {
     expect(isAllowedOrigin("http://192.168.1.100:3000", [])).toBe(false);
   });
+
+  // Regression: Vite emits `<script type="module" crossorigin>` which makes
+  // browsers send CORS-mode requests even same-origin. When the dashboard is
+  // served through a zrok tunnel the Origin header is the tunnel URL, which
+  // previously wasn't in the allow list — the server then threw inside the
+  // CORS callback, surfacing as HTTP 500 on every asset. These tests pin the
+  // fix so that behavior cannot regress.
+  describe("zrok tunnel origins (browser module-script regression)", () => {
+    it("allows the currently-active tunnel URL", () => {
+      const tunnelUrl = "https://cwanni9wce66.share.zrok.io";
+      expect(isAllowedOrigin(tunnelUrl, [], () => tunnelUrl)).toBe(true);
+    });
+
+    it("allows any *.share.zrok.io origin (URL rotation, stale tabs)", () => {
+      expect(isAllowedOrigin("https://tgbdzzvlar6b.share.zrok.io", [])).toBe(true);
+      expect(isAllowedOrigin("https://anyothershare123.share.zrok.io", [])).toBe(true);
+    });
+
+    it("does not allow non-zrok sibling hosts", () => {
+      expect(isAllowedOrigin("https://share.zrok.io.attacker.com", [])).toBe(false);
+      expect(isAllowedOrigin("https://evil.io", [])).toBe(false);
+    });
+  });
 });

package/packages/server/src/__tests__/crash-recovery.test.ts

@@ -0,0 +1,88 @@
+/**
+ * Integration test — crash recovery.
+ *
+ * Simulates the "SIGKILL, no cleanup" case:
+ *   1. Acquire lock
+ *   2. Skip release() (simulated crash)
+ *   3. Attempt to acquire again from a different caller
+ *   4. Assert: stale detection fires, new caller acquires cleanly
+ *
+ * See change: single-dashboard-per-home, task 12.2.
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { acquireOrAttach } from "../home-lock.js";
+
+let tmpHome: string;
+let lockPath: string;
+let metaPath: string;
+
+beforeEach(() => {
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "pi-crash-"));
+  lockPath = path.join(tmpHome, ".pi", "dashboard", "server.lock");
+  metaPath = `${lockPath}.meta.json`;
+});
+
+afterEach(() => {
+  try { fs.rmSync(tmpHome, { recursive: true, force: true }); } catch { /* ignore */ }
+});
+
+describe("crash recovery", () => {
+  it("steals a stale lock when the previous holder's process is dead", async () => {
+    // First acquire — simulate a dead process.
+    const first = await acquireOrAttach({
+      httpPort: 8000, piPort: 9999, version: "t",
+      identity: "dead-holder",
+      hooks: { lockPath, metaPath, staleMs: 1 },
+    });
+    expect(first.mode).toBe("acquired");
+    // INTENTIONALLY don't release.
+
+    // Allow stale threshold to elapse.
+    await new Promise(r => setTimeout(r, 50));
+
+    const second = await acquireOrAttach({
+      httpPort: 8000, piPort: 9999, version: "t",
+      identity: "recovery",
+      hooks: {
+        lockPath, metaPath, staleMs: 1,
+        isProcessAlive: () => false,           // previous holder is dead
+        probeHealth: async () => ({ running: false }),
+      },
+    });
+    expect(second.mode).toBe("acquired");
+
+    // Metadata now reflects the new holder.
+    const meta = JSON.parse(fs.readFileSync(metaPath, "utf-8")) as { identity: string };
+    expect(meta.identity).toBe("recovery");
+
+    if (second.mode === "acquired") await second.release();
+  });
+
+  it("cleans up the metadata sidecar on graceful release", async () => {
+    const r = await acquireOrAttach({
+      httpPort: 8000, piPort: 9999, version: "t",
+      hooks: { lockPath, metaPath, staleMs: 1_000 },
+    });
+    expect(r.mode).toBe("acquired");
+    expect(fs.existsSync(metaPath)).toBe(true);
+
+    if (r.mode === "acquired") {
+      await r.release();
+      expect(fs.existsSync(metaPath)).toBe(false);
+    }
+  });
+
+  it("leaves metadata in place on crash (no release called)", async () => {
+    const r = await acquireOrAttach({
+      httpPort: 8000, piPort: 9999, version: "t",
+      hooks: { lockPath, metaPath, staleMs: 1_000 },
+    });
+    expect(r.mode).toBe("acquired");
+    // Don't release; metadata should persist until the next successful
+    // acquire clears it as part of steal.
+    expect(fs.existsSync(metaPath)).toBe(true);
+  });
+});

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

@@ -7,9 +7,23 @@ 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";
 
-// Mock the shared openspec poller
-vi.mock("@blackbelt-technology/pi-dashboard-shared/openspec-poller.js", () => ({
-  pollOpenSpecAsync: vi.fn(async () => ({ initialized: false, changes: [] })),
+// Mock the shared openspec poller. We expose three entry points now:
+//   - pollOpenSpecAsync: legacy monolithic (still used as fallback where no mtime gate applies)
+//   - runOpenSpecList:   new granular list call
+//   - runOpenSpecStatus: new granular status call
+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: false, changes: [] })),
+    runOpenSpecList: vi.fn(async () => null),
+    runOpenSpecStatus: vi.fn(async () => null),
+  };
+});
+
+// Mock pi-resource-scanner so polling ticks don't hit the filesystem.
+vi.mock("../pi-resource-scanner.js", () => ({
+  scanPiResources: vi.fn(async () => ({ local: { extensions: [], skills: [], prompts: [] }, global: { extensions: [], skills: [], prompts: [] }, packages: [] })),
 }));
 
 // Mock the shared state replay
@@ -184,20 +198,33 @@ describe("DirectoryService", () => {
 
   describe("getOpenSpecData / refreshOpenSpec", () => {
     it("returns cached data after polling", async () => {
-      const { pollOpenSpecAsync } = await import("@blackbelt-technology/pi-dashboard-shared/openspec-poller.js");
-      (pollOpenSpecAsync as any).mockResolvedValue({ initialized: true, changes: [{ name: "change-1" }] });
+      // Use the granular mocks; fs.stat on the bogus path will return undefined so
+      // the new gated poll short-circuits. To exercise the happy path we set up a
+      // real tmp dir with an openspec/changes folder.
+      const fs = await import("node:fs");
+      const os = await import("node:os");
+      const path = await import("node:path");
+      const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "ds-cache-"));
+      fs.mkdirSync(path.join(tmp, "openspec", "changes", "change-1"), { recursive: true });
+
+      const { runOpenSpecList, runOpenSpecStatus } = await import("@blackbelt-technology/pi-dashboard-shared/openspec-poller.js");
+      (runOpenSpecList as any).mockResolvedValue({ changes: [
+        { name: "change-1", status: "in-progress", completedTasks: 0, totalTasks: 1 },
+      ] });
+      (runOpenSpecStatus as any).mockResolvedValue({ artifacts: [], isComplete: false });
 
       const stateStore = createMockPreferencesStore();
       const sessionManager = createMockSessionManager();
       service = createDirectoryService(stateStore, sessionManager);
 
-      const data = await service.refreshOpenSpec("/project");
+      const data = await service.refreshOpenSpec(tmp);
       expect(data.initialized).toBe(true);
       expect(data.changes[0].name).toBe("change-1");
 
-      // getOpenSpecData returns cached value
-      const cached = service.getOpenSpecData("/project");
+      const cached = service.getOpenSpecData(tmp);
       expect(cached).toEqual(data);
+
+      fs.rmSync(tmp, { recursive: true, force: true });
     });
   });
 
@@ -237,4 +264,203 @@ describe("DirectoryService", () => {
       vi.useRealTimers();
     });
   });
+
+  describe("mtime gate", () => {
+    const fs = require("node:fs") as typeof import("node:fs");
+    const os = require("node:os") as typeof import("node:os");
+    const path = require("node:path") as typeof import("node:path");
+
+    let tmpDir: string;
+    let cwd: string;
+    let changesDir: string;
+
+    beforeEach(async () => {
+      vi.clearAllMocks();
+      tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "ds-mtime-"));
+      cwd = tmpDir;
+      changesDir = path.join(cwd, "openspec", "changes");
+      fs.mkdirSync(changesDir, { recursive: true });
+      fs.mkdirSync(path.join(changesDir, "change-a"));
+      fs.mkdirSync(path.join(changesDir, "change-b"));
+    });
+
+    afterEach(() => {
+      if (fs.existsSync(tmpDir)) fs.rmSync(tmpDir, { recursive: true, force: true });
+    });
+
+    it("first poll invokes list and status for each change", async () => {
+      const { runOpenSpecList, runOpenSpecStatus } = await import("@blackbelt-technology/pi-dashboard-shared/openspec-poller.js");
+      (runOpenSpecList as any).mockResolvedValue({ changes: [
+        { name: "change-a", status: "in-progress", completedTasks: 1, totalTasks: 2 },
+        { name: "change-b", status: "in-progress", completedTasks: 0, totalTasks: 3 },
+      ] });
+      (runOpenSpecStatus as any).mockResolvedValue({ artifacts: [], isComplete: false });
+
+      const stateStore = createMockPreferencesStore();
+      const sessionManager = createMockSessionManager();
+      service = createDirectoryService(stateStore, sessionManager);
+
+      const data = await service.refreshOpenSpec(cwd);
+      expect(data.initialized).toBe(true);
+      expect(data.changes).toHaveLength(2);
+      expect(runOpenSpecList).toHaveBeenCalledTimes(1);
+      expect(runOpenSpecStatus).toHaveBeenCalledTimes(2);
+    });
+
+    it("second poll with unchanged mtimes makes zero CLI calls", async () => {
+      const { runOpenSpecList, runOpenSpecStatus } = await import("@blackbelt-technology/pi-dashboard-shared/openspec-poller.js");
+      (runOpenSpecList as any).mockResolvedValue({ changes: [
+        { name: "change-a", status: "in-progress", completedTasks: 1, totalTasks: 2 },
+      ] });
+      (runOpenSpecStatus as any).mockResolvedValue({ artifacts: [], isComplete: false });
+
+      const stateStore = createMockPreferencesStore();
+      const sessionManager = createMockSessionManager();
+      service = createDirectoryService(stateStore, sessionManager);
+
+      // First poll (force = true bypasses gate, populates cache).
+      await service.refreshOpenSpec(cwd);
+      (runOpenSpecList as any).mockClear();
+      (runOpenSpecStatus as any).mockClear();
+
+      // Second poll via the internal gated path.
+      await service.pollDirectoryGated(cwd);
+      expect(runOpenSpecList).not.toHaveBeenCalled();
+      expect(runOpenSpecStatus).not.toHaveBeenCalled();
+    });
+
+    it("mtime advance on one change runs status only for that change", async () => {
+      const { runOpenSpecList, runOpenSpecStatus } = await import("@blackbelt-technology/pi-dashboard-shared/openspec-poller.js");
+      (runOpenSpecList as any).mockResolvedValue({ changes: [
+        { name: "change-a", status: "in-progress", completedTasks: 1, totalTasks: 2 },
+        { name: "change-b", status: "in-progress", completedTasks: 0, totalTasks: 3 },
+      ] });
+      (runOpenSpecStatus as any).mockResolvedValue({ artifacts: [], isComplete: false });
+
+      const stateStore = createMockPreferencesStore();
+      const sessionManager = createMockSessionManager();
+      service = createDirectoryService(stateStore, sessionManager);
+      await service.refreshOpenSpec(cwd);
+      (runOpenSpecList as any).mockClear();
+      (runOpenSpecStatus as any).mockClear();
+
+      // Bump mtime of change-a only by touching a file inside it.
+      const future = new Date(Date.now() + 10_000);
+      fs.utimesSync(path.join(changesDir, "change-a"), future, future);
+
+      await service.pollDirectoryGated(cwd);
+      // List is gated by top-level mtime (unchanged) so it's skipped.
+      expect(runOpenSpecList).not.toHaveBeenCalled();
+      // Status re-run exactly once, for change-a.
+      expect(runOpenSpecStatus).toHaveBeenCalledTimes(1);
+      expect((runOpenSpecStatus as any).mock.calls[0][1]).toBe("change-a");
+    });
+
+    it("changeDetection: 'always' bypasses the gate", async () => {
+      const { runOpenSpecList, runOpenSpecStatus } = await import("@blackbelt-technology/pi-dashboard-shared/openspec-poller.js");
+      (runOpenSpecList as any).mockResolvedValue({ changes: [
+        { name: "change-a", status: "in-progress", completedTasks: 0, totalTasks: 1 },
+      ] });
+      (runOpenSpecStatus as any).mockResolvedValue({ artifacts: [], isComplete: false });
+
+      const stateStore = createMockPreferencesStore();
+      const sessionManager = createMockSessionManager();
+      service = createDirectoryService(stateStore, sessionManager, { changeDetection: "always" });
+      await service.refreshOpenSpec(cwd);
+      (runOpenSpecList as any).mockClear();
+      (runOpenSpecStatus as any).mockClear();
+
+      await service.pollDirectoryGated(cwd);
+      expect(runOpenSpecList).toHaveBeenCalledTimes(1);
+      expect(runOpenSpecStatus).toHaveBeenCalledTimes(1);
+    });
+
+    it("removed change is pruned from cache", async () => {
+      const { runOpenSpecList, runOpenSpecStatus } = await import("@blackbelt-technology/pi-dashboard-shared/openspec-poller.js");
+      (runOpenSpecList as any).mockResolvedValueOnce({ changes: [
+        { name: "change-a", status: "in-progress", completedTasks: 0, totalTasks: 1 },
+        { name: "change-b", status: "in-progress", completedTasks: 0, totalTasks: 1 },
+      ] });
+      (runOpenSpecStatus as any).mockResolvedValue({ artifacts: [], isComplete: false });
+
+      const stateStore = createMockPreferencesStore();
+      const sessionManager = createMockSessionManager();
+      service = createDirectoryService(stateStore, sessionManager);
+      await service.refreshOpenSpec(cwd);
+
+      // Remove change-b and bump top-level mtime.
+      fs.rmSync(path.join(changesDir, "change-b"), { recursive: true });
+      const future = new Date(Date.now() + 20_000);
+      fs.utimesSync(changesDir, future, future);
+      (runOpenSpecList as any).mockResolvedValueOnce({ changes: [
+        { name: "change-a", status: "in-progress", completedTasks: 0, totalTasks: 1 },
+      ] });
+      (runOpenSpecStatus as any).mockClear();
+
+      await service.pollDirectoryGated(cwd);
+      const data = service.getOpenSpecData(cwd);
+      expect(data?.changes).toHaveLength(1);
+      expect(data?.changes[0].name).toBe("change-a");
+    });
+  });
+
+  describe("semaphore + refresh", () => {
+    it("caps concurrent CLI spawns during refresh storms", async () => {
+      const { runOpenSpecList, runOpenSpecStatus } = await import("@blackbelt-technology/pi-dashboard-shared/openspec-poller.js");
+      (runOpenSpecList as any).mockImplementation(async () => ({ changes: [
+        { name: "c1", status: "in-progress", completedTasks: 0, totalTasks: 1 },
+      ] }));
+
+      let active = 0;
+      let peak = 0;
+      (runOpenSpecStatus as any).mockImplementation(async () => {
+        active++;
+        peak = Math.max(peak, active);
+        await new Promise((r) => setTimeout(r, 10));
+        active--;
+        return { artifacts: [], isComplete: false };
+      });
+
+      const stateStore = createMockPreferencesStore();
+      const sessionManager = createMockSessionManager();
+      service = createDirectoryService(stateStore, sessionManager, { maxConcurrentSpawns: 2, changeDetection: "always" });
+
+      // 10 concurrent refreshes across 5 dirs with list returning 1 change each.
+      await Promise.all(Array.from({ length: 10 }, (_, i) => service.refreshOpenSpec(`/project-${i}`)));
+      expect(peak).toBeLessThanOrEqual(2);
+    });
+  });
+
+  describe("jitter", () => {
+    it("produces deterministic per-cwd offsets within jitterSeconds", async () => {
+      const { phaseOffsetMs } = await import("../directory-service.js");
+      const a1 = phaseOffsetMs("/project/a", 5);
+      const a2 = phaseOffsetMs("/project/a", 5);
+      const b = phaseOffsetMs("/project/b", 5);
+      expect(a1).toBe(a2);          // stable
+      expect(a1).toBeLessThan(5000);
+      expect(a1).toBeGreaterThanOrEqual(0);
+      expect(b).toBeLessThan(5000);
+    });
+
+    it("returns 0 when jitterSeconds is 0", async () => {
+      const { phaseOffsetMs } = await import("../directory-service.js");
+      expect(phaseOffsetMs("/any", 0)).toBe(0);
+    });
+  });
+
+  describe("reconfigurePolling", () => {
+    it("accepts a new interval without losing cached data", async () => {
+      const { runOpenSpecList, runOpenSpecStatus } = await import("@blackbelt-technology/pi-dashboard-shared/openspec-poller.js");
+      (runOpenSpecList as any).mockResolvedValue({ changes: [] });
+      (runOpenSpecStatus as any).mockResolvedValue(null);
+
+      const stateStore = createMockPreferencesStore();
+      const sessionManager = createMockSessionManager();
+      service = createDirectoryService(stateStore, sessionManager);
+      await service.refreshOpenSpec("/x");
+      service.reconfigurePolling({ pollIntervalSeconds: 60, maxConcurrentSpawns: 5, changeDetection: "mtime", jitterSeconds: 0 });
+      expect(service.getOpenSpecData("/x")).toBeDefined();
+    });
+  });
 });

package/packages/server/src/__tests__/editor-manager-pid-registry.test.ts

@@ -0,0 +1,168 @@
+/**
+ * Integration test: verify pidRegistry.register/remove fires during an
+ * actual EditorManager start()/stop() cycle.
+ *
+ * Stubs `node:child_process#spawn` to return a fake ChildProcess that binds
+ * a real TCP listener on the port parsed from --bind-addr. This lets the
+ * real `waitForPort` resolve true, so the production start() code path
+ * (including the pidRegistry.register call with child.pid) executes as in prod.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { EventEmitter } from "node:events";
+import { createServer as createNetServer, type Server as NetServer } from "node:net";
+import type { EditorConfig } from "@blackbelt-technology/pi-dashboard-shared/config.js";
+import type { EditorDetectionResult } from "@blackbelt-technology/pi-dashboard-shared/editor-types.js";
+
+// Track every fake child spawned so we can tear them down.
+const spawnedChildren: FakeChild[] = [];
+
+class FakeChild extends EventEmitter {
+  pid: number;
+  killed = false;
+  private server: NetServer | null = null;
+
+  constructor(port: number) {
+    super();
+    // Use a fake but plausible PID; real PID would be this process's tree.
+    // Using Math.random keeps tests from colliding.
+    this.pid = 100000 + Math.floor(Math.random() * 900000);
+
+    // Bind a TCP listener on the requested port so waitForPort's probe
+    // succeeds. This is the key trick that lets the real start() path run.
+    this.server = createNetServer();
+    this.server.listen(port, "127.0.0.1");
+  }
+
+  kill(_signal?: NodeJS.Signals): boolean {
+    if (this.killed) return false;
+    this.killed = true;
+    if (this.server) {
+      this.server.close();
+      this.server = null;
+    }
+    // Emit exit asynchronously, like the real ChildProcess.
+    setImmediate(() => this.emit("exit", 0, null));
+    return true;
+  }
+}
+
+vi.mock("node:child_process", async (importOriginal) => {
+  const real = await importOriginal<typeof import("node:child_process")>();
+  return {
+    ...real,
+    spawn: (_cmd: string, args: readonly string[] = []) => {
+      // Parse --bind-addr 127.0.0.1:<port>
+      const idx = args.indexOf("--bind-addr");
+      const bind = idx >= 0 ? args[idx + 1] : "";
+      const port = Number(bind.split(":")[1] ?? 0);
+      const child = new FakeChild(port);
+      spawnedChildren.push(child);
+      return child as unknown as import("node:child_process").ChildProcess;
+    },
+  };
+});
+
+// IMPORTANT: import AFTER vi.mock so the mocked child_process is picked up.
+const { createEditorManager } = await import("../editor-manager.js");
+
+const DEFAULT_CONFIG: EditorConfig = { idleTimeoutMinutes: 10, maxInstances: 3 };
+const DETECTED: EditorDetectionResult = { available: true, binary: "/fake/code-server" };
+
+function makeRegistryStub() {
+  const calls: Array<{ op: "register" | "remove"; payload: unknown }> = [];
+  return {
+    calls,
+    register: vi.fn((entry: unknown) => { calls.push({ op: "register", payload: entry }); }),
+    remove: vi.fn((id: unknown) => { calls.push({ op: "remove", payload: id }); }),
+    size: () => 0,
+    cleanupOrphans: async () => {},
+  };
+}
+
+describe("EditorManager + pidRegistry integration", () => {
+  beforeEach(() => {
+    spawnedChildren.length = 0;
+  });
+
+  afterEach(() => {
+    // Ensure any dangling fake children release their TCP servers.
+    for (const c of spawnedChildren) {
+      if (!c.killed) c.kill("SIGTERM");
+    }
+  });
+
+  it("calls pidRegistry.register after start() resolves to ready", async () => {
+    const registry = makeRegistryStub();
+    const mgr = createEditorManager({
+      config: DEFAULT_CONFIG,
+      detection: DETECTED,
+      pidRegistry: registry,
+    });
+    const info = await mgr.start("/tmp/fake-project-a");
+    expect(info.status).toBe("ready");
+    expect(registry.register).toHaveBeenCalledTimes(1);
+    const payload = (registry.register.mock.calls[0][0] ?? {}) as Record<string, unknown>;
+    expect(payload.id).toBe(info.id);
+    expect(payload.cwd).toBe("/tmp/fake-project-a");
+    expect(payload.port).toBe(info.port);
+    expect(typeof payload.pid).toBe("number");
+    expect(typeof payload.dataDir).toBe("string");
+    mgr.stop(info.id);
+  });
+
+  it("calls pidRegistry.remove when stop(id) is invoked", async () => {
+    const registry = makeRegistryStub();
+    const mgr = createEditorManager({
+      config: DEFAULT_CONFIG,
+      detection: DETECTED,
+      pidRegistry: registry,
+    });
+    const info = await mgr.start("/tmp/fake-project-b");
+    registry.remove.mockClear();
+    mgr.stop(info.id);
+    // stop() calls remove() synchronously BEFORE SIGTERM.
+    expect(registry.remove).toHaveBeenCalledWith(info.id);
+  });
+
+  it("calls pidRegistry.remove when the child emits exit", async () => {
+    const registry = makeRegistryStub();
+    const mgr = createEditorManager({
+      config: DEFAULT_CONFIG,
+      detection: DETECTED,
+      pidRegistry: registry,
+    });
+    const info = await mgr.start("/tmp/fake-project-c");
+    registry.remove.mockClear();
+    // Simulate the child exiting on its own (e.g., crashed, not via stop()).
+    const child = spawnedChildren[spawnedChildren.length - 1];
+    child.kill("SIGTERM");
+    // exit is emitted on next tick
+    await new Promise((r) => setImmediate(r));
+    await new Promise((r) => setImmediate(r));
+    // Either stop() or the exit handler may call remove — both are fine.
+    expect(registry.remove).toHaveBeenCalledWith(info.id);
+  });
+
+  it("does not call pidRegistry.register if spawn fails (no detection)", async () => {
+    const registry = makeRegistryStub();
+    const mgr = createEditorManager({
+      config: DEFAULT_CONFIG,
+      detection: { available: false },
+      allowRedetection: false,
+      pidRegistry: registry,
+    });
+    await expect(mgr.start("/tmp/fake-project-d")).rejects.toThrow("binary_not_found");
+    expect(registry.register).not.toHaveBeenCalled();
+  });
+
+  it("operates normally when pidRegistry is undefined (back-compat)", async () => {
+    const mgr = createEditorManager({
+      config: DEFAULT_CONFIG,
+      detection: DETECTED,
+      // no pidRegistry
+    });
+    const info = await mgr.start("/tmp/fake-project-e");
+    expect(info.status).toBe("ready");
+    expect(() => mgr.stop(info.id)).not.toThrow();
+  });
+});

package/packages/server/src/__tests__/editor-manager.test.ts

@@ -58,6 +58,39 @@ describe("createEditorManager", () => {
     await expect(mgr.start("/tmp/test")).rejects.toThrow("max_instances_reached");
   });
 
+  it("accepts an injected pidRegistry without affecting back-compat behavior", () => {
+    const calls: string[] = [];
+    const stubRegistry = {
+      register: () => calls.push("register"),
+      remove: () => calls.push("remove"),
+      size: () => 0,
+      cleanupOrphans: async () => {},
+    };
+    const mgr = createEditorManager({ config: DEFAULT_CONFIG, detection: DETECTED, pidRegistry: stubRegistry });
+    expect(mgr.list()).toEqual([]);
+    // stop on unknown id is a no-op and must not call registry.remove
+    expect(() => mgr.stop("nonexistent")).not.toThrow();
+    expect(calls).toEqual([]);
+  });
+
+  it("start failure path does not call pidRegistry.register", async () => {
+    const calls: string[] = [];
+    const stubRegistry = {
+      register: () => calls.push("register"),
+      remove: () => calls.push("remove"),
+      size: () => 0,
+      cleanupOrphans: async () => {},
+    };
+    const mgr = createEditorManager({
+      config: DEFAULT_CONFIG,
+      detection: NOT_DETECTED,
+      allowRedetection: false,
+      pidRegistry: stubRegistry,
+    });
+    await expect(mgr.start("/tmp/test")).rejects.toThrow("binary_not_found");
+    expect(calls).toEqual([]);
+  });
+
   it("calls onStatusChange callback", async () => {
     const statusChanges: Array<{ cwd: string; id: string; status: string }> = [];
     const mgr = createEditorManager({