sidekick-shared 0.27.6 → 0.28.0

package/dist/promptHistory.js

@@ -57,6 +57,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.__promptHistoryTesting = exports.DEFAULT_BOUNDS = void 0;
 exports.collectPromptHistory = collectPromptHistory;
 exports.emptyStats = emptyStats;
+exports.isPromptHistorySessionSettled = isPromptHistorySessionSettled;
+exports.parsePromptHistoryCursor = parsePromptHistoryCursor;
 exports.compareStrings = compareStrings;
 exports.resolveRoots = resolveRoots;
 exports.listCandidates = listCandidates;
@@ -65,9 +67,11 @@ const crypto_1 = require("crypto");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const humanPrompt_1 = require("./humanPrompt");
-const sessionPathResolver_1 = require("./parsers/sessionPathResolver");
-const claudeCode_1 = require("./providers/claudeCode");
-const codex_1 = require("./providers/codex");
+const claudeListing_1 = require("./providers/claudeListing");
+const codexRollouts_1 = require("./providers/codexRollouts");
+const directoryListingCache_1 = require("./providers/directoryListingCache");
+const workspaceRoots_1 = require("./workspaceRoots");
+const fileHead_1 = require("./fileHead");
 /** @internal */
 exports.DEFAULT_BOUNDS = {
     maxSessions: 1000,
@@ -78,7 +82,6 @@ exports.DEFAULT_BOUNDS = {
     deadlineMs: 30_000,
 };
 const DEFAULT_READ_CHUNK_BYTES = 1024 * 1024;
-const HEAD_BYTES = 4096;
 const MAX_EXCLUSIONS = 1000;
 const CHECK_EVERY_LINES = 500;
 const ALL_PROVIDERS = ['claude-code', 'codex'];
@@ -99,7 +102,17 @@ async function collectPromptHistory(options) {
     const cursor = { version: 3, sessions: { ...previous } };
     const entries = [];
     const exclusions = [];
+    const changed = new Map();
     let hasMore = false;
+    let progressed = false;
+    let scannedRoots = [];
+    const markChanged = (candidate) => {
+        changed.set(candidate.key, {
+            provider: candidate.provider,
+            sessionId: candidate.sessionId,
+            sessionKey: candidate.key,
+        });
+    };
     const shouldStop = () => {
         if (options.signal?.aborted)
             return 'aborted';
@@ -114,14 +127,19 @@ async function collectPromptHistory(options) {
         boundsHit: [...boundsHit],
         exclusions,
         hasMore,
+        changed: [...changed.values()],
+        progressed,
+        roots: scannedRoots,
     });
     const realpaths = new Map();
     const { roots, listingRoots } = resolveRoots(options.workspacePaths, options.includeWorktrees !== false, realpaths);
+    scannedRoots = roots;
     if (roots.length === 0)
         return finish();
     const sinceMs = options.since ? options.since.getTime() : null;
     const providers = options.providers ?? ALL_PROVIDERS;
     const candidates = rotate(await listCandidates(providers, listingRoots, sinceMs), previousNext);
+    const moved = movedSessionKeys(previous, candidates);
     const context = {
         roots,
         sinceMs,
@@ -160,7 +178,21 @@ async function collectPromptHistory(options) {
         catch {
             continue;
         }
-        const prior = validSession(previous[candidate.key]);
+        let prior = validSession(previous[candidate.key]);
+        const sessionRef = `${candidate.provider}:${candidate.sessionId}`;
+        const movedFrom = prior ? undefined : moved.get(sessionRef);
+        const carried = movedFrom ? validSession(previous[movedFrom]) : undefined;
+        // The same session under a new path (Codex archives a thread by moving its
+        // rollout): carry the entry over, but only when the new file starts with
+        // the recorded head. Another file that merely shares the id (an unlisted
+        // file is not necessarily gone) keeps its own entry and is read as new.
+        if (movedFrom && carried?.head && (await fileStartsWith(candidate.filePath, carried.head))) {
+            moved.delete(sessionRef);
+            prior = carried;
+            delete cursor.sessions[movedFrom];
+            cursor.sessions[candidate.key] = carried;
+            markChanged(candidate);
+        }
         if (prior && isSettled(prior) && prior.size === stat.size && prior.mtimeMs === stat.mtimeMs) {
             stats.sessionsSkippedUnchanged++;
             continue;
@@ -191,7 +223,15 @@ async function collectPromptHistory(options) {
             continue;
         }
         totalBytes += outcome.bytesRead;
+        for (const entry of outcome.entries)
+            entry.sessionKey = candidate.key;
         entries.push(...outcome.entries);
+        if (outcome.progressed)
+            progressed = true;
+        if (!outcome.session ||
+            JSON.stringify(outcome.session) !== JSON.stringify(previous[candidate.key])) {
+            markChanged(candidate);
+        }
         if (outcome.notInteractive)
             stats.sessionsNotInteractive++;
         else if (outcome.inScope === 0 && outcome.outOfScope > 0)
@@ -276,6 +316,33 @@ function validSession(session) {
         typeof session.mtimeMs === 'number';
     return valid ? session : undefined;
 }
+/**
+ * True when a cursor entry's last pass reached the end of its file with no
+ * prompt still waiting for its answer: an unchanged file needs no read.
+ */
+function isPromptHistorySessionSettled(session) {
+    return validSession(session) !== undefined && isSettled(session);
+}
+/**
+ * Validates a stored cursor (versions 1 to 3). Returns it as a version-3
+ * cursor with malformed session entries dropped, or undefined when it is
+ * not a cursor at all.
+ */
+function parsePromptHistoryCursor(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const candidate = value;
+    if (typeof candidate.version !== 'number' || ![1, 2, 3].includes(candidate.version)) {
+        return undefined;
+    }
+    const { sessions, next } = acceptedCursor(value);
+    const valid = {};
+    for (const [key, session] of Object.entries(sessions)) {
+        if (validSession(session))
+            valid[key] = session;
+    }
+    return { version: 3, sessions: valid, ...(next !== undefined ? { next } : {}) };
+}
 /** A session whose last pass reached the end and needs no migration. */
 function isSettled(session) {
     if (session.backlog || session.skipping)
@@ -339,53 +406,15 @@ function rotate(candidates, nextKey) {
     const index = nextKey ? candidates.findIndex((candidate) => candidate.key === nextKey) : -1;
     return index <= 0 ? candidates : [...candidates.slice(index), ...candidates.slice(0, index)];
 }
-function realpathOrNull(input, cache) {
-    const cached = cache.get(input);
-    if (cached !== undefined)
-        return cached;
-    let resolved = null;
-    try {
-        resolved = path.isAbsolute(input) ? fs.realpathSync.native(input) : null;
-    }
-    catch {
-        resolved = null;
-    }
-    cache.set(input, resolved);
-    return resolved;
-}
 /** @internal */
 function resolveRoots(workspacePaths, includeWorktrees, realpaths) {
-    const roots = new Set();
-    const listingRoots = new Set();
-    const add = (candidate) => {
-        const real = realpathOrNull(candidate, realpaths);
-        if (!real)
-            return;
-        roots.add(real);
-        listingRoots.add(real);
-        listingRoots.add(path.resolve(candidate));
-    };
-    for (const workspacePath of workspacePaths) {
-        if (typeof workspacePath !== 'string' || !path.isAbsolute(workspacePath))
-            continue;
-        add(workspacePath);
-        if (!includeWorktrees)
-            continue;
-        const real = realpathOrNull(workspacePath, realpaths);
-        if (!real)
-            continue;
-        const mainRepo = (0, sessionPathResolver_1.resolveWorktreeMainRepo)(real) ?? real;
-        add(mainRepo);
-        for (const sibling of (0, sessionPathResolver_1.discoverWorktreeSiblings)(mainRepo))
-            add(sibling);
-    }
-    return { roots: [...roots], listingRoots: [...listingRoots] };
+    return (0, workspaceRoots_1.resolveWorkspaceRoots)(workspacePaths, { includeWorktrees }, realpaths);
 }
 /** Fail-closed scope check on a recorded working directory. */
 function scopedCwd(cwd, roots, realpaths) {
     if (typeof cwd !== 'string' || cwd.length === 0)
         return null;
-    const real = realpathOrNull(cwd, realpaths);
+    const real = (0, workspaceRoots_1.realpathOrNull)(cwd, realpaths);
     if (!real)
         return null;
     for (const root of roots) {
@@ -405,11 +434,12 @@ async function listCandidates(providers, listingRoots, sinceMs) {
         if (!ALL_PROVIDERS.includes(provider))
             continue;
         // Listings are only candidate supersets; scope is re-checked per prompt.
-        const source = provider === 'claude-code' ? new claudeCode_1.ClaudeCodeProvider() : new codex_1.CodexProvider();
+        const list = provider === 'claude-code' ? claudeListing_1.listClaudeSessionFilesAsync : codexRollouts_1.listCodexSessionFilesAsync;
+        const cache = new directoryListingCache_1.DirectoryListingCache();
         for (const root of listingRoots) {
             let files;
             try {
-                files = (await source.listSessionFilesAsync?.(root, listOptions)) ?? [];
+                files = await list(root, listOptions, cache);
             }
             catch {
                 files = [];
@@ -426,18 +456,48 @@ async function listCandidates(providers, listingRoots, sinceMs) {
                 });
             }
         }
-        source.dispose();
     }
     return [...byPath.values()].sort((left, right) => compareStrings(left.provider, right.provider) ||
         compareStrings(left.sessionId, right.sessionId) ||
         compareStrings(left.key, right.key));
 }
+/** True when the file's first bytes still match a recorded head. */
+async function fileStartsWith(filePath, head) {
+    let handle;
+    try {
+        handle = await fs.promises.open(filePath, 'r');
+        return (0, fileHead_1.headMatches)(head, await readAt(handle, 0, Math.min(fileHead_1.HEAD_BYTES, head.bytes)));
+    }
+    catch {
+        return false;
+    }
+    finally {
+        await handle?.close();
+    }
+}
+/**
+ * Cursor entries whose file is no longer listed, by `provider:sessionId`, for
+ * sessions that are listed again under another path.
+ */
+function movedSessionKeys(previous, candidates) {
+    const listedKeys = new Set(candidates.map((candidate) => candidate.key));
+    const listedIds = new Set(candidates.map((candidate) => `${candidate.provider}:${candidate.sessionId}`));
+    const moved = new Map();
+    for (const [key, value] of Object.entries(previous)) {
+        if (listedKeys.has(key))
+            continue;
+        const session = validSession(value);
+        if (!session)
+            continue;
+        const id = `${session.provider}:${session.sessionId}`;
+        if (listedIds.has(id) && !moved.has(id))
+            moved.set(id, key);
+    }
+    return moved;
+}
 function hashPath(filePath) {
     return (0, crypto_1.createHash)('sha256').update(filePath).digest('hex').slice(0, 12);
 }
-function hashBytes(buffer) {
-    return (0, crypto_1.createHash)('sha256').update(buffer).digest('hex').slice(0, 32);
-}
 async function readAt(handle, offset, length) {
     const buffer = Buffer.alloc(length);
     let read = 0;
@@ -457,7 +517,7 @@ function yieldToEventLoop() {
  * Returns the head to store, or null when the file was truncated or rewritten.
  */
 async function verifyFile(handle, size, session) {
-    const headBytes = Math.min(HEAD_BYTES, size);
+    const headBytes = Math.min(fileHead_1.HEAD_BYTES, size);
     const head = await readAt(handle, 0, headBytes);
     let bytesRead = head.length;
     if (head.length !== headBytes)
@@ -466,12 +526,8 @@ async function verifyFile(handle, size, session) {
         if (session.offset > size)
             return null;
         const known = session.head;
-        if (known) {
-            if (!isOffset(known.bytes) || known.bytes > head.length)
-                return null;
-            if (hashBytes(head.subarray(0, known.bytes)) !== known.hash)
-                return null;
-        }
+        if (known && !(0, fileHead_1.headMatches)(known, head))
+            return null;
         if (session.offset > 0 && !session.skipping) {
             const before = await readAt(handle, session.offset - 1, 1);
             bytesRead += before.length;
@@ -479,7 +535,7 @@ async function verifyFile(handle, size, session) {
                 return null;
         }
     }
-    return { head: { bytes: head.length, hash: hashBytes(head) }, bytesRead };
+    return { head: (0, fileHead_1.fileHeadOf)(head), bytesRead };
 }
 /** @internal */
 async function scanFile(candidate, stat, prior, budget, context) {

package/dist/providerFailure.d.ts

@@ -1,10 +1,13 @@
 import type { AccountProviderId } from './providerIds';
-export type ProviderCredentialKind = 'oauth' | 'api-key' | 'unknown';
+export declare const PROVIDER_CREDENTIAL_KINDS: readonly ["oauth", "api-key", "unknown"];
+export type ProviderCredentialKind = (typeof PROVIDER_CREDENTIAL_KINDS)[number];
+export declare const PROVIDER_AUTHENTICATION_STATES: readonly ["authenticated", "missing", "signed-out", "expired", "rejected", "unknown"];
+export declare const PROVIDER_AUTHENTICATION_SOURCES: readonly ["local-check", "provider-response"];
 export interface ProviderAuthenticationEvidence {
     credentialKind: ProviderCredentialKind;
-    state: 'authenticated' | 'missing' | 'signed-out' | 'expired' | 'rejected' | 'unknown';
+    state: (typeof PROVIDER_AUTHENTICATION_STATES)[number];
     checkedAt: string;
-    source: 'local-check' | 'provider-response';
+    source: (typeof PROVIDER_AUTHENTICATION_SOURCES)[number];
 }
 export interface ProviderFailureInput {
     provider: AccountProviderId;
@@ -14,8 +17,10 @@ export interface ProviderFailureInput {
     /** The caller owns freshness and relevance of this separate observation. */
     authentication?: ProviderAuthenticationEvidence;
 }
-export type ProviderFailureCode = 'missing_credentials' | 'oauth_reauthentication_required' | 'api_credentials_rejected' | 'authentication_rejected' | 'invalid_provider_session' | 'service_unavailable' | 'connection_failed' | 'timeout' | 'rate_limited' | 'overloaded' | 'execution_policy_denied' | 'runtime_unavailable' | 'context_overflow' | 'unknown';
-export type ProviderRecoveryAction = 'sign_in' | 'update_credentials' | 'check_authentication' | 'start_new_session' | 'retry_later' | 'check_connection' | 'review_execution_policy' | 'repair_runtime' | 'reduce_context' | 'inspect_error';
+export declare const PROVIDER_FAILURE_CODES: readonly ["missing_credentials", "oauth_reauthentication_required", "api_credentials_rejected", "authentication_rejected", "invalid_provider_session", "service_unavailable", "connection_failed", "timeout", "rate_limited", "overloaded", "execution_policy_denied", "runtime_unavailable", "context_overflow", "unknown"];
+export type ProviderFailureCode = (typeof PROVIDER_FAILURE_CODES)[number];
+export declare const PROVIDER_RECOVERY_ACTIONS: readonly ["sign_in", "update_credentials", "check_authentication", "start_new_session", "retry_later", "check_connection", "review_execution_policy", "repair_runtime", "reduce_context", "inspect_error"];
+export type ProviderRecoveryAction = (typeof PROVIDER_RECOVERY_ACTIONS)[number];
 export type ProviderRetryAfter = {
     kind: 'delay';
     delayMs: number;
@@ -23,8 +28,9 @@ export type ProviderRetryAfter = {
     kind: 'date';
     at: string;
 };
+export declare const PROVIDER_FAILURE_EVIDENCE_SOURCES: readonly ["structured-error", "http-status", "message", "authentication-check"];
 export interface ProviderFailureEvidence {
-    source: 'structured-error' | 'http-status' | 'message' | 'authentication-check';
+    source: (typeof PROVIDER_FAILURE_EVIDENCE_SOURCES)[number];
     rule: ProviderFailureCode;
     checkedAt?: string;
 }

package/dist/providerFailure.js

@@ -1,6 +1,51 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROVIDER_FAILURE_EVIDENCE_SOURCES = exports.PROVIDER_RECOVERY_ACTIONS = exports.PROVIDER_FAILURE_CODES = exports.PROVIDER_AUTHENTICATION_SOURCES = exports.PROVIDER_AUTHENTICATION_STATES = exports.PROVIDER_CREDENTIAL_KINDS = void 0;
 exports.diagnoseProviderFailure = diagnoseProviderFailure;
+exports.PROVIDER_CREDENTIAL_KINDS = ['oauth', 'api-key', 'unknown'];
+exports.PROVIDER_AUTHENTICATION_STATES = [
+    'authenticated',
+    'missing',
+    'signed-out',
+    'expired',
+    'rejected',
+    'unknown',
+];
+exports.PROVIDER_AUTHENTICATION_SOURCES = ['local-check', 'provider-response'];
+exports.PROVIDER_FAILURE_CODES = [
+    'missing_credentials',
+    'oauth_reauthentication_required',
+    'api_credentials_rejected',
+    'authentication_rejected',
+    'invalid_provider_session',
+    'service_unavailable',
+    'connection_failed',
+    'timeout',
+    'rate_limited',
+    'overloaded',
+    'execution_policy_denied',
+    'runtime_unavailable',
+    'context_overflow',
+    'unknown',
+];
+exports.PROVIDER_RECOVERY_ACTIONS = [
+    'sign_in',
+    'update_credentials',
+    'check_authentication',
+    'start_new_session',
+    'retry_later',
+    'check_connection',
+    'review_execution_policy',
+    'repair_runtime',
+    'reduce_context',
+    'inspect_error',
+];
+exports.PROVIDER_FAILURE_EVIDENCE_SOURCES = [
+    'structured-error',
+    'http-status',
+    'message',
+    'authentication-check',
+];
 function read(value, key) {
     try {
         return value && typeof value === 'object' ? value[key] : undefined;

package/dist/providers/claudeCode.js

@@ -44,7 +44,6 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ClaudeCodeProvider = void 0;
 const fs = __importStar(require("fs"));
-const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const string_decoder_1 = require("string_decoder");
 const sessionContext_1 = require("../context/sessionContext");
@@ -57,6 +56,8 @@ const sessionPathResolver_1 = require("../parsers/sessionPathResolver");
 const subagentScanner_1 = require("../parsers/subagentScanner");
 const modelContext_1 = require("../modelContext");
 const sessionEvent_1 = require("../schemas/sessionEvent");
+const claudePaths_1 = require("../claudePaths");
+const claudeListing_1 = require("./claudeListing");
 /** Type guard for content blocks with a `type` string property */
 function isTypedBlock(block) {
     return (block !== null &&
@@ -96,22 +97,6 @@ function extractSearchableText(event) {
  * worktree suffix of it, or a directory ending in the workspace's basename.
  * Without a workspace every directory matches.
  */
-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}`));
-    };
-}
 function extractClaudeLabelFromPrefix(chunk) {
     for (const line of chunk.split('\n')) {
         const trimmed = line.trim();
@@ -368,89 +353,12 @@ class ClaudeCodeProvider {
      * event; `since` filters files and shares the caveat.
      */
     async listSessionFilesAsync(workspacePath, options = {}) {
-        const projectsRoot = this.getProjectsBaseDir();
-        if (options.stats) {
-            options.stats.directoriesListed ??= 0;
-            options.stats.directoriesStatted ??= 0;
-            options.stats.filesStatted ??= 0;
-        }
-        const root = await this.directoryCache.listDirectory(projectsRoot, () => false, {
-            revalidateRecent: options.revalidateRecent,
-            stats: options.stats,
-        });
-        if (!root) {
-            this.recordHomeStatus('listSessionFilesAsync');
-            return [];
+        try {
+            return await (0, claudeListing_1.listClaudeSessionFilesAsync)(workspacePath, options, this.directoryCache);
         }
-        const limit = options.limit !== undefined && Number.isFinite(options.limit)
-            ? Math.max(0, Math.floor(options.limit))
-            : null;
-        if (limit === 0) {
+        finally {
             this.recordHomeStatus('listSessionFilesAsync');
-            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 this.directoryCache.listDirectory(candidate.directory, (name) => this.isSessionFile(name), {
-                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: this.getSessionId(sessionPath),
-                });
-            }
-            if (limit !== null && results.length >= limit) {
-                results.sort(byNewest);
-                results.length = limit;
-                cutoffMs = results[limit - 1].mtime.getTime();
-            }
-            await new Promise((resolve) => setImmediate(resolve));
         }
-        this.recordHomeStatus('listSessionFilesAsync');
-        results.sort(byNewest);
-        return limit !== null && results.length > limit ? results.slice(0, limit) : results;
     }
     /**
      * Resolve a recursive-watch event under the projects root with one stat.
@@ -478,7 +386,7 @@ class ClaudeCodeProvider {
         const [directoryName, fileName] = segments;
         if (!this.isSessionFile(fileName))
             return { status: 'ignored' };
-        if (!workspaceDirectoryFilter(workspacePath)(directoryName))
+        if (!(0, claudeListing_1.workspaceDirectoryFilter)(workspacePath)(directoryName))
             return { status: 'ignored' };
         const sessionId = this.getSessionId(fullPath);
         const stat = await this.directoryCache.refreshFile(fullPath);
@@ -593,7 +501,7 @@ class ClaudeCodeProvider {
         return results;
     }
     getProjectsBaseDir() {
-        return path.join(os.homedir(), '.claude', 'projects');
+        return (0, claudePaths_1.getClaudeProjectsDir)();
     }
     getWatchRoots() {
         return [this.getProjectsBaseDir()];

package/dist/providers/claudeListing.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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.
+ */
+import { DirectoryListingCache } from './directoryListingCache';
+import type { ListSessionFilesOptions, SessionFileInfo } from './types';
+/** Matches project directory names that may hold sessions for `workspacePath`. */
+export declare function workspaceDirectoryFilter(workspacePath?: string): (directoryName: string) => boolean;
+/**
+ * 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.
+ */
+export declare function listClaudeSessionFilesAsync(workspacePath?: string, options?: ListSessionFilesOptions, cache?: DirectoryListingCache): Promise<SessionFileInfo[]>;