@ai-devkit/agent-manager 0.31.0 → 0.33.0

package/src/__tests__/providers/pi/PiAdapter.test.ts

@@ -0,0 +1,310 @@
+/**
+ * Tests for PiAdapter provider orchestration.
+ */
+
+import type { MockedFunction } from "vitest";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+
+import { AgentStatus, type ProcessInfo } from "../../../adapters/AgentAdapter.js";
+import { PiAdapter } from "../../../providers/pi/PiAdapter.js";
+import { AgentRegistry } from "../../../utils/AgentRegistry.js";
+import { captureProcessSnapshot } from "../../../utils/process.js";
+import { generateAgentName, matchProcessesToSessions } from "../../../utils/matching.js";
+
+vi.mock("../../../utils/process.js", async (importOriginal) => {
+  const actual = (await importOriginal()) as typeof import("../../../utils/process.js");
+  return {
+    ...actual,
+    captureProcessSnapshot: vi.fn(),
+  };
+});
+
+vi.mock("../../../utils/matching.js", () => ({
+  matchProcessesToSessions: vi.fn(),
+  generateAgentName: vi.fn(),
+}));
+
+const mockedCaptureProcessSnapshot = captureProcessSnapshot as MockedFunction<
+  typeof captureProcessSnapshot
+>;
+const mockedMatchProcessesToSessions = matchProcessesToSessions as MockedFunction<
+  typeof matchProcessesToSessions
+>;
+const mockedGenerateAgentName = generateAgentName as MockedFunction<typeof generateAgentName>;
+
+describe("PiAdapter", () => {
+  let adapter: PiAdapter;
+  let tmpHome: string;
+  let sessionsDir: string;
+
+  beforeEach(() => {
+    tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "pi-adapter-test-"));
+    process.env.HOME = tmpHome;
+    sessionsDir = path.join(tmpHome, ".pi", "agent", "sessions");
+    fs.mkdirSync(sessionsDir, { recursive: true });
+
+    adapter = new PiAdapter(new AgentRegistry(path.join(tmpHome, "agents.json")));
+    mockedCaptureProcessSnapshot.mockReset();
+    mockedMatchProcessesToSessions.mockReset();
+    mockedGenerateAgentName.mockReset();
+
+    mockedCaptureProcessSnapshot.mockResolvedValue([]);
+    mockedMatchProcessesToSessions.mockReturnValue([]);
+    mockedGenerateAgentName.mockImplementation((cwd: string, pid: number) => {
+      const folder = path.basename(cwd) || "unknown";
+      return `${folder} (${pid})`;
+    });
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpHome, { recursive: true, force: true });
+  });
+
+  it("exposes pi type", () => {
+    expect(adapter.type).toBe("pi");
+  });
+
+  it("identifies Pi commands without matching unrelated paths", () => {
+    expect(adapter.canHandle({ pid: 1, command: "pi", cwd: "/repo", tty: "ttys001" })).toBe(true);
+    expect(
+      adapter.canHandle({
+        pid: 2,
+        command: "/usr/local/bin/PI --model x",
+        cwd: "/repo",
+        tty: "ttys002",
+      }),
+    ).toBe(true);
+    expect(
+      adapter.canHandle({
+        pid: 3,
+        command: "node /opt/pi/bin/pi.js",
+        cwd: "/repo",
+        tty: "ttys003",
+      }),
+    ).toBe(true);
+    expect(
+      adapter.canHandle({
+        pid: 4,
+        command: "node /repo/feature-pi-adapter/script.js",
+        cwd: "/repo",
+        tty: "ttys004",
+      }),
+    ).toBe(false);
+    expect(
+      adapter.canHandle({
+        pid: 5,
+        command: "C:\\tools\\node.exe C:\\lib\\pi.js",
+        cwd: "/repo",
+        tty: "ttys005",
+      }),
+    ).toBe(true);
+  });
+
+  it("rejects foreign executables from a hand-built snapshot context", async () => {
+    const foreign: ProcessInfo = {
+      pid: 6,
+      command: "claude --resume /Users/x/repos/pi/session.jsonl",
+      cwd: "/repo",
+      tty: "ttys006",
+    };
+
+    expect(await adapter.detectAgents({ processes: [foreign] })).toEqual([]);
+  });
+
+  it("maps a running Pi process to the tracker session for its PID", async () => {
+    const cwd = "/repo/project-a";
+    const proc = makeProcess({ pid: 101, cwd });
+    const sessionFile = writePiSession(cwd, [
+      { type: "session_meta", timestamp: "2026-06-10T08:58:20.754Z", sessionId: "sess-101", cwd },
+      { role: "user", timestamp: "2026-06-10T08:58:21.000Z", content: "implement Pi adapter" },
+      { role: "assistant", timestamp: new Date().toISOString(), content: "working on it" },
+    ]);
+    writeTracker({ 101: sessionFile });
+    mockedCaptureProcessSnapshot.mockResolvedValue([proc]);
+
+    const agents = await adapter.detectAgents();
+
+    expect(agents).toHaveLength(1);
+    expect(agents[0]).toMatchObject({
+      type: "pi",
+      pid: 101,
+      projectPath: cwd,
+      sessionId: "sess-101",
+      summary: "implement Pi adapter",
+      status: AgentStatus.WAITING,
+      sessionFilePath: sessionFile,
+    });
+    expect(mockedMatchProcessesToSessions).not.toHaveBeenCalled();
+  });
+
+  it("falls back to legacy matching when sessions.json is missing", async () => {
+    const cwd = "/repo/project-b";
+    const proc = makeProcess({ pid: 202, cwd });
+    const sessionFile = writePiSession(cwd, [
+      { timestamp: "2026-06-10T08:58:20.754Z", sessionId: "sess-202" },
+      { role: "user", timestamp: "2026-06-10T08:58:21.000Z", content: "fallback matching please" },
+    ]);
+    mockedCaptureProcessSnapshot.mockResolvedValue([proc]);
+    mockedMatchProcessesToSessions.mockReturnValue([
+      {
+        process: proc,
+        session: {
+          sessionId: "sess-202",
+          filePath: sessionFile,
+          projectDir: path.dirname(sessionFile),
+          birthtimeMs: Date.now(),
+          resolvedCwd: cwd,
+        },
+        deltaMs: 0,
+      },
+    ]);
+
+    const agents = await adapter.detectAgents();
+
+    expect(agents).toHaveLength(1);
+    expect(agents[0]).toMatchObject({
+      type: "pi",
+      pid: 202,
+      projectPath: cwd,
+      sessionId: "sess-202",
+      summary: "fallback matching please",
+    });
+    expect(mockedMatchProcessesToSessions).toHaveBeenCalledWith(
+      [proc],
+      expect.arrayContaining([
+        expect.objectContaining({ filePath: sessionFile, resolvedCwd: cwd }),
+      ]),
+    );
+  });
+
+  it("falls back to legacy matching when a trusted tracker session is unparseable", async () => {
+    const cwd = "/repo/project-bad-tracker-session";
+    const proc = makeProcess({ pid: 304, cwd });
+    const badSessionFile = writePiSessionWithFileName(cwd, "bad.jsonl", ["{not json"]);
+    const fallbackSessionFile = writePiSession(cwd, [
+      { timestamp: "2026-06-10T08:58:20.754Z", sessionId: "sess-304", cwd },
+      {
+        role: "user",
+        timestamp: "2026-06-10T08:58:21.000Z",
+        content: "fallback after bad tracker session",
+      },
+    ]);
+    writeTracker({ 304: badSessionFile });
+    mockedCaptureProcessSnapshot.mockResolvedValue([proc]);
+    mockedMatchProcessesToSessions.mockReturnValue([
+      {
+        process: proc,
+        session: {
+          sessionId: "sess-304",
+          filePath: fallbackSessionFile,
+          projectDir: path.dirname(fallbackSessionFile),
+          birthtimeMs: Date.now(),
+          resolvedCwd: cwd,
+        },
+        deltaMs: 0,
+      },
+    ]);
+
+    const agents = await adapter.detectAgents();
+
+    expect(agents).toHaveLength(1);
+    expect(agents[0]).toMatchObject({
+      sessionId: "sess-304",
+      summary: "fallback after bad tracker session",
+      sessionFilePath: fallbackSessionFile,
+    });
+    expect(mockedMatchProcessesToSessions).toHaveBeenCalled();
+  });
+
+  it("returns a process-only agent when no session can be matched", async () => {
+    const proc = makeProcess({ pid: 505, cwd: "/repo/project-e" });
+    mockedCaptureProcessSnapshot.mockResolvedValue([proc]);
+
+    const agents = await adapter.detectAgents();
+
+    expect(agents).toHaveLength(1);
+    expect(agents[0]).toMatchObject({
+      type: "pi",
+      status: AgentStatus.RUNNING,
+      pid: 505,
+      projectPath: "/repo/project-e",
+      sessionId: "pid-505",
+      summary: "Pi process running",
+    });
+  });
+
+  it("lists historical sessions and applies cwd filtering", async () => {
+    const matchingCwd = "/repo/project-g";
+    const otherCwd = "/repo/project-h";
+    const matchingSession = writePiSession(matchingCwd, [
+      { timestamp: "2026-06-10T08:58:20.754Z", sessionId: "sess-g", cwd: matchingCwd },
+      { role: "user", timestamp: "2026-06-10T08:58:21.000Z", content: "first matching message" },
+    ]);
+    writePiSession(otherCwd, [
+      { timestamp: "2026-06-10T08:58:20.754Z", sessionId: "sess-h", cwd: otherCwd },
+      { role: "user", timestamp: "2026-06-10T08:58:21.000Z", content: "other message" },
+    ]);
+
+    const sessions = await adapter.listSessions({ cwd: matchingCwd });
+
+    expect(sessions).toEqual([
+      expect.objectContaining({
+        type: "pi",
+        sessionId: "sess-g",
+        cwd: matchingCwd,
+        firstUserMessage: "first matching message",
+        sessionFilePath: matchingSession,
+      }),
+    ]);
+  });
+
+  function makeProcess(overrides: Partial<ProcessInfo>): ProcessInfo {
+    return {
+      pid: 1,
+      command: "pi",
+      cwd: "/repo",
+      tty: "ttys001",
+      startTime: new Date("2026-06-10T08:58:20.000Z"),
+      ...overrides,
+    };
+  }
+
+  function writeTracker(entries: Record<number, string>): void {
+    fs.writeFileSync(path.join(tmpHome, ".pi", "agent", "sessions.json"), JSON.stringify(entries));
+  }
+
+  function writePiSession(cwd: string, entries: Array<Record<string, unknown> | string>): string {
+    const sessionId =
+      entries
+        .map((entry) => (typeof entry === "string" ? undefined : entry.sessionId))
+        .find((value): value is string => typeof value === "string") ?? cryptoRandomSessionId();
+    return writePiSessionWithFileName(cwd, `2026-06-10T08-58-20-754Z_${sessionId}.jsonl`, entries);
+  }
+
+  function writePiSessionWithFileName(
+    cwd: string,
+    fileName: string,
+    entries: Array<Record<string, unknown> | string>,
+  ): string {
+    const projectDir = path.join(sessionsDir, encodeProjectDir(cwd));
+    fs.mkdirSync(projectDir, { recursive: true });
+    const filePath = path.join(projectDir, fileName);
+    fs.writeFileSync(
+      filePath,
+      entries
+        .map((entry) => (typeof entry === "string" ? entry : JSON.stringify(entry)))
+        .join("\n"),
+    );
+    return filePath;
+  }
+});
+
+function encodeProjectDir(cwd: string): string {
+  return cwd.replace(/\//g, "-").replace(/^-?/, "--") + "--";
+}
+
+function cryptoRandomSessionId(): string {
+  return `019eb0c1-06d2-71ed-90ee-${Math.random().toString(16).slice(2, 14).padEnd(12, "0")}`;
+}

package/src/__tests__/providers/pi/PiSessionParser.test.ts

@@ -0,0 +1,190 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+
+import { AgentStatus } from "../../../adapters/AgentAdapter.js";
+import { PiSessionParser } from "../../../providers/pi/PiSessionParser.js";
+
+describe("PiSessionParser", () => {
+  let tmpDir: string;
+  let parser: PiSessionParser;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-parser-test-"));
+    parser = new PiSessionParser();
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("reads session metadata, summary, timestamps, and status signal", () => {
+    const filePath = writeJsonl("session.jsonl", [
+      {
+        type: "session_meta",
+        timestamp: "2026-06-10T08:58:20.754Z",
+        sessionId: "sess-101",
+        cwd: "/repo/project-a",
+      },
+      { role: "user", timestamp: "2026-06-10T08:58:21.000Z", content: "implement Pi adapter" },
+      { role: "assistant", timestamp: new Date().toISOString(), content: "working on it" },
+    ]);
+
+    const session = parser.readSession(filePath);
+
+    expect(session).toMatchObject({
+      sessionId: "sess-101",
+      projectPath: "/repo/project-a",
+      summary: "implement Pi adapter",
+      lastRole: "assistant",
+    });
+    expect(session?.sessionStart.toISOString()).toBe("2026-06-10T08:58:20.754Z");
+    expect(parser.determineStatus(session!)).toBe(AgentStatus.WAITING);
+  });
+
+  it("uses the filename session id fallback and reports running when the latest message is from the user", () => {
+    const filePath = writeJsonl("plain-session.jsonl", [
+      { role: "user", timestamp: new Date().toISOString(), content: "still working" },
+    ]);
+
+    const session = parser.readSession(filePath);
+
+    expect(session).toMatchObject({
+      sessionId: "plain-session",
+      summary: "still working",
+      lastRole: "user",
+    });
+    expect(parser.determineStatus(session!)).toBe(AgentStatus.RUNNING);
+  });
+
+  it("truncates long user prompts in detected session summaries", () => {
+    const longPrompt = "x".repeat(140);
+    const filePath = writeJsonl("session.jsonl", [
+      {
+        type: "session",
+        timestamp: "2026-06-10T08:58:20.754Z",
+        id: "sess-long",
+        cwd: "/repo/project-long-summary",
+      },
+      { role: "user", timestamp: "2026-06-10T08:58:21.000Z", content: longPrompt },
+    ]);
+
+    const session = parser.readSession(filePath);
+
+    expect(session?.summary).toHaveLength(120);
+    expect(session?.summary.endsWith("...")).toBe(true);
+  });
+
+  it("reads user and assistant conversation messages from JSONL", () => {
+    const filePath = writeJsonl("conversation.jsonl", [
+      { role: "system", timestamp: "2026-06-10T08:58:20.000Z", content: "hidden" },
+      { role: "user", timestamp: "2026-06-10T08:58:21.000Z", content: "hello pi" },
+      {
+        type: "assistant",
+        timestamp: "2026-06-10T08:58:22.000Z",
+        message: { content: "hello human" },
+      },
+      "{not json",
+    ]);
+
+    expect(parser.getConversation(filePath)).toEqual([
+      { role: "user", content: "hello pi", timestamp: "2026-06-10T08:58:21.000Z" },
+      { role: "assistant", content: "hello human", timestamp: "2026-06-10T08:58:22.000Z" },
+    ]);
+  });
+
+  it("includes system entries only in verbose conversation mode", () => {
+    const filePath = writeJsonl("verbose.jsonl", [
+      { role: "system", timestamp: "2026-06-10T08:58:20.000Z", content: "model changed" },
+      { role: "user", timestamp: "2026-06-10T08:58:21.000Z", content: "visible" },
+    ]);
+
+    expect(parser.getConversation(filePath)).toEqual([
+      { role: "user", content: "visible", timestamp: "2026-06-10T08:58:21.000Z" },
+    ]);
+    expect(parser.getConversation(filePath, { verbose: true })).toEqual([
+      { role: "system", content: "model changed", timestamp: "2026-06-10T08:58:20.000Z" },
+      { role: "user", content: "visible", timestamp: "2026-06-10T08:58:21.000Z" },
+    ]);
+  });
+
+  it("reads real Pi message entries with nested role and text parts", () => {
+    const filePath = writeJsonl("real.jsonl", [
+      {
+        type: "session",
+        version: 3,
+        id: "sess-real",
+        timestamp: "2026-06-10T13:27:17.581Z",
+        cwd: "/repo/project-real",
+      },
+      {
+        type: "model_change",
+        id: "model-1",
+        timestamp: "2026-06-10T13:27:17.655Z",
+        modelId: "claude-sonnet-4-6",
+      },
+      {
+        type: "message",
+        id: "msg-user",
+        timestamp: "2026-06-10T13:27:37.975Z",
+        message: {
+          role: "user",
+          content: [{ type: "text", text: "hello" }],
+          timestamp: 1781098057974,
+        },
+      },
+      {
+        type: "message",
+        id: "msg-assistant",
+        timestamp: "2026-06-10T13:27:40.161Z",
+        message: {
+          role: "assistant",
+          content: [{ type: "text", text: "Hello! How can I help you today?" }],
+          provider: "anthropic",
+          model: "claude-sonnet-4-6",
+          timestamp: 1781098058012,
+        },
+      },
+    ]);
+
+    expect(parser.getConversation(filePath)).toEqual([
+      { role: "user", content: "hello", timestamp: "2026-06-10T13:27:37.975Z" },
+      {
+        role: "assistant",
+        content: "Hello! How can I help you today?",
+        timestamp: "2026-06-10T13:27:40.161Z",
+      },
+    ]);
+    expect(parser.readSession(filePath)).toMatchObject({
+      sessionId: "sess-real",
+      summary: "hello",
+      lastActive: new Date("2026-06-10T13:27:40.161Z"),
+    });
+  });
+
+  it("builds historical summaries from the first user message", () => {
+    const filePath = writeJsonl("summary.jsonl", [
+      { timestamp: "2026-06-10T08:58:20.754Z", sessionId: "sess-g", cwd: "/repo/project-g" },
+      { role: "user", timestamp: "2026-06-10T08:58:21.000Z", content: "first matching message" },
+    ]);
+
+    expect(parser.fileToSessionSummary(filePath)).toMatchObject({
+      type: "pi",
+      sessionId: "sess-g",
+      cwd: "/repo/project-g",
+      firstUserMessage: "first matching message",
+      sessionFilePath: filePath,
+    });
+  });
+
+  function writeJsonl(name: string, entries: Array<Record<string, unknown> | string>): string {
+    const filePath = path.join(tmpDir, name);
+    fs.writeFileSync(
+      filePath,
+      entries
+        .map((entry) => (typeof entry === "string" ? entry : JSON.stringify(entry)))
+        .join("\n"),
+    );
+    return filePath;
+  }
+});

package/src/__tests__/providers/pi/PiSessionTracker.test.ts

@@ -0,0 +1,79 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+
+import type { ProcessInfo } from "../../../adapters/AgentAdapter.js";
+import { PiSessionTracker } from "../../../providers/pi/PiSessionTracker.js";
+
+describe("PiSessionTracker", () => {
+  let tmpHome: string;
+  let sessionsDir: string;
+  let trackerPath: string;
+  let tracker: PiSessionTracker;
+
+  beforeEach(() => {
+    tmpHome = fs.mkdtempSync(path.join(os.tmpdir(), "pi-tracker-test-"));
+    sessionsDir = path.join(tmpHome, ".pi", "agent", "sessions");
+    trackerPath = path.join(tmpHome, ".pi", "agent", "sessions.json");
+    fs.mkdirSync(sessionsDir, { recursive: true });
+    tracker = new PiSessionTracker({ sessionsDir, trackerPath });
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpHome, { recursive: true, force: true });
+  });
+
+  it("matches trusted tracker session files by PID", () => {
+    const proc = makeProcess({ pid: 101 });
+    const sessionFile = writeSessionFile("project-a/session.jsonl");
+    writeTracker({ 101: sessionFile });
+
+    expect(tracker.match([proc])).toEqual({
+      matches: [{ process: proc, filePath: sessionFile }],
+      fallback: [],
+    });
+  });
+
+  it("ignores malformed tracker metadata", () => {
+    const proc = makeProcess({ pid: 303 });
+    fs.writeFileSync(trackerPath, "{bad json");
+
+    expect(tracker.match([proc])).toEqual({
+      matches: [],
+      fallback: [proc],
+    });
+  });
+
+  it("does not trust tracker paths outside the Pi sessions directory", () => {
+    const proc = makeProcess({ pid: 404 });
+    const outside = path.join(tmpHome, "outside.jsonl");
+    fs.writeFileSync(outside, JSON.stringify({ role: "user", content: "nope" }));
+    writeTracker({ 404: outside });
+
+    expect(tracker.match([proc])).toEqual({
+      matches: [],
+      fallback: [proc],
+    });
+  });
+
+  function makeProcess(overrides: Partial<ProcessInfo>): ProcessInfo {
+    return {
+      pid: 1,
+      command: "pi",
+      cwd: "/repo",
+      tty: "ttys001",
+      ...overrides,
+    };
+  }
+
+  function writeTracker(entries: Record<number, string>): void {
+    fs.writeFileSync(trackerPath, JSON.stringify(entries));
+  }
+
+  function writeSessionFile(relativePath: string): string {
+    const filePath = path.join(sessionsDir, relativePath);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify({ role: "user", content: "hello" }));
+    return filePath;
+  }
+});

