@ai-devkit/agent-manager 0.36.0 → 0.38.0

package/src/__tests__/harnesses/antigravity/AntigravityCliAdapter.subprocess.test.ts

@@ -0,0 +1,133 @@
+/**
+ * Subprocess budget tests for AntigravityCliAdapter (#257).
+ *
+ * `child_process` is mocked so every spawn is recorded; the real process
+ * utilities and AgentManager run on top of it. Detection must never use the
+ * synchronous child_process APIs and must reuse the shared snapshot.
+ */
+
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import * as childProcess from "child_process";
+
+import { AntigravityCliAdapter } from "../../../harnesses/antigravity/AntigravityCliAdapter.js";
+import type { ProcessInfo } from "../../../adapters/AgentAdapter.js";
+import { AgentManager } from "../../../AgentManager.js";
+import { AgentRegistry } from "../../../utils/AgentRegistry.js";
+import { createProcessSnapshotCapture } from "../../../utils/process.js";
+
+vi.mock("child_process", async (importOriginal) => {
+  const actual = (await importOriginal()) as typeof import("child_process");
+  const forbidden = (name: string) =>
+    vi.fn(() => {
+      throw new Error(`unexpected child_process.${name} call`);
+    });
+  return {
+    ...actual,
+    execFile: vi.fn(),
+    exec: forbidden("exec"),
+    spawn: forbidden("spawn"),
+    execFileSync: forbidden("execFileSync"),
+    execSync: forbidden("execSync"),
+    spawnSync: forbidden("spawnSync"),
+  };
+});
+
+const AGY_PID = 4242;
+const AGY_CWD = "/Users/dev/my-project";
+
+type ExecFileCallback = (error: Error | null, stdout: string, stderr: string) => void;
+
+/** Fake `ps`/`lsof` output for one running agy process plus an unrelated one. */
+function fakeExecFile(file: string, args: readonly string[]): string {
+  if (file === "ps" && args[0] === "-axo") {
+    return [`${AGY_PID} 1 ttys010 /usr/local/bin/agy`, "77 1 ttys011 node server.js"].join("\n");
+  }
+  if (file === "lsof") return `p${AGY_PID}\nn${AGY_CWD}\n`;
+  if (file === "ps" && args[0] === "-o") return `${AGY_PID} Wed Mar 18 23:18:01 2026\n`;
+  throw new Error(`unexpected execFile ${file} ${args.join(" ")}`);
+}
+
+const mockedExecFile = childProcess.execFile as unknown as ReturnType<typeof vi.fn>;
+const syncApis = ["execFileSync", "execSync", "spawnSync"] as const;
+const allSpawnApis = [...syncApis, "execFile", "exec", "spawn"] as const;
+
+function callCount(api: (typeof allSpawnApis)[number]): number {
+  return (childProcess[api] as unknown as ReturnType<typeof vi.fn>).mock.calls.length;
+}
+
+describe("AntigravityCliAdapter subprocess usage", () => {
+  let base: string;
+
+  beforeEach(() => {
+    base = fs.mkdtempSync(path.join(os.tmpdir(), "agy-subprocess-test-"));
+    process.env.ANTIGRAVITY_CLI_HOME = base;
+    for (const api of allSpawnApis) {
+      (childProcess[api] as unknown as ReturnType<typeof vi.fn>).mockClear();
+    }
+    mockedExecFile.mockImplementation(
+      (file: string, args: readonly string[], _opts: unknown, cb: ExecFileCallback) => {
+        try {
+          cb(null, fakeExecFile(file, args), "");
+        } catch (error) {
+          cb(error as Error, "", "");
+        }
+      },
+    );
+  });
+
+  afterEach(() => {
+    delete process.env.ANTIGRAVITY_CLI_HOME;
+    fs.rmSync(base, { recursive: true, force: true });
+  });
+
+  it("spawns no subprocess when the injected snapshot has no agy process", async () => {
+    const adapter = new AntigravityCliAdapter();
+    const snapshot: ProcessInfo[] = [{ pid: 77, command: "node server.js", cwd: "/x", tty: "" }];
+
+    expect(await adapter.detectAgents({ processes: snapshot })).toEqual([]);
+
+    for (const api of allSpawnApis) expect(callCount(api)).toBe(0);
+  });
+
+  it("spawns no subprocess when the injected snapshot contains an agy process", async () => {
+    const adapter = new AntigravityCliAdapter();
+    const snapshot: ProcessInfo[] = [
+      { pid: AGY_PID, command: "agy", cwd: AGY_CWD, tty: "ttys010", startTime: new Date() },
+    ];
+
+    const agents = await adapter.detectAgents({ processes: snapshot });
+
+    expect(agents.map((agent) => agent.pid)).toEqual([AGY_PID]);
+    for (const api of allSpawnApis) expect(callCount(api)).toBe(0);
+  });
+
+  it("never calls synchronous child_process APIs when capturing its own snapshot", async () => {
+    const adapter = new AntigravityCliAdapter();
+
+    const agents = await adapter.detectAgents();
+
+    expect(agents).toHaveLength(1);
+    expect(agents[0]).toMatchObject({ pid: AGY_PID, projectPath: AGY_CWD });
+    for (const api of syncApis) expect(callCount(api)).toBe(0);
+  });
+
+  it("makes a full listAgents() refresh spawn exactly one ps + lsof + ps lstart set", async () => {
+    // A fresh capture: the shared one caches start times from earlier tests (#266).
+    const manager = new AgentManager(
+      new AgentRegistry(path.join(base, "agents.json")),
+      createProcessSnapshotCapture(),
+    );
+    manager.registerAdapter(new AntigravityCliAdapter());
+
+    const agents = await manager.listAgents();
+
+    expect(agents.map((agent) => agent.pid)).toEqual([AGY_PID]);
+    const spawned = mockedExecFile.mock.calls.map(
+      ([file, args]) => `${file} ${(args as string[])[0]}`,
+    );
+    expect(spawned.sort()).toEqual(["lsof -a", "ps -axo", "ps -o"]);
+    for (const api of syncApis) expect(callCount(api)).toBe(0);
+  });
+});

