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

package/packages/server/src/__tests__/smoke-integration.test.ts

@@ -2,7 +2,8 @@
  * Smoke integration tests — validates end-to-end flows without SQLite.
  */
 import { describe, it, expect, afterAll } from "vitest";
-import { createServer, type DashboardServer, type ServerConfig } from "../server.js";
+import { createTestServer, type TestServerHandle } from "../test-support/test-server.js";
+import type { DashboardServer } from "../server.js";
 import { WebSocket } from "ws";
 
 function waitForOpen(ws: WebSocket): Promise<void> {
@@ -24,22 +25,21 @@ function collectMsgs(ws: WebSocket, ms: number): Promise<any[]> {
 }
 
 const delay = (ms: number) => new Promise((r) => setTimeout(r, ms));
-const httpPort = 19070;
-const piPort = 19071;
+let handle: TestServerHandle;
 let server: DashboardServer;
+let httpPort: number;
+let piPort: number;
 
 describe("Smoke integration", () => {
   afterAll(async () => {
-    if (server) await server.stop();
+    if (handle) await handle.stop();
   });
 
   it("9.2 — events flow and replay from memory on reconnect", async () => {
-    server = await createServer({
-      port: httpPort, piPort, dev: true,
-      autoShutdown: false, shutdownIdleSeconds: 999, tunnel: false,
-    editor: { idleTimeoutMinutes: 10, maxInstances: 3 },
-    });
-    await server.start();
+    handle = await createTestServer();
+    server = handle.server;
+    httpPort = handle.httpPort;
+    piPort = handle.piPort;
 
     // Bridge connects and registers
     const bridge = new WebSocket(`ws://localhost:${piPort}`);

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

@@ -25,6 +25,12 @@ vi.mock("node-pty", () => ({
   })),
 }));
 
+// Mock platform/process.ts killProcess so the Windows path is observable in tests.
+const mockKillProcess = vi.fn((..._args: unknown[]) => Promise.resolve({ ok: true, forced: false }));
+vi.mock("@blackbelt-technology/pi-dashboard-shared/platform/process.js", () => ({
+  killProcess: (...args: unknown[]) => mockKillProcess(...args),
+}));
+
 describe("TerminalManager", () => {
   let manager: TerminalManager;
   let exitCallbacks: Array<(termId: string) => void>;
@@ -112,10 +118,44 @@ describe("TerminalManager", () => {
   });
 
   describe("kill", () => {
-    it("sends SIGHUP to PTY (bash on Linux ignores SIGTERM)", () => {
+    beforeEach(() => {
+      mockKillProcess.mockClear();
+    });
+
+    it("POSIX: sends SIGHUP to PTY (bash on Linux ignores SIGTERM)", () => {
+      if (process.platform === "win32") return; // skipped on Windows; covered below
       const session = manager.spawn("/tmp");
       manager.kill(session.id);
       expect(mockPtyKill).toHaveBeenCalledWith("SIGHUP");
+      expect(mockKillProcess).not.toHaveBeenCalled();
+    });
+
+    it("Windows: routes kill through platform killProcess (tree kill via taskkill /F /T)", () => {
+      if (process.platform !== "win32") return; // skipped off-Windows
+      const session = manager.spawn("C:\\tmp");
+      manager.kill(session.id);
+      // pty.kill MUST NOT be called on Windows — killProcess(pid) does the tree-kill.
+      expect(mockPtyKill).not.toHaveBeenCalled();
+      expect(mockKillProcess).toHaveBeenCalledWith(12345, expect.objectContaining({ timeoutMs: 2000 }));
+    });
+
+    it("fallback cleanup fires if onExit does not within 3 s (simulates Windows ConPTY)", async () => {
+      vi.useFakeTimers();
+      try {
+        const session = manager.spawn("/tmp");
+        let exitCalled = false;
+        manager = createTerminalManager({
+          onExit: () => { exitCalled = true; },
+        });
+        const session2 = manager.spawn("/tmp");
+        manager.kill(session2.id);
+        // Simulate node-pty NOT firing onExit (the actual Windows failure mode).
+        await vi.advanceTimersByTimeAsync(3001);
+        expect(exitCalled).toBe(true);
+        expect(manager.get(session2.id)).toBeUndefined(); // removed from map
+      } finally {
+        vi.useRealTimers();
+      }
     });
 
     it("throws for unknown ID", () => {

package/packages/server/src/__tests__/test-server-canary.test.ts

@@ -0,0 +1,31 @@
+/**
+ * Canary for createTestServer(): verifies that port:0 end-to-end resolution
+ * works and the helper returns non-zero, distinct ports.
+ *
+ * This test exists to de-risk the integration-test migration (tasks 4.x).
+ * If createServer / piGateway ever stop propagating resolved ports, this
+ * fails loudly before the other tests are touched.
+ */
+import { describe, it, expect, afterAll } from "vitest";
+import { createTestServer, type TestServerHandle } from "../test-support/test-server.js";
+
+let handle: TestServerHandle | undefined;
+
+describe("createTestServer (port:0 canary)", () => {
+  afterAll(async () => {
+    if (handle) await handle.stop();
+  });
+
+  it("resolves non-zero distinct ports and answers /api/health", async () => {
+    handle = await createTestServer();
+
+    expect(handle.httpPort).toBeGreaterThan(0);
+    expect(handle.piPort).toBeGreaterThan(0);
+    expect(handle.httpPort).not.toBe(handle.piPort);
+
+    const res = await fetch(`http://localhost:${handle.httpPort}/api/health`);
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.ok).toBe(true);
+  }, 15000);
+});

package/packages/server/src/__tests__/tool-routes.test.ts

@@ -0,0 +1,277 @@
+/**
+ * Tests for /api/tools REST routes.
+ *
+ * Covers: list, get single, rescan (all / one), set override, clear
+ * override, unknown-tool 404, bad-body 400, diagnostics text format.
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import Fastify, { type FastifyInstance } from "fastify";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  ToolRegistry,
+  OverridesStore,
+  registerDefaultTools,
+  type Strategy,
+} from "@blackbelt-technology/pi-dashboard-shared/tool-registry/index.js";
+import { registerToolRoutes, formatDiagnostics } from "../routes/tool-routes.js";
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function noGuard() {
+  return async () => { /* allow all */ };
+}
+
+function tmpOverridesPath(): string {
+  return path.join(
+    os.tmpdir(),
+    `tool-routes-test-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}.json`,
+  );
+}
+
+/**
+ * Build a registry with two fake tools: `pi` (resolves) and `ghost`
+ * (never resolves). The `override` strategy honors ctx.overrides so
+ * set/clear flows are observable.
+ */
+function buildRegistry(opts?: { existsPath?: string }): ToolRegistry {
+  const overrides = new OverridesStore({ filePath: tmpOverridesPath(), warn: () => {} });
+  const r = new ToolRegistry({ overrides, platform: "linux" });
+
+  const piStrategies: Strategy[] = [
+    {
+      name: "override",
+      run: (ctx) => ctx.overrides["pi"]
+        ? { ok: true, path: ctx.overrides["pi"] }
+        : { ok: false, reason: "no override set" },
+    },
+    { name: "where", run: () => ({ ok: true, path: opts?.existsPath ?? "/usr/bin/pi" }) },
+  ];
+  const ghostStrategies: Strategy[] = [
+    { name: "override", run: (ctx) => ctx.overrides["ghost"]
+      ? { ok: true, path: ctx.overrides["ghost"] }
+      : { ok: false, reason: "no override set" } },
+    { name: "where", run: () => ({ ok: false, reason: "not found on PATH" }) },
+  ];
+  r.register({ name: "pi", kind: "binary", strategies: piStrategies });
+  r.register({ name: "ghost", kind: "binary", strategies: ghostStrategies });
+  return r;
+}
+
+function buildServer(registry: ToolRegistry): FastifyInstance {
+  const fastify = Fastify();
+  registerToolRoutes(fastify, { registry, networkGuard: noGuard() });
+  return fastify;
+}
+
+// ── Tests ──────────────────────────────────────────────────────────────────
+
+describe("GET /api/tools", () => {
+  let fastify: FastifyInstance;
+  beforeEach(() => { fastify = buildServer(buildRegistry()); });
+  afterEach(async () => { await fastify.close(); });
+
+  it("returns all registered tools", async () => {
+    const res = await fastify.inject({ method: "GET", url: "/api/tools" });
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(body.success).toBe(true);
+    const names = body.data.tools.map((t: any) => t.name).sort();
+    expect(names).toEqual(["ghost", "pi"]);
+  });
+});
+
+describe("GET /api/tools/:name", () => {
+  let fastify: FastifyInstance;
+  beforeEach(() => { fastify = buildServer(buildRegistry()); });
+  afterEach(async () => { await fastify.close(); });
+
+  it("returns the resolution for a known tool", async () => {
+    const res = await fastify.inject({ method: "GET", url: "/api/tools/pi" });
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(body.data.name).toBe("pi");
+    expect(body.data.ok).toBe(true);
+    expect(body.data.path).toBe("/usr/bin/pi");
+  });
+
+  it("404s for an unregistered tool", async () => {
+    const res = await fastify.inject({ method: "GET", url: "/api/tools/bogus" });
+    expect(res.statusCode).toBe(404);
+    expect(res.json().error).toMatch(/Unknown tool/);
+  });
+});
+
+describe("POST /api/tools/rescan", () => {
+  it("rescan() without body clears all caches", async () => {
+    let calls = 0;
+    const overrides = new OverridesStore({ filePath: tmpOverridesPath(), warn: () => {} });
+    const r = new ToolRegistry({ overrides, platform: "linux" });
+    r.register({
+      name: "pi",
+      kind: "binary",
+      strategies: [{ name: "where", run: () => ({ ok: true, path: `/pi${++calls}` }) }],
+    });
+    const fastify = buildServer(r);
+
+    await fastify.inject({ method: "GET", url: "/api/tools/pi" });
+    expect(r.resolve("pi").path).toBe("/pi1");
+
+    const res = await fastify.inject({ method: "POST", url: "/api/tools/rescan", payload: {} });
+    expect(res.statusCode).toBe(200);
+    expect(res.json().data.tools[0].path).toBe("/pi2");
+    await fastify.close();
+  });
+
+  it("rescan({ name }) only clears that tool's cache", async () => {
+    let piCalls = 0, ghostCalls = 0;
+    const overrides = new OverridesStore({ filePath: tmpOverridesPath(), warn: () => {} });
+    const r = new ToolRegistry({ overrides, platform: "linux" });
+    r.register({
+      name: "pi",
+      kind: "binary",
+      strategies: [{ name: "where", run: () => ({ ok: true, path: `/pi${++piCalls}` }) }],
+    });
+    r.register({
+      name: "ghost",
+      kind: "binary",
+      strategies: [{ name: "where", run: () => ({ ok: true, path: `/ghost${++ghostCalls}` }) }],
+    });
+    const fastify = buildServer(r);
+
+    r.resolve("pi"); r.resolve("ghost");
+    await fastify.inject({
+      method: "POST", url: "/api/tools/rescan", payload: { name: "pi" },
+    });
+    expect(r.resolve("pi").path).toBe("/pi2");
+    expect(r.resolve("ghost").path).toBe("/ghost1"); // unchanged
+    await fastify.close();
+  });
+
+  it("404s when rescanning an unknown name", async () => {
+    const fastify = buildServer(buildRegistry());
+    const res = await fastify.inject({
+      method: "POST", url: "/api/tools/rescan", payload: { name: "bogus" },
+    });
+    expect(res.statusCode).toBe(404);
+    await fastify.close();
+  });
+});
+
+describe("PUT /api/tools/:name (set override)", () => {
+  it("sets the override and returns refreshed Resolution", async () => {
+    const r = buildRegistry();
+    const fastify = buildServer(r);
+
+    const res = await fastify.inject({
+      method: "PUT", url: "/api/tools/pi",
+      payload: { path: "/custom/pi" },
+    });
+    expect(res.statusCode).toBe(200);
+    const body = res.json();
+    expect(body.data.source).toBe("override");
+    expect(body.data.path).toBe("/custom/pi");
+    await fastify.close();
+  });
+
+  it("400s on missing path body", async () => {
+    const fastify = buildServer(buildRegistry());
+    const res = await fastify.inject({
+      method: "PUT", url: "/api/tools/pi", payload: {},
+    });
+    expect(res.statusCode).toBe(400);
+    await fastify.close();
+  });
+
+  it("404s for unknown tool name", async () => {
+    const fastify = buildServer(buildRegistry());
+    const res = await fastify.inject({
+      method: "PUT", url: "/api/tools/bogus", payload: { path: "/x" },
+    });
+    expect(res.statusCode).toBe(404);
+    await fastify.close();
+  });
+});
+
+describe("DELETE /api/tools/:name (clear override)", () => {
+  it("clears the override and returns refreshed Resolution", async () => {
+    const r = buildRegistry();
+    r.setOverride("pi", "/custom/pi");
+    const fastify = buildServer(r);
+
+    const res = await fastify.inject({ method: "DELETE", url: "/api/tools/pi" });
+    expect(res.statusCode).toBe(200);
+    expect(res.json().data.path).toBe("/usr/bin/pi");
+    await fastify.close();
+  });
+
+  it("404s for unknown tool", async () => {
+    const fastify = buildServer(buildRegistry());
+    const res = await fastify.inject({ method: "DELETE", url: "/api/tools/bogus" });
+    expect(res.statusCode).toBe(404);
+    await fastify.close();
+  });
+});
+
+describe("POST /api/tools/diagnostics", () => {
+  it("returns text/plain with per-tool headers and trail lines", async () => {
+    const fastify = buildServer(buildRegistry());
+    const res = await fastify.inject({ method: "POST", url: "/api/tools/diagnostics" });
+    expect(res.statusCode).toBe(200);
+    expect(res.headers["content-type"]).toMatch(/text\/plain/);
+    const body = res.body;
+    // Header line per tool
+    expect(body).toMatch(/^\[ok\] +pi /m);
+    expect(body).toMatch(/^\[miss\] +ghost /m);
+    // Each attempted strategy appears with a leading dash
+    expect(body).toMatch(/- where: ok/);
+    expect(body).toMatch(/- where: not found on PATH/);
+    await fastify.close();
+  });
+
+  it("formatDiagnostics is stable for unit testing", () => {
+    const text = formatDiagnostics([
+      {
+        name: "pi", ok: true, path: "/usr/bin/pi", source: "system",
+        tried: [{ strategy: "where", result: "ok" }],
+        resolvedAt: 0,
+      },
+    ]);
+    expect(text).toMatch(/\[ok\] +pi \(system\) → \/usr\/bin\/pi/);
+    expect(text).toMatch(/- where: ok/);
+  });
+});
+
+describe("integration with default tool definitions", () => {
+  it("the standard registry exposes pi, openspec, git, npm etc. via GET /api/tools", async () => {
+    const overrides = new OverridesStore({ filePath: tmpOverridesPath(), warn: () => {} });
+    const r = new ToolRegistry({ overrides, platform: "linux" });
+    registerDefaultTools(r, {
+      exists: () => false,
+      which: () => null,
+      npmRootGlobal: () => "",
+    });
+    const fastify = buildServer(r);
+
+    const res = await fastify.inject({ method: "GET", url: "/api/tools" });
+    expect(res.statusCode).toBe(200);
+    const names = res.json().data.tools.map((t: any) => t.name).sort();
+    expect(names).toEqual(expect.arrayContaining(["git", "node", "npm", "openspec", "pi", "pi-coding-agent", "zrok"]));
+    expect(names).not.toContain("tsx");
+    expect(names).not.toContain("pi-dashboard");
+    await fastify.close();
+  });
+});
+
+// Clean up tmp overrides files
+afterAll();
+function afterAll() {
+  try {
+    for (const f of fs.readdirSync(os.tmpdir())) {
+      if (f.startsWith("tool-routes-test-")) {
+        try { fs.unlinkSync(path.join(os.tmpdir(), f)); } catch {}
+      }
+    }
+  } catch {}
+}

package/packages/server/src/__tests__/trusted-networks-config.test.ts

@@ -52,6 +52,25 @@ describe("trustedNetworks config", () => {
     expect(config.resolvedTrustedNetworks).toContain("10.0.0.0/8");
   });
 
+  // Companion to the test above. The archived trusted-networks spec scenario
+  // "trustedNetworks merged with auth.bypassHosts" as written did NOT include
+  // a `providers` field; the test above silently adds one to make it pass.
+  // This second test exercises the literal spec scenario — it would have
+  // failed pre-fix (parseAuthConfig nuked the whole auth block when
+  // providers was absent) and demonstrates the scenario as written now holds.
+  // See openspec/changes/fix-trusted-networks-no-oauth.
+  it("should merge trustedNetworks with auth.bypassHosts (no providers configured)", () => {
+    fs.writeFileSync(configFile, JSON.stringify({
+      trustedNetworks: ["192.168.1.0/24"],
+      auth: {
+        bypassHosts: ["10.0.0.0/8"],
+      },
+    }));
+    const config = loadConfig();
+    expect(config.resolvedTrustedNetworks).toContain("192.168.1.0/24");
+    expect(config.resolvedTrustedNetworks).toContain("10.0.0.0/8");
+  });
+
   it("should deduplicate entries", () => {
     fs.writeFileSync(configFile, JSON.stringify({
       trustedNetworks: ["192.168.1.0/24"],

package/packages/server/src/__tests__/trusted-networks-no-oauth-roundtrip.test.ts

@@ -0,0 +1,126 @@
+/**
+ * End-to-end regression test for fix-trusted-networks-no-oauth.
+ *
+ * Round-trips a bypassHosts-only auth config through the full
+ * write → disk → loadConfig → resolvedTrustedNetworks path.
+ *
+ * This is the test that would have caught the bug activated by
+ * eb24780 (consolidate-trusted-networks). The archived tasks.md
+ * section 5.4 claimed this case was "covered by unit test" — but
+ * the cited unit test only checked the React onChange handler's
+ * return value in memory, never writing to disk or reloading.
+ *
+ * This test asserts the end state: after the UI's PUT /api/config
+ * equivalent fires, a subsequent loadConfig() sees the entry in
+ * resolvedTrustedNetworks.
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { writeConfigPartial } from "../config-api.js";
+import { loadConfig } from "@blackbelt-technology/pi-dashboard-shared/config.js";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+describe("fix-trusted-networks-no-oauth: round-trip", () => {
+  let testDir: string;
+  let configFile: string;
+  let origHome: string;
+
+  beforeEach(() => {
+    testDir = path.join(os.tmpdir(), `test-no-oauth-rt-${Date.now()}`);
+    fs.mkdirSync(path.join(testDir, ".pi", "dashboard"), { recursive: true });
+    configFile = path.join(testDir, ".pi", "dashboard", "config.json");
+    origHome = process.env.HOME!;
+    process.env.HOME = testDir;
+  });
+
+  afterEach(() => {
+    process.env.HOME = origHome;
+    if (fs.existsSync(testDir)) fs.rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it("UI add → save → reload → resolvedTrustedNetworks contains entry", () => {
+    // Simulate fresh config (no auth section).
+    fs.writeFileSync(configFile, JSON.stringify({ port: 8000 }));
+
+    // Simulate the UI PUT /api/config from Settings → Security → Add
+    // with no OAuth configured (the case that broke users).
+    const writeResult = writeConfigPartial({
+      auth: { providers: {}, bypassHosts: ["192.168.1.0/24"] },
+    });
+    expect(writeResult.success).toBe(true);
+
+    // Disk assertion — the bypassHosts must actually land on disk.
+    const written = JSON.parse(fs.readFileSync(configFile, "utf-8"));
+    expect(written.auth).toBeDefined();
+    expect(written.auth.bypassHosts).toEqual(["192.168.1.0/24"]);
+
+    // Reload assertion — loadConfig must surface the entry in
+    // resolvedTrustedNetworks, which is what the network guard
+    // and the WS upgrade handler consult.
+    const loaded = loadConfig();
+    expect(loaded.auth).toBeDefined();
+    expect(loaded.auth!.bypassHosts).toEqual(["192.168.1.0/24"]);
+    expect(loaded.resolvedTrustedNetworks).toContain("192.168.1.0/24");
+  });
+
+  it("UI add with existing OAuth → round-trip preserves both", () => {
+    fs.writeFileSync(
+      configFile,
+      JSON.stringify({
+        port: 8000,
+        auth: {
+          secret: "s",
+          providers: { github: { clientId: "abc", clientSecret: "xyz" } },
+        },
+      }),
+    );
+
+    const writeResult = writeConfigPartial({
+      auth: { bypassHosts: ["10.0.0.0/8"] },
+    });
+    expect(writeResult.success).toBe(true);
+
+    const loaded = loadConfig();
+    expect(loaded.auth).toBeDefined();
+    expect(loaded.auth!.providers.github).toBeDefined();
+    expect(loaded.auth!.bypassHosts).toEqual(["10.0.0.0/8"]);
+    expect(loaded.resolvedTrustedNetworks).toContain("10.0.0.0/8");
+  });
+
+  it("UI clear → save → reload → entry gone from resolvedTrustedNetworks", () => {
+    fs.writeFileSync(
+      configFile,
+      JSON.stringify({
+        auth: { providers: {}, bypassHosts: ["192.168.1.0/24"] },
+      }),
+    );
+
+    const writeResult = writeConfigPartial({
+      auth: { bypassHosts: [] },
+    });
+    expect(writeResult.success).toBe(true);
+
+    const loaded = loadConfig();
+    // Loader returns auth === undefined when nothing auth-relevant remains.
+    // Either way, the trusted entry must not survive.
+    expect(loaded.resolvedTrustedNetworks).not.toContain("192.168.1.0/24");
+    expect(loaded.resolvedTrustedNetworks).toEqual([]);
+  });
+
+  it("hand-edited config (no UI write) with bypassHosts only → loads correctly", () => {
+    // This path simulates a user who edited config.json by hand
+    // rather than through the UI. The fix must make loadConfig
+    // honor this shape.
+    fs.writeFileSync(
+      configFile,
+      JSON.stringify({
+        auth: { providers: {}, bypassHosts: ["192.168.0.0/24"] },
+      }),
+    );
+
+    const loaded = loadConfig();
+    expect(loaded.auth).toBeDefined();
+    expect(loaded.resolvedTrustedNetworks).toContain("192.168.0.0/24");
+  });
+});

package/packages/server/src/__tests__/tunnel-cleanup.test.ts

@@ -0,0 +1,90 @@
+/**
+ * Tests that `cleanupStaleZrok` routes liveness + termination through the
+ * shared platform module rather than raw `process.kill`.
+ *
+ * See change: route-kill-paths-through-platform.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const killProcessSpy = vi.fn(async (_pid: number, _opts?: any) => ({ ok: true, forced: false }));
+const isProcessAliveSpy = vi.fn((_pid: number) => true);
+
+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 { cleanupStaleZrok, writeZrokPid, readZrokPid } = await import("../tunnel.js");
+
+function pidFile(): string {
+  return path.join(os.homedir(), ".pi", "dashboard", "zrok.pid");
+}
+
+describe("cleanupStaleZrok uses platform helpers", () => {
+  const original = readZrokPid();
+
+  beforeEach(() => {
+    killProcessSpy.mockClear();
+    killProcessSpy.mockImplementation(async () => ({ ok: true, forced: false }));
+    isProcessAliveSpy.mockClear();
+    isProcessAliveSpy.mockReturnValue(true);
+  });
+
+  afterEach(() => {
+    // Restore prior PID file content if any.
+    try {
+      if (original !== null) writeZrokPid(original);
+      else fs.unlinkSync(pidFile());
+    } catch { /* ignore */ }
+  });
+
+  it("calls platform killProcess when a live stale PID exists", async () => {
+    writeZrokPid(654321);
+    isProcessAliveSpy.mockReturnValue(true);
+
+    await cleanupStaleZrok();
+
+    expect(isProcessAliveSpy).toHaveBeenCalledWith(654321);
+    expect(killProcessSpy).toHaveBeenCalledOnce();
+    expect(killProcessSpy).toHaveBeenCalledWith(654321, expect.any(Object));
+    // PID file removed after cleanup
+    expect(readZrokPid()).toBeNull();
+  });
+
+  it("skips killProcess when PID is already dead but still removes PID file", async () => {
+    writeZrokPid(654322);
+    isProcessAliveSpy.mockReturnValue(false);
+
+    await cleanupStaleZrok();
+
+    expect(killProcessSpy).not.toHaveBeenCalled();
+    expect(readZrokPid()).toBeNull();
+  });
+
+  it("no-ops when no PID file exists", async () => {
+    try { fs.unlinkSync(pidFile()); } catch { /* ignore */ }
+    await cleanupStaleZrok();
+    expect(killProcessSpy).not.toHaveBeenCalled();
+    expect(isProcessAliveSpy).not.toHaveBeenCalled();
+  });
+
+  it("does not invoke process.kill directly", async () => {
+    writeZrokPid(654323);
+    isProcessAliveSpy.mockReturnValue(true);
+    const processKillSpy = vi.spyOn(process, "kill");
+
+    await cleanupStaleZrok();
+
+    expect(processKillSpy).not.toHaveBeenCalled();
+    processKillSpy.mockRestore();
+  });
+});