sidekick-shared 0.26.4 → 0.26.6

package/dist/processDetection.d.ts

@@ -0,0 +1,32 @@
+export interface RunningProcess {
+    pid: number;
+    /** The matched name (as passed to the finder). */
+    name: string;
+    /** The executable as reported by the OS (basename or image name). */
+    command: string;
+}
+export type AccountConsumerKind = 'claude-cli' | 'claude-desktop' | 'codex-cli' | 'codex-app' | 'vscode-extension-host';
+export interface RunningAccountConsumer {
+    kind: AccountConsumerKind;
+    pids: number[];
+    /** Whether a live-store switch reaches this consumer once it restarts. */
+    switched: boolean;
+    /** The user-facing sentence both UIs print for this consumer. */
+    reachability: string;
+}
+/** Sync sibling of {@link findRunningProcesses}; blocks up to 4 s. */
+export declare function findRunningProcessesSync(names: string[]): RunningProcess[];
+export declare function findRunningProcesses(names: string[]): Promise<RunningProcess[]>;
+export declare const ACCOUNT_CONSUMER_REACHABILITY: Record<AccountConsumerKind, {
+    switched: boolean;
+    reachability: string;
+}>;
+/**
+ * Which credential consumers are running right now, with the reachability
+ * sentence to show for each. Optionally scoped to one provider.
+ */
+export declare function detectRunningAccountConsumers(provider?: 'claude-code' | 'codex'): Promise<RunningAccountConsumer[]>;
+/** Sync sibling of {@link detectRunningAccountConsumers}; blocks up to 4 s. */
+export declare function detectRunningAccountConsumersSync(provider?: 'claude-code' | 'codex'): RunningAccountConsumer[];
+/** Build a consumer entry for a kind the host detects itself (e.g. its own extension host). */
+export declare function describeAccountConsumer(kind: AccountConsumerKind, pids?: number[]): RunningAccountConsumer;

package/dist/processDetection.js