package/src/__tests__/harnesses/antigravity/AntigravityCliAdapter.test.ts

@@ -0,0 +1,396 @@
+/**
+ * Tests for AntigravityCliAdapter
+ *
+ * The adapter resolves a live `agy` process to its conversation via
+ * ~/.gemini/antigravity-cli/cache/last_conversations.json (cwd -> conversationId)
+ * and reads session details from brain/<id>/.system_generated/logs/transcript.jsonl.
+ */
+
+import type { MockedFunction } from "vitest";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+
+import { AntigravityCliAdapter } from "../../../harnesses/antigravity/AntigravityCliAdapter.js";
+import type { ProcessInfo } from "../../../adapters/AgentAdapter.js";
+import { AgentStatus } from "../../../adapters/AgentAdapter.js";
+import {
+  listAgentProcesses,
+  enrichProcesses,
+  captureProcessSnapshot,
+} from "../../../utils/process.js";
+import { generateAgentName } from "../../../utils/matching.js";
+
+vi.mock("../../../utils/process.js", async (importOriginal) => {
+  const actual = (await importOriginal()) as typeof import("../../../utils/process.js");
+  return {
+    ...actual,
+    listAgentProcesses: vi.fn(),
+    enrichProcesses: vi.fn(),
+    captureProcessSnapshot: vi.fn(),
+  };
+});
+
+vi.mock("../../../utils/matching.js", async (importOriginal) => {
+  const actual = (await importOriginal()) as typeof import("../../../utils/matching.js");
+  return {
+    ...actual,
+    generateAgentName: vi.fn(),
+  };
+});
+
+const mockedListAgentProcesses = listAgentProcesses as MockedFunction<typeof listAgentProcesses>;
+const mockedEnrichProcesses = enrichProcesses as MockedFunction<typeof enrichProcesses>;
+const mockedCaptureProcessSnapshot = captureProcessSnapshot as MockedFunction<
+  typeof captureProcessSnapshot
+>;
+const mockedGenerateAgentName = generateAgentName as MockedFunction<typeof generateAgentName>;
+
+const CONVERSATION_ID = "10485e13-2742-4e9e-b286-ac0606f0cb1e";
+
+const iso = (d: Date) => d.toISOString().replace(/\.\d+Z$/, "Z");
+/** A user transcript record: real prompt wrapped in <USER_REQUEST> like agy writes it. */
+const userRecord = (text: string, at?: Date) => ({
+  source: "USER_EXPLICIT",
+  type: "USER_INPUT",
+  created_at: iso(at ?? new Date()),
+  content: `<USER_REQUEST>\n${text}\n</USER_REQUEST>\n<ADDITIONAL_CONTEXT>ignored</ADDITIONAL_CONTEXT>`,
+});
+const modelRecord = (text: string, at?: Date) => ({
+  source: "MODEL",
+  type: "PLANNER_RESPONSE",
+  created_at: iso(at ?? new Date()),
+  content: text,
+});
+/** A MODEL tool-call record (e.g. RUN_COMMAND) — execution detail, not a reply. */
+const toolRecord = (text: string, at?: Date) => ({
+  source: "MODEL",
+  type: "RUN_COMMAND",
+  created_at: iso(at ?? new Date()),
+  content: text,
+});
+const systemRecord = (text: string, at?: Date) => ({
+  source: "SYSTEM",
+  type: "CHECKPOINT",
+  created_at: iso(at ?? new Date()),
+  content: text,
+});
+
+describe("AntigravityCliAdapter", () => {
+  let adapter: AntigravityCliAdapter;
+  let base: string;
+  let cwd: string;
+
+  beforeEach(() => {
+    base = fs.mkdtempSync(path.join(os.tmpdir(), "agy-adapter-test-"));
+    process.env.ANTIGRAVITY_CLI_HOME = base;
+    cwd = "/Users/dev/my-project";
+
+    adapter = new AntigravityCliAdapter();
+
+    mockedListAgentProcesses.mockReset();
+    mockedEnrichProcesses.mockReset();
+    mockedCaptureProcessSnapshot.mockReset();
+    mockedGenerateAgentName.mockReset();
+
+    mockedEnrichProcesses.mockImplementation((procs) => procs);
+    mockedGenerateAgentName.mockImplementation(
+      (c: string, pid: number) => `${path.basename(c) || "unknown"}-${pid}`,
+    );
+  });
+
+  afterEach(() => {
+    delete process.env.ANTIGRAVITY_CLI_HOME;
+    fs.rmSync(base, { recursive: true, force: true });
+  });
+
+  /** Write brain/<id>/.system_generated/logs/transcript.jsonl. */
+  function writeTranscript(opts: {
+    id?: string;
+    records?: object[];
+    transcript?: boolean;
+  }): string {
+    const id = opts.id ?? CONVERSATION_ID;
+    const dir = path.join(base, "brain", id, ".system_generated", "logs");
+    fs.mkdirSync(dir, { recursive: true });
+    if (opts.transcript !== false) {
+      const records = opts.records ?? [userRecord("fix the bug")];
+      fs.writeFileSync(
+        path.join(dir, "transcript.jsonl"),
+        records.map((r) => JSON.stringify(r)).join("\n"),
+      );
+    }
+    return path.join(dir, "transcript.jsonl");
+  }
+
+  /** Write cache/last_conversations.json (cwd -> conversationId). */
+  function writeRegistry(map: Record<string, string>): void {
+    const dir = path.join(base, "cache");
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, "last_conversations.json"), JSON.stringify(map));
+  }
+
+  function proc(overrides: Partial<ProcessInfo> = {}): ProcessInfo {
+    return {
+      pid: 4242,
+      ppid: 1,
+      command: "agy",
+      cwd,
+      tty: "ttys010",
+      startTime: new Date(),
+      ...overrides,
+    };
+  }
+
+  it("exposes the antigravity_cli type and the agy process name", () => {
+    expect(adapter.type).toBe("antigravity_cli");
+    expect(adapter.processNames).toEqual(["agy"]);
+  });
+
+  describe("canHandle", () => {
+    it("returns true for a plain agy command", () => {
+      expect(adapter.canHandle(proc({ command: "agy" }))).toBe(true);
+    });
+
+    it("returns true for agy with a full path and args", () => {
+      expect(
+        adapter.canHandle(
+          proc({ command: "/Users/dev/.local/bin/agy --dangerously-skip-permissions" }),
+        ),
+      ).toBe(true);
+    });
+
+    it("returns false for non-agy processes", () => {
+      expect(adapter.canHandle(proc({ command: "node app.js" }))).toBe(false);
+    });
+
+    it("returns true for agy installed under a path containing spaces", () => {
+      const executable = path.join(base, "Antigravity App.app", "bin", "agy");
+      fs.mkdirSync(path.dirname(executable), { recursive: true });
+      fs.writeFileSync(executable, "");
+
+      expect(adapter.canHandle(proc({ command: `${executable} --prompt fix it` }))).toBe(true);
+      expect(adapter.canHandle(proc({ command: "/usr/bin/vim My Notes/agy" }))).toBe(false);
+    });
+
+    it('returns false when "agy" appears only in an argument path', () => {
+      expect(adapter.canHandle(proc({ command: "node /path/to/agy-thing.js" }))).toBe(false);
+    });
+  });
+
+  describe("detectAgents", () => {
+    it("uses context.processes when provided and never captures its own snapshot", async () => {
+      writeTranscript({});
+      writeRegistry({ [cwd]: CONVERSATION_ID });
+
+      const agents = await adapter.detectAgents({
+        processes: [proc(), proc({ pid: 7, command: "node server.js" })],
+      });
+
+      expect(agents.map((a) => a.pid)).toEqual([4242]);
+      expect(agents[0].sessionId).toBe(CONVERSATION_ID);
+      expect(mockedCaptureProcessSnapshot).not.toHaveBeenCalled();
+      expect(mockedListAgentProcesses).not.toHaveBeenCalled();
+      expect(mockedEnrichProcesses).not.toHaveBeenCalled();
+    });
+
+    it("falls back to the async captureProcessSnapshot without context", async () => {
+      mockedCaptureProcessSnapshot.mockResolvedValue([]);
+
+      expect(await adapter.detectAgents()).toEqual([]);
+      expect(mockedCaptureProcessSnapshot).toHaveBeenCalledWith(["agy"], {
+        isCandidate: expect.any(Function),
+      });
+      expect(mockedListAgentProcesses).not.toHaveBeenCalled();
+      expect(mockedEnrichProcesses).not.toHaveBeenCalled();
+    });
+
+    it("resolves the conversation via last_conversations.json (cwd -> id)", async () => {
+      writeTranscript({});
+      writeRegistry({ [cwd]: CONVERSATION_ID });
+      mockedCaptureProcessSnapshot.mockResolvedValue([proc()]);
+
+      const agents = await adapter.detectAgents();
+
+      expect(agents).toHaveLength(1);
+      expect(agents[0]).toMatchObject({
+        type: "antigravity_cli",
+        pid: 4242,
+        projectPath: cwd,
+        sessionId: CONVERSATION_ID,
+        summary: "fix the bug",
+      });
+      expect(agents[0].sessionFilePath).toBe(
+        path.join(base, "brain", CONVERSATION_ID, ".system_generated", "logs", "transcript.jsonl"),
+      );
+    });
+
+    it("falls back to a process-only RUNNING agent when the cwd is not in the registry", async () => {
+      writeTranscript({});
+      writeRegistry({ "/some/other/cwd": CONVERSATION_ID });
+      mockedCaptureProcessSnapshot.mockResolvedValue([proc()]);
+
+      const agents = await adapter.detectAgents();
+
+      expect(agents).toHaveLength(1);
+      expect(agents[0].status).toBe(AgentStatus.RUNNING);
+      expect(agents[0].sessionId).toBe("pid-4242");
+      expect(agents[0].sessionFilePath).toBeUndefined();
+    });
+
+    it("is process-only when the mapped conversation has no transcript", async () => {
+      writeTranscript({ transcript: false });
+      writeRegistry({ [cwd]: CONVERSATION_ID });
+      mockedCaptureProcessSnapshot.mockResolvedValue([proc()]);
+
+      const agents = await adapter.detectAgents();
+
+      expect(agents[0].sessionId).toBe("pid-4242");
+    });
+  });
+
+  describe("getConversation", () => {
+    it("maps USER_INPUT (<USER_REQUEST>) and MODEL records to roles", () => {
+      const file = writeTranscript({ records: [userRecord("hi"), modelRecord("hello")] });
+      expect(adapter.getConversation(file)).toEqual([
+        { role: "user", content: "hi" },
+        { role: "assistant", content: "hello" },
+      ]);
+    });
+
+    it("skips malformed lines", () => {
+      const file = writeTranscript({ records: [userRecord("hi")] });
+      fs.appendFileSync(file, "\n{bad json");
+      expect(adapter.getConversation(file)).toEqual([{ role: "user", content: "hi" }]);
+    });
+
+    it("excludes SYSTEM records unless verbose", () => {
+      const file = writeTranscript({ records: [systemRecord("checkpoint"), userRecord("go")] });
+      expect(adapter.getConversation(file)).toEqual([{ role: "user", content: "go" }]);
+      expect(adapter.getConversation(file, { verbose: true }).map((m) => m.role)).toEqual([
+        "system",
+        "user",
+      ]);
+    });
+
+    it("excludes MODEL tool-call (RUN_COMMAND) records except in verbose", () => {
+      const file = writeTranscript({
+        records: [userRecord("go"), toolRecord("ran: echo hi"), modelRecord("done")],
+      });
+      // A tool call is not an assistant reply; only USER_INPUT + PLANNER_RESPONSE show.
+      expect(adapter.getConversation(file)).toEqual([
+        { role: "user", content: "go" },
+        { role: "assistant", content: "done" },
+      ]);
+      expect(adapter.getConversation(file, { verbose: true }).map((m) => m.role)).toEqual([
+        "user",
+        "system",
+        "assistant",
+      ]);
+    });
+  });
+
+  describe("detectAgents status + summary mapping", () => {
+    const detectFirst = async () => (await adapter.detectAgents())[0];
+
+    it("marks WAITING when the last reply is a PLANNER_RESPONSE (after a tool call)", async () => {
+      writeTranscript({
+        records: [userRecord("go"), toolRecord("ran: echo hi"), modelRecord("done")],
+      });
+      writeRegistry({ [cwd]: CONVERSATION_ID });
+      mockedCaptureProcessSnapshot.mockResolvedValue([proc()]);
+      expect((await detectFirst()).status).toBe(AgentStatus.WAITING);
+    });
+
+    it("marks RUNNING when the last transcript turn is a USER_INPUT message", async () => {
+      writeTranscript({ records: [userRecord("still there?")] });
+      writeRegistry({ [cwd]: CONVERSATION_ID });
+      mockedCaptureProcessSnapshot.mockResolvedValue([proc()]);
+      expect((await detectFirst()).status).toBe(AgentStatus.RUNNING);
+    });
+
+    it("marks IDLE when the last created_at is older than the threshold", async () => {
+      const old = new Date(Date.now() - 10 * 60 * 1000);
+      writeTranscript({ records: [userRecord("go", old)] });
+      writeRegistry({ [cwd]: CONVERSATION_ID });
+      mockedCaptureProcessSnapshot.mockResolvedValue([proc()]);
+      expect((await detectFirst()).status).toBe(AgentStatus.IDLE);
+    });
+
+    it("uses the last user request as the agent summary", async () => {
+      writeTranscript({ records: [userRecord("refactor the parser"), modelRecord("on it")] });
+      writeRegistry({ [cwd]: CONVERSATION_ID });
+      mockedCaptureProcessSnapshot.mockResolvedValue([proc()]);
+      expect((await detectFirst()).summary).toBe("refactor the parser");
+    });
+  });
+
+  describe("listSessions", () => {
+    it("returns [] when there is no registry", async () => {
+      expect(await adapter.listSessions()).toEqual([]);
+    });
+
+    it("ignores a malformed registry and non-string conversation ids", async () => {
+      writeTranscript({});
+      fs.mkdirSync(path.join(base, "cache"), { recursive: true });
+      fs.writeFileSync(path.join(base, "cache", "last_conversations.json"), "{not json");
+      expect(await adapter.listSessions()).toEqual([]);
+
+      writeRegistry({ [cwd]: 42 as unknown as string, "/Users/dev/other": "" });
+      expect(await adapter.listSessions()).toEqual([]);
+    });
+
+    it("lists sessions from the registry with cwd + first user message", async () => {
+      writeTranscript({});
+      writeRegistry({ [cwd]: CONVERSATION_ID });
+      const summaries = await adapter.listSessions();
+      expect(summaries).toHaveLength(1);
+      expect(summaries[0]).toMatchObject({
+        type: "antigravity_cli",
+        sessionId: CONVERSATION_ID,
+        cwd,
+        firstUserMessage: "fix the bug",
+      });
+    });
+
+    it("applies the cwd filter", async () => {
+      writeTranscript({ id: "aaa0000a-0000-4000-8000-00000000000a", records: [userRecord("a")] });
+      writeTranscript({ id: "bbb0000b-0000-4000-8000-00000000000b", records: [userRecord("b")] });
+      writeRegistry({
+        "/Users/dev/project-a": "aaa0000a-0000-4000-8000-00000000000a",
+        "/Users/dev/project-b": "bbb0000b-0000-4000-8000-00000000000b",
+      });
+
+      const all = await adapter.listSessions();
+      expect(all).toHaveLength(2);
+
+      const filtered = await adapter.listSessions({ cwd: "/Users/dev/project-a" });
+      expect(filtered).toHaveLength(1);
+      expect(filtered[0].cwd).toBe("/Users/dev/project-a");
+    });
+  });
+
+  describe("findSessionsById", () => {
+    it("finds a registered conversation by id", async () => {
+      writeTranscript({});
+      writeRegistry({ [cwd]: CONVERSATION_ID });
+
+      expect(await adapter.findSessionsById(CONVERSATION_ID)).toEqual([
+        expect.objectContaining({
+          type: "antigravity_cli",
+          sessionId: CONVERSATION_ID,
+          cwd,
+          firstUserMessage: "fix the bug",
+        }),
+      ]);
+    });
+
+    it("ignores transcripts that are not in the registry, like listSessions", async () => {
+      writeTranscript({});
+      writeRegistry({});
+
+      expect(await adapter.findSessionsById(CONVERSATION_ID)).toEqual([]);
+      expect(await adapter.listSessions()).toEqual([]);
+    });
+  });
+});

