@ai-devkit/agent-manager 0.34.0 → 0.35.0

package/dist/utils/session.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/utils/session.ts"],"sourcesContent":["/**\n * Session File Utilities\n *\n * Utilities for discovering session files and their birth times.\n * Uses Node.js fs APIs to get birth timestamps without reading file contents.\n */\n\nimport * as fs from \"fs\";\nimport * as path from \"path\";\n\n/**\n * Represents a session file with its birth time metadata.\n */\nexport interface SessionFile {\n  /** Session identifier (filename without .jsonl extension) */\n  sessionId: string;\n\n  /** Full path to the session file */\n  filePath: string;\n\n  /** Parent directory of the session file */\n  projectDir: string;\n\n  /** File creation time in milliseconds since epoch */\n  birthtimeMs: number;\n\n  /** CWD this session maps to — set by the adapter after calling batchGetSessionFileBirthtimes() */\n  resolvedCwd: string;\n}\n\n/**\n * Check whether a path exists and is a directory.\n * Returns false on any error (missing path, permission denied, broken symlink, etc.).\n */\nexport function isDirectory(p: string): boolean {\n  return safeStat(p)?.isDirectory() ?? false;\n}\n\n/**\n * `fs.statSync` that swallows errors and returns `undefined` on failure.\n * Callers can pull whichever fields they need (mtime, birthtime, ...).\n */\nexport function safeStat(filePath: string): fs.Stats | undefined {\n  try {\n    return fs.statSync(filePath);\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * `fs.readFileSync` (utf-8) that swallows errors and returns `undefined`\n * on failure. Use when an unreadable file should be skipped rather than\n * raised.\n */\nexport function safeReadFile(filePath: string): string | undefined {\n  try {\n    return fs.readFileSync(filePath, \"utf-8\");\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * `fs.readdirSync` that swallows errors and returns `[]` on failure.\n * Useful when walking optional/transient directories where missing or\n * unreadable entries should be skipped silently.\n */\nexport function safeReaddir(dir: string): string[] {\n  try {\n    return fs.readdirSync(dir);\n  } catch {\n    return [];\n  }\n}\n\n/**\n * List entries in a directory that end with `.jsonl`. Returns `[]` on\n * read errors. The result preserves directory order (no sorting).\n */\nexport function listJsonl(dir: string): string[] {\n  return safeReaddir(dir).filter((name) => name.endsWith(\".jsonl\"));\n}\n\n/**\n * Get birth times for .jsonl session files across multiple directories.\n *\n * Enumerates each directory with readdirSync and stats each .jsonl file\n * to get its birth time. No shell commands are used.\n * Returns empty array if no directories have .jsonl files or reads fail.\n * resolvedCwd is left empty — the adapter must set it.\n */\nexport function batchGetSessionFileBirthtimes(dirs: string[]): SessionFile[] {\n  if (dirs.length === 0) return [];\n\n  const results: SessionFile[] = [];\n\n  for (const dir of dirs) {\n    let entries: string[];\n    try {\n      entries = fs.readdirSync(dir);\n    } catch {\n      continue;\n    }\n\n    for (const entry of entries) {\n      if (!entry.endsWith(\".jsonl\")) continue;\n\n      const filePath = path.join(dir, entry);\n\n      let birthtimeMs: number;\n      try {\n        birthtimeMs = fs.statSync(filePath).birthtimeMs;\n      } catch {\n        continue;\n      }\n\n      if (!Number.isFinite(birthtimeMs) || birthtimeMs <= 0) continue;\n\n      const sessionId = entry.replace(/\\.jsonl$/, \"\");\n\n      results.push({\n        sessionId,\n        filePath,\n        projectDir: dir,\n        birthtimeMs,\n        resolvedCwd: \"\",\n      });\n    }\n  }\n\n  return results;\n}\n"],"names":["fs","path","isDirectory","p","safeStat","filePath","statSync","undefined","safeReadFile","readFileSync","safeReaddir","dir","readdirSync","listJsonl","filter","name","endsWith","batchGetSessionFileBirthtimes","dirs","length","results","entries","entry","join","birthtimeMs","Number","isFinite","sessionId","replace","push","projectDir","resolvedCwd"],"mappings":"AAAA;;;;;CAKC,GAED,YAAYA,QAAQ,KAAK;AACzB,YAAYC,UAAU,OAAO;AAsB7B;;;CAGC,GACD,OAAO,SAASC,YAAYC,CAAS;IACnC,OAAOC,SAASD,IAAID,iBAAiB;AACvC;AAEA;;;CAGC,GACD,OAAO,SAASE,SAASC,QAAgB;IACvC,IAAI;QACF,OAAOL,GAAGM,QAAQ,CAACD;IACrB,EAAE,OAAM;QACN,OAAOE;IACT;AACF;AAEA;;;;CAIC,GACD,OAAO,SAASC,aAAaH,QAAgB;IAC3C,IAAI;QACF,OAAOL,GAAGS,YAAY,CAACJ,UAAU;IACnC,EAAE,OAAM;QACN,OAAOE;IACT;AACF;AAEA;;;;CAIC,GACD,OAAO,SAASG,YAAYC,GAAW;IACrC,IAAI;QACF,OAAOX,GAAGY,WAAW,CAACD;IACxB,EAAE,OAAM;QACN,OAAO,EAAE;IACX;AACF;AAEA;;;CAGC,GACD,OAAO,SAASE,UAAUF,GAAW;IACnC,OAAOD,YAAYC,KAAKG,MAAM,CAAC,CAACC,OAASA,KAAKC,QAAQ,CAAC;AACzD;AAEA;;;;;;;CAOC,GACD,OAAO,SAASC,8BAA8BC,IAAc;IAC1D,IAAIA,KAAKC,MAAM,KAAK,GAAG,OAAO,EAAE;IAEhC,MAAMC,UAAyB,EAAE;IAEjC,KAAK,MAAMT,OAAOO,KAAM;QACtB,IAAIG;QACJ,IAAI;YACFA,UAAUrB,GAAGY,WAAW,CAACD;QAC3B,EAAE,OAAM;YACN;QACF;QAEA,KAAK,MAAMW,SAASD,QAAS;YAC3B,IAAI,CAACC,MAAMN,QAAQ,CAAC,WAAW;YAE/B,MAAMX,WAAWJ,KAAKsB,IAAI,CAACZ,KAAKW;YAEhC,IAAIE;YACJ,IAAI;gBACFA,cAAcxB,GAAGM,QAAQ,CAACD,UAAUmB,WAAW;YACjD,EAAE,OAAM;gBACN;YACF;YAEA,IAAI,CAACC,OAAOC,QAAQ,CAACF,gBAAgBA,eAAe,GAAG;YAEvD,MAAMG,YAAYL,MAAMM,OAAO,CAAC,YAAY;YAE5CR,QAAQS,IAAI,CAAC;gBACXF;gBACAtB;gBACAyB,YAAYnB;gBACZa;gBACAO,aAAa;YACf;QACF;IACF;IAEA,OAAOX;AACT"}
+{"version":3,"sources":["../../src/utils/session.ts"],"sourcesContent":["/**\n * Session File Utilities\n *\n * Utilities for discovering session files and their birth times.\n * Uses Node.js fs APIs to get birth timestamps without reading file contents.\n */\n\nimport * as fs from \"fs\";\nimport * as path from \"path\";\n\n/**\n * Represents a session file with its birth time metadata.\n */\nexport interface SessionFile {\n  /** Session identifier (filename without .jsonl extension) */\n  sessionId: string;\n\n  /** Full path to the session file */\n  filePath: string;\n\n  /** Parent directory of the session file */\n  projectDir: string;\n\n  /** File creation time in milliseconds since epoch */\n  birthtimeMs: number;\n\n  /** CWD this session maps to — set by the adapter after calling batchGetSessionFileBirthtimes() */\n  resolvedCwd: string;\n}\n\n/**\n * Check whether a path exists and is a directory.\n * Returns false on any error (missing path, permission denied, broken symlink, etc.).\n */\nexport function isDirectory(p: string): boolean {\n  return safeStat(p)?.isDirectory() ?? false;\n}\n\n/** Return whether a value can be safely appended as one filesystem path segment. */\nexport function isSafePathSegment(value: string): boolean {\n  return (\n    value.length > 0 &&\n    value !== \".\" &&\n    value !== \"..\" &&\n    !value.includes(\"\\0\") &&\n    path.basename(value) === value\n  );\n}\n\n/**\n * `fs.statSync` that swallows errors and returns `undefined` on failure.\n * Callers can pull whichever fields they need (mtime, birthtime, ...).\n */\nexport function safeStat(filePath: string): fs.Stats | undefined {\n  try {\n    return fs.statSync(filePath);\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * `fs.readFileSync` (utf-8) that swallows errors and returns `undefined`\n * on failure. Use when an unreadable file should be skipped rather than\n * raised.\n */\nexport function safeReadFile(filePath: string): string | undefined {\n  try {\n    return fs.readFileSync(filePath, \"utf-8\");\n  } catch {\n    return undefined;\n  }\n}\n\n/**\n * `fs.readdirSync` that swallows errors and returns `[]` on failure.\n * Useful when walking optional/transient directories where missing or\n * unreadable entries should be skipped silently.\n */\nexport function safeReaddir(dir: string): string[] {\n  try {\n    return fs.readdirSync(dir);\n  } catch {\n    return [];\n  }\n}\n\n/**\n * List entries in a directory that end with `.jsonl`. Returns `[]` on\n * read errors. The result preserves directory order (no sorting).\n */\nexport function listJsonl(dir: string): string[] {\n  return safeReaddir(dir).filter((name) => name.endsWith(\".jsonl\"));\n}\n\n/**\n * Get birth times for .jsonl session files across multiple directories.\n *\n * Enumerates each directory with readdirSync and stats each .jsonl file\n * to get its birth time. No shell commands are used.\n * Returns empty array if no directories have .jsonl files or reads fail.\n * resolvedCwd is left empty — the adapter must set it.\n */\nexport function batchGetSessionFileBirthtimes(dirs: string[]): SessionFile[] {\n  if (dirs.length === 0) return [];\n\n  const results: SessionFile[] = [];\n\n  for (const dir of dirs) {\n    let entries: string[];\n    try {\n      entries = fs.readdirSync(dir);\n    } catch {\n      continue;\n    }\n\n    for (const entry of entries) {\n      if (!entry.endsWith(\".jsonl\")) continue;\n\n      const filePath = path.join(dir, entry);\n\n      let birthtimeMs: number;\n      try {\n        birthtimeMs = fs.statSync(filePath).birthtimeMs;\n      } catch {\n        continue;\n      }\n\n      if (!Number.isFinite(birthtimeMs) || birthtimeMs <= 0) continue;\n\n      const sessionId = entry.replace(/\\.jsonl$/, \"\");\n\n      results.push({\n        sessionId,\n        filePath,\n        projectDir: dir,\n        birthtimeMs,\n        resolvedCwd: \"\",\n      });\n    }\n  }\n\n  return results;\n}\n"],"names":["fs","path","isDirectory","p","safeStat","isSafePathSegment","value","length","includes","basename","filePath","statSync","undefined","safeReadFile","readFileSync","safeReaddir","dir","readdirSync","listJsonl","filter","name","endsWith","batchGetSessionFileBirthtimes","dirs","results","entries","entry","join","birthtimeMs","Number","isFinite","sessionId","replace","push","projectDir","resolvedCwd"],"mappings":"AAAA;;;;;CAKC,GAED,YAAYA,QAAQ,KAAK;AACzB,YAAYC,UAAU,OAAO;AAsB7B;;;CAGC,GACD,OAAO,SAASC,YAAYC,CAAS;IACnC,OAAOC,SAASD,IAAID,iBAAiB;AACvC;AAEA,kFAAkF,GAClF,OAAO,SAASG,kBAAkBC,KAAa;IAC7C,OACEA,MAAMC,MAAM,GAAG,KACfD,UAAU,OACVA,UAAU,QACV,CAACA,MAAME,QAAQ,CAAC,SAChBP,KAAKQ,QAAQ,CAACH,WAAWA;AAE7B;AAEA;;;CAGC,GACD,OAAO,SAASF,SAASM,QAAgB;IACvC,IAAI;QACF,OAAOV,GAAGW,QAAQ,CAACD;IACrB,EAAE,OAAM;QACN,OAAOE;IACT;AACF;AAEA;;;;CAIC,GACD,OAAO,SAASC,aAAaH,QAAgB;IAC3C,IAAI;QACF,OAAOV,GAAGc,YAAY,CAACJ,UAAU;IACnC,EAAE,OAAM;QACN,OAAOE;IACT;AACF;AAEA;;;;CAIC,GACD,OAAO,SAASG,YAAYC,GAAW;IACrC,IAAI;QACF,OAAOhB,GAAGiB,WAAW,CAACD;IACxB,EAAE,OAAM;QACN,OAAO,EAAE;IACX;AACF;AAEA;;;CAGC,GACD,OAAO,SAASE,UAAUF,GAAW;IACnC,OAAOD,YAAYC,KAAKG,MAAM,CAAC,CAACC,OAASA,KAAKC,QAAQ,CAAC;AACzD;AAEA;;;;;;;CAOC,GACD,OAAO,SAASC,8BAA8BC,IAAc;IAC1D,IAAIA,KAAKhB,MAAM,KAAK,GAAG,OAAO,EAAE;IAEhC,MAAMiB,UAAyB,EAAE;IAEjC,KAAK,MAAMR,OAAOO,KAAM;QACtB,IAAIE;QACJ,IAAI;YACFA,UAAUzB,GAAGiB,WAAW,CAACD;QAC3B,EAAE,OAAM;YACN;QACF;QAEA,KAAK,MAAMU,SAASD,QAAS;YAC3B,IAAI,CAACC,MAAML,QAAQ,CAAC,WAAW;YAE/B,MAAMX,WAAWT,KAAK0B,IAAI,CAACX,KAAKU;YAEhC,IAAIE;YACJ,IAAI;gBACFA,cAAc5B,GAAGW,QAAQ,CAACD,UAAUkB,WAAW;YACjD,EAAE,OAAM;gBACN;YACF;YAEA,IAAI,CAACC,OAAOC,QAAQ,CAACF,gBAAgBA,eAAe,GAAG;YAEvD,MAAMG,YAAYL,MAAMM,OAAO,CAAC,YAAY;YAE5CR,QAAQS,IAAI,CAAC;gBACXF;gBACArB;gBACAwB,YAAYlB;gBACZY;gBACAO,aAAa;YACf;QACF;IACF;IAEA,OAAOX;AACT"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-devkit/agent-manager",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "Standalone agent detection and management utilities for AI DevKit",
   "keywords": [
     "agent",

package/src/AgentManager.ts

@@ -347,6 +347,40 @@ export class AgentManager {
     return merged;
   }
 
+  /** Resolve an exact historical session ID across the selected providers. */
+  async findSessionsById(
+    sessionId: string,
+    opts?: Pick<ListSessionsOptions, "type">,
+  ): Promise<SessionSummary[]> {
+    const targetAdapters = Array.from(this.adapters.values()).filter(
+      (adapter) => opts?.type === undefined || adapter.type === opts.type,
+    );
+    const errors: Array<{ type: string; error: Error }> = [];
+
+    const results = await Promise.all(
+      targetAdapters.map(async (adapter) => {
+        try {
+          if (adapter.findSessionsById) return await adapter.findSessionsById(sessionId);
+          const sessions = await adapter.listSessions(opts);
+          return sessions.filter((session) => session.sessionId === sessionId);
+        } catch (error) {
+          const err = error instanceof Error ? error : new Error(String(error));
+          errors.push({ type: adapter.type, error: err });
+          return [];
+        }
+      }),
+    );
+
+    if (errors.length > 0) {
+      console.error(`Warning: ${errors.length} adapter(s) failed to find session by ID:`);
+      for (const { type, error } of errors) {
+        console.error(`  - ${type}: ${error.message}`);
+      }
+    }
+
+    return results.flat();
+  }
+
   /**
    * Get count of registered adapters
    *

package/src/__tests__/AgentManager.test.ts

@@ -21,6 +21,7 @@ import type { HerdrAgentPane } from "../runtime/herdr/HerdrAgentDiscovery.js";
 // Mock adapter for testing
 class MockAdapter implements AgentAdapter {
   public lastListSessionsOpts: unknown = undefined;
+  public findSessionsByIdCalls: string[] = [];
 
   constructor(
     public readonly type: AgentType,
@@ -53,6 +54,11 @@ class MockAdapter implements AgentAdapter {
     return this.mockSessions;
   }
 
+  async findSessionsById(sessionId: string): Promise<SessionSummary[]> {
+    this.findSessionsByIdCalls.push(sessionId);
+    return this.mockSessions.filter((session) => session.sessionId === sessionId);
+  }
+
   setAgents(agents: AgentInfo[]): void {
     this.mockAgents = agents;
   }
@@ -1119,6 +1125,60 @@ describe("AgentManager", () => {
     });
   });
 
+  describe("findSessionsById", () => {
+    const session = (type: AgentType, sessionId: string): SessionSummary => ({
+      type,
+      sessionId,
+      cwd: "/repo",
+      firstUserMessage: "hello",
+      lastActive: new Date("2025-01-01T00:00:00Z"),
+      startedAt: new Date("2025-01-01T00:00:00Z"),
+      sessionFilePath: `/tmp/${sessionId}`,
+    });
+
+    it("uses each built-in adapter direct lookup and preserves cross-provider ambiguity", async () => {
+      const claude = new MockAdapter("claude", [], false, [session("claude", "shared")]);
+      const codex = new MockAdapter("codex", [], false, [session("codex", "shared")]);
+      manager.registerAdapter(claude);
+      manager.registerAdapter(codex);
+
+      const result = await manager.findSessionsById("shared");
+
+      expect(result).toHaveLength(2);
+      expect(claude.findSessionsByIdCalls).toEqual(["shared"]);
+      expect(codex.findSessionsByIdCalls).toEqual(["shared"]);
+      expect(claude.lastListSessionsOpts).toBeUndefined();
+      expect(codex.lastListSessionsOpts).toBeUndefined();
+    });
+
+    it("skips non-matching providers when type is supplied", async () => {
+      const claude = new MockAdapter("claude", [], false, [session("claude", "target")]);
+      const codex = new MockAdapter("codex", [], false, [session("codex", "target")]);
+      manager.registerAdapter(claude);
+      manager.registerAdapter(codex);
+
+      const result = await manager.findSessionsById("target", { type: "codex" });
+
+      expect(result).toEqual([expect.objectContaining({ type: "codex", sessionId: "target" })]);
+      expect(claude.findSessionsByIdCalls).toEqual([]);
+      expect(codex.findSessionsByIdCalls).toEqual(["target"]);
+    });
+
+    it("falls back to filtered listing for external adapters without direct lookup", async () => {
+      const external = new MockAdapter("other", [], false, [
+        session("other", "target"),
+        session("other", "different"),
+      ]);
+      (external as Partial<AgentAdapter>).findSessionsById = undefined;
+      manager.registerAdapter(external);
+
+      const result = await manager.findSessionsById("target");
+
+      expect(result).toEqual([expect.objectContaining({ sessionId: "target" })]);
+      expect(external.lastListSessionsOpts).toEqual(undefined);
+    });
+  });
+
   describe("resolveAgent", () => {
     it("should return null for empty input or empty agents list", () => {
       const agent = createMockAgent({ name: "test-agent" });

package/src/__tests__/adapters/ClaudeCodeAdapter.test.ts

@@ -1624,6 +1624,29 @@ describe("ClaudeCodeAdapter", () => {
       expect(cwds).toEqual([cwdA, cwdB]);
     });
 
+    it("finds an exact session ID without returning other project sessions", async () => {
+      const wantedPath = writeSession(path.join(projectsDir, "-repo-a"), "wanted", [
+        {
+          type: "user",
+          timestamp: "2025-01-01T00:00:00Z",
+          cwd: "/repo-a",
+          message: { content: "wanted prompt" },
+        },
+      ]);
+      writeSession(path.join(projectsDir, "-repo-b"), "other", [
+        {
+          type: "user",
+          timestamp: "2025-01-01T00:00:00Z",
+          cwd: "/repo-b",
+          message: { content: "other prompt" },
+        },
+      ]);
+
+      await expect(adapter.findSessionsById("wanted")).resolves.toEqual([
+        expect.objectContaining({ sessionId: "wanted", sessionFilePath: wantedPath }),
+      ]);
+    });
+
     it("drops sessions whose recorded cwd does not match opts.cwd (strict equality)", async () => {
       const cwdReal = "/Users/test/foo";
       const cwdRequested = "/Users/test/foo/sub";

package/src/__tests__/adapters/CodexAdapter.test.ts

@@ -339,6 +339,13 @@ describe("CodexAdapter", () => {
         sessionFilePath: sessionFile,
       },
     ]);
+    await expect(adapter.findSessionsById("listed")).resolves.toMatchObject([
+      {
+        type: "codex",
+        sessionId: "listed",
+        sessionFilePath: sessionFile,
+      },
+    ]);
   });
 
   function writeSession(

package/src/__tests__/providers/copilot/CopilotAdapter.test.ts

@@ -552,6 +552,18 @@ describe("CopilotAdapter", () => {
       });
     });
 
+    it("finds an exact session ID from its session directory", async () => {
+      writeSession("wanted", { events: [sessionStart("wanted", "/repo")] });
+      writeSession("other", { events: [sessionStart("other", "/other")] });
+
+      await expect(adapter.findSessionsById("wanted")).resolves.toEqual([
+        expect.objectContaining({
+          sessionId: "wanted",
+          sessionFilePath: path.join(sessionStateDir, "wanted", "events.jsonl"),
+        }),
+      ]);
+    });
+
     it("applies strict cwd filter", async () => {
       writeSession("keep", { events: [sessionStart("keep", "/repo")] });
       writeSession("drop", { events: [sessionStart("drop", "/other")] });

package/src/__tests__/providers/gemini/GeminiCliAdapter.test.ts

@@ -1185,6 +1185,27 @@ describe("GeminiCliAdapter", () => {
       });
     });
 
+    it("finds an exact session ID from Gemini metadata", async () => {
+      const wantedPath = writeSession(tmpHome, "aaa", "session-one", {
+        sessionId: "wanted",
+        projectHash: hashProjectRoot("/repo"),
+        startTime: "2025-01-01T00:00:00Z",
+        directories: ["/repo"],
+        messages: [{ type: "user", content: "wanted prompt" }],
+      });
+      writeSession(tmpHome, "bbb", "session-two", {
+        sessionId: "other",
+        projectHash: hashProjectRoot("/other"),
+        startTime: "2025-01-01T00:00:00Z",
+        directories: ["/other"],
+        messages: [{ type: "user", content: "other prompt" }],
+      });
+
+      await expect(adapter.findSessionsById("wanted")).resolves.toEqual([
+        expect.objectContaining({ sessionId: "wanted", sessionFilePath: wantedPath }),
+      ]);
+    });
+
     it("applies strict-equality cwd filter against directories[0]", async () => {
       writeSession(tmpHome, "aaa", "session-keep", {
         sessionId: "keep",

package/src/__tests__/providers/grok/GrokAgentMapper.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+
+import { AgentStatus, type ProcessInfo } from "../../../adapters/AgentAdapter.js";
+import { GrokAgentMapper } from "../../../providers/grok/GrokAgentMapper.js";
+import type { GrokSession } from "../../../providers/grok/GrokSessionParser.js";
+
+function makeProcess(overrides: Partial<ProcessInfo> = {}): ProcessInfo {
+  return { pid: 123, command: "grok", cwd: "/repo/my-app", tty: "ttys001", ...overrides };
+}
+
+function makeSession(overrides: Partial<GrokSession> = {}): GrokSession {
+  return {
+    sessionId: "session-1",
+    projectPath: "/repo/my-app",
+    sessionFilePath: "/home/.grok/sessions/%2Frepo%2Fmy-app/session-1/chat_history.jsonl",
+    sessionStart: new Date(),
+    lastActive: new Date(),
+    lastUserMessage: "Review this change",
+    lastRole: "assistant",
+    ...overrides,
+  };
+}
+
+describe("GrokAgentMapper", () => {
+  const mapper = new GrokAgentMapper();
+
+  it("maps a session to a grok_cli agent pointing at chat_history.jsonl", () => {
+    const agent = mapper.mapSessionToAgent({
+      session: makeSession(),
+      processInfo: makeProcess(),
+    });
+
+    expect(agent).toMatchObject({
+      name: "my-app-123",
+      type: "grok_cli",
+      status: AgentStatus.WAITING,
+      summary: "Review this change",
+      pid: 123,
+      projectPath: "/repo/my-app",
+      sessionId: "session-1",
+      sessionFilePath: "/home/.grok/sessions/%2Frepo%2Fmy-app/session-1/chat_history.jsonl",
+    });
+  });
+
+  it("maps a process-only agent as RUNNING with a pid session id", () => {
+    const agent = mapper.mapProcessOnlyAgent(makeProcess(), "/repo/resolved");
+
+    expect(agent).toMatchObject({
+      type: "grok_cli",
+      status: AgentStatus.RUNNING,
+      summary: "Grok CLI process running",
+      projectPath: "/repo/resolved",
+      sessionId: "pid-123",
+    });
+    expect(agent.sessionFilePath).toBeUndefined();
+  });
+});

package/src/__tests__/{adapters → providers/grok}/GrokCliAdapter.test.ts

@@ -10,18 +10,18 @@ import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
 
-import { GrokCliAdapter } from "../../adapters/GrokCliAdapter.js";
-import type { ProcessInfo } from "../../adapters/AgentAdapter.js";
-import { AgentStatus } from "../../adapters/AgentAdapter.js";
+import { GrokCliAdapter } from "../../../providers/grok/GrokCliAdapter.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";
+} 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");
+vi.mock("../../../utils/process.js", async (importOriginal) => {
+  const actual = (await importOriginal()) as typeof import("../../../utils/process.js");
   return {
     ...actual,
     listAgentProcesses: vi.fn(),
@@ -30,8 +30,8 @@ vi.mock("../../utils/process.js", async (importOriginal) => {
   };
 });
 
-vi.mock("../../utils/matching.js", async (importOriginal) => {
-  const actual = (await importOriginal()) as typeof import("../../utils/matching.js");
+vi.mock("../../../utils/matching.js", async (importOriginal) => {
+  const actual = (await importOriginal()) as typeof import("../../../utils/matching.js");
   return {
     ...actual,
     generateAgentName: vi.fn(),
@@ -335,6 +335,15 @@ describe("GrokCliAdapter", () => {
       );
     });
 
+    it("finds an exact session ID across project groups", async () => {
+      writeSession({});
+      writeSession({ sessionCwd: "/Users/dev/other", id: "other-session" });
+
+      await expect(adapter.findSessionsById(SESSION_ID)).resolves.toEqual([
+        expect.objectContaining({ sessionId: SESSION_ID, cwd }),
+      ]);
+    });
+
     it("applies the cwd filter against the decoded cwd", async () => {
       writeSession({
         sessionCwd: "/Users/dev/project-a",

package/src/__tests__/providers/grok/GrokSessionLocator.test.ts

@@ -0,0 +1,106 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import type { ProcessInfo } from "../../../adapters/AgentAdapter.js";
+import { GrokSessionLocator } from "../../../providers/grok/GrokSessionLocator.js";
+
+describe("GrokSessionLocator", () => {
+  let baseDir: string;
+  let locator: GrokSessionLocator;
+
+  beforeEach(() => {
+    baseDir = fs.mkdtempSync(path.join(os.tmpdir(), "grok-locator-test-"));
+    locator = new GrokSessionLocator({ baseDir });
+  });
+
+  afterEach(() => {
+    fs.rmSync(baseDir, { recursive: true, force: true });
+  });
+
+  function writeSession(cwd: string, id: string, mtime?: Date): string {
+    const sessionDir = path.join(baseDir, "sessions", encodeURIComponent(cwd), id);
+    fs.mkdirSync(sessionDir, { recursive: true });
+    const chatPath = path.join(sessionDir, "chat_history.jsonl");
+    fs.writeFileSync(chatPath, "");
+    if (mtime) fs.utimesSync(chatPath, mtime, mtime);
+    return sessionDir;
+  }
+
+  function proc(overrides: Partial<ProcessInfo> = {}): ProcessInfo {
+    return { pid: 4242, command: "grok", cwd: "/repo/app", tty: "ttys001", ...overrides };
+  }
+
+  describe("matchRunningProcesses", () => {
+    it("prefers the active_sessions.json cwd over the process cwd", () => {
+      const sessionDir = writeSession("/repo/real", "s1");
+      fs.writeFileSync(
+        path.join(baseDir, "active_sessions.json"),
+        JSON.stringify([{ pid: 4242, cwd: "/repo/real" }]),
+      );
+
+      expect(locator.matchRunningProcesses([proc({ cwd: "/wrong" })])).toEqual([
+        { process: expect.objectContaining({ pid: 4242 }), cwd: "/repo/real", sessionDir },
+      ]);
+    });
+
+    it("ignores a malformed active_sessions.json and falls back to the process cwd", () => {
+      const sessionDir = writeSession("/repo/app", "s1");
+      fs.writeFileSync(path.join(baseDir, "active_sessions.json"), "{not json");
+
+      expect(locator.matchRunningProcesses([proc()])[0]).toMatchObject({
+        cwd: "/repo/app",
+        sessionDir,
+      });
+    });
+
+    it("picks the session with the newest chat_history.jsonl", () => {
+      writeSession("/repo/app", "old", new Date(Date.now() - 60_000));
+      const newest = writeSession("/repo/app", "new");
+
+      expect(locator.matchRunningProcesses([proc()])[0].sessionDir).toBe(newest);
+    });
+
+    it("returns a null sessionDir when no cwd is known", () => {
+      expect(locator.matchRunningProcesses([proc({ cwd: "" })])[0]).toMatchObject({
+        cwd: "",
+        sessionDir: null,
+      });
+    });
+  });
+
+  describe("historical sessions", () => {
+    it("discovers session dirs with the decoded group cwd", () => {
+      const a = writeSession("/repo/a", "s1");
+      const b = writeSession("/repo/b", "s2");
+
+      expect(locator.discoverHistoricalSessionDirs()).toEqual(
+        expect.arrayContaining([
+          { sessionDir: a, defaultCwd: "/repo/a" },
+          { sessionDir: b, defaultCwd: "/repo/b" },
+        ]),
+      );
+    });
+
+    it("prefers the .cwd file over the encoded group name", () => {
+      const groupDir = path.join(baseDir, "sessions", "slug-abc123");
+      fs.mkdirSync(path.join(groupDir, "s1"), { recursive: true });
+      fs.writeFileSync(path.join(groupDir, ".cwd"), "/very/long/path\n");
+
+      expect(locator.discoverHistoricalSessionDirs()).toEqual([
+        { sessionDir: path.join(groupDir, "s1"), defaultCwd: "/very/long/path" },
+      ]);
+    });
+
+    it("finds session dirs by id and rejects unsafe ids", () => {
+      const dir = writeSession("/repo/a", "s1");
+      writeSession("/repo/b", "s2");
+
+      expect(locator.findHistoricalSessionDirsById("s1")).toEqual([
+        { sessionDir: dir, defaultCwd: "/repo/a" },
+      ]);
+      expect(locator.findHistoricalSessionDirsById("../s1")).toEqual([]);
+    });
+  });
+});

package/src/__tests__/providers/opencode/OpenCodeAdapter.test.ts

@@ -121,6 +121,24 @@ describe("OpenCodeAdapter", () => {
     ]);
     expect(adapter.getConversation("/not-an-opencode-ref")).toEqual([]);
   });
+
+  it("finds an exact session ID with a targeted database query", async () => {
+    const now = Date.now();
+    writeDatabase(dbPath, {
+      sessions: [
+        { id: "wanted", directory: "/repo", timeCreated: now },
+        { id: "other", directory: "/other", timeCreated: now - 1_000 },
+      ],
+    });
+
+    await expect(adapter.findSessionsById("wanted")).resolves.toEqual([
+      expect.objectContaining({
+        type: "opencode",
+        sessionId: "wanted",
+        sessionFilePath: `${dbPath}::wanted`,
+      }),
+    ]);
+  });
 });
 
 function writeDatabase(

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

@@ -260,6 +260,21 @@ describe("PiAdapter", () => {
     ]);
   });
 
+  it("finds an exact session ID from the filename suffix", async () => {
+    const wanted = writePiSession("/repo/wanted", [
+      { timestamp: "2026-06-10T08:58:20.754Z", sessionId: "sess-wanted", cwd: "/repo/wanted" },
+      { role: "user", content: "wanted" },
+    ]);
+    writePiSession("/repo/other", [
+      { timestamp: "2026-06-10T08:58:20.754Z", sessionId: "sess-other", cwd: "/repo/other" },
+      { role: "user", content: "other" },
+    ]);
+
+    await expect(adapter.findSessionsById("sess-wanted")).resolves.toEqual([
+      expect.objectContaining({ sessionId: "sess-wanted", sessionFilePath: wanted }),
+    ]);
+  });
+
   function makeProcess(overrides: Partial<ProcessInfo>): ProcessInfo {
     return {
       pid: 1,

package/src/__tests__/utils/session.test.ts

@@ -5,7 +5,7 @@
 import type { MockedFunction } from "vitest";
 
 import * as fs from "fs";
-import { batchGetSessionFileBirthtimes } from "../../utils/session.js";
+import { batchGetSessionFileBirthtimes, isSafePathSegment } from "../../utils/session.js";
 
 vi.mock("fs", () => ({
   readdirSync: vi.fn(),
@@ -15,6 +15,16 @@ vi.mock("fs", () => ({
 const mockedReaddirSync = fs.readdirSync as MockedFunction<typeof fs.readdirSync>;
 const mockedStatSync = fs.statSync as MockedFunction<typeof fs.statSync>;
 
+describe("isSafePathSegment", () => {
+  it.each(["", ".", "..", "nested/session", "bad\0id"])("rejects unsafe segment %j", (value) => {
+    expect(isSafePathSegment(value)).toBe(false);
+  });
+
+  it.each(["session-id", ".hidden-session"])("accepts safe segment %j", (value) => {
+    expect(isSafePathSegment(value)).toBe(true);
+  });
+});
+
 describe("batchGetSessionFileBirthtimes", () => {
   beforeEach(() => {
     mockedReaddirSync.mockReset();

package/src/adapters/AgentAdapter.ts

@@ -208,4 +208,13 @@ export interface AgentAdapter {
    * @returns Array of sessions discovered on disk
    */
   listSessions(opts?: ListSessionsOptions): Promise<SessionSummary[]>;
+
+  /**
+   * Resolve exact historical session matches without enumerating every summary.
+   *
+   * Built-in adapters implement this using their provider-native storage shape.
+   * The method remains optional so external adapters can fall back to
+   * {@link listSessions} until they adopt direct lookup.
+   */
+  findSessionsById?(sessionId: string): Promise<SessionSummary[]>;
 }

package/src/adapters/index.ts

@@ -2,7 +2,7 @@ export { ClaudeCodeAdapter } from "../providers/claude/ClaudeCodeAdapter.js";
 export { CodexAdapter } from "../providers/codex/CodexAdapter.js";
 export { CopilotAdapter } from "../providers/copilot/CopilotAdapter.js";
 export { GeminiCliAdapter } from "../providers/gemini/GeminiCliAdapter.js";
-export { GrokCliAdapter } from "./GrokCliAdapter.js";
+export { GrokCliAdapter } from "../providers/grok/GrokCliAdapter.js";
 export { OpenCodeAdapter } from "../providers/opencode/OpenCodeAdapter.js";
 export { PiAdapter } from "../providers/pi/PiAdapter.js";
 export { AgentStatus } from "./AgentAdapter.js";

package/src/index.ts

@@ -29,7 +29,7 @@ export { ClaudeCodeAdapter } from "./providers/claude/ClaudeCodeAdapter.js";
 export { CodexAdapter } from "./providers/codex/CodexAdapter.js";
 export { CopilotAdapter } from "./providers/copilot/CopilotAdapter.js";
 export { GeminiCliAdapter } from "./providers/gemini/GeminiCliAdapter.js";
-export { GrokCliAdapter } from "./adapters/GrokCliAdapter.js";
+export { GrokCliAdapter } from "./providers/grok/GrokCliAdapter.js";
 export { OpenCodeAdapter } from "./providers/opencode/OpenCodeAdapter.js";
 export { PiAdapter } from "./providers/pi/PiAdapter.js";
 export { AgentStatus } from "./adapters/AgentAdapter.js";

package/src/providers/claude/ClaudeCodeAdapter.ts

@@ -138,31 +138,36 @@ export class ClaudeCodeAdapter implements AgentAdapter {
     const summaries: SessionSummary[] = [];
 
     for (const { filePath, defaultCwd } of candidates) {
-      const session = this.parser.readSession(filePath, defaultCwd);
-      if (!session) continue;
-
-      // Drop sessions whose JSONL had no parseable conversation entries.
-      // readSession is permissive (returns a shell record even when every
-      // line fails to parse); listSessions needs at least one real entry
-      // so we don't surface garbage files.
-      if (!session.lastEntryType) continue;
-
-      const recordedCwd = session.lastCwd || defaultCwd;
-      if (filterCwd !== undefined && recordedCwd !== filterCwd) continue;
-
-      const stat = safeStat(filePath);
-
-      summaries.push({
-        type: "claude",
-        sessionId: session.sessionId,
-        cwd: recordedCwd,
-        firstUserMessage: session.firstUserMessage || "",
-        lastActive: session.lastActive ?? stat?.mtime ?? new Date(),
-        startedAt: session.sessionStart ?? stat?.birthtime ?? stat?.mtime ?? new Date(),
-        sessionFilePath: filePath,
-      });
+      const summary = this.toSessionSummary(filePath, defaultCwd);
+      if (!summary) continue;
+      if (filterCwd !== undefined && summary.cwd !== filterCwd) continue;
+      summaries.push(summary);
     }
 
     return summaries;
   }
+
+  async findSessionsById(sessionId: string): Promise<SessionSummary[]> {
+    return this.createLocator()
+      .findHistoricalSessionFilesById(sessionId)
+      .map(({ filePath, defaultCwd }) => this.toSessionSummary(filePath, defaultCwd))
+      .filter((summary): summary is SessionSummary => summary?.sessionId === sessionId);
+  }
+
+  private toSessionSummary(filePath: string, defaultCwd: string): SessionSummary | null {
+    const session = this.parser.readSession(filePath, defaultCwd);
+    if (!session?.lastEntryType) return null;
+
+    const recordedCwd = session.lastCwd || defaultCwd;
+    const stat = safeStat(filePath);
+    return {
+      type: "claude",
+      sessionId: session.sessionId,
+      cwd: recordedCwd,
+      firstUserMessage: session.firstUserMessage || "",
+      lastActive: session.lastActive ?? stat?.mtime ?? new Date(),
+      startedAt: session.sessionStart ?? stat?.birthtime ?? stat?.mtime ?? new Date(),
+      sessionFilePath: filePath,
+    };
+  }
 }