sidekick-shared 0.26.4 → 0.26.5

package/dist/providers/directoryListingCache.js

@@ -0,0 +1,244 @@
+"use strict";
+/**
+ * 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
+ */
+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.DirectoryListingCache = exports.DEFAULT_DIRECTORY_CACHE_RECENT_WINDOW_MS = exports.DEFAULT_DIRECTORY_CACHE_MAX_DIRECTORIES = void 0;
+exports.splitWatchedPath = splitWatchedPath;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+exports.DEFAULT_DIRECTORY_CACHE_MAX_DIRECTORIES = 10_000;
+exports.DEFAULT_DIRECTORY_CACHE_RECENT_WINDOW_MS = 30 * 60_000;
+/**
+ * A directory whose mtime is within this many milliseconds of the moment it
+ * was listed may still receive entries that land on the same coarse mtime
+ * (HFS+, exFAT, SMB), so it is re-listed rather than trusted.
+ */
+const COARSE_MTIME_GUARD_MS = 2_000;
+class DirectoryListingCache {
+    listings = new Map();
+    maxDirectories;
+    recentWindowMs;
+    constructor(options = {}) {
+        this.maxDirectories = Math.max(1, Math.floor(options.maxDirectories ?? exports.DEFAULT_DIRECTORY_CACHE_MAX_DIRECTORIES));
+        this.recentWindowMs = Math.max(0, options.recentWindowMs ?? exports.DEFAULT_DIRECTORY_CACHE_RECENT_WINDOW_MS);
+    }
+    get size() {
+        return this.listings.size;
+    }
+    /** The cached listing without touching the filesystem, if any. */
+    peek(dir) {
+        return this.listings.get(dir);
+    }
+    /**
+     * List `dir`, reusing the cached listing when the directory is unchanged.
+     * Returns null when `dir` is missing, unreadable, or not a directory.
+     */
+    async listDirectory(dir, accept, options = {}) {
+        let dirStat = options.dirStat;
+        if (!dirStat) {
+            try {
+                dirStat = await fs.promises.stat(dir);
+                count(options.stats, 'directoriesStatted');
+            }
+            catch {
+                this.listings.delete(dir);
+                return null;
+            }
+        }
+        if (!dirStat.isDirectory()) {
+            this.listings.delete(dir);
+            return null;
+        }
+        const cached = this.listings.get(dir);
+        const unchanged = cached !== undefined &&
+            cached.mtimeMs === dirStat.mtimeMs &&
+            cached.ino === dirStat.ino &&
+            dirStat.mtimeMs < cached.listedAtMs - COARSE_MTIME_GUARD_MS;
+        if (cached && unchanged) {
+            this.touch(dir, cached);
+            if (options.revalidateRecent)
+                await this.revalidateRecent(dir, cached, options.stats);
+            return cached;
+        }
+        let entries;
+        try {
+            entries = await fs.promises.readdir(dir, { withFileTypes: true });
+            count(options.stats, 'directoriesListed');
+        }
+        catch {
+            this.listings.delete(dir);
+            return null;
+        }
+        const listedAtMs = Date.now();
+        const files = new Map();
+        const subdirectories = [];
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                subdirectories.push(entry.name);
+                continue;
+            }
+            const isCandidateFile = entry.isFile() && accept(entry.name);
+            if (!isCandidateFile && !entry.isSymbolicLink())
+                continue;
+            const fullPath = path.join(dir, entry.name);
+            // A file already in the listing keeps its cached stat unless it is
+            // recent enough to be live; a directory change is a create, delete, or
+            // rename, and only the new names need a fresh stat.
+            const previous = cached?.files.get(entry.name);
+            if (isCandidateFile && previous && !this.isRecent(previous, listedAtMs)) {
+                files.set(entry.name, previous);
+                continue;
+            }
+            if (entry.isSymbolicLink() && !accept(entry.name)) {
+                // Symlinked directories are followed so linked project folders count.
+                try {
+                    const target = await fs.promises.stat(fullPath);
+                    count(options.stats, 'directoriesStatted');
+                    if (target.isDirectory())
+                        subdirectories.push(entry.name);
+                }
+                catch {
+                    // Dangling link.
+                }
+                continue;
+            }
+            try {
+                const stat = await fs.promises.stat(fullPath);
+                count(options.stats, 'filesStatted');
+                if (stat.isFile())
+                    files.set(entry.name, { sizeBytes: stat.size, mtimeMs: stat.mtimeMs });
+                else if (stat.isDirectory())
+                    subdirectories.push(entry.name);
+            }
+            catch {
+                // Vanished between readdir and stat.
+            }
+        }
+        const listing = {
+            mtimeMs: dirStat.mtimeMs,
+            ino: dirStat.ino,
+            listedAtMs,
+            files,
+            subdirectories,
+        };
+        this.touch(dir, listing);
+        return listing;
+    }
+    /**
+     * 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.
+     */
+    async refreshFile(fullPath, stats) {
+        const dir = path.dirname(fullPath);
+        const name = path.basename(fullPath);
+        const listing = this.listings.get(dir);
+        try {
+            const stat = await fs.promises.stat(fullPath);
+            count(stats, 'filesStatted');
+            if (!stat.isFile()) {
+                listing?.files.delete(name);
+                return null;
+            }
+            const fileStat = { sizeBytes: stat.size, mtimeMs: stat.mtimeMs };
+            listing?.files.set(name, fileStat);
+            return fileStat;
+        }
+        catch {
+            listing?.files.delete(name);
+            return null;
+        }
+    }
+    /** Drop one directory's listing, or every listing. */
+    invalidate(dir) {
+        if (dir === undefined)
+            this.listings.clear();
+        else
+            this.listings.delete(dir);
+    }
+    async revalidateRecent(dir, listing, stats) {
+        const now = Date.now();
+        for (const [name, cached] of [...listing.files]) {
+            if (!this.isRecent(cached, now))
+                continue;
+            await this.refreshFile(path.join(dir, name), stats);
+        }
+    }
+    isRecent(stat, now) {
+        return now - stat.mtimeMs <= this.recentWindowMs;
+    }
+    touch(dir, listing) {
+        this.listings.delete(dir);
+        this.listings.set(dir, listing);
+        while (this.listings.size > this.maxDirectories) {
+            const oldest = this.listings.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.listings.delete(oldest);
+        }
+    }
+}
+exports.DirectoryListingCache = DirectoryListingCache;
+/**
+ * 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.
+ */
+function splitWatchedPath(relativePath) {
+    const segments = relativePath.split(/[\\/]+/).filter((segment) => segment.length > 0);
+    if (segments.length === 0)
+        return null;
+    if (segments.some((segment) => segment === '.' || segment === '..'))
+        return null;
+    return segments;
+}
+function count(stats, field) {
+    if (!stats)
+        return;
+    stats[field] = (stats[field] ?? 0) + 1;
+}

