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

package/packages/shared/src/__tests__/platform-paths.test.ts

@@ -0,0 +1,284 @@
+/**
+ * Tests for packages/shared/src/platform/paths.ts.
+ *
+ * Every test explicitly passes a `platform: NodeJS.Platform` argument so
+ * both Windows and Unix branches run on every CI host. No mutation of
+ * `process.platform`, no `vi.mock`.
+ *
+ * See change: platform-path-normalization.
+ */
+import { describe, it, expect } from "vitest";
+import {
+  normalizePath,
+  samePath,
+  parsePathInput,
+  withTrailingSep,
+  joinForDisplay,
+  isFilesystemRoot,
+} from "../platform/paths.js";
+
+// ── normalizePath ───────────────────────────────────────────────────────────
+
+describe("normalizePath — Windows", () => {
+  it("strips trailing separator from non-root path", () => {
+    expect(normalizePath("C:\\Dev\\BB\\pi-agent-dashboard\\", "win32"))
+      .toBe("C:\\Dev\\BB\\pi-agent-dashboard");
+  });
+
+  it("canonicalizes mixed separators to backslash", () => {
+    expect(normalizePath("C:/Dev\\BB/pi-agent-dashboard", "win32"))
+      .toBe("C:\\Dev\\BB\\pi-agent-dashboard");
+  });
+
+  it("preserves drive root trailing separator", () => {
+    expect(normalizePath("C:\\", "win32")).toBe("C:\\");
+  });
+
+  it("preserves UNC root", () => {
+    expect(normalizePath("\\\\server\\share\\path\\", "win32"))
+      .toBe("\\\\server\\share\\path");
+  });
+
+  it("resolves .. and . segments within a drive", () => {
+    expect(normalizePath("C:\\Dev\\BB\\..\\.\\pi-agent-dashboard", "win32"))
+      .toBe("C:\\Dev\\pi-agent-dashboard");
+  });
+
+  it("preserves case (no lowercasing)", () => {
+    expect(normalizePath("C:\\Dev\\BB", "win32")).toBe("C:\\Dev\\BB");
+    expect(normalizePath("b:\\Dev\\BB", "win32")).toBe("b:\\Dev\\BB");
+  });
+
+  it("preserves different drive letters independently", () => {
+    expect(normalizePath("A:\\Foo\\Bar", "win32")).toBe("A:\\Foo\\Bar");
+    expect(normalizePath("B:\\Foo\\Bar", "win32")).toBe("B:\\Foo\\Bar");
+    expect(normalizePath("Z:\\Something", "win32")).toBe("Z:\\Something");
+  });
+
+  it("treats bare drive letter as drive root, not cwd-relative", () => {
+    // Must NOT fall through to path.win32.resolve which would return
+    // <cwd-on-B-drive>, leaking process.cwd() into the result.
+    expect(normalizePath("B:", "win32")).toBe("B:\\");
+    expect(normalizePath("Z:", "win32")).toBe("Z:\\");
+  });
+
+  it("treats drive-relative typed form as drive-rooted", () => {
+    // "B:Dev" → treat as "B:\Dev", NOT as <B-drive-cwd>\Dev
+    expect(normalizePath("B:Dev", "win32")).toBe("B:\\Dev");
+    expect(normalizePath("C:Users\\me", "win32")).toBe("C:\\Users\\me");
+  });
+
+  it("drops duplicate separators", () => {
+    expect(normalizePath("D:\\\\", "win32")).toBe("D:\\");
+    expect(normalizePath("C:\\\\Users\\\\me", "win32")).toBe("C:\\Users\\me");
+  });
+});
+
+describe("normalizePath — POSIX", () => {
+  it("strips trailing separator from non-root path", () => {
+    expect(normalizePath("/Users/me/Projects/", "linux"))
+      .toBe("/Users/me/Projects");
+  });
+
+  it("preserves root", () => {
+    expect(normalizePath("/", "linux")).toBe("/");
+    expect(normalizePath("/", "darwin")).toBe("/");
+  });
+
+  it("resolves .. and . segments", () => {
+    expect(normalizePath("/Users/me/Dev/../Projects", "linux"))
+      .toBe("/Users/me/Projects");
+  });
+
+  it("collapses duplicate slashes", () => {
+    expect(normalizePath("/Users//me///Projects", "linux"))
+      .toBe("/Users/me/Projects");
+  });
+
+  it("preserves case", () => {
+    expect(normalizePath("/Users/Robson/Dev", "linux")).toBe("/Users/Robson/Dev");
+  });
+});
+
+// ── samePath ────────────────────────────────────────────────────────────────
+
+describe("samePath — Windows (case-insensitive)", () => {
+  it("matches identical paths", () => {
+    expect(samePath("C:\\Dev", "C:\\Dev", "win32")).toBe(true);
+  });
+
+  it("matches with different case", () => {
+    expect(samePath("C:\\Dev\\BB", "c:\\dev\\bb", "win32")).toBe(true);
+  });
+
+  it("matches with different separator style", () => {
+    expect(samePath("C:\\Dev\\BB", "C:/Dev/BB", "win32")).toBe(true);
+  });
+
+  it("matches with trailing-separator drift", () => {
+    expect(samePath("C:\\Dev\\BB", "C:\\Dev\\BB\\", "win32")).toBe(true);
+  });
+
+  it("matches drive-letter case drift alone", () => {
+    expect(samePath("B:\\Dev\\BB", "b:\\Dev\\BB", "win32")).toBe(true);
+  });
+
+  it("DOES NOT merge different drive letters", () => {
+    expect(samePath("A:\\Foo", "B:\\Foo", "win32")).toBe(false);
+    expect(samePath("C:\\Users\\me\\Dev", "D:\\Users\\me\\Dev", "win32")).toBe(false);
+  });
+
+  it("DOES NOT merge UNC path with drive-letter path", () => {
+    expect(samePath("\\\\server\\share\\x", "B:\\x", "win32")).toBe(false);
+  });
+
+  it("returns false for genuinely different paths", () => {
+    expect(samePath("C:\\a", "C:\\b", "win32")).toBe(false);
+  });
+});
+
+describe("samePath — macOS (case-insensitive, HFS+ default)", () => {
+  it("matches with different case", () => {
+    expect(samePath("/Users/me/Dev", "/Users/me/dev", "darwin")).toBe(true);
+  });
+
+  it("matches with trailing-separator drift", () => {
+    expect(samePath("/Users/me/Dev", "/Users/me/Dev/", "darwin")).toBe(true);
+  });
+});
+
+describe("samePath — Linux (case-sensitive)", () => {
+  it("does NOT match on case drift", () => {
+    expect(samePath("/Users/me/Dev", "/users/me/dev", "linux")).toBe(false);
+  });
+
+  it("matches identical paths", () => {
+    expect(samePath("/Users/me/Dev", "/Users/me/Dev", "linux")).toBe(true);
+  });
+
+  it("matches with trailing-separator drift", () => {
+    expect(samePath("/Users/me/Dev", "/Users/me/Dev/", "linux")).toBe(true);
+  });
+
+  it("returns false for different paths", () => {
+    expect(samePath("/a/b", "/a/c", "linux")).toBe(false);
+  });
+});
+
+// ── parsePathInput ──────────────────────────────────────────────────────────
+
+describe("parsePathInput — Windows", () => {
+  it("splits path ending in separator", () => {
+    expect(parsePathInput("C:\\Users\\mboto\\", "win32"))
+      .toEqual({ parent: "C:\\Users\\mboto", partial: "" });
+  });
+
+  it("splits path with partial trailing segment", () => {
+    expect(parsePathInput("C:\\Users\\mboto\\Dev", "win32"))
+      .toEqual({ parent: "C:\\Users\\mboto", partial: "Dev" });
+  });
+
+  it("treats drive root with trailing separator as root", () => {
+    expect(parsePathInput("C:\\", "win32"))
+      .toEqual({ parent: "C:\\", partial: "" });
+  });
+
+  it("treats bare drive letter as drive root", () => {
+    // Critical: must NOT leak cwd via path.win32.resolve fallback.
+    expect(parsePathInput("B:", "win32"))
+      .toEqual({ parent: "B:\\", partial: "" });
+    expect(parsePathInput("Z:", "win32"))
+      .toEqual({ parent: "Z:\\", partial: "" });
+  });
+
+  it("treats drive-relative typed form as drive root + partial", () => {
+    expect(parsePathInput("B:Dev", "win32"))
+      .toEqual({ parent: "B:\\", partial: "Dev" });
+    expect(parsePathInput("C:Users", "win32"))
+      .toEqual({ parent: "C:\\", partial: "Users" });
+  });
+
+  it("splits drive root + partial when separator present", () => {
+    expect(parsePathInput("C:\\Us", "win32"))
+      .toEqual({ parent: "C:\\", partial: "Us" });
+  });
+
+  it("handles UNC path with trailing separator", () => {
+    expect(parsePathInput("\\\\server\\share\\dir\\", "win32"))
+      .toEqual({ parent: "\\\\server\\share\\dir", partial: "" });
+  });
+
+  it("tolerates mixed separators", () => {
+    expect(parsePathInput("C:\\Users\\mboto/Dev", "win32"))
+      .toEqual({ parent: "C:\\Users\\mboto", partial: "Dev" });
+  });
+
+  it("is drive-letter symmetric", () => {
+    // Same shape regardless of drive letter.
+    for (const d of ["A", "B", "C", "D", "Z"]) {
+      expect(parsePathInput(`${d}:\\Foo\\B`, "win32"))
+        .toEqual({ parent: `${d}:\\Foo`, partial: "B" });
+    }
+  });
+});
+
+describe("parsePathInput — POSIX", () => {
+  it("splits absolute path with trailing separator", () => {
+    expect(parsePathInput("/Users/me/", "linux"))
+      .toEqual({ parent: "/Users/me", partial: "" });
+  });
+
+  it("splits absolute path with partial", () => {
+    expect(parsePathInput("/Users/me/Dev", "linux"))
+      .toEqual({ parent: "/Users/me", partial: "Dev" });
+  });
+
+  it("treats root alone as root", () => {
+    expect(parsePathInput("/", "linux"))
+      .toEqual({ parent: "/", partial: "" });
+  });
+
+  it("treats partial-under-root as such", () => {
+    expect(parsePathInput("/U", "linux"))
+      .toEqual({ parent: "/", partial: "U" });
+  });
+});
+
+// ── withTrailingSep & joinForDisplay ────────────────────────────────────────
+
+describe("withTrailingSep", () => {
+  it("appends \\ on Windows", () => {
+    expect(withTrailingSep("C:\\Users\\me", "win32")).toBe("C:\\Users\\me\\");
+  });
+  it("appends / on POSIX", () => {
+    expect(withTrailingSep("/Users/me", "linux")).toBe("/Users/me/");
+  });
+  it("does not double-append when already terminated", () => {
+    expect(withTrailingSep("C:\\Users\\me\\", "win32")).toBe("C:\\Users\\me\\");
+    expect(withTrailingSep("/Users/me/", "linux")).toBe("/Users/me/");
+  });
+});
+
+describe("joinForDisplay", () => {
+  it("joins Windows paths with backslash", () => {
+    expect(joinForDisplay("C:\\Users", "me", "win32")).toBe("C:\\Users\\me");
+  });
+  it("joins POSIX paths with forward slash", () => {
+    expect(joinForDisplay("/Users", "me", "linux")).toBe("/Users/me");
+  });
+});
+
+// ── isFilesystemRoot ────────────────────────────────────────────────────────
+
+describe("isFilesystemRoot", () => {
+  it("recognises Windows drive roots", () => {
+    expect(isFilesystemRoot("C:\\", "win32")).toBe(true);
+    expect(isFilesystemRoot("B:\\", "win32")).toBe(true);
+    expect(isFilesystemRoot("C:\\Users", "win32")).toBe(false);
+  });
+
+  it("recognises Unix root", () => {
+    expect(isFilesystemRoot("/", "linux")).toBe(true);
+    expect(isFilesystemRoot("/Users", "linux")).toBe(false);
+  });
+});

