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

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__/fixtures/fork-jsonl-roundtrip.jsonl

@@ -0,0 +1,8 @@
+{"type":"session","version":"1","id":"019dcdd5-0000-0000-0000-000000000000","timestamp":"2026-04-27T07:26:23.927Z","cwd":"/tmp/fork-test"}
+{"type":"model_change","id":"m1","timestamp":"2026-04-27T07:26:24.000Z","provider":"anthropic","modelId":"claude-sonnet-4"}
+{"type":"message","id":"u1","parentId":"m1","timestamp":"2026-04-27T07:26:25.000Z","message":{"role":"user","content":[{"type":"text","text":"Hello"}]}}
+{"type":"message","id":"a1","parentId":"u1","timestamp":"2026-04-27T07:26:30.000Z","message":{"role":"assistant","content":[{"type":"text","text":"Hi there!"}]}}
+{"type":"message","id":"u2","parentId":"a1","timestamp":"2026-04-27T07:26:40.000Z","message":{"role":"user","content":[{"type":"text","text":"How are you?"}]}}
+{"type":"message","id":"a2","parentId":"u2","timestamp":"2026-04-27T07:26:45.000Z","message":{"role":"assistant","content":[{"type":"text","text":"Doing well."}]}}
+{"type":"message","id":"u3","parentId":"a2","timestamp":"2026-04-27T07:26:55.000Z","message":{"role":"user","content":[{"type":"text","text":"Goodbye"}]}}
+{"type":"message","id":"a3","parentId":"u3","timestamp":"2026-04-27T07:27:00.000Z","message":{"role":"assistant","content":[{"type":"text","text":"Bye!"}]}}

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__/fork-jsonl-roundtrip.test.ts

@@ -0,0 +1,49 @@
+/**
+ * Round-trip test: createBranchedSessionFile MUST end the new JSONL at the
+ * given entry id. Catches the fork-bubble off-by-one bug from the upstream
+ * angle: if the bridge ever stamps a correct entry id on a bubble, this
+ * function must produce a file whose tail entry equals that id.
+ */
+import { describe, it, expect } from "vitest";
+import { readFileSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createBranchedSessionFile } from "../session-file-reader.js";
+
+const FIXTURE = join(__dirname, "fixtures", "fork-jsonl-roundtrip.jsonl");
+
+function readEntries(path: string): any[] {
+  return readFileSync(path, "utf-8").trim().split("\n").map(l => JSON.parse(l));
+}
+
+describe("createBranchedSessionFile round-trip", () => {
+  it("for every non-header entry id, the forked JSONL ends at that id", () => {
+    // Copy fixture to a tmp dir so the function can write its sibling output there.
+    const tmp = mkdtempSync(join(tmpdir(), "fork-roundtrip-"));
+    const tmpFixture = join(tmp, "src.jsonl");
+    require("node:fs").copyFileSync(FIXTURE, tmpFixture);
+
+    try {
+      const allEntries = readEntries(tmpFixture);
+      const candidates = allEntries.filter(e => e.type === "message" || e.type === "model_change").map(e => e.id);
+      expect(candidates.length).toBeGreaterThan(0);
+
+      for (const targetId of candidates) {
+        const newPath = createBranchedSessionFile(tmpFixture, targetId);
+        const newEntries = readEntries(newPath);
+
+        const header = newEntries[0];
+        expect(header.type).toBe("session");
+
+        const lastEntry = newEntries[newEntries.length - 1];
+        expect(lastEntry.id).toBe(targetId);
+      }
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  it("throws on unknown entry id", () => {
+    expect(() => createBranchedSessionFile(FIXTURE, "does-not-exist")).toThrow(/not found/i);
+  });
+});

package/packages/server/src/__tests__/home-lock-escape-hatch.test.ts

@@ -0,0 +1,60 @@
+/**
+ * Tests for the PI_DASHBOARD_ALLOW_MULTIPLE escape hatch.
+ *
+ * The escape hatch is evaluated in `cli.ts::runForeground`; here we test
+ * the pure predicate `isLockDisabled` plus a behavioral test that confirms
+ * NO metadata is written when the lock is skipped.
+ *
+ * See change: single-dashboard-per-home, task 14.3.
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { isLockDisabled, acquireOrAttach } from "../home-lock.js";
+
+let tmpHome: string;
+let lockPath: string;
+let metaPath: string;
+
+beforeEach(() => {
+  tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "pi-escape-hatch-"));
+  lockPath = path.join(tmpHome, ".pi", "dashboard", "server.lock");
+  metaPath = `${lockPath}.meta.json`;
+});
+
+afterEach(() => {
+  try { fs.rmSync(tmpHome, { recursive: true, force: true }); } catch { /* ignore */ }
+});
+
+describe("escape hatch", () => {
+  it("isLockDisabled true for =1 and =true", () => {
+    expect(isLockDisabled({ PI_DASHBOARD_ALLOW_MULTIPLE: "1" })).toBe(true);
+    expect(isLockDisabled({ PI_DASHBOARD_ALLOW_MULTIPLE: "true" })).toBe(true);
+  });
+
+  it("isLockDisabled false when unset or other values", () => {
+    expect(isLockDisabled({})).toBe(false);
+    expect(isLockDisabled({ PI_DASHBOARD_ALLOW_MULTIPLE: "" })).toBe(false);
+    expect(isLockDisabled({ PI_DASHBOARD_ALLOW_MULTIPLE: "yes" })).toBe(false);
+    expect(isLockDisabled({ PI_DASHBOARD_ALLOW_MULTIPLE: "0" })).toBe(false);
+  });
+
+  it("when caller skips acquireOrAttach (escape hatch on), no metadata sidecar exists", () => {
+    // The CLI-level behavior when PI_DASHBOARD_ALLOW_MULTIPLE is set is to
+    // NOT call acquireOrAttach at all. We simulate that: the fact that we
+    // never called acquireOrAttach means the sidecar was never written.
+    expect(fs.existsSync(metaPath)).toBe(false);
+  });
+
+  it("when lock IS acquired, metadata is written (control)", async () => {
+    const r = await acquireOrAttach({
+      httpPort: 8000, piPort: 9999, version: "t",
+      hooks: { lockPath, metaPath, staleMs: 500 },
+    });
+    expect(r.mode).toBe("acquired");
+    expect(fs.existsSync(metaPath)).toBe(true);
+    if (r.mode === "acquired") await r.release();
+    expect(fs.existsSync(metaPath)).toBe(false);
+  });
+});

