sidekick-shared 0.27.6 → 0.28.0

package/dist/providers/claudeListing.js

@@ -0,0 +1,158 @@
+"use strict";
+/**
+ * Claude Code session-file listing, kept apart from the provider class so a
+ * caller that only lists files does not bundle the provider's stats,
+ * context and transcript code.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.workspaceDirectoryFilter = workspaceDirectoryFilter;
+exports.listClaudeSessionFilesAsync = listClaudeSessionFilesAsync;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const claudePaths_1 = require("../claudePaths");
+const sessionPathResolver_1 = require("../parsers/sessionPathResolver");
+const directoryListingCache_1 = require("./directoryListingCache");
+/** Matches project directory names that may hold sessions for `workspacePath`. */
+function workspaceDirectoryFilter(workspacePath) {
+    if (!workspacePath)
+        return () => true;
+    const encodedWorkspace = (0, sessionPathResolver_1.encodeWorkspacePath)(workspacePath).toLowerCase();
+    const workspaceBasename = path
+        .basename(workspacePath)
+        .replace(/[^a-zA-Z0-9]/g, '-')
+        .toLowerCase();
+    return (directoryName) => {
+        const name = directoryName.toLowerCase();
+        return (name === encodedWorkspace ||
+            name.startsWith(`${encodedWorkspace}-`) ||
+            name === workspaceBasename ||
+            name.endsWith(`-${workspaceBasename}`));
+    };
+}
+/**
+ * Enumerate session files across project directories through the
+ * directory cache: one stat per project directory, a readdir only for
+ * directories whose mtime changed, and a stat only for files new to a
+ * changed directory (or recently modified, with `revalidateRecent`).
+ *
+ * With `limit`, directories are visited newest-mtime first and the walk
+ * stops once the remaining directories are older than the newest `limit`
+ * files found. A directory's mtime ignores appends, so a cold limited walk
+ * can miss a long-running session in an old directory until its next watch
+ * event; `since` filters files and shares the caveat.
+ */
+async function listClaudeSessionFilesAsync(workspacePath, options = {}, cache = new directoryListingCache_1.DirectoryListingCache()) {
+    const projectsRoot = (0, claudePaths_1.getClaudeProjectsDir)();
+    if (options.stats) {
+        options.stats.directoriesListed ??= 0;
+        options.stats.directoriesStatted ??= 0;
+        options.stats.filesStatted ??= 0;
+    }
+    const root = await cache.listDirectory(projectsRoot, () => false, {
+        revalidateRecent: options.revalidateRecent,
+        stats: options.stats,
+    });
+    if (!root) {
+        return [];
+    }
+    const limit = options.limit !== undefined && Number.isFinite(options.limit)
+        ? Math.max(0, Math.floor(options.limit))
+        : null;
+    if (limit === 0) {
+        return [];
+    }
+    const since = options.since !== undefined && Number.isFinite(options.since) ? options.since : null;
+    const matchesWorkspace = workspaceDirectoryFilter(workspacePath);
+    const candidates = [];
+    let sinceYield = 0;
+    for (const name of root.subdirectories) {
+        if (!matchesWorkspace(name))
+            continue;
+        const directory = path.join(projectsRoot, name);
+        try {
+            const stat = await fs.promises.stat(directory);
+            if (options.stats) {
+                options.stats.directoriesStatted = (options.stats.directoriesStatted ?? 0) + 1;
+            }
+            if (stat.isDirectory())
+                candidates.push({ directory, stat });
+        }
+        catch {
+            continue;
+        }
+        if (++sinceYield >= 50) {
+            sinceYield = 0;
+            await new Promise((resolve) => setImmediate(resolve));
+        }
+    }
+    if (limit !== null)
+        candidates.sort((left, right) => right.stat.mtimeMs - left.stat.mtimeMs);
+    const byNewest = (left, right) => right.mtime.getTime() - left.mtime.getTime();
+    const results = [];
+    let cutoffMs = null;
+    for (const candidate of candidates) {
+        if (limit !== null && cutoffMs !== null && candidate.stat.mtimeMs < cutoffMs)
+            break;
+        const listing = await cache.listDirectory(candidate.directory, (name) => name.endsWith('.jsonl'), {
+            dirStat: candidate.stat,
+            revalidateRecent: options.revalidateRecent,
+            stats: options.stats,
+        });
+        if (!listing)
+            continue;
+        for (const [name, stat] of listing.files) {
+            if (stat.sizeBytes <= 0)
+                continue;
+            if (since !== null && stat.mtimeMs < since)
+                continue;
+            const sessionPath = path.join(candidate.directory, name);
+            results.push({
+                path: sessionPath,
+                mtime: new Date(stat.mtimeMs),
+                sizeBytes: stat.sizeBytes,
+                sessionId: path.basename(sessionPath, '.jsonl'),
+            });
+        }
+        if (limit !== null && results.length >= limit) {
+            results.sort(byNewest);
+            results.length = limit;
+            cutoffMs = results[limit - 1].mtime.getTime();
+        }
+        await new Promise((resolve) => setImmediate(resolve));
+    }
+    results.sort(byNewest);
+    return limit !== null && results.length > limit ? results.slice(0, limit) : results;
+}

