@blackbelt-technology/pi-agent-dashboard 0.2.8 → 0.3.0

package/packages/server/src/__tests__/browse-endpoint.test.ts

@@ -1,25 +1,26 @@
 /**
  * Tests for the browse directory endpoint logic.
  */
-import { describe, it, expect } from "vitest";
-import { listDirectories } from "../browse.js";
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { listDirectories, createDirectory, validateMkdirName } from "../browse.js";
 import path from "node:path";
 import os from "node:os";
 import fs from "node:fs";
+import fsp from "node:fs/promises";
 
 describe("listDirectories", () => {
   it("should return directory entries for a valid path", async () => {
     // Use the project root — known to have subdirectories
-    const projectRoot = path.resolve(import.meta.dirname, "../../..");
+    const projectRoot = path.resolve(import.meta.dirname, "../../../..");
     const result = await listDirectories(projectRoot);
 
     expect(result.current).toBe(projectRoot);
     expect(result.parent).toBe(path.dirname(projectRoot));
     expect(result.entries.length).toBeGreaterThan(0);
 
-    // Should contain known subdirectories
+    // Should contain known subdirectories at the monorepo root
     const names = result.entries.map((e) => e.name);
-    expect(names).toContain("src");
+    expect(names).toContain("packages");
     expect(names).toContain("node_modules");
   });
 
@@ -29,7 +30,7 @@ describe("listDirectories", () => {
   });
 
   it("should return entries sorted alphabetically", async () => {
-    const projectRoot = path.resolve(import.meta.dirname, "../../..");
+    const projectRoot = path.resolve(import.meta.dirname, "../../../..");
     const result = await listDirectories(projectRoot);
     const names = result.entries.map((e) => e.name);
     const sorted = [...names].sort((a, b) => a.localeCompare(b));
@@ -45,7 +46,7 @@ describe("listDirectories", () => {
   });
 
   it("should detect isGit flag for git repos", async () => {
-    const projectRoot = path.resolve(import.meta.dirname, "../../..");
+    const projectRoot = path.resolve(import.meta.dirname, "../../../..");
     const parentDir = path.dirname(projectRoot);
     const result = await listDirectories(parentDir);
 
@@ -57,7 +58,7 @@ describe("listDirectories", () => {
   });
 
   it("should detect isPi flag for pi projects", async () => {
-    const projectRoot = path.resolve(import.meta.dirname, "../../..");
+    const projectRoot = path.resolve(import.meta.dirname, "../../../..");
     const parentDir = path.dirname(projectRoot);
     const result = await listDirectories(parentDir);
 
@@ -86,7 +87,7 @@ describe("listDirectories", () => {
   });
 
   it("should only return directories, not files", async () => {
-    const projectRoot = path.resolve(import.meta.dirname, "../../..");
+    const projectRoot = path.resolve(import.meta.dirname, "../../../..");
     const result = await listDirectories(projectRoot);
     const names = result.entries.map((e) => e.name);
     // package.json is a file, should not appear
@@ -95,10 +96,228 @@ describe("listDirectories", () => {
   });
 
   it("should include full path in each entry", async () => {
-    const projectRoot = path.resolve(import.meta.dirname, "../../..");
+    const projectRoot = path.resolve(import.meta.dirname, "../../../..");
     const result = await listDirectories(projectRoot);
     for (const entry of result.entries) {
       expect(entry.path).toBe(path.join(projectRoot, entry.name));
     }
   });
 });
+
+describe("listDirectories with q filter", () => {
+  let tmp: string;
+
+  beforeEach(async () => {
+    tmp = await fsp.mkdtemp(path.join(os.tmpdir(), "browse-q-"));
+  });
+
+  afterEach(async () => {
+    await fsp.rm(tmp, { recursive: true, force: true });
+  });
+
+  async function makeDirs(names: string[]) {
+    for (const n of names) await fsp.mkdir(path.join(tmp, n));
+  }
+
+  it("treats empty q as no filter", async () => {
+    await makeDirs(["alpha", "beta"]);
+    const r1 = await listDirectories(tmp, "");
+    const r2 = await listDirectories(tmp, "   ");
+    const r3 = await listDirectories(tmp);
+    const names1 = r1.entries.map((e) => e.name);
+    const names2 = r2.entries.map((e) => e.name);
+    const names3 = r3.entries.map((e) => e.name);
+    expect(names1).toEqual(["alpha", "beta"]);
+    expect(names2).toEqual(["alpha", "beta"]);
+    expect(names3).toEqual(["alpha", "beta"]);
+  });
+
+  it("returns non-prefix substring matches", async () => {
+    await makeDirs(["pi-dashboard", "my-dashboard-old", "readme-dir"]);
+    const r = await listDirectories(tmp, "dash");
+    const names = r.entries.map((e) => e.name);
+    expect(names).toContain("pi-dashboard");
+    expect(names).toContain("my-dashboard-old");
+    expect(names).not.toContain("readme-dir");
+  });
+
+  it("ranks by tier: exact, prefix, word-boundary, substring", async () => {
+    await makeDirs(["pi", "pi-core", "my-pi-tools", "epiphany"]);
+    const r = await listDirectories(tmp, "pi");
+    const names = r.entries.map((e) => e.name);
+    expect(names).toEqual(["pi", "pi-core", "my-pi-tools", "epiphany"]);
+  });
+
+  it("sorts alphabetically within the same tier", async () => {
+    await makeDirs(["pi-zeta", "pi-alpha", "pi-mu"]);
+    const r = await listDirectories(tmp, "pi");
+    const names = r.entries.map((e) => e.name);
+    // all prefix-tier → alphabetical
+    expect(names).toEqual(["pi-alpha", "pi-mu", "pi-zeta"]);
+  });
+
+  it("is case-insensitive", async () => {
+    await makeDirs(["Pi-Dashboard", "OtherThing"]);
+    const r = await listDirectories(tmp, "dash");
+    const names = r.entries.map((e) => e.name);
+    expect(names).toContain("Pi-Dashboard");
+    expect(names).not.toContain("OtherThing");
+  });
+
+  it("applies the 200-cap AFTER filtering so late-alphabet matches survive", async () => {
+    // Create 210 dummy dirs that don't match 'pi', plus one that does.
+    // The matching one alphabetically sorts near the end.
+    const dummy: string[] = [];
+    for (let i = 0; i < 210; i++) {
+      dummy.push(`z-${String(i).padStart(3, "0")}-other`);
+    }
+    // 'pi-dashboard' is the only match; sorts after all 'z-*'? No — 'p' < 'z',
+    // so use 'pi-dashboard' which alphabetically precedes them anyway. Use
+    // a different setup: create one matching dir named so alphabetically it
+    // falls past position 200 in the unfiltered list.
+    await makeDirs(dummy);
+    // 'zz-pi-match' will alphabetically be past the 200 'z-*' entries if we
+    // keep them, but since we only have 210 total, let's just make the matcher
+    // something that would be cut without filtering. Easier: 'aa-other' ×210
+    // plus a single 'pi-found'.
+    await fsp.rm(tmp, { recursive: true, force: true });
+    await fsp.mkdir(tmp);
+    const many: string[] = [];
+    for (let i = 0; i < 210; i++) many.push(`aa-${String(i).padStart(3, "0")}`);
+    many.push("pi-found");
+    await makeDirs(many);
+
+    // Without filter: 'pi-found' sorts alphabetically past 210 'aa-*' entries,
+    // so it lands at position 210 — cut by the 200 cap.
+    const unfiltered = await listDirectories(tmp);
+    expect(unfiltered.entries.length).toBe(200);
+    expect(unfiltered.entries.map((e) => e.name)).not.toContain("pi-found");
+
+    // With filter: it should survive because filtering happens first.
+    const filtered = await listDirectories(tmp, "pi");
+    expect(filtered.entries.map((e) => e.name)).toContain("pi-found");
+  });
+});
+
+describe("validateMkdirName", () => {
+  it("accepts normal names", () => {
+    expect(validateMkdirName("foo")).toBeNull();
+    expect(validateMkdirName("foo-bar")).toBeNull();
+    expect(validateMkdirName("foo_bar")).toBeNull();
+    expect(validateMkdirName("foo.bar")).toBeNull();
+    expect(validateMkdirName("foo bar")).toBeNull();
+    expect(validateMkdirName("\u00e9l\u00e9phant")).toBeNull();
+  });
+
+  it("rejects empty / whitespace", () => {
+    expect(validateMkdirName("")).toBe("invalid name");
+    expect(validateMkdirName("   ")).toBe("invalid name");
+    expect(validateMkdirName(" foo")).toBe("invalid name");
+    expect(validateMkdirName("foo ")).toBe("invalid name");
+  });
+
+  it("rejects . and ..", () => {
+    expect(validateMkdirName(".")).toBe("invalid name");
+    expect(validateMkdirName("..")).toBe("invalid name");
+  });
+
+  it("rejects path separators", () => {
+    expect(validateMkdirName("foo/bar")).toBe("invalid name");
+    expect(validateMkdirName("foo\\bar")).toBe("invalid name");
+  });
+
+  it("rejects null byte", () => {
+    expect(validateMkdirName("foo\0bar")).toBe("invalid name");
+  });
+});
+
+describe("createDirectory", () => {
+  let tmp: string;
+
+  beforeEach(async () => {
+    tmp = await fsp.mkdtemp(path.join(os.tmpdir(), "mkdir-"));
+  });
+
+  afterEach(async () => {
+    await fsp.rm(tmp, { recursive: true, force: true });
+  });
+
+  it("creates a new directory and returns its absolute path", async () => {
+    const result = await createDirectory(tmp, "new-thing");
+    expect(result).toBe(path.join(tmp, "new-thing"));
+    const stat = await fsp.stat(result);
+    expect(stat.isDirectory()).toBe(true);
+  });
+
+  it("throws 'already exists' when target already exists", async () => {
+    await fsp.mkdir(path.join(tmp, "dup"));
+    await expect(createDirectory(tmp, "dup")).rejects.toThrow("already exists");
+  });
+
+  it("throws 'parent not found' when parent does not exist", async () => {
+    await expect(createDirectory("/nonexistent/path/really", "x")).rejects.toThrow("parent not found");
+  });
+
+  it("throws 'parent is not a directory' when parent is a file", async () => {
+    const filePath = path.join(tmp, "somefile");
+    await fsp.writeFile(filePath, "hi");
+    await expect(createDirectory(filePath, "x")).rejects.toThrow("parent is not a directory");
+  });
+
+  it("rejects invalid names without touching disk", async () => {
+    await expect(createDirectory(tmp, "foo/bar")).rejects.toThrow("invalid name");
+    await expect(createDirectory(tmp, "..")).rejects.toThrow("invalid name");
+    await expect(createDirectory(tmp, ".")).rejects.toThrow("invalid name");
+    await expect(createDirectory(tmp, "")).rejects.toThrow("invalid name");
+    await expect(createDirectory(tmp, "foo\0bar")).rejects.toThrow("invalid name");
+    const entries = await fsp.readdir(tmp);
+    expect(entries).toEqual([]);
+  });
+});
+
+// ── S1: rankTier word-boundary edge cases ────────────────────
+// rankTier isn't exported; exercise it indirectly via listDirectories.
+describe("listDirectories word-boundary ranking", () => {
+  let tmp: string;
+
+  beforeEach(async () => {
+    tmp = await fsp.mkdtemp(path.join(os.tmpdir(), "browse-wb-"));
+  });
+
+  afterEach(async () => {
+    await fsp.rm(tmp, { recursive: true, force: true });
+  });
+
+  async function makeDirs(names: string[]) {
+    for (const n of names) await fsp.mkdir(path.join(tmp, n));
+  }
+
+  it("treats hyphen, underscore, dot, space as word boundaries", async () => {
+    // All four should rank at tier 2 for query 'foo' (word boundary before 'foo');
+    // 'embeddedfoo' ranks tier 3 (plain substring).
+    await makeDirs([
+      "pi-foo",    // hyphen boundary
+      "pi_foo",    // underscore boundary
+      "pi.foo",    // dot boundary
+      "pi foo",    // space boundary
+      "embeddedfoo", // no boundary
+    ]);
+    const r = await listDirectories(tmp, "foo");
+    const names = r.entries.map((e) => e.name);
+    // The first four are tier 2 (alphabetical within tier); 'embeddedfoo' is tier 3 last.
+    expect(names[names.length - 1]).toBe("embeddedfoo");
+    // All four boundary-matched names appear before embeddedfoo.
+    const boundaryNames = ["pi foo", "pi-foo", "pi.foo", "pi_foo"];
+    const boundaryPositions = boundaryNames.map((n) => names.indexOf(n));
+    for (const p of boundaryPositions) expect(p).toBeGreaterThanOrEqual(0);
+    for (const p of boundaryPositions) expect(p).toBeLessThan(names.indexOf("embeddedfoo"));
+  });
+
+  it("treats start-of-string as a word boundary (prefix trumps via tier 1)", async () => {
+    await makeDirs(["foo-bar", "xx-foo"]);
+    const r = await listDirectories(tmp, "foo");
+    // 'foo-bar' is prefix (tier 1), 'xx-foo' is word-boundary (tier 2).
+    const names = r.entries.map((e) => e.name);
+    expect(names).toEqual(["foo-bar", "xx-foo"]);
+  });
+});

package/packages/server/src/__tests__/browser-gateway-handler-errors.test.ts

@@ -0,0 +1,129 @@
+/**
+ * Regression tests for browser-gateway exception handling.
+ *
+ * - Handler exceptions MUST be logged with a `[browser-gw] handler error`
+ *   prefix and the message type, so real bugs (e.g. node-pty spawn
+ *   failures) are no longer silently swallowed.
+ * - Malformed JSON frames MUST still be silently dropped (no log noise
+ *   for garbage input).
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { EventEmitter } from "node:events";
+import { createBrowserGateway } from "../browser-gateway.js";
+import { createMemorySessionManager } from "../memory-session-manager.js";
+import { createMemoryEventStore } from "../memory-event-store.js";
+import type { TerminalManager } from "../terminal-manager.js";
+import type { PiGateway } from "../pi-gateway.js";
+import type { SessionOrderManager } from "../session-order-manager.js";
+
+function makeFakeWs() {
+  const ws = new EventEmitter() as EventEmitter & {
+    send: ReturnType<typeof vi.fn>;
+    close: ReturnType<typeof vi.fn>;
+    readyState: number;
+    OPEN: number;
+  };
+  ws.send = vi.fn();
+  ws.close = vi.fn();
+  ws.readyState = 1;
+  ws.OPEN = 1;
+  return ws;
+}
+
+function makeStubPiGateway(): PiGateway {
+  return {
+    start: vi.fn(),
+    stop: vi.fn(),
+    sendToSession: vi.fn(),
+    getConnectedSessionIds: vi.fn(() => []),
+    hasSession: vi.fn(() => false),
+    onEvent: vi.fn(),
+  } as unknown as PiGateway;
+}
+
+function makeStubOrderManager(): SessionOrderManager {
+  return {
+    insert: vi.fn(),
+    remove: vi.fn(),
+    getOrder: vi.fn(() => []),
+    reorder: vi.fn(),
+    getAllOrders: vi.fn(() => ({})),
+  } as unknown as SessionOrderManager;
+}
+
+describe("browser-gateway handler error reporting", () => {
+  let errorSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    errorSpy.mockRestore();
+  });
+
+  it("logs handler exceptions with type and error (does not silently swallow)", async () => {
+    const throwingTerminalManager = {
+      spawn: vi.fn(() => {
+        throw new Error("posix_spawnp failed.");
+      }),
+      attach: vi.fn(),
+      detach: vi.fn(),
+      kill: vi.fn(),
+      get: vi.fn(),
+      list: vi.fn(() => []),
+      updateTitle: vi.fn(),
+    } as unknown as TerminalManager;
+
+    const gateway = createBrowserGateway(
+      createMemorySessionManager(),
+      createMemoryEventStore(() => false),
+      makeStubPiGateway(),
+      undefined,
+      undefined,
+      makeStubOrderManager(),
+      undefined,
+      undefined,
+      throwingTerminalManager,
+    );
+
+    const ws = makeFakeWs();
+    gateway.wss.emit("connection", ws, {});
+
+    ws.emit(
+      "message",
+      Buffer.from(JSON.stringify({ type: "create_terminal", cwd: "/tmp" })),
+    );
+    // Allow any microtasks to settle.
+    await new Promise((r) => setImmediate(r));
+
+    const handlerErrorCall = errorSpy.mock.calls.find(
+      (args: unknown[]) =>
+        typeof args[0] === "string" &&
+        args[0].includes("[browser-gw] handler error") &&
+        args[0].includes("type=create_terminal"),
+    );
+    expect(handlerErrorCall, "expected a [browser-gw] handler error log line").toBeTruthy();
+    expect(throwingTerminalManager.spawn).toHaveBeenCalledOnce();
+  });
+
+  it("silently drops malformed JSON frames (no handler-error log)", async () => {
+    const gateway = createBrowserGateway(
+      createMemorySessionManager(),
+      createMemoryEventStore(() => false),
+      makeStubPiGateway(),
+    );
+
+    const ws = makeFakeWs();
+    gateway.wss.emit("connection", ws, {});
+
+    ws.emit("message", Buffer.from("{not json"));
+    await new Promise((r) => setImmediate(r));
+
+    const handlerErrorCall = errorSpy.mock.calls.find(
+      (args: unknown[]) =>
+        typeof args[0] === "string" && args[0].includes("[browser-gw] handler error"),
+    );
+    expect(handlerErrorCall).toBeUndefined();
+  });
+});

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__/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({