sidekick-shared 0.28.3 → 0.29.0

package/dist/usage/usageEvents.js

@@ -12,9 +12,19 @@
  * every hit and pruned least-recently-used, once per collection.
  *
  * A Claude Code session's subagents write their own transcripts under
- * `<sessionId>/subagents/`; their usage is attributed to the parent session
- * and their sizes and mtimes join the fingerprint. (Codex spawned subagents
- * are top-level rollouts, already listed as sessions of their own.)
+ * `<sessionId>/subagents/`; their usage is attributed to the parent session,
+ * 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.)
+ *
+ * Each event also carries the ordinal of the human prompt it answered, from
+ * the same scanner as `collectPromptHistory()`, so usage joins prompt history
+ * on `(provider, sessionId, ordinal)`.
+ *
+ * Cache files are named per cache version (`<provider>--<session>.v3.json`)
+ * so readers of different versions sharing the directory never overwrite each
+ * other's files; pruning ages out every version's files alike.
  *
  * Node-only: reads session files and the cache directory.
  *
@@ -60,7 +70,10 @@ exports.pruneUsageCache = pruneUsageCache;
 exports.collectUsageEvents = collectUsageEvents;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const codexRolloutOrigin_1 = require("../parsers/codexRolloutOrigin");
 const paths_1 = require("../paths");
+const promptHistory_1 = require("../promptHistory");
+const codexRollouts_1 = require("../providers/codexRollouts");
 const sessionPreviews_1 = require("../sessionPreviews");
 const usageNormalization_1 = require("../usageNormalization");
 const atomic_1 = require("../writers/atomic");
@@ -68,9 +81,11 @@ const workspaceRoots_1 = require("../workspaceRoots");
 /**
  * Bump when the cached record shape or the counting rules change; older files
  * are re-read. v2: Claude split lines and duplicate Codex `token_count` events
- * are counted once, and Claude subagent transcripts are included.
+ * are counted once, and Claude subagent transcripts are included. v3: events
+ * keep reasoning tokens, prompt ordinal, message id, and subagent, and files
+ * move to a versioned name (`<provider>--<session>.v3.json`).
  */
-exports.USAGE_CACHE_VERSION = 2;
+exports.USAGE_CACHE_VERSION = 3;
 /**
  * Most-recently-used cache files kept on disk. Sized for a busy month of
  * sessions (files are a few KB each); a collection larger than this still
@@ -81,9 +96,15 @@ exports.MAX_USAGE_CACHE_FILES = 5000;
 function getUsageCacheDir() {
     return path.join((0, paths_1.getConfigDir)(), 'usage-cache');
 }
+/**
+ * Cache file of one session. The name carries the cache version, so a reader
+ * of another version sharing the directory (which rejects this version, and
+ * versions before 3 use the unversioned `<provider>--<session>.json`) never
+ * overwrites it, and this version never overwrites theirs.
+ */
 function cacheFilePath(dir, provider, sessionId) {
     const safe = sessionId.replace(/[^A-Za-z0-9._-]/g, '_');
-    return path.join(dir, `${provider}--${safe}.json`);
+    return path.join(dir, `${provider}--${safe}.v${exports.USAGE_CACHE_VERSION}.json`);
 }
 function toMs(value, label) {
     if (value === undefined)
@@ -114,7 +135,11 @@ function readCache(filePath) {
         return null;
     }
 }
