sidekick-shared 0.27.6 → 0.28.0

package/dist/esm/observedSessionCollector.js

@@ -0,0 +1,939 @@
+import * as fs from 'node:fs';
+import { createProviderSessionAdapterV1, getObservedActivityReason, } from './types/observedSessionV1';
+import { refreshSessionActivityState } from './parsers/sessionActivityDetector';
+import { fileFingerprintParts, fingerprintString } from './sessionFingerprint';
+export { fileFingerprint, fileFingerprintParts } from './sessionFingerprint';
+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.
+ */
+export class ObservedSessionCollector {
+    options;
+    failures = 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;
+        this.initialBackoffMs = Math.max(1, options.initialBackoffMs ?? 30_000);
+        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();
+                return;
+            }
+            await new Promise((resolve) => setImmediate(resolve));
+        };
+    }
+    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), {
+                fingerprint: item.fingerprint,
+                parts: item.fingerprintParts ?? null,
+            });
+        }
+        for (const [key, entry] of this.cache) {
+            known.set(key, { fingerprint: entry.fingerprint, parts: entry.fingerprintParts });
+        }
+        let disposed = false;
+        let timer = null;
+        let timerFireAt = 0;
+        let running = false;
+        let pendingScoped = new Map();
+        let pendingFull = new Map();
+        const sourceDisposables = [];
+        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;
+            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;
+            }
+            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 {
+                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;
+                    }
+                    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 {
+                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);
+                }
+            }
+        };
+        let needsCollectorPoll = false;
+        for (const source of this.options.sources) {
+            if (source.subscribe) {
+                try {
+                    sourceDisposables.push(source.subscribe((signal) => onSignal(source, signal), { pollIntervalMs }));
+                }
+                catch {
+                    // The collector-level poll below remains the correctness fallback.
+                    needsCollectorPoll = true;
+                }
+            }
+            else {
+                needsCollectorPoll = true;
+            }
+        }
+        let pollTimer = null;
+        if (needsCollectorPoll && pollIntervalMs > 0) {
+            pollTimer = setInterval(() => {
+                for (const source of this.options.sources)
+                    onSignal(source, { trigger: 'poll' });
+            }, pollIntervalMs);
+            pollTimer.unref?.();
+        }
+        for (const source of this.options.sources)
+            requestFull(source, 'initial');
+        arm(debounceMs);
+        const disposable = {
+            dispose: () => {
+                if (disposed)
+                    return;
+                disposed = true;
+                if (timer)
+                    clearTimeout(timer);
+                if (pollTimer)
+                    clearInterval(pollTimer);
+                for (const item of sourceDisposables) {
+                    try {
+                        item.dispose();
+                    }
+                    catch {
+                        // Disposal is best effort.
+                    }
+                }
+                this.subscriptions.delete(disposable);
+            },
+        };
+        this.subscriptions.add(disposable);
+        return disposable;
+    }
+    reset() {
+        this.failures.clear();
+        this.cache.clear();
+        this.lastDiscovery.clear();
+        this.scopedReferences.clear();
+    }
+    dispose() {
+        for (const subscription of [...this.subscriptions])
+            subscription.dispose();
+        for (const source of this.options.sources) {
+            try {
+                source.dispose?.();
+            }
+            catch {
+                // Disposal is best-effort and isolated per source.
+            }
+        }
+        this.reset();
+    }
+    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;
+        // 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()];
+        }
+        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 rows = await this.mapWithConcurrency(references, async (reference) => {
+            const result = await this.collectSession(source, reference);
+            await this.yieldBetweenReads();
+            return result;
+        });
+        return rows.filter((row) => row !== null);
+    }
+    async collectSession(source, reference) {
+        const key = this.key(source.providerId, reference.sessionId);
+        const fingerprint = await this.fingerprint(source, reference);
+        const priorFailure = this.failures.get(key);
+        if (priorFailure &&
+            priorFailure.fingerprint === fingerprint.value &&
+            this.clock.now() < priorFailure.retryAt) {
+            return null;
+        }
+        const observedAt = new Date(this.clock.now()).toISOString();
+        const cached = fingerprint.value === null ? undefined : this.cache.get(key, this.passId);
+        if (cached && cached.fingerprint === fingerprint.value) {
+            let value = cached.value;
+            try {
+                if (source.refreshCached) {
+                    value = await source.refreshCached(reference, cached.value, observedAt);
+                }
+            }
+            catch {
+                value = cached.value;
+            }
+            cached.value = value;
+            cached.fingerprintParts = fingerprint.parts;
+            const observation = this.makeObservation(source, reference, value, fingerprint, true, observedAt, cached.contentObservedAt);
+            this.emitObservation(observation);
+            return observation;
+        }
+        let value;
+        try {
+            value = await source.read(reference);
+        }
+        catch (error) {
+            this.fail(key, 'session-read-failed', source.providerId, reference.sessionId, fingerprint.value, error);
+            return null;
+        }
+        this.recover(key, 'session-recovered', source.providerId, reference.sessionId);
+        const contentObservedAt = contentTimestamp(value) ?? observedAt;
+        if (fingerprint.value !== null) {
+            this.cache.set(key, {
+                value,
+                fingerprint: fingerprint.value,
+                fingerprintParts: fingerprint.parts,
+                contentObservedAt,
+            }, this.passId);
+        }
+        const observation = this.makeObservation(source, reference, value, fingerprint, false, observedAt, contentObservedAt);
+        this.emitObservation(observation);
+        return observation;
+    }
+    makeObservation(source, reference, value, fingerprint, cacheHit, observedAt, contentObservedAt) {
+        return {
+            providerId: source.providerId,
+            sessionId: reference.sessionId,
+            value,
+            fingerprint: fingerprint.value,
+            fingerprintParts: fingerprint.parts,
+            cacheHit,
+            observedAt,
+            contentObservedAt,
+        };
+    }
+    emitObservation(observation) {
+        try {
+            this.options.onObservation?.(observation);
+        }
+        catch {
+            // Host callbacks cannot turn a healthy provider read into a collection failure.
+        }
+    }
+    /**
+     * 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 {
+            const discovery = this.startDiscovery(source, trigger);
+            startGeneration = discovery.generation;
+            references = await discovery.promise;
+        }
+        catch {
+            return null;
+        }
+        const changes = [];
+        const seen = new Set();
+        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({
+                    type: previous ? 'changed' : 'added',
+                    reference,
+                    previousFingerprint: previous?.fingerprint ?? null,
+                    previousFingerprintParts: previous?.parts ?? null,
+                    fingerprint: current.value,
+                    fingerprintParts: current.parts,
+                });
+            }
+            known.set(key, { fingerprint: current.value, parts: current.parts });
+        }
+        for (const [key, previous] of [...known]) {
+            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(prefix.length);
+            changes.push({
+                type: 'removed',
+                reference: { sessionId },
+                previousFingerprint: previous.fingerprint,
+                previousFingerprintParts: previous.parts,
+                fingerprint: null,
+                fingerprintParts: null,
+            });
+            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,
+            changes,
+            observedAt: new Date(this.clock.now()).toISOString(),
+        };
+    }
+    async fingerprint(source, reference) {
+        let value = reference.fingerprintHint ?? null;
+        try {
+            if (this.options.fingerprint)
+                value = await this.options.fingerprint(source, reference);
+        }
+        catch {
+            // Retain the reference hint.
+        }
+        const parts = reference.fingerprintParts ?? parseFingerprintParts(value);
+        return { value, parts };
+    }
+    evictMissing(providerId, activeKeys) {
+        for (const key of this.failures.keys()) {
+            if (key.startsWith(`${providerId}\0`) &&
+                !key.endsWith('$discovery') &&
+                !activeKeys.has(key)) {
+                this.failures.delete(key);
+            }
+        }
+        for (const key of [...this.cache.keys()]) {
+            if (key.startsWith(`${providerId}\0`) && !activeKeys.has(key))
+                this.cache.delete(key);
+        }
+    }
+    async mapWithConcurrency(values, mapper) {
+        const results = new Array(values.length);
+        let cursor = 0;
+        const workers = Array.from({ length: Math.min(this.maxConcurrentReads, values.length) }, async () => {
+            while (true) {
+                const index = cursor++;
+                if (index >= values.length)
+                    return;
+                results[index] = await mapper(values[index]);
+            }
+        });
+        await Promise.all(workers);
+        return results;
+    }
+    fail(key, kind, providerId, sessionId, fingerprint, error) {
+        const previous = this.failures.get(key);
+        const signature = failureSignature(error);
+        const fingerprintChanged = previous?.fingerprint !== fingerprint;
+        const attempt = previous && !fingerprintChanged ? previous.attempt + 1 : 1;
+        const delay = Math.min(this.maxBackoffMs, this.initialBackoffMs * 2 ** (attempt - 1));
+        const retryAt = this.clock.now() + delay;
+        const reportedSignature = previous?.reportedSignature ?? '';
+        this.failures.set(key, { attempt, retryAt, fingerprint, reportedSignature: signature });
+        if (signature !== reportedSignature || fingerprintChanged) {
+            this.emitDiagnostic({
+                kind,
+                severity: 'error',
+                phase: kind === 'provider-discovery-failed' ? 'discover' : 'read',
+                providerId,
+                sessionId,
+                attempt,
+                retryAt,
+            });
+        }
+    }
+    recover(key, kind, providerId, sessionId) {
+        const prior = this.failures.get(key);
+        if (!prior)
+            return;
+        this.failures.delete(key);
+        this.emitDiagnostic({
+            kind,
+            severity: 'info',
+            phase: 'recover',
+            providerId,
+            sessionId,
+            attempt: prior.attempt,
+        });
+    }
+    emitDiagnostic(diagnostic) {
+        try {
+            this.options.onDiagnostic?.(diagnostic);
+        }
+        catch {
+            // Diagnostics are observational and never affect collection isolation.
+        }
+    }
+    key(providerId, sessionId) {
+        return `${providerId}\0${sessionId}`;
+    }
+}
+/**
+ * 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.
+ */
+export function observedSessionSourceFromProvider(provider, cwd, options = {}) {
+    const adapter = options.observationOnly
+        ? createProviderSessionAdapterV1(provider, { observationOnly: true })
+        : createProviderSessionAdapterV1(provider);
+    const referenceFromPath = (sessionPath, sessionId = provider.getSessionId(sessionPath), suppliedParts) => {
+        const metadata = suppliedParts ? null : provider.getSessionMetadata?.(sessionPath);
+        const parts = suppliedParts ??
+            fileFingerprintParts(sessionPath) ??
+            (metadata ? { sizeBytes: 0, mtimeMs: metadata.mtime.getTime() } : null);
+        return {
+            sessionId,
+            sourceKey: sessionPath,
+            fingerprintHint: parts ? fingerprintString(parts) : undefined,
+            fingerprintParts: parts ?? undefined,
+        };
+    };
+    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, {
+                    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
+                // enumerator is temporarily unavailable.
+            }
+        }
+        return provider.findAllSessions(cwd).map((sessionPath) => {
+            const metadata = provider.getSessionMetadata?.(sessionPath);
+            const parts = fileFingerprintParts(sessionPath) ??
+                (metadata ? { sizeBytes: 0, mtimeMs: metadata.mtime.getTime() } : null);
+            return {
+                sessionId: provider.getSessionId(sessionPath),
+                sourceKey: sessionPath,
+                fingerprintHint: parts ? fingerprintString(parts) : undefined,
+                fingerprintParts: parts ?? undefined,
+            };
+        });
+    };
+    const source = {
+        providerId: provider.id,
+        capabilities: adapter.capabilities,
+        discover,
+        async read(reference) {
+            if (!reference.sourceKey)
+                throw new Error('session source unavailable');
+            return adapter.read(reference.sourceKey, cwd);
+        },
+        refreshCached(reference, cached, observedAt) {
+            const mtimeMs = reference.fingerprintParts?.mtimeMs ?? Date.parse(cached.observedAt);
+            const activity = refreshSessionActivityState(cached.activity.value, mtimeMs, Date.now(), getObservedActivityReason(cached));
+            return {
+                ...cached,
+                activity: { ...cached.activity, value: activity },
+                observedAt,
+            };
+        },
+        subscribe(listener, subscribeOptions = {}) {
+            return subscribeToProviderRoot(provider, listener, subscribeOptions.pollIntervalMs ?? 0);
+        },
+        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)
+        return null;
+    const match = value.match(/^([0-9]+):([0-9]+(?:\.[0-9]+)?)$/);
+    if (!match)
+        return null;
+    const sizeBytes = Number(match[1]);
+    const mtimeMs = Number(match[2]);
+    return Number.isFinite(sizeBytes) && Number.isFinite(mtimeMs) ? { sizeBytes, mtimeMs } : null;
+}
+function contentTimestamp(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const candidate = value.contentObservedAt;
+    return typeof candidate === 'string' ? candidate : null;
+}
+function subscribeToProviderRoot(provider, listener, pollIntervalMs) {
+    const watchers = new Set();
+    let pollTimer = null;
+    let roots;
+    try {
+        roots = provider.getWatchRoots?.() ?? [provider.getProjectsBaseDir()];
+    }
+    catch {
+        roots = [];
+    }
+    for (const root of new Set(roots)) {
+        try {
+            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);
+                try {
+                    watcher.close();
+                }
+                catch {
+                    // Catch-up polling remains active.
+                }
+            });
+        }
+        catch {
+            // Polling remains the documented fallback.
+        }
+    }
+    if (pollIntervalMs > 0) {
+        pollTimer = setInterval(() => listener({ trigger: 'poll' }), pollIntervalMs);
+        pollTimer.unref?.();
+    }
+    return {
+        dispose: () => {
+            for (const watcher of watchers)
+                watcher.close();
+            watchers.clear();
+            if (pollTimer)
+                clearInterval(pollTimer);
+        },
+    };
+}
+function failureSignature(error) {
+    if (error instanceof Error)
+        return `${error.name}\0${error.message}`;
+    return typeof error === 'string' ? error : Object.prototype.toString.call(error);
+}