sidekick-shared 0.26.4 → 0.26.5

package/dist/providers/claudeCode.d.ts

@@ -9,7 +9,7 @@
  */
 import type { ReadSessionContextSnapshotOptions, SessionContextSnapshot } from '../context/sessionContext';
 import type { SubagentStats, TokenUsage } from '../types/sessionEvent';
-import type { SessionProviderBase, SessionReader, SessionFileInfo, SessionFileStats, SearchHit, ProjectFolderInfo, ProviderId, ProviderOperationStatus, ProviderRuntimeStatus, SessionProviderOptions } from './types';
+import type { ListSessionFilesOptions, SessionProviderBase, SessionReader, SessionFileInfo, SessionFileStats, SearchHit, ProjectFolderInfo, ProviderId, ProviderOperationStatus, ProviderRuntimeStatus, SessionProviderOptions, WatchedSessionFile } from './types';
 /**
  * Session provider for Claude Code CLI.
  *
@@ -23,6 +23,8 @@ export declare class ClaudeCodeProvider implements SessionProviderBase {
     private readonly diagnostics;
     /** Runtime-reported context window limit (overrides static map when set). */
     private dynamicContextWindowLimit;
+    /** Project-directory listings reused across async enumerations. */
+    private readonly directoryCache;
     constructor(options?: SessionProviderOptions);
     getSessionDirectory(workspacePath: string): string;
     discoverSessionDirectory(workspacePath: string): string | null;
@@ -34,7 +36,26 @@ export declare class ClaudeCodeProvider implements SessionProviderBase {
     findSessionsInDirectory(dir: string): string[];
     getAllProjectFolders(workspacePath?: string): ProjectFolderInfo[];
     listAllSessionFiles(): SessionFileInfo[];
-    listSessionFilesAsync(workspacePath?: string): Promise<SessionFileInfo[]>;
+    /**
+     * 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.
+     */
+    listSessionFilesAsync(workspacePath?: string, options?: ListSessionFilesOptions): Promise<SessionFileInfo[]>;
+    /**
+     * Resolve a recursive-watch event under the projects root with one stat.
+     * Sessions live exactly one directory below the root; deeper paths are
+     * subagent transcripts and are ignored. A path at the root itself is a
+     * project directory appearing or vanishing, which needs a full listing.
+     */
+    statWatchedSessionFile(root: string, relativePath: string, workspacePath?: string): Promise<WatchedSessionFile>;
     isSessionFile(filename: string): boolean;
     getSessionId(sessionPath: string): string;
     encodeWorkspacePath(workspacePath: string): string;

package/dist/providers/claudeCode.js

@@ -51,6 +51,7 @@ const sessionContext_1 = require("../context/sessionContext");
 const sessionStats_1 = require("../sessionStats");
 const jsonl_1 = require("../parsers/jsonl");
 const diagnostics_1 = require("./diagnostics");
+const directoryListingCache_1 = require("./directoryListingCache");
 const sessionPathResolver_1 = require("../parsers/sessionPathResolver");
 const subagentScanner_1 = require("../parsers/subagentScanner");
 const modelContext_1 = require("../modelContext");
@@ -90,6 +91,27 @@ function extractSearchableText(event) {
     }
     return '';
 }
+/**
+ * Project-directory filter for a workspace: the encoded workspace path, a
+ * 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();
@@ -284,6 +306,8 @@ class ClaudeCodeProvider {
     diagnostics;
     /** Runtime-reported context window limit (overrides static map when set). */
     dynamicContextWindowLimit = null;
+    /** Project-directory listings reused across async enumerations. */
+    directoryCache = new directoryListingCache_1.DirectoryListingCache();
     constructor(options = {}) {
         this.diagnostics = new diagnostics_1.ProviderDiagnosticTracker(this.id, options);
     }
@@ -364,77 +388,144 @@ class ClaudeCodeProvider {
         this.recordHomeStatus('listAllSessionFiles');
         return results;
     }