package/src/__tests__/providers/pi/durable/PiCliProbe.test.ts

@@ -1,38 +1,54 @@
-import { describe, expect, it, vi } from 'vitest';
+import { describe, expect, it, vi } from "vitest";
 
-describe('PiCliProbe', () => {
-    it('validates documented JSON mode and session capabilities', async () => {
-        const api = await import('../../../../index.js') as Record<string, unknown>;
-        expect(api).toHaveProperty('PiCliProbe');
-        const exec = vi.fn()
-            .mockResolvedValueOnce({ stdout: 'pi 0.52.8', stderr: '' })
-            .mockResolvedValueOnce({ stdout: '--mode json\n--session-id <uuid>\n--session <path|id>', stderr: '' });
-        const Probe = api.PiCliProbe as new (options: unknown) => any;
-        await expect(new Probe({ executable: 'fake-pi', exec }).validate()).resolves.toEqual({
-            executable: 'fake-pi', version: 'pi 0.52.8',
-        });
-        expect(exec.mock.calls).toEqual([['fake-pi', ['--version']], ['fake-pi', ['--help']]]);
+describe("PiCliProbe", () => {
+  it("validates documented JSON mode and session capabilities", async () => {
+    const api = (await import("../../../../index.js")) as Record<string, unknown>;
+    expect(api).toHaveProperty("PiCliProbe");
+    const exec = vi
+      .fn()
+      .mockResolvedValueOnce({ stdout: "pi 0.52.8", stderr: "" })
+      .mockResolvedValueOnce({
+        stdout: "--mode json\n--session-id <uuid>\n--session <path|id>",
+        stderr: "",
+      });
+    const Probe = api.PiCliProbe as new (options: unknown) => any;
+    await expect(new Probe({ executable: "fake-pi", exec }).validate()).resolves.toEqual({
+      executable: "fake-pi",
+      version: "pi 0.52.8",
     });
+    expect(exec.mock.calls).toEqual([
+      ["fake-pi", ["--version"]],
+      ["fake-pi", ["--help"]],
+    ]);
+  });
 
-    it('rejects unsupported and unavailable CLIs with sanitized errors', async () => {
-        const api = await import('../../../../index.js') as Record<string, unknown>;
-        const Probe = api.PiCliProbe as new (options: unknown) => any;
-        await expect(new Probe({ exec: vi.fn()
-            .mockResolvedValueOnce({ stdout: '', stderr: '' })
-            .mockResolvedValueOnce({ stdout: '--print only', stderr: '' }) }).validate())
-            .rejects.toMatchObject({ code: 'PI_CLI_UNSUPPORTED' });
-        const unavailable = new Probe({ exec: vi.fn().mockRejectedValue(new Error(`bad\0${'x'.repeat(1000)}`)) });
-        const error = await unavailable.validate().catch((value: Error & { code: string }) => value);
-        expect(error.code).toBe('PI_CLI_UNAVAILABLE');
-        expect(error.message).not.toContain('\0');
-        expect(error.message.length).toBeLessThan(600);
+  it("rejects unsupported and unavailable CLIs with sanitized errors", async () => {
+    const api = (await import("../../../../index.js")) as Record<string, unknown>;
+    const Probe = api.PiCliProbe as new (options: unknown) => any;
+    await expect(
+      new Probe({
+        exec: vi
+          .fn()
+          .mockResolvedValueOnce({ stdout: "", stderr: "" })
+          .mockResolvedValueOnce({ stdout: "--print only", stderr: "" }),
+      }).validate(),
+    ).rejects.toMatchObject({ code: "PI_CLI_UNSUPPORTED" });
+    const unavailable = new Probe({
+      exec: vi.fn().mockRejectedValue(new Error(`bad\0${"x".repeat(1000)}`)),
     });
+    const error = await unavailable.validate().catch((value: Error & { code: string }) => value);
+    expect(error.code).toBe("PI_CLI_UNAVAILABLE");
+    expect(error.message).not.toContain("\0");
+    expect(error.message.length).toBeLessThan(600);
+  });
 
-    it('reports an empty version as unknown', async () => {
-        const api = await import('../../../../index.js') as Record<string, unknown>;
-        const Probe = api.PiCliProbe as new (options: unknown) => any;
-        const exec = vi.fn().mockResolvedValueOnce({ stdout: ' \n', stderr: '' })
-            .mockResolvedValueOnce({ stdout: '--mode json --session-id --session', stderr: '' });
-        await expect(new Probe({ exec }).validate()).resolves.toMatchObject({ version: 'unknown' });
-    });
+  it("reports an empty version as unknown", async () => {
+    const api = (await import("../../../../index.js")) as Record<string, unknown>;
+    const Probe = api.PiCliProbe as new (options: unknown) => any;
+    const exec = vi
+      .fn()
+      .mockResolvedValueOnce({ stdout: " \n", stderr: "" })
+      .mockResolvedValueOnce({ stdout: "--mode json --session-id --session", stderr: "" });
+    await expect(new Probe({ exec }).validate()).resolves.toMatchObject({ version: "unknown" });
+  });
 });