sidekick-shared 0.29.0 → 0.30.0

package/dist/esm/watchers/jsonlTail.js

@@ -4,6 +4,7 @@
  */
 import * as fs from 'fs';
 import { fileHeadOf, HEAD_BYTES, headMatches } from '../fileHead';
+import { FileContinuity, probeFileContinuity } from '../fileContinuity';
 import { JsonlParser } from '../parsers/jsonl';
 const DEFAULT_DEBOUNCE_MS = 100;
 const DEFAULT_CATCHUP_INTERVAL_MS = 30_000;
@@ -60,6 +61,63 @@ export class JsonlTailSymlinkError extends Error {
 export 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.
+ */
+export 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, 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.
+ */
+export 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;
@@ -71,10 +129,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();
     maxReadBytes;
     maxLineBytes;
     rewritePolicy;
@@ -282,21 +338,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(HEAD_BYTES, stat.size));
+        return this.continuity.needsProbe(stat, this.readOffset);
     }
     probeSync(fd, stat) {
-        return {
-            prefix: readAt(fd, 0, Math.min(HEAD_BYTES, stat.size)),
-            before: this.committedOffset > 0 && this.committedOffset <= stat.size
-                ? readAt(fd, this.committedOffset - 1, 1)
-                : null,
-        };
+        return probeFileContinuity(fd, stat, this.committedOffset);
     }
     async probeAsync(handle, stat) {
         const committedOffset = this.committedOffset;
@@ -313,31 +358,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 && !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(HEAD_BYTES, stat.size))) {
-            this.head = 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();
@@ -412,12 +442,7 @@ class JsonlTailReader {
         this.position(Math.max(0, offset));
     }
     checkpoint() {
-        return {
-            version: 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;
@@ -427,7 +452,7 @@ class JsonlTailReader {
         try {
             fd = this.openSync();
             const stat = fs.fstatSync(fd);
-            const prefix = readAt(fd, 0, Math.min(HEAD_BYTES, stat.size));
+            const prefix = readPrefix(fd, stat);
             const matches = parsed !== null && checkpointMatches(parsed, fd, stat, prefix);
             const offset = matches
                 ? parsed.offset
@@ -435,16 +460,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 = 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;
         }
@@ -559,6 +580,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: 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;
@@ -601,6 +631,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(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/esm/watchers/jsonlWatcher.js

@@ -3,9 +3,10 @@
  * Uses byte-offset tracking + fs.watch with debounce + catch-up polling.
  */
 import { createJsonlTail } from './jsonlTail';
-import { normalizeCodexToolName, resolveCodexCallUsage } from '../parsers/codexParser';
+import { codexTokenUsageFrom, normalizeCodexToolName, resolveCodexCallUsage, } from '../parsers/codexParser';
 import { formatToolSummary } from '../formatters/toolSummary';
 import { ClaudeUsageDeduper, normalizeClaudeUsage } from '../usage/claudeUsageDedupe';
+import { describeAgentsStopped, describeTaskStatus, isAgentsKilledSystemEvent, isFinalTaskStatus, parseAgentsStoppedNotice, parseTaskNotification, taskNotificationPromptFromAttachment, taskStatusFromAttachment, } from '../subagentSpawn';
 // ── Normalizers ──
 /**
  * Split lines of one Claude response repeat its usage; run the raw usage
@@ -21,7 +22,7 @@ function dedupedClaudeUsage(raw, deduper) {
     }));
     return { usage: event.message?.usage, usageKind: event.message?.usageKind };
 }
-function normalizeClaudeCodeEvent(raw, deduper) {
+function normalizeClaudeCodeEvent(raw, deduper, includeTaskNotifications) {
     const events = [];
     const ts = raw.timestamp || new Date().toISOString();
     const permissionMode = raw.permissionMode;
@@ -133,6 +134,29 @@ function normalizeClaudeCodeEvent(raw, deduper) {
                 raw,
             });
         }
+        else if (includeTaskNotifications) {
+            // A task notification that landed mid-turn is only an attachment line.
+            const prompt = taskNotificationPromptFromAttachment(raw);
+            const notification = parseTaskNotification(prompt);
+            const stopped = notification ? null : parseAgentsStoppedNotice(prompt);
+            const taskStatus = taskStatusFromAttachment(raw);
+            let summary = null;
+            if (notification) {
+                summary = notification.summary ?? `Background task ${notification.status ?? 'finished'}`;
+            }
+            else if (stopped) {
+                summary = describeAgentsStopped(stopped);
+            }
+            else if (taskStatus && isFinalTaskStatus(taskStatus.status)) {
+                summary = describeTaskStatus(taskStatus);
+            }
+            else if (isAgentsKilledSystemEvent(raw)) {
+                summary = describeAgentsStopped(null);
+            }
+            if (summary !== null) {
+                events.push({ providerId: 'claude-code', type: 'system', timestamp: ts, summary, raw });
+            }
+        }
     }
     // Propagate permission mode to all generated events
     if (permissionMode) {
@@ -204,16 +228,18 @@ export class JsonlSessionWatcher {
     providerId;
     sessionPath;
     callbacks;
+    options;
     tail;
     startOffset;
     codexInPlanMode = false;
     claudeUsageDeduper = new ClaudeUsageDeduper();
     /** Last Codex cumulative usage seen; repeated `token_count` events carry the same value. */
     codexPrevTotal;
-    constructor(providerId, sessionPath, callbacks) {
+    constructor(providerId, sessionPath, callbacks, options = {}) {
         this.providerId = providerId;
         this.sessionPath = sessionPath;
         this.callbacks = callbacks;
+        this.options = options;
     }
     get isActive() {
         return this.tail?.isActive ?? false;
@@ -227,6 +253,37 @@ export class JsonlSessionWatcher {
     getPosition() {
         return this.tail?.getOffset() ?? this.startOffset ?? 0;
     }
+    /**
+     * 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() {
+        if (this.providerId === 'codex') {
+            return {
+                version: 1,
+                prevTotalUsage: this.codexPrevTotal ? { ...this.codexPrevTotal } : null,
+                inPlanMode: this.codexInPlanMode,
+            };
+        }
+        return this.claudeUsageDeduper.exportState();
+    }
+    /** Restores state from {@link getResumeState} after `seekTo()` and before `start()`. */
+    restoreResumeState(state) {
+        if (this.providerId !== 'codex')
+            return this.claudeUsageDeduper.importState(state);
+        if (!state || typeof state !== 'object')
+            return false;
+        const { version, prevTotalUsage, inPlanMode } = state;
+        if (version !== 1 || typeof inPlanMode !== 'boolean')
+            return false;
+        const total = codexTokenUsageFrom(prevTotalUsage);
+        if (total === undefined)
+            return false;
+        this.codexPrevTotal = total ?? undefined;
+        this.codexInPlanMode = inPlanMode;
+        return true;
+    }
     start(replay) {
         if (this.isActive)
             return;
@@ -258,7 +315,7 @@ export class JsonlSessionWatcher {
         // JsonlParser parses any JSON object. Cast to Record for codex normalizer.
         const followEvents = this.providerId === 'codex'
             ? this.normalizeCodexEvent(event)
-            : normalizeClaudeCodeEvent(event, this.claudeUsageDeduper);
+            : normalizeClaudeCodeEvent(event, this.claudeUsageDeduper, this.options.includeTaskNotifications === true);
         for (const fe of followEvents) {
             this.callbacks.onEvent(fe);
         }

package/dist/esm/watchers/providerReaderWatcher.js

@@ -32,6 +32,19 @@ export class ProviderReaderSessionWatcher {
     getPosition() {
         return this.reader.getPosition();
     }
+    /** The reader's resume state, if it keeps any. */
+    getResumeState() {
+        return this.reader.getResumeState?.();
+    }
+    /**
+     * Restores the reader's resume state after `seekTo()`. A reader that keeps
+     * none accepts only `undefined`.
+     */
+    restoreResumeState(state) {
+        if (!this.reader.restoreResumeState)
+            return state === undefined;
+        return this.reader.restoreResumeState(state);
+    }
     start(replay) {
         if (this._isActive)
             return;
@@ -99,11 +112,12 @@ export class ProviderReaderSessionWatcher {
         if (!this._isActive)
             return;
         try {
-            if (this.reader.wasTruncated()) {
-                this.reader.reset();
-                this.callbacks.onReset?.();
-            }
             const events = this.reader.readNew();
+            // The reader started over (truncated, rewritten, or replaced file):
+            // these events are the session from the beginning, so consumers must
+            // drop what they built before receiving them.
+            if (this.reader.wasTruncated())
+                this.callbacks.onReset?.();
             for (const event of events) {
                 for (const followEvent of toFollowEvents(event, this.provider.id)) {
                     this.callbacks.onEvent(followEvent);

package/dist/esm/zaiQuota.js

@@ -1,3 +1,4 @@
+import { ownValue } from './ownKey';
 // ── Tier budgets ──
 /**
  * Published z.ai coding-plan prompt budgets.
@@ -215,7 +216,7 @@ export function parseZaiQuotaError(error) {
     if (!error)
         return null;
     const code = String(error.code ?? '');
-    const kind = ZAI_ERROR_CODES[code];
+    const kind = ownValue(ZAI_ERROR_CODES, code);
     if (!kind)
         return null;
     const message = error.message ?? '';

package/dist/fileContinuity.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Continuity of a file read incrementally by byte offset: whether the file
+ * now at a path is still the content earlier reads consumed, or was
+ * truncated, rewritten, or replaced since.
+ *
+ * {@link FileContinuity} holds the rules `createJsonlTail` applies, so every
+ * incremental reader detects the same cases the same way:
+ *
+ * - `replaced`: another file (by device and inode, read from the open
+ *   descriptor, so a rename between a stat and an open cannot mix two files)
+ *   now has the path.
+ * - `truncated`: the file is shorter than the read position.
+ * - `rewritten`: the mtime changed and either the first {@link HEAD_BYTES}
+ *   bytes differ from those recorded, or the byte before the committed
+ *   (resume-safe) offset is no longer a newline.
+ *
+ * Replacement and truncation are checked on every read; the content probe
+ * only when the mtime changed or the recorded head is still short.
+ *
+ * Known limits: a rewrite that leaves the mtime unchanged (coarse mtime
+ * resolution, or an mtime restored on purpose) or that changes only bytes
+ * past the first 4 KiB while the resume point still follows a newline goes
+ * unnoticed; on filesystems without stable inode numbers (some SMB mounts,
+ * Windows) an unchanged file can read as replaced, which costs a replay.
+ *
+ * @module fileContinuity
+ */
+import * as fs from 'fs';
+import { type FileHead } from './fileHead';
+import type { JsonlTailResetReason } from './watchers/jsonlTail';
+/** The fields of `fs.Stats` the continuity rules read. */
+export type FileContinuityStat = Pick<fs.Stats, 'dev' | 'ino' | 'size' | 'mtimeMs'>;
+/** The bytes the continuity check needs, read before any state changes. */
+export interface FileContinuityProbe {
+    /** The file's first `min(HEAD_BYTES, size)` bytes. */
+    prefix: Buffer;
+    /** The byte before the committed offset, when there is one. */
+    before: Buffer | null;
+}
+/**
+ * What one reader knows about the file its offsets refer to: identity,
+ * mtime, and a digest of the first bytes, recorded by {@link adopt} after
+ * each read.
+ *
+ * Synchronous readers call {@link check} on the open descriptor, restart
+ * from offset 0 when it returns a reason, then call {@link adopt}. A reader
+ * that repositions without reading (a seek to a stored offset, a reset)
+ * calls {@link forget}, so its next read adopts the file instead of
+ * comparing it with the old one. The lower-level methods ({@link needsProbe},
+ * {@link reasonFor}, {@link record}) serve asynchronous readers that probe
+ * on their own.
+ */
+export declare class FileContinuity {
+    private identity;
+    private head;
+    private lastMtimeMs;
+    /** What the last {@link check} probed and decided, for {@link adopt}. */
+    private checked;
+    /** Device and inode of the adopted file; `null` before the first read and after {@link forget}. */
+    get knownIdentity(): {
+        dev: number;
+        ino: number;
+    } | null;
+    /** Length and digest of the adopted file's first bytes, once probed. */
+    get knownHead(): FileHead | null;
+    /** Whether {@link reasonFor} needs bytes from the file to decide. */
+    needsProbe(stat: FileContinuityStat, readOffset: number): boolean;
+    /**
+     * Why the reader must start over: the path now names another file, the
+     * file shrank below `readOffset`, its first bytes changed, or the resume
+     * point no longer follows a newline. `null` when it can continue.
+     */
+    reasonFor(stat: FileContinuityStat, readOffset: number, probe: FileContinuityProbe | null): JsonlTailResetReason | null;
+    /** Records the identity, mtime, and (from `probe`) first bytes of the file the offsets now refer to. */
+    record(stat: FileContinuityStat, probe: FileContinuityProbe | null): void;
+    /** Drops the recorded first bytes (the reader restarted); the next {@link record} with a probe sets them again. */
+    discardHead(): void;
+    /** Records the file as known from `prefix`, its first `min(HEAD_BYTES, size)` bytes. */
+    adoptPrefix(stat: FileContinuityStat, prefix: Buffer): void;
+    /** Forgets the file, so the next {@link check} adopts whatever file has the path. */
+    forget(): void;
+    /**
+     * Applies the rules to the file open on `fd` (`stat` from `fstat` on that
+     * descriptor), reading the bytes they need. `readOffset` is how far the
+     * reader has read; `committedOffset` (default `readOffset`) is its
+     * resume-safe position just after a newline. Returns why the reader must
+     * restart from offset 0, or `null`. Call {@link adopt} with the same
+     * `stat` once the reader has acted on the answer.
+     */
+    check(fd: number, stat: FileContinuityStat, readOffset: number, committedOffset?: number): JsonlTailResetReason | null;
+    /** Records the file just checked as the one the reader's offsets now refer to. */
+    adopt(stat: FileContinuityStat): void;
+}
+/** Reads the bytes {@link FileContinuity.reasonFor} compares, from the file open on `fd`. */
+export declare function probeFileContinuity(fd: number, stat: FileContinuityStat, committedOffset: number): FileContinuityProbe;

package/dist/fileContinuity.js

@@ -0,0 +1,187 @@
+"use strict";
+/**
+ * Continuity of a file read incrementally by byte offset: whether the file
+ * now at a path is still the content earlier reads consumed, or was
+ * truncated, rewritten, or replaced since.
+ *
+ * {@link FileContinuity} holds the rules `createJsonlTail` applies, so every
+ * incremental reader detects the same cases the same way:
+ *
+ * - `replaced`: another file (by device and inode, read from the open
+ *   descriptor, so a rename between a stat and an open cannot mix two files)
+ *   now has the path.
+ * - `truncated`: the file is shorter than the read position.
+ * - `rewritten`: the mtime changed and either the first {@link HEAD_BYTES}
+ *   bytes differ from those recorded, or the byte before the committed
+ *   (resume-safe) offset is no longer a newline.
+ *
+ * Replacement and truncation are checked on every read; the content probe
+ * only when the mtime changed or the recorded head is still short.
+ *
+ * Known limits: a rewrite that leaves the mtime unchanged (coarse mtime
+ * resolution, or an mtime restored on purpose) or that changes only bytes
+ * past the first 4 KiB while the resume point still follows a newline goes
+ * unnoticed; on filesystems without stable inode numbers (some SMB mounts,
+ * Windows) an unchanged file can read as replaced, which costs a replay.
+ *
+ * @module fileContinuity
+ */
+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.FileContinuity = void 0;
+exports.probeFileContinuity = probeFileContinuity;
+const fs = __importStar(require("fs"));
+const fileHead_1 = require("./fileHead");
+/**
+ * What one reader knows about the file its offsets refer to: identity,
+ * mtime, and a digest of the first bytes, recorded by {@link adopt} after
+ * each read.
+ *
+ * Synchronous readers call {@link check} on the open descriptor, restart
+ * from offset 0 when it returns a reason, then call {@link adopt}. A reader
+ * that repositions without reading (a seek to a stored offset, a reset)
+ * calls {@link forget}, so its next read adopts the file instead of
+ * comparing it with the old one. The lower-level methods ({@link needsProbe},
+ * {@link reasonFor}, {@link record}) serve asynchronous readers that probe
+ * on their own.
+ */
+class FileContinuity {
+    identity = null;
+    head = null;
+    lastMtimeMs = -1;
+    /** What the last {@link check} probed and decided, for {@link adopt}. */
+    checked = null;
+    /** Device and inode of the adopted file; `null` before the first read and after {@link forget}. */
+    get knownIdentity() {
+        return this.identity;
+    }
+    /** Length and digest of the adopted file's first bytes, once probed. */
+    get knownHead() {
+        return this.head;
+    }
+    /** Whether {@link reasonFor} needs bytes from the file to decide. */
+    needsProbe(stat, readOffset) {
+        return (this.identity === null ||
+            stat.dev !== this.identity.dev ||
+            stat.ino !== this.identity.ino ||
+            stat.size < readOffset ||
+            stat.mtimeMs !== this.lastMtimeMs ||
+            this.head === null ||
+            this.head.bytes < Math.min(fileHead_1.HEAD_BYTES, stat.size));
+    }
+    /**
+     * Why the reader must start over: the path now names another file, the
+     * file shrank below `readOffset`, its first bytes changed, or the resume
+     * point no longer follows a newline. `null` when it can continue.
+     */
+    reasonFor(stat, readOffset, probe) {
+        if (this.identity && (stat.dev !== this.identity.dev || stat.ino !== this.identity.ino)) {
+            return 'replaced';
+        }
+        if (stat.size < 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;
+    }
+    /** Records the identity, mtime, and (from `probe`) first bytes of the file the offsets now refer to. */
+    record(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);
+        }
+    }
+    /** Drops the recorded first bytes (the reader restarted); the next {@link record} with a probe sets them again. */
+    discardHead() {
+        this.head = null;
+    }
+    /** Records the file as known from `prefix`, its first `min(HEAD_BYTES, size)` bytes. */
+    adoptPrefix(stat, prefix) {
+        this.identity = { dev: stat.dev, ino: stat.ino };
+        this.lastMtimeMs = stat.mtimeMs;
+        this.head = (0, fileHead_1.fileHeadOf)(prefix);
+    }
+    /** Forgets the file, so the next {@link check} adopts whatever file has the path. */
+    forget() {
+        this.identity = null;
+        this.head = null;
+        this.lastMtimeMs = -1;
+        this.checked = null;
+    }
+    /**
+     * Applies the rules to the file open on `fd` (`stat` from `fstat` on that
+     * descriptor), reading the bytes they need. `readOffset` is how far the
+     * reader has read; `committedOffset` (default `readOffset`) is its
+     * resume-safe position just after a newline. Returns why the reader must
+     * restart from offset 0, or `null`. Call {@link adopt} with the same
+     * `stat` once the reader has acted on the answer.
+     */
+    check(fd, stat, readOffset, committedOffset = readOffset) {
+        const probe = this.needsProbe(stat, readOffset)
+            ? probeFileContinuity(fd, stat, committedOffset)
+            : null;
+        const reason = this.reasonFor(stat, readOffset, probe);
+        this.checked = { probe, reset: reason !== null };
+        return reason;
+    }
+    /** Records the file just checked as the one the reader's offsets now refer to. */
+    adopt(stat) {
+        const checked = this.checked;
+        this.checked = null;
+        if (checked?.reset)
+            this.head = null;
+        this.record(stat, checked?.probe ?? null);
+    }
+}
+exports.FileContinuity = FileContinuity;
+/** Reads the bytes {@link FileContinuity.reasonFor} compares, from the file open on `fd`. */
+function probeFileContinuity(fd, stat, committedOffset) {
+    return {
+        prefix: readAt(fd, 0, Math.min(fileHead_1.HEAD_BYTES, stat.size)),
+        before: committedOffset > 0 && committedOffset <= stat.size
+            ? readAt(fd, committedOffset - 1, 1)
+            : null,
+    };
+}
+function readAt(fd, position, length) {
+    const buffer = Buffer.alloc(length);
+    const count = length > 0 ? fs.readSync(fd, buffer, 0, length, position) : 0;
+    return buffer.subarray(0, count);
+}