package/packages/shared/src/__tests__/platform-process-scan.test.ts

@@ -0,0 +1,55 @@
+/**
+ * Tests for packages/shared/src/platform/process-scan.ts.
+ * Platform behavior is exercised via injected `platform` + `exec`.
+ * See change: consolidate-platform-handlers.
+ */
+import { describe, it, expect, vi } from "vitest";
+import { parseEtime, isProcessRunning } from "../platform/process-scan.js";
+
+describe("parseEtime", () => {
+  it("parses mm:ss format", () => expect(parseEtime("02:15")).toBe(135_000));
+  it("parses hh:mm:ss format", () => expect(parseEtime("01:30:00")).toBe(5_400_000));
+  it("parses dd-hh:mm:ss format", () => expect(parseEtime("2-03:00:00")).toBe(183_600_000));
+  it("parses 1-00:00:00 as 1 day", () => expect(parseEtime("1-00:00:00")).toBe(86_400_000));
+  it("parses 00:05 as 5 seconds", () => expect(parseEtime("00:05")).toBe(5_000));
+  it("returns 0 for empty", () => expect(parseEtime("")).toBe(0));
+  it("returns 0 for whitespace", () => expect(parseEtime("   ")).toBe(0));
+  it("returns 0 for garbage", () => expect(parseEtime("not-a-time")).toBe(0));
+  it("returns 0 for single number (not a time)", () => expect(parseEtime("42")).toBe(0));
+});
+
+describe("isProcessRunning", () => {
+  it("uses tasklist on Windows and matches image name", () => {
+    const exec = vi.fn().mockReturnValue(
+      "Code.exe                    12345 Console                    1    50,000 K\n",
+    );
+    expect(isProcessRunning("Code.exe", { platform: "win32", exec })).toBe(true);
+    expect(exec.mock.calls[0][0]).toMatch(/tasklist\s+\/FI\s+"IMAGENAME eq Code\.exe"/);
+  });
+
+  it("returns false on Windows when image name is missing from output", () => {
+    const exec = vi.fn().mockReturnValue("INFO: No tasks are running.\n");
+    expect(isProcessRunning("Missing.exe", { platform: "win32", exec })).toBe(false);
+  });
+
+  it("uses pgrep on Unix and returns true when exit code is 0", () => {
+    const exec = vi.fn().mockReturnValue("12345\n");
+    expect(isProcessRunning("/Applications/Zed.app", { platform: "darwin", exec })).toBe(true);
+    expect(exec.mock.calls[0][0]).toMatch(/pgrep\s+-f\s+"\/Applications\/Zed\.app"/);
+  });
+
+  it("returns false on Unix when pgrep throws (no match)", () => {
+    const exec = vi.fn().mockImplementation(() => {
+      throw new Error("exit code 1");
+    });
+    expect(isProcessRunning("nothing", { platform: "linux", exec })).toBe(false);
+  });
+
+  it("returns false on any platform when exec throws unexpectedly", () => {
+    const exec = vi.fn().mockImplementation(() => {
+      throw new Error("boom");
+    });
+    expect(isProcessRunning("Code.exe", { platform: "win32", exec })).toBe(false);
+    expect(isProcessRunning("zed", { platform: "linux", exec })).toBe(false);
+  });
+});

