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

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

@@ -0,0 +1,191 @@
+import { describe, it, expect } from "vitest";
+import { mkdtempSync, mkdirSync, readFileSync, existsSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import os from "node:os";
+import path from "node:path";
+import {
+  createEditorPidRegistry,
+  isDashboardOwnedCodeServer,
+  type PersistedEditorEntry,
+} from "../editor-pid-registry.js";
+
+function tempPidFile(): string {
+  const dir = mkdtempSync(join(tmpdir(), "editor-pid-reg-"));
+  return join(dir, "editor-pids.json");
+}
+
+function readEntries(file: string): PersistedEditorEntry[] {
+  if (!existsSync(file)) return [];
+  return JSON.parse(readFileSync(file, "utf-8")).entries ?? [];
+}
+
+const VALID_CMDLINE = `/usr/local/bin/code-server --auth none --bind-addr 127.0.0.1:63584 --user-data-dir ${path.join(os.homedir(), ".pi", "dashboard", "editors", "abc123def456")} /Users/me/project`;
+
+const UNRELATED_CMDLINE = "/usr/local/bin/code-server --user-data-dir /Users/me/.config/Code";
+
+describe("isDashboardOwnedCodeServer", () => {
+  it("returns true for a dashboard-owned code-server cmdline", () => {
+    expect(isDashboardOwnedCodeServer(VALID_CMDLINE)).toBe(true);
+  });
+
+  it("returns false for an unrelated code-server", () => {
+    expect(isDashboardOwnedCodeServer(UNRELATED_CMDLINE)).toBe(false);
+  });
+
+  it("returns false for null cmdline", () => {
+    expect(isDashboardOwnedCodeServer(null)).toBe(false);
+  });
+
+  it("returns false when --user-data-dir is missing", () => {
+    expect(isDashboardOwnedCodeServer("/usr/local/bin/code-server --bind-addr 127.0.0.1:1234")).toBe(false);
+  });
+});
+
+describe("createEditorPidRegistry — register/remove/persist", () => {
+  it("register writes an entry to the JSON file", () => {
+    const file = tempPidFile();
+    const reg = createEditorPidRegistry({ pidFilePath: file });
+    reg.register({ id: "editor-aaa", pid: 5961, port: 63584, cwd: "/projects/app", dataDir: "/data" });
+    expect(reg.size()).toBe(1);
+    const entries = readEntries(file);
+    expect(entries).toHaveLength(1);
+    expect(entries[0]).toMatchObject({ id: "editor-aaa", pid: 5961, port: 63584, cwd: "/projects/app", dataDir: "/data" });
+    expect(entries[0].spawnedAt).toBeDefined();
+  });
+
+  it("remove deletes the entry from the JSON file", () => {
+    const file = tempPidFile();
+    const reg = createEditorPidRegistry({ pidFilePath: file });
+    reg.register({ id: "editor-aaa", pid: 1, port: 1, cwd: "/a", dataDir: "/d" });
+    reg.register({ id: "editor-bbb", pid: 2, port: 2, cwd: "/b", dataDir: "/d2" });
+    reg.remove("editor-aaa");
+    expect(reg.size()).toBe(1);
+    const entries = readEntries(file);
+    expect(entries).toHaveLength(1);
+    expect(entries[0].id).toBe("editor-bbb");
+  });
+
+  it("persistence write failure does not throw from register", () => {
+    // Portable way to force writeJsonFile to fail: make the target path a
+    // directory so fs.writeFileSync (to path + ".tmp") succeeds but rename()
+    // onto a directory fails with EISDIR/EPERM on every platform.
+    const file = tempPidFile();
+    mkdirSync(file, { recursive: true }); // target exists as a directory
+    const reg = createEditorPidRegistry({ pidFilePath: file });
+    expect(() => reg.register({ id: "editor-aaa", pid: 1, port: 1, cwd: "/a", dataDir: "/d" })).not.toThrow();
+    // In-memory entry still tracked even when disk write failed.
+    expect(reg.size()).toBe(1);
+  });
+});
+
+describe("createEditorPidRegistry — cleanupOrphans", () => {
+  it("returns without throwing when file does not exist", async () => {
+    const file = join(mkdtempSync(join(tmpdir(), "missing-")), "nope.json");
+    const reg = createEditorPidRegistry({ pidFilePath: file });
+    await expect(reg.cleanupOrphans()).resolves.toBeUndefined();
+  });
+
+  it("returns without throwing when file is corrupt", async () => {
+    const file = tempPidFile();
+    writeFileSync(file, "{not json");
+    const reg = createEditorPidRegistry({ pidFilePath: file });
+    await expect(reg.cleanupOrphans()).resolves.toBeUndefined();
+  });
+
+  it("skips dead PIDs", async () => {
+    const file = tempPidFile();
+    writeFileSync(file, JSON.stringify({
+      entries: [{ id: "editor-x", pid: 999999, port: 1, cwd: "/a", dataDir: "/d", spawnedAt: new Date().toISOString() }],
+    }));
+    const killed: Array<{ pid: number; sig: string }> = [];
+    const reg = createEditorPidRegistry({
+      pidFilePath: file,
+      isProcessAlive: () => false,
+      getCmdline: () => VALID_CMDLINE,
+      kill: (pid, sig) => { killed.push({ pid, sig }); return true; },
+      graceMs: 1,
+    });
+    await reg.cleanupOrphans();
+    expect(killed).toEqual([]);
+  });
+
+  it("does NOT signal a live PID whose cmdline doesn't match (PID reuse)", async () => {
+    const file = tempPidFile();
+    writeFileSync(file, JSON.stringify({
+      entries: [{ id: "editor-x", pid: 1234, port: 1, cwd: "/a", dataDir: "/d", spawnedAt: new Date().toISOString() }],
+    }));
+    const killed: Array<{ pid: number; sig: string }> = [];
+    const reg = createEditorPidRegistry({
+      pidFilePath: file,
+      isProcessAlive: () => true,
+      getCmdline: () => UNRELATED_CMDLINE,
+      kill: (pid, sig) => { killed.push({ pid, sig }); return true; },
+      graceMs: 1,
+    });
+    await reg.cleanupOrphans();
+    expect(killed).toEqual([]);
+  });
+
+  it("does NOT signal when cmdline lookup fails (cannot verify)", async () => {
+    const file = tempPidFile();
+    writeFileSync(file, JSON.stringify({
+      entries: [{ id: "editor-x", pid: 1234, port: 1, cwd: "/a", dataDir: "/d", spawnedAt: new Date().toISOString() }],
+    }));
+    const killed: Array<{ pid: number; sig: string }> = [];
+    const reg = createEditorPidRegistry({
+      pidFilePath: file,
+      isProcessAlive: () => true,
+      getCmdline: () => null,
+      kill: (pid, sig) => { killed.push({ pid, sig }); return true; },
+      graceMs: 1,
+    });
+    await reg.cleanupOrphans();
+    expect(killed).toEqual([]);
+  });
+
+  it("SIGTERMs verified live orphans then SIGKILLs survivors", async () => {
+    const file = tempPidFile();
+    writeFileSync(file, JSON.stringify({
+      entries: [
+        { id: "editor-x", pid: 5961, port: 63584, cwd: "/a", dataDir: "/d1", spawnedAt: new Date().toISOString() },
+        { id: "editor-y", pid: 5962, port: 63585, cwd: "/b", dataDir: "/d2", spawnedAt: new Date().toISOString() },
+      ],
+    }));
+    const killed: Array<{ pid: number; sig: string }> = [];
+    // First call: alive. After SIGTERM grace, simulate that 5961 died, 5962 survived.
+    let phase: "before" | "after" = "before";
+    const reg = createEditorPidRegistry({
+      pidFilePath: file,
+      isProcessAlive: (pid) => phase === "before" ? true : pid === 5962,
+      getCmdline: () => VALID_CMDLINE,
+      kill: (pid, sig) => { killed.push({ pid, sig }); return true; },
+      graceMs: 1,
+    });
+    // Toggle phase right after SIGTERMs are sent.
+    const origSetTimeout = setTimeout;
+    const promise = reg.cleanupOrphans();
+    // microtask flip
+    queueMicrotask(() => { phase = "after"; });
+    await promise;
+
+    expect(killed.filter((k) => k.sig === "SIGTERM").map((k) => k.pid).sort()).toEqual([5961, 5962]);
+    expect(killed.filter((k) => k.sig === "SIGKILL").map((k) => k.pid)).toEqual([5962]);
+  });
+
+  it("rewrites the registry file empty after sweep", async () => {
+    const file = tempPidFile();
+    writeFileSync(file, JSON.stringify({
+      entries: [{ id: "editor-x", pid: 5961, port: 1, cwd: "/a", dataDir: "/d", spawnedAt: new Date().toISOString() }],
+    }));
+    const reg = createEditorPidRegistry({
+      pidFilePath: file,
+      isProcessAlive: () => true,
+      getCmdline: () => VALID_CMDLINE,
+      kill: () => true,
+      graceMs: 1,
+    });
+    await reg.cleanupOrphans();
+    expect(readEntries(file)).toEqual([]);
+  });
+});

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

@@ -1,12 +1,18 @@
 import { describe, it, expect, vi, beforeEach } from "vitest";
 
-const { mockedExecSync } = vi.hoisted(() => ({
+const { mockedExecSync, mockedSpawnSync } = vi.hoisted(() => ({
   mockedExecSync: vi.fn(),
+  mockedSpawnSync: vi.fn(),
 }));
 
+// platform/process.ts and platform/tools.ts now use spawnSync via whereAllLines
+// and isProcessRunning; both must be mocked to exercise the detection path in
+// isolation. Default return is status:1 (not found) so each test explicitly
+// overrides what it needs.
 vi.mock("node:child_process", () => ({
-  default: { execSync: mockedExecSync },
+  default: { execSync: mockedExecSync, spawnSync: mockedSpawnSync },
   execSync: mockedExecSync,
+  spawnSync: mockedSpawnSync,
 }));
 
 import { detectEditors, isProcessRunning, isProcessRunningWin32, EDITORS, type DetectedEditor } from "../editor-registry.js";
@@ -14,6 +20,9 @@ import { detectEditors, isProcessRunning, isProcessRunningWin32, EDITORS, type D
 describe("editor-registry", () => {
   beforeEach(() => {
     vi.resetAllMocks();
+    // Default: spawnSync reports not-found so any un-overridden test still
+    // sees clean state rather than stale returns from previous tests.
+    mockedSpawnSync.mockReturnValue({ status: 1, stdout: "", stderr: "" });
   });
 
   describe("EDITORS", () => {
@@ -74,19 +83,22 @@ describe("editor-registry", () => {
 
   describe("detectEditors", () => {
     it("should return editor when process is running AND CLI is available", () => {
+      // platform/process.ts isProcessRunning uses execSync (pgrep) internally.
       mockedExecSync.mockImplementation((cmd) => {
         const s = String(cmd);
         if (s.includes("pgrep")) {
-          // Only Zed is running
-          if (s.includes("Zed")) return Buffer.from("12345\n");
-          throw new Error("not found");
-        }
-        if (s.includes("which")) {
-          if (s.includes("zed")) return Buffer.from("/usr/local/bin/zed\n");
+          if (s.includes("Zed") || s.includes("zed")) return Buffer.from("12345\n");
           throw new Error("not found");
         }
         throw new Error("unexpected command");
       });
+      // ToolResolver.which uses spawnSync for `which`/`where` lookup.
+      mockedSpawnSync.mockImplementation((cmd, args) => {
+        if ((cmd === "which" || cmd === "where") && args?.[0] === "zed") {
+          return { status: 0, stdout: "/usr/local/bin/zed\n", stderr: "" };
+        }
+        return { status: 1, stdout: "", stderr: "" };
+      });
 
       const result = detectEditors("/some/project");
       expect(result).toEqual([{ id: "zed", name: "Zed" }]);
@@ -96,9 +108,9 @@ describe("editor-registry", () => {
       mockedExecSync.mockImplementation((cmd) => {
         const s = String(cmd);
         if (s.includes("pgrep")) throw new Error("not found");
-        if (s.includes("which")) return Buffer.from("/usr/local/bin/zed\n");
         throw new Error("unexpected command");
       });
+      mockedSpawnSync.mockImplementation(() => ({ status: 0, stdout: "/usr/local/bin/zed\n", stderr: "" }));
 
       const result = detectEditors("/some/project");
       expect(result).toEqual([]);
@@ -108,9 +120,9 @@ describe("editor-registry", () => {
       mockedExecSync.mockImplementation((cmd) => {
         const s = String(cmd);
         if (s.includes("pgrep")) return Buffer.from("12345\n");
-        if (s.includes("which")) throw new Error("not found");
         throw new Error("unexpected command");
       });
+      mockedSpawnSync.mockReturnValue({ status: 1, stdout: "", stderr: "" });
 
       const result = detectEditors("/some/project");
       expect(result).toEqual([]);
@@ -124,13 +136,15 @@ describe("editor-registry", () => {
           if (s.includes("Visual Studio Code") || s.includes("code")) return Buffer.from("67890\n");
           throw new Error("not found");
         }
-        if (s.includes("which")) {
-          if (s.includes("zed")) return Buffer.from("/usr/local/bin/zed\n");
-          if (s.includes("code")) return Buffer.from("/usr/local/bin/code\n");
-          throw new Error("not found");
-        }
         throw new Error("unexpected command");
       });
+      mockedSpawnSync.mockImplementation((cmd, args) => {
+        if (cmd === "which" || cmd === "where") {
+          if (args?.[0] === "zed") return { status: 0, stdout: "/usr/local/bin/zed\n", stderr: "" };
+          if (args?.[0] === "code") return { status: 0, stdout: "/usr/local/bin/code\n", stderr: "" };
+        }
+        return { status: 1, stdout: "", stderr: "" };
+      });
 
       const result = detectEditors("/some/project");
       expect(result).toEqual([

package/packages/server/src/__tests__/extension-register-appimage.test.ts

@@ -30,7 +30,11 @@ describe("findBundledExtension - AppImage guard", () => {
   });
 
   it("returns null when extension does not exist", () => {
-    expect(findBundledExtension(tmpDir)).toBeNull();
+    // Disable Strategy 2 (node-resolver fallback) so this test exercises
+    // the AppImage guard path in isolation.
+    expect(
+      findBundledExtension(tmpDir, { resolvePackage: () => null }),
+    ).toBeNull();
   });
 
   // Note: We can't easily test the /tmp/.mount_ guard with real paths

package/packages/server/src/__tests__/extension-register.test.ts

@@ -26,7 +26,9 @@ describe("bridge extension registration (server context)", () => {
   });
 
   it("findBundledExtension returns null when extension dir does not exist", () => {
-    const result = findBundledExtension(tmpDir);
+    // Strategy 2 (require.resolve) would find the monorepo extension;
+    // disable it for this test so we exercise Strategy 1 in isolation.
+    const result = findBundledExtension(tmpDir, { resolvePackage: () => null });
     expect(result).toBeNull();
   });
 

package/packages/server/src/__tests__/find-port-holders.test.ts

@@ -0,0 +1,94 @@
+/**
+ * Tests for cross-platform port-holder detection.
+ * See change: fix-windows-server-parity.
+ */
+import { describe, it, expect, vi } from "vitest";
+import { findPortHolders, parseNetstatListeners } from "../cli.js";
+
+describe("parseNetstatListeners", () => {
+  const selfPid = 99999;
+
+  it("parses Windows netstat -ano output for a listening PID", () => {
+    const output = [
+      "Active Connections",
+      "",
+      "  Proto  Local Address          Foreign Address        State           PID",
+      "  TCP    0.0.0.0:8000           0.0.0.0:0              LISTENING       12345",
+      "  TCP    0.0.0.0:445            0.0.0.0:0              LISTENING       4",
+      "  TCP    127.0.0.1:8000         127.0.0.1:54321        ESTABLISHED     23456",
+    ].join("\r\n");
+
+    expect(parseNetstatListeners(output, 8000, selfPid)).toEqual([12345]);
+  });
+
+  it("excludes non-LISTENING rows (ESTABLISHED, TIME_WAIT)", () => {
+    const output = [
+      "  TCP    0.0.0.0:9999           0.0.0.0:0              ESTABLISHED     11111",
+      "  TCP    0.0.0.0:9999           0.0.0.0:0              TIME_WAIT       22222",
+    ].join("\n");
+    expect(parseNetstatListeners(output, 9999, selfPid)).toEqual([]);
+  });
+
+  it("excludes the current process PID", () => {
+    const output = `  TCP    0.0.0.0:8000           0.0.0.0:0              LISTENING       ${selfPid}`;
+    expect(parseNetstatListeners(output, 8000, selfPid)).toEqual([]);
+  });
+
+  it("only matches the requested port (suffix-based)", () => {
+    const output = [
+      "  TCP    0.0.0.0:8000           0.0.0.0:0              LISTENING       1111",
+      "  TCP    0.0.0.0:18000          0.0.0.0:0              LISTENING       2222",
+      "  TCP    0.0.0.0:80             0.0.0.0:0              LISTENING       3333",
+    ].join("\n");
+    expect(parseNetstatListeners(output, 8000, selfPid).sort()).toEqual([1111]);
+  });
+
+  it("returns empty array for empty or garbage input", () => {
+    expect(parseNetstatListeners("", 8000, selfPid)).toEqual([]);
+    expect(parseNetstatListeners("not a netstat output\nblah", 8000, selfPid)).toEqual([]);
+  });
+
+  it("handles IPv6 listening addresses", () => {
+    const output = "  TCP    [::]:8000              [::]:0                 LISTENING       7777";
+    expect(parseNetstatListeners(output, 8000, selfPid)).toEqual([7777]);
+  });
+});
+
+describe("findPortHolders", () => {
+  it("uses netstat on Windows (via injected exec)", () => {
+    const originalPlatform = process.platform;
+    Object.defineProperty(process, "platform", { value: "win32", configurable: true });
+    try {
+      const exec = vi.fn().mockReturnValue(
+        "  TCP    0.0.0.0:8000           0.0.0.0:0              LISTENING       12345\n",
+      );
+      const result = findPortHolders(8000, exec as any);
+      expect(exec).toHaveBeenCalledTimes(1);
+      expect(exec.mock.calls[0][0]).toMatch(/netstat/i);
+      expect(exec.mock.calls[0][0]).not.toMatch(/lsof/i);
+      expect(result).toEqual([12345]);
+    } finally {
+      Object.defineProperty(process, "platform", { value: originalPlatform, configurable: true });
+    }
+  });
+
+  it("uses lsof on Unix (via injected exec)", () => {
+    const originalPlatform = process.platform;
+    Object.defineProperty(process, "platform", { value: "linux", configurable: true });
+    try {
+      const exec = vi.fn().mockReturnValue("12345\n67890\n");
+      const result = findPortHolders(8000, exec as any);
+      expect(exec).toHaveBeenCalledTimes(1);
+      expect(exec.mock.calls[0][0]).toMatch(/lsof/);
+      expect(exec.mock.calls[0][0]).toContain(":8000");
+      expect(result.sort()).toEqual([12345, 67890].sort());
+    } finally {
+      Object.defineProperty(process, "platform", { value: originalPlatform, configurable: true });
+    }
+  });
+
+  it("returns empty array on exec failure (best-effort)", () => {
+    const exec = vi.fn().mockImplementation(() => { throw new Error("boom"); });
+    expect(findPortHolders(8000, exec as any)).toEqual([]);
+  });
+});

package/packages/server/src/__tests__/fix-pty-permissions.test.ts

@@ -0,0 +1,59 @@
+/**
+ * Regression test for the postinstall `fix-pty-permissions.cjs` script.
+ *
+ * Ensures that after `npm install` the native `spawn-helper` binary in the
+ * current platform's `node-pty` prebuild directory has at least one execute
+ * bit set. Without this, `pty.spawn(...)` fails with "posix_spawnp failed."
+ * and the dashboard's "New Terminal" button appears dead.
+ */
+import { describe, it, expect } from "vitest";
+import { existsSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { createRequire } from "node:module";
+
+describe("fix-pty-permissions", () => {
+  it.skipIf(process.platform === "win32")(
+    "spawn-helper for current platform is executable",
+    () => {
+      const require = createRequire(import.meta.url);
+      const ptyPkg = require.resolve("node-pty/package.json");
+      const ptyRoot = dirname(ptyPkg);
+      const platformDir =
+        process.platform === "darwin"
+          ? process.arch === "arm64"
+            ? "darwin-arm64"
+            : "darwin-x64"
+          : process.arch === "arm64"
+          ? "linux-arm64"
+          : "linux-x64";
+
+      // node-pty ships pre-packed binaries under `prebuilds/<platform>-<arch>/`
+      // when the tarball includes a prebuild for the host platform (macOS,
+      // Windows, some Linux builds). Otherwise node-pty's install script
+      // falls back to `node-gyp rebuild`, producing artifacts under
+      // `build/Release/` instead. Accept either location so this test is
+      // stable across local dev (prebuilt) and Linux CI (built from source).
+      const candidates = [
+        join(ptyRoot, "prebuilds", platformDir, "spawn-helper"),
+        join(ptyRoot, "build", "Release", "spawn-helper"),
+      ];
+      const helper = candidates.find((p) => existsSync(p));
+
+      if (!helper) {
+        // No spawn-helper anywhere means node-pty's install step did not
+        // produce the binary on this host (e.g. missing build toolchain).
+        // The fix-permissions script is defensive — it silently skips when
+        // the prebuild dir is absent — so skipping here matches runtime
+        // behavior rather than masking a real regression.
+        console.warn(
+          `[fix-pty-permissions.test] no spawn-helper found at any of: ${candidates.join(", ")} — skipping`,
+        );
+        return;
+      }
+
+      const mode = statSync(helper).mode;
+      // At least one execute bit (owner/group/other) must be set.
+      expect(mode & 0o111).not.toBe(0);
+    },
+  );
+});

package/packages/server/src/__tests__/force-kill-handler.test.ts

@@ -1,9 +1,30 @@
 /**
  * Tests for handleForceKill in session-action-handler.
+ *
+ * Kill-path routing (see change: route-kill-paths-through-platform):
+ * we verify that the handler delegates to the platform `killProcess`
+ * helper rather than calling `process.kill(...)` directly. Cross-OS
+ * behavior of `killProcess` itself is covered in
+ * `packages/shared/src/__tests__/platform-process.test.ts`.
  */
 import { describe, it, expect, vi, beforeEach } from "vitest";
-import { handleForceKill } from "../browser-handlers/session-action-handler.js";
-import type { BrowserHandlerContext } from "../browser-handlers/handler-context.js";
+
+// Spy on the platform module so we can assert the handler routes through it.
+const killProcessSpy = vi.fn(async (_pid: number, _opts?: any) => ({ ok: true, forced: false }));
+const isProcessAliveSpy = vi.fn((_pid: number) => false);
+vi.mock("@blackbelt-technology/pi-dashboard-shared/platform/process.js", async () => {
+  const actual = await vi.importActual<typeof import("@blackbelt-technology/pi-dashboard-shared/platform/process.js")>(
+    "@blackbelt-technology/pi-dashboard-shared/platform/process.js",
+  );
+  return {
+    ...actual,
+    killProcess: (pid: number, opts?: any) => killProcessSpy(pid, opts),
+    isProcessAlive: (pid: number) => isProcessAliveSpy(pid),
+  };
+});
+
+const { handleForceKill } = await import("../browser-handlers/session-action-handler.js");
+type BrowserHandlerContext = import("../browser-handlers/handler-context.js").BrowserHandlerContext;
 
 function createMockContext(sessionOverrides?: Record<string, any>): BrowserHandlerContext & { sent: any[]; broadcasts: any[] } {
   const sent: any[] = [];
@@ -44,7 +65,10 @@ function createMockContext(sessionOverrides?: Record<string, any>): BrowserHandl
 
 describe("handleForceKill", () => {
   beforeEach(() => {
-    vi.restoreAllMocks();
+    killProcessSpy.mockClear();
+    killProcessSpy.mockImplementation(async () => ({ ok: true, forced: false }));
+    isProcessAliveSpy.mockClear();
+    isProcessAliveSpy.mockReturnValue(false);
   });
 
   it("should close bridge WebSocket and mark session ended when no PID", async () => {
@@ -61,19 +85,44 @@ describe("handleForceKill", () => {
     expect(result.message).toContain("no PID");
   });
 
-  it("should send SIGTERM and mark session ended for valid PID", async () => {
-    // Use a PID that doesn't exist so SIGTERM throws
-    const ctx = createMockContext({ pid: 2147483647 });
+  it("should delegate termination to platform killProcess with 2s timeout", async () => {
+    const ctx = createMockContext({ pid: 12345 });
 
     await handleForceKill({ type: "force_kill", sessionId: "sess-1" }, ctx);
 
+    expect(killProcessSpy).toHaveBeenCalledTimes(1);
+    expect(killProcessSpy).toHaveBeenCalledWith(12345, expect.objectContaining({ timeoutMs: 2000 }));
+
     expect(ctx.piGateway.closeSession).toHaveBeenCalledWith("sess-1");
     expect(ctx.sessionManager.update).toHaveBeenCalledWith("sess-1", expect.objectContaining({ status: "ended" }));
-    
+
+    const result = ctx.sent.find((m: any) => m.type === "force_kill_result");
+    expect(result).toBeDefined();
+    expect(result.success).toBe(true);
+  });
+
+  it("should report already-exited when killProcess reports pid not alive", async () => {
+    killProcessSpy.mockResolvedValueOnce({ ok: false, forced: false });
+    const ctx = createMockContext({ pid: 2147483647 });
+
+    await handleForceKill({ type: "force_kill", sessionId: "sess-1" }, ctx);
+
     const result = ctx.sent.find((m: any) => m.type === "force_kill_result");
     expect(result).toBeDefined();
     expect(result.success).toBe(true);
-    expect(result.message).toContain("already exited");
+  });
+
+  it("should not call process.kill directly (must route through platform)", async () => {
+    const processKillSpy = vi.spyOn(process, "kill");
+    const ctx = createMockContext({ pid: 12345 });
+
+    await handleForceKill({ type: "force_kill", sessionId: "sess-1" }, ctx);
+
+    // handleForceKill must NOT invoke process.kill; all termination goes
+    // through killProcess from the platform module.
+    expect(processKillSpy).not.toHaveBeenCalled();
+    expect(killProcessSpy).toHaveBeenCalledOnce();
+    processKillSpy.mockRestore();
   });
 
   it("should broadcast session_updated with ended status", async () => {

package/packages/server/src/__tests__/git-operations.test.ts

@@ -18,7 +18,9 @@ function git(cmd: string, cwd: string) {
 
 function makeRepo(): string {
   const dir = mkdtempSync(join(tmpdir(), "git-ops-test-"));
-  git("init", dir);
+  // Force `main` as the default branch so tests are deterministic regardless
+  // of the host user's `init.defaultBranch` config.
+  git("-c init.defaultBranch=main init", dir);
   git("config user.email test@test.com", dir);
   git("config user.name Test", dir);
   // Initial commit so we have a branch
@@ -122,7 +124,7 @@ describe("git-operations", () => {
         writeFileSync(join(repo, "remote.txt"), "data");
         git("add .", repo);
         git("commit -m remote-only", repo);
-        git("checkout master", repo);
+        git("checkout main", repo);
 
         // Fetch in clone
         git("fetch origin", clone);
@@ -151,7 +153,7 @@ describe("git-operations", () => {
   describe("checkoutBranch", () => {
     it("checks out a local branch on clean repo", () => {
       git("checkout -b feature-x", repo);
-      git("checkout master", repo);
+      git("checkout main", repo);
       const result = checkoutBranch(repo, "feature-x", false);
       expect(result.success).toBe(true);
       const head = execSync("git rev-parse --abbrev-ref HEAD", { cwd: repo, encoding: "utf-8" }).trim();
@@ -160,7 +162,7 @@ describe("git-operations", () => {
 
     it("returns dirty when working tree is dirty and stash=false", () => {
       git("checkout -b feature-y", repo);
-      git("checkout master", repo);
+      git("checkout main", repo);
       writeFileSync(join(repo, "README.md"), "dirty");
       const result = checkoutBranch(repo, "feature-y", false);
       expect(result.success).toBe(false);
@@ -172,7 +174,7 @@ describe("git-operations", () => {
 
     it("stashes and checks out when stash=true", () => {
       git("checkout -b feature-z", repo);
-      git("checkout master", repo);
+      git("checkout main", repo);
       writeFileSync(join(repo, "README.md"), "dirty");
       const result = checkoutBranch(repo, "feature-z", true);
       expect(result.success).toBe(true);
@@ -184,7 +186,7 @@ describe("git-operations", () => {
     });
 
     it("returns success when already on target branch", () => {
-      const result = checkoutBranch(repo, "master", false);
+      const result = checkoutBranch(repo, "main", false);
       expect(result.success).toBe(true);
     });
 
@@ -194,7 +196,7 @@ describe("git-operations", () => {
       writeFileSync(join(repo, "r.txt"), "data");
       git("add .", repo);
       git("commit -m r", repo);
-      git("checkout master", repo);
+      git("checkout main", repo);
 
       const clone = mkdtempSync(join(tmpdir(), "git-ops-clone-"));
       try {