@phnx-labs/agents-cli 1.20.74 → 1.20.77

package/dist/lib/session/discover.js

@@ -14,20 +14,23 @@ import * as readline from 'readline';
 import { execFile } from 'child_process';
 import { promisify } from 'util';
 import Database from '../sqlite.js';
-import { getAgentsDir, getHistoryDir, getRunsDir } from '../state.js';
+import { getAgentsDir, getUserAgentsDir, getHistoryDir, getRunsDir } from '../state.js';
+import { shortCodexHome } from '../codex-home.js';
 const execFileAsync = promisify(execFile);
 import { AGENTS, agentConfigDirName, getCliVersion } from '../agents.js';
-import { walkForFiles } from '../fs-walk.js';
+import { walkForFilesWithStat } from '../fs-walk.js';
 import { getConfigSymlinkVersion } from '../shims.js';
 import { SESSION_AGENTS } from './types.js';
+import { deriveShortId } from './short-id.js';
 import { extractSessionTopic } from './prompt.js';
 import { parseAntigravity } from './parse.js';
-import { extractPrUrl, detectWorktree, detectTicket, isPrCreateCommand, detectSpawnedTeam, isTicketCreateTool, extractCreatedTicket } from './state.js';
+import { extractPrUrl, detectWorktree, detectTicket, isPrCreateCommand, detectSpawnedTeam, isTicketCreateTool, extractCreatedTicket, extractRecentDirectoriesTouched, extractTodoProgressFromEvents } from './state.js';
 import { costOfUsage } from '../pricing/index.js';
 import { machineId } from './sync/config.js';
 import { mapBounded } from '../concurrency.js';
-import { getDB, getScanStampByPath, getScanStampsForPaths, recordScans, syncLabels, seedLabelsFromNames, syncTopics, upsertSessionsBatch, querySessions, countSessions, ftsSearch, tryClaimScan, releaseScan, } from './db.js';
+import { getDB, getScanStampByPath, getScanStampsForPaths, getParserStatesForPaths, getDirLedgerForPaths, recordDirScans, recordScans, syncLabels, seedLabelsFromNames, syncTopics, upsertSessionsBatch, querySessions, countSessions, ftsSearch, tryClaimScan, releaseScan, cacheLinearProject, } from './db.js';
 import { buildRunNameMap } from './run-names.js';
+import { resolveLinearApiKey } from '../auto-dispatch-linear.js';
 const HOME = os.homedir();
 // Versions can live under either repo: the user repo (current canonical
 // location, ~/.agents/.history/versions/) or the system repo (legacy / npm-shipped,
@@ -41,6 +44,26 @@ const HERMES_SESSIONS_DIR = path.join(HOME, '.hermes', 'sessions');
 /** How long OpenClaw channel/cron snapshots stay valid before we re-shell-out. */
 const OPENCLAW_TTL_MS = 60_000;
 const ACTIVE_APPEND_RESCAN_DEBOUNCE_MS = 5_000;
