@blackbelt-technology/pi-agent-dashboard 0.4.6 → 0.5.1

package/packages/server/src/__tests__/spawn-correlation-token-integration.test.ts

@@ -0,0 +1,91 @@
+/**
+ * Integration: verify the kill-fork-kills-parent bug stays fixed.
+ *
+ * Simulates the race window where parent + fork are both registered in the
+ * same cwd and bridges connect in arbitrary order. Asserts the registry
+ * resolves each sessionId to its OWN PID via the three-tier link.
+ *
+ * See change: spawn-correlation-token.
+ */
+import { describe, it, expect } from "vitest";
+import { EventEmitter } from "node:events";
+import { mkdtempSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { createHeadlessPidRegistry } from "../headless-pid-registry.js";
+import { createPendingForkRegistry } from "../pending-fork-registry.js";
+import { mintSpawnToken } from "../spawn-token.js";
+
+function mockProc() {
+  return new EventEmitter() as any;
+}
+
+function tmpPidFile() {
+  return join(mkdtempSync(join(tmpdir(), "spawn-corr-")), "pids.json");
+}
+
+describe("spawn-correlation-token: kill-fork-doesn't-kill-parent regression", () => {
+  it("two same-cwd spawns: each session resolves to its OWN pid via token", () => {
+    // Setup: simulate dashboard spawning parent, then fork, in the same cwd.
+    // Each spawn mints a token; registry stores entries by pid + token.
+    const registry = createHeadlessPidRegistry({ pidFilePath: tmpPidFile() });
+    const tokenParent = mintSpawnToken();
+    const tokenFork = mintSpawnToken();
+    expect(tokenParent).not.toBe(tokenFork);
+
+    registry.register(1000, "/proj", mockProc(), tokenParent);
+    registry.register(1234, "/proj", mockProc(), tokenFork);
+
+    // Bridge connect order is reversed (fork first, parent second) — the
+    // worst-case race that produced the original bug.
+    expect(registry.linkByToken(tokenFork, "S_fork")).toBe(true);
+    expect(registry.linkByToken(tokenParent, "S_parent")).toBe(true);
+
+    // Critical: each session resolves to its OWN pid. Pre-fix this would
+    // have given S_fork → 1000 (parent) and S_parent → 1234 (fork) due to
+    // cwd-FIFO ordering.
+    expect(registry.getPid("S_fork")).toBe(1234);
+    expect(registry.getPid("S_parent")).toBe(1000);
+  });
+
+  it("legacy bridge fallback: linkByPid is exact even without tokens", () => {
+    const registry = createHeadlessPidRegistry({ pidFilePath: tmpPidFile() });
+    // Legacy bridges don't send spawnToken; only pid.
+    registry.register(1000, "/proj", mockProc()); // no token
+    registry.register(1234, "/proj", mockProc()); // no token
+
+    // Race-order register messages, but pid-link is direct lookup.
+    expect(registry.linkByPid("S_fork", 1234)).toBe(true);
+    expect(registry.linkByPid("S_parent", 1000)).toBe(true);
+
+    expect(registry.getPid("S_fork")).toBe(1234);
+    expect(registry.getPid("S_parent")).toBe(1000);
+  });
+
+  it("fork registry: per-token keying separates two forks in same cwd", () => {
+    const forkRegistry = createPendingForkRegistry();
+    const tokenA = mintSpawnToken();
+    const tokenB = mintSpawnToken();
+
+    // Two forks issued in the same cwd, each with its own token. Pre-fix
+    // (cwd-keyed registry) the second recordFork would overwrite the first.
+    forkRegistry.recordFork(tokenA, "parent-A");
+    forkRegistry.recordFork(tokenB, "parent-B");
+
+    // Bridge connect order arbitrary; each token resolves to its OWN parent.
+    expect(forkRegistry.consumeFork(tokenB)).toBe("parent-B");
+    expect(forkRegistry.consumeFork(tokenA)).toBe("parent-A");
+  });
+
+  it("stale token (server-restart-mid-spawn) degrades to lower-tier match", () => {
+    const registry = createHeadlessPidRegistry({ pidFilePath: tmpPidFile() });
+    // Bridge holds an env-var token from before server restart; the new
+    // server has no entry for that token. linkByToken returns false; the
+    // event-wiring caller falls through to linkByPid.
+    registry.register(1000, "/proj", mockProc()); // post-restart entry, no token
+    expect(registry.linkByToken("stale_tok_from_old_server", "S")).toBe(false);
+    // Caller falls back:
+    expect(registry.linkByPid("S", 1000)).toBe(true);
+    expect(registry.getPid("S")).toBe(1000);
+  });
+});

package/packages/server/src/__tests__/spawn-failure-log.test.ts

@@ -0,0 +1,118 @@
+/**
+ * Tests for spawn-failure-log.ts.
+ * See change: spawn-failure-diagnostics.
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync, statSync, existsSync } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+import { appendSpawnFailure, readSpawnFailures, _setLogDirForTests } from "../spawn-failure-log.js";
+import type { SpawnFailureEntry } from "../spawn-failure-log.js";
+
+function makeEntry(overrides: Partial<SpawnFailureEntry> = {}): SpawnFailureEntry {
+  return {
+    ts: new Date().toISOString(),
+    cwd: "/tmp/test",
+    strategy: "headless",
+    code: "PI_CRASHED",
+    message: "Pi exited immediately",
+    ...overrides,
+  };
+}
+
+describe("spawn-failure-log", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(path.join(os.tmpdir(), "sfl-test-"));
+    _setLogDirForTests(tmpDir);
+  });
+
+  afterEach(() => {
+    _setLogDirForTests(null);
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("appends an entry and reads it back", () => {
+    const entry = makeEntry();
+    appendSpawnFailure(entry);
+    const entries = readSpawnFailures(10);
+    expect(entries).toHaveLength(1);
+    expect(entries[0]!.cwd).toBe(entry.cwd);
+    expect(entries[0]!.code).toBe(entry.code);
+  });
+
+  it("returns [] when no log file exists", () => {
+    expect(readSpawnFailures(10)).toEqual([]);
+  });
+
+  it("returns [] for limit 0", () => {
+    appendSpawnFailure(makeEntry());
+    expect(readSpawnFailures(0)).toEqual([]);
+  });
+
+  it("returns [] for negative limit", () => {
+    appendSpawnFailure(makeEntry());
+    expect(readSpawnFailures(-5)).toEqual([]);
+  });
+
+  it("returns last N entries when more than limit exist", () => {
+    for (let i = 0; i < 5; i++) {
+      appendSpawnFailure(makeEntry({ message: `msg ${i}` }));
+    }
+    const result = readSpawnFailures(3);
+    expect(result).toHaveLength(3);
+    expect(result[2]!.message).toBe("msg 4");
+  });
+
+  it("skips malformed lines", () => {
+    const logFile = path.join(tmpDir, "spawn-failures.log");
+    writeFileSync(logFile, `not-json\n${JSON.stringify(makeEntry({ message: "good" }))}\n`);
+    const entries = readSpawnFailures(10);
+    expect(entries).toHaveLength(1);
+    expect(entries[0]!.message).toBe("good");
+  });
+
+  it("never throws when append fails", () => {
+    const logFile = path.join(tmpDir, "spawn-failures.log");
+    // Create as dir to force write failure.
+    mkdirSync(logFile);
+    expect(() => appendSpawnFailure(makeEntry())).not.toThrow();
+  });
+
+  it("rotates when file exceeds 10 MB", () => {
+    const logFile = path.join(tmpDir, "spawn-failures.log");
+    const logFile1 = path.join(tmpDir, "spawn-failures.log.1");
+
+    // Write a file >10MB.
+    const bigContent = "x".repeat(10 * 1024 * 1024 + 1);
+    writeFileSync(logFile, bigContent);
+
+    appendSpawnFailure(makeEntry({ message: "after rotation" }));
+
+    expect(existsSync(logFile1)).toBe(true);
+    const entries = readSpawnFailures(10);
+    expect(entries.some((e) => e.message === "after rotation")).toBe(true);
+    expect(statSync(logFile).size).toBeLessThan(bigContent.length);
+  });
+
+  it("reads from both .log.1 and .log (older first)", () => {
+    const logFile = path.join(tmpDir, "spawn-failures.log");
+    const logFile1 = path.join(tmpDir, "spawn-failures.log.1");
+
+    writeFileSync(logFile1, JSON.stringify(makeEntry({ message: "old" })) + "\n");
+    writeFileSync(logFile, JSON.stringify(makeEntry({ message: "new" })) + "\n");
+
+    const entries = readSpawnFailures(10);
+    expect(entries).toHaveLength(2);
+    expect(entries[0]!.message).toBe("old");
+    expect(entries[1]!.message).toBe("new");
+  });
+
+  it("clamps limit at 500", () => {
+    for (let i = 0; i < 10; i++) appendSpawnFailure(makeEntry());
+    const entries = readSpawnFailures(9999);
+    expect(entries.length).toBeLessThanOrEqual(500);
+  });
+});

package/packages/server/src/__tests__/spawn-preflight.test.ts

@@ -0,0 +1,91 @@
+/**
+ * Tests for spawn-preflight.ts — pure validation, no process spawning.
+ * See change: spawn-failure-diagnostics.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { mkdirSync, mkdtempSync, writeFileSync, rmSync, chmodSync } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+// We mock the ToolResolver so no binary lookup is attempted.
+vi.mock("@blackbelt-technology/pi-dashboard-shared/platform/binary-lookup.js", () => ({
+  ToolResolver: function MockToolResolver() {
+    return {
+      resolvePi: vi.fn().mockReturnValue(["pi"]),
+      resolveNode: vi.fn().mockReturnValue("/usr/bin/node"),
+    };
+  },
+}));
+
+import { preflightSpawn } from "../spawn-preflight.js";
+import { ToolResolver } from "@blackbelt-technology/pi-dashboard-shared/platform/binary-lookup.js";
+
+function makeResolver(overrides: { resolvePi?: () => string[] | null; resolveNode?: () => string | null }) {
+  return {
+    resolvePi: overrides.resolvePi ?? (() => ["pi"]),
+    resolveNode: overrides.resolveNode ?? (() => "/usr/bin/node"),
+  } as unknown as InstanceType<typeof ToolResolver>;
+}
+
+describe("preflightSpawn", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(path.join(os.tmpdir(), "preflight-test-"));
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("returns ok when all checks pass", () => {
+    const result = preflightSpawn(tmpDir, { resolver: makeResolver({}) });
+    expect(result.ok).toBe(true);
+    expect(result.reasons).toHaveLength(0);
+  });
+
+  it("returns DIR_MISSING when cwd does not exist", () => {
+    const result = preflightSpawn("/nonexistent/does/not/exist", { resolver: makeResolver({}) });
+    expect(result.ok).toBe(false);
+    expect(result.reasons.some((r) => r.code === "DIR_MISSING")).toBe(true);
+  });
+
+  it("returns DIR_NOT_DIRECTORY when cwd is a file", () => {
+    const filePath = path.join(tmpDir, "regular-file.txt");
+    writeFileSync(filePath, "hello");
+    const result = preflightSpawn(filePath, { resolver: makeResolver({}) });
+    expect(result.ok).toBe(false);
+    expect(result.reasons.some((r) => r.code === "DIR_NOT_DIRECTORY")).toBe(true);
+  });
+
+  it("returns PI_NOT_FOUND when pi binary unresolvable", () => {
+    const result = preflightSpawn(tmpDir, { resolver: makeResolver({ resolvePi: () => null }) });
+    expect(result.ok).toBe(false);
+    expect(result.reasons.some((r) => r.code === "PI_NOT_FOUND")).toBe(true);
+  });
+
+  it("returns NODE_NOT_FOUND when node binary unresolvable", () => {
+    const result = preflightSpawn(tmpDir, { resolver: makeResolver({ resolveNode: () => null }) });
+    expect(result.ok).toBe(false);
+    expect(result.reasons.some((r) => r.code === "NODE_NOT_FOUND")).toBe(true);
+  });
+
+  it("accumulates multiple reasons (no short-circuit)", () => {
+    const result = preflightSpawn("/nonexistent/does/not/exist", {
+      resolver: makeResolver({ resolvePi: () => null }),
+    });
+    expect(result.ok).toBe(false);
+    expect(result.reasons.some((r) => r.code === "DIR_MISSING")).toBe(true);
+    expect(result.reasons.some((r) => r.code === "PI_NOT_FOUND")).toBe(true);
+    expect(result.reasons.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it("does not call login-shell resolver (resolver.resolvePi is called, not whichViaLoginShell)", () => {
+    const mockResolver = makeResolver({});
+    const spyPi = vi.spyOn(mockResolver, "resolvePi");
+    const spyNode = vi.spyOn(mockResolver, "resolveNode");
+    preflightSpawn(tmpDir, { resolver: mockResolver });
+    expect(spyPi).toHaveBeenCalled();
+    expect(spyNode).toHaveBeenCalled();
+  });
+});

package/packages/server/src/__tests__/spawn-register-watchdog.test.ts

@@ -0,0 +1,250 @@
+/**
+ * Tests for SpawnRegisterWatchdog.
+ * Uses vitest fake timers. See change: spawn-failure-diagnostics.
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import WebSocket from "ws";
+
+// Silence appendSpawnFailure in unit tests.
+vi.mock("../spawn-failure-log.js", () => ({
+  appendSpawnFailure: vi.fn(),
+}));
+
+import { SpawnRegisterWatchdog } from "../spawn-register-watchdog.js";
+
+function makeMockWs(readyState: number = WebSocket.OPEN): { ws: WebSocket; messages: string[] } {
+  const messages: string[] = [];
+  const ws = {
+    readyState,
+    send: vi.fn((data: string) => messages.push(data)),
+  } as unknown as WebSocket;
+  return { ws, messages };
+}
+
+describe("SpawnRegisterWatchdog", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("clamps timeoutMs below 5000 to 5000", () => {
+    const w = new SpawnRegisterWatchdog(1000);
+    expect(w.timeoutMs).toBe(5000);
+  });
+
+  it("clamps timeoutMs above 120000 to 120000", () => {
+    const w = new SpawnRegisterWatchdog(999999);
+    expect(w.timeoutMs).toBe(120000);
+  });
+
+  it("headless arm + clearByPid cancels watchdog", () => {
+    const { ws, messages } = makeMockWs();
+    const w = new SpawnRegisterWatchdog(10000);
+    w.arm({ pid: 123, cwd: "/p/x", mechanism: "headless", ws });
+    w.clearByPid(123);
+    vi.advanceTimersByTime(15000);
+    expect(messages).toHaveLength(0);
+  });
+
+  it("headless arm + clearByCwd (pid mismatch) still cancels watchdog", () => {
+    // Regression: Unix headless wraps pi in `sh -c "… | pi"`, so spawnResult.pid
+    // is the sh wrapper while session_register reports pi's real pid. Watchdog
+    // must clear via cwd even when pid was indexed at arm time.
+    const { ws, messages } = makeMockWs();
+    const w = new SpawnRegisterWatchdog(10000);
+    w.arm({ pid: 51250, cwd: "/p/x", mechanism: "headless", ws });
+    w.clearByCwd("/p/x");
+    vi.advanceTimersByTime(15000);
+    expect(messages).toHaveLength(0);
+  });
+
+  it("tmux arm + clearByCwd cancels watchdog", () => {
+    const { ws, messages } = makeMockWs();
+    const w = new SpawnRegisterWatchdog(10000);
+    w.arm({ cwd: "/p/x", mechanism: "tmux", ws });
+    w.clearByCwd("/p/x");
+    vi.advanceTimersByTime(15000);
+    expect(messages).toHaveLength(0);
+  });
+
+  it("arm without clear fires spawn_register_timeout", () => {
+    const { ws, messages } = makeMockWs();
+    const w = new SpawnRegisterWatchdog(10000);
+    w.arm({ pid: 42, cwd: "/p/y", mechanism: "headless", ws });
+    vi.advanceTimersByTime(10001);
+    expect(messages).toHaveLength(1);
+    const msg = JSON.parse(messages[0]!);
+    expect(msg.type).toBe("spawn_register_timeout");
+    expect(msg.cwd).toBe("/p/y");
+    expect(msg.pid).toBe(42);
+  });
+
+  it("tmux timeout omits pid", () => {
+    const { ws, messages } = makeMockWs();
+    const w = new SpawnRegisterWatchdog(10000);
+    w.arm({ cwd: "/p/z", mechanism: "tmux", ws });
+    vi.advanceTimersByTime(10001);
+    expect(messages).toHaveLength(1);
+    const msg = JSON.parse(messages[0]!);
+    expect(msg.pid).toBeUndefined();
+  });
+
+  it("clear on unknown key is a no-op", () => {
+    const w = new SpawnRegisterWatchdog(10000);
+    expect(() => w.clearByPid(999)).not.toThrow();
+    expect(() => w.clearByCwd("/never/seen")).not.toThrow();
+  });
+
+  it("timeout fires silently when ws is closed", () => {
+    const { ws, messages } = makeMockWs(WebSocket.CLOSED);
+    const w = new SpawnRegisterWatchdog(10000);
+    w.arm({ cwd: "/p/q", mechanism: "tmux", ws });
+    expect(() => vi.advanceTimersByTime(10001)).not.toThrow();
+    expect(messages).toHaveLength(0);
+  });
+
+  it("late clearByCwd within 60s emits spawn_register_recovered", () => {
+    const { ws, messages } = makeMockWs();
+    const w = new SpawnRegisterWatchdog(10000);
+    w.arm({ cwd: "/p/r", mechanism: "tmux", ws });
+
+    // Fire the watchdog.
+    vi.advanceTimersByTime(10001);
+    expect(messages[0]).toContain("spawn_register_timeout");
+
+    // Late registration within 60s.
+    vi.advanceTimersByTime(5000);
+    w.clearByCwd("/p/r");
+
+    expect(messages).toHaveLength(2);
+    const recovery = JSON.parse(messages[1]!);
+    expect(recovery.type).toBe("spawn_register_recovered");
+    expect(recovery.cwd).toBe("/p/r");
+  });
+
+  it("late clear past 60s TTL is silent", () => {
+    const { ws, messages } = makeMockWs();
+    const w = new SpawnRegisterWatchdog(10000);
+    w.arm({ cwd: "/p/s", mechanism: "tmux", ws });
+
+    vi.advanceTimersByTime(10001);
+    expect(messages).toHaveLength(1);
+
+    // Past 60s TTL.
+    vi.advanceTimersByTime(61000);
+    w.clearByCwd("/p/s");
+
+    // No recovery message.
+    expect(messages).toHaveLength(1);
+  });
+
+  it("recovery skipped when ws closed at recovery time", () => {
+    const messages: string[] = [];
+    // Start with OPEN, then we'll swap to CLOSED.
+    const ws = {
+      readyState: WebSocket.OPEN,
+      send: vi.fn((data: string) => messages.push(data)),
+    } as unknown as WebSocket;
+
+    const w = new SpawnRegisterWatchdog(10000);
+    w.arm({ cwd: "/p/t", mechanism: "tmux", ws });
+    vi.advanceTimersByTime(10001);
+
+    // Close the ws before recovery.
+    (ws as unknown as { readyState: number }).readyState = WebSocket.CLOSED;
+
+    vi.advanceTimersByTime(5000);
+    w.clearByCwd("/p/t");
+
+    // Only the timeout message was sent (before ws was closed).
+    const recoveries = messages.filter((m) => m.includes("spawn_register_recovered"));
+    expect(recoveries).toHaveLength(0);
+  });
+});
+
+// See change: spawn-correlation-token — third index by token.
+describe("SpawnRegisterWatchdog: byToken index", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("clearByToken cancels the watchdog", () => {
+    const w = new SpawnRegisterWatchdog(30_000);
+    const { ws, messages } = makeMockWs();
+    w.arm({ pid: 100, cwd: "/p", mechanism: "headless", ws, spawnToken: "tok_a" });
+    w.clearByToken("tok_a");
+    vi.advanceTimersByTime(60_000);
+    expect(messages.filter((m) => m.includes("spawn_register_timeout"))).toHaveLength(0);
+  });
+
+  it("clearByToken removes entry from cwd and pid indices too", () => {
+    const w = new SpawnRegisterWatchdog(30_000);
+    const { ws } = makeMockWs();
+    w.arm({ pid: 100, cwd: "/p", mechanism: "headless", ws, spawnToken: "tok_a" });
+    w.clearByToken("tok_a");
+    // Subsequent clearByPid / clearByCwd are no-ops (entry already removed).
+    w.clearByPid(100);
+    w.clearByCwd("/p");
+    // No exception, no double-clear.
+    expect(true).toBe(true);
+  });
+
+  it("clearByPid also clears the token index", () => {
+    const w = new SpawnRegisterWatchdog(30_000);
+    const { ws, messages } = makeMockWs();
+    w.arm({ pid: 100, cwd: "/p", mechanism: "headless", ws, spawnToken: "tok_a" });
+    w.clearByPid(100);
+    // Token-keyed clear is now a no-op (already cleaned up).
+    w.clearByToken("tok_a");
+    vi.advanceTimersByTime(60_000);
+    expect(messages.filter((m) => m.includes("spawn_register_timeout"))).toHaveLength(0);
+  });
+
+  it("tmux arm without pid: token clears watchdog", () => {
+    const w = new SpawnRegisterWatchdog(30_000);
+    const { ws, messages } = makeMockWs();
+    w.arm({ cwd: "/p", mechanism: "tmux", ws, spawnToken: "tok_b" });
+    w.clearByToken("tok_b");
+    vi.advanceTimersByTime(60_000);
+    expect(messages.filter((m) => m.includes("spawn_register_timeout"))).toHaveLength(0);
+  });
+
+  it("late clearByToken after timeout emits recovered", () => {
+    const w = new SpawnRegisterWatchdog(30_000);
+    const { ws, messages } = makeMockWs();
+    w.arm({ pid: 100, cwd: "/p", mechanism: "headless", ws, spawnToken: "tok_c" });
+    vi.advanceTimersByTime(31_000); // timeout fires
+    expect(messages.filter((m) => m.includes("spawn_register_timeout"))).toHaveLength(1);
+    w.clearByToken("tok_c");
+    expect(messages.filter((m) => m.includes("spawn_register_recovered"))).toHaveLength(1);
+  });
+
+  it("two simultaneous arms with distinct tokens, distinct cwds: token-clears each independently", () => {
+    const w = new SpawnRegisterWatchdog(30_000);
+    const { ws: ws1, messages: m1 } = makeMockWs();
+    const { ws: ws2, messages: m2 } = makeMockWs();
+    w.arm({ pid: 100, cwd: "/p1", mechanism: "headless", ws: ws1, spawnToken: "tok_x" });
+    w.arm({ pid: 200, cwd: "/p2", mechanism: "headless", ws: ws2, spawnToken: "tok_y" });
+    w.clearByToken("tok_y");
+    vi.advanceTimersByTime(31_000);
+    // Only the first arm's timeout fired (second was cleared).
+    expect(m1.filter((m) => m.includes("spawn_register_timeout"))).toHaveLength(1);
+    expect(m2.filter((m) => m.includes("spawn_register_timeout"))).toHaveLength(0);
+  });
+
+  it("arm without spawnToken behaves as before", () => {
+    const w = new SpawnRegisterWatchdog(30_000);
+    const { ws, messages } = makeMockWs();
+    w.arm({ pid: 100, cwd: "/p", mechanism: "headless", ws });
+    // Token-clear with empty / unknown token is a no-op.
+    w.clearByToken("tok_unknown");
+    vi.advanceTimersByTime(31_000);
+    expect(messages.filter((m) => m.includes("spawn_register_timeout"))).toHaveLength(1);
+  });
+});

package/packages/server/src/__tests__/spawn-token.test.ts

@@ -0,0 +1,57 @@
+/**
+ * Tests for spawn correlation token primitives.
+ *
+ * Covers:
+ *   - `mintSpawnToken()` returns distinct UUIDv4 strings.
+ *   - `buildSpawnEnv(env, { spawnToken })` injects `PI_DASHBOARD_SPAWN_TOKEN`.
+ *   - Without `spawnToken`, env is unchanged (no leakage).
+ *
+ * See change: spawn-correlation-token.
+ */
+import { describe, expect, it } from "vitest";
+import { mintSpawnToken, SPAWN_TOKEN_ENV_VAR } from "../spawn-token.js";
+import { buildSpawnEnv } from "../process-manager.js";
+
+describe("mintSpawnToken", () => {
+	it("returns a UUIDv4 string", () => {
+		const t = mintSpawnToken();
+		expect(typeof t).toBe("string");
+		// UUIDv4: 8-4-4-4-12 hex with version=4 nibble
+		expect(t).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i);
+	});
+
+	it("returns distinct tokens on each call", () => {
+		const tokens = new Set<string>();
+		for (let i = 0; i < 50; i++) tokens.add(mintSpawnToken());
+		expect(tokens.size).toBe(50);
+	});
+});
+
+describe("buildSpawnEnv: spawnToken injection", () => {
+	it("sets PI_DASHBOARD_SPAWN_TOKEN when spawnToken is provided", () => {
+		const env = buildSpawnEnv({ HOME: "/tmp" }, { spawnToken: "tok_test_123" });
+		expect(env[SPAWN_TOKEN_ENV_VAR]).toBe("tok_test_123");
+	});
+
+	it("does not set PI_DASHBOARD_SPAWN_TOKEN when spawnToken is omitted", () => {
+		const env = buildSpawnEnv({ HOME: "/tmp" });
+		expect(env[SPAWN_TOKEN_ENV_VAR]).toBeUndefined();
+	});
+
+	it("does not set PI_DASHBOARD_SPAWN_TOKEN when opts is empty", () => {
+		const env = buildSpawnEnv({ HOME: "/tmp" }, {});
+		expect(env[SPAWN_TOKEN_ENV_VAR]).toBeUndefined();
+	});
+
+	it("preserves baseEnv variables unchanged when injecting", () => {
+		const env = buildSpawnEnv(
+			{ HOME: "/tmp", FOO: "bar", PATH: "/usr/bin" },
+			{ spawnToken: "tok_xyz" },
+		);
+		expect(env.HOME).toBe("/tmp");
+		expect(env.FOO).toBe("bar");
+		expect(env[SPAWN_TOKEN_ENV_VAR]).toBe("tok_xyz");
+		// PATH may be mutated by managed-node prepend, but the raw value should still appear in it.
+		expect(env.PATH).toContain("/usr/bin");
+	});
+});