package/src/__tests__/harnesses/builtinAdapters.test.ts

@@ -0,0 +1,33 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+
+import { AGENT_TYPES } from "../../adapters/AgentAdapter.js";
+import { createBuiltinAdapters } from "../../harnesses/index.js";
+import { AgentRegistry } from "../../utils/AgentRegistry.js";
+
+describe("createBuiltinAdapters", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "builtin-adapters-"));
+    // Several adapters default to AgentRegistry.default(), which opens ~/.ai-devkit/agents.db.
+    vi.spyOn(AgentRegistry, "default").mockReturnValue(
+      new AgentRegistry(path.join(tmpDir, "agents.json")),
+    );
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("returns exactly one adapter per built-in agent type", () => {
+    const adapters = createBuiltinAdapters();
+    try {
+      expect(adapters.map((adapter) => adapter.type).sort()).toEqual([...AGENT_TYPES].sort());
+    } finally {
+      for (const adapter of adapters) (adapter as { close?: () => void }).close?.();
+    }
+  });
+});

package/src/__tests__/harnesses/claude/ClaudeAgentMapper.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from "vitest";
+
+import { AgentStatus, type ProcessInfo } from "../../../adapters/AgentAdapter.js";
+import { ClaudeAgentMapper } from "../../../harnesses/claude/ClaudeAgentMapper.js";
+import type { ClaudeSession } from "../../../harnesses/claude/ClaudeSessionParser.js";
+import type { SessionFile } from "../../../utils/session.js";
+
+function makeProcess(overrides: Partial<ProcessInfo> = {}): ProcessInfo {
+  return {
+    pid: 123,
+    command: "claude",
+    cwd: "/repo/my-app",
+    tty: "ttys001",
+    ...overrides,
+  };
+}
+
+function makeSession(overrides: Partial<ClaudeSession> = {}): ClaudeSession {
+  return {
+    sessionId: "session-1",
+    projectPath: "/repo/my-app",
+    sessionStart: new Date("2026-08-23T10:00:00.000Z"),
+    lastActive: new Date("2026-08-23T10:05:00.000Z"),
+    lastEntryType: "assistant",
+    isInterrupted: false,
+    lastUserMessage: "Review this change",
+    ...overrides,
+  };
+}
+
+function makeSessionFile(overrides: Partial<SessionFile> = {}): SessionFile {
+  return {
+    sessionId: "session-1",
+    filePath: "/home/.claude/projects/-repo-my-app/session-1.jsonl",
+    projectDir: "/home/.claude/projects/-repo-my-app",
+    birthtimeMs: new Date("2026-08-23T10:00:00.000Z").getTime(),
+    resolvedCwd: "/repo/my-app",
+    ...overrides,
+  };
+}
+
+describe("ClaudeAgentMapper", () => {
+  it("prefers live PID-file status and waiting reason over JSONL-derived status", () => {
+    const mapper = new ClaudeAgentMapper();
+
+    const agent = mapper.mapSessionToAgent({
+      session: makeSession({ lastEntryType: "assistant" }),
+      processInfo: makeProcess(),
+      sessionFile: makeSessionFile(),
+      liveInfo: {
+        pidStatus: AgentStatus.WAITING,
+        waitingFor: "approve Read",
+      },
+    });
+
+    expect(agent).toMatchObject({
+      name: "my-app-123",
+      type: "claude",
+      status: AgentStatus.WAITING,
+      summary: "Review this change — waiting for approve Read",
+      pid: 123,
+      projectPath: "/repo/my-app",
+      sessionId: "session-1",
+      sessionFilePath: "/home/.claude/projects/-repo-my-app/session-1.jsonl",
+    });
+  });
+
+  it("maps unmatched processes to the shared process-only placeholder", () => {
+    const mapper = new ClaudeAgentMapper();
+
+    const agent = mapper.mapProcessOnlyAgent(makeProcess({ pid: 456, cwd: "/repo/tooling" }));
+
+    expect(agent).toMatchObject({
+      name: "tooling-456",
+      type: "claude",
+      status: AgentStatus.RUNNING,
+      summary: "Claude Code process running",
+      pid: 456,
+      projectPath: "/repo/tooling",
+      sessionId: "pid-456",
+    });
+    expect(agent.lastActive).toBeInstanceOf(Date);
+  });
+});