sidekick-shared 0.24.5 → 0.25.0

package/dist/schemas/observedSessionV1.d.ts

@@ -8,8 +8,8 @@ export declare const sessionEvidenceRefV1Schema: z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;
     provider: z.ZodEnum<{
         "claude-code": "claude-code";
-        codex: "codex";
         opencode: "opencode";
+        codex: "codex";
     }>;
     sessionId: z.ZodString;
     sourcePath: z.ZodOptional<z.ZodString>;
@@ -29,8 +29,8 @@ export declare const observedValueV1Schema: <T extends z.ZodType>(value: T) => z
         schemaVersion: z.ZodLiteral<1>;
         provider: z.ZodEnum<{
             "claude-code": "claude-code";
-            codex: "codex";
             opencode: "opencode";
+            codex: "codex";
         }>;
         sessionId: z.ZodString;
         sourcePath: z.ZodOptional<z.ZodString>;
@@ -44,8 +44,8 @@ export declare const pendingUserRequestV1Schema: z.ZodObject<{
     id: z.ZodString;
     provider: z.ZodEnum<{
         "claude-code": "claude-code";
-        codex: "codex";
         opencode: "opencode";
+        codex: "codex";
     }>;
     sessionId: z.ZodString;
     kind: z.ZodObject<{
@@ -64,8 +64,8 @@ export declare const pendingUserRequestV1Schema: z.ZodObject<{
             schemaVersion: z.ZodLiteral<1>;
             provider: z.ZodEnum<{
                 "claude-code": "claude-code";
-                codex: "codex";
                 opencode: "opencode";
+                codex: "codex";
             }>;
             sessionId: z.ZodString;
             sourcePath: z.ZodOptional<z.ZodString>;
@@ -86,8 +86,8 @@ export declare const pendingUserRequestV1Schema: z.ZodObject<{
             schemaVersion: z.ZodLiteral<1>;
             provider: z.ZodEnum<{
                 "claude-code": "claude-code";
-                codex: "codex";
                 opencode: "opencode";
+                codex: "codex";
             }>;
             sessionId: z.ZodString;
             sourcePath: z.ZodOptional<z.ZodString>;
@@ -108,8 +108,8 @@ export declare const pendingUserRequestV1Schema: z.ZodObject<{
             schemaVersion: z.ZodLiteral<1>;
             provider: z.ZodEnum<{
                 "claude-code": "claude-code";
-                codex: "codex";
                 opencode: "opencode";
+                codex: "codex";
             }>;
             sessionId: z.ZodString;
             sourcePath: z.ZodOptional<z.ZodString>;
@@ -124,8 +124,8 @@ export declare const observedAgentSessionV1Schema: z.ZodObject<{
     identity: z.ZodObject<{
         provider: z.ZodEnum<{
             "claude-code": "claude-code";
-            codex: "codex";
             opencode: "opencode";
+            codex: "codex";
         }>;
         sessionId: z.ZodString;
         sourcePath: z.ZodString;
@@ -142,8 +142,8 @@ export declare const observedAgentSessionV1Schema: z.ZodObject<{
             schemaVersion: z.ZodLiteral<1>;
             provider: z.ZodEnum<{
                 "claude-code": "claude-code";
-                codex: "codex";
                 opencode: "opencode";
+                codex: "codex";
             }>;
             sessionId: z.ZodString;
             sourcePath: z.ZodOptional<z.ZodString>;
@@ -164,8 +164,8 @@ export declare const observedAgentSessionV1Schema: z.ZodObject<{
             schemaVersion: z.ZodLiteral<1>;
             provider: z.ZodEnum<{
                 "claude-code": "claude-code";
-                codex: "codex";
                 opencode: "opencode";
+                codex: "codex";
             }>;
             sessionId: z.ZodString;
             sourcePath: z.ZodOptional<z.ZodString>;
@@ -178,8 +178,8 @@ export declare const observedAgentSessionV1Schema: z.ZodObject<{
         value: z.ZodEnum<{
             unknown: "unknown";
             active: "active";
-            idle: "idle";
             ended: "ended";
+            idle: "idle";
         }>;
         provenance: z.ZodEnum<{
             reported: "reported";
@@ -191,8 +191,8 @@ export declare const observedAgentSessionV1Schema: z.ZodObject<{
             schemaVersion: z.ZodLiteral<1>;
             provider: z.ZodEnum<{
                 "claude-code": "claude-code";
-                codex: "codex";
                 opencode: "opencode";
+                codex: "codex";
             }>;
             sessionId: z.ZodString;
             sourcePath: z.ZodOptional<z.ZodString>;
@@ -214,8 +214,8 @@ export declare const observedAgentSessionV1Schema: z.ZodObject<{
                 schemaVersion: z.ZodLiteral<1>;
                 provider: z.ZodEnum<{
                     "claude-code": "claude-code";
-                    codex: "codex";
                     opencode: "opencode";
+                    codex: "codex";
                 }>;
                 sessionId: z.ZodString;
                 sourcePath: z.ZodOptional<z.ZodString>;
@@ -236,8 +236,8 @@ export declare const observedAgentSessionV1Schema: z.ZodObject<{
                 schemaVersion: z.ZodLiteral<1>;
                 provider: z.ZodEnum<{
                     "claude-code": "claude-code";
-                    codex: "codex";
                     opencode: "opencode";
+                    codex: "codex";
                 }>;
                 sessionId: z.ZodString;
                 sourcePath: z.ZodOptional<z.ZodString>;
@@ -258,8 +258,8 @@ export declare const observedAgentSessionV1Schema: z.ZodObject<{
                 schemaVersion: z.ZodLiteral<1>;
                 provider: z.ZodEnum<{
                     "claude-code": "claude-code";
-                    codex: "codex";
                     opencode: "opencode";
+                    codex: "codex";
                 }>;
                 sessionId: z.ZodString;
                 sourcePath: z.ZodOptional<z.ZodString>;
@@ -280,8 +280,8 @@ export declare const observedAgentSessionV1Schema: z.ZodObject<{
                 schemaVersion: z.ZodLiteral<1>;
                 provider: z.ZodEnum<{
                     "claude-code": "claude-code";
-                    codex: "codex";
                     opencode: "opencode";
+                    codex: "codex";
                 }>;
                 sessionId: z.ZodString;
                 sourcePath: z.ZodOptional<z.ZodString>;
@@ -311,8 +311,8 @@ export declare const observedAgentSessionV1Schema: z.ZodObject<{
                 schemaVersion: z.ZodLiteral<1>;
                 provider: z.ZodEnum<{
                     "claude-code": "claude-code";
-                    codex: "codex";
                     opencode: "opencode";
+                    codex: "codex";
                 }>;
                 sessionId: z.ZodString;
                 sourcePath: z.ZodOptional<z.ZodString>;
@@ -333,8 +333,8 @@ export declare const observedAgentSessionV1Schema: z.ZodObject<{
                 schemaVersion: z.ZodLiteral<1>;
                 provider: z.ZodEnum<{
                     "claude-code": "claude-code";
-                    codex: "codex";
                     opencode: "opencode";
+                    codex: "codex";
                 }>;
                 sessionId: z.ZodString;
                 sourcePath: z.ZodOptional<z.ZodString>;
@@ -349,8 +349,8 @@ export declare const observedAgentSessionV1Schema: z.ZodObject<{
         id: z.ZodString;
         provider: z.ZodEnum<{
             "claude-code": "claude-code";
-            codex: "codex";
             opencode: "opencode";
+            codex: "codex";
         }>;
         sessionId: z.ZodString;
         kind: z.ZodObject<{
@@ -369,8 +369,8 @@ export declare const observedAgentSessionV1Schema: z.ZodObject<{
                 schemaVersion: z.ZodLiteral<1>;
                 provider: z.ZodEnum<{
                     "claude-code": "claude-code";
-                    codex: "codex";
                     opencode: "opencode";
+                    codex: "codex";
                 }>;
                 sessionId: z.ZodString;
                 sourcePath: z.ZodOptional<z.ZodString>;
@@ -391,8 +391,8 @@ export declare const observedAgentSessionV1Schema: z.ZodObject<{
                 schemaVersion: z.ZodLiteral<1>;
                 provider: z.ZodEnum<{
                     "claude-code": "claude-code";
-                    codex: "codex";
                     opencode: "opencode";
+                    codex: "codex";
                 }>;
                 sessionId: z.ZodString;
                 sourcePath: z.ZodOptional<z.ZodString>;
@@ -413,8 +413,8 @@ export declare const observedAgentSessionV1Schema: z.ZodObject<{
                 schemaVersion: z.ZodLiteral<1>;
                 provider: z.ZodEnum<{
                     "claude-code": "claude-code";
-                    codex: "codex";
                     opencode: "opencode";
+                    codex: "codex";
                 }>;
                 sessionId: z.ZodString;
                 sourcePath: z.ZodOptional<z.ZodString>;
@@ -424,14 +424,15 @@ export declare const observedAgentSessionV1Schema: z.ZodObject<{
             }, z.core.$strip>>;
         }, z.core.$strip>;
     }, z.core.$strip>>;
+    contentObservedAt: z.ZodOptional<z.ZodString>;
     observedAt: z.ZodString;
 }, z.core.$strip>;
 export declare const providerCapabilitiesV1Schema: z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;
     provider: z.ZodEnum<{
         "claude-code": "claude-code";
-        codex: "codex";
         opencode: "opencode";
+        codex: "codex";
     }>;
     resume: z.ZodObject<{
         value: z.ZodBoolean;
@@ -445,8 +446,8 @@ export declare const providerCapabilitiesV1Schema: z.ZodObject<{
             schemaVersion: z.ZodLiteral<1>;
             provider: z.ZodEnum<{
                 "claude-code": "claude-code";
-                codex: "codex";
                 opencode: "opencode";
+                codex: "codex";
             }>;
             sessionId: z.ZodString;
             sourcePath: z.ZodOptional<z.ZodString>;
@@ -467,8 +468,8 @@ export declare const providerCapabilitiesV1Schema: z.ZodObject<{
             schemaVersion: z.ZodLiteral<1>;
             provider: z.ZodEnum<{
                 "claude-code": "claude-code";
-                codex: "codex";
                 opencode: "opencode";
+                codex: "codex";
             }>;
             sessionId: z.ZodString;
             sourcePath: z.ZodOptional<z.ZodString>;
@@ -494,8 +495,8 @@ export declare const providerCapabilitiesV1Schema: z.ZodObject<{
             schemaVersion: z.ZodLiteral<1>;
             provider: z.ZodEnum<{
                 "claude-code": "claude-code";
-                codex: "codex";
                 opencode: "opencode";
+                codex: "codex";
             }>;
             sessionId: z.ZodString;
             sourcePath: z.ZodOptional<z.ZodString>;
@@ -516,8 +517,8 @@ export declare const providerCapabilitiesV1Schema: z.ZodObject<{
             schemaVersion: z.ZodLiteral<1>;
             provider: z.ZodEnum<{
                 "claude-code": "claude-code";
-                codex: "codex";
                 opencode: "opencode";
+                codex: "codex";
             }>;
             sessionId: z.ZodString;
             sourcePath: z.ZodOptional<z.ZodString>;

package/dist/schemas/observedSessionV1.js

@@ -2,10 +2,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.providerSessionAdapterV1Schema = exports.providerCapabilitiesV1Schema = exports.observedAgentSessionV1Schema = exports.pendingUserRequestV1Schema = exports.observedValueV1Schema = exports.sessionEvidenceRefV1Schema = exports.observationProvenanceV1Schema = void 0;
 const zod_1 = require("zod");
+const providerIds_1 = require("../providerIds");
 exports.observationProvenanceV1Schema = zod_1.z.enum(['reported', 'estimated', 'inferred']);
 exports.sessionEvidenceRefV1Schema = zod_1.z.object({
     schemaVersion: zod_1.z.literal(1),
-    provider: zod_1.z.enum(['claude-code', 'opencode', 'codex']),
+    provider: zod_1.z.enum(providerIds_1.SESSION_PROVIDER_IDS),
     sessionId: zod_1.z.string().min(1),
     sourcePath: zod_1.z.string().optional(),
     eventIndex: zod_1.z.number().int().nonnegative().optional(),
@@ -22,7 +23,7 @@ exports.observedValueV1Schema = observedValueV1Schema;
 exports.pendingUserRequestV1Schema = zod_1.z.object({
     schemaVersion: zod_1.z.literal(1),
     id: zod_1.z.string().min(1),
-    provider: zod_1.z.enum(['claude-code', 'opencode', 'codex']),
+    provider: zod_1.z.enum(providerIds_1.SESSION_PROVIDER_IDS),
     sessionId: zod_1.z.string().min(1),
     kind: (0, exports.observedValueV1Schema)(zod_1.z.enum(['prompt_response', 'tool_approval', 'question'])),
     requestedAt: (0, exports.observedValueV1Schema)(zod_1.z.string()),
@@ -31,7 +32,7 @@ exports.pendingUserRequestV1Schema = zod_1.z.object({
 exports.observedAgentSessionV1Schema = zod_1.z.object({
     schemaVersion: zod_1.z.literal(1),
     identity: zod_1.z.object({
-        provider: zod_1.z.enum(['claude-code', 'opencode', 'codex']),
+        provider: zod_1.z.enum(providerIds_1.SESSION_PROVIDER_IDS),
         sessionId: zod_1.z.string().min(1),
         sourcePath: zod_1.z.string(),
     }),
@@ -56,11 +57,12 @@ exports.observedAgentSessionV1Schema = zod_1.z.object({
         costUsd: (0, exports.observedValueV1Schema)(zod_1.z.number().nonnegative().nullable()),
     }),
     pendingUserRequest: exports.pendingUserRequestV1Schema.nullable(),
+    contentObservedAt: zod_1.z.string().optional(),
     observedAt: zod_1.z.string(),
 });
 exports.providerCapabilitiesV1Schema = zod_1.z.object({
     schemaVersion: zod_1.z.literal(1),
-    provider: zod_1.z.enum(['claude-code', 'opencode', 'codex']),
+    provider: zod_1.z.enum(providerIds_1.SESSION_PROVIDER_IDS),
     resume: (0, exports.observedValueV1Schema)(zod_1.z.boolean()),
     forkLineage: (0, exports.observedValueV1Schema)(zod_1.z.boolean()),
     quotaSource: (0, exports.observedValueV1Schema)(zod_1.z.enum(['api', 'session', 'mixed', 'none'])),

package/dist/schemas/quota.d.ts

@@ -146,8 +146,8 @@ export declare const quotaFailureDescriptorSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const runtimeQuotaProviderSchema: z.ZodEnum<{
     codex: "codex";
-    claude: "claude";
     zai: "zai";
+    claude: "claude";
 }>;
 export declare const providerQuotaStateSchema: z.ZodObject<{
     fiveHour: z.ZodObject<{
@@ -243,8 +243,8 @@ export declare const providerQuotaStateSchema: z.ZodObject<{
     }, z.core.$strip>>>;
     runtimeProvider: z.ZodEnum<{
         codex: "codex";
-        claude: "claude";
         zai: "zai";
+        claude: "claude";
     }>;
 }, z.core.$strip>;
 export declare const claudeProviderQuotaStateSchema: z.ZodObject<{

package/dist/schemas/quota.js

@@ -12,6 +12,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.providerQuotaMapSchema = exports.zaiProviderQuotaStateSchema = exports.codexProviderQuotaStateSchema = exports.claudeProviderQuotaStateSchema = exports.providerQuotaStateSchema = exports.runtimeQuotaProviderSchema = exports.quotaFailureDescriptorSchema = exports.peakHoursStateSchema = exports.quotaStateSchema = exports.codexResetCreditsSnapshotSchema = exports.codexResetCreditSchema = exports.quotaSourceSchema = exports.quotaProviderIdSchema = exports.quotaFailureKindSchema = exports.quotaWindowSchema = void 0;
 const zod_1 = require("zod");
+const providerIds_1 = require("../providerIds");
 // ── QuotaWindow ──
 exports.quotaWindowSchema = zod_1.z.object({
     utilization: zod_1.z.number(),
@@ -25,7 +26,7 @@ exports.quotaFailureKindSchema = zod_1.z.enum([
     'server',
     'unknown',
 ]);
-exports.quotaProviderIdSchema = zod_1.z.enum(['claude-code', 'codex', 'zai']);
+exports.quotaProviderIdSchema = zod_1.z.enum(providerIds_1.QUOTA_PROVIDER_IDS);
 exports.quotaSourceSchema = zod_1.z.enum(['api', 'session', 'cache']);
 exports.codexResetCreditSchema = zod_1.z.object({
     title: zod_1.z.string().optional(),
@@ -88,11 +89,7 @@ exports.quotaFailureDescriptorSchema = zod_1.z.object({
     isRetryable: zod_1.z.boolean(),
 });
 // ── ProviderQuotaState / ProviderQuotaMap ──
-exports.runtimeQuotaProviderSchema = zod_1.z.enum([
-    'claude',
-    'codex',
-    'zai',
-]);
+exports.runtimeQuotaProviderSchema = zod_1.z.enum(providerIds_1.RUNTIME_QUOTA_PROVIDER_IDS);
 /** Fields ProviderQuotaState adds on top of QuotaState, minus the provider tag. */
 const providerQuotaExtensionShape = {
     accountLabel: zod_1.z.string().optional(),

package/dist/schemas/quotaHistory.d.ts

@@ -11,15 +11,15 @@
 import { z } from 'zod';
 export declare const quotaHistoryRuntimeProviderSchema: z.ZodEnum<{
     codex: "codex";
-    claude: "claude";
     zai: "zai";
+    claude: "claude";
 }>;
 export declare const quotaHistorySampleSchema: z.ZodObject<{
     timestamp: z.ZodString;
     runtimeProvider: z.ZodEnum<{
         codex: "codex";
-        claude: "claude";
         zai: "zai";
+        claude: "claude";
     }>;
     providerId: z.ZodString;
     workspaceId: z.ZodString;

package/dist/schemas/tokenEstimation.d.ts

@@ -6,9 +6,9 @@ export declare const tokenEstimateSchema: z.ZodObject<{
         "sidekick-fallback-v1": "sidekick-fallback-v1";
     }>;
     confidence: z.ZodEnum<{
+        exact: "exact";
         low: "low";
         medium: "medium";
-        exact: "exact";
     }>;
     provenance: z.ZodString;
 }, z.core.$strip>;

package/dist/sessionMonitor.d.ts

@@ -1,9 +1,15 @@
 import type { AggregatedMetrics, EventAggregatorOptions } from './aggregation/types';
 import type { SessionProviderBase } from './providers/types';
 import type { SessionEvent } from './types/sessionEvent';
+import type { ObservedSessionChangeBatch } from './observedSessionCollector';
 export interface SessionMonitorOptions extends EventAggregatorOptions {
     replayOnAttach?: boolean;
 }
+export interface SessionMonitorSubscribeOptions {
+    debounceMs?: number;
+    pollIntervalMs?: number;
+    onChange?: (batch: ObservedSessionChangeBatch) => void;
+}
 /**
  * UI-independent session monitor for library consumers. It owns one provider
  * reader and the canonical aggregator; hosts decide how often to call `poll()`.
@@ -14,6 +20,7 @@ export declare class SessionMonitor {
     private reader;
     private sessionPath;
     private readonly listeners;
+    private readonly subscriptions;
     private readonly replayOnAttach;
     constructor(provider: SessionProviderBase, options?: SessionMonitorOptions);
     attach(sessionPath: string, replay?: boolean): AggregatedMetrics;
@@ -21,6 +28,14 @@ export declare class SessionMonitor {
     poll(): SessionEvent[];
     process(event: SessionEvent): void;
     onEvent(listener: (event: SessionEvent) => void): () => void;
+    /**
+     * Watches the attached session with debouncing and catch-up polling. Matching
+     * fingerprint changes automatically call poll(); parsed events still flow
+     * through onEvent.
+     */
+    subscribe(options?: SessionMonitorSubscribeOptions): {
+        dispose(): void;
+    };
     getMetrics(): AggregatedMetrics;
     getSessionPath(): string | null;
     reset(): void;

package/dist/sessionMonitor.js

@@ -1,7 +1,42 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SessionMonitor = void 0;
+const fs = __importStar(require("node:fs"));
 const EventAggregator_1 = require("./aggregation/EventAggregator");
+const observedSessionCollector_1 = require("./observedSessionCollector");
 /**
  * UI-independent session monitor for library consumers. It owns one provider
  * reader and the canonical aggregator; hosts decide how often to call `poll()`.
@@ -12,6 +47,7 @@ class SessionMonitor {
     reader = null;
     sessionPath = null;
     listeners = new Set();
+    subscriptions = new Set();
     replayOnAttach;
     constructor(provider, options = {}) {
         this.provider = provider;
@@ -48,6 +84,110 @@ class SessionMonitor {
         this.listeners.add(listener);
         return () => this.listeners.delete(listener);
     }
+    /**
+     * Watches the attached session with debouncing and catch-up polling. Matching
+     * fingerprint changes automatically call poll(); parsed events still flow
+     * through onEvent.
+     */
+    subscribe(options = {}) {
+        const source = {
+            providerId: this.provider.id,
+            discover: async () => {
+                if (!this.sessionPath)
+                    return [];
+                let parts = (0, observedSessionCollector_1.fileFingerprintParts)(this.sessionPath);
+                if (!parts) {
+                    try {
+                        const metadata = this.provider.getSessionMetadataAsync
+                            ? await this.provider.getSessionMetadataAsync(this.sessionPath)
+                            : this.provider.getSessionMetadata?.(this.sessionPath);
+                        parts = metadata ? { sizeBytes: 0, mtimeMs: metadata.mtime.getTime() } : null;
+                    }
+                    catch {
+                        parts = null;
+                    }
+                }
+                if (!parts)
+                    return [];
+                return [
+                    {
+                        sessionId: this.provider.getSessionId(this.sessionPath),
+                        sourceKey: this.sessionPath,
+                        fingerprintHint: `${parts.sizeBytes}:${parts.mtimeMs}`,
+                        fingerprintParts: parts,
+                    },
+                ];
+            },
+            read: () => null,
+            subscribe: (listener, sourceOptions) => {
+                const watchers = new Set();
+                let pollTimer = null;
+                let roots;
+                try {
+                    roots = this.provider.getWatchRoots?.() ?? [this.provider.getProjectsBaseDir()];
+                }
+                catch {
+                    roots = [];
+                }
+                for (const root of new Set(roots)) {
+                    try {
+                        const watcher = fs.watch(root, { persistent: false, recursive: true }, listener);
+                        watchers.add(watcher);
+                        watcher.on('error', () => {
+                            watchers.delete(watcher);
+                            try {
+                                watcher.close();
+                            }
+                            catch {
+                                // Collector catch-up polling remains active.
+                            }
+                        });
+                    }
+                    catch {
+                        // Collector catch-up polling remains active.
+                    }
+                }
+                const pollIntervalMs = sourceOptions?.pollIntervalMs ?? 0;
+                if (pollIntervalMs > 0) {
+                    pollTimer = setInterval(listener, pollIntervalMs);
+                    pollTimer.unref?.();
+                }
+                return {
+                    dispose: () => {
+                        for (const watcher of watchers)
+                            watcher.close();
+                        watchers.clear();
+                        if (pollTimer)
+                            clearInterval(pollTimer);
+                    },
+                };
+            },
+        };
+        const collector = new observedSessionCollector_1.ObservedSessionCollector({ sources: [source] });
+        const changeSubscription = collector.subscribe((batch) => {
+            if (batch.changes.some((change) => change.reference.sourceKey === this.sessionPath)) {
+                this.poll();
+            }
+            try {
+                options.onChange?.(batch);
+            }
+            catch {
+                // Change callbacks are observational.
+            }
+        }, {
+            debounceMs: options.debounceMs,
+            pollIntervalMs: options.pollIntervalMs,
+        });
+        const disposable = {
+            dispose: () => {
+                changeSubscription.dispose();
+                collector.dispose();
+                this.subscriptions.delete(disposable);
+            },
+        };
+        this.subscriptions.add(disposable);
+        return disposable;
+    }
     getMetrics() {
         return this.aggregator.getMetrics();
     }
@@ -59,6 +199,8 @@ class SessionMonitor {
         this.aggregator.reset();
     }
     dispose() {
+        for (const subscription of [...this.subscriptions])
+            subscription.dispose();
         this.listeners.clear();
         this.reader = null;
         this.provider.dispose();

package/dist/sessionPreviews.d.ts

@@ -17,7 +17,7 @@
  *
  * @module sessionPreviews
  */
-import type { ProviderId, SessionProviderBase } from './providers/types';
+import type { ProviderId, SessionProviderBase, SessionProviderDiagnostic } from './providers/types';
 export interface SessionPreview {
     provider: ProviderId;
     sessionId: string;
@@ -47,14 +47,39 @@ export interface ListSessionPreviewsOptions extends ReadSessionPreviewOptions {
     /** Skip files whose mtime is not strictly newer than this — cheap incremental refresh. */
     since?: Date | string;
 }
+export interface AsyncSessionPreviewOptions {
+    /** Maximum concurrent stat/read units (default 4, hard-capped at 16). */
+    concurrency?: number;
+    /** Cooperative scheduler hook; defaults to setImmediate. */
+    yieldBetweenReads?: () => Promise<void> | void;
+}
+export interface ReadSessionPreviewAsyncOptions extends ReadSessionPreviewOptions, AsyncSessionPreviewOptions {
+}
+export interface ListSessionPreviewsAsyncOptions extends ListSessionPreviewsOptions, AsyncSessionPreviewOptions {
+}
+export interface SessionPreviewReadResult {
+    preview: SessionPreview | null;
+    diagnostics: SessionProviderDiagnostic[];
+}
+export interface SessionPreviewListResult {
+    previews: SessionPreview[];
+    diagnostics: SessionProviderDiagnostic[];
+}
 /**
  * Reads a bounded preview of one session file. Returns `null` when the file is
  * missing or unreadable; malformed content degrades to `null` fields instead
  * of throwing.
  */
 export declare function readSessionPreview(provider: SessionProviderBase, sessionPath: string, options?: ReadSessionPreviewOptions): SessionPreview | null;
+/** Event-loop-safe counterpart to readSessionPreview with per-call degradation status. */
+export declare function readSessionPreviewAsync(provider: SessionProviderBase, sessionPath: string, options?: ReadSessionPreviewAsyncOptions): Promise<SessionPreviewReadResult>;
 /**
  * Lists previews across providers, newest first. Enumeration is stat-only;
  * content is read only for the post-`limit` survivors.
  */
 export declare function listSessionPreviews(providers: SessionProviderBase[], options?: ListSessionPreviewsOptions): SessionPreview[];
+/**
+ * Lists previews without blocking the caller loop on corpus-wide synchronous
+ * work. SQLite-backed providers perform at most one subprocess per call.
+ */
+export declare function listSessionPreviewsAsync(providers: SessionProviderBase[], options?: ListSessionPreviewsAsyncOptions): Promise<SessionPreviewListResult>;