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

package/packages/shared/src/__tests__/resolve-tool-cli.test.ts

@@ -0,0 +1,105 @@
+/**
+ * Unit tests for the shell-callable resolver wrapper at
+ * `packages/shared/bin/pi-dashboard-resolve-tool.cjs`.
+ *
+ * We spawn the wrapper as a child process (matching its real-world use)
+ * and assert stdout/stderr/exit-code per the spec scenarios in
+ *   openspec/changes/register-build-time-tools/specs/tool-registry/spec.md
+ *
+ * See change: register-build-time-tools.
+ */
+import { describe, expect, it } from "vitest";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+import url from "node:url";
+
+const here = path.dirname(url.fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(here, "..", "..", "..", "..");
+const SCRIPT = path.join(
+  repoRoot,
+  "packages",
+  "shared",
+  "bin",
+  "pi-dashboard-resolve-tool.cjs",
+);
+
+function run(args: string[]) {
+  return spawnSync(process.execPath, [SCRIPT, ...args], {
+    cwd: repoRoot,
+    encoding: "utf8",
+    // Isolate from any user override file so tests are deterministic.
+    env: {
+      ...process.env,
+      // Point HOME at /tmp so ~/.pi/dashboard/tool-overrides.json is
+      // (almost certainly) absent, keeping the resolver in the
+      // bare-import branch.
+      HOME: "/tmp/pi-dashboard-resolve-tool-test",
+    },
+  });
+}
+
+describe("pi-dashboard-resolve-tool.cjs", () => {
+  it("prints absolute path to stdout for `electron`", () => {
+    const r = run(["electron"]);
+    expect(r.status).toBe(0);
+    expect(r.stdout.trim()).toMatch(/[\\/]node_modules[\\/]electron$/);
+    expect(r.stderr).toBe("");
+  });
+
+  it("prints absolute path to stdout for `node-pty`", () => {
+    const r = run(["node-pty"]);
+    expect(r.status).toBe(0);
+    expect(r.stdout.trim()).toMatch(/[\\/]node_modules[\\/]node-pty$/);
+    expect(r.stderr).toBe("");
+  });
+
+  it("emits JSON Resolution shape with --json", () => {
+    const r = run(["electron", "--json"]);
+    expect(r.status).toBe(0);
+    const parsed = JSON.parse(r.stdout);
+    expect(parsed.name).toBe("electron");
+    expect(parsed.ok).toBe(true);
+    expect(parsed.path).toMatch(/electron$/);
+    expect(parsed.source).toBe("bare-import");
+    expect(Array.isArray(parsed.tried)).toBe(true);
+    // First strategy attempted is `override`, then `bare-import`.
+    expect(parsed.tried.map((t: { strategy: string }) => t.strategy)).toEqual([
+      "override",
+      "bare-import",
+    ]);
+    expect(typeof parsed.resolvedAt).toBe("number");
+  });
+
+  it("exits 1 with stderr when tool name is unknown", () => {
+    const r = run(["nonexistent-tool"]);
+    expect(r.status).toBe(1);
+    expect(r.stdout).toBe("");
+    expect(r.stderr).toContain("nonexistent-tool");
+    expect(r.stderr).toContain("not registered");
+  });
+
+  it("exits 1 with stderr when --json is passed for unknown tool", () => {
+    const r = run(["nonexistent-tool", "--json"]);
+    expect(r.status).toBe(1);
+    expect(r.stderr).toContain("not registered");
+  });
+
+  it("exits 1 with usage message when no tool name given", () => {
+    const r = run([]);
+    expect(r.status).toBe(1);
+    expect(r.stderr).toContain("usage:");
+    expect(r.stderr).toContain("registered:");
+  });
+
+  it("strategy chain order in --json mirrors definitions.ts", () => {
+    // Both build-time tools share the same chain shape: override → bare-import.
+    for (const tool of ["electron", "node-pty"]) {
+      const r = run([tool, "--json"]);
+      expect(r.status).toBe(0);
+      const parsed = JSON.parse(r.stdout);
+      expect(
+        parsed.tried.map((t: { strategy: string }) => t.strategy),
+      ).toEqual(["override", "bare-import"]);
+    }
+  });
+});

package/packages/shared/src/__tests__/semaphore.test.ts

@@ -0,0 +1,119 @@
+import { describe, it, expect } from "vitest";
+import { createSemaphore } from "../semaphore.js";
+
+function defer<T = void>(): { promise: Promise<T>; resolve: (v: T) => void; reject: (e: any) => void } {
+  let resolve!: (v: T) => void;
+  let reject!: (e: any) => void;
+  const promise = new Promise<T>((res, rej) => { resolve = res; reject = rej; });
+  return { promise, resolve, reject };
+}
+
+describe("createSemaphore", () => {
+  it("throws when max < 1", () => {
+    expect(() => createSemaphore(0)).toThrow();
+    expect(() => createSemaphore(-1)).toThrow();
+  });
+
+  it("runs tasks immediately up to the cap", async () => {
+    const sem = createSemaphore(2);
+    const a = defer<string>();
+    const b = defer<string>();
+    const pa = sem.run(() => a.promise);
+    const pb = sem.run(() => b.promise);
+    expect(sem.size()).toBe(2);
+    a.resolve("a");
+    b.resolve("b");
+    expect(await pa).toBe("a");
+    expect(await pb).toBe("b");
+    expect(sem.size()).toBe(0);
+  });
+
+  it("caps concurrency: third task waits", async () => {
+    const sem = createSemaphore(2);
+    const a = defer<string>();
+    const b = defer<string>();
+    const c = defer<string>();
+
+    let cStarted = false;
+    const pa = sem.run(() => a.promise);
+    const pb = sem.run(() => b.promise);
+    const pc = sem.run(() => { cStarted = true; return c.promise; });
+
+    // Wait a microtask for queue placement
+    await Promise.resolve();
+    expect(cStarted).toBe(false);
+    expect(sem.size()).toBe(3); // active + queued
+
+    a.resolve("a");
+    await pa;
+    // c should now be started
+    await Promise.resolve();
+    expect(cStarted).toBe(true);
+    b.resolve("b");
+    c.resolve("c");
+    expect(await pb).toBe("b");
+    expect(await pc).toBe("c");
+  });
+
+  it("FIFO order of queued tasks", async () => {
+    const sem = createSemaphore(1);
+    const order: string[] = [];
+    const blockers = [defer<void>(), defer<void>(), defer<void>()];
+    const ps = blockers.map((d, i) =>
+      sem.run(async () => { order.push(`start-${i}`); await d.promise; order.push(`end-${i}`); }),
+    );
+    await Promise.resolve();
+    blockers[0].resolve(); await ps[0];
+    blockers[1].resolve(); await ps[1];
+    blockers[2].resolve(); await ps[2];
+    expect(order).toEqual(["start-0", "end-0", "start-1", "end-1", "start-2", "end-2"]);
+  });
+
+  it("releases slot on reject so queued tasks still run", async () => {
+    const sem = createSemaphore(1);
+    const failed = sem.run(async () => { throw new Error("boom"); });
+    await expect(failed).rejects.toThrow("boom");
+    const ok = sem.run(async () => "ok");
+    expect(await ok).toBe("ok");
+  });
+
+  it("setMax increases cap and drains queued tasks immediately", async () => {
+    const sem = createSemaphore(1);
+    const a = defer<void>();
+    const b = defer<void>();
+    let bStarted = false;
+    const pa = sem.run(() => a.promise);
+    const pb = sem.run(() => { bStarted = true; return b.promise; });
+    await Promise.resolve();
+    expect(bStarted).toBe(false);
+
+    sem.setMax(2);
+    await Promise.resolve();
+    expect(bStarted).toBe(true);
+
+    a.resolve(); b.resolve();
+    await pa; await pb;
+  });
+
+  it("setMax shrinking does not interrupt in-flight tasks but caps new ones", async () => {
+    const sem = createSemaphore(3);
+    const a = defer<void>();
+    const b = defer<void>();
+    const pa = sem.run(() => a.promise);
+    const pb = sem.run(() => b.promise);
+
+    sem.setMax(1);
+    const c = defer<void>();
+    let cStarted = false;
+    const pc = sem.run(() => { cStarted = true; return c.promise; });
+    await Promise.resolve();
+    expect(cStarted).toBe(false);
+
+    a.resolve(); b.resolve();
+    await pa; await pb;
+    await Promise.resolve();
+    expect(cStarted).toBe(true);
+    c.resolve();
+    await pc;
+  });
+});

package/packages/shared/src/__tests__/spawn-mechanism.test.ts

@@ -0,0 +1,131 @@
+/**
+ * Tests for platform/spawn-mechanism.ts pure selector + argv builders.
+ *
+ * Every test passes `platform` explicitly. Never mutates process.platform.
+ */
+import { describe, it, expect } from "vitest";
+import {
+  selectMechanism,
+  buildWtArgs,
+  sessionFlagsToArgv,
+  type SpawnMechanismContext,
+} from "../platform/spawn-mechanism.js";
+
+function ctx(overrides: Partial<SpawnMechanismContext> = {}): SpawnMechanismContext {
+  return {
+    platform: "linux",
+    userStrategy: "tmux",
+    electronMode: false,
+    available: { tmux: false, wt: false, wslTmux: false },
+    ...overrides,
+  };
+}
+
+describe("selectMechanism", () => {
+  it("electron mode always returns headless", () => {
+    expect(selectMechanism(ctx({ electronMode: true, platform: "win32", available: { tmux: false, wt: true, wslTmux: true } }))).toBe("headless");
+    expect(selectMechanism(ctx({ electronMode: true, platform: "linux", available: { tmux: true, wt: false, wslTmux: false } }))).toBe("headless");
+    expect(selectMechanism(ctx({ electronMode: true, platform: "darwin", available: { tmux: true, wt: false, wslTmux: false } }))).toBe("headless");
+  });
+
+  it("userStrategy headless always returns headless", () => {
+    expect(selectMechanism(ctx({ userStrategy: "headless", platform: "win32", available: { tmux: false, wt: true, wslTmux: true } }))).toBe("headless");
+    expect(selectMechanism(ctx({ userStrategy: "headless", platform: "linux", available: { tmux: true, wt: false, wslTmux: false } }))).toBe("headless");
+  });
+
+  it("Linux with tmux returns tmux", () => {
+    expect(selectMechanism(ctx({ platform: "linux", available: { tmux: true, wt: false, wslTmux: false } }))).toBe("tmux");
+  });
+
+  it("macOS with tmux returns tmux", () => {
+    expect(selectMechanism(ctx({ platform: "darwin", available: { tmux: true, wt: false, wslTmux: false } }))).toBe("tmux");
+  });
+
+  it("Linux without tmux returns headless", () => {
+    expect(selectMechanism(ctx({ platform: "linux", available: { tmux: false, wt: false, wslTmux: false } }))).toBe("headless");
+  });
+
+  it("Windows with wt returns wt", () => {
+    expect(selectMechanism(ctx({ platform: "win32", available: { tmux: false, wt: true, wslTmux: false } }))).toBe("wt");
+  });
+
+  it("Windows with wt AND wsl-tmux prefers wt", () => {
+    expect(selectMechanism(ctx({ platform: "win32", available: { tmux: false, wt: true, wslTmux: true } }))).toBe("wt");
+  });
+
+  it("Windows with only wsl-tmux returns wsl-tmux", () => {
+    expect(selectMechanism(ctx({ platform: "win32", available: { tmux: false, wt: false, wslTmux: true } }))).toBe("wsl-tmux");
+  });
+
+  it("Windows with nothing available returns headless", () => {
+    expect(selectMechanism(ctx({ platform: "win32", available: { tmux: false, wt: false, wslTmux: false } }))).toBe("headless");
+  });
+
+  it("unknown platform falls back to headless", () => {
+    expect(selectMechanism(ctx({ platform: "openbsd" as NodeJS.Platform, available: { tmux: true, wt: false, wslTmux: false } }))).toBe("headless");
+  });
+});
+
+describe("buildWtArgs", () => {
+  it("produces argv in expected order", () => {
+    const argv = buildWtArgs({
+      cwd: "C:\\proj",
+      title: "proj",
+      piArgv: ["C:\\node.exe", "cli.js", "--mode", "rpc"],
+    });
+    expect(argv).toEqual([
+      "-w", "0",
+      "new-tab",
+      "-d", "C:\\proj",
+      "--title", "proj",
+      "--",
+      "C:\\node.exe", "cli.js", "--mode", "rpc",
+    ]);
+  });
+
+  it("preserves cwd with spaces as a single argv element", () => {
+    const argv = buildWtArgs({
+      cwd: "C:\\Users\\Bob's Project (2)",
+      title: "x",
+      piArgv: ["pi"],
+    });
+    expect(argv).toContain("C:\\Users\\Bob's Project (2)");
+    expect(argv.filter(a => a.includes("Bob"))).toHaveLength(1);
+  });
+
+  it("places piArgv after -- sentinel with --fork intact", () => {
+    const argv = buildWtArgs({
+      cwd: "C:\\proj",
+      title: "proj",
+      piArgv: ["node.exe", "cli.js", "--fork", "C:\\x\\session.jsonl"],
+    });
+    const sentinelIdx = argv.indexOf("--");
+    expect(sentinelIdx).toBeGreaterThan(0);
+    expect(argv.slice(sentinelIdx + 1)).toEqual(["node.exe", "cli.js", "--fork", "C:\\x\\session.jsonl"]);
+  });
+
+  it("never includes -p profile flag", () => {
+    const argv = buildWtArgs({ cwd: "C:\\x", title: "y", piArgv: ["pi"] });
+    expect(argv).not.toContain("-p");
+  });
+});
+
+describe("sessionFlagsToArgv", () => {
+  it("returns --session file for continue mode", () => {
+    expect(sessionFlagsToArgv({ sessionFile: "/s/abc.jsonl", mode: "continue" })).toEqual(["--session", "/s/abc.jsonl"]);
+  });
+
+  it("returns --fork file for fork mode", () => {
+    expect(sessionFlagsToArgv({ sessionFile: "C:\\s\\abc.jsonl", mode: "fork" })).toEqual(["--fork", "C:\\s\\abc.jsonl"]);
+  });
+
+  it("returns empty array with no file", () => {
+    expect(sessionFlagsToArgv({})).toEqual([]);
+    expect(sessionFlagsToArgv({ mode: "continue" })).toEqual([]);
+    expect(sessionFlagsToArgv({ mode: "fork" })).toEqual([]);
+  });
+
+  it("returns empty array with file but no mode", () => {
+    expect(sessionFlagsToArgv({ sessionFile: "/s/x.jsonl" })).toEqual([]);
+  });
+});

package/packages/shared/src/__tests__/state-replay-entry-id.test.ts

@@ -0,0 +1,69 @@
+/**
+ * Round-trip test for state-replay (per change: fix-per-message-fork):
+ * for every persisted entry, the reducer-equivalent message_start /
+ * message_end carries entryId === entry.id. Replay does NOT need
+ * entry_persisted back-fill because it reads from the persisted JSONL.
+ */
+import { describe, it, expect } from "vitest";
+import { replayEntriesAsEvents } from "../state-replay.js";
+
+describe("replayEntriesAsEvents — entryId fidelity", () => {
+  it("stamps entryId on user message_start matching the source entry id", () => {
+    const sessionId = "sess-1";
+    const entries = [
+      {
+        type: "message",
+        id: "u1",
+        parentId: "root",
+        timestamp: "2026-04-27T07:26:25.000Z",
+        message: { role: "user", content: [{ type: "text", text: "Hello" }] },
+      },
+    ];
+
+    const events = replayEntriesAsEvents(sessionId, entries);
+    const start = events.find((e) => e.event.eventType === "message_start");
+    expect(start).toBeDefined();
+    expect((start!.event.data as any).entryId).toBe("u1");
+  });
+
+  it("stamps entryId on assistant message_end matching the source entry id", () => {
+    const sessionId = "sess-1";
+    const entries = [
+      {
+        type: "message",
+        id: "a1",
+        parentId: "u1",
+        timestamp: "2026-04-27T07:26:30.000Z",
+        message: { role: "assistant", content: [{ type: "text", text: "Hi!" }] },
+      },
+    ];
+
+    const events = replayEntriesAsEvents(sessionId, entries);
+    const end = events.find((e) => e.event.eventType === "message_end");
+    expect(end).toBeDefined();
+    expect((end!.event.data as any).entryId).toBe("a1");
+  });
+
+  it("emits no entry_persisted events during replay", () => {
+    const sessionId = "sess-1";
+    const entries = [
+      {
+        type: "message",
+        id: "u1",
+        timestamp: "2026-04-27T07:26:25.000Z",
+        message: { role: "user", content: [{ type: "text", text: "Hi" }] },
+      },
+      {
+        type: "message",
+        id: "a1",
+        parentId: "u1",
+        timestamp: "2026-04-27T07:26:30.000Z",
+        message: { role: "assistant", content: [{ type: "text", text: "Hello!" }] },
+      },
+    ];
+
+    const events = replayEntriesAsEvents(sessionId, entries);
+    const persisted = events.filter((e) => e.event.eventType === "entry_persisted");
+    expect(persisted).toHaveLength(0);
+  });
+});

package/packages/shared/src/__tests__/tool-registry-definitions.test.ts

@@ -0,0 +1,239 @@
+/**
+ * Tests for the standard tool definitions (strategies + registration).
+ *
+ * We inject fake `exists` / `which` / `npmRootGlobal` so tests are
+ * deterministic across platforms and don't depend on the test host's
+ * real filesystem or PATH.
+ */
+import { describe, it, expect } from "vitest";
+import path from "node:path";
+import os from "node:os";
+import {
+  ToolRegistry,
+  registerDefaultTools,
+  OverridesStore,
+} from "../tool-registry/index.js";
+
+function freshRegistry(opts: {
+  exists?: (p: string) => boolean;
+  which?: (name: string) => string | null;
+  npmRootGlobal?: () => string;
+  overrides?: Record<string, string>;
+  platform?: NodeJS.Platform;
+}) {
+  const store = new OverridesStore({
+    filePath: path.join(os.tmpdir(), `tool-registry-test-${Math.random()}.json`),
+    warn: () => {},
+  });
+  for (const [k, v] of Object.entries(opts.overrides ?? {})) store.set(k, v);
+
+  const r = new ToolRegistry({
+    overrides: store,
+    platform: opts.platform ?? "linux",
+  });
+  registerDefaultTools(r, {
+    exists: opts.exists ?? (() => false),
+    which: opts.which ?? (() => null),
+    npmRootGlobal: opts.npmRootGlobal ?? (() => ""),
+  });
+  return r;
+}
+
+describe("pi binary definition", () => {
+  it("chain order: override → managed → where", () => {
+    const r = freshRegistry({ which: (n) => (n === "pi" ? "/usr/bin/pi" : null) });
+    const res = r.resolve("pi");
+    expect(res.tried.map((t) => t.strategy)).toEqual([
+      "override",
+      "managed",
+      "where",
+    ]);
+    expect(res.ok).toBe(true);
+    expect(res.path).toBe("/usr/bin/pi");
+    expect(res.source).toBe("system");
+  });
+
+  it("managed wins over system when MANAGED_BIN/pi exists", () => {
+    const managed = path.join(os.homedir(), ".pi-dashboard", "node_modules", ".bin", "pi");
+    const r = freshRegistry({
+      exists: (p) => p === managed,
+      which: () => "/usr/bin/pi",
+      platform: "linux",
+    });
+    const res = r.resolve("pi");
+    expect(res.ok).toBe(true);
+    expect(res.path).toBe(managed);
+    expect(res.source).toBe("managed");
+  });
+
+  it("picks .cmd extension on Windows", () => {
+    const managed = path.join(os.homedir(), ".pi-dashboard", "node_modules", ".bin", "pi.cmd");
+    const r = freshRegistry({
+      exists: (p) => p === managed,
+      platform: "win32",
+    });
+    const res = r.resolve("pi");
+    expect(res.ok).toBe(true);
+    expect(res.path).toBe(managed);
+  });
+
+  it("override wins when set and path exists", () => {
+    const custom = "/opt/custom/pi";
+    const r = freshRegistry({
+      overrides: { pi: custom },
+      exists: (p) => p === custom, // validate() passes
+    });
+    const res = r.resolve("pi");
+    expect(res.ok).toBe(true);
+    expect(res.path).toBe(custom);
+    expect(res.source).toBe("override");
+  });
+
+  it("invalid override falls through to next strategy with 'invalid:' reason", () => {
+    const r = freshRegistry({
+      overrides: { pi: "/does/not/exist" },
+      which: () => "/usr/bin/pi",
+      exists: (p) => p === "/usr/bin/pi", // override path fails validate
+    });
+    const res = r.resolve("pi");
+    expect(res.ok).toBe(true);
+    expect(res.source).toBe("system");
+    expect(res.tried[0].strategy).toBe("override");
+    expect(res.tried[0].result).toMatch(/^invalid:/);
+  });
+});
+
+describe("pi-coding-agent module definition", () => {
+  it("probes both @mariozechner and @oh-my-pi alias names", () => {
+    const r = freshRegistry({ exists: () => false });
+    const res = r.resolve("pi-coding-agent");
+    const names = res.tried.map((t) => t.strategy);
+    // First strategy: override. Then two bare-import (one per alias),
+    // then two managed, then two npm-global.
+    expect(names[0]).toBe("override");
+    expect(names.filter((n) => n === "bare-import").length).toBe(2);
+    expect(names.filter((n) => n === "managed").length).toBe(2);
+    expect(names.filter((n) => n === "npm-global").length).toBe(2);
+  });
+
+  it("managed strategy hits ~/.pi-dashboard/node_modules/<pkg>/dist/index.js", () => {
+    const managed = path.join(
+      os.homedir(), ".pi-dashboard", "node_modules",
+      "@mariozechner", "pi-coding-agent", "dist", "index.js",
+    );
+    const r = freshRegistry({ exists: (p) => p === managed });
+    const res = r.resolve("pi-coding-agent");
+    expect(res.ok).toBe(true);
+    expect(res.path).toBe(managed);
+    expect(res.source).toBe("managed");
+  });
+
+  it("npm-global strategy uses <npm root -g>/<pkg>/dist/index.js", () => {
+    const npmRoot = "/npm/global/root";
+    const entry = path.join(npmRoot, "@mariozechner", "pi-coding-agent", "dist", "index.js");
+    const r = freshRegistry({
+      exists: (p) => p === entry,
+      npmRootGlobal: () => npmRoot,
+    });
+    const res = r.resolve("pi-coding-agent");
+    expect(res.ok).toBe(true);
+    expect(res.path).toBe(entry);
+    expect(res.source).toBe("npm-global");
+  });
+
+  it("fails cleanly when no strategy succeeds", () => {
+    const r = freshRegistry({
+      exists: () => false,
+      npmRootGlobal: () => "",
+    });
+    const res = r.resolve("pi-coding-agent");
+    expect(res.ok).toBe(false);
+    expect(res.path).toBeNull();
+    expect(res.source).toBeNull();
+    // Trail should include override + 2 bare-import + 2 managed + 2 npm-global.
+    expect(res.tried.length).toBeGreaterThanOrEqual(5);
+    expect(res.tried.some((t) => t.strategy === "npm-global")).toBe(true);
+  });
+});
+
+describe("openspec binary definition", () => {
+  it("finds openspec.cmd under managed bin on Windows", () => {
+    const managed = path.join(os.homedir(), ".pi-dashboard", "node_modules", ".bin", "openspec.cmd");
+    const r = freshRegistry({ exists: (p) => p === managed, platform: "win32" });
+    const res = r.resolve("openspec");
+    expect(res.ok).toBe(true);
+    expect(res.path).toBe(managed);
+  });
+
+  it("falls through managed → where on Unix when managed is absent", () => {
+    const r = freshRegistry({
+      exists: () => false,
+      which: (n) => (n === "openspec" ? "/usr/local/bin/openspec" : null),
+      platform: "darwin",
+    });
+    const res = r.resolve("openspec");
+    expect(res.ok).toBe(true);
+    expect(res.source).toBe("system");
+    expect(res.path).toBe("/usr/local/bin/openspec");
+  });
+});
+
+describe("registered tool set", () => {
+  it("registers pi, pi-coding-agent, openspec, npm, node, git, zrok, wt", () => {
+    const r = freshRegistry({});
+    for (const name of ["pi", "pi-coding-agent", "openspec", "npm", "node", "git", "zrok", "wt"]) {
+      expect(r.has(name)).toBe(true);
+    }
+  });
+
+  it("wt resolves via where when found", () => {
+    const r = freshRegistry({
+      platform: "win32",
+      which: (name) => (name === "wt" ? "C:\\WindowsApps\\wt.exe" : null),
+    });
+    const res = r.resolve("wt");
+    expect(res.ok).toBe(true);
+    expect(res.path).toBe("C:\\WindowsApps\\wt.exe");
+    expect(res.source).toBe("system");
+  });
+
+  it("wt unavailable returns ok:false without error", () => {
+    const r = freshRegistry({ platform: "win32", which: () => null });
+    const res = r.resolve("wt");
+    expect(res.ok).toBe(false);
+  });
+
+  it("does NOT register tsx (it's a loader, not a spawn target)", () => {
+    const r = freshRegistry({});
+    expect(r.has("tsx")).toBe(false);
+  });
+
+  it("registers Windows-only process utilities on win32, NOT ps/pgrep", () => {
+    const r = freshRegistry({ platform: "win32" });
+    expect(r.has("tasklist")).toBe(true);
+    expect(r.has("taskkill")).toBe(true);
+    expect(r.has("wmic")).toBe(true);
+    expect(r.has("powershell")).toBe(true);
+    // ps/pgrep are POSIX-only; they'd always show "not found" on Windows
+    // and pollute the Tools UI with red rows the code never calls.
+    expect(r.has("ps")).toBe(false);
+    expect(r.has("pgrep")).toBe(false);
+  });
+
+  it("registers POSIX process utilities on linux/darwin, NOT tasklist etc.", () => {
+    for (const platform of ["linux", "darwin"] as NodeJS.Platform[]) {
+      const r = freshRegistry({ platform });
+      expect(r.has("ps")).toBe(true);
+      expect(r.has("pgrep")).toBe(true);
+      expect(r.has("tasklist")).toBe(false);
+      expect(r.has("taskkill")).toBe(false);
+      expect(r.has("wmic")).toBe(false);
+      expect(r.has("powershell")).toBe(false);
+    }
+  });
+
+  it("does NOT register pi-dashboard (it's the package this code is part of)", () => {
+    const r = freshRegistry({});
+    expect(r.has("pi-dashboard")).toBe(false);
+  });
+});