package/dist/providers/codex.d.ts

@@ -22,7 +22,9 @@ export interface FindCodexRolloutFileOptions {
 }
 /**
  * Locates the rollout file for a Codex session id by walking
- * `<home>/sessions/YYYY/MM/DD/rollout-<timestamp>-<id>.jsonl`.
+ * `<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

package/dist/providers/codex.js

@@ -53,8 +53,9 @@ const sessionStats_1 = require("../sessionStats");
 const codexParser_1 = require("../parsers/codexParser");
 const codexDatabase_1 = require("./codexDatabase");
 const subagentStatsCache_1 = require("../parsers/subagentStatsCache");
-const codexProfiles_1 = require("../codexProfiles");
 const rolloutWalker_1 = require("./rolloutWalker");
+const codexPaths_1 = require("../codexPaths");
+const codexRollouts_1 = require("./codexRollouts");
 const directoryListingCache_1 = require("./directoryListingCache");
 const diagnostics_1 = require("./diagnostics");
 const modelContext_1 = require("../modelContext");
@@ -64,19 +65,6 @@ const subagentUsage_1 = require("../usage/subagentUsage");
 // ---------------------------------------------------------------------------
 // Helper functions
 // ---------------------------------------------------------------------------
-/**
- * Gets all candidate Codex homes to monitor.
- *
- * Managed profiles stay first so Sidekick-launched sessions keep working, but
- * we also fall back to the system ~/.codex home when no explicit CODEX_HOME is set.
- */
-function getCodexHomes() {
-    return (0, codexProfiles_1.getCodexMonitoringHomes)();
-}
-/** Get every sessions base directory that may contain live Codex rollouts. */
-function getSessionsDirs() {
-    return getCodexHomes().map((home) => path.join(home, 'sessions'));
-}
 /** Truncate a string to maxLen with ellipsis. */
 function truncate(text, maxLen) {
     const trimmed = text.trim().replace(/\s+/g, ' ');
@@ -94,11 +82,13 @@ function hasRolloutFile(dir) {
 }
 /** Every rollout across the monitored homes, newest first, deduplicated by path. */
 function findRolloutFilesInConfiguredHomes(options = {}) {
-    return (0, rolloutWalker_1.walkRolloutFiles)(getSessionsDirs(), options);
+    return (0, rolloutWalker_1.walkRolloutFiles)((0, codexRollouts_1.getSessionsDirs)(), options);
 }
 /**
  * Locates the rollout file for a Codex session id by walking
- * `<home>/sessions/YYYY/MM/DD/rollout-<timestamp>-<id>.jsonl`.
+ * `<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
@@ -112,14 +102,14 @@ function findCodexRolloutFile(sessionId, options = {}) {
     if (!normalizedId)
         return null;
     const sessionsDirs = options.codexHome
-        ? [path.join(options.codexHome, 'sessions')]
-        : getSessionsDirs();
+        ? (0, codexPaths_1.getCodexSessionsDirs)([options.codexHome])
+        : (0, codexRollouts_1.getSessionsDirs)();
     // Name-only filter, one walk across the homes, newest modification first.
     return (0, rolloutWalker_1.walkRolloutFiles)(sessionsDirs, { sessionId: normalizedId })[0]?.path ?? null;
 }
 /** Pick the best sessions directory for UI/search entrypoints. */
 function getSessionsDir() {
-    const dirs = getSessionsDirs();
+    const dirs = (0, codexPaths_1.getCodexSessionsDirs)(undefined, { includeArchived: false });
     for (const dir of dirs) {
         if (hasRolloutFile(dir)) {
             return dir;
@@ -140,174 +130,6 @@ function isSystemInjection(text) {
     const t = text.trimStart();
     return t.startsWith('<') || t.startsWith('#');
 }
-/**
- * Read the first N complete lines from a file using chunked reads.
- * Handles arbitrarily long lines (Codex session_meta can be 10KB+).
- */
-function readFirstLines(filePath, maxLines, maxBytes = 256 * 1024) {
-    const lines = [];
-    let fd;
-    try {
-        fd = fs.openSync(filePath, 'r');
-    }
-    catch {
-        return [];
-    }
-    let pending = '';
-    let totalRead = 0;
-    const chunkSize = 16384;
-    try {
-        while (totalRead < maxBytes && lines.length < maxLines) {
-            const buf = Buffer.alloc(Math.min(chunkSize, maxBytes - totalRead));
-            const bytesRead = fs.readSync(fd, buf, 0, buf.length, totalRead);
-            if (bytesRead === 0)
-                break;
-            totalRead += bytesRead;
-            pending += buf.toString('utf-8', 0, bytesRead);
-            let nlIdx;
-            while ((nlIdx = pending.indexOf('\n')) !== -1 && lines.length < maxLines) {
-                lines.push(pending.substring(0, nlIdx));
-                pending = pending.substring(nlIdx + 1);
-            }
-        }
-        if (pending.trim() && lines.length < maxLines) {
-            lines.push(pending);
-        }
-    }
-    finally {
-        fs.closeSync(fd);
-    }
-    return lines;
-}
-/** Read session_meta from the beginning of a rollout file. */
-function readSessionMeta(rolloutPath) {
-    try {
-        const lines = readFirstLines(rolloutPath, 1);
-        const firstLine = lines[0]?.trim();
-        if (!firstLine)
-            return null;
-        const parsed = JSON.parse(firstLine);
-        if (parsed.type === 'session_meta') {
-            return parsed.payload;
-        }
-    }
-    catch {
-        // Skip
-    }
-    return null;
-}
-/**
- * First line of a rollout, chunk-read under the same 256 KiB cap as
- * readFirstLines(). `complete` is false while the line has no newline yet
- * (a rollout that was just created) or the file could not be read, so
- * callers know not to cache the answer.
- */
-async function readFirstLineAsync(rolloutPath) {
-    // Mirrors readSessionMeta()/readFirstLines(): chunk-read until the first
-    // line is complete under the same 256 KiB cap — session_meta carries
-    // `instructions` and can far exceed a single chunk.
-    const maxBytes = 256 * 1024;
-    const chunkSize = 64 * 1024;
-    let handle = null;
-    try {
-        handle = await fs.promises.open(rolloutPath, 'r');
-        const chunks = [];
-        let totalRead = 0;
-        let newlineFound = false;
-        while (totalRead < maxBytes && !newlineFound) {
-            const buffer = Buffer.alloc(Math.min(chunkSize, maxBytes - totalRead));
-            const { bytesRead } = await handle.read(buffer, 0, buffer.length, totalRead);
-            if (bytesRead === 0)
-                break;
-            const chunk = buffer.subarray(0, bytesRead);
-            chunks.push(chunk);
-            totalRead += bytesRead;
-            newlineFound = chunk.includes(0x0a);
-        }
-        const firstLine = Buffer.concat(chunks).toString('utf8').split('\n', 1)[0]?.trim();
-        return { line: firstLine || null, complete: newlineFound || totalRead >= maxBytes };
-    }
-    catch {
-        return { line: null, complete: false };
-    }
-    finally {
-        await handle?.close().catch(() => undefined);
-    }
-}
-function parseSessionMetaLine(line) {
-    if (!line)
-        return null;
-    try {
-        const parsed = JSON.parse(line);
-        return parsed.type === 'session_meta' ? parsed.payload : null;
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Read the CWD from a rollout file's session_meta. Cached per path, bounded
- * so a long-lived host watching a large history cannot grow it without limit
- * (insertion order doubles as an eviction order).
- */
-const CWD_CACHE_LIMIT = 5000;
-const cwdCache = new Map();
-function rememberCwd(rolloutPath, cwd) {
-    if (!cwdCache.has(rolloutPath) && cwdCache.size >= CWD_CACHE_LIMIT) {
-        const oldest = cwdCache.keys().next().value;
-        if (oldest !== undefined)
-            cwdCache.delete(oldest);
-    }
-    cwdCache.set(rolloutPath, cwd);
-}
-function readSessionCwd(rolloutPath) {
-    const cached = cwdCache.get(rolloutPath);
-    if (cached !== undefined)
-        return cached;
-    const meta = readSessionMeta(rolloutPath);
-    const cwd = meta?.cwd || null;
-    rememberCwd(rolloutPath, cwd);
-    return cwd;
-}
-/** Async twin of readSessionCwd, sharing its cache so repeat listings do no content reads. */
-async function readSessionCwdAsync(rolloutPath) {
-    const cached = cwdCache.get(rolloutPath);
-    if (cached !== undefined)
-        return cached;
-    const { line, complete } = await readFirstLineAsync(rolloutPath);
-    const cwd = parseSessionMetaLine(line)?.cwd || null;
-    // A rollout observed before its session_meta line is flushed has no cwd
-    // yet; caching that null would hide the session from its workspace until
-    // the entry aged out, so only conclusive answers are remembered.
-    if (cwd !== null || complete)
-        rememberCwd(rolloutPath, cwd);
-    return cwd;
-}
-/** Built-in enumerators report explicit zeros rather than leaving a counter unset. */
-function initializeCounters(stats) {
-    if (!stats)
-        return;
-    stats.directoriesListed ??= 0;
-    stats.directoriesStatted ??= 0;
-    stats.filesStatted ??= 0;
-}
-/** Check if a session's CWD matches a workspace path. */
-function cwdMatches(sessionCwd, workspacePath) {
-    const normalizedSession = normalizePath(sessionCwd);
-    const normalizedWorkspace = normalizePath(workspacePath);
-    return (normalizedSession === normalizedWorkspace ||
-        normalizedWorkspace.startsWith(normalizedSession + path.sep) ||
-        normalizedSession.startsWith(normalizedWorkspace + path.sep));
-}
-/** Normalize a path using realpathSync. */
-function normalizePath(input) {
-    try {
-        return fs.realpathSync(input);
-    }
-    catch {
-        return path.resolve(input);
-    }
-}
 /**
  * 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).
@@ -315,7 +137,7 @@ function normalizePath(input) {
  */
 function extractFirstUserMessage(rolloutPath) {
     try {
-        return extractFirstUserMessageFromLines(readFirstLines(rolloutPath, 20));
+        return extractFirstUserMessageFromLines((0, codexRollouts_1.readFirstLines)(rolloutPath, 20));
     }
     catch {
         return null;
@@ -754,8 +576,8 @@ class CodexProvider {
             return null;
         }
         for (const file of files) {
-            const cwd = readSessionCwd(file.path);
-            if (cwd && cwdMatches(cwd, workspacePath)) {
+            const cwd = (0, codexRollouts_1.readSessionCwd)(file.path);
+            if (cwd && (0, codexRollouts_1.cwdMatches)(cwd, workspacePath)) {
                 this.recordDatabaseFallback('discoverSessionDirectory', true);
                 return path.dirname(file.path);
             }
@@ -778,8 +600,8 @@ class CodexProvider {
         }
         // 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)) {
+            const cwd = (0, codexRollouts_1.readSessionCwd)(file.path);
+            if (cwd && (0, codexRollouts_1.cwdMatches)(cwd, workspacePath)) {
                 this.recordDatabaseFallback('findActiveSession', true);
                 return file.path;
             }
@@ -803,8 +625,8 @@ class CodexProvider {
         // 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);
+            const cwd = (0, codexRollouts_1.readSessionCwd)(f.path);
+            return cwd !== null && (0, codexRollouts_1.cwdMatches)(cwd, workspacePath);
         })
             .map((f) => f.path);
         this.recordDatabaseFallback('findAllSessions', true);
@@ -834,30 +656,7 @@ class CodexProvider {
         return files;
     }
     async listSessionFilesAsync(workspacePath, options = {}) {
-        const results = [];
-        initializeCounters(options.stats);
-        // One capped walk across the homes (deduplicated, newest first) through
-        // the directory cache. With a workspace filter the limit applies after
-        // filtering, so the walk itself is bounded only by its file cap.
-        const files = await (0, rolloutWalker_1.walkRolloutFilesAsync)(getSessionsDirs(), {
-            limit: workspacePath ? undefined : options.limit,
-            since: options.since,
-            cache: this.directoryCache,
-            revalidateRecent: options.revalidateRecent,
-            stats: options.stats,
-        });
-        for (const file of files) {
-            if (options.limit !== undefined && results.length >= options.limit)
-                break;
-            const info = { ...file };
-            if (workspacePath) {
-                const cwd = await readSessionCwdAsync(file.path);
-                if (!cwd || !cwdMatches(cwd, workspacePath))
-                    continue;
-                info.workspacePath = cwd;
-            }
-            results.push(info);
-        }
+        const results = await (0, codexRollouts_1.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.
@@ -898,8 +697,8 @@ class CodexProvider {
             sessionId,
         };
         if (workspacePath) {
-            const cwd = await readSessionCwdAsync(fullPath);
-            if (!cwd || !cwdMatches(cwd, workspacePath))
+            const cwd = await (0, codexRollouts_1.readSessionCwdAsync)(fullPath);
+            if (!cwd || !(0, codexRollouts_1.cwdMatches)(cwd, workspacePath))
                 return { status: 'ignored' };
             file.workspacePath = cwd;
         }
@@ -930,7 +729,7 @@ class CodexProvider {
         for (const file of findRolloutFilesInConfiguredHomes()) {
             if (db && indexedUpTo > 0 && file.mtime.getTime() <= indexedUpTo)
                 continue;
-            const cwd = readSessionCwd(file.path);
+            const cwd = (0, codexRollouts_1.readSessionCwd)(file.path);
             if (!cwd)
                 continue;
             const existing = seenCwds.get(cwd);
@@ -952,11 +751,11 @@ class CodexProvider {
         }
         folders.push(...seenCwds.values());
         // Sort: current workspace first, then by recency
-        const normalizedWorkspace = workspacePath ? normalizePath(workspacePath) : null;
+        const normalizedWorkspace = workspacePath ? (0, codexRollouts_1.normalizePath)(workspacePath) : null;
         folders.sort((a, b) => {
             if (normalizedWorkspace) {
-                const aMatch = cwdMatches(a.name, normalizedWorkspace);
-                const bMatch = cwdMatches(b.name, normalizedWorkspace);
+                const aMatch = (0, codexRollouts_1.cwdMatches)(a.name, normalizedWorkspace);
+                const bMatch = (0, codexRollouts_1.cwdMatches)(b.name, normalizedWorkspace);
                 if (aMatch && !bMatch)
                     return -1;
                 if (!aMatch && bMatch)
@@ -1074,7 +873,7 @@ class CodexProvider {
         // 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);
+            const meta = (0, codexRollouts_1.readSessionMeta)(file.path);
             if (meta &&
                 (meta.forked_from_id === sessionId || (0, codexDatabase_1.spawnParentFromSource)(meta.source) === sessionId)) {
                 const childId = (0, rolloutWalker_1.extractRolloutSessionId)(path.basename(file.path));
@@ -1187,7 +986,7 @@ class CodexProvider {
                         line: snippet.replace(/\n/g, ' '),
                         eventType: parsed.type,
                         timestamp: parsed.timestamp || '',
-                        projectPath: readSessionCwd(sessionPath) || sessionPath,
+                        projectPath: (0, codexRollouts_1.readSessionCwd)(sessionPath) || sessionPath,
                     });
                 }
                 catch {
@@ -1204,7 +1003,7 @@ class CodexProvider {
         return getSessionsDir();
     }
     getWatchRoots() {
-        return getSessionsDirs();
+        return (0, codexRollouts_1.getSessionsDirs)();
     }
     // --- Stats ---
     readSessionStats(sessionPath) {

package/dist/providers/codexRollouts.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Codex rollout-file helpers shared by the provider and by callers that only
+ * list rollouts: bounded first-line reads, session_meta and cwd lookups, and
+ * the async session-file listing. Kept apart from the provider class so a
+ * listing does not bundle the provider's stats, context and reader code.
+ */
+import type { CodexSessionMeta } from '../types/codex';
+import { DirectoryListingCache } from './directoryListingCache';
+import type { ListSessionFilesOptions, SessionFileInfo } from './types';
+/** Every directory across the monitored homes that may hold rollouts, archived ones included. */
+export declare function getSessionsDirs(): string[];
+/**
+ * Read the first N complete lines from a file using chunked reads.
+ * Handles arbitrarily long lines (Codex session_meta can be 10KB+).
+ */
+export declare function readFirstLines(filePath: string, maxLines: number, maxBytes?: number): string[];
+/** Read session_meta from the beginning of a rollout file. */
+export declare function readSessionMeta(rolloutPath: string): CodexSessionMeta | null;
+/**
+ * First line of a rollout, chunk-read under the same 256 KiB cap as
+ * readFirstLines(). `complete` is false while the line has no newline yet
+ * (a rollout that was just created) or the file could not be read, so
+ * callers know not to cache the answer.
+ */
+export declare function readFirstLineAsync(rolloutPath: string): Promise<{
+    line: string | null;
+    complete: boolean;
+}>;
+export declare function parseSessionMetaLine(line: string | null): CodexSessionMeta | null;
+export declare function readSessionCwd(rolloutPath: string): string | null;
+/** Async twin of readSessionCwd, sharing its cache so repeat listings do no content reads. */
+export declare function readSessionCwdAsync(rolloutPath: string): Promise<string | null>;
+/** Built-in enumerators report explicit zeros rather than leaving a counter unset. */
+export declare function initializeCounters(stats: ListSessionFilesOptions['stats']): void;
+/** Check if a session's CWD matches a workspace path. */
+export declare function cwdMatches(sessionCwd: string, workspacePath: string): boolean;
+/** Normalize a path using realpathSync. */
+export declare function normalizePath(input: string): string;
+/**
+ * List rollout files across the monitored Codex homes, newest first. With
+ * `workspacePath`, keeps rollouts whose session_meta cwd equals, contains, or
+ * sits inside it.
+ */
+export declare function listCodexSessionFilesAsync(workspacePath?: string, options?: ListSessionFilesOptions, cache?: DirectoryListingCache): Promise<SessionFileInfo[]>;