-    async listSessionFilesAsync(workspacePath) {
+    /**
+     * 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 listSessionFilesAsync(workspacePath, options = {}) {
         const projectsRoot = this.getProjectsBaseDir();
-        let projectEntries = [];
-        try {
-            projectEntries = await fs.promises.readdir(projectsRoot, { withFileTypes: true });
+        if (options.stats) {
+            options.stats.directoriesListed ??= 0;
+            options.stats.directoriesStatted ??= 0;
+            options.stats.filesStatted ??= 0;
         }
-        catch {
+        const root = await this.directoryCache.listDirectory(projectsRoot, () => false, {
+            revalidateRecent: options.revalidateRecent,
+            stats: options.stats,
+        });
+        if (!root) {
             this.recordHomeStatus('listSessionFilesAsync');
             return [];
         }
-        const encodedWorkspace = workspacePath ? (0, sessionPathResolver_1.encodeWorkspacePath)(workspacePath).toLowerCase() : null;
-        const workspaceBasename = workspacePath
-            ? path
-                .basename(workspacePath)
-                .replace(/[^a-zA-Z0-9]/g, '-')
-                .toLowerCase()
+        const limit = options.limit !== undefined && Number.isFinite(options.limit)
+            ? Math.max(0, Math.floor(options.limit))
             : null;
-        const directories = [];
-        for (const entry of projectEntries) {
-            const directory = path.join(projectsRoot, entry.name);
+        if (limit === 0) {
+            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 = entry.isDirectory() ? null : await fs.promises.stat(directory);
-                if (!entry.isDirectory() && !stat?.isDirectory())
-                    continue;
+                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;
             }
-            const name = entry.name.toLowerCase();
-            if (encodedWorkspace &&
-                name !== encodedWorkspace &&
-                !name.startsWith(`${encodedWorkspace}-`) &&
-                name !== workspaceBasename &&
-                !name.endsWith(`-${workspaceBasename}`)) {
+            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();
             }
-            directories.push(directory);
             await new Promise((resolve) => setImmediate(resolve));
         }
-        const results = [];
-        for (const directory of directories) {
-            let entries = [];
+        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.
+     * Sessions live exactly one directory below the root; deeper paths are
+     * subagent transcripts and are ignored. A path at the root itself is a
+     * project directory appearing or vanishing, which needs a full listing.
+     */
+    async statWatchedSessionFile(root, relativePath, workspacePath) {
+        const segments = (0, directoryListingCache_1.splitWatchedPath)(relativePath);
+        if (!segments)
+            return { status: 'unknown' };
+        if (segments.length > 2)
+            return { status: 'ignored' };
+        const fullPath = path.join(root, ...segments);
+        if (segments.length === 1) {
+            this.directoryCache.invalidate(fullPath);
             try {
-                entries = await fs.promises.readdir(directory, { withFileTypes: true });
+                const stat = await fs.promises.stat(fullPath);
+                return stat.isDirectory() ? { status: 'unknown' } : { status: 'ignored' };
             }
             catch {
-                continue;
-            }
-            for (const entry of entries) {
-                if (!entry.isFile() || !this.isSessionFile(entry.name))
-                    continue;
-                const sessionPath = path.join(directory, entry.name);
-                try {
-                    const stat = await fs.promises.stat(sessionPath);
-                    if (stat.size > 0) {
-                        results.push({
-                            path: sessionPath,
-                            mtime: stat.mtime,
-                            sizeBytes: stat.size,
-                            sessionId: this.getSessionId(sessionPath),
-                        });
-                    }
-                }
-                catch {
-                    // Skip files that vanish between discovery and stat.
-                }
-                await new Promise((resolve) => setImmediate(resolve));
+                return { status: 'unknown' };
             }
         }
-        this.recordHomeStatus('listSessionFilesAsync');
-        return results.sort((left, right) => right.mtime.getTime() - left.mtime.getTime());
+        const [directoryName, fileName] = segments;
+        if (!this.isSessionFile(fileName))
+            return { status: 'ignored' };
+        if (!workspaceDirectoryFilter(workspacePath)(directoryName))
+            return { status: 'ignored' };
+        const sessionId = this.getSessionId(fullPath);
+        const stat = await this.directoryCache.refreshFile(fullPath);
+        if (!stat || stat.sizeBytes <= 0)
+            return { status: 'missing', path: fullPath, sessionId };
+        return {
+            status: 'present',
+            file: {
+                path: fullPath,
+                mtime: new Date(stat.mtimeMs),
+                sizeBytes: stat.sizeBytes,
+                sessionId,
+            },
+        };
     }
     // --- File identification ---
     isSessionFile(filename) {
@@ -627,6 +718,7 @@ class ClaudeCodeProvider {
     // --- Lifecycle ---
     dispose() {
         this.dynamicContextWindowLimit = null;
+        this.directoryCache.invalidate();
     }
     recordHomeStatus(operation) {
         const status = this.getRuntimeStatus();

package/dist/providers/codex.d.ts

@@ -9,7 +9,7 @@
  * Ported from sidekick-vscode/src/services/providers/CodexSessionProvider.ts
  */
 import type { ReadSessionContextSnapshotOptions, SessionContextSnapshot } from '../context/sessionContext';
-import type { SessionProviderBase, SessionReader, ProjectFolderInfo, SearchHit, SessionFileInfo, SessionFileStats, ProviderId, ProviderOperationStatus, ProviderRuntimeStatus, SessionProviderOptions } from './types';
+import type { ListSessionFilesOptions, SessionProviderBase, SessionReader, ProjectFolderInfo, SearchHit, SessionFileInfo, SessionFileStats, ProviderId, ProviderOperationStatus, ProviderRuntimeStatus, SessionProviderOptions, WatchedSessionFile } from './types';
 import type { SubagentStats, TokenUsage } from '../types/sessionEvent';
 import type { CodexRateLimits } from '../types/codex';
 export interface FindCodexRolloutFileOptions {
@@ -48,6 +48,8 @@ export declare class CodexProvider implements SessionProviderBase {
     private dynamicContextWindowLimit;
     private lastRateLimitsData;
     private lastTokenUsageData;
+    /** Dated rollout-directory listings reused across async enumerations. */
+    private readonly directoryCache;
     constructor(options?: SessionProviderOptions);
     /** Lazy-initialize database connection. */
     private ensureDb;
@@ -69,7 +71,13 @@ export declare class CodexProvider implements SessionProviderBase {
     findSessionFiles(workspacePath: string): string[];
     findSessionsInDirectory(dir: string): string[];
     listAllSessionFiles(): SessionFileInfo[];
-    listSessionFilesAsync(workspacePath?: string): Promise<SessionFileInfo[]>;
+    listSessionFilesAsync(workspacePath?: string, options?: ListSessionFilesOptions): Promise<SessionFileInfo[]>;
+    /**
+     * 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.
+     */
+    statWatchedSessionFile(root: string, relativePath: string, workspacePath?: string): Promise<WatchedSessionFile>;
     getAllProjectFolders(workspacePath?: string): ProjectFolderInfo[];
     isSessionFile(filename: string): boolean;
     getSessionId(sessionPath: string): string;

package/dist/providers/codex.js

@@ -54,6 +54,7 @@ const codexParser_1 = require("../parsers/codexParser");
 const codexDatabase_1 = require("./codexDatabase");
 const codexProfiles_1 = require("../codexProfiles");
 const rolloutWalker_1 = require("./rolloutWalker");
+const directoryListingCache_1 = require("./directoryListingCache");
 const diagnostics_1 = require("./diagnostics");
 const modelContext_1 = require("../modelContext");
 const observedContextWindows_1 = require("../observedContextWindows");
@@ -193,7 +194,13 @@ function readSessionMeta(rolloutPath) {
     }
     return null;
 }
-async function readSessionMetaAsync(rolloutPath) {
+/**
+ * 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.
@@ -216,18 +223,26 @@ async function readSessionMetaAsync(rolloutPath) {
             newlineFound = chunk.includes(0x0a);
         }
         const firstLine = Buffer.concat(chunks).toString('utf8').split('\n', 1)[0]?.trim();
-        if (!firstLine)
-            return null;
-        const parsed = JSON.parse(firstLine);
-        return parsed.type === 'session_meta' ? parsed.payload : null;
+        return { line: firstLine || null, complete: newlineFound || totalRead >= maxBytes };
     }
     catch {
-        return null;
+        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
@@ -257,11 +272,23 @@ async function readSessionCwdAsync(rolloutPath) {
     const cached = cwdCache.get(rolloutPath);
     if (cached !== undefined)
         return cached;
-    const meta = await readSessionMetaAsync(rolloutPath);
-    const cwd = meta?.cwd || null;
-    rememberCwd(rolloutPath, cwd);
+    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);
@@ -646,6 +673,8 @@ class CodexProvider {
     dynamicContextWindowLimit = null;
     lastRateLimitsData = null;
     lastTokenUsageData = null;
+    /** Dated rollout-directory listings reused across async enumerations. */
+    directoryCache = new directoryListingCache_1.DirectoryListingCache();
     constructor(options = {}) {
         this.diagnostics = new diagnostics_1.ProviderDiagnosticTracker(this.id, options);
     }
@@ -802,10 +831,22 @@ class CodexProvider {
         this.recordDatabaseFallback('listAllSessionFiles', true);
         return files;
     }
-    async listSessionFilesAsync(workspacePath) {
+    async listSessionFilesAsync(workspacePath, options = {}) {
         const results = [];
-        // One capped walk across the homes (deduplicated, newest first).
-        for (const file of await (0, rolloutWalker_1.walkRolloutFilesAsync)(getSessionsDirs())) {
+        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);
@@ -821,6 +862,47 @@ class CodexProvider {
         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 = (0, directoryListingCache_1.splitWatchedPath)(relativePath);
+        if (!segments)
+            return { status: 'unknown' };
+        const fullPath = path.join(root, ...segments);
+        const name = segments[segments.length - 1];
+        if (segments.length - 1 > rolloutWalker_1.DEFAULT_ROLLOUT_WALK_MAX_DEPTH)
+            return { status: 'ignored' };
+        if (!(0, rolloutWalker_1.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 = (0, rolloutWalker_1.extractRolloutSessionId)(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();
@@ -1153,6 +1235,7 @@ class CodexProvider {
         this.dynamicContextWindowLimit = null;
         this.lastRateLimitsData = null;
         this.lastTokenUsageData = null;
+        this.directoryCache.invalidate();
     }
     recordDatabaseFallback(operation, usable) {
         if (!this.dbInitialized) {

package/dist/providers/directoryListingCache.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Directory listings keyed by path and validated by the directory's own
+ * mtime and inode.
+ *
+ * A create, delete, or rename inside a directory bumps that directory's
+ * mtime; an append to an existing file does not. So a listing can be reused
+ * for as long as the directory's mtime and inode are unchanged, and the per
+ * file size/mtime it carries is only refreshed by `refreshFile()` (the watch
+ * event path) or by `revalidateRecent` on catch-up passes. Full discovery is
+ * then one stat per directory instead of one readdir per directory plus one
+ * stat per file.
+ *
+ * @module providers/directoryListingCache
+ */
+import * as fs from 'fs';
+export interface CachedFileStat {
+    sizeBytes: number;
+    mtimeMs: number;
+}
+export interface CachedDirectoryListing {
+    /** Directory mtime when the listing was taken. */
+    mtimeMs: number;
+    ino: number;
+    /** Wall-clock time the listing was taken (coarse-mtime guard). */
+    listedAtMs: number;
+    /** Files accepted by the caller's filter, with the stat seen last. */
+    files: Map<string, CachedFileStat>;
+    /** Subdirectory names, unsorted. */
+    subdirectories: string[];
+}
+/** Payload-free counters a caller can pass to measure what a pass cost. */
+export interface DirectoryListingCounters {
+    directoriesListed?: number;
+    directoriesStatted?: number;
+    filesStatted?: number;
+}
+export interface DirectoryListingCacheOptions {
+    /** Bound on cached directories, least-recently-used first (default 10 000). */
+    maxDirectories?: number;
+    /**
+     * Files whose cached mtime is within this window are re-stat'ed when a
+     * caller asks for `revalidateRecent` (default 30 minutes).
+     */
+    recentWindowMs?: number;
+}
+export interface ListDirectoryOptions {
+    /** Re-stat files modified within the recent window even if the directory is unchanged. */
+    revalidateRecent?: boolean;
+    /** A stat of the directory the caller already took; saves one syscall. */
+    dirStat?: fs.Stats;
+    stats?: DirectoryListingCounters;
+}
+export declare const DEFAULT_DIRECTORY_CACHE_MAX_DIRECTORIES = 10000;
+export declare const DEFAULT_DIRECTORY_CACHE_RECENT_WINDOW_MS: number;
+export declare class DirectoryListingCache {
+    private readonly listings;
+    private readonly maxDirectories;
+    private readonly recentWindowMs;
+    constructor(options?: DirectoryListingCacheOptions);
+    get size(): number;
+    /** The cached listing without touching the filesystem, if any. */
+    peek(dir: string): CachedDirectoryListing | undefined;
+    /**
+     * List `dir`, reusing the cached listing when the directory is unchanged.
+     * Returns null when `dir` is missing, unreadable, or not a directory.
+     */
+    listDirectory(dir: string, accept: (name: string) => boolean, options?: ListDirectoryOptions): Promise<CachedDirectoryListing | null>;
+    /**
+     * Stat one file and reflect the result in its parent's cached listing when
+     * that listing exists. Returns null when the path is missing or not a file.
+     * Never creates a listing: a partial listing must not pass for a full one.
+     */
+    refreshFile(fullPath: string, stats?: DirectoryListingCounters): Promise<CachedFileStat | null>;
+    /** Drop one directory's listing, or every listing. */
+    invalidate(dir?: string): void;
+    private revalidateRecent;
+    private isRecent;
+    private touch;
+}
+/**
+ * Split a watcher-reported root-relative path into segments. Both separators
+ * are accepted (Windows watchers report backslashes). Returns null for an
+ * empty path or one that escapes the root.
+ */
+export declare function splitWatchedPath(relativePath: string): string[] | null;