@@ -0,0 +1,210 @@
+"use strict";
+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.ACCOUNT_CONSUMER_REACHABILITY = void 0;
+exports.findRunningProcessesSync = findRunningProcessesSync;
+exports.findRunningProcesses = findRunningProcesses;
+exports.detectRunningAccountConsumers = detectRunningAccountConsumers;
+exports.detectRunningAccountConsumersSync = detectRunningAccountConsumersSync;
+exports.describeAccountConsumer = describeAccountConsumer;
+/**
+ * Cross-platform detection of running CLI/app processes that hold provider
+ * credentials in memory. Bounded, never throws, never spawns a shell.
+ */
+const child_process_1 = require("child_process");
+const path = __importStar(require("path"));
+const PROBE_TIMEOUT_MS = 4000;
+const CLAUDE_NPM_ENTRY = /claude-code[\\/]cli\.js/;
+function parseUnixTable(stdout) {
+    const rows = [];
+    for (const line of stdout.split('\n')) {
+        const match = line.match(/^\s*(\d+)\s+(\S+)\s*(.*)$/);
+        if (!match)
+            continue;
+        rows.push({ pid: Number(match[1]), command: match[2], args: match[3] ?? '' });
+    }
+    return rows;
+}
+function parseWindowsCsv(stdout) {
+    const rows = [];
+    for (const line of stdout.split(/\r?\n/)) {
+        const match = line.match(/^"([^"]+)","(\d+)"/);
+        if (!match)
+            continue;
+        rows.push({ pid: Number(match[2]), command: match[1], args: '' });
+    }
+    return rows;
+}
+function matchRows(rows, names) {
+    const wanted = new Set(names);
+    const found = [];
+    for (const row of rows) {
+        if (!Number.isFinite(row.pid) || row.pid === process.pid)
+            continue;
+        const base = path.basename(row.command);
+        // The native Claude Code binary is invoked through a `claude` symlink but
+        // its executable is the versioned file (`.../versions/2.1.273`), so `comm`
+        // never says `claude`; argv[0] does.
+        const argv0 = row.args.trim().split(/\s+/)[0] ?? '';
+        const candidates = [base, base.replace(/\.exe$/i, ''), path.basename(argv0)];
+        let name = candidates.find((candidate) => candidate && wanted.has(candidate));
+        // An npm-installed `claude` runs under `node`; recognise it by its entry file.
+        if (!name &&
+            wanted.has('claude') &&
+            /^node(\.exe)?$/i.test(base) &&
+            CLAUDE_NPM_ENTRY.test(row.args)) {
+            name = 'claude';
+        }
+        if (name)
+            found.push({ pid: row.pid, name, command: row.command });
+    }
+    return found;
+}
+function probeCommand() {
+    return process.platform === 'win32'
+        ? { command: 'tasklist', args: ['/FO', 'CSV', '/NH'] }
+        : { command: 'ps', args: ['-axo', 'pid=,comm=,args='] };
+}
+function parseOutput(stdout) {
+    return process.platform === 'win32' ? parseWindowsCsv(stdout) : parseUnixTable(stdout);
+}
+/** Sync sibling of {@link findRunningProcesses}; blocks up to 4 s. */
+function findRunningProcessesSync(names) {
+    if (names.length === 0)
+        return [];
+    try {
+        const { command, args } = probeCommand();
+        const result = (0, child_process_1.spawnSync)(command, args, {
+            encoding: 'utf8',
+            maxBuffer: 16 * 1024 * 1024,
+            timeout: PROBE_TIMEOUT_MS,
+            killSignal: 'SIGKILL',
+            windowsHide: true,
+        });
+        if (result.error || result.status !== 0)
+            return [];
+        return matchRows(parseOutput(String(result.stdout ?? '')), names);
+    }
+    catch {
+        return [];
+    }
+}
+function findRunningProcesses(names) {
+    if (names.length === 0)
+        return Promise.resolve([]);
+    return new Promise((resolve) => {
+        try {
+            const { command, args } = probeCommand();
+            (0, child_process_1.execFile)(command, args, {
+                encoding: 'utf8',
+                timeout: PROBE_TIMEOUT_MS,
+                killSignal: 'SIGKILL',
+                windowsHide: true,
+                maxBuffer: 16 * 1024 * 1024,
+            }, (error, stdout) => {
+                resolve(error ? [] : matchRows(parseOutput(String(stdout ?? '')), names));
+            });
+        }
+        catch {
+            resolve([]);
+        }
+    });
+}
+const CONSUMER_PROCESS_NAMES = {
+    'claude-cli': 'claude',
+    'claude-desktop': 'Claude',
+    'codex-cli': 'codex',
+    'codex-app': 'Codex',
+};
+exports.ACCOUNT_CONSUMER_REACHABILITY = {
+    'claude-cli': {
+        switched: true,
+        reachability: 'Running claude sessions keep the previous account until restarted; a running session can rotate the refresh token of the account you just left.',
+    },
+    'claude-desktop': {
+        switched: false,
+        reachability: 'Claude Desktop is not switched by sidekick (it keeps its own web session) and its embedded engine can rotate the shared CLI token.',
+    },
+    'codex-cli': {
+        switched: true,
+        reachability: 'Running codex sessions keep the previous account until restarted.',
+    },
+    'codex-app': {
+        switched: true,
+        reachability: 'The Codex app shares the CLI login; restart it to pick up the switch. While running it can refresh and rotate the live token.',
+    },
+    'vscode-extension-host': {
+        switched: true,
+        reachability: 'The Claude Code extension host keeps the previous account until the window reloads.',
+    },
+};
+function toConsumer(kind, pids) {
+    return { kind, pids, ...exports.ACCOUNT_CONSUMER_REACHABILITY[kind] };
+}
+function groupConsumers(processes, kinds) {
+    const consumers = [];
+    for (const kind of kinds) {
+        const pids = processes.filter((p) => p.name === CONSUMER_PROCESS_NAMES[kind]).map((p) => p.pid);
+        if (pids.length > 0)
+            consumers.push(toConsumer(kind, pids));
+    }
+    return consumers;
+}
+function kindsForProvider(provider) {
+    if (provider === 'claude-code')
+        return ['claude-cli', 'claude-desktop'];
+    if (provider === 'codex')
+        return ['codex-cli', 'codex-app'];
+    return ['claude-cli', 'claude-desktop', 'codex-cli', 'codex-app'];
+}
+/**
+ * Which credential consumers are running right now, with the reachability
+ * sentence to show for each. Optionally scoped to one provider.
+ */
+async function detectRunningAccountConsumers(provider) {
+    const kinds = kindsForProvider(provider);
+    const processes = await findRunningProcesses(kinds.map((kind) => CONSUMER_PROCESS_NAMES[kind]));
+    return groupConsumers(processes, kinds);
+}
+/** Sync sibling of {@link detectRunningAccountConsumers}; blocks up to 4 s. */
+function detectRunningAccountConsumersSync(provider) {
+    const kinds = kindsForProvider(provider);
+    const processes = findRunningProcessesSync(kinds.map((kind) => CONSUMER_PROCESS_NAMES[kind]));
+    return groupConsumers(processes, kinds);
+}
+/** Build a consumer entry for a kind the host detects itself (e.g. its own extension host). */
+function describeAccountConsumer(kind, pids = []) {
+    return toConsumer(kind, pids);
+}

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;