package/packages/server/src/__tests__/home-lock-release.test.ts

@@ -0,0 +1,85 @@
+/**
+ * Unit tests for signal-handler installation. See change: single-dashboard-per-home.
+ */
+import { describe, it, expect, vi } from "vitest";
+import { EventEmitter } from "node:events";
+import { installReleaseHandlers } from "../home-lock-release.js";
+
+function fakeProcess() {
+  const ee = new EventEmitter() as unknown as NodeJS.Process;
+  (ee as unknown as { exit: (code: number) => void }).exit = vi.fn();
+  return ee;
+}
+
+describe("installReleaseHandlers", () => {
+  it("registers SIGINT, SIGTERM, SIGHUP, SIGBREAK, and exit handlers", () => {
+    const proc = fakeProcess();
+    const onSpy = vi.spyOn(proc, "on");
+    installReleaseHandlers(async () => {}, { proc });
+    const registered = onSpy.mock.calls.map(c => c[0]);
+    expect(registered).toEqual(expect.arrayContaining(["SIGINT", "SIGTERM", "SIGHUP", "SIGBREAK", "exit"]));
+  });
+
+  it("calls release() on SIGTERM", async () => {
+    const proc = fakeProcess();
+    const release = vi.fn(async () => {});
+    installReleaseHandlers(release, { proc });
+    proc.emit("SIGTERM");
+    // Handler is async — let microtasks flush.
+    await new Promise(r => setImmediate(r));
+    expect(release).toHaveBeenCalledTimes(1);
+  });
+
+  it("calls release() on SIGBREAK (Windows Ctrl+Break)", async () => {
+    // On POSIX Node never emits SIGBREAK, but the handler must still be
+    // wired so Windows Ctrl+Break triggers lock release. Exercising via a
+    // fake process guarantees the registration + dispatch path works.
+    const proc = fakeProcess();
+    const release = vi.fn(async () => {});
+    installReleaseHandlers(release, { proc });
+    proc.emit("SIGBREAK" as NodeJS.Signals);
+    await new Promise(r => setImmediate(r));
+    expect(release).toHaveBeenCalledTimes(1);
+  });
+
+  it("calls release() on SIGHUP", async () => {
+    const proc = fakeProcess();
+    const release = vi.fn(async () => {});
+    installReleaseHandlers(release, { proc });
+    proc.emit("SIGHUP");
+    await new Promise(r => setImmediate(r));
+    expect(release).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not double-release on repeated signals", async () => {
+    const proc = fakeProcess();
+    const release = vi.fn(async () => {});
+    installReleaseHandlers(release, { proc });
+    proc.emit("SIGTERM");
+    proc.emit("SIGTERM");
+    proc.emit("SIGINT");
+    await new Promise(r => setImmediate(r));
+    expect(release).toHaveBeenCalledTimes(1);
+  });
+
+  it("returns a dispose function that removes handlers", () => {
+    const proc = fakeProcess();
+    const release = vi.fn(async () => {});
+    const dispose = installReleaseHandlers(release, { proc });
+    dispose();
+    proc.emit("SIGTERM");
+    // After dispose, the release must not fire.
+    expect(release).not.toHaveBeenCalled();
+  });
+
+  it("swallows release errors but logs them", async () => {
+    const proc = fakeProcess();
+    const logs: string[] = [];
+    const release = vi.fn(async () => { throw new Error("boom"); });
+    installReleaseHandlers(release, { proc, log: (m) => logs.push(m) });
+    proc.emit("SIGTERM");
+    await new Promise(r => setImmediate(r));
+    await new Promise(r => setImmediate(r));
+    expect(logs.join("\n")).toContain("boom");
+  });
+});