@ai-devkit/agent-manager 0.36.0 → 0.37.0

package/src/harnesses/gemini/GeminiSessionLocator.ts

@@ -0,0 +1,394 @@
+import * as crypto from "crypto";
+import * as fs from "fs";
+import * as path from "path";
+import type { ProcessInfo } from "../../adapters/AgentAdapter.js";
+import { MATCH_TOLERANCE_MS } from "../../utils/matchingConstants.js";
+import type { SessionFile } from "../../utils/session.js";
+import { isDirectory, safeReadFile, safeReaddir, safeStat } from "../../utils/session.js";
+import { fileSignature } from "./fileSignature.js";
+import { isSessionLogPath } from "./GeminiSessionParser.js";
+import { homeDir } from "../shared.js";
+
+export interface GeminiSessionDiscovery {
+  sessions: SessionFile[];
+}
+
+export interface GeminiSessionLocatorOptions {
+  geminiTmpDir?: string;
+}
+
+interface GeminiSessionMetadata {
+  sessionId?: string;
+  projectHash?: string;
+}
+
+interface CachedSessionMetadata extends GeminiSessionMetadata {
+  signature: string;
+}
+
+interface CachedProjectMarker {
+  signature: string;
+  projectRoot: string;
+}
+
+interface CandidateProjects {
+  /** sha256(projectRoot) -> process CWD that may own sessions for that root. */
+  cwdByHash: Map<string, string>;
+  /** Normalized candidate project roots, compared against `.project_root` markers. */
+  roots: Set<string>;
+}
+
+const SESSION_FILE_PREFIX = "session-";
+/** Legacy single-document sessions. */
+const SESSION_DOCUMENT_EXTENSION = ".json";
+/** Gemini CLI 0.46+ append-only session logs; line 1 is the metadata record. */
+const SESSION_LOG_EXTENSION = ".jsonl";
+const CHATS_DIR_NAME = "chats";
+/** Ownership marker Gemini CLI writes into slug-named project temp dirs. */
+const PROJECT_ROOT_MARKER = ".project_root";
+/** Legacy Gemini CLI temp dirs are named sha256(projectRoot). */
+const LEGACY_HASH_DIR_PATTERN = /^[0-9a-f]{64}$/;
+/** Slack for coarse filesystem timestamp granularity. */
+const MTIME_SLACK_MS = 2 * 1000;
+/**
+ * Both formats start with sessionId/projectHash (a legacy document's leading
+ * keys, a log's line-1 metadata record); a small head is enough.
+ */
+const METADATA_HEAD_BYTES = 8 * 1024;
+
+export class GeminiSessionLocator {
+  private readonly geminiTmpDir: string;
+  private metadataCache = new Map<string, CachedSessionMetadata>();
+  private markerCache = new Map<string, CachedProjectMarker>();
+
+  constructor(options: GeminiSessionLocatorOptions = {}) {
+    this.geminiTmpDir = options.geminiTmpDir ?? path.join(homeDir(), ".gemini", "tmp");
+  }
+
+  /**
+   * Discover session files for the given processes.
+   *
+   * Gemini CLI writes sessions to ~/.gemini/tmp/<shortId>/chats/session-*.jsonl
+   * (0.46+; older versions wrote session-*.json) where <shortId> is either sha256(projectRoot) (legacy) or a slug whose
+   * owner is recorded in <shortId>/.project_root. Each session's projectHash
+   * is matched against sha256 of every candidate project root of a process.
+   *
+   * To keep each refresh cheap:
+   * - project dirs whose name or marker can't belong to a candidate root are
+   *   skipped without listing or opening their chats;
+   * - chat files last modified before the earliest candidate process start
+   *   (minus the matching tolerance) are skipped after a stat;
+   * - sessionId/projectHash come from a bounded head read, cached by
+   *   inode+size+mtime, so unchanged files are never re-read.
+   */
+  discoverSessions(processes: ProcessInfo[]): GeminiSessionDiscovery {
+    const empty: GeminiSessionDiscovery = { sessions: [] };
+    if (!fs.existsSync(this.geminiTmpDir)) return empty;
+
+    const candidates = this.buildCandidateProjects(processes);
+    if (candidates.cwdByHash.size === 0) return empty;
+
+    let shortIdEntries: string[];
+    try {
+      shortIdEntries = fs.readdirSync(this.geminiTmpDir);
+    } catch {
+      return empty;
+    }
+
+    const minMtimeMs = this.earliestMatchableMtime(processes);
+    const nextMetadataCache = new Map<string, CachedSessionMetadata>();
+    const nextMarkerCache = new Map<string, CachedProjectMarker>();
+    const sessions: SessionFile[] = [];
+
+    for (const shortId of shortIdEntries) {
+      const projectDir = path.join(this.geminiTmpDir, shortId);
+      if (!this.mayBelongToCandidates(projectDir, shortId, candidates, nextMarkerCache)) continue;
+
+      const chatsDir = path.join(projectDir, CHATS_DIR_NAME);
+      if (!isDirectory(chatsDir)) continue;
+
+      for (const fileName of this.listSessionFileNames(chatsDir)) {
+        const session = this.readCandidateSession(
+          chatsDir,
+          fileName,
+          candidates.cwdByHash,
+          minMtimeMs,
+          nextMetadataCache,
+        );
+        if (session) sessions.push(session);
+      }
+    }
+
+    // Keep metadata only for files still in scope so the caches stay bounded.
+    this.metadataCache = nextMetadataCache;
+    this.markerCache = nextMarkerCache;
+    return { sessions };
+  }
+
+  discoverHistoricalSessionFiles(): string[] {
+    if (!isDirectory(this.geminiTmpDir)) return [];
+
+    const files: string[] = [];
+    for (const shortId of safeReaddir(this.geminiTmpDir)) {
+      const chatsDir = path.join(this.geminiTmpDir, shortId, CHATS_DIR_NAME);
+      if (!isDirectory(chatsDir)) continue;
+
+      for (const fileName of this.listSessionFileNames(chatsDir)) {
+        files.push(path.join(chatsDir, fileName));
+      }
+    }
+
+    return files;
+  }
+
+  private readCandidateSession(
+    chatsDir: string,
+    fileName: string,
+    cwdByHash: Map<string, string>,
+    minMtimeMs: number,
+    nextMetadataCache: Map<string, CachedSessionMetadata>,
+  ): SessionFile | null {
+    const filePath = path.join(chatsDir, fileName);
+
+    const stat = safeStat(filePath);
+    if (!stat || stat.mtimeMs < minMtimeMs) return null;
+
+    const metadata = this.readSessionMetadata(filePath, stat);
+    nextMetadataCache.set(filePath, metadata);
+    if (!metadata.projectHash) return null;
+
+    const resolvedCwd = cwdByHash.get(metadata.projectHash);
+    if (!resolvedCwd) return null;
+
+    return {
+      sessionId: metadata.sessionId || fileName.replace(/\.jsonl?$/, ""),
+      filePath,
+      projectDir: chatsDir,
+      birthtimeMs: stat.birthtimeMs,
+      resolvedCwd,
+    };
+  }
+
+  private readSessionMetadata(filePath: string, stat: fs.Stats): CachedSessionMetadata {
+    const signature = fileSignature(stat);
+    const cached = this.metadataCache.get(filePath);
+    if (cached?.signature === signature) return cached;
+
+    return { signature, ...this.extractSessionMetadata(filePath) };
+  }
+
+  /**
+   * Read sessionId/projectHash from the first METADATA_HEAD_BYTES. Files that
+   * fit in the head are parsed as JSON exactly; larger files are scanned for
+   * the leading keys and only fully parsed when the head lacks them.
+   */
+  private extractSessionMetadata(filePath: string): GeminiSessionMetadata {
+    const head = this.readHead(filePath);
+    if (head === null) return {};
+    if (isSessionLogPath(filePath)) return this.extractLogMetadata(head);
+    if (head.complete) return this.pickMetadata(this.parseSessionMetadata(head.text));
+
+    const sessionId = this.matchStringField(head.text, "sessionId");
+    const projectHash = this.matchStringField(head.text, "projectHash");
+    if (sessionId !== undefined && projectHash !== undefined) {
+      return { sessionId, projectHash };
+    }
+
+    const content = safeReadFile(filePath);
+    if (content === undefined) return {};
+    return this.pickMetadata(this.parseSessionMetadata(content));
+  }
+
+  /**
+   * A `.jsonl` log's metadata is its first line. Never fall back to reading
+   * the whole log: it only grows, and a log whose first record is not
+   * metadata cannot be attributed from its head anyway.
+   */
+  private extractLogMetadata(head: { text: string; complete: boolean }): GeminiSessionMetadata {
+    const newline = head.text.indexOf("\n");
+    if (newline !== -1 || head.complete) {
+      const firstLine = newline === -1 ? head.text : head.text.slice(0, newline);
+      return this.pickMetadata(this.parseSessionMetadata(firstLine));
+    }
+    // First line longer than the head: pick the leading keys from its prefix.
+    return {
+      sessionId: this.matchStringField(head.text, "sessionId"),
+      projectHash: this.matchStringField(head.text, "projectHash"),
+    };
+  }
+
+  private readHead(filePath: string): { text: string; complete: boolean } | null {
+    let fd: number | undefined;
+    try {
+      fd = fs.openSync(filePath, "r");
+      // One extra byte tells "exactly METADATA_HEAD_BYTES long" from "longer".
+      const buffer = Buffer.alloc(METADATA_HEAD_BYTES + 1);
+      let length = 0;
+      while (length < buffer.length) {
+        const bytesRead = fs.readSync(fd, buffer, length, buffer.length - length, length);
+        if (bytesRead === 0) break;
+        length += bytesRead;
+      }
+      return {
+        text: buffer.toString("utf-8", 0, Math.min(length, METADATA_HEAD_BYTES)),
+        complete: length <= METADATA_HEAD_BYTES,
+      };
+    } catch {
+      return null;
+    } finally {
+      if (fd !== undefined) {
+        try {
+          fs.closeSync(fd);
+        } catch {
+          // Nothing useful to do if closing a read-only descriptor fails.
+        }
+      }
+    }
+  }
+
+  private matchStringField(text: string, key: string): string | undefined {
+    const match = new RegExp(`"${key}"\\s*:\\s*"((?:[^"\\\\]|\\\\.)*)"`).exec(text);
+    if (!match) return undefined;
+    try {
+      return JSON.parse(`"${match[1]}"`) as string;
+    } catch {
+      return undefined;
+    }
+  }
+
+  private pickMetadata(parsed: GeminiSessionMetadata | null): GeminiSessionMetadata {
+    if (!parsed || typeof parsed !== "object") return {};
+    return { sessionId: parsed.sessionId, projectHash: parsed.projectHash };
+  }
+
+  /**
+   * Decide from the directory name or its `.project_root` marker whether a
+   * project temp dir can hold sessions for a candidate root. Dirs with no
+   * recognisable ownership are scanned conservatively.
+   */
+  private mayBelongToCandidates(
+    projectDir: string,
+    shortId: string,
+    candidates: CandidateProjects,
+    nextMarkerCache: Map<string, CachedProjectMarker>,
+  ): boolean {
+    if (LEGACY_HASH_DIR_PATTERN.test(shortId)) return candidates.cwdByHash.has(shortId);
+
+    const projectRoot = this.readProjectMarker(projectDir, nextMarkerCache);
+    if (projectRoot === undefined) return true;
+    return candidates.roots.has(this.normalizeRoot(projectRoot));
+  }
+
+  private readProjectMarker(
+    projectDir: string,
+    nextMarkerCache: Map<string, CachedProjectMarker>,
+  ): string | undefined {
+    const markerPath = path.join(projectDir, PROJECT_ROOT_MARKER);
+    const stat = safeStat(markerPath);
+    if (!stat?.isFile()) return undefined;
+
+    const signature = fileSignature(stat);
+    const cached = this.markerCache.get(markerPath);
+    const projectRoot =
+      cached?.signature === signature ? cached.projectRoot : safeReadFile(markerPath)?.trim();
+    if (!projectRoot) return undefined;
+
+    nextMarkerCache.set(markerPath, { signature, projectRoot });
+    return projectRoot;
+  }
+
+  private earliestMatchableMtime(processes: ProcessInfo[]): number {
+    let earliestStartMs = Number.POSITIVE_INFINITY;
+    for (const proc of processes) {
+      if (!proc.cwd || !proc.startTime) continue;
+      const startMs = proc.startTime.getTime();
+      if (Number.isFinite(startMs)) earliestStartMs = Math.min(earliestStartMs, startMs);
+    }
+    // No start times: nothing can be windowed safely, so scan every file.
+    if (!Number.isFinite(earliestStartMs)) return Number.NEGATIVE_INFINITY;
+    // A file last modified before (earliest start - matcher tolerance) was also
+    // born before it, so it can never be matched to any candidate process.
+    return earliestStartMs - MATCH_TOLERANCE_MS - MTIME_SLACK_MS;
+  }
+
+  private buildCandidateProjects(processes: ProcessInfo[]): CandidateProjects {
+    const cwdByHash = new Map<string, string>();
+    const roots = new Set<string>();
+    for (const proc of processes) {
+      if (!proc.cwd) continue;
+
+      // Gemini CLI resolves its project root by walking up from the
+      // startup directory looking for a `.git` boundary marker. A
+      // session's projectHash therefore tracks that ancestor rather
+      // than the process' actual CWD. Enumerate every ancestor as a
+      // candidate so subdirectory invocations still line up with the
+      // session the Gemini process wrote.
+      for (const candidate of this.candidateProjectRoots(proc.cwd)) {
+        roots.add(this.normalizeRoot(candidate));
+        const hash = this.hashProjectRoot(candidate);
+        if (!cwdByHash.has(hash)) {
+          cwdByHash.set(hash, proc.cwd);
+        }
+      }
+    }
+    return { cwdByHash, roots };
+  }
+
+  /** Match Gemini CLI's project registry normalization (lower-cased on Windows). */
+  private normalizeRoot(projectRoot: string): string {
+    const resolved = path.resolve(projectRoot);
+    return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+  }
+
+  private candidateProjectRoots(cwd: string): string[] {
+    const roots: string[] = [];
+    let current = path.resolve(cwd);
+    let parent = path.dirname(current);
+    while (parent !== current) {
+      roots.push(current);
+      current = parent;
+      parent = path.dirname(current);
+    }
+    roots.push(current);
+    return roots;
+  }
+
+  private hashProjectRoot(projectRoot: string): string {
+    return crypto.createHash("sha256").update(projectRoot).digest("hex");
+  }
+
+  /**
+   * Session files in a chats dir, in both formats. Resuming a legacy session
+   * makes Gemini CLI continue it in `<name>.jsonl` next to the stale
+   * `<name>.json`, so a `.json` with a `.jsonl` sibling is skipped.
+   */
+  private listSessionFileNames(chatsDir: string): string[] {
+    const sessionFiles = safeReaddir(chatsDir).filter((fileName) => this.isSessionFile(fileName));
+    const names = new Set(sessionFiles);
+    return sessionFiles.filter(
+      (fileName) =>
+        !fileName.endsWith(SESSION_DOCUMENT_EXTENSION) ||
+        !names.has(this.toSessionLogName(fileName)),
+    );
+  }
+
+  private toSessionLogName(documentFileName: string): string {
+    const baseName = documentFileName.slice(0, -SESSION_DOCUMENT_EXTENSION.length);
+    return `${baseName}${SESSION_LOG_EXTENSION}`;
+  }
+
+  private isSessionFile(fileName: string): boolean {
+    return (
+      fileName.startsWith(SESSION_FILE_PREFIX) &&
+      (fileName.endsWith(SESSION_DOCUMENT_EXTENSION) || fileName.endsWith(SESSION_LOG_EXTENSION))
+    );
+  }
+
+  private parseSessionMetadata(content: string): GeminiSessionMetadata | null {
+    try {
+      return JSON.parse(content) as GeminiSessionMetadata;
+    } catch {
+      return null;
+    }
+  }
+}