package/dist/providers/rolloutWalker.d.ts

@@ -8,14 +8,20 @@
  * `limit` can stop early, stats each file exactly once, and returns results
  * newest first with the size and session id already attached.
  *
- * With `limit`, the early exit is by directory date: a rollout that was
- * created days ago but is still being written lands in its creation day's
- * directory, so a very small limit can miss it in favour of newer-dated,
- * older-modified files. Callers that need exact mtime order over the whole
- * history omit `limit` (the `maxFiles` cap still applies).
+ * With `limit` or `since`, the early exit is by directory date: a rollout
+ * that was created days ago but is still being written lands in its creation
+ * day's directory, so a very small limit (or a recent `since`) can miss it in
+ * favour of newer-dated, older-modified files. Callers that need exact mtime
+ * order over the whole history omit both (the `maxFiles` cap still applies);
+ * a live session missed this way is picked up by its next watch event.
+ *
+ * The async walker accepts a {@link DirectoryListingCache}: unchanged
+ * directories are then one stat each instead of a readdir plus a stat per
+ * file, which is what makes repeated discovery over a large history cheap.
  *
  * @module providers/rolloutWalker
  */
+import type { DirectoryListingCache, DirectoryListingCounters } from './directoryListingCache';
 export interface RolloutFileInfo {
     path: string;
     mtime: Date;
@@ -30,10 +36,21 @@ export interface WalkRolloutFilesOptions {
     maxFiles?: number;
     /** Stop once this many files are collected, visiting newest-dated directories first. */
     limit?: number;
+    /**
+     * Skip files modified before this epoch-ms, and skip dated directories
+     * whose whole day, month, or year ended more than a day before it.
+     */
+    since?: number;
     /** Only files whose name carries this session id (case-insensitive). */
     sessionId?: string;
     /** Include zero-byte files (default false). */
     includeEmpty?: boolean;
+    /** Reuse directory listings across walks (async walker only). */
+    cache?: DirectoryListingCache;
+    /** With `cache`: re-stat recently modified files even in unchanged directories. */
+    revalidateRecent?: boolean;
+    /** Payload-free counters of what the walk cost. */
+    stats?: DirectoryListingCounters;
 }
 export declare const DEFAULT_ROLLOUT_WALK_MAX_DEPTH = 6;
 export declare const DEFAULT_ROLLOUT_WALK_MAX_FILES = 20000;
@@ -44,6 +61,12 @@ export declare function isRolloutFile(filename: string): boolean;
  * Format: rollout-<timestamp>-<uuid>.jsonl -> <uuid>
  */
 export declare function extractRolloutSessionId(filename: string): string;
+/**
+ * True when `segments` (the directory names below the root, e.g. `['2026',
+ * '09', '04']`) are all numeric and describe a year, month, or day that ended
+ * more than a day before `since`. Non-numeric names are never pruned.
+ */
+export declare function isDatedDirectoryBefore(segments: readonly string[], since: number): boolean;
 /**
  * Walk one or more `sessions` roots for rollout files, newest first.
  * Missing or unreadable directories are skipped; paths are deduplicated.

package/dist/providers/rolloutWalker.js

@@ -9,11 +9,16 @@
  * `limit` can stop early, stats each file exactly once, and returns results
  * newest first with the size and session id already attached.
  *
- * With `limit`, the early exit is by directory date: a rollout that was
- * created days ago but is still being written lands in its creation day's
- * directory, so a very small limit can miss it in favour of newer-dated,
- * older-modified files. Callers that need exact mtime order over the whole
- * history omit `limit` (the `maxFiles` cap still applies).
+ * With `limit` or `since`, the early exit is by directory date: a rollout
+ * that was created days ago but is still being written lands in its creation
+ * day's directory, so a very small limit (or a recent `since`) can miss it in
+ * favour of newer-dated, older-modified files. Callers that need exact mtime
+ * order over the whole history omit both (the `maxFiles` cap still applies);
+ * a live session missed this way is picked up by its next watch event.
+ *
+ * The async walker accepts a {@link DirectoryListingCache}: unchanged
+ * directories are then one stat each instead of a readdir plus a stat per
+ * file, which is what makes repeated discovery over a large history cheap.
  *
  * @module providers/rolloutWalker
  */
@@ -54,6 +59,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_ROLLOUT_WALK_MAX_FILES = exports.DEFAULT_ROLLOUT_WALK_MAX_DEPTH = void 0;
 exports.isRolloutFile = isRolloutFile;
 exports.extractRolloutSessionId = extractRolloutSessionId;
+exports.isDatedDirectoryBefore = isDatedDirectoryBefore;
 exports.walkRolloutFiles = walkRolloutFiles;
 exports.walkRolloutFilesAsync = walkRolloutFilesAsync;
 const fs = __importStar(require("fs"));
@@ -90,8 +96,12 @@ function walkState(options) {
         seen: new Set(),
         cap: Math.min(maxFiles, limit),
         maxDepth: options.maxDepth ?? exports.DEFAULT_ROLLOUT_WALK_MAX_DEPTH,
+        since: options.since !== undefined && Number.isFinite(options.since) ? options.since : null,
         sessionId: options.sessionId ? options.sessionId.trim().toLowerCase() : null,
         includeEmpty: options.includeEmpty ?? false,
+        cache: options.cache ?? null,
+        revalidateRecent: options.revalidateRecent ?? false,
+        stats: options.stats,
     };
 }
 /** Newest-dated first: directory and file names sort descending. */
