sidekick-shared 0.29.0 → 0.30.0

package/dist/types/sessionEvent.d.ts

@@ -85,7 +85,7 @@ export interface SessionEventBase {
     /** Provider-reported git branch for this event/session. */
     gitBranch?: string;
     /** Permission mode active when this event occurred */
-    permissionMode?: 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan';
+    permissionMode?: PermissionMode;
     /** Subscription rate limits, when provided by the session source. */
     rateLimits?: {
         primary?: {
@@ -166,6 +166,11 @@ export interface SystemSessionEvent extends SessionEventBase {
     type: 'system';
     /** Bookkeeping-only system rows legitimately have no message. */
     message?: SessionMessage;
+    /**
+     * The provider's system-line subtype, when it wrote one (Claude Code:
+     * `turn_duration`, `compact_boundary`, `agents_killed`, …).
+     */
+    subtype?: string;
 }
 export interface ToolUseSessionEvent extends SessionEventBase {
     type: 'tool_use';
@@ -187,9 +192,11 @@ export interface ToolResultSessionEvent extends SessionEventBase {
 /** Canonical provider-neutral event contract. */
 export type SessionEvent = UserSessionEvent | AssistantSessionEvent | SummarySessionEvent | SystemSessionEvent | ToolUseSessionEvent | ToolResultSessionEvent;
 /**
- * Permission mode values from Claude Code JSONL.
+ * Permission mode values from Claude Code JSONL. `auto` approves or denies
+ * permission prompts with a model classifier; `dontAsk` denies anything not
+ * pre-approved. Unknown future modes are dropped by the schema, not rejected.
  */
-export type PermissionMode = 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan';
+export type PermissionMode = 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan' | 'auto' | 'dontAsk';
 /**
  * A permission mode change event in the session timeline.
  */
@@ -423,6 +430,34 @@ export interface SubagentStats {
     endTime?: Date;
     /** Duration in milliseconds */
     durationMs?: number;
+    /**
+     * Codex: the subagent's rollout file — the `.jsonl`, or the `.jsonl.zst`
+     * when only the compressed one exists (with `includeCompressedRollouts`).
+     */
+    filePath?: string;
+    /**
+     * Codex: the parent's spawn call (`spawn_agent` call id) that started this
+     * subagent — the tool-use id of that call in the parent's events.
+     */
+    spawnToolUseId?: string;
+    /** Codex: the display nickname Codex gave the subagent (e.g. `Banach`). */
+    agentNickname?: string;
+    /** Codex: the subagent's agent path (e.g. `/root/review_builder`). */
+    agentPath?: string;
+    /**
+     * Codex: the thread that spawned this subagent — the session's id for its
+     * own children, another subagent's `agentId` below that.
+     */
+    parentAgentId?: string;
+    /** Codex: spawn depth — 1 for the session's own children, 2 for theirs, … */
+    depth?: number;
+    /**
+     * The subagent's transcript ended cleanly: Claude Code, its last assistant
+     * turn stopped with `end_turn` / `stop_sequence` and left no tool call
+     * unanswered; Codex, its last own turn ended with `task_complete`. A later
+     * prompt (a resumed agent) clears it. Absent when unknown.
+     */
+    endedCleanly?: boolean;
 }
 /**
  * Pending user request awaiting assistant response.

package/dist/usage/claudeUsageDedupe.d.ts

@@ -22,6 +22,24 @@ import type { SessionEvent } from '../types/sessionEvent';
 export declare const SYNTHETIC_MODEL = "<synthetic>";
 /** Attach Anthropic-semantics normalized usage and Claude Code provenance to an event. */
 export declare function normalizeClaudeUsage(event: SessionEvent): SessionEvent;
+/** Tokens a {@link ClaudeUsageDeduper} has already counted for one message id. */
+export interface ClaudeUsageDedupeBuckets {
+    input: number;
+    cacheRead: number;
+    cacheWrite: number;
+    output: number;
+    reasoning: number;
+}
+/**
+ * JSON-serializable state of a {@link ClaudeUsageDeduper}, from
+ * `exportState()`, for `importState()` in a reader resumed at the same
+ * position (for example from a persisted session snapshot).
+ */
+export interface ClaudeUsageDedupeState {
+    version: 1;
+    /** `[message id, counted tokens]` pairs, oldest first. */
+    entries: Array<[string, ClaudeUsageDedupeBuckets]>;
+}
 /**
  * Per-reader dedupe state. Split lines of one response are adjacent, so a
  * bounded map (oldest keys evicted first) is enough.
@@ -40,6 +58,19 @@ export declare class ClaudeUsageDeduper {
     /** Whether a message id has already been counted by this deduper. */
     has(id: string): boolean;
     reset(): void;
+    /**
+     * The most recent `limit` message ids and the tokens counted for each,
+     * oldest first. Split lines of one response are adjacent, so a reader
+     * resumed at the position this was taken at needs only the last few.
+     */
+    exportState(limit?: number): ClaudeUsageDedupeState;
+    /**
+     * Replaces this deduper's state with one from {@link exportState}. Returns
+     * false, changing nothing, when `state` is not a valid version-1 state
+     * (wrong shape, empty ids, or counts that are not finite non-negative
+     * numbers). Entries beyond this deduper's capacity drop oldest first.
+     */
+    importState(state: unknown): boolean;
     private remember;
 }
 /**

package/dist/usage/claudeUsageDedupe.js

@@ -64,6 +64,25 @@ function normalizeClaudeUsage(event) {
         },
     };
 }
+const BUCKET_KEYS = ['input', 'cacheRead', 'cacheWrite', 'output', 'reasoning'];
+/** Entries {@link ClaudeUsageDeduper.exportState} keeps by default. */
+const DEFAULT_EXPORT_LIMIT = 256;
+function isCount(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+function bucketsFrom(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const record = value;
+    const buckets = {};
+    for (const key of BUCKET_KEYS) {
+        const count = record[key];
+        if (!isCount(count))
+            return null;
+        buckets[key] = count;
+    }
+    return buckets;
+}
 function bucketsOf(usage) {
     return {
         input: usage.uncachedInputTokens,
@@ -168,6 +187,55 @@ class ClaudeUsageDeduper {
     reset() {
         this.seen.clear();
     }
+    /**
+     * The most recent `limit` message ids and the tokens counted for each,
+     * oldest first. Split lines of one response are adjacent, so a reader
+     * resumed at the position this was taken at needs only the last few.
+     */
+    exportState(limit = DEFAULT_EXPORT_LIMIT) {
+        const count = limit >= 0 ? Math.min(this.seen.size, Math.floor(limit)) : 0;
+        const entries = [];
+        if (count > 0) {
+            let skip = this.seen.size - count;
+            for (const [id, buckets] of this.seen) {
+                if (skip > 0) {
+                    skip -= 1;
+                    continue;
+                }
+                entries.push([id, { ...buckets }]);
+            }
+        }
+        return { version: 1, entries };
+    }
+    /**
+     * Replaces this deduper's state with one from {@link exportState}. Returns
+     * false, changing nothing, when `state` is not a valid version-1 state
+     * (wrong shape, empty ids, or counts that are not finite non-negative
+     * numbers). Entries beyond this deduper's capacity drop oldest first.
+     */
+    importState(state) {
+        if (!state || typeof state !== 'object')
+            return false;
+        const { version, entries } = state;
+        if (version !== 1 || !Array.isArray(entries))
+            return false;
+        const parsed = [];
+        for (const entry of entries) {
+            if (!Array.isArray(entry) || entry.length !== 2)
+                return false;
+            const [id, value] = entry;
+            if (typeof id !== 'string' || id.length === 0)
+                return false;
+            const buckets = bucketsFrom(value);
+            if (!buckets)
+                return false;
+            parsed.push([id, buckets]);
+        }
+        this.seen.clear();
+        for (const [id, buckets] of parsed)
+            this.remember(id, buckets);
+        return true;
+    }
     remember(id, buckets) {
         this.seen.delete(id);
         this.seen.set(id, buckets);

package/dist/usage/usageEvents.d.ts

@@ -15,7 +15,10 @@
  * tagged with the subagent, and their sizes and mtimes join the fingerprint.
  * (Codex spawned subagents and forks are top-level rollouts, already listed
  * as sessions of their own; their events are tagged with the parent read
- * from the rollout's first line.)
+ * from the rollout's first line; the parent history a forked child embeds
+ * is not counted (it carries no token usage). Compressed rollouts
+ * (`….jsonl.zst`) are read when a Codex provider was created with
+ * `includeCompressedRollouts`.)
  *
  * Each event also carries the ordinal of the human prompt it answered, from
  * the same scanner as `collectPromptHistory()`, so usage joins prompt history

package/dist/usage/usageEvents.js

@@ -16,7 +16,10 @@
  * tagged with the subagent, and their sizes and mtimes join the fingerprint.
  * (Codex spawned subagents and forks are top-level rollouts, already listed
  * as sessions of their own; their events are tagged with the parent read
- * from the rollout's first line.)
+ * from the rollout's first line; the parent history a forked child embeds
+ * is not counted (it carries no token usage). Compressed rollouts
+ * (`….jsonl.zst`) are read when a Codex provider was created with
+ * `includeCompressedRollouts`.)
  *
  * Each event also carries the ordinal of the human prompt it answered, from
  * the same scanner as `collectPromptHistory()`, so usage joins prompt history

package/dist/watchers/eventBridge.js

@@ -11,6 +11,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toFollowEvents = toFollowEvents;
 const toolSummary_1 = require("../formatters/toolSummary");
+const subagentSpawn_1 = require("../subagentSpawn");
+const subagentActivity_1 = require("../subagentActivity");
 /**
  * Converts a single SessionEvent to one or more FollowEvents.
  *
@@ -151,6 +153,49 @@ function toFollowEvents(event, providerId) {
             break;
         }
         case 'system': {
+            // A background task's notice (opt-in reader event): its summary, not the raw block.
+            const notification = (0, subagentSpawn_1.isTaskNotificationSystemEvent)(event)
+                ? (0, subagentSpawn_1.taskNotificationFromEvent)(event)
+                : null;
+            if (notification) {
+                events.push({
+                    providerId,
+                    type: 'system',
+                    timestamp: ts,
+                    summary: notification.summary ?? `Background task ${notification.status ?? 'finished'}`,
+                    raw: event,
+                });
+                break;
+            }
+            // The user stopping background agents, or a background agent's final status.
+            const stopped = (0, subagentSpawn_1.agentsStoppedNoticeFromEvent)(event);
+            const taskStatus = stopped ? null : (0, subagentSpawn_1.taskStatusFromEvent)(event);
+            if (stopped || taskStatus || (0, subagentSpawn_1.isAgentsKilledSystemEvent)(event)) {
+                events.push({
+                    providerId,
+                    type: 'system',
+                    timestamp: ts,
+                    summary: stopped
+                        ? (0, subagentSpawn_1.describeAgentsStopped)(stopped)
+                        : taskStatus
+                            ? (0, subagentSpawn_1.describeTaskStatus)(taskStatus)
+                            : (0, subagentSpawn_1.describeAgentsStopped)(null),
+                    raw: event,
+                });
+                break;
+            }
+            // A subagent lifecycle record (opt-in Codex parser event): a content-free summary.
+            const activity = (0, subagentActivity_1.subagentActivityFromEvent)(event);
+            if (activity) {
+                events.push({
+                    providerId,
+                    type: 'system',
+                    timestamp: ts,
+                    summary: (0, subagentActivity_1.describeSubagentActivity)(activity),
+                    raw: event,
+                });
+                break;
+            }
             const text = extractTextContent(event.message?.content);
             const label = event.message?.sourceLabel || event.message?.role || 'system';
             const summary = text ||

package/dist/watchers/factory.d.ts

@@ -8,6 +8,12 @@ export interface CreateWatcherOptions {
     workspacePath: string;
     sessionId?: string;
     callbacks: SessionWatcherCallbacks;
+    /**
+     * Claude Code only: also emit a `system` event for each mid-turn
+     * task-notification attachment, so an `EventAggregator` fed by this watcher
+     * can finish background subagents. Default `false`.
+     */
+    includeTaskNotifications?: boolean;
 }
 /**
  * Resolve the session a command should act on: an exact or unique-prefix

package/dist/watchers/factory.js

@@ -78,13 +78,15 @@ function resolveSessionPath(provider, workspacePath, sessionId) {
 function createWatcher(options) {
     const { provider, workspacePath, sessionId, callbacks } = options;
     const sessionPath = resolveSessionPath(provider, workspacePath, sessionId);
-    const watcher = createWatcherForProvider(provider, sessionPath, callbacks);
+    const watcher = createWatcherForProvider(provider, sessionPath, callbacks, {
+        includeTaskNotifications: options.includeTaskNotifications === true,
+    });
     return { watcher, sessionPath };
 }
-function createWatcherForProvider(provider, sessionPath, callbacks) {
+function createWatcherForProvider(provider, sessionPath, callbacks, jsonlOptions) {
     switch (provider.id) {
         case 'claude-code':
-            return new jsonlWatcher_1.JsonlSessionWatcher(provider.id, sessionPath, callbacks);
+            return new jsonlWatcher_1.JsonlSessionWatcher(provider.id, sessionPath, callbacks, jsonlOptions);
         case 'codex':
             return new providerReaderWatcher_1.ProviderReaderSessionWatcher(provider, sessionPath, callbacks);
         case 'opencode': {

package/dist/watchers/jsonlTail.d.ts

@@ -53,10 +53,11 @@ export interface JsonlTailReadResult<T> extends JsonlTailBatch {
     reset?: JsonlTailReset;
 }
 /**
- * A JSON-serializable resume point from {@link JsonlTail.checkpoint}. It
- * identifies the file by device and inode plus a digest of its first bytes,
- * so a new tail (in this or a later process) can verify it is still reading
- * the same, append-only file before continuing from `offset`.
+ * A JSON-serializable resume point from {@link JsonlTail.checkpoint} or
+ * {@link captureJsonlCheckpoint}. It identifies the file by device and inode
+ * plus a digest of its first bytes, so a new tail (in this or a later
+ * process) or {@link verifyJsonlCheckpoint} can confirm the file is still the
+ * same, append-only one before anything continues from `offset`.
  */
 export interface JsonlTailCheckpoint {
     version: typeof JSONL_TAIL_CHECKPOINT_VERSION;
@@ -151,3 +152,25 @@ export interface JsonlTail<T = unknown> {
     resumeFrom(checkpoint: unknown): boolean;
 }
 export declare function createJsonlTail<T>(options: JsonlTailOptions<T>): JsonlTail<T>;
+/**
+ * Records a {@link JsonlTailCheckpoint} for byte `offset` of `filePath`
+ * without a tail, for readers that keep their own offset (a snapshot that
+ * stores a reader position, for example). The checkpoint carries the file's
+ * current device and inode and a digest of its first bytes, so
+ * {@link verifyJsonlCheckpoint} (or {@link JsonlTail.resumeFrom}) can later
+ * tell whether `offset` still refers to the same, append-only content.
+ *
+ * Returns `null` when the file is missing or unreadable, or when `offset` is
+ * not a resume-safe position in it: negative, past the end, or not 0 and not
+ * just after a newline. Follows symbolic links.
+ */
+export declare function captureJsonlCheckpoint(filePath: string, offset: number): JsonlTailCheckpoint | null;
+/**
+ * Whether `checkpoint` (any value, typically parsed from JSON) is a valid
+ * {@link JsonlTailCheckpoint} that still describes `filePath`: same device
+ * and inode, the recorded first bytes unchanged, and its offset within the
+ * file and just after a newline (or 0). This is the check
+ * {@link JsonlTail.resumeFrom} applies. `false` on any error, including a
+ * missing file. Follows symbolic links.
+ */
+export declare function verifyJsonlCheckpoint(filePath: string, checkpoint: unknown): boolean;

package/dist/watchers/jsonlTail.js

@@ -39,8 +39,11 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.JsonlTailSymlinkError = exports.JSONL_TAIL_CHECKPOINT_VERSION = exports.DEFAULT_JSONL_TAIL_MAX_LINE_BYTES = exports.DEFAULT_JSONL_TAIL_READ_BYTES = void 0;
 exports.createJsonlTail = createJsonlTail;
+exports.captureJsonlCheckpoint = captureJsonlCheckpoint;
+exports.verifyJsonlCheckpoint = verifyJsonlCheckpoint;
 const fs = __importStar(require("fs"));
 const fileHead_1 = require("../fileHead");
+const fileContinuity_1 = require("../fileContinuity");
 const jsonl_1 = require("../parsers/jsonl");
 const DEFAULT_DEBOUNCE_MS = 100;
 const DEFAULT_CATCHUP_INTERVAL_MS = 30_000;
@@ -98,6 +101,63 @@ exports.JsonlTailSymlinkError = JsonlTailSymlinkError;
 function createJsonlTail(options) {
     return new JsonlTailReader(options);
 }
+/**
+ * Records a {@link JsonlTailCheckpoint} for byte `offset` of `filePath`
+ * without a tail, for readers that keep their own offset (a snapshot that
+ * stores a reader position, for example). The checkpoint carries the file's
+ * current device and inode and a digest of its first bytes, so
+ * {@link verifyJsonlCheckpoint} (or {@link JsonlTail.resumeFrom}) can later
+ * tell whether `offset` still refers to the same, append-only content.
+ *
+ * Returns `null` when the file is missing or unreadable, or when `offset` is
+ * not a resume-safe position in it: negative, past the end, or not 0 and not
+ * just after a newline. Follows symbolic links.
+ */
+function captureJsonlCheckpoint(filePath, offset) {
+    if (!Number.isSafeInteger(offset) || offset < 0)
+        return null;
+    let fd = null;
+    try {
+        fd = fs.openSync(filePath, 'r');
+        const stat = fs.fstatSync(fd);
+        if (offset > stat.size)
+            return null;
+        if (offset > 0 && readAt(fd, offset - 1, 1)[0] !== 0x0a)
+            return null;
+        return checkpointOf(offset, stat, (0, fileHead_1.fileHeadOf)(readPrefix(fd, stat)));
+    }
+    catch {
+        return null;
+    }
+    finally {
+        closeQuietly(fd);
+    }
+}
+/**
+ * Whether `checkpoint` (any value, typically parsed from JSON) is a valid
+ * {@link JsonlTailCheckpoint} that still describes `filePath`: same device
+ * and inode, the recorded first bytes unchanged, and its offset within the
+ * file and just after a newline (or 0). This is the check
+ * {@link JsonlTail.resumeFrom} applies. `false` on any error, including a
+ * missing file. Follows symbolic links.
+ */
+function verifyJsonlCheckpoint(filePath, checkpoint) {
+    const parsed = parseCheckpoint(checkpoint);
+    if (parsed === null)
+        return false;
+    let fd = null;
+    try {
+        fd = fs.openSync(filePath, 'r');
+        const stat = fs.fstatSync(fd);
+        return checkpointMatches(parsed, fd, stat, readPrefix(fd, stat));
+    }
+    catch {
+        return false;
+    }
+    finally {
+        closeQuietly(fd);
+    }
+}
 class JsonlTailReader {
     options;
     active = false;
@@ -109,10 +169,8 @@ class JsonlTailReader {
     /** Inside a line over `maxLineBytes`: drop bytes until its newline. */
     skippingLine = false;
     currentLine = { offset: 0, length: 0 };
-    /** Identity and prefix of the file the offsets refer to, once read. */
-    identity = null;
-    head = null;
-    lastMtimeMs = -1;
+    /** Identity, mtime, and prefix of the file the offsets refer to, once read. */
+    continuity = new fileContinuity_1.FileContinuity();
     maxReadBytes;
     maxLineBytes;
     rewritePolicy;
@@ -320,21 +378,10 @@ class JsonlTailReader {
     }
     /** Whether the continuity check needs bytes from the file. */
     probeNeeded(stat) {
-        return (this.identity === null ||
-            stat.dev !== this.identity.dev ||
-            stat.ino !== this.identity.ino ||
-            stat.size < this.readOffset ||
-            stat.mtimeMs !== this.lastMtimeMs ||
-            this.head === null ||
-            this.head.bytes < Math.min(fileHead_1.HEAD_BYTES, stat.size));
+        return this.continuity.needsProbe(stat, this.readOffset);
     }
     probeSync(fd, stat) {
-        return {
-            prefix: readAt(fd, 0, Math.min(fileHead_1.HEAD_BYTES, stat.size)),
-            before: this.committedOffset > 0 && this.committedOffset <= stat.size
-                ? readAt(fd, this.committedOffset - 1, 1)
-                : null,
-        };
+        return (0, fileContinuity_1.probeFileContinuity)(fd, stat, this.committedOffset);
     }
     async probeAsync(handle, stat) {
         const committedOffset = this.committedOffset;
@@ -351,31 +398,16 @@ class JsonlTailReader {
      * newline. `null` when it can continue.
      */
     resetReason(stat, probe) {
-        if (this.identity && (stat.dev !== this.identity.dev || stat.ino !== this.identity.ino)) {
-            return 'replaced';
-        }
-        if (stat.size < this.readOffset)
-            return 'truncated';
-        if (this.identity && stat.mtimeMs !== this.lastMtimeMs && probe) {
-            if (this.head && !(0, fileHead_1.headMatches)(this.head, probe.prefix))
-                return 'rewritten';
-            if (probe.before && probe.before[0] !== 0x0a)
-                return 'rewritten';
-        }
-        return null;
+        return this.continuity.reasonFor(stat, this.readOffset, probe);
     }
     /** Records the identity and prefix of the file the offsets now refer to. */
     adoptFile(stat, probe) {
-        this.identity = { dev: stat.dev, ino: stat.ino };
-        this.lastMtimeMs = stat.mtimeMs;
-        if (probe && (!this.head || this.head.bytes < Math.min(fileHead_1.HEAD_BYTES, stat.size))) {
-            this.head = (0, fileHead_1.fileHeadOf)(probe.prefix);
-        }
+        this.continuity.record(stat, probe);
     }
     reset(reason, offset) {
         const previousOffset = this.committedOffset;
         this.position(offset);
-        this.head = null;
+        this.continuity.discardHead();
         if (reason === 'replaced' && this.active) {
             // fs.watch follows the old inode; watch the file now at the path.
             this.fsWatcher?.close();
@@ -450,12 +482,7 @@ class JsonlTailReader {
         this.position(Math.max(0, offset));
     }
     checkpoint() {
-        return {
-            version: exports.JSONL_TAIL_CHECKPOINT_VERSION,
-            offset: this.committedOffset,
-            identity: this.identity ? { dev: this.identity.dev, ino: this.identity.ino } : null,
-            prefixDigest: this.head ? { bytes: this.head.bytes, hash: this.head.hash } : null,
-        };
+        return checkpointOf(this.committedOffset, this.continuity.knownIdentity, this.continuity.knownHead);
     }
     resumeFrom(checkpoint) {
         this.generation += 1;
@@ -465,7 +492,7 @@ class JsonlTailReader {
         try {
             fd = this.openSync();
             const stat = fs.fstatSync(fd);
-            const prefix = readAt(fd, 0, Math.min(fileHead_1.HEAD_BYTES, stat.size));
+            const prefix = readPrefix(fd, stat);
             const matches = parsed !== null && checkpointMatches(parsed, fd, stat, prefix);
             const offset = matches
                 ? parsed.offset
@@ -473,16 +500,12 @@ class JsonlTailReader {
                     ? lastCompleteLineOffset(fd, stat.size)
                     : 0;
             this.position(offset);
-            this.identity = { dev: stat.dev, ino: stat.ino };
-            this.lastMtimeMs = stat.mtimeMs;
-            this.head = (0, fileHead_1.fileHeadOf)(prefix);
+            this.continuity.adoptPrefix(stat, prefix);
             return matches;
         }
         catch (error) {
             this.position(0);
-            this.identity = null;
-            this.head = null;
-            this.lastMtimeMs = -1;
+            this.continuity.forget();
             this.options.onError?.(toError(error));
             return false;
         }
@@ -597,6 +620,15 @@ function parseCheckpoint(value) {
         prefixDigest: parsedDigest,
     };
 }
+/** A fresh checkpoint for `offset` in the file with `identity` and recorded `head`. */
+function checkpointOf(offset, identity, head) {
+    return {
+        version: exports.JSONL_TAIL_CHECKPOINT_VERSION,
+        offset,
+        identity: identity ? { dev: identity.dev, ino: identity.ino } : null,
+        prefixDigest: head ? { bytes: head.bytes, hash: head.hash } : null,
+    };
+}
 /** Whether `checkpoint` still describes the open file. */
 function checkpointMatches(checkpoint, fd, stat, prefix) {
     const { offset, identity, prefixDigest } = checkpoint;
@@ -639,6 +671,10 @@ function readAt(fd, position, length) {
     const count = length > 0 ? fs.readSync(fd, buffer, 0, length, position) : 0;
     return buffer.subarray(0, count);
 }
+/** The file's first `min(HEAD_BYTES, size)` bytes: what a checkpoint digests. */
+function readPrefix(fd, stat) {
+    return readAt(fd, 0, Math.min(fileHead_1.HEAD_BYTES, stat.size));
+}
 async function readAtAsync(handle, position, length) {
     const buffer = Buffer.alloc(length);
     const count = length > 0 ? (await handle.read(buffer, 0, length, position)).bytesRead : 0;

package/dist/watchers/jsonlWatcher.d.ts

@@ -4,22 +4,43 @@
  */
 import type { ProviderId } from '../providers/types';
 import type { SessionWatcher, SessionWatcherCallbacks } from './types';
+/** Options for {@link JsonlSessionWatcher}. */
+export interface JsonlSessionWatcherOptions {
+    /**
+     * Emit a `system` event (summary from the notification, `raw` the line) for
+     * each Claude Code mid-turn task-notification attachment, and for the other
+     * lines that settle background agents: the plain-text "background agents
+     * were stopped by the user" notice, a background agent's final
+     * `task_status` attachment, and an `agents_killed` system line. Default
+     * `false`.
+     */
+    includeTaskNotifications?: boolean;
+}
 export declare class JsonlSessionWatcher implements SessionWatcher {
     private readonly providerId;
     private readonly sessionPath;
     private readonly callbacks;
+    private readonly options;
     private tail;
     private startOffset;
     private codexInPlanMode;
     private readonly claudeUsageDeduper;
     /** Last Codex cumulative usage seen; repeated `token_count` events carry the same value. */
     private codexPrevTotal;
-    constructor(providerId: ProviderId, sessionPath: string, callbacks: SessionWatcherCallbacks);
+    constructor(providerId: ProviderId, sessionPath: string, callbacks: SessionWatcherCallbacks, options?: JsonlSessionWatcherOptions);
     get isActive(): boolean;
     /** Seek to a committed byte offset before starting replay. */
     seekTo(position: number): void;
     /** Position after the last complete JSONL line. */
     getPosition(): number;
+    /**
+     * Parse state for {@link getPosition}: for Claude Code, the usage deduper's
+     * recent message ids (a `ClaudeUsageDedupeState`); for Codex, the previous
+     * cumulative token total and plan mode.
+     */
+    getResumeState(): unknown;
+    /** Restores state from {@link getResumeState} after `seekTo()` and before `start()`. */
+    restoreResumeState(state: unknown): boolean;
     start(replay: boolean): void;
     stop(): void;
     private handleRawEvent;