sidekick-shared 0.27.6 → 0.28.0

package/dist/esm/providers/codex.js

@@ -0,0 +1,1034 @@
+/**
+ * Codex CLI session provider for the shared package.
+ *
+ * Implements SessionProviderBase for monitoring Codex CLI sessions.
+ * Codex stores sessions as JSONL rollout files in:
+ *   ~/.codex/sessions/YYYY/MM/DD/rollout-<timestamp>-<uuid>.jsonl
+ * with an optional SQLite index at ~/.codex/state.sqlite.
+ *
+ * Ported from sidekick-vscode/src/services/providers/CodexSessionProvider.ts
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { StringDecoder } from 'string_decoder';
+import { readSessionContextSnapshot } from '../context/sessionContext';
+import { readSessionFileStats } from '../sessionStats';
+import { CodexRolloutParser } from '../parsers/codexParser';
+import { CodexDatabase, spawnParentFromSource } from './codexDatabase';
+import { cachedSubagentStats } from '../parsers/subagentStatsCache';
+import { DEFAULT_ROLLOUT_WALK_MAX_DEPTH, extractRolloutSessionId as extractSessionId, isRolloutFile, walkRolloutFiles, } from './rolloutWalker';
+import { getCodexSessionsDirs } from '../codexPaths';
+import { cwdMatches, getSessionsDirs, listCodexSessionFilesAsync, normalizePath, readFirstLines, readSessionCwd, readSessionCwdAsync, readSessionMeta, } from './codexRollouts';
+import { DirectoryListingCache, splitWatchedPath } from './directoryListingCache';
+import { ProviderDiagnosticTracker, diagnosticFromRuntimeStatus } from './diagnostics';
+import { getModelContextWindowSize } from '../modelContext';
+import { recordObservedContextWindow } from '../observedContextWindows';
+import { extractNormalizedUsage, normalizeProviderUsage } from '../usageNormalization';
+import { addUsageToSubagent } from '../usage/subagentUsage';
+// ---------------------------------------------------------------------------
+// Helper functions
+// ---------------------------------------------------------------------------
+/** Truncate a string to maxLen with ellipsis. */
+function truncate(text, maxLen) {
+    const trimmed = text.trim().replace(/\s+/g, ' ');
+    if (trimmed.length > maxLen) {
+        return trimmed.substring(0, maxLen - 3) + '...';
+    }
+    return trimmed;
+}
+/** Every rollout under a directory, newest first (one capped walk). */
+function findRolloutFiles(dir) {
+    return walkRolloutFiles([dir]);
+}
+function hasRolloutFile(dir) {
+    return walkRolloutFiles([dir], { limit: 1 }).length > 0;
+}
+/** Every rollout across the monitored homes, newest first, deduplicated by path. */
+function findRolloutFilesInConfiguredHomes(options = {}) {
+    return walkRolloutFiles(getSessionsDirs(), options);
+}
+/**
+ * Locates the rollout file for a Codex session id by walking
+ * `<home>/sessions/YYYY/MM/DD/rollout-<timestamp>-<id>.jsonl`, then
+ * `<home>/archived_sessions/`, where Codex moves the rollouts of archived
+ * threads.
+ *
+ * Filename-only match, case-insensitive on the id — no file contents are read
+ * and files are only stat'ed once their name matches, so the walk stays cheap
+ * even over a large history. When the same id exists in more than one home,
+ * the most recently modified copy wins. Returns `null` for an unknown, empty,
+ * or whitespace id. Consumers who want the database's answer instead can query
+ * the already-public `CodexDatabase` (requires the external `sqlite3` binary).
+ */
+export function findCodexRolloutFile(sessionId, options = {}) {
+    const normalizedId = sessionId.trim().toLowerCase();
+    if (!normalizedId)
+        return null;
+    const sessionsDirs = options.codexHome
+        ? getCodexSessionsDirs([options.codexHome])
+        : getSessionsDirs();
+    // Name-only filter, one walk across the homes, newest modification first.
+    return walkRolloutFiles(sessionsDirs, { sessionId: normalizedId })[0]?.path ?? null;
+}
+/** Pick the best sessions directory for UI/search entrypoints. */
+function getSessionsDir() {
+    const dirs = getCodexSessionsDirs(undefined, { includeArchived: false });
+    for (const dir of dirs) {
+        if (hasRolloutFile(dir)) {
+            return dir;
+        }
+    }
+    return dirs[0] ?? path.join(process.cwd(), '.codex', 'sessions');
+}
+/** Pick the home that owns the preferred sessions directory. */
+function getCodexHome() {
+    return path.dirname(getSessionsDir());
+}
+/**
+ * Check if text looks like system-injected context rather than a real user prompt.
+ * Codex prepends AGENTS.md, environment_context, permissions, and collaboration_mode
+ * as user/developer messages before the actual user prompt.
+ */
+function isSystemInjection(text) {
+    const t = text.trimStart();
+    return t.startsWith('<') || t.startsWith('#');
+}
+/**
+ * Read the first user message text from a rollout file.
+ * Reads up to 20 lines to find a real user message (lines can be 10KB+ each).
+ * Skips system-injected context (AGENTS.md, environment_context, etc.).
+ */
+function extractFirstUserMessage(rolloutPath) {
+    try {
+        return extractFirstUserMessageFromLines(readFirstLines(rolloutPath, 20));
+    }
+    catch {
+        return null;
+    }
+}
+function extractFirstUserMessageFromLines(lines) {
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            // Check response_item with user message
+            if (parsed.type === 'response_item') {
+                const payload = parsed.payload;
+                if (payload.role === 'user') {
+                    const content = payload.content;
+                    if (typeof content === 'string' && content.trim() && !isSystemInjection(content)) {
+                        return truncate(content, 60);
+                    }
+                    if (Array.isArray(content)) {
+                        for (const part of content) {
+                            const p = part;
+                            if (p.text?.trim() && !isSystemInjection(p.text)) {
+                                return truncate(p.text, 60);
+                            }
+                        }
+                    }
+                }
+            }
+            // Check event_msg with user_message
+            if (parsed.type === 'event_msg') {
+                const payload = parsed.payload;
+                if (payload.type === 'user_message' && payload.message?.trim()) {
+                    return truncate(payload.message, 60);
+                }
+            }
+        }
+        catch {
+            // Skip malformed lines
+        }
+    }
+    return null;
+}
+async function extractFirstUserMessageAsync(rolloutPath) {
+    let handle = null;
+    try {
+        handle = await fs.promises.open(rolloutPath, 'r');
+        const buffer = Buffer.alloc(256 * 1024);
+        const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+        return extractFirstUserMessageFromLines(buffer.toString('utf8', 0, bytesRead).split('\n').slice(0, 20));
+    }
+    catch {
+        return null;
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}
+/** Extract searchable text from a rollout line. */
+function extractSearchableText(line) {
+    const parts = [];
+    switch (line.type) {
+        case 'session_meta': {
+            const payload = line.payload;
+            if (payload.cwd)
+                parts.push(payload.cwd);
+            if (payload.source)
+                parts.push(payload.source);
+            if (payload.base_instructions?.text)
+                parts.push(payload.base_instructions.text);
+            if (payload.git?.branch)
+                parts.push(payload.git.branch);
+            if (payload.git?.commit)
+                parts.push(payload.git.commit);
+            return parts.join(' ');
+        }
+        case 'response_item': {
+            const item = line.payload;
+            if (item.type === 'message') {
+                parts.push(extractTextFromUnknownContent(item.content));
+            }
+            if (item.type === 'reasoning') {
+                const summary = item.summary;
+                if (Array.isArray(summary)) {
+                    for (const entry of summary) {
+                        if (typeof entry.text === 'string')
+                            parts.push(entry.text);
+                    }
+                }
+            }
+            if (item.type === 'function_call') {
+                if (typeof item.name === 'string')
+                    parts.push(item.name);
+                if (typeof item.arguments === 'string')
+                    parts.push(item.arguments);
+            }
+            if (item.type === 'function_call_output' && typeof item.output === 'string') {
+                parts.push(item.output);
+            }
+            if (item.type === 'local_shell_call') {
+                const action = item.action;
+                const command = action?.command;
+                if (Array.isArray(command))
+                    parts.push(command.map(String).join(' '));
+                if (typeof action?.workdir === 'string')
+                    parts.push(action.workdir);
+            }
+            if (item.type === 'custom_tool_call') {
+                if (typeof item.name === 'string')
+                    parts.push(item.name);
+                if (typeof item.input === 'string')
+                    parts.push(item.input);
+            }
+            if (item.type === 'custom_tool_call_output' && typeof item.output === 'string') {
+                parts.push(item.output);
+            }
+            return parts.filter(Boolean).join(' ');
+        }
+        case 'event_msg': {
+            const event = line.payload;
+            for (const key of [
+                'type',
+                'message',
+                'result',
+                'stdout',
+                'stderr',
+                'summary',
+                'error',
+                'code',
+                'tool_name',
+                'server_name',
+            ]) {
+                if (typeof event[key] === 'string')
+                    parts.push(event[key]);
+            }
+            const command = event.command;
+            if (Array.isArray(command))
+                parts.push(command.map(String).join(' '));
+            if (event.arguments && typeof event.arguments === 'object')
+                parts.push(JSON.stringify(event.arguments));
+            return parts.filter(Boolean).join(' ');
+        }
+        case 'compacted': {
+            const payload = line.payload;
+            return payload.summary || '';
+        }
+        case 'turn_context': {
+            const payload = line.payload;
+            for (const key of ['model', 'cwd', 'approval_policy', 'sandbox_policy', 'effort']) {
+                if (typeof payload[key] === 'string')
+                    parts.push(payload[key]);
+            }
+            return parts.join(' ');
+        }
+        default:
+            return '';
+    }
+}
+function extractTextFromUnknownContent(content) {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    return content
+        .map((part) => {
+        const p = part;
+        return typeof p.text === 'string' ? p.text : '';
+    })
+        .filter(Boolean)
+        .join(' ');
+}
+// ---------------------------------------------------------------------------
+// CodexReader — incremental JSONL reader wrapping CodexRolloutParser
+// ---------------------------------------------------------------------------
+/**
+ * Incremental JSONL reader for Codex rollout files.
+ * Tracks byte position and feeds lines through CodexRolloutParser.
+ */
+class CodexReader {
+    rolloutPath;
+    onContextWindowLimit;
+    onRateLimits;
+    onTokenUsage;
+    parser;
+    filePosition = 0;
+    /** Cursor after the last complete line, safe to persist across restarts. */
+    committedPosition = 0;
+    lineBuffer = '';
+    _wasTruncated = false;
+    decoder = new StringDecoder('utf8');
+    constructor(rolloutPath, onContextWindowLimit, onRateLimits, onTokenUsage) {
+        this.rolloutPath = rolloutPath;
+        this.onContextWindowLimit = onContextWindowLimit;
+        this.onRateLimits = onRateLimits;
+        this.onTokenUsage = onTokenUsage;
+        this.parser = new CodexRolloutParser();
+    }
+    /** Get the parser's session metadata. */
+    getSessionMeta() {
+        return this.parser.getSessionMeta();
+    }
+    readNew(endPosition) {
+        this._wasTruncated = false;
+        const events = [];
+        try {
+            if (!fs.existsSync(this.rolloutPath))
+                return [];
+            const stats = fs.statSync(this.rolloutPath);
+            const currentSize = Math.min(stats.size, endPosition ?? stats.size);
+            // Handle truncation
+            if (currentSize < this.filePosition) {
+                this._wasTruncated = true;
+                this.filePosition = 0;
+                this.committedPosition = 0;
+                this.lineBuffer = '';
+                this.parser.reset();
+                this.decoder = new StringDecoder('utf8');
+            }
+            // No new content
+            if (currentSize <= this.filePosition)
+                return [];
+            // Read new bytes
+            const fd = fs.openSync(this.rolloutPath, 'r');
+            const bufferSize = currentSize - this.filePosition;
+            const buffer = Buffer.alloc(bufferSize);
+            let bytesRead = 0;
+            try {
+                bytesRead = fs.readSync(fd, buffer, 0, bufferSize, this.filePosition);
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+            const bytes = buffer.subarray(0, bytesRead);
+            const newline = bytes.lastIndexOf(0x0a);
+            if (newline >= 0)
+                this.committedPosition = this.filePosition + newline + 1;
+            const chunk = this.decoder.write(bytes);
+            this.filePosition += bytesRead;
+            // Process lines
+            const text = this.lineBuffer + chunk;
+            const lines = text.split('\n');
+            // Last element may be incomplete
+            this.lineBuffer = lines.pop() || '';
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                try {
+                    const parsed = JSON.parse(trimmed);
+                    events.push(...this.parser.convertLine(parsed));
+                }
+                catch {
+                    // Skip malformed JSON lines
+                }
+            }
+            // Propagate model_context_window from token_count events to the provider.
+            // The model comes along so the value can be persisted per model — the
+            // window Codex reports is tier-specific, not the published maximum.
+            const mcw = this.parser.getModelContextWindow();
+            if (mcw && this.onContextWindowLimit) {
+                this.onContextWindowLimit(mcw, this.parser.getCurrentModel() ?? undefined);
+            }
+            // Propagate rate_limits from token_count events to the provider
+            const rateLimits = this.parser.getLastRateLimits();
+            if (rateLimits && this.onRateLimits) {
+                this.onRateLimits(rateLimits);
+            }
+            // Propagate last token usage snapshot to the provider
+            const lastUsage = this.parser.getLastTokenUsage();
+            if (lastUsage && this.onTokenUsage) {
+                const normalized = normalizeProviderUsage({
+                    semantics: 'openai',
+                    provider: 'openai',
+                    source: 'codex-reader-snapshot',
+                    model: this.parser.getCurrentModel() || undefined,
+                    inputTokens: lastUsage.input_tokens,
+                    outputTokens: lastUsage.output_tokens,
+                    cacheReadTokens: lastUsage.cached_input_tokens,
+                    reasoningTokens: lastUsage.reasoning_output_tokens,
+                });
+                this.onTokenUsage({
+                    inputTokens: normalized.uncachedInputTokens,
+                    outputTokens: normalized.outputTokens,
+                    cacheWriteTokens: normalized.cacheWriteTokens,
+                    cacheReadTokens: normalized.cacheReadTokens,
+                    reasoningTokens: normalized.reasoningTokens,
+                    model: this.parser.getCurrentModel() || 'unknown',
+                    timestamp: new Date(),
+                });
+            }
+        }
+        catch {
+            // Skip read errors
+        }
+        return events;
+    }
+    readAll() {
+        this.reset();
+        return this.readNew();
+    }
+    reset() {
+        this.filePosition = 0;
+        this.committedPosition = 0;
+        this.lineBuffer = '';
+        this.parser.reset();
+        this.decoder = new StringDecoder('utf8');
+        this._wasTruncated = false;
+    }
+    exists() {
+        return fs.existsSync(this.rolloutPath);
+    }
+    flush() {
+        this.lineBuffer += this.decoder.end();
+        // Process any remaining data in the line buffer
+        if (this.lineBuffer.trim()) {
+            try {
+                const parsed = JSON.parse(this.lineBuffer.trim());
+                this.parser.convertLine(parsed);
+            }
+            catch {
+                // Not a complete line yet
+            }
+        }
+        this.decoder = new StringDecoder('utf8');
+    }
+    getPosition() {
+        return this.committedPosition;
+    }
+    seekTo(position) {
+        // Rebuild model, turn, and cumulative-token context before resuming.
+        // The prefix is parsed only; its events are already in the consumer snapshot.
+        this.reset();
+        if (position > 0)
+            this.readNew(position);
+    }
+    wasTruncated() {
+        return this._wasTruncated;
+    }
+}
+// ---------------------------------------------------------------------------
+// CodexProvider — full SessionProviderBase implementation
+// ---------------------------------------------------------------------------
+/**
+ * Session provider for Codex CLI.
+ *
+ * Uses SQLite database as optional index, with file-system scanning
+ * of the YYYY/MM/DD directory structure as primary discovery method.
+ */
+export class CodexProvider {
+    id = 'codex';
+    displayName = 'Codex CLI';
+    db = null;
+    dbInitialized = false;
+    dbStatus = { available: false, kind: 'db_missing' };
+    diagnostics;
+    dynamicContextWindowLimit = null;
+    lastRateLimitsData = null;
+    lastTokenUsageData = null;
+    /** Dated rollout-directory listings reused across async enumerations. */
+    directoryCache = new DirectoryListingCache();
+    constructor(options = {}) {
+        this.diagnostics = new ProviderDiagnosticTracker(this.id, options);
+    }
+    // --- Database ---
+    /** Lazy-initialize database connection. */
+    ensureDb() {
+        if (this.dbInitialized)
+            return this.db;
+        this.dbInitialized = true;
+        const codexHome = getCodexHome();
+        const db = new CodexDatabase(codexHome);
+        if (db.isAvailable() && db.open()) {
+            this.db = db;
+        }
+        if (typeof db.getRuntimeStatus === 'function') {
+            this.dbStatus = db.getRuntimeStatus();
+        }
+        return this.db;
+    }
+    async ensureDbAsync() {
+        if (this.db)
+            return this.db;
+        return new CodexDatabase(getCodexHome());
+    }
+    /**
+     * Cache an async-created database only after an operation proved it usable.
+     * Sync paths treat a cached `db` as "open() succeeded", so adopting an
+     * unproven instance would silently disable their file fallbacks.
+     */
+    adoptDbIfAvailable(db) {
+        if (this.db || !db.getRuntimeStatus().available)
+            return;
+        this.db = db;
+        this.dbInitialized = true;
+    }
+    getRuntimeStatus() {
+        const db = this.ensureDb();
+        return db && typeof db.getRuntimeStatus === 'function' ? db.getRuntimeStatus() : this.dbStatus;
+    }
+    getLastOperationStatus() {
+        return this.diagnostics.getLastOperationStatus();
+    }
+    // --- Path resolution ---
+    getSessionDirectory(workspacePath) {
+        // Codex doesn't use workspace-encoded directories like Claude Code.
+        // All sessions live under ~/.codex/sessions/ in date-based subdirs.
+        // We return the sessions base dir; session matching is done by CWD in the data.
+        const db = this.ensureDb();
+        if (db) {
+            const thread = db.getMostRecentThread(workspacePath);
+            if (thread?.rollout_path) {
+                this.recordDatabaseFallback('getSessionDirectory', true);
+                return path.dirname(thread.rollout_path);
+            }
+        }
+        const directory = getSessionsDir();
+        this.recordDatabaseFallback('getSessionDirectory', true);
+        return directory;
+    }
+    discoverSessionDirectory(workspacePath) {
+        // DB: find latest rollout directory for this workspace
+        const db = this.ensureDb();
+        if (db) {
+            const thread = db.getMostRecentThread(workspacePath);
+            if (thread?.rollout_path && fs.existsSync(thread.rollout_path)) {
+                this.recordDatabaseFallback('discoverSessionDirectory', true);
+                return path.dirname(thread.rollout_path);
+            }
+        }
+        // File scan: look for any rollout file whose session_meta.cwd matches
+        // (newest first; the cwd read is cached per path).
+        const files = findRolloutFilesInConfiguredHomes();
+        if (files.length === 0) {
+            this.recordDatabaseFallback('discoverSessionDirectory', true);
+            return null;
+        }
+        for (const file of files) {
+            const cwd = readSessionCwd(file.path);
+            if (cwd && cwdMatches(cwd, workspacePath)) {
+                this.recordDatabaseFallback('discoverSessionDirectory', true);
+                return path.dirname(file.path);
+            }
+        }
+        // Fallback: return the most relevant base sessions dir if one exists
+        const directory = getSessionsDir();
+        this.recordDatabaseFallback('discoverSessionDirectory', true);
+        return directory;
+    }
+    // --- Session discovery ---
+    findActiveSession(workspacePath) {
+        // DB first
+        const db = this.ensureDb();
+        if (db) {
+            const thread = db.getMostRecentThread(workspacePath);
+            if (thread?.rollout_path && fs.existsSync(thread.rollout_path)) {
+                this.recordDatabaseFallback('findActiveSession', true);
+                return thread.rollout_path;
+            }
+        }
+        // File scan fallback (newest first; cwd reads are cached per path)
+        for (const file of findRolloutFilesInConfiguredHomes()) {
+            const cwd = readSessionCwd(file.path);
+            if (cwd && cwdMatches(cwd, workspacePath)) {
+                this.recordDatabaseFallback('findActiveSession', true);
+                return file.path;
+            }
+        }
+        this.recordDatabaseFallback('findActiveSession', true);
+        return null;
+    }
+    findAllSessions(workspacePath) {
+        // DB first
+        const db = this.ensureDb();
+        if (db) {
+            const threads = db.getThreadsByCwd(workspacePath);
+            const dbPaths = threads
+                .filter((t) => t.rollout_path && fs.existsSync(t.rollout_path))
+                .map((t) => t.rollout_path);
+            if (dbPaths.length > 0) {
+                this.recordDatabaseFallback('findAllSessions', true);
+                return dbPaths;
+            }
+        }
+        // File scan (newest first; cwd reads are cached per path)
+        const sessions = findRolloutFilesInConfiguredHomes()
+            .filter((f) => {
+            const cwd = readSessionCwd(f.path);
+            return cwd !== null && cwdMatches(cwd, workspacePath);
+        })
+            .map((f) => f.path);
+        this.recordDatabaseFallback('findAllSessions', true);
+        return sessions;
+    }
+    findSessionById(_workspacePath, sessionId) {
+        try {
+            const found = findCodexRolloutFile(sessionId);
+            this.recordDatabaseFallback('findSessionById', true);
+            return found;
+        }
+        catch {
+            this.recordDatabaseFallback('findSessionById', false);
+            return null;
+        }
+    }
+    /** Backward-compatible alias for findAllSessions. */
+    findSessionFiles(workspacePath) {
+        return this.findAllSessions(workspacePath);
+    }
+    findSessionsInDirectory(dir) {
+        return findRolloutFiles(dir).map((f) => f.path);
+    }
+    listAllSessionFiles() {
+        const files = findRolloutFilesInConfiguredHomes();
+        this.recordDatabaseFallback('listAllSessionFiles', true);
+        return files;
+    }
+    async listSessionFilesAsync(workspacePath, options = {}) {
+        const results = await listCodexSessionFilesAsync(workspacePath, options, this.directoryCache);
+        // Filesystem enumeration bypasses the database, so record that here as
+        // the sync listing paths do; otherwise `getLastOperationStatus()` keeps
+        // describing whichever operation ran before this one.
+        this.recordDatabaseFallback('listSessionFilesAsync', true);
+        return results;
+    }
+    /**
+     * Resolve a recursive-watch event under a sessions root with one stat.
+     * Rollouts are matched by name at any depth the walker would visit; a
+     * dated directory appearing or vanishing needs a full walk.
+     */
+    async statWatchedSessionFile(root, relativePath, workspacePath) {
+        const segments = splitWatchedPath(relativePath);
+        if (!segments)
+            return { status: 'unknown' };
+        const fullPath = path.join(root, ...segments);
+        const name = segments[segments.length - 1];
+        if (segments.length - 1 > DEFAULT_ROLLOUT_WALK_MAX_DEPTH)
+            return { status: 'ignored' };
+        if (!isRolloutFile(name)) {
+            this.directoryCache.invalidate(fullPath);
+            try {
+                const stat = await fs.promises.stat(fullPath);
+                return stat.isDirectory() ? { status: 'unknown' } : { status: 'ignored' };
+            }
+            catch {
+                return { status: 'unknown' };
+            }
+        }
+        const sessionId = extractSessionId(name);
+        const stat = await this.directoryCache.refreshFile(fullPath);
+        if (!stat || stat.sizeBytes <= 0)
+            return { status: 'missing', path: fullPath, sessionId };
+        const file = {
+            path: fullPath,
+            mtime: new Date(stat.mtimeMs),
+            sizeBytes: stat.sizeBytes,
+            sessionId,
+        };
+        if (workspacePath) {
+            const cwd = await readSessionCwdAsync(fullPath);
+            if (!cwd || !cwdMatches(cwd, workspacePath))
+                return { status: 'ignored' };
+            file.workspacePath = cwd;
+        }
+        return { status: 'present', file };
+    }
+    getAllProjectFolders(workspacePath) {
+        const folders = [];
+        const seenCwds = new Map();
+        // DB first
+        const db = this.ensureDb();
+        if (db) {
+            const cwdStats = db.getAllDistinctCwds();
+            const sessionsDir = getSessionsDir();
+            for (const stat of cwdStats) {
+                seenCwds.set(stat.cwd, {
+                    dir: sessionsDir,
+                    name: stat.cwd,
+                    encodedName: stat.cwd,
+                    sessionCount: stat.count,
+                    lastModified: new Date(stat.lastUpdated),
+                });
+            }
+        }
+        // File scan supplement. When the index answered, only rollouts written
+        // after its last update can be missing from it, so older files are not
+        // opened; the cwd read itself is cached per path either way.
+        const indexedUpTo = db ? db.getDbMtime() : 0;
+        for (const file of findRolloutFilesInConfiguredHomes()) {
+            if (db && indexedUpTo > 0 && file.mtime.getTime() <= indexedUpTo)
+                continue;
+            const cwd = readSessionCwd(file.path);
+            if (!cwd)
+                continue;
+            const existing = seenCwds.get(cwd);
+            if (existing) {
+                // Update mtime if newer
+                if (file.mtime > existing.lastModified) {
+                    existing.lastModified = file.mtime;
+                }
+            }
+            else {
+                seenCwds.set(cwd, {
+                    dir: path.dirname(file.path),
+                    name: cwd,
+                    encodedName: cwd,
+                    sessionCount: 1,
+                    lastModified: file.mtime,
+                });
+            }
+        }
+        folders.push(...seenCwds.values());
+        // Sort: current workspace first, then by recency
+        const normalizedWorkspace = workspacePath ? normalizePath(workspacePath) : null;
+        folders.sort((a, b) => {
+            if (normalizedWorkspace) {
+                const aMatch = cwdMatches(a.name, normalizedWorkspace);
+                const bMatch = cwdMatches(b.name, normalizedWorkspace);
+                if (aMatch && !bMatch)
+                    return -1;
+                if (!aMatch && bMatch)
+                    return 1;
+            }
+            return b.lastModified.getTime() - a.lastModified.getTime();
+        });
+        this.recordDatabaseFallback('getAllProjectFolders', true);
+        return folders;
+    }
+    // --- File identification ---
+    isSessionFile(filename) {
+        return isRolloutFile(filename);
+    }
+    getSessionId(sessionPath) {
+        return extractSessionId(path.basename(sessionPath));
+    }
+    encodeWorkspacePath(workspacePath) {
+        // Codex doesn't encode workspace paths in directory names
+        return workspacePath;
+    }
+    /** Thread title or first user message from the SQLite index; null without it. */
+    extractSessionLabelFromDb(sessionPath) {
+        const db = this.ensureDb();
+        if (!db)
+            return null;
+        const sessionId = this.getSessionId(sessionPath);
+        const thread = db.getThread(sessionId);
+        if (thread?.title) {
+            this.recordDatabaseFallback('extractSessionLabel', true);
+            return truncate(thread.title, 60);
+        }
+        if (thread?.first_user_message) {
+            this.recordDatabaseFallback('extractSessionLabel', true);
+            return truncate(thread.first_user_message, 60);
+        }
+        return null;
+    }
+    extractSessionLabel(sessionPath) {
+        const fromDb = this.extractSessionLabelFromDb(sessionPath);
+        if (fromDb)
+            return fromDb;
+        // File fallback: parse first user message
+        const label = extractFirstUserMessage(sessionPath);
+        this.recordDatabaseFallback('extractSessionLabel', true);
+        return label;
+    }
+    async extractSessionLabelsAsync(sessionPaths) {
+        const results = new Map();
+        const byId = new Map(sessionPaths.map((sessionPath) => [this.getSessionId(sessionPath), sessionPath]));
+        const db = await this.ensureDbAsync();
+        const threads = await db.getThreadsByIdsAsync([...byId.keys()]);
+        for (const thread of threads) {
+            const sessionPath = byId.get(thread.id);
+            if (!sessionPath)
+                continue;
+            const label = thread.title ?? thread.first_user_message;
+            if (label)
+                results.set(sessionPath, truncate(label, 60));
+        }
+        this.dbStatus = db.getRuntimeStatus();
+        this.adoptDbIfAvailable(db);
+        for (const sessionPath of sessionPaths) {
+            if (!results.has(sessionPath)) {
+                results.set(sessionPath, await extractFirstUserMessageAsync(sessionPath));
+                await new Promise((resolve) => setImmediate(resolve));
+            }
+        }
+        this.recordDatabaseFallback('extractSessionLabelsAsync', true);
+        return results;
+    }
+    // --- Data reading ---
+    createReader(sessionPath) {
+        return new CodexReader(sessionPath, (limit, modelId) => {
+            this.dynamicContextWindowLimit = limit;
+            if (modelId) {
+                // Fire-and-forget: persist so historical/static views keep this
+                // tier-specific window instead of falling back to the catalog maximum.
+                void recordObservedContextWindow(modelId, limit).catch(() => {
+                    /* non-fatal; the in-memory limit above still applies */
+                });
+            }
+        }, (limits) => {
+            this.lastRateLimitsData = limits;
+        }, (usage) => {
+            this.lastTokenUsageData = usage;
+        });
+    }
+    // --- Subagent support ---
+    scanSubagents(_sessionDir, sessionId) {
+        // Codex tracks forked sessions via forked_from_id in session_meta.
+        // Use DB when available, fall back to filesystem scanning.
+        const subagents = [];
+        // DB approach: spawned subagents (parent recorded in `threads.source`),
+        // plus forked children on older schemas that carry `forked_from_id`.
+        const db = this.ensureDb();
+        if (db) {
+            const seen = new Set();
+            const children = [
+                ...db.getSpawnedChildThreads(sessionId),
+                ...db.getThreadsByForkedFromId(sessionId),
+            ].filter((thread) => !seen.has(thread.id) && seen.add(thread.id));
+            for (const thread of children) {
+                const built = cachedSubagentStats(thread.rollout_path, () => this.buildSubagentStats(thread.id, thread.rollout_path, thread.title || thread.agent_nickname));
+                if (built) {
+                    subagents.push(thread.agent_role && !built.agentType
+                        ? { ...built, agentType: thread.agent_role }
+                        : built);
+                }
+            }
+            if (children.length > 0)
+                return subagents;
+        }
+        // Filesystem fallback: scan recent rollout files for a matching
+        // forked_from_id. The walk stops after the 50 newest-dated files instead
+        // of enumerating the whole history and slicing afterwards.
+        for (const file of findRolloutFilesInConfiguredHomes({ limit: 50 })) {
+            const meta = readSessionMeta(file.path);
+            if (meta &&
+                (meta.forked_from_id === sessionId || spawnParentFromSource(meta.source) === sessionId)) {
+                const childId = extractSessionId(path.basename(file.path));
+                // `source` is a plain string for top-level sessions but an object
+                // (`{ subagent: { thread_spawn: … } }`) for spawned children.
+                const description = typeof meta.source === 'string' ? meta.source : undefined;
+                const stats = cachedSubagentStats(file.path, () => this.buildSubagentStats(childId, file.path, description));
+                if (stats)
+                    subagents.push(stats);
+            }
+        }
+        return subagents;
+    }
+    /**
+     * Builds SubagentStats for a forked session by reading its rollout file.
+     */
+    buildSubagentStats(agentId, rolloutPath, description) {
+        if (!rolloutPath || !fs.existsSync(rolloutPath))
+            return null;
+        const stats = {
+            agentId,
+            description: description || undefined,
+            toolCalls: [],
+            inputTokens: 0,
+            outputTokens: 0,
+        };
+        try {
+            const parser = new CodexRolloutParser();
+            const content = fs.readFileSync(rolloutPath, 'utf8');
+            const lines = content.split('\n');
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                try {
+                    const parsed = JSON.parse(trimmed);
+                    // Track timestamps
+                    if (parsed.timestamp) {
+                        const ts = new Date(parsed.timestamp);
+                        if (!stats.startTime || ts < stats.startTime)
+                            stats.startTime = ts;
+                        if (!stats.endTime || ts > stats.endTime)
+                            stats.endTime = ts;
+                    }
+                    const events = parser.convertLine(parsed);
+                    for (const event of events) {
+                        // Collect tool calls
+                        if (event.type === 'assistant' && Array.isArray(event.message.content)) {
+                            for (const block of event.message.content) {
+                                if (block.type === 'tool_use' && typeof block.name === 'string') {
+                                    stats.toolCalls.push({
+                                        name: block.name,
+                                        input: block.input || {},
+                                        timestamp: new Date(event.timestamp),
+                                    });
+                                }
+                            }
+                        }
+                        // Accumulate tokens from usage events (duplicate token_count events
+                        // are already dropped by the parser).
+                        const usage = extractNormalizedUsage(event);
+                        if (usage)
+                            addUsageToSubagent(stats, usage);
+                    }
+                }
+                catch {
+                    /* skip malformed lines */
+                }
+            }
+            if (stats.startTime && stats.endTime) {
+                stats.durationMs = stats.endTime.getTime() - stats.startTime.getTime();
+            }
+        }
+        catch {
+            /* skip unreadable files */
+        }
+        return stats;
+    }
+    // --- Cross-session search ---
+    searchInSession(sessionPath, query, maxResults) {
+        const results = [];
+        const queryLower = query.toLowerCase();
+        try {
+            const content = fs.readFileSync(sessionPath, 'utf8');
+            const lines = content.split('\n');
+            for (const line of lines) {
+                if (results.length >= maxResults)
+                    break;
+                if (!line.trim())
+                    continue;
+                const lineLower = line.toLowerCase();
+                if (!lineLower.includes(queryLower))
+                    continue;
+                try {
+                    const parsed = JSON.parse(line);
+                    const text = extractSearchableText(parsed);
+                    if (!text)
+                        continue;
+                    const textLower = text.toLowerCase();
+                    const matchIdx = textLower.indexOf(queryLower);
+                    if (matchIdx < 0)
+                        continue;
+                    const start = Math.max(0, matchIdx - 40);
+                    const end = Math.min(text.length, matchIdx + query.length + 40);
+                    const snippet = (start > 0 ? '...' : '') +
+                        text.substring(start, end) +
+                        (end < text.length ? '...' : '');
+                    results.push({
+                        sessionPath,
+                        line: snippet.replace(/\n/g, ' '),
+                        eventType: parsed.type,
+                        timestamp: parsed.timestamp || '',
+                        projectPath: readSessionCwd(sessionPath) || sessionPath,
+                    });
+                }
+                catch {
+                    // Skip malformed JSON
+                }
+            }
+        }
+        catch {
+            // Skip unreadable files
+        }
+        return results;
+    }
+    getProjectsBaseDir() {
+        return getSessionsDir();
+    }
+    getWatchRoots() {
+        return getSessionsDirs();
+    }
+    // --- Stats ---
+    readSessionStats(sessionPath) {
+        // One reader pass computes stats and the label: the SQLite thread title is
+        // used when the index is available, otherwise the first user prompt comes
+        // from the events already read, so the rollout is never opened twice.
+        return readSessionFileStats(this, sessionPath, {
+            resolveLabel: () => this.extractSessionLabelFromDb(sessionPath),
+        });
+    }
+    readSessionContextSnapshot(sessionPath, options = {}) {
+        return readSessionContextSnapshot(this, sessionPath, options);
+    }
+    // --- Optional methods ---
+    getContextWindowLimit(modelId) {
+        // Prefer actual model_context_window reported by token_count events
+        if (this.dynamicContextWindowLimit)
+            return this.dynamicContextWindowLimit;
+        return getModelContextWindowSize(modelId);
+    }
+    getCurrentUsageSnapshot(_sessionPath) {
+        // Return the last token usage snapshot received via the CodexReader callback.
+        // This is populated in real-time as token_count events arrive during active monitoring.
+        return this.lastTokenUsageData;
+    }
+    computeContextSize(usage) {
+        // Codex usage is normalized to the disjoint TokenUsage shape at the reader
+        // boundary, so reconstruct the full prompt/context from uncached + cached.
+        return usage.inputTokens + usage.cacheReadTokens;
+    }
+    // --- Rate limits (for vscode wrapper to build QuotaState) ---
+    /** Get the last rate limits data received from token_count events. */
+    getLastRateLimits() {
+        return this.lastRateLimitsData;
+    }
+    // --- Lifecycle ---
+    dispose() {
+        this.db?.close();
+        this.db = null;
+        this.dbInitialized = false;
+        this.dbStatus = { available: false, kind: 'db_missing' };
+        this.dynamicContextWindowLimit = null;
+        this.lastRateLimitsData = null;
+        this.lastTokenUsageData = null;
+        this.directoryCache.invalidate();
+    }
+    recordDatabaseFallback(operation, usable) {
+        if (!this.dbInitialized) {
+            this.diagnostics.available(operation);
+            return;
+        }
+        const status = this.getRuntimeStatus();
+        const diagnostic = diagnosticFromRuntimeStatus(this.id, 'query', status);
+        if (!diagnostic) {
+            this.diagnostics.available(operation);
+            return;
+        }
+        this.diagnostics.degraded(operation, status, {
+            kind: diagnostic.kind,
+            severity: diagnostic.severity,
+            phase: diagnostic.phase,
+            message: diagnostic.message,
+        }, usable);
+    }
+}