sidekick-shared 0.26.4 → 0.26.5

package/dist/observedSessionCollector.js

@@ -46,6 +46,12 @@ const DEFAULT_MAX_CONCURRENT_READS = 4;
 const MAX_CONCURRENT_READS = 16;
 const DEFAULT_DEBOUNCE_MS = 100;
 const DEFAULT_POLL_INTERVAL_MS = 30_000;
+const DEFAULT_MIN_RECONCILE_GAP_MS = 2_000;
+const DEFAULT_MAX_CACHE_ENTRIES = 20_000;
+const DEFAULT_MAX_CACHE_BYTES = 128 * 1024 * 1024;
+const FALLBACK_VALUE_BYTES = 1_024;
+/** A full discovery may recur once it has been idle this many times its own duration. */
+const GAP_COST_MULTIPLIER = 4;
 /**
  * Fail-soft observed-session collection with fingerprint-keyed parse caching,
  * cooperative reads, and optional provider-level subscriptions.
@@ -53,12 +59,22 @@ const DEFAULT_POLL_INTERVAL_MS = 30_000;
 class ObservedSessionCollector {
     options;
     failures = new Map();
-    cache = new Map();
+    cache;
     subscriptions = new Set();
+    /** Latest complete reference set per provider, kept current by scoped reconciles. */
+    lastDiscovery = new Map();
+    /** One full discovery per provider at a time; concurrent callers share it. */
+    inflightDiscovery = new Map();
+    fullPassState = new Map();
+    /** Scoped results newer than an in-flight walk, so the walk cannot undo them. */
+    scopedReferences = new Map();
+    generation = 0;
+    passId = 0;
     initialBackoffMs;
     maxBackoffMs;
     clock;
     maxConcurrentReads;