package/packages/shared/src/__tests__/platform-process.test.ts

@@ -0,0 +1,160 @@
+/**
+ * Tests for packages/shared/src/platform/process.ts.
+ *
+ * Every helper accepts injectable `platform`, `exec`, and `kill` parameters,
+ * so no `Object.defineProperty(process, "platform", ...)` mutation is needed.
+ * See change: consolidate-platform-handlers.
+ */
+import { describe, it, expect, vi } from "vitest";
+import {
+  findPortHolders,
+  parseNetstatListeners,
+  isProcessAlive,
+  killProcess,
+  killPidWithGroup,
+} from "../platform/process.js";
+
+describe("parseNetstatListeners", () => {
+  const selfPid = 99999;
+
+  it("parses a Windows netstat listener", () => {
+    const output = [
+      "  Proto  Local Address     Foreign Address   State       PID",
+      "  TCP    0.0.0.0:8000      0.0.0.0:0         LISTENING   12345",
+    ].join("\r\n");
+    expect(parseNetstatListeners(output, 8000, selfPid)).toEqual([12345]);
+  });
+
+  it("excludes non-LISTENING rows", () => {
+    const output = "  TCP    0.0.0.0:8000    0.0.0.0:0    ESTABLISHED    1111";
+    expect(parseNetstatListeners(output, 8000, selfPid)).toEqual([]);
+  });
+
+  it("excludes 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", () => {
+    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",
+    ].join("\n");
+    expect(parseNetstatListeners(output, 8000, selfPid)).toEqual([1111]);
+  });
+
+  it("handles IPv6 addresses", () => {
+    const output = "  TCP    [::]:8000    [::]:0    LISTENING    7777";
+    expect(parseNetstatListeners(output, 8000, selfPid)).toEqual([7777]);
+  });
+});
+
+describe("findPortHolders", () => {
+  it("uses netstat when platform=win32 is injected", () => {
+    const exec = vi.fn().mockReturnValue(
+      "  TCP    0.0.0.0:8000    0.0.0.0:0    LISTENING    12345\n",
+    );
+    const result = findPortHolders(8000, { platform: "win32", exec });
+    expect(exec).toHaveBeenCalledOnce();
+    expect(exec.mock.calls[0][0]).toMatch(/netstat/i);
+    expect(result).toEqual([12345]);
+  });
+
+  it("uses lsof when platform=linux is injected", () => {
+    const exec = vi.fn().mockReturnValue("12345\n67890\n");
+    const result = findPortHolders(8000, { platform: "linux", exec });
+    expect(exec).toHaveBeenCalledOnce();
+    expect(exec.mock.calls[0][0]).toMatch(/lsof.*:8000/);
+    expect(result.sort()).toEqual([12345, 67890]);
+  });
+
+  it("returns [] on exec failure (best-effort)", () => {
+    const exec = vi.fn().mockImplementation(() => {
+      throw new Error("boom");
+    });
+    expect(findPortHolders(8000, { platform: "win32", exec })).toEqual([]);
+  });
+});
+
+describe("isProcessAlive", () => {
+  it("returns true when kill(pid, 0) succeeds", () => {
+    const kill = vi.fn().mockReturnValue(undefined);
+    expect(isProcessAlive(12345, { kill })).toBe(true);
+    expect(kill).toHaveBeenCalledWith(12345, 0);
+  });
+
+  it("returns false when kill(pid, 0) throws", () => {
+    const kill = vi.fn().mockImplementation(() => {
+      throw new Error("ESRCH");
+    });
+    expect(isProcessAlive(12345, { kill })).toBe(false);
+  });
+});
+
+describe("killProcess", () => {
+  it("uses taskkill on Windows", async () => {
+    const exec = vi.fn().mockReturnValue("");
+    const kill = vi.fn().mockReturnValue(undefined); // isProcessAlive → true
+    const result = await killProcess(12345, { platform: "win32", exec, kill });
+    expect(exec).toHaveBeenCalledWith(
+      expect.stringMatching(/taskkill\s+\/F\s+\/T\s+\/PID\s+12345/),
+      expect.any(Object),
+    );
+    expect(result).toEqual({ ok: true, forced: false });
+  });
+
+  it("returns { ok: false } when pid already dead", async () => {
+    const kill = vi.fn().mockImplementation(() => {
+      throw new Error("ESRCH");
+    });
+    const result = await killProcess(12345, { platform: "linux", kill });
+    expect(result).toEqual({ ok: false, forced: false });
+  });
+
+  it("sends SIGTERM on Unix and reports clean stop when process dies", async () => {
+    let aliveCount = 0;
+    const kill = vi.fn().mockImplementation((_pid, sig) => {
+      // isProcessAlive pre-check (signal 0) must succeed once to enter the branch
+      if (sig === 0) {
+        aliveCount++;
+        if (aliveCount === 1) return; // alive
+        throw new Error("ESRCH"); // dead after SIGTERM
+      }
+      if (sig === "SIGTERM") return;
+      throw new Error("unexpected signal");
+    });
+    const result = await killProcess(12345, { platform: "linux", kill, timeoutMs: 500 });
+    expect(kill).toHaveBeenCalledWith(12345, "SIGTERM");
+    expect(result).toEqual({ ok: true, forced: false });
+  });
+
+  it("forces SIGKILL when process survives SIGTERM", async () => {
+    const kill = vi.fn().mockImplementation((_pid, sig) => {
+      if (sig === 0) return; // always alive during polling
+      if (sig === "SIGTERM" || sig === "SIGKILL") return;
+    });
+    const result = await killProcess(12345, { platform: "linux", kill, timeoutMs: 300 });
+    expect(kill).toHaveBeenCalledWith(12345, "SIGKILL");
+    expect(result).toEqual({ ok: true, forced: true });
+  });
+});
+
+describe("killPidWithGroup", () => {
+  it("signals -pid on Unix (process group)", () => {
+    const kill = vi.fn();
+    killPidWithGroup(12345, "SIGTERM", { platform: "linux", kill });
+    expect(kill).toHaveBeenCalledWith(-12345, "SIGTERM");
+  });
+
+  it("signals +pid on Windows (no process groups)", () => {
+    const kill = vi.fn();
+    killPidWithGroup(12345, "SIGTERM", { platform: "win32", kill });
+    expect(kill).toHaveBeenCalledWith(12345, "SIGTERM");
+  });
+
+  it("signals -pid on macOS", () => {
+    const kill = vi.fn();
+    killPidWithGroup(99999, "SIGKILL", { platform: "darwin", kill });
+    expect(kill).toHaveBeenCalledWith(-99999, "SIGKILL");
+  });
+});

