sidekick-shared 0.24.5 → 0.26.0

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;
@@ -37,6 +37,7 @@ export declare const quotaHistorySampleSchema: z.ZodObject<{
         api: "api";
         cache: "cache";
         session: "session";
+        statusline: "statusline";
     }>>;
     stale: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;

package/dist/schemas/quotaHistory.js

@@ -28,7 +28,7 @@ exports.quotaHistorySampleSchema = zod_1.z.object({
     sevenDay: zod_1.z.object({ utilization: zod_1.z.number(), resetsAt: zod_1.z.string() }),
     available: zod_1.z.boolean(),
     error: zod_1.z.string().optional(),
-    source: zod_1.z.enum(['session', 'cache', 'api']).optional(),
+    source: zod_1.z.enum(['session', 'cache', 'api', 'statusline']).optional(),
     stale: zod_1.z.boolean().optional(),
 });
 // ── QuotaHistoryDailyBucket ──

package/dist/schemas/sessionEvent.d.ts

@@ -52,6 +52,7 @@ export declare const sessionMessageSchema: z.ZodObject<{
         }, z.core.$strip>;
     }, z.core.$strip>>;
     content: z.ZodOptional<z.ZodUnknown>;
+    stop_reason: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const permissionModeSchema: z.ZodEnum<{
     default: "default";
@@ -136,6 +137,7 @@ export declare const userSessionEventSchema: z.ZodObject<{
             }, z.core.$strip>;
         }, z.core.$strip>>;
         content: z.ZodOptional<z.ZodUnknown>;
+        stop_reason: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
 }, z.core.$strip>;
 export declare const assistantSessionEventSchema: z.ZodObject<{
@@ -215,6 +217,7 @@ export declare const assistantSessionEventSchema: z.ZodObject<{
             }, z.core.$strip>;
         }, z.core.$strip>>;
         content: z.ZodOptional<z.ZodUnknown>;
+        stop_reason: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
 }, z.core.$strip>;
 export declare const summarySessionEventSchema: z.ZodType<SummarySessionEvent>;
@@ -295,6 +298,7 @@ export declare const systemSessionEventSchema: z.ZodObject<{
             }, z.core.$strip>;
         }, z.core.$strip>>;
         content: z.ZodOptional<z.ZodUnknown>;
+        stop_reason: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const toolUseSessionEventSchema: z.ZodObject<{
@@ -378,6 +382,7 @@ export declare const toolUseSessionEventSchema: z.ZodObject<{
             }, z.core.$strip>;
         }, z.core.$strip>>;
         content: z.ZodOptional<z.ZodUnknown>;
+        stop_reason: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const toolResultSessionEventSchema: z.ZodObject<{
@@ -462,6 +467,7 @@ export declare const toolResultSessionEventSchema: z.ZodObject<{
             }, z.core.$strip>;
         }, z.core.$strip>>;
         content: z.ZodOptional<z.ZodUnknown>;
+        stop_reason: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const sessionEventSchema: z.ZodType<SessionEvent>;

package/dist/schemas/sessionEvent.js