+    minReconcileGapMs;
     yieldBetweenReads;
     constructor(options) {
         this.options = options;
@@ -66,6 +82,17 @@ class ObservedSessionCollector {
         this.maxBackoffMs = Math.max(this.initialBackoffMs, options.maxBackoffMs ?? 5 * 60_000);
         this.clock = options.clock ?? { now: () => Date.now() };
         this.maxConcurrentReads = Math.min(MAX_CONCURRENT_READS, Math.max(1, Math.floor(options.maxConcurrentReads ?? DEFAULT_MAX_CONCURRENT_READS)));
+        this.minReconcileGapMs = Math.max(0, options.minReconcileGapMs ?? DEFAULT_MIN_RECONCILE_GAP_MS);
+        const estimate = options.approximateValueBytes ?? defaultValueBytes;
+        this.cache = new BoundedCache(Math.max(1, Math.floor(options.maxCacheEntries ?? DEFAULT_MAX_CACHE_ENTRIES)), Math.max(1, Math.floor(options.maxCacheBytes ?? DEFAULT_MAX_CACHE_BYTES)), (value) => {
+            try {
+                const bytes = estimate(value);
+                return Number.isFinite(bytes) && bytes >= 0 ? bytes : FALLBACK_VALUE_BYTES;
+            }
+            catch {
+                return FALLBACK_VALUE_BYTES;
+            }
+        });
         this.yieldBetweenReads = async () => {
             if (options.yieldBetweenReads) {
                 await options.yieldBetweenReads();
@@ -74,17 +101,28 @@ class ObservedSessionCollector {
             await new Promise((resolve) => setImmediate(resolve));
         };
     }
-    async collect() {
-        const nested = await Promise.all(this.options.sources.map((source) => this.collectSource(source)));
+    async collect(options = {}) {
+        this.passId++;
+        const nested = await Promise.all(this.options.sources.map((source) => this.collectSource(source, options)));
         return nested.flat();
     }
+    /** Number of parsed sessions currently cached. */
+    get cacheSize() {
+        return this.cache.size;
+    }
     /**
      * Subscribe to debounced provider changes. The listener receives fingerprints
      * only; call collect() to consume changed sessions through the parse cache.
+     *
+     * A signal that names a file is reconciled with one stat. Signals without a
+     * filename, catch-up polls, and the initial pass run a full discovery, at
+     * most once per gap per provider; bursts inside the debounce window join a
+     * single trailing pass.
      */
     subscribe(listener, options = {}) {
         const debounceMs = Math.max(0, options.debounceMs ?? DEFAULT_DEBOUNCE_MS);
         const pollIntervalMs = Math.max(0, options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS);
+        const gapCeilingMs = Math.max(0, options.minReconcileGapMs ?? this.minReconcileGapMs);
         const known = new Map();
         for (const item of options.knownFingerprints ?? []) {
             known.set(this.key(item.providerId, item.sessionId), {
@@ -96,60 +134,137 @@ class ObservedSessionCollector {
             known.set(key, { fingerprint: entry.fingerprint, parts: entry.fingerprintParts });
         }
         let disposed = false;
-        let debounceTimer = null;
-        let reconciling = false;
-        let pending = false;
+        let timer = null;
+        let timerFireAt = 0;
+        let running = false;
+        let pendingScoped = new Map();
+        let pendingFull = new Map();
         const sourceDisposables = [];
-        const reconcile = async () => {
+        const gapRemainingMs = (source, trigger) => {
+            if (trigger === 'initial')
+                return 0;
+            const state = this.fullPassState.get(source.providerId);
+            if (!state)
+                return 0;
+            return Math.max(0, state.endedAt + this.effectiveGapMs(source.providerId, gapCeilingMs) - Date.now());
+        };
+        const emit = (batch) => {
+            if (batch.changes.length === 0)
+                return;
+            try {
+                listener(batch);
+            }
+            catch {
+                // Subscriber failures cannot stop reconciliation.
+            }
+        };
+        // Arms the trailing timer; a later request can only pull it earlier,
+        // never push it out, so a busy live session cannot starve the pass.
+        const arm = (delayMs) => {
             if (disposed)
                 return;
-            if (reconciling) {
-                pending = true;
+            const fireAt = Date.now() + delayMs;
+            if (timer && timerFireAt <= fireAt)
+                return;
+            if (timer)
+                clearTimeout(timer);
+            timerFireAt = fireAt;
+            timer = setTimeout(() => {
+                timer = null;
+                void run();
+            }, delayMs);
+            timer.unref?.();
+        };
+        const requestFull = (source, trigger) => {
+            const existing = pendingFull.get(source);
+            if (!existing || existing === 'event')
+                pendingFull.set(source, trigger);
+        };
+        const onSignal = (source, signal) => {
+            if (disposed)
+                return;
+            const parsed = typeof signal === 'object' && signal !== null ? signal : undefined;
+            if (parsed &&
+                typeof parsed.filename === 'string' &&
+                parsed.filename.length > 0 &&
+                source.resolveReference) {
+                pendingScoped.set(`${source.providerId}\0${parsed.root ?? ''}\0${parsed.filename}`, {
+                    source,
+                    signal: parsed,
+                });
+                arm(debounceMs);
                 return;
             }
-            reconciling = true;
+            const trigger = parsed?.trigger === 'poll' ? 'poll' : 'event';
+            requestFull(source, trigger);
+            arm(Math.max(debounceMs, gapRemainingMs(source, trigger)));
+        };
+        const run = async () => {
+            if (disposed || running)
+                return;
+            running = true;
+            // Swap before the first await so signals landing mid-run are kept.
+            const scoped = pendingScoped;
+            pendingScoped = new Map();
+            const full = pendingFull;
+            pendingFull = new Map();
             try {
-                do {
-                    pending = false;
-                    for (const source of this.options.sources) {
-                        if (disposed)
-                            break;
-                        const batch = await this.reconcileSource(source, known);
-                        // Re-check after the await: disposal during the reconcile must
-                        // not deliver the pre-disposal batch to the listener.
-                        if (disposed)
-                            break;
-                        if (batch && batch.changes.length > 0) {
-                            try {
-                                listener(batch);
-                            }
-                            catch {
-                                // Subscriber failures cannot stop reconciliation.
-                            }
-                        }
+                const scopedChanges = new Map();
+                for (const { source, signal } of scoped.values()) {
+                    if (disposed)
+                        return;
+                    const result = await this.reconcileSignal(source, signal, known, gapCeilingMs);
+                    if (disposed)
+                        return;
+                    if (result === 'unknown') {
+                        requestFull(source, 'event');
+                        continue;
+                    }
+                    if (!result)
+                        continue;
+                    const list = scopedChanges.get(source) ?? [];
+                    list.push(result);
+                    scopedChanges.set(source, list);
+                }
+                for (const [source, changes] of scopedChanges) {
+                    emit({
+                        providerId: source.providerId,
+                        changes,
+                        observedAt: new Date(this.clock.now()).toISOString(),
+                    });
+                }
+                for (const [source, trigger] of full) {
+                    if (disposed)
+                        return;
+                    if (gapRemainingMs(source, trigger) > 0) {
+                        requestFull(source, trigger);
+                        continue;
                     }
-                } while (pending && !disposed);
+                    const batch = await this.reconcileSource(source, known, trigger, gapCeilingMs);
+                    // Re-check after the await: disposal during the reconcile must
+                    // not deliver the pre-disposal batch to the listener.
+                    if (disposed)
+                        return;
+                    if (batch)
+                        emit(batch);
+                }
             }
             finally {
-                reconciling = false;
+                running = false;
+                if (!disposed && (pendingScoped.size > 0 || pendingFull.size > 0)) {
+                    let delayMs = pendingScoped.size > 0 ? debounceMs : Infinity;
+                    for (const [source, trigger] of pendingFull) {
+                        delayMs = Math.min(delayMs, Math.max(debounceMs, gapRemainingMs(source, trigger)));
+                    }
+                    arm(delayMs);
+                }
             }
         };
-        const schedule = () => {
-            if (disposed)
-                return;
-            if (debounceTimer)
-                clearTimeout(debounceTimer);
-            debounceTimer = setTimeout(() => {
-                debounceTimer = null;
-                void reconcile();
-            }, debounceMs);
-            debounceTimer.unref?.();
-        };
         let needsCollectorPoll = false;
         for (const source of this.options.sources) {
             if (source.subscribe) {
                 try {
-                    sourceDisposables.push(source.subscribe(schedule, { pollIntervalMs }));
+                    sourceDisposables.push(source.subscribe((signal) => onSignal(source, signal), { pollIntervalMs }));
                 }
                 catch {
                     // The collector-level poll below remains the correctness fallback.
@@ -162,17 +277,22 @@ class ObservedSessionCollector {
         }
         let pollTimer = null;
         if (needsCollectorPoll && pollIntervalMs > 0) {
-            pollTimer = setInterval(schedule, pollIntervalMs);
+            pollTimer = setInterval(() => {
+                for (const source of this.options.sources)
+                    onSignal(source, { trigger: 'poll' });
+            }, pollIntervalMs);
             pollTimer.unref?.();
         }
-        schedule();
+        for (const source of this.options.sources)
+            requestFull(source, 'initial');
+        arm(debounceMs);
         const disposable = {
             dispose: () => {
                 if (disposed)
                     return;
                 disposed = true;
-                if (debounceTimer)
-                    clearTimeout(debounceTimer);
+                if (timer)
+                    clearTimeout(timer);
                 if (pollTimer)
                     clearInterval(pollTimer);
                 for (const item of sourceDisposables) {
@@ -192,6 +312,8 @@ class ObservedSessionCollector {
     reset() {
         this.failures.clear();
         this.cache.clear();
+        this.lastDiscovery.clear();
+        this.scopedReferences.clear();
     }
     dispose() {
         for (const subscription of [...this.subscriptions])
@@ -206,22 +328,35 @@ class ObservedSessionCollector {
         }
         this.reset();
     }
-    async collectSource(source) {
+    async collectSource(source, options) {
         const discoveryKey = `${source.providerId}\0$discovery`;
         const discoveryFailure = this.failures.get(discoveryKey);
         if (discoveryFailure && this.clock.now() < discoveryFailure.retryAt)
             return [];
+        const partial = options.limit !== undefined || options.since !== undefined;
         let references;
-        try {
-            references = await source.discover();
-            this.recover(discoveryKey, 'provider-recovered', source.providerId);
+        // A reconcile pass within the gap already produced the references; a
+        // collect() issued from the listener must not walk the provider again.
+        const snapshot = !partial && this.subscriptions.size > 0
+            ? this.lastDiscovery.get(source.providerId)
+            : undefined;
+        if (snapshot && Date.now() < snapshot.reuseUntil) {
+            references = [...snapshot.references.values()];
         }
-        catch (error) {
-            this.fail(discoveryKey, 'provider-discovery-failed', source.providerId, undefined, null, error);
-            return [];
+        else {
+            try {
+                references = await this.runDiscovery(source, 'collect', options);
+                this.recover(discoveryKey, 'provider-recovered', source.providerId);
+            }
+            catch (error) {
+                this.fail(discoveryKey, 'provider-discovery-failed', source.providerId, undefined, null, error);
+                return [];
+            }
+        }
+        if (!partial) {
+            const activeKeys = new Set(references.map((ref) => this.key(source.providerId, ref.sessionId)));
+            this.evictMissing(source.providerId, activeKeys);
         }
-        const activeKeys = new Set(references.map((ref) => this.key(source.providerId, ref.sessionId)));
-        this.evictMissing(source.providerId, activeKeys);
         const rows = await this.mapWithConcurrency(references, async (reference) => {
             const result = await this.collectSession(source, reference);
             await this.yieldBetweenReads();
@@ -239,7 +374,7 @@ class ObservedSessionCollector {
             return null;
         }
         const observedAt = new Date(this.clock.now()).toISOString();
-        const cached = fingerprint.value === null ? undefined : this.cache.get(key);
+        const cached = fingerprint.value === null ? undefined : this.cache.get(key, this.passId);
         if (cached && cached.fingerprint === fingerprint.value) {
             let value = cached.value;
             try {
@@ -272,7 +407,7 @@ class ObservedSessionCollector {
                 fingerprint: fingerprint.value,
                 fingerprintParts: fingerprint.parts,
                 contentObservedAt,
-            });
+            }, this.passId);
         }
         const observation = this.makeObservation(source, reference, value, fingerprint, false, observedAt, contentObservedAt);
         this.emitObservation(observation);
@@ -298,22 +433,169 @@ class ObservedSessionCollector {
             // Host callbacks cannot turn a healthy provider read into a collection failure.
         }
     }
-    async reconcileSource(source, known) {
+    /**
+     * Runs `discover()` once per provider at a time. Unbounded discoveries are
+     * shared with concurrent callers and update the gap bookkeeping; every
+     * discovery emits one payload-free cost diagnostic.
+     */
+    runDiscovery(source, trigger, options = {}) {
+        return this.startDiscovery(source, trigger, options).promise;
+    }
+    /**
+     * Starts (or joins) a discovery and reports the generation it started at,
+     * so a reconcile that joins a walk begun earlier by `collect()` compares
+     * scoped results against the walk's start rather than its own entry.
+     */
+    startDiscovery(source, trigger, options = {}) {
+        const providerId = source.providerId;
+        const partial = options.limit !== undefined || options.since !== undefined;
+        if (!partial) {
+            const inflight = this.inflightDiscovery.get(providerId);
+            if (inflight)
+                return inflight;
+        }
+        const generation = this.generation;
+        const stats = {};
+        const startedAt = Date.now();
+        const promise = (async () => {
+            const references = await source.discover({
+                limit: options.limit,
+                since: options.since,
+                stats,
+            });
+            const endedAt = Date.now();
+            const durationMs = endedAt - startedAt;
+            if (!partial)
+                this.fullPassState.set(providerId, { endedAt, durationMs });
+            this.emitDiagnostic(compact({
+                kind: 'provider-discovery-completed',
+                severity: 'info',
+                phase: 'discover',
+                providerId,
+                trigger,
+                durationMs,
+                referenceCount: references.length,
+                directoriesListed: stats.directoriesListed,
+                directoriesStatted: stats.directoriesStatted,
+                filesStatted: stats.filesStatted,
+                partial: partial ? true : undefined,
+            }));
+            return references;
+        })();
+        const handle = { promise, generation };
+        if (!partial) {
+            this.inflightDiscovery.set(providerId, handle);
+            const settle = () => {
+                if (this.inflightDiscovery.get(providerId) === handle) {
+                    this.inflightDiscovery.delete(providerId);
+                }
+            };
+            promise.then(settle, settle);
+        }
+        return handle;
+    }
+    effectiveGapMs(providerId, ceilingMs) {
+        const state = this.fullPassState.get(providerId);
+        if (!state)
+            return 0;
+        return Math.min(ceilingMs, state.durationMs * GAP_COST_MULTIPLIER);
+    }
+    /** Reconcile one watch signal against `known` with at most one stat. */
+    async reconcileSignal(source, signal, known, gapCeilingMs) {
+        if (!source.resolveReference)
+            return 'unknown';
+        let resolution;
+        try {
+            resolution = await source.resolveReference(signal);
+        }
+        catch {
+            return 'unknown';
+        }
+        if (!resolution || typeof resolution !== 'object')
+            return 'unknown';
+        const providerId = source.providerId;
+        switch (resolution.status) {
+            case 'ignored':
+                return null;
+            case 'missing': {
+                const key = this.key(providerId, resolution.sessionId);
+                this.scopedReferences.set(key, { reference: null, generation: ++this.generation });
+                this.lastDiscovery.get(providerId)?.references.delete(resolution.sessionId);
+                const previous = known.get(key);
+                if (!previous)
+                    return null;
+                known.delete(key);
+                return {
+                    type: 'removed',
+                    reference: { sessionId: resolution.sessionId },
+                    previousFingerprint: previous.fingerprint,
+                    previousFingerprintParts: previous.parts,
+                    fingerprint: null,
+                    fingerprintParts: null,
+                };
+            }
+            case 'present': {
+                const reference = resolution.reference;
+                const key = this.key(providerId, reference.sessionId);
+                const current = await this.fingerprint(source, reference);
+                if (current.value === null)
+                    return null;
+                this.scopedReferences.set(key, { reference, generation: ++this.generation });
+                const snapshot = this.lastDiscovery.get(providerId);
+                if (snapshot) {
+                    snapshot.references.set(reference.sessionId, reference);
+                    snapshot.reuseUntil = Date.now() + this.effectiveGapMs(providerId, gapCeilingMs);
+                }
+                const previous = known.get(key);
+                known.set(key, { fingerprint: current.value, parts: current.parts });
+                if (previous && previous.fingerprint === current.value)
+                    return null;
+                return {
+                    type: previous ? 'changed' : 'added',
+                    reference,
+                    previousFingerprint: previous?.fingerprint ?? null,
+                    previousFingerprintParts: previous?.parts ?? null,
+                    fingerprint: current.value,
+                    fingerprintParts: current.parts,
+                };
+            }
+            default:
+                return 'unknown';
+        }
+    }
+    async reconcileSource(source, known, trigger, gapCeilingMs) {
+        const providerId = source.providerId;
+        const prefix = `${providerId}\0`;
+        // The walk may have been started earlier by a concurrent collect(); its
+        // start generation, not this pass's entry, decides which scoped results
+        // are newer than the references it returns.
+        let startGeneration;
         let references;
         try {
-            references = await source.discover();
+            const discovery = this.startDiscovery(source, trigger);
+            startGeneration = discovery.generation;
+            references = await discovery.promise;
         }
         catch {
             return null;
         }
         const changes = [];
         const seen = new Set();
-        for (const reference of references) {
-            const key = this.key(source.providerId, reference.sessionId);
+        const snapshotReferences = new Map();
+        for (const discovered of references) {
+            const key = this.key(providerId, discovered.sessionId);
             seen.add(key);
+            // A scoped result that landed while the walk was running is newer than
+            // the walk's copy; use it so the walk cannot flip the fingerprint back.
+            const scoped = this.scopedReferences.get(key);
+            const newer = scoped !== undefined && scoped.generation > startGeneration;
+            if (newer && scoped.reference === null)
+                continue;
+            const reference = newer && scoped.reference ? scoped.reference : discovered;
             const current = await this.fingerprint(source, reference);
             if (current.value === null)
                 continue;
+            snapshotReferences.set(reference.sessionId, reference);
             const previous = known.get(key);
             if (!previous || previous.fingerprint !== current.value) {
                 changes.push({
@@ -328,9 +610,15 @@ class ObservedSessionCollector {
             known.set(key, { fingerprint: current.value, parts: current.parts });
         }
         for (const [key, previous] of [...known]) {
-            if (!key.startsWith(`${source.providerId}\0`) || seen.has(key))
+            if (!key.startsWith(prefix) || seen.has(key))
+                continue;
+            const scoped = this.scopedReferences.get(key);
+            if (scoped && scoped.generation > startGeneration && scoped.reference) {
+                // Created after the walk began; the scoped pass already reported it.
+                snapshotReferences.set(scoped.reference.sessionId, scoped.reference);
                 continue;
-            const sessionId = key.slice(source.providerId.length + 1);
+            }
+            const sessionId = key.slice(prefix.length);
             changes.push({
                 type: 'removed',
                 reference: { sessionId },
@@ -341,8 +629,17 @@ class ObservedSessionCollector {
             });
             known.delete(key);
         }
+        for (const [key, entry] of this.scopedReferences) {
+            if (key.startsWith(prefix) && entry.generation <= startGeneration) {
+                this.scopedReferences.delete(key);
+            }
+        }
+        this.lastDiscovery.set(providerId, {
+            references: snapshotReferences,
+            reuseUntil: Date.now() + this.effectiveGapMs(providerId, gapCeilingMs),
+        });
         return {
-            providerId: source.providerId,
+            providerId,
             changes,
             observedAt: new Date(this.clock.now()).toISOString(),
         };
@@ -367,7 +664,7 @@ class ObservedSessionCollector {
                 this.failures.delete(key);
             }
         }
-        for (const key of this.cache.keys()) {
+        for (const key of [...this.cache.keys()]) {
             if (key.startsWith(`${providerId}\0`) && !activeKeys.has(key))
                 this.cache.delete(key);
         }
@@ -434,6 +731,82 @@ class ObservedSessionCollector {
     }
 }
 exports.ObservedSessionCollector = ObservedSessionCollector;
+/**
+ * Parse cache bounded by entry count and approximate bytes. Insertion order
+ * doubles as recency: a hit re-inserts, so the first entry is always the
+ * least recently observed. Entries observed in the current pass are never
+ * evicted by that pass, so one oversized pass cannot thrash itself.
+ */
+class BoundedCache {
+    maxEntries;
+    maxBytes;
+    estimate;
+    entries = new Map();
+    totalBytes = 0;
+    constructor(maxEntries, maxBytes, estimate) {
+        this.maxEntries = maxEntries;
+        this.maxBytes = maxBytes;
+        this.estimate = estimate;
+    }
+    get size() {
+        return this.entries.size;
+    }
+    get(key, passId) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return undefined;
+        this.entries.delete(key);
+        this.entries.set(key, entry);
+        entry.passId = passId;
+        return entry;
+    }
+    set(key, entry, passId) {
+        this.delete(key);
+        const bytes = this.estimate(entry.value);
+        this.entries.set(key, { ...entry, bytes, passId });
+        this.totalBytes += bytes;
+        this.evict(passId);
+    }
+    delete(key) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return;
+        this.totalBytes -= entry.bytes;
+        this.entries.delete(key);
+    }
+    keys() {
+        return this.entries.keys();
+    }
+    [Symbol.iterator]() {
+        return this.entries.entries();
+    }
+    clear() {
+        this.entries.clear();
+        this.totalBytes = 0;
+    }
+    evict(passId) {
+        while (this.entries.size > this.maxEntries || this.totalBytes > this.maxBytes) {
+            // Untouched entries always precede entries touched in this pass, so
+            // a protected first entry means every remaining entry is protected.
+            const first = this.entries.entries().next();
+            if (first.done || first.value[1].passId === passId)
+                return;
+            this.delete(first.value[0]);
+        }
+    }
+}
+function defaultValueBytes(value) {
+    const json = JSON.stringify(value);
+    return typeof json === 'string' ? json.length : FALLBACK_VALUE_BYTES;
+}
+function compact(diagnostic) {
+    const result = {};
+    for (const [key, value] of Object.entries(diagnostic)) {
+        if (value !== undefined)
+            result[key] = value;
+    }
+    return result;
+}
 /**
  * Adapt a provider using path-only discovery and independent adapter reads, so
  * one malformed session cannot reject discovery of its healthy siblings.
@@ -454,17 +827,26 @@ function observedSessionSourceFromProvider(provider, cwd, options = {}) {
             fingerprintParts: parts ?? undefined,
         };
     };
-    const discover = async () => {
+    const referenceFromInfo = (info) => {
+        const mtimeMs = info.mtime.getTime();
+        const suppliedParts = info.sizeBytes !== undefined && Number.isFinite(mtimeMs)
+            ? { sizeBytes: info.sizeBytes, mtimeMs }
+            : undefined;
+        return referenceFromPath(info.path, info.sessionId ?? provider.getSessionId(info.path), suppliedParts);
+    };
+    const discover = async (discoverOptions = {}) => {
         if (provider.listSessionFilesAsync) {
             try {
-                const files = await provider.listSessionFilesAsync(cwd);
-                return files.map((info) => {
-                    const mtimeMs = info.mtime.getTime();
-                    const suppliedParts = info.sizeBytes !== undefined && Number.isFinite(mtimeMs)
-                        ? { sizeBytes: info.sizeBytes, mtimeMs }
-                        : undefined;
-                    return referenceFromPath(info.path, info.sessionId ?? provider.getSessionId(info.path), suppliedParts);
+                const files = await provider.listSessionFilesAsync(cwd, {
+                    limit: discoverOptions.limit,
+                    since: discoverOptions.since,
+                    stats: discoverOptions.stats,
+                    // Appends do not bump a directory's mtime; a full pass re-checks
+                    // files modified recently so a missed watch event cannot hide a
+                    // live session's growth from a cached listing.
+                    revalidateRecent: true,
                 });
+                return files.map(referenceFromInfo);
             }
             catch {
                 // Retain compatibility with third-party providers whose optional async
@@ -483,7 +865,7 @@ function observedSessionSourceFromProvider(provider, cwd, options = {}) {
             };
         });
     };
-    return {
+    const source = {
         providerId: provider.id,
         capabilities: adapter.capabilities,
         discover,
@@ -506,6 +888,26 @@ function observedSessionSourceFromProvider(provider, cwd, options = {}) {
         },
         dispose: () => adapter.dispose(),
     };
+    if (provider.statWatchedSessionFile) {
+        const statWatchedSessionFile = provider.statWatchedSessionFile.bind(provider);
+        source.resolveReference = async (signal) => {
+            if (!signal.root || typeof signal.filename !== 'string' || signal.filename.length === 0) {
+                return { status: 'unknown' };
+            }
+            const resolved = await statWatchedSessionFile(signal.root, signal.filename, cwd || undefined);
+            switch (resolved.status) {
+                case 'present':
+                    return { status: 'present', reference: referenceFromInfo(resolved.file) };
+                case 'missing':
+                    return { status: 'missing', sessionId: resolved.sessionId };
+                case 'ignored':
+                    return { status: 'ignored' };
+                default:
+                    return { status: 'unknown' };
+            }
+        };
+    }
+    return source;
 }
 function parseFingerprintParts(value) {
     if (!value)
@@ -535,7 +937,12 @@ function subscribeToProviderRoot(provider, listener, pollIntervalMs) {
     }
     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);
@@ -552,7 +959,7 @@ function subscribeToProviderRoot(provider, listener, pollIntervalMs) {
         }
     }
     if (pollIntervalMs > 0) {
-        pollTimer = setInterval(listener, pollIntervalMs);
+        pollTimer = setInterval(() => listener({ trigger: 'poll' }), pollIntervalMs);
         pollTimer.unref?.();
     }
     return {