package/packages/shared/src/__tests__/platform-runner.test.ts

@@ -0,0 +1,173 @@
+/**
+ * Tests for packages/shared/src/platform/runner.ts — the Recipe engine.
+ * Uses real subprocess execution against node itself (always available)
+ * so we test the full pipeline: resolve → spawn → parse → Result.
+ *
+ * See change: platform-command-executor.
+ */
+import { describe, it, expect, beforeEach } from "vitest";
+import { run, unwrap, resetResolverCache, type Recipe } from "../platform/runner.js";
+
+// A trivial Recipe that runs `node --version` and returns the version string.
+const NODE_VERSION: Recipe<Record<string, never>, string> = {
+  argv: () => [process.execPath, "--version"],
+  parse: (stdout) => stdout.trim(),
+};
+
+// A Recipe that runs `node -e "process.exit(N)"` where N comes from input.
+const NODE_EXIT: Recipe<{ code: number }, string> = {
+  argv: ({ code }) => [process.execPath, "-e", `process.exit(${code})`],
+  parse: (stdout) => stdout.trim(),
+};
+
+// A Recipe that uses tolerate to accept exit 1.
+const NODE_EXIT_1_TOLERATED: Recipe<Record<string, never>, string> = {
+  argv: () => [process.execPath, "-e", "process.exit(1)"],
+  parse: (stdout) => stdout.trim() || "exited-1-but-ok",
+  tolerate: [1],
+};
+
+// A Recipe that times out (sleeps 10s, we allow 100ms).
+const NODE_SLEEP_LONG: Recipe<Record<string, never>, string> = {
+  argv: () => [process.execPath, "-e", "setTimeout(() => {}, 10000)"],
+  parse: (stdout) => stdout,
+  timeout: 100,
+};
+
+// A Recipe pointing at a binary that cannot be on PATH.
+const NONEXISTENT_BINARY: Recipe<Record<string, never>, string> = {
+  argv: () => ["this-binary-does-not-exist-12345abcde", "--help"],
+  parse: (stdout) => stdout,
+};
+
+describe("run()", () => {
+  beforeEach(() => {
+    resetResolverCache();
+  });
+
+  it("executes a successful recipe and returns parsed value", () => {
+    const result = run(NODE_VERSION, {});
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value).toMatch(/^v\d+\.\d+\.\d+/);
+    }
+  });
+
+  it("returns { ok: false, error: not-found } when binary is missing", () => {
+    const result = run(NONEXISTENT_BINARY, {});
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.kind).toBe("not-found");
+      if (result.error.kind === "not-found") {
+        expect(result.error.binary).toBe("this-binary-does-not-exist-12345abcde");
+      }
+    }
+  });
+
+  it("returns { ok: false, error: exit } when subprocess exits non-zero (not tolerated)", () => {
+    const result = run(NODE_EXIT, { code: 42 });
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.kind).toBe("exit");
+      if (result.error.kind === "exit") {
+        expect(result.error.code).toBe(42);
+      }
+    }
+  });
+
+  it("returns { ok: true } when non-zero exit code is in recipe.tolerate", () => {
+    const result = run(NODE_EXIT_1_TOLERATED, {});
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value).toBe("exited-1-but-ok");
+    }
+  });
+
+  it("returns { ok: false, error: timeout } when subprocess exceeds timeout", () => {
+    const result = run(NODE_SLEEP_LONG, {});
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.kind).toBe("timeout");
+      if (result.error.kind === "timeout") {
+        expect(result.error.timeoutMs).toBe(100);
+      }
+    }
+  }, 2000);
+
+  it("ctx.timeout overrides recipe.timeout", () => {
+    // Recipe says 100ms, context says 10s — a 500ms subprocess should succeed.
+    const FAST: Recipe<Record<string, never>, string> = {
+      argv: () => [process.execPath, "-e", "setTimeout(() => process.exit(0), 200)"],
+      parse: () => "ok",
+      timeout: 50, // would cause timeout without override
+    };
+    const result = run(FAST, {}, { timeout: 5000 });
+    expect(result.ok).toBe(true);
+  }, 10000);
+
+  it("caches binary resolution across calls", () => {
+    // First call resolves + caches
+    const a = run(NODE_VERSION, {});
+    expect(a.ok).toBe(true);
+    // Second call reuses cache — behavior identical
+    const b = run(NODE_VERSION, {});
+    expect(b.ok).toBe(true);
+  });
+
+  it("resetResolverCache forces re-resolution", () => {
+    const a = run(NODE_VERSION, {});
+    expect(a.ok).toBe(true);
+    resetResolverCache();
+    const b = run(NODE_VERSION, {});
+    expect(b.ok).toBe(true);
+  });
+
+  it("passes cwd from ctx to the subprocess", () => {
+    const PWD: Recipe<Record<string, never>, string> = {
+      argv: () => [process.execPath, "-e", "process.stdout.write(process.cwd())"],
+      parse: (out) => out.trim(),
+    };
+    const result = run(PWD, {}, { cwd: process.cwd() });
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      // Normalize separators for cross-platform comparison
+      const normalizedOut = result.value.replace(/\\/g, "/").toLowerCase();
+      const normalizedCwd = process.cwd().replace(/\\/g, "/").toLowerCase();
+      expect(normalizedOut).toBe(normalizedCwd);
+    }
+  });
+
+  it("passes env from ctx to the subprocess (merged over process.env)", () => {
+    const PRINT_ENV: Recipe<Record<string, never>, string> = {
+      argv: () => [process.execPath, "-e", "process.stdout.write(process.env.TEST_VAR_RUNNER || 'unset')"],
+      parse: (out) => out.trim(),
+    };
+    const result = run(PRINT_ENV, {}, { env: { TEST_VAR_RUNNER: "hello-from-ctx" } });
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value).toBe("hello-from-ctx");
+    }
+  });
+
+  it("rejects recipes with empty argv", () => {
+    const EMPTY: Recipe<Record<string, never>, string> = {
+      argv: () => [],
+      parse: () => "",
+    };
+    const result = run(EMPTY, {});
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.kind).toBe("spawn-failure");
+    }
+  });
+});
+
+describe("unwrap()", () => {
+  it("returns value on success", () => {
+    expect(unwrap({ ok: true, value: 42 }, 0)).toBe(42);
+  });
+
+  it("returns fallback on error", () => {
+    expect(unwrap({ ok: false, error: { kind: "not-found", binary: "x" } }, 99)).toBe(99);
+  });
+});