-/** Deletes all but the `keep` most recently used cache files (by mtime). Best-effort. */
+/**
+ * Deletes all but the `keep` most recently used cache files (by mtime), of
+ * every cache version alike, so files no reader touches any more age out.
+ * Best-effort.
+ */
 function pruneUsageCache(keep = exports.MAX_USAGE_CACHE_FILES, dir = getUsageCacheDir()) {
     try {
         const entries = fs
@@ -147,7 +172,7 @@ function pruneUsageCache(keep = exports.MAX_USAGE_CACHE_FILES, dir = getUsageCac
         return 0;
     }
 }
-function cachedEventFromUsage(usage, timestamp, model) {
+function cachedEventFromUsage(usage, timestamp, model, messageId, agentId) {
     const record = {
         t: timestamp,
         m: model,
@@ -160,16 +185,29 @@ function cachedEventFromUsage(usage, timestamp, model) {
     };
     if (usage.reportedCostUsd !== undefined)
         record.rc = usage.reportedCostUsd;
+    if (usage.reasoningTokens > 0)
+        record.rt = usage.reasoningTokens;
+    if (messageId && !messageId.startsWith('token-count-'))
+        record.rid = messageId;
+    if (agentId)
+        record.sa = agentId;
     return record;
 }
-/** Price a cached event with the current catalog (or its provider-reported cost). */
-function priceCachedEvent(cached, provider, sessionId, project, sessionFile) {
+/**
+ * Price a cached event with the current catalog (or its provider-reported
+ * cost). Output is priced from the billable output (`bo`), which already
+ * holds reasoning however the provider reports it, so restoring the reasoning
+ * count never changes the cost.
+ */
+function priceCachedEvent(cached, provider, sessionId, project, sessionFile, sessionSubagent) {
+    const reasoningTokens = typeof cached.rt === 'number' && cached.rt > 0 ? cached.rt : 0;
     const usage = {
         uncachedInputTokens: cached.i,
         cacheReadTokens: cached.cr,
         cacheWriteTokens: cached.cw,
         outputTokens: cached.o,
-        reasoningTokens: 0,
+        reasoningTokens,
+        // `bo` is already the billable output; nothing is added to it.
         reasoningIncludedInOutput: true,
         cacheInclusiveInputTokens: cached.i + cached.cr + cached.cw,
         billableOutputTokens: cached.bo,
@@ -181,6 +219,9 @@ function priceCachedEvent(cached, provider, sessionId, project, sessionFile) {
         usage,
         modelId: cached.m === 'unknown' ? undefined : cached.m,
     });
+    const subagent = typeof cached.sa === 'string' && cached.sa
+        ? { agentId: cached.sa, parentSessionId: sessionId }
+        : sessionSubagent;
     return {
         timestamp: cached.t,
         provider,
@@ -193,13 +234,19 @@ function priceCachedEvent(cached, provider, sessionId, project, sessionFile) {
             cacheWriteTokens: cached.cw,
             cacheReadTokens: cached.cr,
             totalTokens: cached.tt,
+            ...(reasoningTokens > 0 ? { reasoningTokens } : {}),
         },
         costUsd: priced.costUsd,
         costProvenance: priced.source,
         filePath: sessionFile,
+        ...(cached.po === null || (typeof cached.po === 'number' && Number.isInteger(cached.po))
+            ? { promptOrdinal: cached.po }
+            : {}),
+        ...(typeof cached.rid === 'string' ? { requestId: cached.rid } : {}),
+        ...(subagent ? { subagent: { ...subagent } } : {}),
     };
 }
-const CLAUDE_AGENT_FILE = /^agent-.+\.jsonl$/;
+const CLAUDE_AGENT_FILE = /^agent-(.+)\.jsonl$/;
 /** Claude Code subagent transcripts of a session, sorted by name. */
 function claudeSubagentFiles(preview) {
     if (preview.provider !== 'claude-code')
@@ -219,6 +266,7 @@ function claudeSubagentFiles(preview) {
             files.push({
                 path: path.join(dir, name),
                 name,
+                agentId: CLAUDE_AGENT_FILE.exec(name)?.[1] ?? name,
                 sizeBytes: stat.size,
                 modifiedAt: stat.mtimeMs,
             });
@@ -235,7 +283,7 @@ function sessionFingerprint(preview, subagents) {
         return base;
     return `${base}|${subagents.map((f) => `${f.name}:${f.sizeBytes}:${f.modifiedAt}`).join(',')}`;
 }
-function readTranscriptUsage(provider, filePath, cached) {
+function readTranscriptUsage(provider, filePath, cached, agentId) {
     const reader = provider.createReader(filePath);
     const events = reader.readAll();
     reader.flush();
@@ -257,12 +305,14 @@ function readTranscriptUsage(provider, filePath, cached) {
             target.cr += usage.cacheReadTokens;
             target.bo += usage.billableOutputTokens;
             target.tt += usage.totalTokens;
+            if (usage.reasoningTokens > 0)
+                target.rt = (target.rt ?? 0) + usage.reasoningTokens;
             continue;
         }
         const timestamp = Date.parse(event.timestamp);
         if (!Number.isFinite(timestamp))
             continue;
-        const record = cachedEventFromUsage(usage, timestamp, event.message?.model ?? usage.model ?? 'unknown');
+        const record = cachedEventFromUsage(usage, timestamp, event.message?.model ?? usage.model ?? 'unknown', messageId, agentId);
         cached.push(record);
         if (messageId)
             byMessageId.set(messageId, record);
@@ -272,10 +322,75 @@ function readSessionUsage(provider, preview, subagents) {
     const cached = [];
     readTranscriptUsage(provider, preview.filePath, cached);
     for (const file of subagents)
-        readTranscriptUsage(provider, file.path, cached);
+        readTranscriptUsage(provider, file.path, cached, file.agentId);
     cached.sort((a, b) => a.t - b.t);
     return cached;
 }
+/**
+ * Sets each event's `po` to the highest ordinal among the prompts timestamped
+ * at or before it, or null when none is. With prompts in time order (the
+ * usual case) that is the last prompt before the event.
+ */
+function assignPromptOrdinals(events, marks) {
+    const sorted = [...marks].sort((a, b) => a.timestampMs - b.timestampMs || a.ordinal - b.ordinal);
+    const highest = [];
+    let max = -1;
+    for (const mark of sorted) {
+        max = Math.max(max, mark.ordinal);
+        highest.push(max);
+    }
+    for (const event of events) {
+        let low = 0;
+        let high = sorted.length;
+        while (low < high) {
+            const middle = (low + high) >>> 1;
+            if (sorted[middle].timestampMs <= event.t)
+                low = middle + 1;
+            else
+                high = middle;
+        }
+        event.po = low === 0 ? null : highest[low - 1];
+    }
+}
+/**
+ * Prompt ordinals for a freshly read session, from its main transcript.
+ * Returns false when the transcript could not be scanned (the events then
+ * keep no ordinal and the session is not cached, so the next run retries).
+ */
+async function addPromptOrdinals(preview, events) {
+    if (preview.provider !== 'claude-code' && preview.provider !== 'codex')
+        return true;
+    let marks;
+    try {
+        marks = await (0, promptHistory_1.readPromptOrdinalMarks)(preview.provider, preview.sessionId, preview.filePath);
+    }
+    catch {
+        return false;
+    }
+    assignPromptOrdinals(events, marks);
+    return true;
+}
+/** Parent of a Codex rollout that is a fork or a spawned subagent, from its first line only. */
+async function codexSessionSubagent(preview) {
+    if (preview.provider !== 'codex')
+        return undefined;
+    const { line } = await (0, codexRollouts_1.readFirstLineAsync)(preview.filePath);
+    if (!line)
+        return undefined;
+    let first;
+    try {
+        first = JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+    const origin = (0, codexRolloutOrigin_1.codexRolloutOrigin)(first);
+    if (!origin.parentId || (!origin.isSubagent && !origin.forkedFromId))
+        return undefined;
+    if (origin.parentId === preview.sessionId)
+        return undefined;
+    return { agentId: preview.sessionId, parentSessionId: origin.parentId };
+}
 function yieldToEventLoop() {
     return new Promise((resolve) => setImmediate(resolve));
 }
@@ -315,12 +430,14 @@ async function collectUsageEvents(options) {
         const fingerprint = sessionFingerprint(preview, subagentFiles);
         const filePath = cacheFilePath(cacheDir, preview.provider, preview.sessionId);
         let cachedEvents = null;
+        let sessionSubagent;
         let project = preview.workspacePath;
         let fromCache = false;
         if (useCache) {
             const cached = readCache(filePath);
             if (cached && cached.fingerprint === fingerprint && cached.sessionId === preview.sessionId) {
                 cachedEvents = cached.events;
+                sessionSubagent = validSubagent(cached.subagent);
                 project = project ?? cached.project;
                 fromCache = true;
                 cacheHits += 1;
@@ -344,7 +461,10 @@ async function collectUsageEvents(options) {
                 options.onDiagnostic?.(diagnostic);
                 continue;
             }
-            if (useCache) {
+            // Ordinals and origin are best-effort: a failure costs only the cache write.
+            const ordinalsRead = await addPromptOrdinals(preview, cachedEvents);
+            sessionSubagent = await codexSessionSubagent(preview).catch(() => undefined);
+            if (useCache && ordinalsRead) {
                 const record = {
                     version: exports.USAGE_CACHE_VERSION,
                     provider: preview.provider,
@@ -352,6 +472,7 @@ async function collectUsageEvents(options) {
                     fingerprint,
                     project,
                     events: cachedEvents,
+                    ...(sessionSubagent ? { subagent: sessionSubagent } : {}),
                 };
                 try {
                     await (0, atomic_1.atomicWriteJson)(filePath, record);
@@ -371,7 +492,7 @@ async function collectUsageEvents(options) {
                 continue;
             if (untilMs !== null && cached.t > untilMs)
                 continue;
-            events.push(priceCachedEvent(cached, preview.provider, preview.sessionId, project, preview.filePath));
+            events.push(priceCachedEvent(cached, preview.provider, preview.sessionId, project, preview.filePath, sessionSubagent));
             first = first === null ? cached.t : Math.min(first, cached.t);
             last = last === null ? cached.t : Math.max(last, cached.t);
             count += 1;
@@ -400,6 +521,14 @@ async function collectUsageEvents(options) {
         ...(scope ? { roots: scope.roots } : {}),
     };
 }
+function validSubagent(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const { agentId, parentSessionId } = value;
+    return typeof agentId === 'string' && typeof parentSessionId === 'string'
+        ? { agentId, parentSessionId }
+        : undefined;
+}
 /** The roots to list, or undefined for an unscoped (or legacy single-root) call. */
 function usageScope(options) {
     if (options.workspacePaths) {

package/dist/usage/usageReports.d.ts

@@ -10,8 +10,11 @@ import type { ProviderId } from '../providers/types';
 import type { TokenTotals } from '../types/historicalData';
 import type { UsageEventRecord } from './usageEvents';
 export type UsageGranularity = 'day' | 'week' | 'month' | 'session';
-/** Extra dimensions a bucket is split by, beyond the time key. */
-export type UsageGroupDimension = 'provider' | 'project' | 'model';
+/**
+ * Extra dimensions a bucket is split by, beyond the time key. `session`
+ * splits each time bucket per session (rows then carry `sessionId`).
+ */
+export type UsageGroupDimension = 'provider' | 'project' | 'model' | 'session';
 export interface BucketUsageOptions {
     granularity: UsageGranularity;
     /** Key by the UTC calendar instead of the local calendar (default false). */
@@ -20,6 +23,19 @@ export interface BucketUsageOptions {
     weekStartsOn?: 0 | 1;
     /** Dimensions to group by in addition to the time key (default `['provider']`). */
     groupBy?: readonly UsageGroupDimension[];
+    /**
+     * Drop events whose model is Claude Code's `<synthetic>` placeholder
+     * (`SYNTHETIC_MODEL`: locally generated, unbilled messages). Default false.
+     */
+    excludeSynthetic?: boolean;
+    /**
+     * How model ids are keyed in `model` rows and the `models` list. `'raw'`
+     * (default) keeps each id as recorded; `'canonical'` merges spellings of one
+     * model (date suffixes, provider/region prefixes, Bedrock forms) through
+     * `canonicalModelId()`, so `claude-opus-5-5-20261001` and `claude-opus-5-5`
+     * share a row. Pricing is unaffected: events arrive already priced.
+     */
+    modelKey?: 'raw' | 'canonical';
 }
 export interface UsageBucketRow {
     /** `YYYY-MM-DD` for days and week starts, `YYYY-MM` for months, the session id for sessions. */
@@ -29,7 +45,7 @@ export interface UsageBucketRow {
     project: string | null;
     /** Set when grouping by model; null for rows spanning every model. */
     model: string | null;
-    /** Session id for `session` rows; null otherwise. */
+    /** Session id for `session` rows and rows grouped by `session`; null otherwise. */
     sessionId: string | null;
     /** Models seen in the row, most tokens first. */
     models: string[];
@@ -41,8 +57,18 @@ export interface UsageBucketRow {
     totalTokens: number;
     /** Priced portion of the cost; read `costProvenance` before labelling it. */
     costUsd: number;
+    /**
+     * Sum of the priced calls' costs, or null when no call in the row was
+     * priced (where `costUsd` reads 0).
+     */
+    pricedCostUsd: number | null;
     costProvenance: AggregatedCostProvenance;
     unpricedCalls: number;
+    /**
+     * Reasoning tokens reported by the row's calls. Informational, already
+     * inside the token buckets and `totalTokens`. Always set by `bucketUsage`.
+     */
+    reasoningTokens?: number;
     /** First and last event in the row, ms since epoch. */
     firstTimestamp: number;
     lastTimestamp: number;
@@ -53,8 +79,12 @@ export interface UsageTotals {
     tokens: TokenTotals;
     totalTokens: number;
     costUsd: number;
+    /** Sum of the rows' priced costs, or null when no row had a priced call. */
+    pricedCostUsd: number | null;
     costProvenance: AggregatedCostProvenance;
     unpricedCalls: number;
+    /** Sum of the rows' `reasoningTokens`. Always set by `summarizeUsageRows`. */
+    reasoningTokens?: number;
 }
 /** The `YYYY-MM-DD` key of the week containing `ms`, starting on `weekStartsOn`. */
 export declare function weekKey(ms: number, options?: {
@@ -65,7 +95,8 @@ export declare function weekKey(ms: number, options?: {
 export declare function usageBucketKey(event: Pick<UsageEventRecord, 'timestamp' | 'sessionId'>, options: BucketUsageOptions): string;
 /**
  * Group usage events into rows. Rows are sorted by key (sessions by first
- * event), then provider, project, and model, so tables read oldest first.
+ * event), then provider, project, and model, so tables read oldest first;
+ * rows grouped by `session` within one of those follow their first event.
  */
 export declare function bucketUsage(events: readonly UsageEventRecord[], options: BucketUsageOptions): UsageBucketRow[];
 /**

package/dist/usage/usageReports.js

@@ -13,6 +13,8 @@ exports.bucketUsage = bucketUsage;
 exports.summarizeUsageRows = summarizeUsageRows;
 const costProvenance_1 = require("../aggregation/costProvenance");
 const formatting_1 = require("../formatting");
+const modelInfo_1 = require("../modelInfo");
+const claudeUsageDedupe_1 = require("./claudeUsageDedupe");
 function dayParts(ms, utc) {
     const date = new Date(ms);
     return utc
@@ -75,7 +77,8 @@ function addTokens(target, source) {
 }
 /**
  * Group usage events into rows. Rows are sorted by key (sessions by first
- * event), then provider, project, and model, so tables read oldest first.
+ * event), then provider, project, and model, so tables read oldest first;
+ * rows grouped by `session` within one of those follow their first event.
  */
 function bucketUsage(events, options) {
     const groupBy = new Set(options.groupBy ?? ['provider']);
@@ -83,13 +86,21 @@ function bucketUsage(events, options) {
     const byProvider = isSession || groupBy.has('provider');
     const byProject = isSession || groupBy.has('project');
     const byModel = groupBy.has('model');
+    const bySession = isSession || groupBy.has('session');
+    const keyModel = options.modelKey === 'canonical'
+        ? (model) => (model === claudeUsageDedupe_1.SYNTHETIC_MODEL ? model : (0, modelInfo_1.canonicalModelId)(model) || model)
+        : (model) => model;
     const buckets = new Map();
     for (const event of events) {
+        if (options.excludeSynthetic && event.model === claudeUsageDedupe_1.SYNTHETIC_MODEL)
+            continue;
         const key = usageBucketKey(event, options);
         const provider = byProvider ? event.provider : null;
         const project = byProject ? event.project : null;
-        const model = byModel ? event.model : null;
-        const id = [key, provider ?? '', project ?? '', model ?? ''].join('|');
+        const eventModel = keyModel(event.model);
+        const model = byModel ? eventModel : null;
+        const sessionId = bySession ? event.sessionId : null;
+        const id = JSON.stringify([key, provider, project, model, sessionId]);
         let acc = buckets.get(id);
         if (!acc) {
             acc = {
@@ -99,15 +110,17 @@ function bucketUsage(events, options) {
                     provider,
                     project,
                     model,
-                    sessionId: isSession ? event.sessionId : null,
+                    sessionId,
                     models: [],
                     calls: 0,
                     sessions: 0,
                     tokens: emptyTokens(),
                     totalTokens: 0,
                     costUsd: 0,
+                    pricedCostUsd: null,
                     costProvenance: 'none',
                     unpricedCalls: 0,
+                    reasoningTokens: 0,
                     firstTimestamp: event.timestamp,
                     lastTimestamp: event.timestamp,
                 },
@@ -122,12 +135,14 @@ function bucketUsage(events, options) {
         row.calls += 1;
         addTokens(row.tokens, event.tokens);
         row.totalTokens += event.tokens.totalTokens;
+        row.reasoningTokens = (row.reasoningTokens ?? 0) + reasoningOf(event.tokens.reasoningTokens);
         row.firstTimestamp = Math.min(row.firstTimestamp, event.timestamp);
         row.lastTimestamp = Math.max(row.lastTimestamp, event.timestamp);
         acc.sessionIds.add(event.sessionId);
-        acc.modelTokens.set(event.model, (acc.modelTokens.get(event.model) ?? 0) + event.tokens.totalTokens);
+        acc.modelTokens.set(eventModel, (acc.modelTokens.get(eventModel) ?? 0) + event.tokens.totalTokens);
         if (event.costUsd !== null) {
             row.costUsd += event.costUsd;
+            row.pricedCostUsd = (row.pricedCostUsd ?? 0) + event.costUsd;
             if (event.costProvenance === 'provider-reported')
                 acc.reportedCalls += 1;
             else
@@ -153,7 +168,14 @@ function bucketUsage(events, options) {
     return rows.sort((a, b) => (isSession ? a.firstTimestamp - b.firstTimestamp : a.key.localeCompare(b.key)) ||
         (a.provider ?? '').localeCompare(b.provider ?? '') ||
         (a.project ?? '').localeCompare(b.project ?? '') ||
-        (a.model ?? '').localeCompare(b.model ?? ''));
+        (a.model ?? '').localeCompare(b.model ?? '') ||
+        (bySession && !isSession
+            ? a.firstTimestamp - b.firstTimestamp ||
+                (a.sessionId ?? '').localeCompare(b.sessionId ?? '')
+            : 0));
+}
+function reasoningOf(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : 0;
 }
 /**
  * Sum rows that do not overlap (for example every row of one `bucketUsage`
@@ -167,8 +189,10 @@ function summarizeUsageRows(rows, events) {
         tokens: emptyTokens(),
         totalTokens: 0,
         costUsd: 0,
+        pricedCostUsd: null,
         costProvenance: 'none',
         unpricedCalls: 0,
+        reasoningTokens: 0,
     };
     let reportedCalls = 0;
     let estimatedCalls = 0;
@@ -178,6 +202,15 @@ function summarizeUsageRows(rows, events) {
         addTokens(totals.tokens, row.tokens);
         totals.totalTokens += row.totalTokens;
         totals.costUsd += row.costUsd;
+        // Rows from before `pricedCostUsd` existed: any priced call means a priced cost.
+        const rowPriced = row.pricedCostUsd !== undefined
+            ? row.pricedCostUsd
+            : row.calls > row.unpricedCalls
+                ? row.costUsd
+                : null;
+        if (rowPriced !== null)
+            totals.pricedCostUsd = (totals.pricedCostUsd ?? 0) + rowPriced;
+        totals.reasoningTokens = (totals.reasoningTokens ?? 0) + reasoningOf(row.reasoningTokens);
         totals.unpricedCalls += row.unpricedCalls;
         const priced = row.calls - row.unpricedCalls;
         if (row.costProvenance === 'reported')

package/dist/watchers/jsonlTail.d.ts

@@ -7,6 +7,8 @@ import type { ZodType } from 'zod';
 export declare const DEFAULT_JSONL_TAIL_READ_BYTES: number;
 /** Default longest line parsed; longer lines are skipped and reported. */
 export declare const DEFAULT_JSONL_TAIL_MAX_LINE_BYTES: number;
+/** The `version` written into, and accepted from, {@link JsonlTailCheckpoint}. */
+export declare const JSONL_TAIL_CHECKPOINT_VERSION = 1;
 export interface JsonlTailBatch {
     bytesRead: number;
     eventsRead: number;
@@ -20,12 +22,68 @@ export interface JsonlTailLine {
     length: number;
 }
 export type JsonlTailResetReason = 'truncated' | 'rewritten' | 'replaced';
-/** The tail started over from the beginning of the file. */
+/**
+ * What the tail does when the file it follows shrank, was rewritten, or was
+ * replaced: `'restart'` replays it from offset 0; `'end'` continues from its
+ * current end, skipping what it already holds.
+ */
+export type JsonlTailRewritePolicy = 'restart' | 'end';
+/** The tail started over from the beginning, or (with `onRewrite: 'end'`) the end, of the file. */
 export interface JsonlTailReset {
     /** `truncated`: the file shrank; `rewritten`: its first bytes or the resume point changed; `replaced`: another file now has the path. */
     reason: JsonlTailResetReason;
     /** The committed offset before the reset. */
     previousOffset: number;
+    /**
+     * Where reading continues. Present only with `onRewrite: 'end'`; with the
+     * default `'restart'` policy reading always continues from 0.
+     */
+    offset?: number;
+}
+/** An event parsed by {@link JsonlTail.read}, with its line's position. */
+export interface JsonlTailEntry<T> {
+    event: T;
+    line: JsonlTailLine;
+}
+/** What one {@link JsonlTail.read} call read. */
+export interface JsonlTailReadResult<T> extends JsonlTailBatch {
+    /** Events from the lines that became complete, in file order: the same ones `onEvent` received. */
+    events: JsonlTailEntry<T>[];
+    /** Present when the tail reset before reading; `onReset` received the same object. */
+    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`.
+ */
+export interface JsonlTailCheckpoint {
+    version: typeof JSONL_TAIL_CHECKPOINT_VERSION;
+    /** Resume-safe byte offset: 0, or just after a newline. */
+    offset: number;
+    /** Device and inode of the file the offset refers to; `null` before the first read. */
+    identity: {
+        dev: number;
+        ino: number;
+    } | null;
+    /**
+     * Length (at most 4096) and truncated SHA-256 hex of the file's first
+     * bytes when last read; `null` before the first read.
+     */
+    prefixDigest: {
+        bytes: number;
+        hash: string;
+    } | null;
+}
+/**
+ * Reported to `onError` (and nothing is read) when `noFollow` is set and the
+ * tailed path is a symbolic link.
+ */
+export declare class JsonlTailSymlinkError extends Error {
+    readonly path: string;
+    readonly code = "JSONL_TAIL_SYMLINK";
+    constructor(path: string);
 }
 export interface JsonlTailOptions<T> {
     path: string;
@@ -37,20 +95,59 @@ export interface JsonlTailOptions<T> {
     onEvent: (event: T, line: JsonlTailLine) => void;
     onBatchComplete?: (batch: JsonlTailBatch) => void;
     onError?: (error: Error, line?: string) => void;
-    /** Called after the tail resets to offset 0; events from the start follow. */
+    /** Called after the tail resets (see `onRewrite`); events from the new position follow. */
     onReset?: (reset: JsonlTailReset) => void;
     /** Bytes read per chunk (default 1 MiB); one poll reads chunk by chunk to the end. */
     maxReadBytes?: number;
     /** Longest line parsed (default 16 MiB); a longer line is skipped and reported to `onError`. */
     maxLineBytes?: number;
+    /**
+     * Where to continue after the file is truncated, rewritten, or replaced,
+     * and after `resumeFrom()` rejects a checkpoint. `'restart'` (default)
+     * replays from offset 0. `'end'` continues from the file's current end, or
+     * from the start of an unfinished final line as `startAtEnd` does. `onReset`
+     * fires either way.
+     */
+    onRewrite?: JsonlTailRewritePolicy;
+    /**
+     * Refuse to follow a symbolic link at `path`: the file is opened with
+     * `O_NOFOLLOW` where the platform defines it (a no-op where it does not,
+     * such as Windows). A symlinked path is reported to `onError` as a
+     * {@link JsonlTailSymlinkError} and not read or watched. Only the final
+     * path component is checked; symlinked parent directories still resolve.
+     */
+    noFollow?: boolean;
 }
-export interface JsonlTail {
+export interface JsonlTail<T = unknown> {
     readonly isActive: boolean;
     start(): void;
     stop(): void;
     dispose(): void;
+    /**
+     * Reads every newly complete line now, synchronously, through the
+     * callbacks. While `read()` calls are queued or running, the call is
+     * deferred until the last of them settles.
+     */
     readNow(): void;
+    /**
+     * Reads like `readNow()`, with asynchronous I/O, and resolves with what it
+     * read; the callbacks fire as they do for `readNow()`. Never rejects for
+     * I/O or parse problems (those go to `onError`). Concurrent calls run one
+     * after another.
+     */
+    read(): Promise<JsonlTailReadResult<T>>;
     getOffset(): number;
     seekTo(offset: number): void;
+    /** A JSON-serializable resume point at the committed offset; does no I/O. */
+    checkpoint(): JsonlTailCheckpoint;
+    /**
+     * Validates `checkpoint` (shape, file identity, prefix digest, and that its
+     * offset still follows a newline) against the file now at the path. On
+     * success reading continues from its offset and this returns true.
+     * Otherwise the `onRewrite` policy picks the position (0, or the file's
+     * current end) and this returns false; `onReset` is not called. Either way
+     * the position overrides `startAtEnd` on a later `start()`.
+     */
+    resumeFrom(checkpoint: unknown): boolean;
 }
-export declare function createJsonlTail<T>(options: JsonlTailOptions<T>): JsonlTail;
+export declare function createJsonlTail<T>(options: JsonlTailOptions<T>): JsonlTail<T>;