@@ -106,12 +116,14 @@ function matchesFilter(state, name) {
 function record(state, fullPath, name, stat) {
     if (!state.includeEmpty && stat.size <= 0)
         return;
+    if (state.since !== null && stat.mtimeMs < state.since)
+        return;
     if (state.seen.has(fullPath))
         return;
     state.seen.add(fullPath);
     state.results.push({
         path: fullPath,
-        mtime: stat.mtime,
+        mtime: new Date(stat.mtimeMs),
         sizeBytes: stat.size,
         sessionId: extractRolloutSessionId(name),
     });
@@ -119,9 +131,38 @@ function record(state, fullPath, name, stat) {
 function finish(state) {
     return state.results.sort((a, b) => b.mtime.getTime() - a.mtime.getTime());
 }
-function visitSync(state, dir, depth) {
+/** Slack added to a dated directory's range so a timezone skew cannot prune a live day. */
+const DATE_DIR_SLACK_MS = 24 * 60 * 60_000;
+/**
+ * True when `segments` (the directory names below the root, e.g. `['2026',
+ * '09', '04']`) are all numeric and describe a year, month, or day that ended
+ * more than a day before `since`. Non-numeric names are never pruned.
+ */
+function isDatedDirectoryBefore(segments, since) {
+    if (segments.length === 0 || segments.length > 3)
+        return false;
+    const numbers = segments.map((segment) => (/^\d+$/.test(segment) ? Number(segment) : NaN));
+    if (numbers.some((value) => !Number.isFinite(value)))
+        return false;
+    const [year, month, day] = numbers;
+    if (year < 1970 || year > 9999)
+        return false;
+    if (segments.length >= 2 && (month < 1 || month > 12))
+        return false;
+    if (segments.length === 3 && (day < 1 || day > 31))
+        return false;
+    const rangeEnd = segments.length === 1
+        ? new Date(year + 1, 0, 1).getTime()
+        : segments.length === 2
+            ? new Date(year, month, 1).getTime()
+            : new Date(year, month - 1, day + 1).getTime();
+    return rangeEnd + DATE_DIR_SLACK_MS < since;
+}
+function visitSync(state, dir, depth, segments) {
     if (depth > state.maxDepth || state.results.length >= state.cap)
         return;
+    if (state.since !== null && isDatedDirectoryBefore(segments, state.since))
+        return;
     let entries;
     try {
         entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -146,8 +187,9 @@ function visitSync(state, dir, depth) {
     for (const entry of entries) {
         if (state.results.length >= state.cap)
             return;
-        if (entry.isDirectory())
-            visitSync(state, path.join(dir, entry.name), depth + 1);
+        if (entry.isDirectory()) {
+            visitSync(state, path.join(dir, entry.name), depth + 1, [...segments, entry.name]);
+        }
     }
 }
 /**
@@ -157,18 +199,52 @@ function visitSync(state, dir, depth) {
 function walkRolloutFiles(roots, options = {}) {
     const state = walkState(options);
     for (const root of roots)
-        visitSync(state, root, 0);
+        visitSync(state, root, 0, []);
     return finish(state);
 }
 function yieldToEventLoop() {
     return new Promise((resolve) => setImmediate(resolve));
 }
-async function visitAsync(state, dir, depth) {
+function byStringDescending(a, b) {
+    return b.localeCompare(a);
+}
+async function visitCached(state, cache, dir, depth, segments) {
     if (depth > state.maxDepth || state.results.length >= state.cap)
         return;
+    if (state.since !== null && isDatedDirectoryBefore(segments, state.since))
+        return;
+    const listing = await cache.listDirectory(dir, (name) => matchesFilter(state, name), {
+        revalidateRecent: state.revalidateRecent,
+        stats: state.stats,
+    });
+    if (!listing)
+        return;
+    const names = [...listing.files.keys()].sort(byStringDescending);
+    for (const name of names) {
+        if (state.results.length >= state.cap)
+            return;
+        const stat = listing.files.get(name);
+        if (!stat)
+            continue;
+        record(state, path.join(dir, name), name, { size: stat.sizeBytes, mtimeMs: stat.mtimeMs });
+    }
+    await yieldToEventLoop();
+    for (const name of [...listing.subdirectories].sort(byStringDescending)) {
+        if (state.results.length >= state.cap)
+            return;
+        await visitCached(state, cache, path.join(dir, name), depth + 1, [...segments, name]);
+    }
+}
+async function visitAsync(state, dir, depth, segments) {
+    if (depth > state.maxDepth || state.results.length >= state.cap)
+        return;
+    if (state.since !== null && isDatedDirectoryBefore(segments, state.since))
+        return;
     let entries;
     try {
         entries = await fs.promises.readdir(dir, { withFileTypes: true });
+        if (state.stats)
+            state.stats.directoriesListed = (state.stats.directoriesListed ?? 0) + 1;
     }
     catch {
         return;
@@ -182,7 +258,10 @@ async function visitAsync(state, dir, depth) {
             continue;
         const fullPath = path.join(dir, entry.name);
         try {
-            record(state, fullPath, entry.name, await fs.promises.stat(fullPath));
+            const stat = await fs.promises.stat(fullPath);
+            if (state.stats)
+                state.stats.filesStatted = (state.stats.filesStatted ?? 0) + 1;
+            record(state, fullPath, entry.name, stat);
         }
         catch {
             // Skip files that vanish between readdir and stat.
@@ -196,14 +275,19 @@ async function visitAsync(state, dir, depth) {
     for (const entry of entries) {
         if (state.results.length >= state.cap)
             return;
-        if (entry.isDirectory())
-            await visitAsync(state, path.join(dir, entry.name), depth + 1);
+        if (entry.isDirectory()) {
+            await visitAsync(state, path.join(dir, entry.name), depth + 1, [...segments, entry.name]);
+        }
     }
 }
 /** Async twin of {@link walkRolloutFiles} that yields between directories. */
 async function walkRolloutFilesAsync(roots, options = {}) {
     const state = walkState(options);
-    for (const root of roots)
-        await visitAsync(state, root, 0);
+    for (const root of roots) {
+        if (state.cache)
+            await visitCached(state, state.cache, root, 0, []);
+        else
+            await visitAsync(state, root, 0, []);
+    }
     return finish(state);
 }

package/dist/providers/types.d.ts

@@ -59,6 +59,46 @@ export interface SessionFileInfo {
     /** Optional provider-recorded creation timestamp. */
     createdAt?: Date;
 }
+/** Payload-free counters of what an enumeration cost. */
+export interface SessionEnumerationCounters {
+    directoriesListed?: number;
+    directoriesStatted?: number;
+    filesStatted?: number;
+}
+/** Options for `listSessionFilesAsync()`; every field is optional and additive. */
+export interface ListSessionFilesOptions {
+    /** Return at most this many files, newest first (may skip an old-directory live session; see rolloutWalker). */
+    limit?: number;
+    /** Only files modified at or after this epoch-ms. */
+    since?: number;
+    /** Re-stat recently modified files even when their directory is unchanged. */
+    revalidateRecent?: boolean;
+    /** Counters the enumerator increments for real readdir/stat calls. */
+    stats?: SessionEnumerationCounters;
+}
+/**
+ * What a recursive-watch event under one of the provider's watch roots maps
+ * to, resolved with at most one stat.
+ *
+ * - `ignored`: structurally not a session of this provider (wrong depth or
+ *   extension, another workspace); nothing to do.
+ * - `unknown`: a directory or something the provider cannot classify; the
+ *   caller should fall back to a full enumeration.
+ * - `missing`: the path names a session that is gone or still empty.
+ * - `present`: the session file with its current stat.
+ */
+export type WatchedSessionFile = {
+    status: 'ignored';
+} | {
+    status: 'unknown';
+} | {
+    status: 'missing';
+    path: string;
+    sessionId: string;
+} | {
+    status: 'present';
+    file: SessionFileInfo;
+};
 /** How much of a session `readSessionStats()` could read. */
 export type SessionFileStatsAvailability = 'full' | 'partial' | 'unavailable';
 /**
@@ -225,7 +265,14 @@ export interface SessionProviderBase {
      */
     listAllSessionFiles?(): SessionFileInfo[];
     /** Event-loop-safe enumeration used by async preview and subscription APIs. */
-    listSessionFilesAsync?(workspacePath?: string): Promise<SessionFileInfo[]>;
+    listSessionFilesAsync?(workspacePath?: string, options?: ListSessionFilesOptions): Promise<SessionFileInfo[]>;
+    /**
+     * Resolve a recursive-watch event (`root` from `getWatchRoots()`, the
+     * root-relative `relativePath` the watcher reported) to a session file with
+     * at most one stat, applying the same workspace filter as
+     * `listSessionFilesAsync(workspacePath)`.
+     */
+    statWatchedSessionFile?(root: string, relativePath: string, workspacePath?: string): Promise<WatchedSessionFile>;
     /** Batch label extraction. DB-backed implementations use at most one query. */
     extractSessionLabelsAsync?(sessionPaths: readonly string[]): Promise<Map<string, string | null>>;
     /** Tests whether a provider can monitor a directory path, including synthetic DB-backed paths. */

package/dist/sessionMonitor.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SessionMonitor = void 0;
 const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
 const EventAggregator_1 = require("./aggregation/EventAggregator");
 const observedSessionCollector_1 = require("./observedSessionCollector");
 /**
@@ -119,6 +120,22 @@ class SessionMonitor {
                 ];
             },
             read: () => null,
+            // One session is watched, so an event naming any other file costs
+            // nothing; an event naming this file costs one stat.
+            resolveReference: async (signal) => {
+                if (!signal.root || typeof signal.filename !== 'string' || !signal.filename) {
+                    return { status: 'unknown' };
+                }
+                if (!this.sessionPath)
+                    return { status: 'ignored' };
+                const eventPath = path.resolve(signal.root, signal.filename);
+                if (eventPath !== path.resolve(this.sessionPath))
+                    return { status: 'ignored' };
+                const [reference] = await source.discover();
+                return reference
+                    ? { status: 'present', reference }
+                    : { status: 'missing', sessionId: this.provider.getSessionId(this.sessionPath) };
+            },
             subscribe: (listener, sourceOptions) => {
                 const watchers = new Set();
                 let pollTimer = null;
@@ -131,7 +148,12 @@ class SessionMonitor {
                 }
                 for (const root of new Set(roots)) {
                     try {
-                        const watcher = fs.watch(root, { persistent: false, recursive: true }, listener);
+                        const watcher = fs.watch(root, { persistent: false, recursive: true }, (eventType, filename) => listener({
+                            trigger: 'event',
+                            root,
+                            eventType,
+                            filename: filename === null || filename === undefined ? null : String(filename),
+                        }));
                         watchers.add(watcher);
                         watcher.on('error', () => {
                             watchers.delete(watcher);
@@ -149,7 +171,7 @@ class SessionMonitor {
                 }
                 const pollIntervalMs = sourceOptions?.pollIntervalMs ?? 0;
                 if (pollIntervalMs > 0) {
-                    pollTimer = setInterval(listener, pollIntervalMs);
+                    pollTimer = setInterval(() => listener({ trigger: 'poll' }), pollIntervalMs);
                     pollTimer.unref?.();
                 }
                 return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sidekick-shared",
-  "version": "0.26.4",
+  "version": "0.26.5",
   "description": "Shared data access layer for Sidekick — readers, types, providers, credentials, quota",
   "keywords": [
     "claude-code",