package/src/{providers → harnesses}/gemini/GeminiSessionParser.ts

@@ -1,7 +1,14 @@
 import * as fs from "fs";
-import type { ConversationMessage, SessionSummary } from "../../adapters/AgentAdapter.js";
+import type {
+  ConversationMessage,
+  ConversationOptions,
+  SessionSummary,
+} from "../../adapters/AgentAdapter.js";
 import { AgentStatus } from "../../adapters/AgentAdapter.js";
+import { sliceTail } from "../../utils/jsonlTail.js";
 import { safeReadFile, safeStat } from "../../utils/session.js";
+import { fileSignature } from "./fileSignature.js";
+import { isIdle, parseTimestamp, SUMMARY_MAX_LENGTH, truncate } from "../shared.js";
 
 /**
  * A single Gemini CLI message content part. Mirrors the `{text?: string}`
@@ -54,31 +61,70 @@ export interface GeminiSession {
   lastMessageType?: string;
 }
 
-const IDLE_THRESHOLD_MINUTES = 5;
+interface CachedParsedSession {
+  signature: string;
+  session: GeminiSession | null;
+}
+
+const SESSION_LOG_EXTENSION = ".jsonl";
+/** Parsed sessions are small (summary is truncated); cap entries, not bytes. */
+const MAX_CACHED_SESSIONS = 256;
 
 export class GeminiSessionParser {
+  private readonly sessionCache = new Map<string, CachedParsedSession>();
+
   /**
    * Parse session file content into GeminiSession.
-   * Uses cached content if available, otherwise reads from disk.
+   * Uses the given content if available; otherwise reads from disk, reusing
+   * the previous result while the file's inode, size and mtime are unchanged.
    */
   parseSession(cachedContent: string | undefined, filePath: string): GeminiSession | null {
-    const content = cachedContent ?? this.readSessionFile(filePath);
-    if (content === null) return null;
+    const fileStat = safeStat(filePath);
+    if (cachedContent !== undefined) return this.buildSession(cachedContent, filePath, fileStat);
+
+    if (!fileStat) {
+      this.sessionCache.delete(filePath);
+      return null;
+    }
+
+    const signature = fileSignature(fileStat);
+    const cached = this.sessionCache.get(filePath);
+    if (cached?.signature === signature) return cached.session;
+
+    const content = this.readSessionFile(filePath);
+    const session = content === null ? null : this.buildSession(content, filePath, fileStat);
+    this.rememberSession(filePath, { signature, session });
+    return session;
+  }
+
+  private rememberSession(filePath: string, entry: CachedParsedSession): void {
+    this.sessionCache.delete(filePath);
+    this.sessionCache.set(filePath, entry);
+    while (this.sessionCache.size > MAX_CACHED_SESSIONS) {
+      const oldest = this.sessionCache.keys().next().value;
+      if (oldest === undefined) break;
+      this.sessionCache.delete(oldest);
+    }
+  }
 
-    const parsed = this.parseSessionJson(content);
+  private buildSession(
+    content: string,
+    filePath: string,
+    fileStat: fs.Stats | undefined,
+  ): GeminiSession | null {
+    const parsed = this.parseSessionContent(content, filePath);
     if (!parsed?.sessionId) return null;
 
     const messages = Array.isArray(parsed.messages) ? parsed.messages : [];
     const lastEntry = messages.length > 0 ? messages[messages.length - 1] : undefined;
-    const fileStat = safeStat(filePath);
 
     const lastActive =
-      this.parseTimestamp(parsed.lastUpdated) ||
-      this.parseTimestamp(lastEntry?.timestamp) ||
+      parseTimestamp(parsed.lastUpdated) ||
+      parseTimestamp(lastEntry?.timestamp) ||
       fileStat?.mtime ||
       new Date();
 
-    const sessionStart = this.parseTimestamp(parsed.startTime) || lastActive;
+    const sessionStart = parseTimestamp(parsed.startTime) || lastActive;
     const projectPath =
       Array.isArray(parsed.directories) && parsed.directories.length > 0
         ? parsed.directories[0]
@@ -95,10 +141,7 @@ export class GeminiSessionParser {
   }
 
   determineStatus(session: GeminiSession): AgentStatus {
-    const diffMs = Date.now() - session.lastActive.getTime();
-    const diffMinutes = diffMs / 60000;
-
-    if (diffMinutes > IDLE_THRESHOLD_MINUTES) {
+    if (isIdle(session.lastActive)) {
       return AgentStatus.IDLE;
     }
 
@@ -114,13 +157,17 @@ export class GeminiSessionParser {
    *
    * Gemini sessions store messages in an array with `type` field — typically
    * 'user' or 'gemini' for visible turns, with tool and system entries mixed in.
+   *
+   * `tail` only slices the result: the session is a single JSON document, so
+   * it cannot be read from the end and is always parsed in full. Callers that
+   * poll (the console preview) rely on their mtime cache to skip re-parses.
    */
-  getConversation(sessionFilePath: string, options?: { verbose?: boolean }): ConversationMessage[] {
+  getConversation(sessionFilePath: string, options?: ConversationOptions): ConversationMessage[] {
     const verbose = options?.verbose ?? false;
     const content = safeReadFile(sessionFilePath);
     if (content === undefined) return [];
 
-    const parsed = this.parseSessionJson(content);
+    const parsed = this.parseSessionContent(content, sessionFilePath);
     if (!Array.isArray(parsed?.messages)) return [];
 
     const messages: ConversationMessage[] = [];
@@ -138,7 +185,7 @@ export class GeminiSessionParser {
       });
     }
 
-    return messages;
+    return sliceTail(messages, options?.tail);
   }
 
   /**
@@ -150,7 +197,7 @@ export class GeminiSessionParser {
     const content = safeReadFile(filePath);
     if (content === undefined) return null;
 
-    const parsed = this.parseSessionJson(content);
+    const parsed = this.parseSessionContent(content, filePath);
     if (!parsed?.sessionId) return null;
 
     const messages = Array.isArray(parsed.messages) ? parsed.messages : [];
@@ -161,13 +208,13 @@ export class GeminiSessionParser {
         : "";
 
     const stat = safeStat(filePath);
-    const lastEntryTimestamp = this.parseTimestamp(
+    const lastEntryTimestamp = parseTimestamp(
       messages.length > 0 ? messages[messages.length - 1]?.timestamp : undefined,
     );
     const lastActive =
-      this.parseTimestamp(parsed.lastUpdated) || lastEntryTimestamp || stat?.mtime || new Date();
+      parseTimestamp(parsed.lastUpdated) || lastEntryTimestamp || stat?.mtime || new Date();
     const startedAt =
-      this.parseTimestamp(parsed.startTime) || stat?.birthtime || stat?.mtime || lastActive;
+      parseTimestamp(parsed.startTime) || stat?.birthtime || stat?.mtime || lastActive;
 
     return {
       type: "gemini_cli",
@@ -180,6 +227,85 @@ export class GeminiSessionParser {
     };
   }
 
+  /**
+   * Parse either session format into the legacy single-document shape:
+   * `session-*.json` is one JSON document, `session-*.jsonl` (Gemini CLI
+   * 0.46+) is an append-only log replayed by {@link replaySessionLog}.
+   */
+  private parseSessionContent(content: string, filePath: string): GeminiSessionFile | null {
+    return isSessionLogPath(filePath)
+      ? this.replaySessionLog(content)
+      : this.parseSessionJson(content);
+  }
+
+  /**
+   * Rebuild a session document from a `.jsonl` log, mirroring Gemini CLI's
+   * own loader (`loadConversationRecord`):
+   * - a record with a string `id` is a message, upserted by id in place;
+   * - `{"$set": {...}}` merges metadata; a `$set.messages` array replaces
+   *   every message;
+   * - `{"$rewindTo": id}` drops that message and all later ones (all
+   *   messages when the id is unknown);
+   * - a record with `sessionId` and `projectHash` (line 1) merges metadata.
+   * Unknown operators, non-object lines and a torn trailing line (a write
+   * in progress) are ignored.
+   */
+  private replaySessionLog(content: string): GeminiSessionFile | null {
+    let metadata: Record<string, unknown> = {};
+    const messages = new Map<string, GeminiMessageEntry>();
+    const upsertAll = (entries: unknown): void => {
+      if (!Array.isArray(entries)) return;
+      for (const entry of entries) {
+        if (isRecord(entry) && typeof entry.id === "string") messages.set(entry.id, entry);
+      }
+    };
+
+    for (const line of content.split("\n")) {
+      if (!line.trim()) continue;
+      const record = this.parseLogRecord(line);
+      if (!record) continue;
+
+      if (typeof record.$rewindTo === "string") {
+        this.rewindMessages(messages, record.$rewindTo);
+      } else if (typeof record.id === "string") {
+        messages.set(record.id, record);
+      } else if (isRecord(record.$set)) {
+        if (Array.isArray(record.$set.messages)) {
+          messages.clear();
+          upsertAll(record.$set.messages);
+        }
+        metadata = { ...metadata, ...record.$set };
+      } else if (typeof record.sessionId === "string" && typeof record.projectHash === "string") {
+        metadata = { ...metadata, ...record };
+        upsertAll(record.messages);
+      }
+    }
+
+    if (typeof metadata.sessionId !== "string") return null;
+    return { ...(metadata as GeminiSessionFile), messages: Array.from(messages.values()) };
+  }
+
+  private rewindMessages(messages: Map<string, GeminiMessageEntry>, messageId: string): void {
+    if (!messages.has(messageId)) {
+      messages.clear();
+      return;
+    }
+    let found = false;
+    for (const id of Array.from(messages.keys())) {
+      if (id === messageId) found = true;
+      if (found) messages.delete(id);
+    }
+  }
+
+  private parseLogRecord(line: string): Record<string, unknown> | null {
+    try {
+      const record: unknown = JSON.parse(line);
+      return isRecord(record) ? record : null;
+    } catch {
+      return null;
+    }
+  }
+
   private parseSessionJson(content: string): GeminiSessionFile | null {
     try {
       return JSON.parse(content) as GeminiSessionFile;
@@ -211,7 +337,7 @@ export class GeminiSessionParser {
       const entry = messages[i];
       if (entry?.type !== "user") continue;
       const text = this.messageText(entry).trim();
-      if (text) return this.truncate(text, 120);
+      if (text) return truncate(text, SUMMARY_MAX_LENGTH);
     }
 
     return "Gemini CLI session active";
@@ -257,15 +383,13 @@ export class GeminiSessionParser {
     }
     return "";
   }
+}
 
-  private parseTimestamp(value?: string): Date | null {
-    if (!value) return null;
-    const timestamp = new Date(value);
-    return Number.isNaN(timestamp.getTime()) ? null : timestamp;
-  }
+/** Gemini CLI 0.46+ writes sessions as append-only `.jsonl` logs. */
+export function isSessionLogPath(filePath: string): boolean {
+  return filePath.endsWith(SESSION_LOG_EXTENSION);
+}
 
-  private truncate(value: string, maxLength: number): string {
-    if (value.length <= maxLength) return value;
-    return `${value.slice(0, maxLength - 3)}...`;
-  }
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
 }

package/src/harnesses/gemini/fileSignature.ts

@@ -0,0 +1,10 @@
+import type * as fs from "fs";
+
+/**
+ * Identity of a file's current contents derived from `stat` alone:
+ * inode, size and mtime. Used to reuse metadata and parse results across
+ * refreshes without re-reading unchanged Gemini chat files.
+ */
+export function fileSignature(stat: fs.Stats): string {
+  return `${stat.ino}:${stat.size}:${stat.mtimeMs}`;
+}