+/**
+ * How recently a file must have been scanned to be treated as "hot" — a
+ * candidate for an in-place append even when its parent dir's mtime hasn't
+ * moved. A dir-ledger match lets us skip the per-file stat of everything in a
+ * leaf dir EXCEPT its hot set; a file is hot if it lives under the agent's live
+ * `~/.<agent>` root (the only tree an agent appends to live) or was scanned
+ * within this window. 10 minutes comfortably covers a session that paused
+ * between `agents sessions` calls but is still being written to.
+ */
+const HOT_FILE_WINDOW_MS = 600_000;
+/**
+ * Kill-switch: set `AGENTS_SESSIONS_NO_DIR_LEDGER=1` to force the old full-walk
+ * path (readdir + per-file stat every dir, every run — the pre-A-2 behavior),
+ * skipping the dir_ledger short-circuit entirely. One env var reverts a field
+ * regression to today's behavior.
+ */
+function dirLedgerDisabled() {
+    const v = process.env.AGENTS_SESSIONS_NO_DIR_LEDGER;
+    return v === '1' || v === 'true';
+}
 let cachedOpenClawWorkspaces = null;
 const cachedAgentVersions = new Map();
 /**
@@ -77,9 +100,97 @@ export async function discoverSessions(options) {
         }
     }
     const sessions = querySessions(buildQueryOptions(options, agents, { includeLimit: true }));
+    await resolveLinearProjects(sessions);
     for (const s of sessions)
         s.machine = machineForSessionFile(s.filePath, s.agent);
-    return sessions;
+    return scopeToManaged(sessions, agents, options);
+}
+const linearProjectCache = new Map();
+async function resolveLinearProjects(sessions) {
+    const apiKey = resolveLinearApiKey();
+    if (!apiKey)
+        return;
+    await Promise.all(sessions.map(async (session) => {
+        if (!session.ticketId || session.linearProject)
+            return;
+        let project = linearProjectCache.get(session.ticketId);
+        if (project === undefined) {
+            try {
+                const response = await fetch('https://api.linear.app/graphql', {
+                    method: 'POST',
+                    signal: AbortSignal.timeout(3_000),
+                    headers: { Authorization: apiKey, 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        query: `query($id:String!){ issue(id:$id){ project{ name url } } }`,
+                        variables: { id: session.ticketId },
+                    }),
+                });
+                if (!response.ok)
+                    throw new Error(String(response.status));
+                const body = await response.json();
+                const node = body.data?.issue?.project;
+                project = node?.name && node?.url ? { name: node.name, url: node.url } : null;
+            }
+            catch {
+                project = null;
+            }
+            linearProjectCache.set(session.ticketId, project);
+        }
+        if (!project)
+            return;
+        session.linearProject = project.name;
+        session.linearProjectUrl = project.url;
+        cacheLinearProject(session.id, project.name, project.url);
+    }));
+}
+/**
+ * Drop unmanaged rows for agents that HAVE managed versions.
+ *
+ * Scoping happens here, at query time, rather than by narrowing the scan: the index
+ * stays complete, so `--unmanaged` needs no re-scan and every other consumer of the
+ * DB (watchdog, the Factory watcher, `--roots`) is unaffected.
+ *
+ * An agent with no managed versions is left alone entirely — someone who has never
+ * run `agents add` sees exactly what they saw before.
+ */
+function scopeToManaged(sessions, agents, options) {
+    if (options?.includeUnmanaged)
+        return sessions;
+    if (!anyManagedVersions())
+        return sessions;
+    const kept = sessions.filter((s) => isManagedSessionFile(s.filePath));
+    const hidden = sessions.length - kept.length;
+    if (hidden > 0)
+        options?.onHiddenUnmanaged?.(hidden);
+    return kept;
+}
+/**
+ * True once agents-cli manages ANY agent version. Until then it manages nothing, so
+ * scoping to "managed only" would leave the listing empty for a user who has never
+ * run `agents add` — the browser is most of the tool's value before you install
+ * anything through it.
+ */
+function anyManagedVersions() {
+    for (const root of VERSIONS_ROOTS) {
+        const base = path.join(root, 'versions');
+        let agentDirs;
+        try {
+            agentDirs = fs.readdirSync(base, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const a of agentDirs) {
+            if (!a.isDirectory())
+                continue;
+            try {
+                if (fs.readdirSync(path.join(base, a.name), { withFileTypes: true }).some((e) => e.isDirectory()))
+                    return true;
+            }
+            catch { /* unreadable */ }
+        }
+    }
+    return false;
 }
 /**
  * How many agents' dotfile dirs we scan at once, and the minimum spacing between
@@ -108,6 +219,7 @@ function dispatchAgentScan(agent, onProgress) {
         case 'hermes': return scanHermesIncremental(onProgress);
         case 'kimi': return scanKimiIncremental(onProgress);
         case 'droid': return scanDroidIncremental(onProgress);
+        case 'grok': return scanGrokIncremental(onProgress);
         default: return Promise.resolve();
     }
 }
@@ -119,6 +231,45 @@ let _localMachineId;
  * when the path sits under the agent's backups root, the first segment below it
  * is the origin machine id; otherwise it's the local machine.
  */
+/**
+ * True when this transcript belongs to a version agents-cli manages — i.e. it lives
+ * under a version home (or a backup mirror of one) rather than in the user's own
+ * `~/.<agent>`.
+ *
+ * `agents sessions` scans both, which is right for indexing: the DB stays a complete
+ * picture and `--unmanaged` can surface everything without a re-scan. But listing
+ * *by default* is a different question. Once you have managed versions, an unmanaged
+ * install's history is not really agents-cli's to show — most visibly after
+ * `agents add --isolated`, where the whole point was to keep the two apart.
+ */
+export function isManagedSessionFile(filePath) {
+    // Synthetic rows (OpenClaw workspace sessions, cloud/remote entries) have no local
+    // transcript to classify. They are produced BY agents-cli rather than read out of
+    // someone's dotfile dir, so scoping must not silently swallow them.
+    if (!filePath || !path.isAbsolute(filePath))
+        return true;
+    const roots = [
+        ...VERSIONS_ROOTS.map((root) => path.join(root, 'versions')),
+        path.join(getHistoryDir(), 'backups'),
+        // Codex's managed home is not always under versions/. On macOS the versioned path
+        // overflows SUN_LEN for codex's control socket, so the shim relocates it to
+        // `<agentsUserDir>/.codex-homes/<version>/` (lib/codex-home.ts).
+        path.join(getUserAgentsDir(), '.codex-homes'),
+        // Routine archives are agents-cli's OWN run output — managed by definition.
+        getRunsDir(),
+    ];
+    // Compare realpaths as well as the literal roots. A transcript's stored path is
+    // resolved, so on macOS (`/var` -> `/private/var`) a temp-dir HOME yields
+    // `/private/var/...` for the file and `/var/...` for the root, and a plain prefix
+    // test silently classifies every managed session as the user's own.
+    const real = safeRealpathSync(filePath) || filePath;
+    return roots.some((root) => {
+        if (filePath.startsWith(root + path.sep))
+            return true;
+        const realRoot = safeRealpathSync(root);
+        return !!realRoot && real.startsWith(realRoot + path.sep);
+    });
+}
 export function machineForSessionFile(filePath, agent) {
     const base = path.join(getHistoryDir(), 'backups', agent) + path.sep;
     if (filePath.startsWith(base)) {
@@ -168,12 +319,74 @@ function buildQueryOptions(options, agents, opts) {
         sortBy: options?.sortBy,
     };
 }
-/** Resolve and canonicalize a working directory path (follows symlinks). */
+/**
+ * Canonicalize a working directory path (follows symlinks when it is local).
+ *
+ * Most callers pass a cwd RECORDED in a transcript, which may name a directory
+ * on another machine — a POSIX path read on a Windows host, say. `path.resolve()`
+ * rebases such a path onto the current drive (`/Users/me` -> `D:\Users\me`),
+ * inventing a location that never existed. So an absolute path is normalized but
+ * never rebased; only a genuinely relative one resolves against the process cwd.
+ *
+ * `path.normalize()` still runs on every branch: it collapses `.`, `..`, and
+ * duplicate separators, and folds separators on Windows. Both sides of the cwd
+ * filter in `db.ts` (`cwd = ?` and `cwd LIKE ? || path.sep || '%'`) come through
+ * here, so dropping that would leave a trailing slash or a `..` segment in one
+ * side and match nothing.
+ *
+ * Realpath is attempted only for a path that is absolute in THIS platform's
+ * terms. A POSIX-rooted path on Windows is drive-relative to `fs.realpathSync`,
+ * which would resolve `/Users/me` against the current drive and reintroduce the
+ * graft for any path that happens to exist locally.
+ */
+export function _normalizeCwdForTest(cwd) {
+    return normalizeCwd(cwd);
+}
 function normalizeCwd(cwd) {
     if (!cwd)
         return '';
-    const resolved = path.resolve(cwd);
-    return safeRealpathSync(resolved) || resolved;
+    // A POSIX-rooted path on Windows belongs to another machine. Normalize it with
+    // POSIX rules so its separators survive — path.win32.normalize would fold them
+    // to backslashes, mangling the very path we are trying to preserve — and never
+    // realpath it, since fs.realpathSync would resolve it against the current drive.
+    if (process.platform === 'win32' && /^\//.test(cwd) && !/^[a-zA-Z]:/.test(cwd)) {
+        return stripTrailingSep(path.posix.normalize(cwd));
+    }
+    const normalized = path.isAbsolute(cwd) ? stripTrailingSep(path.normalize(cwd)) : path.resolve(cwd);
+    return safeRealpathSync(normalized) || normalized;
+}
+/** Drop a trailing separator so `cwd = ?` and the `cwd LIKE ? + sep` subdir
+ *  wildcard agree; a root path (`/`, `C:\`) keeps its separator. */
+function stripTrailingSep(p) {
+    const stripped = p.replace(/[\\/]+$/, '');
+    return stripped.length > 0 && !/^[a-zA-Z]:$/.test(stripped) ? stripped : p;
+}
+/** Canonical 8-4-4-4-12 hex UUID (covers both v4 and the v7 ids newer harnesses mint). */
+const UUID_36 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/** kimi and rush mint `session_` + a UUID. */
+const SESSION_UUID_PREFIX = /^session_/;
+/** opencode mints `ses_` + a 26-char ULID — NOT a UUID, so it needs its own shape. */
+const SES_ULID = /^ses_[0-9a-z]{26}$/;
+/**
+ * Whether a query is a session id in full, rather than an id prefix or a search
+ * phrase.
+ *
+ * Callers use this to decide that an id lookup is the ONLY admissible
+ * interpretation: a complete id is unique, so when it misses there is nothing
+ * left to widen to. Without the check, `sessions <uuid>` fell through to the
+ * FTS content search, which tokenizes the UUID and matches every transcript that
+ * merely mentions it — surfacing unrelated sessions as if they were id matches.
+ *
+ * The accepted shapes are the ones the index actually holds, measured over a
+ * 12,507-row index: a bare UUID (11,116 rows), `session_` + UUID (1,360 — kimi
+ * and rush), and `ses_` + ULID (15 — opencode). Deliberately NOT covered, so a
+ * miss keeps today's search behavior rather than gaining a wrong error: routine
+ * run ids (ISO timestamps, matched via `routineRunId` below) and cloud execution
+ * ids, whose charset is too permissive to distinguish from a search phrase.
+ */
+export function isCompleteSessionId(query) {
+    const q = query.trim().toLowerCase();
+    return UUID_36.test(q.replace(SESSION_UUID_PREFIX, '')) || SES_ULID.test(q);
 }
 /**
  * Resolve a session by full or short ID. Accepts a pre-loaded session list
@@ -230,26 +443,39 @@ export function searchContentIndex(sessions, query) {
  * growing transcript over and over. The cached row is good enough for a few
  * seconds; once writes settle or the debounce expires, the file is parsed once.
  */
-function filterChangedFiles(filePaths) {
-    const ledger = getScanStampsForPaths(filePaths);
-    const out = [];
-    const now = Date.now();
+export function filterChangedFiles(filePaths) {
+    const entries = [];
     for (const filePath of filePaths) {
         const stat = safeStatSync(filePath);
         if (!stat)
             continue;
+        entries.push({ filePath, fileMtimeMs: stat.mtimeMs, fileSize: stat.size });
+    }
+    return filterChangedEntries(entries);
+}
+/**
+ * Ledger-compare pre-stat'd entries (from the walk's own stat) without a second
+ * stat. Same debounce and change-detection as filterChangedFiles; the raw
+ * mtime is floored here so warm files match the ledger exactly as the stat path
+ * does (Math.floor(stat.mtimeMs)).
+ */
+export function filterChangedEntries(entries) {
+    const ledger = getScanStampsForPaths(entries.map(e => e.filePath));
+    const out = [];
+    const now = Date.now();
+    for (const entry of entries) {
         const scan = {
-            fileMtimeMs: Math.floor(stat.mtimeMs),
-            fileSize: stat.size,
+            fileMtimeMs: Math.floor(entry.fileMtimeMs),
+            fileSize: entry.fileSize,
         };
-        const prev = ledger.get(filePath);
+        const prev = ledger.get(entry.filePath);
         if (prev && prev.fileMtimeMs === scan.fileMtimeMs && prev.fileSize === scan.fileSize) {
             continue;
         }
         if (prev && shouldDeferRecentAppend(prev, scan, now)) {
             continue;
         }
-        out.push({ filePath, scan });
+        out.push({ filePath: entry.filePath, scan });
     }
     return out;
 }
@@ -262,6 +488,96 @@ export function shouldDeferRecentAppend(prev, current, nowMs, debounceMs = ACTIV
         return false;
     return nowMs - prev.scannedAt < debounceMs;
 }
+/**
+ * Walk a set of leaf transcript directories and return the files that changed,
+ * skipping the per-file `stat` of directories whose (mtime, entry_count) matches
+ * the dir_ledger.
+ *
+ * Per leaf dir:
+ *   - `stat` the dir once and `readdir` it (one cheap syscall) to get the entry
+ *     count and the file list.
+ *   - If the dir matches the dir_ledger (floored mtime AND entry_count), no file
+ *     was created / deleted / renamed since we last walked it. We then stat ONLY
+ *     the hot files (live-root files, or files scanned within HOT_FILE_WINDOW_MS)
+ *     and run just those through the ledger compare — so an in-place append to a
+ *     still-live session is still caught, while immutable backup/version dirs
+ *     collapse to a single dir stat and zero per-file stats.
+ *   - Else (changed dir, or no ledger row) we stat every file (today's full
+ *     walk) and record the fresh dir stamp so the next run can short-circuit.
+ *
+ * The kill-switch (`AGENTS_SESSIONS_NO_DIR_LEDGER=1`) forces the full-walk branch
+ * for every dir and never consults or records the dir_ledger.
+ */
+export function collectChangedFilesInLeafDirs(leafDirs, ext) {
+    const disabled = dirLedgerDisabled();
+    const dirStamps = disabled ? new Map() : getDirLedgerForPaths(leafDirs.map(d => d.dirPath));
+    const now = Date.now();
+    // Files whose per-file stat we still need to ledger-compare this run.
+    const toCompare = [];
+    const allFiles = [];
+    const dirScansToRecord = [];
+    for (const { dirPath, isLiveRoot } of leafDirs) {
+        const dirStat = safeStatSync(dirPath);
+        if (!dirStat?.isDirectory())
+            continue;
+        let names;
+        try {
+            names = fs.readdirSync(dirPath).filter(f => f.endsWith(ext));
+        }
+        catch {
+            continue;
+        }
+        const files = names.map(f => path.join(dirPath, f));
+        for (const filePath of files)
+            allFiles.push({ filePath, isLiveRoot });
+        const dirMtimeMs = Math.floor(dirStat.mtimeMs);
+        const entryCount = names.length;
+        const prevDir = dirStamps.get(dirPath);
+        const dirUnchanged = !disabled && prevDir !== undefined && prevDir.dirMtimeMs === dirMtimeMs && prevDir.entryCount === entryCount;
+        if (dirUnchanged) {
+            // Contents did not change (no create/delete/rename). Stat only the hot
+            // files; the rest are served from the DB with no stat. An immutable backup
+            // dir (not a live root, nothing recently scanned) does zero per-file stats.
+            //
+            // A live-root dir treats every file as hot — that is the tree an agent
+            // appends to live, and an append does NOT bump the parent-dir mtime, so
+            // without this a growing session would be silently skipped. A non-live
+            // file is hot only if it was scanned within HOT_FILE_WINDOW_MS (bulk ledger
+            // lookup), covering a session under a version/backup path that is somehow
+            // still being written.
+            const stamps = isLiveRoot ? null : getScanStampsForPaths(files);
+            for (const filePath of files) {
+                let hot = isLiveRoot;
+                if (!hot && stamps) {
+                    const s = stamps.get(filePath);
+                    hot = s?.scannedAt !== undefined && now - s.scannedAt <= HOT_FILE_WINDOW_MS;
+                }
+                if (!hot)
+                    continue;
+                const stat = safeStatSync(filePath);
+                if (!stat)
+                    continue;
+                toCompare.push({ filePath, fileMtimeMs: stat.mtimeMs, fileSize: stat.size });
+            }
+            // No dir stamp to record — nothing about the dir changed.
+        }
+        else {
+            // Changed dir (or cold ledger): full per-file stat, exactly as today.
+            for (const filePath of files) {
+                const stat = safeStatSync(filePath);
+                if (!stat)
+                    continue;
+                toCompare.push({ filePath, fileMtimeMs: stat.mtimeMs, fileSize: stat.size });
+            }
+            if (!disabled)
+                dirScansToRecord.push({ dirPath, dirMtimeMs, entryCount });
+        }
+    }
+    const changed = filterChangedEntries(toCompare);
+    if (dirScansToRecord.length > 0)
+        recordDirScans(dirScansToRecord);
+    return { changed, allFiles };
+}
 // ---------------------------------------------------------------------------
 // Multi-version directory scanning
 // ---------------------------------------------------------------------------
@@ -294,6 +610,17 @@ export function getAgentSessionDirs(agent, subdir) {
         try {
             for (const version of fs.readdirSync(versionsBase)) {
                 addDir(path.join(versionsBase, version, 'home', configDirName, subdir));
+                // Codex's managed home is not always where the version layout says. On macOS
+                // the versioned path overflows SUN_LEN (104 bytes) for codex's control
+                // socket, so the shim relocates the home to
+                // `<agentsUserDir>/.codex-homes/<version>/.codex` (lib/codex-home.ts). Every
+                // transcript an isolated codex writes lands there, and nothing scanned it —
+                // `agents sessions --roots` listed only the user's own ~/.codex, so a managed
+                // copy's own history was invisible. addDir skips what does not exist, so this
+                // is inert on Linux and for versions that never needed relocating.
+                if (agent === 'codex') {
+                    addDir(path.join(shortCodexHome(getUserAgentsDir(), version), subdir));
+                }
             }
         }
         catch { /* dir unreadable */ }
@@ -324,6 +651,7 @@ const SESSION_ROOT_SPECS = [
     { agent: 'antigravity', subdir: 'conversations' },
     { agent: 'droid', subdir: 'sessions' },
     { agent: 'kimi', subdir: 'sessions' },
+    { agent: 'grok', subdir: 'sessions' },
 ];
 function sessionRootSubdir(agent) {
     return SESSION_ROOT_SPECS.find((spec) => spec.agent === agent)?.subdir ?? null;
@@ -402,7 +730,14 @@ async function readRoutineArchiveMeta(agent, filePath) {
         return null;
     if (agent === 'claude') {
         const sessionId = path.basename(filePath).replace(/\.jsonl$/, '');
-        const result = await readClaudeMeta(filePath, sessionId);
+        // Routine archives are finalized, immutable transcripts — no live append, so
+        // no continuation to resume. A FULL parse (undefined prior) is correct here;
+        // the returned continuation is unused by this archive path.
+        const stat = safeStatSync(filePath);
+        if (!stat)
+            return null;
+        const scanStamp = { fileMtimeMs: Math.floor(stat.mtimeMs), fileSize: stat.size };
+        const result = await readClaudeMeta(filePath, sessionId, scanStamp, undefined);
         return result ? { ...result, meta: decorateRoutineSession(result.meta, info) } : null;
     }
     if (agent === 'codex') {
@@ -416,12 +751,13 @@ async function scanRoutineArchivesIncremental(agent, onProgress) {
     if (!subdir)
         return;
     const ext = agent === 'gemini' ? '.json' : '.jsonl';
-    const filePaths = [];
+    const prestat = [];
     for (const sessionsDir of getRoutineArchiveSessionDirs(agent, subdir)) {
-        for (const fp of walkForFiles(sessionsDir, ext, 100_000))
-            filePaths.push(fp);
+        for (const f of walkForFilesWithStat(sessionsDir, ext, 100_000)) {
+            prestat.push({ filePath: f.path, fileMtimeMs: f.mtimeMs, fileSize: f.size });
+        }
     }
-    const changed = filterChangedFiles(filePaths);
+    const changed = filterChangedEntries(prestat);
     if (changed.length === 0)
         return;
     onProgress?.({ agent, parsed: 0, total: changed.length });
@@ -533,40 +869,64 @@ export function buildClaudeLabelMap() {
 async function scanClaudeIncremental(onProgress) {
     const account = getClaudeAccount();
     const labelMap = buildClaudeLabelMap();
-    const filePaths = [];
-    const seen = new Set();
-    for (const projectsDir of getAgentSessionDirs('claude', 'projects')) {
+    // Enumerate every leaf project dir across all Claude roots. The FIRST root
+    // returned by getAgentSessionDirs is the agent's live `~/.claude/projects` —
+    // the only tree Claude appends to in place, so its project dirs are live roots
+    // (every file hot). Version-home + backup roots are immutable: their dirs
+    // short-circuit to a single dir stat when unchanged.
+    const roots = getAgentSessionDirs('claude', 'projects');
+    const leafDirs = [];
+    const seenLeaf = new Set();
+    roots.forEach((projectsDir, rootIdx) => {
+        const isLiveRoot = rootIdx === 0;
         let projectDirs;
         try {
             projectDirs = fs.readdirSync(projectsDir);
         }
         catch {
-            continue;
+            return;
         }
         for (const dirName of projectDirs) {
             const dirPath = path.join(projectsDir, dirName);
-            const stat = safeStatSync(dirPath);
-            if (!stat?.isDirectory())
-                continue;
-            let files;
-            try {
-                files = fs.readdirSync(dirPath).filter(f => f.endsWith('.jsonl'));
-            }
-            catch {
+            const key = safeRealpathSync(dirPath) || dirPath;
+            if (seenLeaf.has(key))
                 continue;
-            }
-            for (const file of files) {
-                const sessionId = file.replace('.jsonl', '');
-                if (seen.has(sessionId))
-                    continue;
-                seen.add(sessionId);
-                filePaths.push(path.join(dirPath, file));
-            }
+            seenLeaf.add(key);
+            leafDirs.push({ dirPath, isLiveRoot });
         }
-    }
-    const changed = filterChangedFiles(filePaths);
+    });
+    const { changed: changedAll, allFiles } = collectChangedFilesInLeafDirs(leafDirs, '.jsonl');
+    // Restore the pre-A-2 cross-root precedence: a session id present in multiple
+    // roots is ALWAYS served from its live path, never a frozen backup/version
+    // copy. Pre-A-2, dedup happened at enumeration time via a live-first `seen`
+    // set, so a non-live copy was never even stat'd when a live copy existed. This
+    // PR must not regress that to "whichever copy changed this run wins" — a cold
+    // (unchanged) live copy paired with a freshly-written backup snapshot would
+    // otherwise flip the row's file_path to the backup path.
+    //
+    // allFiles is every transcript file across all roots in live-first order, so
+    // the FIRST occurrence of each session id is its live (or highest-precedence)
+    // path — the durable winner, independent of which copy was flagged changed.
+    const sessionIdOf = (fp) => path.basename(fp).replace('.jsonl', '');
+    const winnerBySession = new Map();
+    for (const { filePath } of allFiles) {
+        const id = sessionIdOf(filePath);
+        if (!winnerBySession.has(id))
+            winnerBySession.set(id, filePath);
+    }
+    // Keep a changed entry only if it is its session's winner. A changed non-live
+    // copy is dropped whenever a live copy exists anywhere; the winning path is
+    // parsed only when it itself changed (a cold winner needs no re-parse — its DB
+    // row already points at the live path).
+    const changed = changedAll.filter(e => winnerBySession.get(sessionIdOf(e.filePath)) === e.filePath);
     if (changed.length > 0) {
         onProgress?.({ agent: 'claude', parsed: 0, total: changed.length });
+        // Bulk-fetch each changed file's prior resumable continuation. A file with a
+        // usable prior state + growth goes incremental (re-parse only the appended
+        // bytes); everything else does a FULL from-offset-0 parse. The decision + the
+        // parse both live in scanClaudeSessionResumable so full and incremental share
+        // one reducer and produce identical rows.
+        const priorStates = getParserStatesForPaths(changed.map(c => c.filePath));
         const entries = [];
         const touched = [];
         let parsed = 0;
@@ -574,9 +934,16 @@ async function scanClaudeIncremental(onProgress) {
             try {
                 const sessionId = path.basename(filePath).replace('.jsonl', '');
                 const label = labelMap.get(sessionId) ?? undefined;
-                const result = await readClaudeMeta(filePath, sessionId, account, label);
+                const priorRow = priorStates.get(filePath);
+                const result = await readClaudeMeta(filePath, sessionId, scan, priorRow, account, label);
                 if (result) {
-                    entries.push({ meta: result.meta, content: result.content, scan });
+                    entries.push({
+                        meta: result.meta,
+                        content: result.content,
+                        scan,
+                        parserState: result.parserState,
+                        contentText: result.contentText,
+                    });
                 }
                 else {
                     touched.push({ filePath, scan });
@@ -596,16 +963,27 @@ async function scanClaudeIncremental(onProgress) {
     if (labelMap.size > 0)
         syncLabels(labelMap);
 }
-/** Stream-parse a single Claude JSONL file to extract session metadata. */
-async function readClaudeMeta(filePath, sessionId, account, label) {
-    const scan = await scanClaudeSession(filePath);
+/**
+ * Stream-parse a single Claude JSONL file to extract session metadata, resuming
+ * from the persisted continuation when the file merely grew (see
+ * {@link scanClaudeSessionResumable}). Returns the row's meta + FTS content plus
+ * the serialized continuation (parser_state + content_text) to persist for the
+ * next scan.
+ */
+async function readClaudeMeta(filePath, sessionId, scanStamp, priorRow, account, label) {
+    const prior = parsePriorClaudeState(priorRow);
+    const { scan, newState, mode } = await scanClaudeSessionResumable(filePath, prior, scanStamp.fileMtimeMs, scanStamp.fileSize, priorRow?.fileMtimeMs);
+    if (mode === 'incremental')
+        claudeIncrementalScanCount++;
+    else
+        claudeFullScanCount++;
     const isTeamOrigin = scan.entrypoint === 'sdk-cli';
     let meta;
     if (scan.timestamp) {
         const cwd = normalizeCwd(scan.cwd || '');
         meta = {
             id: sessionId,
-            shortId: sessionId.slice(0, 8),
+            shortId: deriveShortId(sessionId),
             agent: 'claude',
             timestamp: scan.timestamp,
             lastActivity: scan.lastActivity,
@@ -630,13 +1008,15 @@ async function readClaudeMeta(filePath, sessionId, account, label) {
             createdTickets: scan.createdTickets,
             spawnedTeam: scan.spawnedTeam,
             plan: scan.plan,
+            todos: scan.todos,
+            recentDirectoriesTouched: scan.recentDirectoriesTouched,
         };
     }
     else {
         const stat = safeStatSync(filePath);
         meta = {
             id: sessionId,
-            shortId: sessionId.slice(0, 8),
+            shortId: deriveShortId(sessionId),
             agent: 'claude',
             timestamp: stat ? stat.mtime.toISOString() : new Date().toISOString(),
             lastActivity: scan.lastActivity,
@@ -657,9 +1037,19 @@ async function readClaudeMeta(filePath, sessionId, account, label) {
             createdTickets: scan.createdTickets,
             spawnedTeam: scan.spawnedTeam,
             plan: scan.plan,
+            todos: scan.todos,
+            recentDirectoriesTouched: scan.recentDirectoriesTouched,
         };
     }
-    return { meta, content: scan.contentText || '' };
+    return {
+        meta,
+        content: scan.contentText || '',
+        // Persist the continuation so the next scan of this file can resume from the
+        // offset instead of a full reparse. content_text is the same accumulated user
+        // doc, cached so the resume can hydrate userTexts without re-reading the file.
+        parserState: JSON.stringify(newState),
+        contentText: newState.contentText,
+    };
 }
 // ---------------------------------------------------------------------------
 // Codex account info
@@ -745,37 +1135,58 @@ async function scanCodexIncremental(onProgress) {
     // readCodexMeta when a changed session actually needs it — never eagerly here,
     // so a no-op scan (changed.length === 0) never touches the credential file.
     const currentVersion = await getCurrentAgentVersion('codex');
-    const filePaths = [];
+    const prestat = [];
     for (const sessionsDir of getAgentSessionDirs('codex', 'sessions')) {
-        // High limit: we only stat files here, parsing is gated by ledger match.
-        for (const fp of walkForFiles(sessionsDir, '.jsonl', 100_000)) {
-            filePaths.push(fp);
+        // High limit: the walk stats each file once here; parsing is gated by the
+        // ledger match below, which reuses that stat instead of re-stat'ing.
+        for (const f of walkForFilesWithStat(sessionsDir, '.jsonl', 100_000)) {
+            prestat.push({ filePath: f.path, fileMtimeMs: f.mtimeMs, fileSize: f.size });
         }
     }
-    const changed = filterChangedFiles(filePaths);
+    const changed = filterChangedEntries(prestat);
     // Codex keeps human-readable titles (`thread_name`) in `session_index.jsonl`,
-    // which updates independently of the rollout files — apply them by id on every
-    // scan so a title that lands after a session was first indexed still surfaces.
+    // which updates independently of the rollout files. Stat each index against the
+    // ledger *without reading it*; only read + re-apply titles when the index (or a
+    // rollout) actually changed. On a fully unchanged scan this collapses to a
+    // couple of stat() calls instead of a full read + a `syncTopics` DB pass.
+    const titleIndex = diffCodexTitleIndexes();
+    if (changed.length === 0 && !titleIndex.changed)
+        return;
     const titles = readCodexThreadNames();
     if (changed.length === 0) {
+        // No rollouts changed, but the title index did — apply the new titles.
         syncTopics(titles);
+        recordScans(titleIndex.stamps);
         return;
     }
     onProgress?.({ agent: 'codex', parsed: 0, total: changed.length });
+    // Bulk-fetch each changed rollout's prior resumable continuation. A file with
+    // a usable prior state + growth goes incremental (re-parse only the appended
+    // bytes); everything else does a FULL from-offset-0 parse. The decision + the
+    // parse both live in scanCodexSessionResumable so full and incremental share
+    // one reducer and produce identical rows.
+    const priorStates = getParserStatesForPaths(changed.map(c => c.filePath));
     const entries = [];
     const touched = [];
     const seen = new Set();
     let parsed = 0;
     for (const { filePath, scan } of changed) {
         try {
-            const result = await readCodexMeta(filePath, getCodexAccount, currentVersion);
+            const priorRow = priorStates.get(filePath);
+            const result = await readCodexMeta(filePath, getCodexAccount, currentVersion, scan, priorRow);
             if (result && !seen.has(result.meta.id)) {
                 seen.add(result.meta.id);
                 // Prefer the Codex-generated title over the first-prompt fallback.
                 const title = titles.get(result.meta.id);
                 if (title)
                     result.meta.topic = title;
-                entries.push({ meta: result.meta, content: result.content, scan });
+                entries.push({
+                    meta: result.meta,
+                    content: result.content,
+                    scan,
+                    parserState: result.parserState,
+                    contentText: result.contentText,
+                });
             }
             else {
                 touched.push({ filePath, scan });
@@ -789,9 +1200,12 @@ async function scanCodexIncremental(onProgress) {
     }
     upsertSessionsBatch(entries);
     recordScans(touched);
-    // Catch sessions whose rollout file was unchanged but gained a title since the
-    // last scan (the index changed, the transcript did not).
-    syncTopics(titles);
+    // Only when the title index changed can an *unchanged* rollout have gained a
+    // title since the last scan; the inline titles applied above already cover
+    // every changed session, so skip the extra sync when the index is untouched.
+    if (titleIndex.changed)
+        syncTopics(titles);
+    recordScans(titleIndex.stamps);
 }
 /** Parse the lines of a Codex `session_index.jsonl` into a session id -> title map. */
 export function parseCodexThreadNameIndex(raw) {
@@ -812,6 +1226,32 @@ export function parseCodexThreadNameIndex(raw) {
     }
     return titles;
 }
+/**
+ * Stat every Codex `session_index.jsonl` and diff it against the scan ledger
+ * *without reading it*. Returns the fresh stamps (persisted only after a
+ * successful title sync) and whether any index changed since the last scan — the
+ * signal that lets a no-op scan skip the file read + `syncTopics` entirely.
+ *
+ * The index path is a sibling of `sessions/` (never inside it), so it is never
+ * walked as a rollout and its ledger row can't collide with a transcript's.
+ */
+function diffCodexTitleIndexes() {
+    const stamps = [];
+    let changed = false;
+    for (const sessionsDir of getAgentSessionDirs('codex', 'sessions')) {
+        const indexPath = path.join(path.dirname(sessionsDir), 'session_index.jsonl');
+        const stat = safeStatSync(indexPath);
+        if (!stat)
+            continue; // no index in this home
+        const scan = { fileMtimeMs: Math.floor(stat.mtimeMs), fileSize: stat.size };
+        const prev = getScanStampByPath(indexPath);
+        if (!prev || prev.fileMtimeMs !== scan.fileMtimeMs || prev.fileSize !== scan.fileSize) {
+            changed = true;
+        }
+        stamps.push({ filePath: indexPath, scan });
+    }
+    return { stamps, changed };
+}
 /**
  * Read Codex session titles across every Codex home (live + versioned). The
  * `session_index.jsonl` file sits beside each `sessions/` rollout tree.
@@ -839,15 +1279,36 @@ function readCodexThreadNames() {
  * performs is deferred until we know this file is a real session worth building
  * metadata for, and only then — never during the file walk / stat phase.
  */
-export async function readCodexMeta(filePath, resolveAccount, currentVersion) {
-    const scan = await scanCodexSession(filePath);
+export async function readCodexMeta(filePath, resolveAccount, currentVersion, scanStamp, priorRow) {
+    // Resume from the persisted continuation when the file merely grew; otherwise
+    // full-parse from byte 0. Both branches share one reducer, so an append yields
+    // a row identical to a from-scratch reparse. When no stamp is supplied (a
+    // caller outside the live scan path), fall back to a plain full parse with no
+    // continuation to persist.
+    let scan;
+    let newState;
+    let newOffset = 0;
+    if (scanStamp) {
+        const prior = parsePriorCodexState(priorRow);
+        const result = await scanCodexSessionResumable(filePath, prior, scanStamp.fileMtimeMs, scanStamp.fileSize, priorRow?.fileMtimeMs);
+        if (result.mode === 'incremental')
+            codexIncrementalScanCount++;
+        else
+            codexFullScanCount++;
+        scan = result.scan;
+        newState = result.newState;
+        newOffset = result.newOffset;
+    }
+    else {
+        scan = await scanCodexSession(filePath);
+    }
     const sessionId = scan.sessionId || '';
     if (!sessionId)
         return null;
     const cwd = normalizeCwd(scan.cwd || '');
     const meta = {
         id: sessionId,
-        shortId: sessionId.slice(0, 8),
+        shortId: deriveShortId(sessionId),
         agent: 'codex',
         // Codex `session_meta` only carries the start time; use file mtime when
         // it's newer so long-running sessions register as recently active.
@@ -871,8 +1332,18 @@ export async function readCodexMeta(filePath, resolveAccount, currentVersion) {
         ticketId: scan.ticketId,
         createdTickets: scan.createdTickets,
         spawnedTeam: scan.spawnedTeam,
+        todos: scan.todos,
+        recentDirectoriesTouched: scan.recentDirectoriesTouched,
+    };
+    return {
+        meta,
+        content: scan.contentText || '',
+        // Persist the continuation so the next scan of this rollout resumes from the
+        // offset instead of a full reparse; content_text caches the accumulated user
+        // doc for the resume's hydrate. Absent when no stamp was supplied.
+        parserState: newState ? JSON.stringify(newState) : undefined,
+        contentText: newState?.contentText,
     };
-    return { meta, content: scan.contentText || '' };
 }
 /**
  * Codex writes `session_meta` (with the start timestamp) on the first line of a
@@ -901,33 +1372,34 @@ function pickLatestCodexTimestamp(metaTimestamp, filePath) {
 async function scanGeminiIncremental(onProgress) {
     const currentVersion = await getCurrentAgentVersion('gemini');
     const projectMap = buildGeminiProjectMap();
-    const filePaths = [];
-    for (const tmpDir of getAgentSessionDirs('gemini', 'tmp')) {
+    // Each `<tmpDir>/<hashDir>/chats` is a leaf dir of Gemini transcripts. The
+    // FIRST tmp root is the live `~/.gemini/tmp` — its chats dirs are live roots;
+    // version-home + backup roots are immutable and short-circuit when unchanged.
+    const tmpRoots = getAgentSessionDirs('gemini', 'tmp');
+    const leafDirs = [];
+    const seenLeaf = new Set();
+    tmpRoots.forEach((tmpDir, rootIdx) => {
+        const isLiveRoot = rootIdx === 0;
         let hashDirs;
         try {
             hashDirs = fs.readdirSync(tmpDir);
         }
         catch {
-            continue;
+            return;
         }
         for (const hashDir of hashDirs) {
             const chatsDir = path.join(tmpDir, hashDir, 'chats');
             if (!fs.existsSync(chatsDir))
                 continue;
-            let chatFiles;
-            try {
-                chatFiles = fs.readdirSync(chatsDir).filter(f => f.endsWith('.json'));
-            }
-            catch {
+            const key = safeRealpathSync(chatsDir) || chatsDir;
+            if (seenLeaf.has(key))
                 continue;
-            }
-            for (const file of chatFiles) {
-                filePaths.push({ filePath: path.join(chatsDir, file), hashDir });
-            }
+            seenLeaf.add(key);
+            leafDirs.push({ dirPath: chatsDir, isLiveRoot });
         }
-    }
-    const changedPaths = filterChangedFiles(filePaths.map(f => f.filePath));
-    const changedByPath = new Map(changedPaths.map(c => [c.filePath, c.scan]));
+    });
+    const { changed } = collectChangedFilesInLeafDirs(leafDirs, '.json');
+    const changedByPath = new Map(changed.map(c => [c.filePath, c.scan]));
     if (changedByPath.size === 0)
         return;
     onProgress?.({ agent: 'gemini', parsed: 0, total: changedByPath.size });
@@ -935,10 +1407,9 @@ async function scanGeminiIncremental(onProgress) {
     const touched = [];
     const seen = new Set();
     let parsed = 0;
-    for (const { filePath, hashDir } of filePaths) {
-        const scan = changedByPath.get(filePath);
-        if (!scan)
-            continue;
+    for (const { filePath, scan } of changed) {
+        // The hashDir is the directory two levels up: <hashDir>/chats/<file>.json.
+        const hashDir = path.basename(path.dirname(path.dirname(filePath)));
         try {
             const result = readGeminiMeta(filePath, hashDir, projectMap, currentVersion);
             if (result && !seen.has(result.meta.id)) {
@@ -1058,7 +1529,7 @@ function readGeminiMeta(filePath, hashDir, projectMap, currentVersion) {
         : undefined;
     const meta = {
         id: sessionId,
-        shortId: sessionId.slice(0, 8),
+        shortId: deriveShortId(sessionId),
         agent: 'gemini',
         timestamp: startTime || (stat ? stat.mtime.toISOString() : new Date().toISOString()),
         lastActivity: lastTsMs !== undefined ? new Date(lastTsMs).toISOString() : undefined,
@@ -1204,7 +1675,7 @@ function readAntigravityMeta(filePath, currentVersion) {
     const stat = safeStatSync(filePath);
     const meta = {
         id: sessionId,
-        shortId: sessionId.slice(0, 8),
+        shortId: deriveShortId(sessionId),
         agent: 'antigravity',
         timestamp: stat ? stat.mtime.toISOString() : new Date().toISOString(),
         project: normalizedCwd ? path.basename(normalizedCwd) : undefined,
@@ -1332,7 +1803,7 @@ async function scanOpenCodeIncremental() {
             const topic = title || undefined;
             const meta = {
                 id,
-                shortId: id.replace(/^ses_/, '').slice(0, 8),
+                shortId: deriveShortId(id, /^ses_/),
                 agent: 'opencode',
                 timestamp,
                 lastActivity,
@@ -1402,7 +1873,7 @@ async function scanOpenClawIncremental() {
             entries.push({
                 meta: {
                     id: `openclaw-${agentId}`,
-                    shortId: agentId.slice(0, 8),
+                    shortId: deriveShortId(agentId),
                     agent: 'openclaw',
                     timestamp: new Date().toISOString(),
                     project: name,
@@ -1438,7 +1909,7 @@ async function scanOpenClawIncremental() {
             entries.push({
                 meta: {
                     id: `openclaw-cron-${jobId}`,
-                    shortId: jobId.slice(0, 8),
+                    shortId: deriveShortId(jobId),
                     agent: 'openclaw',
                     timestamp: new Date().toISOString(),
                     project: `${jobName} (${agentId || 'unknown'})`,
@@ -1512,7 +1983,7 @@ async function readRushMeta(filePath, sessionId) {
     const stat = safeStatSync(filePath);
     const timestamp = scan.timestamp
         || (stat ? stat.mtime.toISOString() : new Date().toISOString());
-    const shortId = sessionId.replace(/^session_/, '').slice(0, 8);
+    const shortId = deriveShortId(sessionId, /^session_/);
     const meta = {
         id: sessionId,
         shortId,
@@ -1672,7 +2143,7 @@ function readHermesMeta(filePath) {
         : typeof session.session_start === 'string'
             ? session.session_start
             : stat ? stat.mtime.toISOString() : new Date().toISOString();
-    const shortId = sessionId.replace(/^api-/, '').slice(0, 8);
+    const shortId = deriveShortId(sessionId, /^api-/);
     const model = typeof session.model === 'string' ? session.model : undefined;
     const platform = typeof session.platform === 'string' ? session.platform : undefined;
     const meta = {
@@ -1713,14 +2184,15 @@ function extractHermesMessageText(content) {
  */
 async function scanDroidIncremental(onProgress) {
     const currentVersion = await getCurrentAgentVersion('droid');
-    const filePaths = [];
+    const prestat = [];
     for (const sessionsDir of getAgentSessionDirs('droid', 'sessions')) {
-        // High limit: we only stat files here, parsing is gated by ledger match.
-        for (const fp of walkForFiles(sessionsDir, '.jsonl', 100_000)) {
-            filePaths.push(fp);
+        // High limit: the walk stats each file once here; parsing is gated by the
+        // ledger match below, which reuses that stat instead of re-stat'ing.
+        for (const f of walkForFilesWithStat(sessionsDir, '.jsonl', 100_000)) {
+            prestat.push({ filePath: f.path, fileMtimeMs: f.mtimeMs, fileSize: f.size });
         }
     }
-    const changed = filterChangedFiles(filePaths);
+    const changed = filterChangedEntries(prestat);
     if (changed.length === 0)
         return;
     onProgress?.({ agent: 'droid', parsed: 0, total: changed.length });
@@ -1772,7 +2244,7 @@ async function readDroidMeta(filePath, currentVersion) {
     const cwd = normalizeCwd(scan.cwd || '');
     const meta = {
         id: sessionId,
-        shortId: sessionId.slice(0, 8),
+        shortId: deriveShortId(sessionId),
         agent: 'droid',
         timestamp: scan.timestamp || (stat ? stat.mtime.toISOString() : new Date().toISOString()),
         lastActivity: scan.lastActivity,
@@ -1916,46 +2388,254 @@ function extractDroidMessageText(content) {
         .join('\n')
         .trim();
 }
+/** Zero-value accumulator for a fresh (from-byte-0) Claude parse. */
+export function initClaudeParseState() {
+    return {
+        timestamp: undefined,
+        cwd: undefined,
+        gitBranch: undefined,
+        version: undefined,
+        topic: undefined,
+        customTitle: undefined,
+        aiTitle: undefined,
+        entrypoint: undefined,
+        messageCount: 0,
+        tokenCount: 0,
+        outputTokens: 0,
+        sawTokenCount: false,
+        costUsd: 0,
+        sawCost: false,
+        firstTsMs: undefined,
+        lastTsMs: undefined,
+        seenAssistantIds: new Set(),
+        userTexts: [],
+        sawPrCreate: false,
+        prUrl: undefined,
+        prNumber: undefined,
+        createdTickets: new Set(),
+        pendingTicketTools: new Set(),
+        spawnedTeam: undefined,
+        plan: undefined,
+        checklistEvents: [],
+        recentDirectoriesTouched: [],
+    };
+}
+const CHECKLIST_TOOLS = new Set(['TodoWrite', 'todo_write', 'update_plan', 'TaskCreate', 'TaskUpdate']);
+const DIRECTORY_TOOLS = new Set(['Edit', 'Write', 'edit_file', 'write_file', 'create_file', 'edit', 'write', 'Bash', 'exec_command', 'run_shell_command', 'shell', 'Execute']);
+function foldDerivedToolState(state, event) {
+    if (CHECKLIST_TOOLS.has(event.tool ?? ''))
+        state.checklistEvents.push(event);
+    if (!DIRECTORY_TOOLS.has(event.tool ?? ''))
+        return;
+    const next = extractRecentDirectoriesTouched([event], state.cwd);
+    for (const dir of next ?? []) {
+        const old = state.recentDirectoriesTouched.indexOf(dir);
+        if (old >= 0)
+            state.recentDirectoriesTouched.splice(old, 1);
+        state.recentDirectoriesTouched.push(dir);
+    }
+    if (state.recentDirectoriesTouched.length > 10)
+        state.recentDirectoriesTouched.splice(0, state.recentDirectoriesTouched.length - 10);
+}
+/**
+ * Fold one parsed transcript line into the accumulator. This is the exact loop
+ * body {@link scanClaudeSession} used to run inline — extracted verbatim,
+ * mutating `state.*` in place. `parsed` is the already-`JSON.parse`d line (the
+ * malformed-line skip happens in the caller, as before).
+ */
+export function applyClaudeLine(state, parsed) {
+    // entrypoint ships on the first envelope event (attachment/user/assistant)
+    // and is the clean structural signal for "was this a team spawn?"
+    if (!state.entrypoint && typeof parsed.entrypoint === 'string') {
+        state.entrypoint = parsed.entrypoint;
+    }
+    // Produced-artifact signals, structurally (independent of the PR gate below):
+    //   - a Bash `agents teams create/add` command → the team it spawned
+    //   - a Linear create_issue / `gh issue create` tool_use → its result carries
+    //     the new ticket ref, read from the matching tool_result.
+    if (parsed.type === 'assistant' && Array.isArray(parsed.message?.content)) {
+        for (const b of parsed.message.content) {
+            if (b?.type !== 'tool_use')
+                continue;
+            if (!state.spawnedTeam && typeof b?.input?.command === 'string') {
+                const team = detectSpawnedTeam(b.input.command);
+                if (team)
+                    state.spawnedTeam = team;
+            }
+            if (typeof b?.id === 'string' && isTicketCreateTool(b?.name, b?.input?.command)) {
+                state.pendingTicketTools.add(b.id);
+            }
+            // ExitPlanMode plan markdown — last one wins so a re-planned session
+            // reports its most recent plan.
+            if (b?.name === 'ExitPlanMode' && typeof b?.input?.plan === 'string') {
+                const p = b.input.plan.trim();
+                if (p)
+                    state.plan = b.input.plan;
+            }
+            foldDerivedToolState(state, {
+                type: 'tool_use', agent: 'claude', timestamp: parsed.timestamp || '', tool: b?.name, args: b?.input || {},
+                path: b?.input?.file_path || b?.input?.path, command: b?.input?.command,
+            });
+        }
+    }
+    if (state.pendingTicketTools.size > 0 && parsed.type === 'user' && Array.isArray(parsed.message?.content)) {
+        for (const b of parsed.message.content) {
+            if (b?.type !== 'tool_result' || typeof b?.tool_use_id !== 'string')
+                continue;
+            if (!state.pendingTicketTools.has(b.tool_use_id))
+                continue;
+            state.pendingTicketTools.delete(b.tool_use_id);
+            const text = typeof b.content === 'string'
+                ? b.content
+                : Array.isArray(b.content) ? b.content.map((c) => c?.text || '').join('\n') : '';
+            const t = extractCreatedTicket(text);
+            if (t)
+                state.createdTickets.add(t);
+        }
+    }
+    // PR signal, structurally: a Bash tool_use whose command is `gh pr create`
+    // marks intent; the pull URL is then read from a tool_result's output.
+    if (!state.prUrl) {
+        if (!state.sawPrCreate && parsed.type === 'assistant' && Array.isArray(parsed.message?.content)) {
+            for (const b of parsed.message.content) {
+                if (b?.type === 'tool_use' && typeof b?.input?.command === 'string' && isPrCreateCommand(b.input.command)) {
+                    state.sawPrCreate = true;
+                }
+            }
+        }
+        if (state.sawPrCreate && parsed.type === 'user' && Array.isArray(parsed.message?.content)) {
+            for (const b of parsed.message.content) {
+                if (b?.type !== 'tool_result')
+                    continue;
+                const text = typeof b.content === 'string'
+                    ? b.content
+                    : Array.isArray(b.content) ? b.content.map((c) => c?.text || '').join('\n') : '';
+                const pr = extractPrUrl(text);
+                if (pr) {
+                    state.prUrl = pr.url;
+                    state.prNumber = pr.number;
+                }
+            }
+        }
+    }
+    // Track duration across every timestamped event, not just the first.
+    if (typeof parsed.timestamp === 'string') {
+        const ms = new Date(parsed.timestamp).getTime();
+        if (!Number.isNaN(ms)) {
+            if (state.firstTsMs === undefined || ms < state.firstTsMs)
+                state.firstTsMs = ms;
+            if (state.lastTsMs === undefined || ms > state.lastTsMs)
+                state.lastTsMs = ms;
+        }
+    }
+    if (!state.timestamp && (parsed.type === 'user' || parsed.type === 'assistant') && parsed.timestamp) {
+        state.timestamp = parsed.timestamp;
+        state.cwd = parsed.cwd || '';
+        state.gitBranch = parsed.gitBranch || undefined;
+        state.version = parsed.version || undefined;
+    }
+    if (parsed.type === 'custom-title') {
+        const t = typeof parsed.customTitle === 'string' ? parsed.customTitle.trim() : '';
+        if (t)
+            state.customTitle = t;
+        return;
+    }
+    if (parsed.type === 'ai-title') {
+        const t = typeof parsed.aiTitle === 'string' ? parsed.aiTitle.trim() : '';
+        if (t)
+            state.aiTitle = t;
+        return;
+    }
+    if (parsed.type === 'user') {
+        const text = extractClaudeUserText(parsed);
+        if (text) {
+            state.messageCount++;
+            state.userTexts.push(text);
+            if (!state.topic)
+                state.topic = extractSessionTopic(text);
+        }
+        return;
+    }
+    if (parsed.type !== 'assistant')
+        return;
+    const assistantId = typeof parsed.message?.id === 'string'
+        ? parsed.message.id
+        : typeof parsed.uuid === 'string'
+            ? parsed.uuid
+            : undefined;
+    const logicalId = assistantId || `${parsed.timestamp || ''}:${state.seenAssistantIds.size}`;
+    if (state.seenAssistantIds.has(logicalId))
+        return;
+    state.seenAssistantIds.add(logicalId);
+    state.messageCount++;
+    const usageObj = parsed.message?.usage || parsed.usage;
+    const usage = getClaudeUsageTotal(usageObj);
+    if (usage !== null) {
+        state.tokenCount += usage;
+        state.sawTokenCount = true;
+    }
+    if (typeof usageObj?.output_tokens === 'number')
+        state.outputTokens += usageObj.output_tokens;
+    // Per-assistant-message cost: each event carries its own model, so we
+    // multiply that event's raw token directions by that model's price.
+    const model = parsed.message?.model;
+    if (model && usageObj && typeof usageObj === 'object') {
+        const eventCost = costOfUsage({
+            model,
+            inputTokens: usageObj.input_tokens,
+            outputTokens: usageObj.output_tokens,
+            cacheReadTokens: usageObj.cache_read_input_tokens,
+            cacheCreationTokens: usageObj.cache_creation_input_tokens,
+        });
+        if (eventCost > 0) {
+            state.costUsd += eventCost;
+            state.sawCost = true;
+        }
+    }
+}
+/**
+ * Build the {@link ClaudeSessionScan} return object from an accumulator. This is
+ * the exact return-building {@link scanClaudeSession} used to run inline.
+ */
+export function finalizeClaudeScan(state) {
+    const durationMs = state.firstTsMs !== undefined && state.lastTsMs !== undefined && state.lastTsMs > state.firstTsMs
+        ? state.lastTsMs - state.firstTsMs
+        : undefined;
+    // Prefer an explicit session title (user `/rename` > Claude auto-title) over
+    // the first-prompt topic.
+    const resolvedTopic = state.customTitle || state.aiTitle || state.topic;
+    const worktree = detectWorktree(state.cwd, state.gitBranch);
+    const ticket = detectTicket(state.userTexts.join('\n') || undefined, state.gitBranch);
+    return {
+        timestamp: state.timestamp,
+        cwd: state.cwd,
+        gitBranch: state.gitBranch,
+        version: state.version,
+        topic: resolvedTopic,
+        entrypoint: state.entrypoint,
+        messageCount: state.messageCount,
+        tokenCount: state.sawTokenCount ? state.tokenCount : undefined,
+        outputTokens: state.sawTokenCount ? state.outputTokens : undefined,
+        costUsd: state.sawCost ? state.costUsd : undefined,
+        durationMs,
+        lastActivity: state.lastTsMs !== undefined ? new Date(state.lastTsMs).toISOString() : undefined,
+        contentText: state.userTexts.length > 0 ? state.userTexts.join('\n') : undefined,
+        prUrl: state.prUrl,
+        prNumber: state.prNumber,
+        worktreeSlug: worktree?.slug,
+        ticketId: ticket?.id,
+        createdTickets: state.createdTickets.size > 0 ? [...state.createdTickets] : undefined,
+        spawnedTeam: state.spawnedTeam,
+        plan: state.plan,
+        todos: extractTodoProgressFromEvents(state.checklistEvents),
+        recentDirectoriesTouched: state.recentDirectoriesTouched.length ? state.recentDirectoriesTouched : undefined,
+    };
+}
 /** Stream a Claude JSONL file and extract scan-level metadata (timestamp, cwd, topic, tokens). */
 export async function scanClaudeSession(filePath) {
     const stream = fs.createReadStream(filePath, { encoding: 'utf-8' });
     const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
-    let timestamp;
-    let cwd;
-    let gitBranch;
-    let version;
-    let topic;
-    // Explicit session titles: `/rename` writes a `custom-title` event; Claude
-    // auto-generates an `ai-title`. Both can repeat across the file — last wins.
-    let customTitle;
-    let aiTitle;
-    let entrypoint;
-    let messageCount = 0;
-    let tokenCount = 0;
-    let outputTokens = 0;
-    let sawTokenCount = false;
-    let costUsd = 0;
-    let sawCost = false;
-    // Track the first and last timestamped event to derive wall-clock duration.
-    let firstTsMs;
-    let lastTsMs;
-    const seenAssistantIds = new Set();
-    const userTexts = [];
-    // Durable PR signal: set only when an actual `gh pr create` Bash *command*
-    // runs (structural — the command field, not any prose mentioning it), then
-    // capture the pull URL from a later tool_result's output.
-    let sawPrCreate = false;
-    let prUrl;
-    let prNumber;
-    // Artifacts the session PRODUCED: tracker refs it created and any team it spawned.
-    // Ticket creation spans two events — a create_issue tool_use, then the tool_result
-    // carrying the new id — so we hold the pending tool_use ids until their result lands.
-    const createdTickets = new Set();
-    const pendingTicketTools = new Set();
-    let spawnedTeam;
-    // The LAST ExitPlanMode plan wins so a re-planned session surfaces its most
-    // recent plan, matching the semantic the extension's re-parser relied on.
-    let plan;
+    const state = initClaudeParseState();
     try {
         for await (const line of rl) {
             if (!line.trim())
@@ -1967,213 +2647,163 @@ export async function scanClaudeSession(filePath) {
             catch {
                 continue;
             }
-            // entrypoint ships on the first envelope event (attachment/user/assistant)
-            // and is the clean structural signal for "was this a team spawn?"
-            if (!entrypoint && typeof parsed.entrypoint === 'string') {
-                entrypoint = parsed.entrypoint;
-            }
-            // Produced-artifact signals, structurally (independent of the PR gate below):
-            //   - a Bash `agents teams create/add` command → the team it spawned
-            //   - a Linear create_issue / `gh issue create` tool_use → its result carries
-            //     the new ticket ref, read from the matching tool_result.
-            if (parsed.type === 'assistant' && Array.isArray(parsed.message?.content)) {
-                for (const b of parsed.message.content) {
-                    if (b?.type !== 'tool_use')
-                        continue;
-                    if (!spawnedTeam && typeof b?.input?.command === 'string') {
-                        const team = detectSpawnedTeam(b.input.command);
-                        if (team)
-                            spawnedTeam = team;
-                    }
-                    if (typeof b?.id === 'string' && isTicketCreateTool(b?.name, b?.input?.command)) {
-                        pendingTicketTools.add(b.id);
-                    }
-                    // ExitPlanMode plan markdown — last one wins so a re-planned session
-                    // reports its most recent plan.
-                    if (b?.name === 'ExitPlanMode' && typeof b?.input?.plan === 'string') {
-                        const p = b.input.plan.trim();
-                        if (p)
-                            plan = b.input.plan;
-                    }
-                }
-            }
-            if (pendingTicketTools.size > 0 && parsed.type === 'user' && Array.isArray(parsed.message?.content)) {
-                for (const b of parsed.message.content) {
-                    if (b?.type !== 'tool_result' || typeof b?.tool_use_id !== 'string')
-                        continue;
-                    if (!pendingTicketTools.has(b.tool_use_id))
-                        continue;
-                    pendingTicketTools.delete(b.tool_use_id);
-                    const text = typeof b.content === 'string'
-                        ? b.content
-                        : Array.isArray(b.content) ? b.content.map((c) => c?.text || '').join('\n') : '';
-                    const t = extractCreatedTicket(text);
-                    if (t)
-                        createdTickets.add(t);
-                }
-            }
-            // PR signal, structurally: a Bash tool_use whose command is `gh pr create`
-            // marks intent; the pull URL is then read from a tool_result's output.
-            if (!prUrl) {
-                if (!sawPrCreate && parsed.type === 'assistant' && Array.isArray(parsed.message?.content)) {
-                    for (const b of parsed.message.content) {
-                        if (b?.type === 'tool_use' && typeof b?.input?.command === 'string' && isPrCreateCommand(b.input.command)) {
-                            sawPrCreate = true;
-                        }
-                    }
-                }
-                if (sawPrCreate && parsed.type === 'user' && Array.isArray(parsed.message?.content)) {
-                    for (const b of parsed.message.content) {
-                        if (b?.type !== 'tool_result')
-                            continue;
-                        const text = typeof b.content === 'string'
-                            ? b.content
-                            : Array.isArray(b.content) ? b.content.map((c) => c?.text || '').join('\n') : '';
-                        const pr = extractPrUrl(text);
-                        if (pr) {
-                            prUrl = pr.url;
-                            prNumber = pr.number;
-                        }
-                    }
-                }
-            }
-            // Track duration across every timestamped event, not just the first.
-            if (typeof parsed.timestamp === 'string') {
-                const ms = new Date(parsed.timestamp).getTime();
-                if (!Number.isNaN(ms)) {
-                    if (firstTsMs === undefined || ms < firstTsMs)
-                        firstTsMs = ms;
-                    if (lastTsMs === undefined || ms > lastTsMs)
-                        lastTsMs = ms;
-                }
-            }
-            if (!timestamp && (parsed.type === 'user' || parsed.type === 'assistant') && parsed.timestamp) {
-                timestamp = parsed.timestamp;
-                cwd = parsed.cwd || '';
-                gitBranch = parsed.gitBranch || undefined;
-                version = parsed.version || undefined;
-            }
-            if (parsed.type === 'custom-title') {
-                const t = typeof parsed.customTitle === 'string' ? parsed.customTitle.trim() : '';
-                if (t)
-                    customTitle = t;
-                continue;
-            }
-            if (parsed.type === 'ai-title') {
-                const t = typeof parsed.aiTitle === 'string' ? parsed.aiTitle.trim() : '';
-                if (t)
-                    aiTitle = t;
-                continue;
-            }
-            if (parsed.type === 'user') {
-                const text = extractClaudeUserText(parsed);
-                if (text) {
-                    messageCount++;
-                    userTexts.push(text);
-                    if (!topic)
-                        topic = extractSessionTopic(text);
-                }
-                continue;
-            }
-            if (parsed.type !== 'assistant')
-                continue;
-            const assistantId = typeof parsed.message?.id === 'string'
-                ? parsed.message.id
-                : typeof parsed.uuid === 'string'
-                    ? parsed.uuid
-                    : undefined;
-            const logicalId = assistantId || `${parsed.timestamp || ''}:${seenAssistantIds.size}`;
-            if (seenAssistantIds.has(logicalId))
-                continue;
-            seenAssistantIds.add(logicalId);
-            messageCount++;
-            const usageObj = parsed.message?.usage || parsed.usage;
-            const usage = getClaudeUsageTotal(usageObj);
-            if (usage !== null) {
-                tokenCount += usage;
-                sawTokenCount = true;
-            }
-            if (typeof usageObj?.output_tokens === 'number')
-                outputTokens += usageObj.output_tokens;
-            // Per-assistant-message cost: each event carries its own model, so we
-            // multiply that event's raw token directions by that model's price.
-            const model = parsed.message?.model;
-            if (model && usageObj && typeof usageObj === 'object') {
-                const eventCost = costOfUsage({
-                    model,
-                    inputTokens: usageObj.input_tokens,
-                    outputTokens: usageObj.output_tokens,
-                    cacheReadTokens: usageObj.cache_read_input_tokens,
-                    cacheCreationTokens: usageObj.cache_creation_input_tokens,
-                });
-                if (eventCost > 0) {
-                    costUsd += eventCost;
-                    sawCost = true;
-                }
-            }
+            applyClaudeLine(state, parsed);
         }
     }
     finally {
         rl.close();
         stream.destroy();
     }
-    const durationMs = firstTsMs !== undefined && lastTsMs !== undefined && lastTsMs > firstTsMs
-        ? lastTsMs - firstTsMs
-        : undefined;
-    // Prefer an explicit session title (user `/rename` > Claude auto-title) over
-    // the first-prompt topic.
-    const resolvedTopic = customTitle || aiTitle || topic;
-    const worktree = detectWorktree(cwd, gitBranch);
-    const ticket = detectTicket(userTexts.join('\n') || undefined, gitBranch);
+    return finalizeClaudeScan(state);
+}
+/** Cap on the FIFO window of recent assistant ids persisted in the continuation. */
+const SEEN_IDS_RECENT_CAP = 256;
+/**
+ * Snapshot a live {@link ClaudeParseState} into its serializable form at
+ * `offset` bytes consumed. Round-trips through {@link hydrateClaudeParseState}
+ * so incremental replay equals a full parse.
+ */
+export function serializeClaudeParserState(state, offset) {
+    const allIds = [...state.seenAssistantIds];
+    const seenIdsRecent = allIds.length > SEEN_IDS_RECENT_CAP
+        ? allIds.slice(allIds.length - SEEN_IDS_RECENT_CAP)
+        : allIds;
+    const ticket = detectTicket(state.userTexts.join('\n') || undefined, state.gitBranch);
     return {
-        timestamp,
-        cwd,
-        gitBranch,
-        version,
-        topic: resolvedTopic,
-        entrypoint,
-        messageCount,
-        tokenCount: sawTokenCount ? tokenCount : undefined,
-        outputTokens: sawTokenCount ? outputTokens : undefined,
-        costUsd: sawCost ? costUsd : undefined,
-        durationMs,
-        lastActivity: lastTsMs !== undefined ? new Date(lastTsMs).toISOString() : undefined,
-        contentText: userTexts.length > 0 ? userTexts.join('\n') : undefined,
-        prUrl,
-        prNumber,
-        worktreeSlug: worktree?.slug,
+        v: 1,
+        offset,
+        timestamp: state.timestamp,
+        cwd: state.cwd,
+        gitBranch: state.gitBranch,
+        version: state.version,
+        entrypoint: state.entrypoint,
+        firstTsMs: state.firstTsMs,
+        topic: state.topic,
+        customTitle: state.customTitle,
+        aiTitle: state.aiTitle,
+        plan: state.plan,
+        lastTsMs: state.lastTsMs,
+        messageCount: state.messageCount,
+        tokenCount: state.tokenCount,
+        outputTokens: state.outputTokens,
+        sawTokenCount: state.sawTokenCount,
+        sawCost: state.sawCost,
+        costUsd: state.costUsd,
+        seenIdsSize: state.seenAssistantIds.size,
+        seenIdsRecent,
+        sawPrCreate: state.sawPrCreate,
+        prUrl: state.prUrl,
+        prNumber: state.prNumber,
+        pendingTicketTools: [...state.pendingTicketTools],
+        createdTickets: [...state.createdTickets],
+        spawnedTeam: state.spawnedTeam,
+        // ticketId is derived at finalize time; persist it (and content_text) so a
+        // consumer (B-2) can rebuild the row + FTS doc on append without re-reading
+        // the whole file. worktreeSlug is re-derived from cwd/gitBranch, so it need
+        // not be persisted.
         ticketId: ticket?.id,
-        createdTickets: createdTickets.size > 0 ? [...createdTickets] : undefined,
-        spawnedTeam,
-        plan,
+        contentText: state.userTexts.length > 0 ? state.userTexts.join('\n') : undefined,
+        checklistEvents: state.checklistEvents,
+        recentDirectoriesTouched: state.recentDirectoriesTouched,
     };
 }
-/** Stream a Codex JSONL file and extract scan-level metadata (session ID, cwd, topic, tokens). */
-async function scanCodexSession(filePath) {
-    const stream = fs.createReadStream(filePath, { encoding: 'utf-8' });
-    const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
-    let sessionId;
-    let timestamp;
-    let cwd;
-    let gitBranch;
-    let version;
-    let topic;
-    let messageCount = 0;
-    let tokenCount;
-    let model;
-    let lastTotalTokenUsage;
-    let firstTsMs;
-    let lastTsMs;
-    const userTexts = [];
-    let sawPrCreate = false;
-    let prUrl;
-    let prNumber;
-    // Produced artifacts (mirror of the Claude scan): created tracker refs + spawned team.
-    const createdTickets = new Set();
-    const pendingTicketTools = new Set();
-    let spawnedTeam;
+/**
+ * Rebuild a live {@link ClaudeParseState} from a persisted continuation so that
+ * applying the appended lines yields the same accumulator a full parse would.
+ *
+ * `seenAssistantIds` is rehydrated from the recent-id FIFO window, then padded
+ * with unique sentinel entries so its `.size` matches the true prior count
+ * (`seenIdsSize`) — the fallback id `${ts}:${size}` must line up with the full
+ * parse even when the window dropped older ids. Padding sentinels can never
+ * collide with a real logical id (real ids are message ids/uuids or
+ * `${ts}:${n}`; the sentinel prefix is not JSON-line-derived).
+ *
+ * `userTexts` is rehydrated as a single joined blob from `contentText`: only
+ * `userTexts.join('\n')` (detectTicket + contentText) and `userTexts.length > 0`
+ * are ever read downstream, and both are preserved by a one-element array
+ * holding the joined content.
+ */
+export function hydrateClaudeParseState(prior) {
+    const seen = new Set(prior.seenIdsRecent);
+    // Pad to the true prior size so `seenAssistantIds.size` (which feeds the
+    // fallback logical id) is exact even when older ids fell out of the window.
+    let pad = 0;
+    while (seen.size < prior.seenIdsSize) {
+        seen.add(`pad:${pad++}`);
+    }
+    return {
+        timestamp: prior.timestamp,
+        cwd: prior.cwd,
+        gitBranch: prior.gitBranch,
+        version: prior.version,
+        topic: prior.topic,
+        customTitle: prior.customTitle,
+        aiTitle: prior.aiTitle,
+        entrypoint: prior.entrypoint,
+        messageCount: prior.messageCount,
+        tokenCount: prior.tokenCount,
+        outputTokens: prior.outputTokens,
+        sawTokenCount: prior.sawTokenCount,
+        costUsd: prior.costUsd,
+        sawCost: prior.sawCost,
+        firstTsMs: prior.firstTsMs,
+        lastTsMs: prior.lastTsMs,
+        seenAssistantIds: seen,
+        userTexts: prior.contentText !== undefined && prior.contentText.length > 0 ? [prior.contentText] : [],
+        sawPrCreate: prior.sawPrCreate,
+        prUrl: prior.prUrl,
+        prNumber: prior.prNumber,
+        createdTickets: new Set(prior.createdTickets),
+        pendingTicketTools: new Set(prior.pendingTicketTools),
+        spawnedTeam: prior.spawnedTeam,
+        plan: prior.plan,
+        checklistEvents: prior.checklistEvents ?? [],
+        recentDirectoriesTouched: prior.recentDirectoriesTouched ?? [],
+    };
+}
+/**
+ * Resume a Claude parse from `fromOffset` bytes into the file, folding only the
+ * newly-appended lines into `prior`. Returns the finalized scan, the next
+ * serialized continuation, and the byte offset to resume from next time —
+ * `newOffset` stops at the last `'\n'` seen so a half-written trailing record is
+ * re-read (not lost) on the next append.
+ *
+ * NOT wired into the live scan path yet (that is B-2); {@link scanClaudeSession}
+ * remains the only caller-facing entry point. This exists so the parity harness
+ * can prove full === hydrate(state@k) + apply(k+1..n).
+ */
+export async function scanClaudeSessionIncremental(filePath, fromOffset, prior) {
+    const state = hydrateClaudeParseState(prior);
+    // Read the appended byte range and apply ONLY newline-terminated lines. The
+    // applied lines and `newOffset` MUST stay consistent: readline (like the full
+    // parse) would emit a trailing UNTERMINATED final line at EOF, but `newOffset`
+    // stops before it — so the next pass, after that record's '\n' is flushed,
+    // would re-read and re-apply the same line and double-count it (user events
+    // have no dedup, unlike assistant `seenAssistantIds`). A record written
+    // non-atomically — bytes first, then '\n' in a second write — is exactly this
+    // case. So we slice at the last '\n' ourselves: everything up to and including
+    // it is a run of complete lines we apply and commit; any tail after it
+    // (syntactically broken OR complete-but-not-yet-terminated) is a still-being-
+    // written record we DEFER to the next pass, once its '\n' lands.
+    const chunks = [];
+    const stream = fs.createReadStream(filePath, { start: fromOffset });
     try {
-        for await (const line of rl) {
+        for await (const chunk of stream) {
+            chunks.push(typeof chunk === 'string' ? Buffer.from(chunk, 'utf-8') : chunk);
+        }
+    }
+    finally {
+        stream.destroy();
+    }
+    const appended = Buffer.concat(chunks);
+    // Bytes up to AND INCLUDING the last '\n' are the committed, complete-line run.
+    const lastNl = appended.lastIndexOf(0x0a);
+    const consumedBytes = lastNl === -1 ? 0 : lastNl + 1;
+    if (consumedBytes > 0) {
+        // split('\n') on the committed run: the element after the final '\n' is ''
+        // (skipped by the trim guard). A stray '\r' from CRLF is tolerated by the
+        // JSON.parse below exactly as the full parse tolerates it.
+        for (const line of appended.subarray(0, consumedBytes).toString('utf-8').split('\n')) {
             if (!line.trim())
                 continue;
             let parsed;
@@ -2183,140 +2813,558 @@ async function scanCodexSession(filePath) {
             catch {
                 continue;
             }
-            // PR signal, structurally: a Codex `function_call` whose command is
-            // `gh pr create`, then the pull URL from a `function_call_output`.
-            if (parsed.type === 'response_item') {
-                const p = parsed.payload || {};
-                if (p.type === 'function_call') {
-                    let cmd = '';
-                    try {
-                        const args = typeof p.arguments === 'string' ? JSON.parse(p.arguments) : (p.arguments || {});
-                        cmd = String(args.command || args.cmd || '');
-                    }
-                    catch { /* non-JSON args */ }
-                    if (!prUrl && !sawPrCreate && isPrCreateCommand(cmd))
-                        sawPrCreate = true;
-                    if (!spawnedTeam) {
-                        const team = detectSpawnedTeam(cmd);
-                        if (team)
-                            spawnedTeam = team;
-                    }
-                    if (typeof p.call_id === 'string' && isTicketCreateTool(p.name, cmd)) {
-                        pendingTicketTools.add(p.call_id);
-                    }
-                }
-                if (p.type === 'function_call_output') {
-                    if (!prUrl && sawPrCreate) {
-                        const pr = extractPrUrl(String(p.output || ''));
-                        if (pr) {
-                            prUrl = pr.url;
-                            prNumber = pr.number;
-                        }
-                    }
-                    if (typeof p.call_id === 'string' && pendingTicketTools.has(p.call_id)) {
-                        pendingTicketTools.delete(p.call_id);
-                        const t = extractCreatedTicket(String(p.output || ''));
-                        if (t)
-                            createdTickets.add(t);
-                    }
-                }
-            }
-            // Track duration across every timestamped event.
-            if (typeof parsed.timestamp === 'string') {
-                const ms = new Date(parsed.timestamp).getTime();
-                if (!Number.isNaN(ms)) {
-                    if (firstTsMs === undefined || ms < firstTsMs)
-                        firstTsMs = ms;
-                    if (lastTsMs === undefined || ms > lastTsMs)
-                        lastTsMs = ms;
-                }
-            }
-            if (parsed.type === 'session_meta') {
-                const payload = parsed.payload || {};
-                sessionId = payload.id || sessionId;
-                timestamp = payload.timestamp || parsed.timestamp || timestamp;
-                cwd = payload.cwd || cwd;
-                gitBranch = payload.git?.branch || gitBranch;
-                version = payload.cli_version || payload.version || version;
-                model = payload.model || model;
+            applyClaudeLine(state, parsed);
+        }
+    }
+    const newOffset = fromOffset + consumedBytes;
+    return {
+        scan: finalizeClaudeScan(state),
+        newState: serializeClaudeParserState(state, newOffset),
+        newOffset,
+    };
+}
+/** Serialized zero-value continuation: a fresh accumulator at offset 0, used to drive a FULL parse from the start through the same resumable path. */
+function freshClaudeParserState() {
+    return serializeClaudeParserState(initClaudeParseState(), 0);
+}
+/**
+ * Decide full-vs-incremental for one Claude file and parse it uniformly, always
+ * returning a finalized scan plus the continuation to persist. Both branches run
+ * through the SAME reducer (via {@link scanClaudeSessionIncremental}), so the row
+ * an append produces is identical to a from-scratch full reparse by construction
+ * (the B-1 parity harness proves this at the function level).
+ *
+ * INCREMENTAL when a prior continuation exists AND the file grew past the
+ * persisted offset AND its mtime did not go backwards — an in-place append.
+ * FULL (from byte 0, fresh state) otherwise: cold start (no prior), truncation /
+ * rewrite (size shrank to at or below the offset), or a clock rewind / restore
+ * (mtime older than the last parse). A FULL parse still produces a continuation,
+ * so the file's very next append can go incremental.
+ *
+ * `mode` is returned so the caller (and tests) can confirm which branch ran.
+ */
+async function scanClaudeSessionResumable(filePath, prior, currentFileMtimeMs, currentFileSize, priorFileMtimeMs) {
+    // File size + mtime cannot distinguish an APPEND from an in-place rewrite or a
+    // restore that dropped DIFFERENT, larger content at the same path: both grow
+    // the file and move mtime forward. Resuming from the stored offset across that
+    // boundary would fold the new file's bytes into an accumulator hydrated from
+    // the OLD session, so the persisted row silently diverges from a full reparse.
+    // So the metadata gate below only makes a file ELIGIBLE; before trusting the
+    // offset we re-read the transcript's first user/assistant timestamp and require
+    // it to still match the prior continuation's. An append keeps that identity
+    // byte-for-byte; a rewrite/restore of a different session changes it. A
+    // mismatch — or an identity we cannot derive — falls back to a FULL parse,
+    // which is always correct. (A shrink is already handled: currentFileSize is not
+    // > prior.offset, so it takes the FULL branch.)
+    let canIncrement = false;
+    if (prior !== null &&
+        currentFileSize > prior.offset &&
+        (priorFileMtimeMs === undefined || currentFileMtimeMs >= priorFileMtimeMs) &&
+        prior.timestamp !== undefined) {
+        canIncrement = (await claudeSessionIdentityAt(filePath)) === prior.timestamp;
+    }
+    if (canIncrement && prior !== null) {
+        const result = await scanClaudeSessionIncremental(filePath, prior.offset, prior);
+        return { ...result, mode: 'incremental' };
+    }
+    const result = await scanClaudeSessionIncremental(filePath, 0, freshClaudeParserState());
+    return { ...result, mode: 'full' };
+}
+/**
+ * Cheaply derive a Claude transcript's session identity — the first
+ * user/assistant event `timestamp` — by streaming only the START of the file
+ * (at most `maxBytes`) and stopping at the first such event. Used by
+ * {@link scanClaudeSessionResumable} to confirm a grown file is still the SAME
+ * session before resuming from a stored parse offset. Returns undefined when no
+ * user/assistant event appears within the budget, which forces a FULL parse.
+ */
+async function claudeSessionIdentityAt(filePath, maxBytes = 1_048_576) {
+    const state = initClaudeParseState();
+    const stream = fs.createReadStream(filePath, { start: 0, end: maxBytes - 1, encoding: 'utf-8' });
+    const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+    try {
+        for await (const line of rl) {
+            if (!line.trim())
                 continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
             }
-            if (parsed.type === 'response_item' && parsed.payload?.type === 'message') {
-                const role = parsed.payload.role === 'user' || parsed.payload.role === 'developer'
-                    ? 'user'
-                    : 'assistant';
-                const text = extractCodexMessageText(parsed.payload.content, role);
-                if (!text)
-                    continue;
-                messageCount++;
-                if (role === 'user') {
-                    userTexts.push(text);
-                    if (!topic)
-                        topic = extractSessionTopic(text);
-                }
+            catch {
                 continue;
             }
-            if (parsed.type === 'event_msg' && parsed.payload?.type === 'token_count') {
-                const totalUsage = parsed.payload.info?.total_token_usage;
-                const total = getCodexTokenCount(totalUsage);
-                if (total !== null)
-                    tokenCount = total;
-                // token_count is cumulative — keep the latest snapshot and price it once
-                // after the stream, so we don't double-count across intermediate events.
-                if (totalUsage && typeof totalUsage === 'object')
-                    lastTotalTokenUsage = totalUsage;
-                // Codex also stamps the model on the rate_limits/token_count payload on
-                // some versions; prefer session_meta but fall back to it.
-                if (!model && typeof parsed.payload.info?.model === 'string')
-                    model = parsed.payload.info.model;
-            }
+            applyClaudeLine(state, parsed);
+            if (state.timestamp !== undefined)
+                break;
         }
     }
     finally {
         rl.close();
         stream.destroy();
     }
+    return state.timestamp;
+}
+/**
+ * Parse the prior continuation blob for a changed file into a usable
+ * {@link ClaudeParserState}, or null when there is none / it is unusable. A blob
+ * from a different serialization version is treated as absent so the file falls
+ * back to a clean FULL parse rather than resuming against a stale shape.
+ */
+function parsePriorClaudeState(row) {
+    if (!row?.parserState)
+        return null;
+    try {
+        const parsed = JSON.parse(row.parserState);
+        if (parsed?.v !== 1 || typeof parsed.offset !== 'number')
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** Test seam: how many times the incremental (append-resume) branch was taken since the last reset. */
+let claudeIncrementalScanCount = 0;
+/** Test seam: how many times a full (from-offset-0) Claude parse ran since the last reset. */
+let claudeFullScanCount = 0;
+/** Test seam: read the (incremental, full) Claude parse counters. */
+export function __claudeScanBranchCountsForTest() {
+    return { incremental: claudeIncrementalScanCount, full: claudeFullScanCount };
+}
+/** Test seam: reset the Claude parse-branch counters to observe a scan from a clean slate. */
+export function __resetClaudeScanBranchCountsForTest() {
+    claudeIncrementalScanCount = 0;
+    claudeFullScanCount = 0;
+}
+/** Zero-value accumulator for a fresh (from-byte-0) Codex parse. */
+export function initCodexParseState() {
+    return {
+        sessionId: undefined,
+        timestamp: undefined,
+        cwd: undefined,
+        gitBranch: undefined,
+        version: undefined,
+        model: undefined,
+        topic: undefined,
+        messageCount: 0,
+        tokenCount: undefined,
+        lastTotalTokenUsage: undefined,
+        firstTsMs: undefined,
+        lastTsMs: undefined,
+        userTexts: [],
+        sawPrCreate: false,
+        prUrl: undefined,
+        prNumber: undefined,
+        createdTickets: new Set(),
+        pendingTicketTools: new Set(),
+        spawnedTeam: undefined,
+        checklistEvents: [],
+        recentDirectoriesTouched: [],
+    };
+}
+/**
+ * Fold one parsed Codex line into the accumulator — the exact loop body
+ * {@link scanCodexSession} used to run inline, extracted verbatim and mutating
+ * `state.*` in place. `parsed` is the already-`JSON.parse`d line (the
+ * malformed-line skip happens in the caller, as before).
+ */
+export function applyCodexLine(state, parsed) {
+    // PR signal, structurally: a Codex `function_call` whose command is
+    // `gh pr create`, then the pull URL from a `function_call_output`.
+    if (parsed.type === 'response_item') {
+        const p = parsed.payload || {};
+        if (p.type === 'function_call') {
+            let cmd = '';
+            let args = {};
+            try {
+                args = typeof p.arguments === 'string' ? JSON.parse(p.arguments) : (p.arguments || {});
+                cmd = String(args.command || args.cmd || '');
+            }
+            catch { /* non-JSON args */ }
+            foldDerivedToolState(state, {
+                type: 'tool_use', agent: 'codex', timestamp: parsed.timestamp || '', tool: p.name, args,
+                path: args.file_path || args.path, command: cmd || undefined,
+            });
+            if (!state.prUrl && !state.sawPrCreate && isPrCreateCommand(cmd))
+                state.sawPrCreate = true;
+            if (!state.spawnedTeam) {
+                const team = detectSpawnedTeam(cmd);
+                if (team)
+                    state.spawnedTeam = team;
+            }
+            if (typeof p.call_id === 'string' && isTicketCreateTool(p.name, cmd)) {
+                state.pendingTicketTools.add(p.call_id);
+            }
+        }
+        if (p.type === 'function_call_output') {
+            if (!state.prUrl && state.sawPrCreate) {
+                const pr = extractPrUrl(String(p.output || ''));
+                if (pr) {
+                    state.prUrl = pr.url;
+                    state.prNumber = pr.number;
+                }
+            }
+            if (typeof p.call_id === 'string' && state.pendingTicketTools.has(p.call_id)) {
+                state.pendingTicketTools.delete(p.call_id);
+                const t = extractCreatedTicket(String(p.output || ''));
+                if (t)
+                    state.createdTickets.add(t);
+            }
+        }
+    }
+    // Track duration across every timestamped event.
+    if (typeof parsed.timestamp === 'string') {
+        const ms = new Date(parsed.timestamp).getTime();
+        if (!Number.isNaN(ms)) {
+            if (state.firstTsMs === undefined || ms < state.firstTsMs)
+                state.firstTsMs = ms;
+            if (state.lastTsMs === undefined || ms > state.lastTsMs)
+                state.lastTsMs = ms;
+        }
+    }
+    if (parsed.type === 'session_meta') {
+        const payload = parsed.payload || {};
+        state.sessionId = payload.id || state.sessionId;
+        state.timestamp = payload.timestamp || parsed.timestamp || state.timestamp;
+        state.cwd = payload.cwd || state.cwd;
+        state.gitBranch = payload.git?.branch || state.gitBranch;
+        state.version = payload.cli_version || payload.version || state.version;
+        state.model = payload.model || state.model;
+        return;
+    }
+    if (parsed.type === 'response_item' && parsed.payload?.type === 'message') {
+        const role = parsed.payload.role === 'user' || parsed.payload.role === 'developer'
+            ? 'user'
+            : 'assistant';
+        const text = extractCodexMessageText(parsed.payload.content, role);
+        if (!text)
+            return;
+        state.messageCount++;
+        if (role === 'user') {
+            state.userTexts.push(text);
+            if (!state.topic)
+                state.topic = extractSessionTopic(text);
+        }
+        return;
+    }
+    if (parsed.type === 'event_msg' && parsed.payload?.type === 'token_count') {
+        const totalUsage = parsed.payload.info?.total_token_usage;
+        const total = getCodexTokenCount(totalUsage);
+        if (total !== null)
+            state.tokenCount = total;
+        // token_count is cumulative — keep the latest snapshot and price it once
+        // after the stream, so we don't double-count across intermediate events.
+        if (totalUsage && typeof totalUsage === 'object')
+            state.lastTotalTokenUsage = totalUsage;
+        // Codex also stamps the model on the rate_limits/token_count payload on
+        // some versions; prefer session_meta but fall back to it.
+        if (!state.model && typeof parsed.payload.info?.model === 'string')
+            state.model = parsed.payload.info.model;
+    }
+}
+/**
+ * Build the {@link CodexSessionScan} return object from an accumulator — the
+ * exact return-building {@link scanCodexSession} used to run inline.
+ */
+export function finalizeCodexScan(state) {
     // Price the final cumulative token snapshot once, against the session model.
     let costUsd;
-    if (model && lastTotalTokenUsage) {
+    if (state.model && state.lastTotalTokenUsage) {
         const c = costOfUsage({
-            model,
-            inputTokens: lastTotalTokenUsage.input_tokens,
-            outputTokens: (lastTotalTokenUsage.output_tokens ?? 0) + (lastTotalTokenUsage.reasoning_output_tokens ?? 0),
-            cacheReadTokens: lastTotalTokenUsage.cached_input_tokens,
+            model: state.model,
+            inputTokens: state.lastTotalTokenUsage.input_tokens,
+            outputTokens: (state.lastTotalTokenUsage.output_tokens ?? 0) + (state.lastTotalTokenUsage.reasoning_output_tokens ?? 0),
+            cacheReadTokens: state.lastTotalTokenUsage.cached_input_tokens,
         });
         if (c > 0)
             costUsd = c;
     }
-    const durationMs = firstTsMs !== undefined && lastTsMs !== undefined && lastTsMs > firstTsMs
-        ? lastTsMs - firstTsMs
+    const durationMs = state.firstTsMs !== undefined && state.lastTsMs !== undefined && state.lastTsMs > state.firstTsMs
+        ? state.lastTsMs - state.firstTsMs
         : undefined;
-    const worktree = detectWorktree(cwd, gitBranch);
-    const ticket = detectTicket(userTexts.join('\n') || undefined, gitBranch);
+    const worktree = detectWorktree(state.cwd, state.gitBranch);
+    const ticket = detectTicket(state.userTexts.join('\n') || undefined, state.gitBranch);
     return {
-        sessionId,
-        timestamp,
-        cwd,
-        gitBranch,
-        version,
-        topic,
-        messageCount,
-        tokenCount,
-        outputTokens: lastTotalTokenUsage
-            ? (lastTotalTokenUsage.output_tokens ?? 0) + (lastTotalTokenUsage.reasoning_output_tokens ?? 0)
+        sessionId: state.sessionId,
+        timestamp: state.timestamp,
+        cwd: state.cwd,
+        gitBranch: state.gitBranch,
+        version: state.version,
+        topic: state.topic,
+        messageCount: state.messageCount,
+        tokenCount: state.tokenCount,
+        outputTokens: state.lastTotalTokenUsage
+            ? (state.lastTotalTokenUsage.output_tokens ?? 0) + (state.lastTotalTokenUsage.reasoning_output_tokens ?? 0)
             : undefined,
         costUsd,
         durationMs,
-        lastActivity: lastTsMs !== undefined ? new Date(lastTsMs).toISOString() : undefined,
-        contentText: userTexts.length > 0 ? userTexts.join('\n') : undefined,
-        prUrl,
-        prNumber,
+        lastActivity: state.lastTsMs !== undefined ? new Date(state.lastTsMs).toISOString() : undefined,
+        contentText: state.userTexts.length > 0 ? state.userTexts.join('\n') : undefined,
+        prUrl: state.prUrl,
+        prNumber: state.prNumber,
         worktreeSlug: worktree?.slug,
         ticketId: ticket?.id,
-        createdTickets: createdTickets.size > 0 ? [...createdTickets] : undefined,
-        spawnedTeam,
+        createdTickets: state.createdTickets.size > 0 ? [...state.createdTickets] : undefined,
+        spawnedTeam: state.spawnedTeam,
+        todos: extractTodoProgressFromEvents(state.checklistEvents),
+        recentDirectoriesTouched: state.recentDirectoriesTouched.length ? state.recentDirectoriesTouched : undefined,
+    };
+}
+/** Stream a Codex JSONL file and extract scan-level metadata (session ID, cwd, topic, tokens). */
+async function scanCodexSession(filePath) {
+    const stream = fs.createReadStream(filePath, { encoding: 'utf-8' });
+    const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+    const state = initCodexParseState();
+    try {
+        for await (const line of rl) {
+            if (!line.trim())
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            applyCodexLine(state, parsed);
+        }
+    }
+    finally {
+        rl.close();
+        stream.destroy();
+    }
+    return finalizeCodexScan(state);
+}
+/**
+ * Snapshot a live {@link CodexParseState} into its serializable form at `offset`
+ * bytes consumed. Round-trips through {@link hydrateCodexParseState} so
+ * incremental replay equals a full parse.
+ */
+export function serializeCodexParserState(state, offset) {
+    const ticket = detectTicket(state.userTexts.join('\n') || undefined, state.gitBranch);
+    return {
+        v: 1,
+        offset,
+        sessionId: state.sessionId,
+        timestamp: state.timestamp,
+        cwd: state.cwd,
+        gitBranch: state.gitBranch,
+        version: state.version,
+        model: state.model,
+        topic: state.topic,
+        messageCount: state.messageCount,
+        tokenCount: state.tokenCount,
+        lastTotalTokenUsage: state.lastTotalTokenUsage,
+        firstTsMs: state.firstTsMs,
+        lastTsMs: state.lastTsMs,
+        sawPrCreate: state.sawPrCreate,
+        prUrl: state.prUrl,
+        prNumber: state.prNumber,
+        pendingTicketTools: [...state.pendingTicketTools],
+        createdTickets: [...state.createdTickets],
+        spawnedTeam: state.spawnedTeam,
+        // ticketId is derived at finalize time; persist it (and content_text) so a
+        // consumer can rebuild the row + FTS doc on append without re-reading the
+        // whole file. worktreeSlug is re-derived from cwd/gitBranch, so it need not
+        // be persisted.
+        ticketId: ticket?.id,
+        contentText: state.userTexts.length > 0 ? state.userTexts.join('\n') : undefined,
+        checklistEvents: state.checklistEvents,
+        recentDirectoriesTouched: state.recentDirectoriesTouched,
+    };
+}
+/**
+ * Rebuild a live {@link CodexParseState} from a persisted continuation so that
+ * applying the appended lines yields the same accumulator a full parse would.
+ *
+ * `userTexts` is rehydrated as a single joined blob from `contentText`: only
+ * `userTexts.join('\n')` (detectTicket + contentText) and `userTexts.length > 0`
+ * are ever read downstream, and both are preserved by a one-element array
+ * holding the joined content. Topic is first-wins and already persisted, so a
+ * collapsed userTexts never changes it.
+ */
+export function hydrateCodexParseState(prior) {
+    return {
+        sessionId: prior.sessionId,
+        timestamp: prior.timestamp,
+        cwd: prior.cwd,
+        gitBranch: prior.gitBranch,
+        version: prior.version,
+        model: prior.model,
+        topic: prior.topic,
+        messageCount: prior.messageCount,
+        tokenCount: prior.tokenCount,
+        lastTotalTokenUsage: prior.lastTotalTokenUsage,
+        firstTsMs: prior.firstTsMs,
+        lastTsMs: prior.lastTsMs,
+        userTexts: prior.contentText !== undefined && prior.contentText.length > 0 ? [prior.contentText] : [],
+        sawPrCreate: prior.sawPrCreate,
+        prUrl: prior.prUrl,
+        prNumber: prior.prNumber,
+        createdTickets: new Set(prior.createdTickets),
+        pendingTicketTools: new Set(prior.pendingTicketTools),
+        spawnedTeam: prior.spawnedTeam,
+        checklistEvents: prior.checklistEvents ?? [],
+        recentDirectoriesTouched: prior.recentDirectoriesTouched ?? [],
+    };
+}
+/**
+ * Resume a Codex parse from `fromOffset` bytes into the file, folding only the
+ * newly-appended lines into `prior`. Returns the finalized scan, the next
+ * serialized continuation, and the byte offset to resume from next time.
+ *
+ * Same trailing-line discipline as {@link scanClaudeSessionIncremental}: apply
+ * ONLY the run of newline-terminated lines (slice at the last `'\n'`), and set
+ * `newOffset = fromOffset + consumedBytes`. Any tail after the last `'\n'` —
+ * syntactically broken OR a complete-but-not-yet-terminated record — is DEFERRED
+ * to the next pass once its `'\n'` lands. Codex `messageCount` is additive with
+ * NO dedup, so re-reading a still-unterminated complete line would double-count
+ * it; deferring prevents that (the bug class prix-cloud caught for Claude).
+ */
+export async function scanCodexSessionIncremental(filePath, fromOffset, prior) {
+    const state = hydrateCodexParseState(prior);
+    const chunks = [];
+    const stream = fs.createReadStream(filePath, { start: fromOffset });
+    try {
+        for await (const chunk of stream) {
+            chunks.push(typeof chunk === 'string' ? Buffer.from(chunk, 'utf-8') : chunk);
+        }
+    }
+    finally {
+        stream.destroy();
+    }
+    const appended = Buffer.concat(chunks);
+    // Bytes up to AND INCLUDING the last '\n' are the committed, complete-line run.
+    const lastNl = appended.lastIndexOf(0x0a);
+    const consumedBytes = lastNl === -1 ? 0 : lastNl + 1;
+    if (consumedBytes > 0) {
+        for (const line of appended.subarray(0, consumedBytes).toString('utf-8').split('\n')) {
+            if (!line.trim())
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            applyCodexLine(state, parsed);
+        }
+    }
+    const newOffset = fromOffset + consumedBytes;
+    return {
+        scan: finalizeCodexScan(state),
+        newState: serializeCodexParserState(state, newOffset),
+        newOffset,
     };
 }
+/** Serialized zero-value continuation: a fresh accumulator at offset 0, used to drive a FULL parse from the start through the same resumable path. */
+function freshCodexParserState() {
+    return serializeCodexParserState(initCodexParseState(), 0);
+}
+/**
+ * Cheaply derive a Codex rollout's session identity — the `session_meta` id — by
+ * streaming only the START of the file (at most `maxBytes`) and stopping once the
+ * id is known. Mirrors {@link claudeSessionIdentityAt}: used by
+ * {@link scanCodexSessionResumable} to confirm a grown file is still the SAME
+ * session before resuming from a stored parse offset. Codex writes `session_meta`
+ * (carrying the durable session UUID) on the first line of every rollout, so the
+ * id is reached almost immediately. Returns undefined when no id appears within
+ * the budget, which forces a FULL parse.
+ */
+async function codexSessionIdentityAt(filePath, maxBytes = 1_048_576) {
+    const state = initCodexParseState();
+    const stream = fs.createReadStream(filePath, { start: 0, end: maxBytes - 1, encoding: 'utf-8' });
+    const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+    try {
+        for await (const line of rl) {
+            if (!line.trim())
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            applyCodexLine(state, parsed);
+            if (state.sessionId !== undefined)
+                break;
+        }
+    }
+    finally {
+        rl.close();
+        stream.destroy();
+    }
+    return state.sessionId;
+}
+/**
+ * Decide full-vs-incremental for one Codex rollout and parse it uniformly,
+ * always returning a finalized scan plus the continuation to persist. Both
+ * branches run through the SAME reducer (via {@link scanCodexSessionIncremental}),
+ * so an append produces a row identical to a from-scratch full reparse by
+ * construction. INCREMENTAL when a prior continuation exists AND the file grew
+ * past the persisted offset AND its mtime did not go backwards; FULL (from byte
+ * 0, fresh state) otherwise (cold start, truncation/rewrite, clock rewind).
+ */
+async function scanCodexSessionResumable(filePath, prior, currentFileMtimeMs, currentFileSize, priorFileMtimeMs) {
+    // File size + mtime cannot distinguish an APPEND from an in-place rewrite or a
+    // restore that dropped a DIFFERENT, larger rollout at the same path: both grow
+    // the file and move mtime forward. Resuming from the stored offset across that
+    // boundary would fold the new session's bytes into an accumulator hydrated from
+    // the OLD session, so the persisted row silently diverges from a full reparse.
+    // So the metadata gate below only makes a file ELIGIBLE; before trusting the
+    // offset we re-read the rollout's `session_meta` id and require it to still
+    // match the prior continuation's. An append keeps that id; a rewrite/restore of
+    // a different session changes it. A mismatch — or an id we cannot derive —
+    // falls back to a FULL parse, which is always correct. (A shrink is already
+    // handled: currentFileSize is not > prior.offset, so it takes the FULL branch.)
+    let canIncrement = false;
+    if (prior !== null &&
+        currentFileSize > prior.offset &&
+        (priorFileMtimeMs === undefined || currentFileMtimeMs >= priorFileMtimeMs) &&
+        prior.sessionId !== undefined) {
+        canIncrement = (await codexSessionIdentityAt(filePath)) === prior.sessionId;
+    }
+    if (canIncrement && prior !== null) {
+        const result = await scanCodexSessionIncremental(filePath, prior.offset, prior);
+        return { ...result, mode: 'incremental' };
+    }
+    const result = await scanCodexSessionIncremental(filePath, 0, freshCodexParserState());
+    return { ...result, mode: 'full' };
+}
+/**
+ * Parse the prior continuation blob for a changed Codex file into a usable
+ * {@link CodexParserState}, or null when there is none / it is unusable. A blob
+ * from a different serialization version is treated as absent so the file falls
+ * back to a clean FULL parse rather than resuming against a stale shape.
+ */
+function parsePriorCodexState(row) {
+    if (!row?.parserState)
+        return null;
+    try {
+        const parsed = JSON.parse(row.parserState);
+        if (parsed?.v !== 1 || typeof parsed.offset !== 'number')
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** Test seam: how many times the incremental (append-resume) branch was taken since the last reset. */
+let codexIncrementalScanCount = 0;
+/** Test seam: how many times a full (from-offset-0) Codex parse ran since the last reset. */
+let codexFullScanCount = 0;
+/** Test seam: read the (incremental, full) Codex parse counters. */
+export function __codexScanBranchCountsForTest() {
+    return { incremental: codexIncrementalScanCount, full: codexFullScanCount };
+}
+/** Test seam: reset the Codex parse-branch counters to observe a scan from a clean slate. */
+export function __resetCodexScanBranchCountsForTest() {
+    codexIncrementalScanCount = 0;
+    codexFullScanCount = 0;
+}
 /** Resolve the working directory for an OpenClaw agent from its workspace config. */
 function getOpenClawSessionCwd(agentId) {
     const workspace = agentId ? getOpenClawWorkspaceMap().get(agentId) : undefined;
@@ -2576,16 +3624,20 @@ async function scanKimiIncremental(onProgress) {
     if (changed.length === 0)
         return;
     onProgress?.({ agent: 'kimi', parsed: 0, total: changed.length });
+    // Bulk-fetch each changed session's prior wire-parse continuation (offset +
+    // counter bases). A session whose wire.jsonl grew resumes from the offset;
+    // everything else (cold start, truncation) full-parses from byte 0.
+    const priorStates = getParserStatesForPaths(changed.map(c => c.filePath));
     const scanEntries = [];
     const touched = [];
     const seen = new Set();
     let parsed = 0;
     for (const { filePath, scan } of changed) {
         try {
-            const result = readKimiMeta(filePath);
+            const result = readKimiMeta(filePath, priorStates.get(filePath));
             if (result && !seen.has(result.meta.id)) {
                 seen.add(result.meta.id);
-                scanEntries.push({ meta: result.meta, content: result.content, scan });
+                scanEntries.push({ meta: result.meta, content: result.content, scan, parserState: result.parserState });
             }
             else {
                 touched.push({ filePath, scan });
@@ -2601,7 +3653,7 @@ async function scanKimiIncremental(onProgress) {
     recordScans(touched);
 }
 /** Parse a single Kimi session state.json file to extract session metadata. */
-export function readKimiMeta(filePath) {
+export function readKimiMeta(filePath, priorRow) {
     let state;
     try {
         state = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
@@ -2626,7 +3678,7 @@ export function readKimiMeta(filePath) {
     const stat = safeStatSync(filePath);
     const timestamp = updatedAt || createdAt
         || (stat ? stat.mtime.toISOString() : new Date().toISOString());
-    const shortId = sessionId.replace(/^session_/, '').slice(0, 8);
+    const shortId = deriveShortId(sessionId, /^session_/);
     // Try to infer project from session directory path
     // ~/.kimi-code/sessions/<workdir_hash>/session_<uuid>/
     const workDirName = path.basename(path.dirname(sessionDir));
@@ -2637,8 +3689,11 @@ export function readKimiMeta(filePath) {
             project = parts.slice(0, -1).join('/');
         }
     }
-    // Parse wire.jsonl to extract message count and token usage
-    const { messageCount, tokenCount, outputTokens } = parseKimiWireMetrics(sessionDir);
+    // Parse wire.jsonl incrementally: resume from the persisted offset + counter
+    // bases when the wire grew, else full-parse from byte 0. The continuation is
+    // persisted on this session's state.json ledger row.
+    const prior = parsePriorKimiState(priorRow);
+    const { messageCount, tokenCount, outputTokens, newState } = parseKimiWireMetricsIncremental(sessionDir, prior);
     const meta = {
         id: sessionId,
         shortId,
@@ -2651,46 +3706,259 @@ export function readKimiMeta(filePath) {
         tokenCount: tokenCount > 0 ? tokenCount : undefined,
         outputTokens: outputTokens > 0 ? outputTokens : undefined,
     };
-    return { meta, content: lastPrompt || '' };
+    return { meta, content: lastPrompt || '', parserState: JSON.stringify(newState) };
 }
-/** Parse Kimi's wire.jsonl to extract message count and token usage.
- * TODO: optimize to stream (like scanClaudeSession) to avoid loading large files into memory.
- * For now, synchronous readFileSync matches the pattern of reading state.json and is acceptable
- * since session dirs are usually fresh in FS cache during incremental scans. */
-function parseKimiWireMetrics(sessionDir) {
+/** Fold one parsed Kimi wire event into the additive counters, in place. */
+function applyKimiWireEvent(acc, event) {
+    if (event.type === 'context.append_message') {
+        acc.messageCount++;
+    }
+    else if (event.type === 'usage.record' && event.usage) {
+        // Kimi usage structure: inputOther + output + inputCacheRead + inputCacheCreation
+        const u = event.usage;
+        acc.tokenCount += (u.inputOther || 0) + (u.output || 0) + (u.inputCacheRead || 0) + (u.inputCacheCreation || 0);
+        acc.outputTokens += (u.output || 0);
+    }
+}
+/**
+ * Incrementally parse Kimi's wire.jsonl for message-count and token counters,
+ * resuming from a persisted continuation instead of re-reading from byte 0 every
+ * scan. Returns the finalized counters and the next {@link KimiParserState} to
+ * persist (offset + the three counter bases).
+ *
+ * Same trailing-line discipline as {@link scanClaudeSessionIncremental}: read
+ * only the appended byte range from `prior.offset`, apply ONLY the run of
+ * newline-terminated lines (slice at the last `'\n'`), and advance the offset to
+ * `prior.offset + consumedBytes`. A complete-but-not-yet-terminated last record
+ * is DEFERRED to the next pass; because these counters are additive with no
+ * dedup, re-reading such a line would double-count it. FULL parse from byte 0
+ * (fresh counters) when there is no prior OR the file shrank below the stored
+ * offset (truncation/rewrite).
+ */
+export function parseKimiWireMetricsIncremental(sessionDir, prior) {
     const wirePath = path.join(sessionDir, 'agents', 'main', 'wire.jsonl');
-    let messageCount = 0;
-    let tokenCount = 0;
-    let outputTokens = 0;
-    if (!fs.existsSync(wirePath)) {
-        return { messageCount: 0, tokenCount: 0, outputTokens: 0 };
+    const stat = safeStatSync(wirePath);
+    if (!stat) {
+        // No wire.jsonl (yet): zero counters, offset 0 so a later append is a clean
+        // full parse.
+        return { messageCount: 0, tokenCount: 0, outputTokens: 0, newState: { v: 1, offset: 0, messageCount: 0, tokenCount: 0, outputTokens: 0 } };
+    }
+    // INCREMENTAL only when a usable prior exists AND the file grew past its
+    // offset; otherwise FULL from byte 0 with fresh counters (cold start OR the
+    // file shrank to/below the offset — a truncation/rewrite).
+    //
+    // No session-identity re-check is needed here (unlike Claude's
+    // claudeSessionIdentityAt / Codex's codexSessionIdentityAt, which guard against
+    // an in-place rewrite dropping a DIFFERENT session at the same path). A Kimi
+    // wire.jsonl is uniquely keyed by its session dir — `.../session_<uuid>/agents/
+    // main/wire.jsonl` (see readKimiMeta: sessionId is `session_<uuid>` and must
+    // start with `session_`) — and Kimi only ever APPENDS to that per-session log.
+    // The path therefore cannot host a different session's transcript, so a
+    // size-grew wire.jsonl is always the same session's append. (A truncation/
+    // rewrite — the only way its bytes could diverge — already shrinks it to/below
+    // the offset and takes the FULL branch above.)
+    const canIncrement = prior !== null && stat.size > prior.offset;
+    const fromOffset = canIncrement ? prior.offset : 0;
+    const acc = canIncrement
+        ? { messageCount: prior.messageCount, tokenCount: prior.tokenCount, outputTokens: prior.outputTokens }
+        : { messageCount: 0, tokenCount: 0, outputTokens: 0 };
+    let consumedBytes = 0;
+    let fd;
+    try {
+        // Read ONLY the appended byte range [fromOffset, stat.size) — not the whole
+        // file. readSync from an explicit position keeps this function synchronous
+        // (its callers are sync) while making the disk read + allocation scale with
+        // the appended delta, not total file size, matching scanCodexSessionIncremental
+        // / scanClaudeSessionIncremental. Bytes past the stat'd size are a concurrent
+        // append and are deferred to the next scan.
+        const bytesToRead = Math.max(0, stat.size - fromOffset);
+        const appended = Buffer.allocUnsafe(bytesToRead);
+        if (bytesToRead > 0) {
+            fd = fs.openSync(wirePath, 'r');
+            let read = 0;
+            while (read < bytesToRead) {
+                const n = fs.readSync(fd, appended, read, bytesToRead - read, fromOffset + read);
+                if (n <= 0)
+                    break;
+                read += n;
+            }
+            const chunk = read === bytesToRead ? appended : appended.subarray(0, read);
+            // Bytes up to AND INCLUDING the last '\n' are the committed, complete-line run.
+            const lastNl = chunk.lastIndexOf(0x0a);
+            consumedBytes = lastNl === -1 ? 0 : lastNl + 1;
+            if (consumedBytes > 0) {
+                for (const line of chunk.subarray(0, consumedBytes).toString('utf-8').split('\n')) {
+                    if (!line.trim())
+                        continue;
+                    try {
+                        applyKimiWireEvent(acc, JSON.parse(line));
+                    }
+                    catch {
+                        // Malformed line, skip
+                    }
+                }
+            }
+        }
     }
+    catch {
+        // If wire.jsonl can't be read, keep the accumulated counters (0s on a cold
+        // parse) — graceful degradation, matching the pre-incremental behavior.
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch { /* already closed / gone */ }
+        }
+    }
+    return {
+        messageCount: acc.messageCount,
+        tokenCount: acc.tokenCount,
+        outputTokens: acc.outputTokens,
+        newState: { v: 1, offset: fromOffset + consumedBytes, messageCount: acc.messageCount, tokenCount: acc.tokenCount, outputTokens: acc.outputTokens },
+    };
+}
+/**
+ * Parse the prior continuation blob for a changed Kimi session into a usable
+ * {@link KimiParserState}, or null when there is none / it is unusable. A blob
+ * from a different serialization version is treated as absent so the wire parse
+ * falls back to a clean FULL parse rather than resuming against a stale shape.
+ */
+function parsePriorKimiState(row) {
+    if (!row?.parserState)
+        return null;
     try {
-        const lines = fs.readFileSync(wirePath, 'utf-8').split('\n');
-        for (const line of lines) {
-            if (!line.trim())
+        const parsed = JSON.parse(row.parserState);
+        if (parsed?.v !== 1 || typeof parsed.offset !== 'number')
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Scan Grok sessions. Grok stores one directory per session under
+ * ~/.grok/sessions/<url-encoded-cwd>/<uuid>/, each holding a summary.json with
+ * structured metadata (id, cwd, title, timestamps, message count). Same
+ * dir-per-session (L3) shape as Kimi, so it walks two levels and gates the
+ * summary.json read through the scan ledger. Before this, Grok had a type slot
+ * and a placeholder parser but no scanner, so `agents sessions` never indexed it.
+ */
+async function scanGrokIncremental(onProgress) {
+    const currentVersion = await getCurrentAgentVersion('grok');
+    const filePaths = [];
+    for (const sessionsDir of getAgentSessionDirs('grok', 'sessions')) {
+        if (!fs.existsSync(sessionsDir))
+            continue;
+        let cwdDirNames;
+        try {
+            cwdDirNames = fs.readdirSync(sessionsDir);
+        }
+        catch {
+            continue;
+        }
+        for (const cwdDirName of cwdDirNames) {
+            const cwdDir = path.join(sessionsDir, cwdDirName);
+            const stat = safeStatSync(cwdDir);
+            if (!stat?.isDirectory())
                 continue;
+            let sessionNames;
             try {
-                const event = JSON.parse(line);
-                if (event.type === 'context.append_message') {
-                    messageCount++;
-                }
-                else if (event.type === 'usage.record' && event.usage) {
-                    // Kimi usage structure: inputOther + output + inputCacheRead + inputCacheCreation
-                    const u = event.usage;
-                    tokenCount += (u.inputOther || 0) + (u.output || 0) + (u.inputCacheRead || 0) + (u.inputCacheCreation || 0);
-                    outputTokens += (u.output || 0);
-                }
+                sessionNames = fs.readdirSync(cwdDir);
             }
             catch {
-                // Malformed line, skip
+                continue;
+            }
+            for (const sessionName of sessionNames) {
+                const summaryPath = path.join(cwdDir, sessionName, 'summary.json');
+                if (!fs.existsSync(summaryPath))
+                    continue;
+                filePaths.push(summaryPath);
+            }
+        }
+    }
+    const changed = filterChangedFiles(filePaths);
+    if (changed.length === 0)
+        return;
+    onProgress?.({ agent: 'grok', parsed: 0, total: changed.length });
+    const scanEntries = [];
+    const touched = [];
+    const seen = new Set();
+    let parsed = 0;
+    for (const { filePath, scan } of changed) {
+        try {
+            const result = readGrokMeta(filePath, currentVersion);
+            if (result && !seen.has(result.meta.id)) {
+                seen.add(result.meta.id);
+                scanEntries.push({ meta: result.meta, content: result.content, scan });
+            }
+            else {
+                touched.push({ filePath, scan });
             }
         }
+        catch {
+            touched.push({ filePath, scan });
+        }
+        parsed++;
+        onProgress?.({ agent: 'grok', parsed, total: changed.length });
+    }
+    upsertSessionsBatch(scanEntries);
+    recordScans(touched);
+}
+/** Parse a single Grok session summary.json into session metadata. */
+export function readGrokMeta(filePath, currentVersion) {
+    let summary;
+    try {
+        summary = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
     }
     catch {
-        // If wire.jsonl can't be read, return 0s (graceful degradation)
+        return null;
+    }
+    const sessionDir = path.dirname(filePath);
+    // The uuid directory name is the canonical id; summary.info.id mirrors it.
+    const sessionId = (typeof summary?.info?.id === 'string' && summary.info.id) || path.basename(sessionDir);
+    if (!sessionId)
+        return null;
+    const cwd = normalizeCwd(typeof summary?.info?.cwd === 'string' ? summary.info.cwd : '');
+    const topic = (typeof summary?.generated_title === 'string' && summary.generated_title.trim()) ||
+        (typeof summary?.session_summary === 'string' && summary.session_summary.trim()) ||
+        undefined;
+    // created_at is the session start; last_active_at/updated_at is the latest
+    // activity. Coerce timestamp to never-null (NOT NULL column) via the file mtime,
+    // matching how the other dir-per-session parsers (Kimi) fall back.
+    const createdAt = typeof summary?.created_at === 'string' ? summary.created_at : undefined;
+    const lastActivity = (typeof summary?.last_active_at === 'string' && summary.last_active_at) ||
+        (typeof summary?.updated_at === 'string' && summary.updated_at) ||
+        undefined;
+    const stat = safeStatSync(filePath);
+    const timestamp = createdAt || lastActivity || (stat ? stat.mtime.toISOString() : new Date().toISOString());
+    const messageCount = typeof summary?.num_chat_messages === 'number'
+        ? summary.num_chat_messages
+        : typeof summary?.num_messages === 'number'
+            ? summary.num_messages
+            : undefined;
+    // Grok records its managed home in summary.grok_home
+    // (…/versions/grok/<version>/home/.grok) — recover the version from it.
+    let embeddedVersion;
+    if (typeof summary?.grok_home === 'string') {
+        embeddedVersion = summary.grok_home.match(/versions\/grok\/([^/]+)\//)?.[1];
     }
-    return { messageCount, tokenCount, outputTokens };
+    const meta = {
+        id: sessionId,
+        shortId: deriveShortId(sessionId),
+        agent: 'grok',
+        timestamp,
+        lastActivity,
+        project: cwd ? path.basename(cwd) : undefined,
+        cwd: cwd || undefined,
+        filePath,
+        version: resolveSessionVersion('grok', filePath, embeddedVersion, currentVersion),
+        topic,
+        messageCount,
+    };
+    return { meta, content: topic || '' };
 }
 /** Parse a time filter string (relative like '7d' or ISO timestamp) into epoch milliseconds. */
 export function parseTimeFilter(input) {