vibe-usage-cli 0.0.0-stage → 0.1.1

package/build/core/sessions.js

@@ -0,0 +1,868 @@
+// Per-provider discovery and reading of local agent sessions for a project directory. Every
+// provider is filtered by the session's recorded working directory, so a session only ever
+// appears under the project it was started in. Formats were verified against real local
+// data (Claude Code JSONL, Codex rollout JSONL, Cursor CLI store.db, Antigravity
+// conversations/*.db + brain transcript); unknown fields are left empty instead of guessed.
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { pathToFileURL } from 'node:url';
+import zlib from 'node:zlib';
+import { CLAUDE_FILES, SYNTHETIC_MODEL } from "../providers/claude.js";
+import { CODEX_SESSIONS_DIR } from "../providers/codex.js";
+import { accountProfileDirs } from "../providers/profiles.js";
+import { AUTO, CLAUDE_PERMISSION_MODES, isOneOf, PROVIDER_IDS } from "../shared/catalog.js";
+import { attempt, attemptSync, field, isObject, JSON_LINES_EXTENSION, jsonLines, newestFiles, readHeadSync, readJsonSync, readTailSync, samePath } from "./files.js";
+import { redactSecrets } from "./redact.js";
+export function sessionSources(homeDir, accounts = []) {
+    return {
+        homeDir,
+        profiles: { claude: accountProfileDirs('claude', homeDir, accounts), codex: accountProfileDirs('codex', homeDir, accounts) }
+    };
+}
+// The recent conversation is bounded by turns, by turn length and in total.
+export const RECENT_TURNS = { count: 12, turnChars: 1500, totalChars: 12000 };
+const ELISION = '\n[…]\n';
+const SYSTEM_REMINDER = /<system-reminder>[\s\S]*?<\/system-reminder>/gi;
+// Secrets are removed from the whole message, before any clipping could cut one in half.
+function sanitizeText(text) {
+    return redactSecrets(text.replace(SYSTEM_REMINDER, '')).trim();
+}
+// Long turns keep their beginning (the request) and their end (the conclusion).
+function elide(text, limit) {
+    if (text.length <= limit)
+        return text;
+    const half = Math.floor((limit - ELISION.length) / 2);
+    return `${text.slice(0, half)}${ELISION}${text.slice(-half)}`;
+}
+// A folder a record names, compared with `b`.
+const namesPath = (a, b) => typeof a === 'string' && a !== '' && samePath(a, b);
+const text = (value) => (typeof value === 'string' ? value : '');
+const TITLE_MAX_LENGTH = 70;
+const TITLE_MIN_LENGTH = 4;
+const RECENT_FILES = 10;
+// Lines that open a prompt but say nothing about it: markup, mentions, rules, code fences.
+const NON_TITLE_PREFIXES = ['<', '@', '---', '```'];
+// First meaningful line of the first prompt, without Markdown heading or list markers.
+function titleFrom(prompt) {
+    const line = prompt
+        .split('\n')
+        .map(x => x.trim())
+        .find(x => x.length >= TITLE_MIN_LENGTH && !NON_TITLE_PREFIXES.some(prefix => x.startsWith(prefix)));
+    return line ? line.replace(/^[#\-*\s]+/, '').slice(0, TITLE_MAX_LENGTH) : '';
+}
+// A session list item, or null for sessions without a single user prompt. An empty title is
+// worded by the UI ("untitled session").
+function listEntry(transcript, { updatedAt, sizeBytes, title }) {
+    if (!transcript.turnCount)
+        return null;
+    return {
+        id: transcript.sessionId,
+        providerId: transcript.providerId,
+        title: title || transcript.sessionTitle,
+        updatedAt,
+        sizeBytes,
+        turnCount: transcript.turnCount,
+        model: transcript.sessionModel
+    };
+}
+const openDb = (file) => new DatabaseSync(file, { readOnly: true });
+function withDb(file, task) {
+    const db = openDb(file);
+    try {
+        return task(db);
+    }
+    finally {
+        db.close();
+    }
+}
+const bytes = (value) => (value instanceof Uint8Array ? Buffer.from(value) : null);
+function emptyTranscript(providerId, sessionId) {
+    return {
+        providerId,
+        sessionId,
+        sessionTitle: '',
+        sessionModel: '',
+        initialGoal: '',
+        lastUserMsg: '',
+        lastAssistantMsg: '',
+        turnCount: 0,
+        files: [],
+        recent: []
+    };
+}
+// Appends to the recent conversation, dropping the oldest turns beyond its bounds.
+function remember({ recent }, role, message) {
+    const last = recent.at(-1);
+    if (last?.role === role)
+        last.text = elide(`${last.text}\n\n${message}`, RECENT_TURNS.turnChars);
+    else
+        recent.push({ role, text: elide(message, RECENT_TURNS.turnChars) });
+    let total = recent.reduce((sum, turn) => sum + turn.text.length, 0);
+    while (recent.length > RECENT_TURNS.count || (recent.length > 1 && total > RECENT_TURNS.totalChars))
+        total -= recent.shift()?.text.length ?? 0;
+}
+function addUser(transcript, message) {
+    const clean = sanitizeText(message);
+    if (!clean)
+        return;
+    transcript.turnCount++;
+    if (!transcript.initialGoal)
+        transcript.initialGoal = clean;
+    if (!transcript.sessionTitle)
+        transcript.sessionTitle = titleFrom(clean);
+    transcript.lastUserMsg = clean;
+    remember(transcript, 'user', clean);
+}
+function addAssistant(transcript, message) {
+    const clean = sanitizeText(message);
+    if (!clean)
+        return;
+    transcript.lastAssistantMsg = clean;
+    remember(transcript, 'assistant', clean);
+}
+// Text parts of a content array whose part types are listed; a plain string as is.
+function contentText(content, types) {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    return content.map(part => (types.includes(String(field(part, 'type'))) ? text(field(part, 'text')) : '')).join('\n');
+}
+// ---------------------------------------------------------------- Claude Code
+function claudeProjectDirs(projectDir, { profiles }) {
+    const resolved = path.resolve(projectDir);
+    const slugs = new Set([resolved.replace(/[/\\:]/g, '-'), resolved.replace(/[^a-zA-Z0-9]/g, '-')]);
+    return profiles.claude
+        .flatMap(root => [...slugs].map(slug => path.join(root, CLAUDE_FILES.projects, slug)))
+        .filter(dir => fs.existsSync(dir));
+}
+const CLAUDE_TEXT_PARTS = ['text'];
+function claudeFilePath(record) {
+    const content = field(record.message, 'content');
+    const edited = Array.isArray(content) ? content.map(part => field(field(part, 'input'), 'file_path')).find(Boolean) : undefined;
+    return field(record.toolUseResult, 'filePath') ?? edited;
+}
+// Parsed results per file, reused until the file changes.
+function mtimeMemo() {
+    const memo = new Map();
+    return async (file, compute) => {
+        const { mtimeMs } = await fsp.stat(file);
+        const hit = memo.get(file);
+        if (hit?.mtimeMs === mtimeMs)
+            return hit.value;
+        const value = await compute();
+        memo.set(file, { mtimeMs, value });
+        return value;
+    };
+}
+// Listing parses every transcript of the project, which can be hundreds of megabytes.
+const claudeMemo = mtimeMemo();
+const readClaudeFile = (file, id) => claudeMemo(file, () => parseClaudeFile(file, id));
+async function parseClaudeFile(file, id) {
+    const transcript = emptyTranscript('claude', id);
+    const files = new Set();
+    let aiTitle = '';
+    for (const record of jsonLines(await fsp.readFile(file, 'utf8'))) {
+        const { message } = record;
+        const content = field(message, 'content');
+        const model = field(message, 'model');
+        if (record.type === 'ai-title' && typeof record.aiTitle === 'string')
+            aiTitle = record.aiTitle;
+        // Messages Claude Code generates itself (API errors, limit notices) are not the model's.
+        const synthetic = Boolean(record.isApiErrorMessage) || model === SYNTHETIC_MODEL;
+        if (typeof model === 'string' && !synthetic)
+            transcript.sessionModel = model;
+        // Tool results are user-role records too; only real prompts count.
+        const toolResults = Array.isArray(content) && content.every(part => field(part, 'type') === 'tool_result');
+        // Older versions kept subagent threads (sidechains) in the same file; they are not the
+        // conversation with the user.
+        const mainThread = content && !record.isSidechain;
+        if (record.type === 'user' && mainThread && !record.isMeta && !toolResults)
+            addUser(transcript, contentText(content, CLAUDE_TEXT_PARTS));
+        if (record.type === 'assistant' && mainThread && !synthetic)
+            addAssistant(transcript, contentText(content, CLAUDE_TEXT_PARTS));
+        const edited = claudeFilePath(record);
+        if (typeof edited === 'string')
+            files.add(edited);
+    }
+    if (aiTitle)
+        transcript.sessionTitle = aiTitle;
+    transcript.files = [...files].slice(-RECENT_FILES);
+    return transcript;
+}
+async function listClaude(projectDir, sources) {
+    const sessions = [];
+    for (const dir of claudeProjectDirs(projectDir, sources)) {
+        for (const name of await fsp.readdir(dir).catch(() => [])) {
+            if (!name.endsWith(JSON_LINES_EXTENSION))
+                continue;
+            const file = path.join(dir, name);
+            sessions.push(await attempt(async () => {
+                const stat = await fsp.stat(file);
+                return listEntry(await readClaudeFile(file, path.basename(name, JSON_LINES_EXTENSION)), {
+                    updatedAt: stat.mtimeMs,
+                    sizeBytes: stat.size
+                });
+            }));
+        }
+    }
+    return sessions;
+}
+async function readClaude(projectDir, sources, id) {
+    for (const dir of claudeProjectDirs(projectDir, sources)) {
+        const file = path.join(dir, `${id}${JSON_LINES_EXTENSION}`);
+        if (fs.existsSync(file))
+            return readClaudeFile(file, id);
+    }
+    return null;
+}
+// ---------------------------------------------------------------------- Codex
+const ROLLOUT_FILE = /^rollout-.*\.jsonl(\.zst)?$/;
+// A session's own rollout is named after its id; fork snapshots append `_<childId>`.
+const OWN_ROLLOUT = /^rollout-.*-([0-9a-f-]{36})\.jsonl(\.zst)?$/i;
+const isCompressed = (file) => file.endsWith('.zst');
+// Codex stores recent rollouts as .jsonl and compresses older ones to .jsonl.zst.
+function walkRollouts(dir) {
+    const entries = attemptSync(() => fs.readdirSync(dir, { withFileTypes: true })) ?? [];
+    return entries.flatMap(entry => {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory())
+            return walkRollouts(full);
+        return entry.isFile() && ROLLOUT_FILE.test(entry.name) ? [full] : [];
+    });
+}
+const MAX_META_LINE_BYTES = 1024 * 1024;
+// The first line of a rollout (its session_meta record), streamed so that a large or
+// compressed file is never read whole. Resolves to '' when there is no complete line.
+function readFirstLine(file) {
+    return new Promise(resolve => {
+        const input = fs.createReadStream(file);
+        const stream = isCompressed(file) ? input.pipe(zlib.createZstdDecompress()) : input;
+        const chunks = [];
+        let size = 0;
+        const finish = (line) => {
+            input.destroy();
+            stream.destroy();
+            resolve(line);
+        };
+        stream.on('data', (chunk) => {
+            const newline = chunk.indexOf(0x0a);
+            chunks.push(newline === -1 ? chunk : chunk.subarray(0, newline));
+            size += chunk.length;
+            if (newline !== -1)
+                finish(Buffer.concat(chunks).toString('utf8'));
+            else if (size > MAX_META_LINE_BYTES)
+                finish('');
+        });
+        stream.on('end', () => {
+            finish('');
+        });
+        stream.on('error', () => {
+            finish('');
+        });
+        input.on('error', () => {
+            finish('');
+        });
+    });
+}
+async function readRollout(file) {
+    const raw = await fsp.readFile(file);
+    return (isCompressed(file) ? zlib.zstdDecompressSync(raw) : raw).toString('utf8');
+}
+// The first record is session_meta. Subagent threads (Guardian reviews, spawned workers) have
+// an object `source` and are skipped.
+const codexMetaMemo = mtimeMemo();
+function readCodexMeta(file) {
+    return codexMetaMemo(file, async () => {
+        const [record] = jsonLines(await readFirstLine(file));
+        const payload = record?.type === 'session_meta' ? record.payload : undefined;
+        const id = field(payload, 'id');
+        return typeof id === 'string'
+            ? {
+                id,
+                cwd: field(payload, 'cwd'),
+                subagent: Boolean(field(field(payload, 'source'), 'subagent')),
+                headless: field(payload, 'source') === 'exec'
+            }
+            : null;
+    });
+}
+const CODEX_TEXT_PARTS = ['input_text', 'output_text'];
+// Injected context (AGENTS.md, environment, skills) is sent as user-role messages.
+function isCodexInjected(message) {
+    const start = message.trimStart();
+    return start.startsWith('<') || start.startsWith('# AGENTS.md instructions');
+}
+async function readCodexFile(file, id) {
+    const transcript = emptyTranscript('codex', id);
+    for (const record of jsonLines(await readRollout(file))) {
+        const payload = isObject(record.payload) ? record.payload : {};
+        const settingsModel = field(payload.thread_settings, 'model');
+        if (record.type === 'turn_context' && typeof payload.model === 'string')
+            transcript.sessionModel = payload.model;
+        if (record.type === 'event_msg' && payload.type === 'thread_settings_applied' && typeof settingsModel === 'string')
+            transcript.sessionModel = settingsModel;
+        if (record.type === 'response_item' && payload.type === 'message') {
+            const message = Array.isArray(payload.content) ? contentText(payload.content, CODEX_TEXT_PARTS) : '';
+            if (payload.role === 'user' && !isCodexInjected(message))
+                addUser(transcript, message);
+            if (payload.role === 'assistant')
+                addAssistant(transcript, message);
+        }
+    }
+    return transcript;
+}
+function codexThreadNames({ profiles }) {
+    const names = new Map();
+    for (const root of profiles.codex) {
+        const index = attemptSync(() => fs.readFileSync(path.join(root, 'session_index.jsonl'), 'utf8')) ?? '';
+        for (const { id, thread_name: name } of jsonLines(index))
+            if (typeof id === 'string' && typeof name === 'string' && name)
+                names.set(id, name);
+    }
+    return names;
+}
+// Fork snapshots start with the parent's session_meta; a session's own rollout is preferred.
+async function findCodexRollouts(projectDir, { profiles }) {
+    const byId = new Map();
+    for (const file of profiles.codex.flatMap(root => walkRollouts(path.join(root, CODEX_SESSIONS_DIR)))) {
+        const meta = await attempt(() => readCodexMeta(file));
+        if (!meta || meta.subagent || !namesPath(meta.cwd, projectDir))
+            continue;
+        const own = OWN_ROLLOUT.exec(path.basename(file))?.[1] === meta.id;
+        const previous = byId.get(meta.id);
+        if (!previous || (own && !previous.own))
+            byId.set(meta.id, { file, id: meta.id, own });
+    }
+    return [...byId.values()].map(({ file, id }) => ({ file, id }));
+}
+// Turn counts need a full parse; reuse it until the rollout changes.
+const codexSummaryMemo = mtimeMemo();
+async function listCodex(projectDir, sources) {
+    const names = codexThreadNames(sources);
+    const sessions = [];
+    for (const { file, id } of await findCodexRollouts(projectDir, sources)) {
+        sessions.push(await attempt(async () => {
+            const stat = await fsp.stat(file);
+            const transcript = await codexSummaryMemo(file, () => readCodexFile(file, id));
+            return listEntry(transcript, { updatedAt: stat.mtimeMs, sizeBytes: stat.size, title: names.get(id) });
+        }));
+    }
+    return sessions;
+}
+async function readCodex(projectDir, sources, id) {
+    const hit = (await findCodexRollouts(projectDir, sources)).find(rollout => rollout.id === id);
+    if (!hit)
+        return null;
+    const transcript = await readCodexFile(hit.file, id);
+    const name = codexThreadNames(sources).get(id);
+    if (name)
+        transcript.sessionTitle = name;
+    return transcript;
+}
+// ----------------------------------------------------------------- Cursor CLI
+// ~/.cursor/chats/<hash>/<chatId>/{meta.json,store.db}. meta.json records cwd; store.db holds
+// JSON message blobs ({"role":...}) in insertion (rowid) order.
+const CURSOR_DEFAULT_CHAT_NAME = 'New Agent';
+const JSON_OBJECT_START = 0x7b; // '{'; other blobs are internal tree nodes
+const HEX = /^[0-9a-f]+$/i;
+const USER_QUERY = /<user_query>\s*([\s\S]*?)\s*<\/user_query>/;
+const CURSOR_TEXT_PARTS = ['text'];
+const subdirectories = (dir) => (attemptSync(() => fs.readdirSync(dir, { withFileTypes: true })) ?? []).filter(entry => entry.isDirectory());
+function cursorChatDirs(projectDir, homeDir) {
+    const root = path.join(homeDir, '.cursor', 'chats');
+    return subdirectories(root).flatMap(workspace => subdirectories(path.join(root, workspace.name)).flatMap(chat => {
+        const dir = path.join(root, workspace.name, chat.name);
+        const meta = readJsonSync(path.join(dir, 'meta.json'));
+        if (!isObject(meta) || meta.hasConversation === false || !namesPath(meta.cwd, projectDir))
+            return [];
+        return [{ id: chat.name, dir, updatedAtMs: meta.updatedAtMs }];
+    }));
+}
+function readCursorChat(dir, id) {
+    const transcript = emptyTranscript('cursor', id);
+    withDb(path.join(dir, 'store.db'), db => {
+        // The chat record is JSON, stored hex-encoded by current CLI versions.
+        const raw = String(db.prepare("SELECT value FROM meta WHERE key = '0'").get()?.value ?? '');
+        const chat = attemptSync(() => JSON.parse(HEX.test(raw) ? Buffer.from(raw, 'hex').toString('utf8') : raw));
+        const name = field(chat, 'name');
+        if (typeof name === 'string' && name && name !== CURSOR_DEFAULT_CHAT_NAME)
+            transcript.sessionTitle = name;
+        for (const row of db.prepare('SELECT data FROM blobs ORDER BY rowid').all()) {
+            const blob = bytes(row.data);
+            if (blob?.[0] !== JSON_OBJECT_START)
+                continue;
+            const message = attemptSync(() => JSON.parse(blob.toString('utf8')));
+            const content = contentText(field(message, 'content'), CURSOR_TEXT_PARTS);
+            const role = field(message, 'role');
+            const query = role === 'user' ? USER_QUERY.exec(content)?.[1] : undefined;
+            if (query !== undefined)
+                addUser(transcript, query);
+            if (role === 'assistant')
+                addAssistant(transcript, content);
+        }
+    });
+    return transcript;
+}
+function listCursor(projectDir, { homeDir }) {
+    return cursorChatDirs(projectDir, homeDir).map(({ id, dir, updatedAtMs }) => attemptSync(() => {
+        const stat = fs.statSync(path.join(dir, 'store.db'));
+        const updatedAt = typeof updatedAtMs === 'number' && updatedAtMs ? updatedAtMs : stat.mtimeMs;
+        return listEntry(readCursorChat(dir, id), { updatedAt, sizeBytes: stat.size });
+    }));
+}
+function readCursor(projectDir, { homeDir }, id) {
+    const hit = cursorChatDirs(projectDir, homeDir).find(chat => chat.id === id);
+    return hit ? readCursorChat(hit.dir, id) : null;
+}
+// ---------------------------------------------------------------- Antigravity
+// conversations/<id>.db is SQLite; trajectory_metadata_blob carries the workspace as a
+// file:// URI. The readable transcript lives in brain/<id>/.system_generated/logs.
+const antigravityRoot = (homeDir) => path.join(homeDir, '.gemini', 'antigravity-ide');
+const WINDOWS_DRIVE_URI = /^file:\/\/\/([A-Za-z]):(.*)$/;
+const PROTOBUF_TAG_START = 0x20; // bytes below are control bytes: the next protobuf tag
+const SLASH = 0x2f;
+function workspaceUris(projectDir) {
+    const href = pathToFileURL(path.resolve(projectDir)).href.replace(/\/$/, '');
+    const uris = new Set([href]);
+    // VS Code-style URIs lower-case and percent-encode the Windows drive colon.
+    const [, drive, rest] = WINDOWS_DRIVE_URI.exec(href) ?? [];
+    if (drive) {
+        uris.add(`file:///${drive.toLowerCase()}%3A${rest}`);
+        uris.add(`file:///${drive.toLowerCase()}:${rest}`);
+    }
+    return [...uris].map(uri => Buffer.from(uri));
+}
+// The URI is protobuf-embedded; a match must not continue as a longer path segment.
+function blobHasWorkspace(blob, uris) {
+    const endsAt = (at) => {
+        const next = blob[at];
+        return next === undefined || next < PROTOBUF_TAG_START;
+    };
+    return uris.some(uri => {
+        for (let at = blob.indexOf(uri); at !== -1; at = blob.indexOf(uri, at + 1)) {
+            const end = at + uri.length;
+            // The URI ends at a control byte, optionally after one '/'.
+            if (endsAt(end) || (blob[end] === SLASH && endsAt(end + 1)))
+                return true;
+        }
+        return false;
+    });
+}
+// Best effort: the latest generation record stores the model display name as a
+// length-prefixed string under protobuf field 21 (tag 0xaa 0x01).
+const MODEL_NAME_TAG = Buffer.from([0xaa, 0x01]);
+const MODEL_NAME_MAX_LENGTH = 80;
+const MODEL_NAME = /^(Gemini|Claude|GPT)[\w .()-]*$/;
+function antigravityModel(db) {
+    const blob = bytes(attemptSync(() => db.prepare('SELECT data FROM gen_metadata ORDER BY idx DESC LIMIT 1').get())?.data);
+    if (!blob)
+        return '';
+    let found = '';
+    for (let i = blob.indexOf(MODEL_NAME_TAG); i !== -1; i = blob.indexOf(MODEL_NAME_TAG, i + 1)) {
+        const length = blob[i + MODEL_NAME_TAG.length];
+        if (!length || length > MODEL_NAME_MAX_LENGTH)
+            continue;
+        const start = i + MODEL_NAME_TAG.length + 1;
+        const name = blob.toString('utf8', start, start + length);
+        if (MODEL_NAME.test(name))
+            found = name;
+    }
+    return found;
+}
+function antigravityConversations(projectDir, homeDir) {
+    const dir = path.join(antigravityRoot(homeDir), 'conversations');
+    const uris = workspaceUris(projectDir);
+    return (attemptSync(() => fs.readdirSync(dir)) ?? [])
+        .filter(name => name.endsWith('.db'))
+        .flatMap(name => {
+        const file = path.join(dir, name);
+        const conversation = attemptSync(() => withDb(file, db => {
+            const rows = db.prepare('SELECT data FROM trajectory_metadata_blob').all();
+            const inProject = rows.some(row => {
+                const blob = bytes(row.data);
+                return blob !== null && blobHasWorkspace(blob, uris);
+            });
+            return inProject ? { id: path.basename(name, '.db'), file, model: antigravityModel(db) } : null;
+        }));
+        return conversation ? [conversation] : [];
+    });
+}
+const MARKUP = /<[^>]+>/g;
+async function readAntigravityTranscript(homeDir, id, model) {
+    const transcript = emptyTranscript('antigravity', id);
+    transcript.sessionModel = model;
+    const file = path.join(antigravityRoot(homeDir), 'brain', id, '.system_generated', 'logs', 'transcript.jsonl');
+    for (const { type, content } of jsonLines(await fsp.readFile(file, 'utf8').catch(() => ''))) {
+        if (typeof content !== 'string')
+            continue;
+        if (type === 'USER_INPUT')
+            addUser(transcript, content.replace(MARKUP, ''));
+        if (type === 'PLANNER_RESPONSE')
+            addAssistant(transcript, content);
+    }
+    return transcript;
+}
+async function listAntigravity(projectDir, { homeDir }) {
+    const sessions = [];
+    for (const { id, file, model } of antigravityConversations(projectDir, homeDir)) {
+        sessions.push(await attempt(async () => {
+            const stat = await fsp.stat(file);
+            return listEntry(await readAntigravityTranscript(homeDir, id, model), { updatedAt: stat.mtimeMs, sizeBytes: stat.size });
+        }));
+    }
+    return sessions;
+}
+async function readAntigravity(projectDir, { homeDir }, id) {
+    const hit = antigravityConversations(projectDir, homeDir).find(conversation => conversation.id === id);
+    return hit ? readAntigravityTranscript(homeDir, id, hit.model) : null;
+}
+const matchesSession = (session, identity) => !identity || (samePath(session.projectDir, identity.projectDir) && session.sessionId === identity.sessionId);
+// Claude Code writes the working directory into its records; it is near the top of the file.
+const CWD_SCAN_BYTES = 256 * 1024;
+const mtime = (file) => attemptSync(() => fs.statSync(file).mtimeMs) ?? 0;
+const isFileSync = (file) => attemptSync(() => fs.statSync(file).isFile()) ?? false;
+export async function recentSessionModel(session) {
+    // The model is in the last turns; a transcript can be hundreds of MB, so only its end is read.
+    if (session.providerId === 'claude')
+        return claudeSessionMode(session.file).model ?? '';
+    if (session.providerId === 'codex')
+        return (await readCodexFile(session.file, session.sessionId)).sessionModel;
+    return session.model ?? '';
+}
+// The folder a Claude Code session belongs to, as Claude Code itself attributes it: where it was
+// relocated to (a worktree), else where it started. The `cwd` of later records follows the
+// agent's shell and can point anywhere inside the project.
+export function claudeProjectDir(file) {
+    const relocated = [...jsonLines(readTailSync(file, TAIL_SCAN_BYTES))]
+        .filter(record => record.type === 'relocated' && typeof record.relocatedCwd === 'string' && record.relocatedCwd)
+        .at(-1);
+    if (typeof relocated?.relocatedCwd === 'string')
+        return relocated.relocatedCwd;
+    const head = [...jsonLines(readHeadSync(file, CWD_SCAN_BYTES))].find(record => typeof record.cwd === 'string' && record.cwd);
+    return typeof head?.cwd === 'string' ? head.cwd : null;
+}
+export function latestClaudeSession(root, identity) {
+    const projects = path.join(root, CLAUDE_FILES.projects);
+    // A known session is found by its file name; otherwise each project's newest transcript is a
+    // candidate. Profiles can hold thousands of transcripts, so no others are read.
+    const files = subdirectories(projects)
+        .flatMap(dir => {
+        const folder = path.join(projects, dir.name);
+        if (!identity)
+            return newestFiles(folder, JSON_LINES_EXTENSION).slice(0, 1);
+        // An id is a file name, never a path.
+        if (path.basename(identity.sessionId) !== identity.sessionId)
+            return [];
+        return [path.join(folder, `${identity.sessionId}${JSON_LINES_EXTENSION}`)].filter(isFileSync);
+    })
+        .map(file => ({ file, updatedAt: mtime(file) }))
+        .sort((a, b) => b.updatedAt - a.updatedAt)
+        .map(entry => entry.file);
+    for (const file of files) {
+        const projectDir = claudeProjectDir(file);
+        if (!projectDir)
+            continue;
+        const session = {
+            providerId: 'claude',
+            sessionId: path.basename(file, JSON_LINES_EXTENSION),
+            projectDir,
+            updatedAt: mtime(file),
+            file
+        };
+        if (matchesSession(session, identity))
+            return session;
+    }
+    return null;
+}
+// A Claude Code session of the profile by its id alone, in whichever project folder it is kept
+// (a worktree's sessions are kept under its repository's folder).
+export function claudeSessionById(root, sessionId) {
+    // An id is a file name, never a path.
+    if (path.basename(sessionId) !== sessionId)
+        return null;
+    const projects = path.join(root, CLAUDE_FILES.projects);
+    const file = subdirectories(projects)
+        .map(dir => path.join(projects, dir.name, `${sessionId}${JSON_LINES_EXTENSION}`))
+        .filter(isFileSync)
+        .sort((a, b) => mtime(b) - mtime(a))[0];
+    const projectDir = file ? claudeProjectDir(file) : null;
+    return file && projectDir ? { providerId: 'claude', sessionId, projectDir, updatedAt: mtime(file), file } : null;
+}
+export async function latestCodexSession(root, identity) {
+    const files = walkRollouts(path.join(root, CODEX_SESSIONS_DIR))
+        .map(file => ({ file, updatedAt: mtime(file) }))
+        .sort((a, b) => b.updatedAt - a.updatedAt);
+    for (const { file, updatedAt } of files) {
+        // A rollout named `<id>_<other>` still names its session by its metadata.
+        const meta = await attempt(() => readCodexMeta(file));
+        if (!meta || meta.subagent || typeof meta.cwd !== 'string' || !meta.cwd)
+            continue;
+        const session = { providerId: 'codex', sessionId: meta.id, projectDir: meta.cwd, updatedAt, file };
+        if (matchesSession(session, identity))
+            return session;
+    }
+    return null;
+}
+export function latestCursorSession(homeDir, identity) {
+    const root = path.join(homeDir, '.cursor', 'chats');
+    const chats = subdirectories(root).flatMap(workspace => subdirectories(path.join(root, workspace.name)).flatMap(chat => {
+        const dir = path.join(root, workspace.name, chat.name);
+        const meta = readJsonSync(path.join(dir, 'meta.json'));
+        if (!isObject(meta) || meta.hasConversation === false || typeof meta.cwd !== 'string' || !meta.cwd)
+            return [];
+        const file = path.join(dir, 'store.db');
+        const updatedAt = typeof meta.updatedAtMs === 'number' && meta.updatedAtMs ? meta.updatedAtMs : mtime(file);
+        return [{ providerId: 'cursor', sessionId: chat.name, projectDir: meta.cwd, updatedAt, file }];
+    }));
+    return chats.filter(s => matchesSession(s, identity)).sort((a, b) => b.updatedAt - a.updatedAt)[0] ?? null;
+}
+const TAIL_SCAN_BYTES = 512 * 1024;
+// Every usage-limit stop Claude Code writes carries this error (checked on 2026-10-19: all 73
+// in this machine's transcripts, Claude Code 2.1.294 to 2.1.302); its wording is not read.
+const CLAUDE_LIMIT_ERROR = 'usage_limit_reached';
+const CODEX_LIMIT_ERROR = 'usage_limit_exceeded';
+const timestamp = (value) => (typeof value === 'string' ? Date.parse(value) : NaN);
+// Claude Code: the session's stop at the usage limit (a synthetic main-thread assistant record),
+// standing until a reply came after it. A prompt alone is waiting, not going on: the user's,
+// or a queued notice (a background task's) that Claude Code takes while it holds the session
+// for the reset, hours before anything is answered. A reply that is another kind of error
+// (overloaded, the network) clears the stop too: the session went on, and stopped on something
+// else. `headless` marks a run started by a program (`claude -p`, the Agent SDK), not a person
+// in a terminal.
+export function claudeLimitStop(file) {
+    let stop = null;
+    for (const record of jsonLines(readTailSync(file, TAIL_SCAN_BYTES))) {
+        if (record.type !== 'assistant' || record.isSidechain || record.isMeta)
+            continue;
+        stop = record.isApiErrorMessage === true && record.apiError === CLAUDE_LIMIT_ERROR ? record : null;
+    }
+    const stoppedAt = timestamp(stop?.timestamp);
+    if (!stop || !Number.isFinite(stoppedAt))
+        return null;
+    const headless = typeof stop.entrypoint === 'string' && stop.entrypoint.startsWith('sdk-');
+    const cwd = claudeProjectDir(file);
+    return cwd ? { stoppedAt, cwd, headless } : null;
+}
+// How a Claude Code session was last running, so that it goes on the same way under another
+// profile: the model it used and its permission mode. Only the end of the transcript is read.
+export function claudeSessionMode(file) {
+    let model;
+    let permissionMode;
+    for (const record of jsonLines(readTailSync(file, TAIL_SCAN_BYTES))) {
+        if (record.isSidechain)
+            continue;
+        const used = field(record.message, 'model');
+        if (typeof used === 'string' && used !== SYNTHETIC_MODEL && !record.isApiErrorMessage)
+            model = used;
+        if (isOneOf(CLAUDE_PERMISSION_MODES, record.permissionMode))
+            permissionMode = record.permissionMode;
+    }
+    return { ...(model ? { model } : {}), ...(permissionMode ? { permissionMode } : {}) };
+}
+const TASK_OUTPUT = /Output is being written to: (.+?\.output)/;
+const TASK_FINISHED = /<task-id>([^<]+)<\/task-id>/g;
+// Tools that end a background command without a task notification, and the input naming it.
+const TASK_STOPPERS = { TaskStop: 'task_id', KillShell: 'shell_id' };
+// The message Claude Code adds when a background command finishes.
+const TASK_NOTIFICATION = '<task-notification>';
+// Only lines carrying one of these can start or end a background command, or name one that
+// may be moved there; the rest of a transcript (most of it) is never parsed.
+const TASK_MARKERS = ['"command":', 'backgroundTaskId', TASK_NOTIFICATION, ...Object.keys(TASK_STOPPERS).map(name => `"${name}"`)];
+const MAX_TASK_SCANS = 50;
+// Commands called but not yet answered, kept by tool use id; a result is not parsed unless it
+// names a task, so the newest calls are kept and the rest let go.
+const MAX_PENDING_COMMANDS = 64;
+// Transcripts only grow, so each is read once and then from where it was left; one that
+// shrank or was replaced is read again.
+const taskScans = new Map();
+function scanTaskLine(scan, line) {
+    if (!TASK_MARKERS.some(marker => line.includes(marker)))
+        return;
+    if (line.includes(TASK_NOTIFICATION))
+        for (const [, id] of line.matchAll(TASK_FINISHED))
+            if (id)
+                scan.finished.add(id);
+    const [record] = jsonLines(line);
+    if (!record || record.isSidechain)
+        return;
+    const content = field(record.message, 'content');
+    for (const part of Array.isArray(content) ? content : []) {
+        const type = field(part, 'type');
+        const input = field(part, 'input');
+        const stopper = TASK_STOPPERS[String(field(part, 'name'))];
+        const stopped = stopper ? field(input, stopper) : undefined;
+        if (type === 'tool_use' && typeof stopped === 'string')
+            scan.finished.add(stopped);
+        // Any command may end up in the background: asked for it, or moved there by Claude Code when
+        // it ran past its time. Its text is kept until its result says which.
+        const command = field(input, 'description') ?? field(input, 'command');
+        if (type === 'tool_use' && typeof field(input, 'command') === 'string' && typeof command === 'string') {
+            scan.commands.set(String(field(part, 'id')), command);
+            for (const oldest of [...scan.commands.keys()].slice(0, Math.max(0, scan.commands.size - MAX_PENDING_COMMANDS)))
+                scan.commands.delete(oldest);
+        }
+        const id = field(record.toolUseResult, 'backgroundTaskId');
+        if (type !== 'tool_result' || typeof id !== 'string')
+            continue;
+        const useId = String(field(part, 'tool_use_id'));
+        scan.started.set(id, {
+            id,
+            command: scan.commands.get(useId) ?? '',
+            outputFile: TASK_OUTPUT.exec(contentText(field(part, 'content'), CLAUDE_TEXT_PARTS))?.[1] ?? null,
+            startedAt: timestamp(record.timestamp)
+        });
+        scan.commands.delete(useId);
+    }
+}
+// Reads the bytes after `scan.size` up to the last complete line, a chunk at a time.
+async function readNewLines(file, scan, size) {
+    let pending = [];
+    let consumed = scan.size;
+    // Without an encoding the stream yields buffers; its typings say `any`.
+    for await (const read of fs.createReadStream(file, { start: scan.size, end: size - 1 })) {
+        const chunk = read;
+        if (!Buffer.isBuffer(chunk))
+            continue;
+        const newline = chunk.lastIndexOf(0x0a);
+        if (newline < 0) {
+            pending.push(chunk);
+            continue;
+        }
+        const lines = Buffer.concat([...pending, chunk.subarray(0, newline + 1)]);
+        for (const line of lines.toString('utf8').split('\n'))
+            scanTaskLine(scan, line);
+        consumed += lines.length;
+        pending = [chunk.subarray(newline + 1)];
+    }
+    scan.size = consumed;
+}
+// The session's background commands still running as far as its transcript knows: started
+// (the tool result names the task) and neither notified as finished nor stopped since. They
+// belong to the process that started them, which alone is notified when they finish.
+export async function claudeBackgroundTasks(file) {
+    const stat = await fsp.stat(file);
+    const identity = `${stat.ino}:${stat.birthtimeMs}`;
+    const known = taskScans.get(file);
+    const scan = known?.identity === identity && known.size <= stat.size
+        ? known
+        : { size: 0, identity, commands: new Map(), started: new Map(), finished: new Set() };
+    if (stat.size > scan.size)
+        await readNewLines(file, scan, stat.size);
+    taskScans.delete(file);
+    taskScans.set(file, scan);
+    for (const oldest of [...taskScans.keys()].slice(0, Math.max(0, taskScans.size - MAX_TASK_SCANS)))
+        taskScans.delete(oldest);
+    return [...scan.started.values()].filter(task => !scan.finished.has(task.id));
+}
+// When a Claude Code transcript was last written to, by its records' own times (a file's times
+// can change without a write). NaN when it holds none.
+export function claudeLastWrittenAt(file) {
+    let last = Number.NaN;
+    for (const record of jsonLines(readTailSync(file, TAIL_SCAN_BYTES))) {
+        const at = timestamp(record.timestamp);
+        if (Number.isFinite(at) && !(at <= last))
+            last = at;
+    }
+    return last;
+}
+const writeMemo = new Map();
+export function claudeTranscriptWrite(file) {
+    const stat = attemptSync(() => fs.statSync(file));
+    if (!stat)
+        return null;
+    const hit = writeMemo.get(file);
+    if (hit?.size === stat.size && hit.mtimeMs === stat.mtimeMs)
+        return hit.value;
+    const value = { lastRecordAt: claudeLastWrittenAt(file), size: stat.size };
+    writeMemo.set(file, { size: stat.size, mtimeMs: stat.mtimeMs, value });
+    return value;
+}
+// Claude Code: the last main-thread message is the model's reply that ended its turn, so the
+// session waits for the user.
+export function claudeTurnEnded(file) {
+    const messages = [...jsonLines(readTailSync(file, TAIL_SCAN_BYTES))].filter(record => (record.type === 'user' || record.type === 'assistant') && !record.isSidechain && !record.isMeta);
+    const last = messages.at(-1);
+    return last?.type === 'assistant' && !last.isApiErrorMessage && field(last.message, 'stop_reason') === 'end_turn';
+}
+// Codex: the last turn completed with the usage-limit error, and no turn started since.
+export function codexLimitStop(file) {
+    if (isCompressed(file))
+        return null;
+    let stoppedAt = null;
+    for (const record of jsonLines(readTailSync(file, TAIL_SCAN_BYTES))) {
+        const type = record.type === 'event_msg' ? field(record.payload, 'type') : undefined;
+        if (type === 'task_started')
+            stoppedAt = null;
+        if (type === 'task_complete')
+            stoppedAt = field(field(record.payload, 'error'), 'codex_error_info') === CODEX_LIMIT_ERROR ? timestamp(record.timestamp) : null;
+    }
+    return stoppedAt !== null && Number.isFinite(stoppedAt) ? { stoppedAt } : null;
+}
+// Sessions of a Claude Code profile written in the last `maxAgeMs` whose agent stopped at the
+// usage limit, newest first. Headless runs are left to the program that started them: it sees
+// the error itself, and opening each one in a terminal would bury the user's own sessions.
+export function claudeLimitStops(root, now, maxAgeMs) {
+    const projects = path.join(root, CLAUDE_FILES.projects);
+    return subdirectories(projects)
+        .flatMap(dir => newestFiles(path.join(projects, dir.name), JSON_LINES_EXTENSION))
+        .map(file => ({ file, updatedAt: mtime(file) }))
+        .filter(({ updatedAt }) => now - updatedAt <= maxAgeMs)
+        .flatMap(({ file, updatedAt }) => {
+        const stop = claudeLimitStop(file);
+        return stop && !stop.headless
+            ? [
+                {
+                    providerId: 'claude',
+                    sessionId: path.basename(file, JSON_LINES_EXTENSION),
+                    projectDir: stop.cwd,
+                    updatedAt,
+                    file,
+                    stoppedAt: stop.stoppedAt
+                }
+            ]
+            : [];
+    })
+        .sort((a, b) => b.stoppedAt - a.stoppedAt);
+}
+export async function codexLimitStops(root, now, maxAgeMs) {
+    const stops = [];
+    for (const file of walkRollouts(path.join(root, CODEX_SESSIONS_DIR))) {
+        const updatedAt = mtime(file);
+        if (now - updatedAt > maxAgeMs)
+            continue;
+        const stop = codexLimitStop(file);
+        const meta = stop && (await attempt(() => readCodexMeta(file)));
+        if (!stop || !meta || meta.subagent || meta.headless || typeof meta.cwd !== 'string' || !meta.cwd)
+            continue;
+        stops.push({ providerId: 'codex', sessionId: meta.id, projectDir: meta.cwd, updatedAt, file, stoppedAt: stop.stoppedAt });
+    }
+    return stops.sort((a, b) => b.stoppedAt - a.stoppedAt);
+}
+const LISTERS = { claude: listClaude, codex: listCodex, cursor: listCursor, antigravity: listAntigravity };
+const READERS = { claude: readClaude, codex: readCodex, cursor: readCursor, antigravity: readAntigravity };
+const providersFor = (providerId) => (providerId === AUTO ? PROVIDER_IDS : [providerId]);
+// Sessions of the project, newest first. A provider whose data cannot be read lists none.
+export async function listProviderSessions(providerId, projectDir, sources) {
+    const results = await Promise.allSettled(providersFor(providerId).map(async (id) => LISTERS[id](projectDir, sources)));
+    return results
+        .flatMap(result => (result.status === 'fulfilled' ? result.value : []))
+        .filter(session => session !== null)
+        .sort((a, b) => b.updatedAt - a.updatedAt);
+}
+// One session; with sessionId 'auto' the newest session of the provider(s). Null when
+// nothing matches: another provider's session is never substituted.
+export async function readSession({ providerId, sessionId, projectDir, sources }) {
+    if (!sessionId || sessionId === AUTO) {
+        const [latest] = await listProviderSessions(providerId, projectDir, sources);
+        return latest ? readSession({ providerId: latest.providerId, sessionId: latest.id, projectDir, sources }) : null;
+    }
+    for (const id of providersFor(providerId)) {
+        const transcript = await attempt(async () => READERS[id](projectDir, sources, sessionId));
+        if (transcript)
+            return transcript;
+    }
+    return null;
+}