@@ -30,6 +30,7 @@ exports.sessionMessageSchema = zod_1.z.object({
     usage: exports.messageUsageSchema.optional(),
     normalizedUsage: usageNormalization_1.normalizedUsageSchema.optional(),
     content: zod_1.z.unknown().optional(),
+    stop_reason: zod_1.z.string().optional(),
 });
 // ── PermissionMode ──
 exports.permissionModeSchema = zod_1.z.enum([

package/dist/schemas/stateFile.d.ts

@@ -0,0 +1,198 @@
+/**
+ * Zod schema for the public `state.json` contract (`schemaVersion: 1`).
+ *
+ * Mirrors the interfaces in `stateFile.ts` (keep in sync when those change;
+ * fields are only ever added). Consumers validating the file from another
+ * process import this from `sidekick-shared/schemas`.
+ *
+ * @module schemas/stateFile
+ */
+import { z } from 'zod';
+export declare const stateFileWriterSchema: z.ZodEnum<{
+    statusline: "statusline";
+    "cli-dashboard": "cli-dashboard";
+    "vscode-dashboard": "vscode-dashboard";
+}>;
+export declare const stateFileQuotaWindowSchema: z.ZodObject<{
+    utilization: z.ZodNumber;
+    resetsAt: z.ZodString;
+}, z.core.$strip>;
+export declare const stateFileQuotaSchema: z.ZodObject<{
+    fiveHour: z.ZodObject<{
+        utilization: z.ZodNumber;
+        resetsAt: z.ZodString;
+    }, z.core.$strip>;
+    sevenDay: z.ZodObject<{
+        utilization: z.ZodNumber;
+        resetsAt: z.ZodString;
+    }, z.core.$strip>;
+    source: z.ZodNullable<z.ZodEnum<{
+        api: "api";
+        cache: "cache";
+        session: "session";
+        statusline: "statusline";
+    }>>;
+    capturedSource: z.ZodNullable<z.ZodEnum<{
+        api: "api";
+        session: "session";
+        statusline: "statusline";
+    }>>;
+    capturedAt: z.ZodNullable<z.ZodString>;
+    ageMs: z.ZodNullable<z.ZodNumber>;
+    freshness: z.ZodNullable<z.ZodEnum<{
+        fresh: "fresh";
+        aging: "aging";
+        stale: "stale";
+    }>>;
+}, z.core.$strip>;
+export declare const stateFileAccountSchema: z.ZodObject<{
+    providerId: z.ZodEnum<{
+        "claude-code": "claude-code";
+        codex: "codex";
+    }>;
+    id: z.ZodNullable<z.ZodString>;
+    label: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export declare const stateFileContextSchema: z.ZodObject<{
+    usedPercentage: z.ZodNullable<z.ZodNumber>;
+    contextWindowSize: z.ZodNullable<z.ZodNumber>;
+    totalInputTokens: z.ZodNullable<z.ZodNumber>;
+    totalOutputTokens: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const stateFileSessionSchema: z.ZodObject<{
+    sessionId: z.ZodNullable<z.ZodString>;
+    cwd: z.ZodNullable<z.ZodString>;
+    model: z.ZodNullable<z.ZodString>;
+    costUsd: z.ZodNullable<z.ZodNumber>;
+    durationMs: z.ZodNullable<z.ZodNumber>;
+    linesAdded: z.ZodNullable<z.ZodNumber>;
+    linesRemoved: z.ZodNullable<z.ZodNumber>;
+    promptCacheHitRatio: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const stateFileBillingBlockSchema: z.ZodObject<{
+    start: z.ZodString;
+    end: z.ZodString;
+    isActive: z.ZodBoolean;
+    tokens: z.ZodNumber;
+    costUsd: z.ZodNumber;
+    costProvenance: z.ZodEnum<{
+        none: "none";
+        reported: "reported";
+        estimated: "estimated";
+        unpriced: "unpriced";
+        mixed: "mixed";
+    }>;
+    burnRatePerMinute: z.ZodNumber;
+    projectedTokens: z.ZodNumber;
+    projectedCostUsd: z.ZodNumber;
+    remainingMs: z.ZodNumber;
+}, z.core.$strip>;
+export declare const sidekickStateFileSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    writtenAt: z.ZodString;
+    writer: z.ZodEnum<{
+        statusline: "statusline";
+        "cli-dashboard": "cli-dashboard";
+        "vscode-dashboard": "vscode-dashboard";
+    }>;
+    account: z.ZodNullable<z.ZodObject<{
+        providerId: z.ZodEnum<{
+            "claude-code": "claude-code";
+            codex: "codex";
+        }>;
+        id: z.ZodNullable<z.ZodString>;
+        label: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    quota: z.ZodObject<{
+        claude: z.ZodNullable<z.ZodObject<{
+            fiveHour: z.ZodObject<{
+                utilization: z.ZodNumber;
+                resetsAt: z.ZodString;
+            }, z.core.$strip>;
+            sevenDay: z.ZodObject<{
+                utilization: z.ZodNumber;
+                resetsAt: z.ZodString;
+            }, z.core.$strip>;
+            source: z.ZodNullable<z.ZodEnum<{
+                api: "api";
+                cache: "cache";
+                session: "session";
+                statusline: "statusline";
+            }>>;
+            capturedSource: z.ZodNullable<z.ZodEnum<{
+                api: "api";
+                session: "session";
+                statusline: "statusline";
+            }>>;
+            capturedAt: z.ZodNullable<z.ZodString>;
+            ageMs: z.ZodNullable<z.ZodNumber>;
+            freshness: z.ZodNullable<z.ZodEnum<{
+                fresh: "fresh";
+                aging: "aging";
+                stale: "stale";
+            }>>;
+        }, z.core.$strip>>;
+        codex: z.ZodNullable<z.ZodObject<{
+            fiveHour: z.ZodObject<{
+                utilization: z.ZodNumber;
+                resetsAt: z.ZodString;
+            }, z.core.$strip>;
+            sevenDay: z.ZodObject<{
+                utilization: z.ZodNumber;
+                resetsAt: z.ZodString;
+            }, z.core.$strip>;
+            source: z.ZodNullable<z.ZodEnum<{
+                api: "api";
+                cache: "cache";
+                session: "session";
+                statusline: "statusline";
+            }>>;
+            capturedSource: z.ZodNullable<z.ZodEnum<{
+                api: "api";
+                session: "session";
+                statusline: "statusline";
+            }>>;
+            capturedAt: z.ZodNullable<z.ZodString>;
+            ageMs: z.ZodNullable<z.ZodNumber>;
+            freshness: z.ZodNullable<z.ZodEnum<{
+                fresh: "fresh";
+                aging: "aging";
+                stale: "stale";
+            }>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    context: z.ZodNullable<z.ZodObject<{
+        usedPercentage: z.ZodNullable<z.ZodNumber>;
+        contextWindowSize: z.ZodNullable<z.ZodNumber>;
+        totalInputTokens: z.ZodNullable<z.ZodNumber>;
+        totalOutputTokens: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>;
+    session: z.ZodNullable<z.ZodObject<{
+        sessionId: z.ZodNullable<z.ZodString>;
+        cwd: z.ZodNullable<z.ZodString>;
+        model: z.ZodNullable<z.ZodString>;
+        costUsd: z.ZodNullable<z.ZodNumber>;
+        durationMs: z.ZodNullable<z.ZodNumber>;
+        linesAdded: z.ZodNullable<z.ZodNumber>;
+        linesRemoved: z.ZodNullable<z.ZodNumber>;
+        promptCacheHitRatio: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>;
+    billingBlock: z.ZodNullable<z.ZodObject<{
+        start: z.ZodString;
+        end: z.ZodString;
+        isActive: z.ZodBoolean;
+        tokens: z.ZodNumber;
+        costUsd: z.ZodNumber;
+        costProvenance: z.ZodEnum<{
+            none: "none";
+            reported: "reported";
+            estimated: "estimated";
+            unpriced: "unpriced";
+            mixed: "mixed";
+        }>;
+        burnRatePerMinute: z.ZodNumber;
+        projectedTokens: z.ZodNumber;
+        projectedCostUsd: z.ZodNumber;
+        remainingMs: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;

package/dist/schemas/stateFile.js

@@ -0,0 +1,77 @@
+"use strict";
+/**
+ * Zod schema for the public `state.json` contract (`schemaVersion: 1`).
+ *
+ * Mirrors the interfaces in `stateFile.ts` (keep in sync when those change;
+ * fields are only ever added). Consumers validating the file from another
+ * process import this from `sidekick-shared/schemas`.
+ *
+ * @module schemas/stateFile
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sidekickStateFileSchema = exports.stateFileBillingBlockSchema = exports.stateFileSessionSchema = exports.stateFileContextSchema = exports.stateFileAccountSchema = exports.stateFileQuotaSchema = exports.stateFileQuotaWindowSchema = exports.stateFileWriterSchema = void 0;
+const zod_1 = require("zod");
+exports.stateFileWriterSchema = zod_1.z.enum([
+    'statusline',
+    'cli-dashboard',
+    'vscode-dashboard',
+]);
+exports.stateFileQuotaWindowSchema = zod_1.z.object({
+    utilization: zod_1.z.number(),
+    resetsAt: zod_1.z.string(),
+});
+exports.stateFileQuotaSchema = zod_1.z.object({
+    fiveHour: exports.stateFileQuotaWindowSchema,
+    sevenDay: exports.stateFileQuotaWindowSchema,
+    source: zod_1.z.enum(['api', 'session', 'cache', 'statusline']).nullable(),
+    capturedSource: zod_1.z.enum(['api', 'session', 'statusline']).nullable(),
+    capturedAt: zod_1.z.string().nullable(),
+    ageMs: zod_1.z.number().nullable(),
+    freshness: zod_1.z.enum(['fresh', 'aging', 'stale']).nullable(),
+});
+exports.stateFileAccountSchema = zod_1.z.object({
+    providerId: zod_1.z.enum(['claude-code', 'codex']),
+    id: zod_1.z.string().nullable(),
+    label: zod_1.z.string().nullable(),
+});
+exports.stateFileContextSchema = zod_1.z.object({
+    usedPercentage: zod_1.z.number().nullable(),
+    contextWindowSize: zod_1.z.number().nullable(),
+    totalInputTokens: zod_1.z.number().nullable(),
+    totalOutputTokens: zod_1.z.number().nullable(),
+});
+exports.stateFileSessionSchema = zod_1.z.object({
+    sessionId: zod_1.z.string().nullable(),
+    cwd: zod_1.z.string().nullable(),
+    model: zod_1.z.string().nullable(),
+    costUsd: zod_1.z.number().nullable(),
+    durationMs: zod_1.z.number().nullable(),
+    linesAdded: zod_1.z.number().nullable(),
+    linesRemoved: zod_1.z.number().nullable(),
+    promptCacheHitRatio: zod_1.z.number().nullable(),
+});
+exports.stateFileBillingBlockSchema = zod_1.z.object({
+    start: zod_1.z.string(),
+    end: zod_1.z.string(),
+    isActive: zod_1.z.boolean(),
+    tokens: zod_1.z.number(),
+    costUsd: zod_1.z.number(),
+    costProvenance: zod_1.z.enum(['reported', 'estimated', 'mixed', 'unpriced', 'none']),
+    burnRatePerMinute: zod_1.z.number(),
+    projectedTokens: zod_1.z.number(),
+    projectedCostUsd: zod_1.z.number(),
+    remainingMs: zod_1.z.number(),
+});
+exports.sidekickStateFileSchema = zod_1.z.object({
+    schemaVersion: zod_1.z.literal(1),
+    writtenAt: zod_1.z.string(),
+    writer: exports.stateFileWriterSchema,
+    account: exports.stateFileAccountSchema.nullable(),
+    quota: zod_1.z.object({
+        claude: exports.stateFileQuotaSchema.nullable(),
+        codex: exports.stateFileQuotaSchema.nullable(),
+    }),
+    context: exports.stateFileContextSchema.nullable(),
+    session: exports.stateFileSessionSchema.nullable(),
+    billingBlock: exports.stateFileBillingBlockSchema.nullable(),
+});

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/schemas/transcript.js

@@ -78,6 +78,8 @@ exports.canonicalSessionTranscriptSchema = zod_1.z.object({
             totalTokens: zod_1.z.number().finite().nonnegative(),
         }),
         totalCostUsd: zod_1.z.number().finite().nonnegative().nullable(),
+        pricedCostUsd: zod_1.z.number().finite().nonnegative(),
+        unpricedEvents: zod_1.z.number().int().nonnegative(),
     }),
     provenance: zod_1.z.object({
         source: zod_1.z.literal('session-events'),

package/dist/sessionFingerprint.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Size/mtime fingerprints for session sources.
+ *
+ * Shared by the observed-session collector, the V1 adapter's watch loop, and
+ * the usage cache, so "has this session changed?" is answered the same way
+ * everywhere without re-reading content.
+ *
+ * @module sessionFingerprint
+ */
+import type { SessionProviderBase } from './providers/types';
+export interface ObservedSessionFingerprintParts {
+    sizeBytes: number;
+    mtimeMs: number;
+}
+/** Structured size/mtime fingerprint; returns null for inaccessible or synthetic paths. */
+export declare function fileFingerprintParts(sourcePath: string): ObservedSessionFingerprintParts | null;
+/** Size/mtime fingerprint suitable for retry bypass; returns null for synthetic DB locators. */
+export declare function fileFingerprint(sourcePath: string): string | null;
+/** Canonical `${sizeBytes}:${mtimeMs}` form of a fingerprint. */
+export declare function fingerprintString(parts: ObservedSessionFingerprintParts): string;
+/**
+ * Fingerprint for a session path, falling back to provider metadata (mtime
+ * only) for database-backed sessions whose path is synthetic.
+ */
+export declare function sessionFingerprintParts(provider: SessionProviderBase, sessionPath: string): ObservedSessionFingerprintParts | null;

package/dist/sessionFingerprint.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * Size/mtime fingerprints for session sources.
+ *
+ * Shared by the observed-session collector, the V1 adapter's watch loop, and
+ * the usage cache, so "has this session changed?" is answered the same way
+ * everywhere without re-reading content.
+ *
+ * @module sessionFingerprint
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fileFingerprintParts = fileFingerprintParts;
+exports.fileFingerprint = fileFingerprint;
+exports.fingerprintString = fingerprintString;
+exports.sessionFingerprintParts = sessionFingerprintParts;
+const node_fs_1 = require("node:fs");
+/** Structured size/mtime fingerprint; returns null for inaccessible or synthetic paths. */
+function fileFingerprintParts(sourcePath) {
+    try {
+        const stat = (0, node_fs_1.statSync)(sourcePath);
+        return { sizeBytes: stat.size, mtimeMs: stat.mtimeMs };
+    }
+    catch {
+        return null;
+    }
+}
+/** Size/mtime fingerprint suitable for retry bypass; returns null for synthetic DB locators. */
+function fileFingerprint(sourcePath) {
+    const parts = fileFingerprintParts(sourcePath);
+    return parts ? fingerprintString(parts) : null;
+}
+/** Canonical `${sizeBytes}:${mtimeMs}` form of a fingerprint. */
+function fingerprintString(parts) {
+    return `${parts.sizeBytes}:${parts.mtimeMs}`;
+}
+/**
+ * Fingerprint for a session path, falling back to provider metadata (mtime
+ * only) for database-backed sessions whose path is synthetic.
+ */
+function sessionFingerprintParts(provider, sessionPath) {
+    const parts = fileFingerprintParts(sessionPath);
+    if (parts)
+        return parts;
+    const metadata = provider.getSessionMetadata?.(sessionPath);
+    return metadata ? { sizeBytes: 0, mtimeMs: metadata.mtime.getTime() } : null;
+}

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();