@50arms/session-telemetry 0.0.0-stage → 0.1.66

package/dist/usage-ledger.js

@@ -0,0 +1,581 @@
+import { LEDGER_TIMING_FIELDS, maxTiming, zeroTiming } from "./ledger-timing.js";
+import { SourceTimingReducer, } from "./transcript-timing.js";
+import { hasRealWork } from "./real-work.js";
+/** DX-4922 - what started a compaction: Claude Code's own threshold (`auto`) or the user's `/compact` (`manual`). */
+export const COMPACTION_TRIGGERS = ["auto", "manual"];
+export const MAIN_SOURCE = "main";
+/**
+ * DX-3261 — a producer handed this module a line it cannot safely key or
+ * date: no valid `byte_offset` on a no-`message.id` line (would collapse
+ * every such line in the source onto the same synthetic key, crediting only
+ * the largest — see {@link syntheticMessageKey}), or a `timestamp` that
+ * doesn't parse (would read as `repliedAt: 0`, invisible to every
+ * account-window lookback). Both were silent `0` defaults before this card;
+ * thrown here instead, so a broken producer fails immediately and visibly
+ * rather than quietly losing or mis-crediting usage.
+ */
+export class LedgerLineDataError extends Error {
+}
+/**
+ * DX-2963 — a usage line with no `message.id` (never observed in the 22,087
+ * usage lines of the 20 newest local transcripts, 2026-09-18) is keyed by its
+ * source and the byte offset of its line, so it is credited exactly once
+ * however often the file is re-read, instead of once per read.
+ */
+export function syntheticMessageKey(source, byteOffset) {
+    return `nomsg:${source}:${byteOffset}`;
+}
+export function isSyntheticMessageKey(key) {
+    return key.startsWith("nomsg:");
+}
+/**
+ * A usage field as a non-negative INTEGER count. A numeric STRING is read as
+ * its number (drift-safe: a transcript that ever quotes a count is still
+ * counted, never silently zeroed); anything else absent or non-numeric is 0.
+ *
+ * DX-3261 — rounded to the nearest integer, never passed through fractional.
+ * A token count is an integer by definition, so a fractional value here is
+ * itself the anomaly (a malformed/synthetic producer), not a legitimate
+ * reading to preserve verbatim — and the wire contract this feeds
+ * (`parseStatsPayload`'s `isNonNegInt`, `stats-wire.ts`) REQUIRES an
+ * integer and fails loud on anything else. Before this fix a fractional
+ * value here would sail through the counter, get queued as a changed entry,
+ * then 400 on every single stats-write attempt for that dispatch FOREVER —
+ * the worker's `flush()` re-queues a failed batch unconditionally, so a
+ * value that never changes never stops failing. Rounding at the source
+ * closes the gap without loosening the wire's own integer contract.
+ */
+function num(v) {
+    const n = typeof v === "string" && v.trim() !== "" ? Number(v) : v;
+    return typeof n === "number" && Number.isFinite(n) && n > 0 ? Math.round(n) : 0;
+}
+/**
+ * Read a raw `message.usage` block into {@link LedgerUsage}. The two
+ * cache-write lifetimes come from `usage.cache_creation.ephemeral_5m_input_tokens`
+ * / `ephemeral_1h_input_tokens`. A line that carries only the flat
+ * `cache_creation_input_tokens` (no split object) wrote with the API's
+ * default 5-minute lifetime, so the whole amount is a 5-minute write — that
+ * is what the flat field meant before the split existed.
+ */
+export function parseUsageBlock(raw) {
+    const split = raw.cache_creation;
+    const hasSplit = split !== null && typeof split === "object";
+    return {
+        input: num(raw.input_tokens),
+        output: num(raw.output_tokens),
+        cacheRead: num(raw.cache_read_input_tokens),
+        cacheWrite5m: hasSplit
+            ? num(split.ephemeral_5m_input_tokens)
+            : num(raw.cache_creation_input_tokens),
+        cacheWrite1h: hasSplit ? num(split.ephemeral_1h_input_tokens) : 0,
+    };
+}
+export function zeroUsage() {
+    return { input: 0, output: 0, cacheRead: 0, cacheWrite5m: 0, cacheWrite1h: 0 };
+}
+export const LEDGER_USAGE_FIELDS = [
+    "input",
+    "output",
+    "cacheRead",
+    "cacheWrite5m",
+    "cacheWrite1h",
+];
+export function maxUsage(a, b) {
+    const out = zeroUsage();
+    for (const f of LEDGER_USAGE_FIELDS)
+        out[f] = Math.max(a[f], b[f]);
+    return out;
+}
+export function addUsage(a, b) {
+    const out = zeroUsage();
+    for (const f of LEDGER_USAGE_FIELDS)
+        out[f] = a[f] + b[f];
+    return out;
+}
+/** Per-field `max(0, a - b)`. */
+export function excessUsage(a, b) {
+    const out = zeroUsage();
+    for (const f of LEDGER_USAGE_FIELDS)
+        out[f] = Math.max(0, a[f] - b[f]);
+    return out;
+}
+export function isZeroUsage(u) {
+    return LEDGER_USAGE_FIELDS.every((f) => u[f] === 0);
+}
+/** Window tokens: input + output + both cache writes (the account-window unit). */
+export function windowTokensOfUsage(u) {
+    return u.input + u.output + u.cacheWrite5m + u.cacheWrite1h;
+}
+/** All five fields summed. */
+export function totalTokensOfUsage(u) {
+    return u.input + u.output + u.cacheRead + u.cacheWrite5m + u.cacheWrite1h;
+}
+function readSpeed(usage) {
+    const s = usage?.speed;
+    return typeof s === "string" && s.length > 0 ? s : "standard";
+}
+/**
+ * The per-process counter: one entry per reply, updated line by line.
+ * `observe` returns true when the line CHANGED the reply's entry (a new
+ * reply, a raised field, or a new tool-use id) — a replay returns false —
+ * and the entry is queued for {@link takeChanged}. Holds one small entry per
+ * reply for the life of the process; no transcript text is kept.
+ */
+export class UsageLedgerCounter {
+    entries = new Map();
+    changed = new Set();
+    /** DX-3964 - one timing reducer per source (transcript file); see `transcript-timing.ts`. */
+    reducers = new Map();
+    /** DX-4922 - every compaction boundary read, by its id. */
+    compactions = new Map();
+    compactionsChanged = new Set();
+    /** DX-4939 - per source, the compaction whose summary line has not been read yet. */
+    openSummary = new Map();
+    /**
+     * DX-3964 - feed one line of the fed set (assistant, user, attachment, system) in FILE ORDER. An assistant
+     * line credits usage exactly as {@link observe} does; every kind also feeds its source's timing reducer,
+     * and a reply's timing that RISES - including one raised by a later tool_result, after the reply's last line,
+     * with no token growth - counts as a change, so {@link takeChanged} re-sends it.
+     */
+    observeLine(t) {
+        let didChange = t.kind === "assistant" ? this.observe(t.line) : false;
+        if (t.kind === "compaction")
+            this.observeCompaction(t);
+        if (t.kind === "user" && t.compactSummaryChars !== null)
+            this.observeCompactSummary(t.source, t.compactSummaryChars);
+        const source = t.kind === "assistant" ? t.line.source : t.source;
+        let reducer = this.reducers.get(source);
+        if (!reducer) {
+            reducer = new SourceTimingReducer();
+            this.reducers.set(source, reducer);
+        }
+        for (const [key, timing] of reducer.feed(t)) {
+            const entry = this.entries.get(key);
+            // A reply the usage counter never opened (no usage and no tool id) has no entry to carry timing.
+            if (!entry)
+                continue;
+            const next = maxTiming(entry.timing, timing);
+            if (LEDGER_TIMING_FIELDS.some((f) => next[f] !== entry.timing[f])) {
+                entry.timing = next;
+                this.changed.add(key);
+                didChange = true;
+            }
+        }
+        return didChange;
+    }
+    observeCompaction(t) {
+        const known = this.compactions.get(t.boundary.id);
+        if (known !== undefined) {
+            // a replay of a boundary already read; its summary line is still awaited when it was not read the first time
+            if (known.summaryChars === null)
+                this.openSummary.set(t.source, known.id);
+            return;
+        }
+        this.compactions.set(t.boundary.id, { ...t.boundary, source: t.source, at: t.timestamp, summaryChars: null });
+        this.compactionsChanged.add(t.boundary.id);
+        this.openSummary.set(t.source, t.boundary.id);
+    }
+    /**
+     * DX-4939 - the summary text follows its boundary in the same source's file: the next `isCompactSummary` user line belongs to the
+     * compaction last read there. A compaction is reported at its boundary and again (a changed entry) once its summary length is known,
+     * so a session that ends right after compacting still reports it.
+     */
+    observeCompactSummary(source, chars) {
+        const id = this.openSummary.get(source);
+        if (id === undefined)
+            return; // no boundary of this reader's session open here (a replayed or inherited summary)
+        this.openSummary.delete(source);
+        const entry = this.compactions.get(id);
+        entry.summaryChars = chars;
+        this.compactionsChanged.add(id);
+    }
+    /** DX-4922 - the compactions read since the last call, oldest first, as snapshots; clears the queue. */
+    takeChangedCompactions() {
+        const out = [...this.compactionsChanged].map((id) => ({ ...this.compactions.get(id) }));
+        this.compactionsChanged.clear();
+        return out;
+    }
+    /** DX-4922 - put compactions back on the changed queue (a write that failed). */
+    requeueCompactions(ids) {
+        for (const id of ids)
+            if (this.compactions.has(id))
+                this.compactionsChanged.add(id);
+    }
+    /**
+     * DX-3964 - a source's file was truncated and is read again from 0: its timing reducer starts fresh and
+     * first-line-anchored, so a stale `hwm` of the old file can never credit a gap at the reset. Entries keep their
+     * values (max semantics); the re-read can only raise them.
+     */
+    resetSource(source) {
+        this.reducers.delete(source);
+    }
+    observe(line) {
+        const hasUsage = line.usage !== undefined;
+        if (!hasUsage && line.toolUseIds.length === 0)
+            return false;
+        // A tool-use-only line with no id cannot be tied to a reply; it has no
+        // usage to credit, and its tool ids would be counted on a key no other
+        // line of the reply shares — skip it rather than invent a reply.
+        if (line.messageId === undefined && !hasUsage)
+            return false;
+        const key = line.messageId ?? syntheticMessageKey(line.source, line.byteOffset);
+        const usage = hasUsage ? parseUsageBlock(line.usage) : zeroUsage();
+        const prior = this.entries.get(key);
+        if (!prior) {
+            this.entries.set(key, {
+                messageId: key,
+                source: line.source,
+                model: line.model ?? null,
+                speed: readSpeed(line.usage),
+                usage,
+                timing: zeroTiming(),
+                repliedAt: line.timestamp,
+                toolUseIds: [...new Set(line.toolUseIds)],
+                issueId: line.issueId,
+                realWork: line.realWork,
+            });
+            this.changed.add(key);
+            return true;
+        }
+        let didChange = false;
+        const next = maxUsage(prior.usage, usage);
+        if (LEDGER_USAGE_FIELDS.some((f) => next[f] !== prior.usage[f])) {
+            prior.usage = next;
+            didChange = true;
+        }
+        for (const id of line.toolUseIds) {
+            if (!prior.toolUseIds.includes(id)) {
+                prior.toolUseIds.push(id);
+                didChange = true;
+            }
+        }
+        if (line.realWork && !prior.realWork) {
+            prior.realWork = true;
+            didChange = true;
+        }
+        if (prior.model === null && line.model) {
+            prior.model = line.model;
+            didChange = true;
+        }
+        if (hasUsage && prior.speed !== readSpeed(line.usage) && readSpeed(line.usage) !== "standard") {
+            prior.speed = readSpeed(line.usage);
+            didChange = true;
+        }
+        if (didChange)
+            this.changed.add(key);
+        return didChange;
+    }
+    /** Entries changed since the last call, as snapshots; clears the queue. */
+    takeChanged() {
+        const out = [];
+        for (const key of this.changed) {
+            const e = this.entries.get(key);
+            if (e)
+                out.push(snapshot(e));
+        }
+        this.changed.clear();
+        return out;
+    }
+    /** Put entries back on the changed queue (a write that failed). */
+    requeue(messageIds) {
+        for (const id of messageIds)
+            if (this.entries.has(id))
+                this.changed.add(id);
+    }
+    get(messageId) {
+        const e = this.entries.get(messageId);
+        return e ? snapshot(e) : undefined;
+    }
+    all() {
+        return [...this.entries.values()].map(snapshot);
+    }
+    /** Per-field sum of every reply's maximum — the transcript's true total. */
+    totals() {
+        let t = zeroUsage();
+        for (const e of this.entries.values())
+            t = addUsage(t, e.usage);
+        return t;
+    }
+    /** Distinct tool-use ids across all replies. */
+    toolUseCount() {
+        let n = 0;
+        for (const e of this.entries.values())
+            n += e.toolUseIds.length;
+        return n;
+    }
+}
+function snapshot(e) {
+    return { ...e, usage: { ...e.usage }, timing: { ...e.timing }, toolUseIds: [...e.toolUseIds] };
+}
+/** The line types the usage collector is fed; every other `type` is ignored. */
+const FED_TYPES = new Set(["assistant", "user", "attachment", "system"]);
+function parseTimestamp(raw, fn) {
+    const ts = typeof raw.timestamp === "string" ? Date.parse(raw.timestamp) : NaN;
+    // DX-3261 - an unparseable/missing timestamp used to silently become `repliedAt: 0` (epoch 0), which falls
+    // outside every account-window lookback and made that reply's tokens permanently invisible to the gate - with
+    // no event, no log, nothing. Fail loud instead. DX-3964: the same for every fed kind, because `hwm` and the
+    // request-send time read it, and a `Date.now()` default would put wall clock into them.
+    if (!Number.isFinite(ts)) {
+        throw new LedgerLineDataError(`${fn}: unparseable/missing timestamp (raw.timestamp=${JSON.stringify(raw.timestamp)})`);
+    }
+    return ts;
+}
+function blocksOf(message) {
+    return message && Array.isArray(message.content)
+        ? message.content
+        : [];
+}
+/** The text of a message's content: the string itself, or its text blocks joined. */
+function textOfContent(content) {
+    return typeof content === "string" ? content : textOfResult(content);
+}
+function textOfResult(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .map((b) => b && typeof b === "object" && typeof b.text === "string"
+        ? b.text
+        : "")
+        .join("\n");
+}
+function toolResultsOf(raw, blocks) {
+    // An `isMeta` user line is counted as a human prompt, as the reference reducer does.
+    if (raw.isMeta === true)
+        return [];
+    const resultBlocks = blocks.filter((b) => b.type === "tool_result" && typeof b.tool_use_id === "string");
+    const tur = raw.toolUseResult;
+    // `toolUseResult` is one object per LINE: it can only be attributed to a line carrying exactly one result.
+    const patch = resultBlocks.length === 1 && tur && typeof tur === "object" && Array.isArray(tur.structuredPatch)
+        ? tur.structuredPatch.map((h) => ({
+            lines: Array.isArray(h.lines) ? h.lines.filter((l) => typeof l === "string") : [],
+        }))
+        : null;
+    return resultBlocks.map((b) => ({
+        toolUseId: b.tool_use_id,
+        isError: b.is_error === true,
+        text: textOfResult(b.content),
+        structuredPatch: patch,
+    }));
+}
+function toolUsesOf(blocks) {
+    return blocks
+        .filter((b) => b.type === "tool_use" && typeof b.id === "string")
+        .map((b) => ({
+        id: b.id,
+        name: typeof b.name === "string" ? b.name : "",
+        input: b.input && typeof b.input === "object" && !Array.isArray(b.input) ? b.input : null,
+    }));
+}
+/** The reader ships nothing, so it reports no compactions. */
+export const REPORT_NO_COMPACTIONS = { report: false };
+/** The reader reports the compactions of `sessionId`: the session its transcript FILE belongs to. */
+export function reportCompactionsOf(sessionId) {
+    return { report: true, sessionId };
+}
+const NEWLINE = "\n";
+/**
+ * The reading for a transcript of a FRESH session read as text: the session id its own lines carry. Only right where
+ * nothing is inherited (a bench attempt starts a new session); a fork's file starts with its parent's lines, so a
+ * live reader takes the session from the file's location instead (`transcriptSessionId`). A transcript with no line
+ * carrying a session id has no compaction boundary either, so it reports none.
+ */
+export function reportCompactionsOfFreshTranscript(text) {
+    let found = null;
+    for (const rawLine of text.split(NEWLINE)) {
+        const trimmed = rawLine.trim();
+        if (!trimmed)
+            continue;
+        let sessionId;
+        try {
+            sessionId = JSON.parse(trimmed).sessionId;
+        }
+        catch {
+            continue; // a truncated line carries no session id; the next one may
+        }
+        if (typeof sessionId !== "string" || sessionId.length === 0)
+            continue;
+        // DX-4940: the "fresh session" premise is enforced, not assumed: a transcript carrying a second session id has inherited lines
+        // (a fork or resume), and reading it as one session would report the parent's compactions as its own.
+        if (found !== null && sessionId !== found) {
+            throw new LedgerLineDataError(`reportCompactionsOfFreshTranscript: the transcript carries more than one session id (${JSON.stringify(found)}, ${JSON.stringify(sessionId)}), so it is not a fresh session`);
+        }
+        found = sessionId;
+    }
+    return found === null ? REPORT_NO_COMPACTIONS : reportCompactionsOf(found);
+}
+/**
+ * Parse one raw transcript line (a parsed JSONL object) of the fed set - assistant, user (tool_result and human
+ * prompts), attachment, system - into a {@link TranscriptLine}. Returns `null` for every other `type`
+ * (`queue-operation`, `last-prompt`, `file-history-*`, `custom-title`, ...). THE one parser for the usage feed:
+ * the live watcher subscription, `observeTranscriptText` (claude-probe) and the tests all go through it.
+ */
+export function ledgerLineFromRaw(raw, source, byteOffset, compactions) {
+    const type = raw.type;
+    if (typeof type !== "string" || !FED_TYPES.has(type))
+        return null;
+    const message = raw.message;
+    if (type === "assistant") {
+        if (!message)
+            return null;
+        const ts = parseTimestamp(raw, "ledgerLineFromRaw");
+        const blocks = blocksOf(message);
+        const toolUses = toolUsesOf(blocks);
+        const messageId = typeof message.id === "string" && message.id.length > 0 ? message.id : undefined;
+        const model = typeof message.model === "string" && message.model.length > 0 ? message.model : undefined;
+        return {
+            kind: "assistant",
+            line: {
+                messageId,
+                source,
+                byteOffset,
+                model,
+                usage: message.usage && typeof message.usage === "object"
+                    ? message.usage
+                    : undefined,
+                timestamp: ts,
+                toolUseIds: toolUses.map((u) => u.id),
+                issueId: null,
+                realWork: hasRealWork(toolUses),
+            },
+            replyKey: messageId ?? syntheticMessageKey(source, byteOffset),
+            byteOffset,
+            synthetic: model === "<synthetic>",
+            toolUses,
+        };
+    }
+    const timestamp = parseTimestamp(raw, "ledgerLineFromRaw");
+    if (type === "user") {
+        const blocks = blocksOf(message);
+        return {
+            kind: "user",
+            source,
+            timestamp,
+            byteOffset,
+            results: toolResultsOf(raw, blocks),
+            compactSummaryChars: raw.isCompactSummary === true ? textOfContent(message?.content).length : null,
+        };
+    }
+    // DX-4922: only the session's OWN compactions are reported. A forked or resumed session's transcript starts with
+    // copies of its parent's lines, boundary lines included, and those keep the parent's `sessionId`; the parent reports
+    // its own, so a copy is read as the plain system line it also is for timing. A reader that reports no compactions
+    // reads every boundary that way.
+    if (type === "system" && raw.subtype === "compact_boundary" && compactions.report) {
+        if (typeof raw.sessionId !== "string" || raw.sessionId.length === 0) {
+            throw new LedgerLineDataError("ledgerLineFromRaw: compact_boundary without a sessionId, so whose compaction it is cannot be told");
+        }
+        if (raw.sessionId === compactions.sessionId) {
+            return { kind: "compaction", source, timestamp, byteOffset, boundary: compactionBoundaryOf(raw) };
+        }
+    }
+    return { kind: type, source, timestamp, byteOffset };
+}
+/** DX-4922 - read a `compact_boundary` line; a boundary this reader cannot identify or measure is a loud error, never a guess. */
+function compactionBoundaryOf(raw) {
+    const meta = raw.compactMetadata;
+    const trigger = meta?.trigger;
+    const preTokens = meta?.preTokens;
+    if (typeof raw.uuid !== "string" ||
+        raw.uuid.length === 0 ||
+        !COMPACTION_TRIGGERS.includes(trigger) ||
+        typeof preTokens !== "number" ||
+        !Number.isFinite(preTokens) ||
+        preTokens < 0) {
+        throw new LedgerLineDataError(`ledgerLineFromRaw: compact_boundary without a uuid, a known trigger and a preTokens count (uuid=${JSON.stringify(raw.uuid)}, trigger=${JSON.stringify(trigger)}, preTokens=${JSON.stringify(preTokens)})`);
+    }
+    return {
+        id: raw.uuid,
+        trigger: trigger,
+        contextBefore: Math.round(preTokens),
+        postTokens: optionalCount(meta?.postTokens, "postTokens", raw.uuid),
+        durationMs: optionalCount(meta?.durationMs, "durationMs", raw.uuid),
+    };
+}
+/** DX-4939 - a boundary figure that may be absent (`null`) but is never a wrong type: a present value that is not a non-negative number is a loud error. */
+function optionalCount(value, field, uuid) {
+    if (value === undefined)
+        return null;
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+        throw new LedgerLineDataError(`ledgerLineFromRaw: compact_boundary ${field} is not a non-negative number (uuid=${uuid}, ${field}=${JSON.stringify(value)})`);
+    }
+    return Math.round(value);
+}
+/**
+ * Count a whole transcript text (one file) into a counter. Byte offsets are
+ * computed on UTF-8 bytes so a no-id line keys identically to the live
+ * watcher's own offset for the same line.
+ */
+export function observeTranscriptText(counter, text, source, compactions, startByteOffset = 0) {
+    const encoder = new TextEncoder();
+    let offset = startByteOffset;
+    for (const rawLine of text.split("\n")) {
+        const lineBytes = encoder.encode(rawLine).length;
+        const lineOffset = offset;
+        offset += lineBytes + 1;
+        const trimmed = rawLine.trim();
+        if (!trimmed)
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        const line = ledgerLineFromRaw(parsed, source, lineOffset, compactions);
+        if (line)
+            counter.observeLine(line);
+    }
+}
+/**
+ * The counter's {@link LedgerLine} for one converted watcher entry
+ * (`AgentLogEntry`, as `SessionLogWatcher` emits it: `data.messageId`,
+ * `data.model`, `data.usage`, `data.content`, `data.subagent_id`,
+ * `data.byte_offset`). `null` for anything that is not an assistant entry.
+ * Shared by every counter fed from watcher entries (the worker's dispatch
+ * usage, the stall sweep's productivity signal).
+ */
+export function ledgerLineFromLogEntry(entry) {
+    if (entry.type !== "assistant")
+        return null;
+    const d = entry.data;
+    const content = Array.isArray(d.content)
+        ? d.content
+        : [];
+    const hasMessageId = typeof d.messageId === "string" && d.messageId.length > 0;
+    const hasUsage = Boolean(d.usage && typeof d.usage === "object");
+    const toolUseIds = content
+        .filter((b) => b.type === "tool_use" && typeof b.id === "string")
+        .map((b) => b.id);
+    // DX-3261 — `byteOffset` only matters as the synthetic key for a line with
+    // no `message.id` (`syntheticMessageKey`); a missing/invalid one used to
+    // silently default to `0`, collapsing EVERY no-id reply from this source
+    // onto one key so only the largest single reply was ever credited. Fail
+    // loud rather than repeat that silent collapse — but ONLY when the line
+    // will actually reach that keying step: `UsageLedgerCounter.observe()`
+    // discards a no-id line with neither usage nor a tool-use id before ever
+    // building a key (a tool-call block with no reported `id`, an empty
+    // wrapper entry), so requiring a valid `byteOffset` on THOSE too would
+    // reject lines the counter was always going to ignore. Harmless when a
+    // real `messageId` is present (byteOffset is never used to key that line).
+    if (!hasMessageId && (hasUsage || toolUseIds.length > 0) && typeof d.byte_offset !== "number") {
+        throw new LedgerLineDataError(`ledgerLineFromLogEntry: missing/invalid byte_offset on a no-message-id line carrying usage or a tool-use id (source=${typeof d.subagent_id === "string" ? d.subagent_id : MAIN_SOURCE})`);
+    }
+    return {
+        messageId: hasMessageId ? d.messageId : undefined,
+        source: typeof d.subagent_id === "string" ? d.subagent_id : MAIN_SOURCE,
+        byteOffset: typeof d.byte_offset === "number" ? d.byte_offset : 0,
+        model: typeof d.model === "string" && d.model.length > 0 ? d.model : undefined,
+        usage: hasUsage ? d.usage : undefined,
+        timestamp: entry.timestamp,
+        toolUseIds,
+        issueId: null,
+        realWork: hasRealWork(content
+            .filter((b) => b.type === "tool_use" && typeof b.id === "string")
+            .map((b) => ({
+            name: typeof b.name === "string" ? b.name : "",
+            input: b.input && typeof b.input === "object" && !Array.isArray(b.input) ? b.input : null,
+        }))),
+    };
+}

package/dist/write-queue.d.ts

@@ -0,0 +1,9 @@
+/**
+ * DX-2398 — a per-tracker FIFO for writes that must land in order: the
+ * periodic stats flush and the terminal finalize (a tick already in flight
+ * when cleanup stops the timer must not commit after the terminal write).
+ * DX-2963 also serializes a dispatch's stats batches through it, so two
+ * flushes never interleave their batches. The chain is never left rejected:
+ * each writer owns its own error handling.
+ */
+export declare function createUsageWriteQueue(): <T>(write: () => Promise<T>) => Promise<T>;

package/dist/write-queue.js

@@ -0,0 +1,16 @@
+/**
+ * DX-2398 — a per-tracker FIFO for writes that must land in order: the
+ * periodic stats flush and the terminal finalize (a tick already in flight
+ * when cleanup stops the timer must not commit after the terminal write).
+ * DX-2963 also serializes a dispatch's stats batches through it, so two
+ * flushes never interleave their batches. The chain is never left rejected:
+ * each writer owns its own error handling.
+ */
+export function createUsageWriteQueue() {
+    let chain = Promise.resolve();
+    return (write) => {
+        const queued = chain.then(write);
+        chain = queued.then(() => undefined, () => undefined);
+        return queued;
+    };
+}

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@50arms/session-telemetry",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.66",
+  "description": "Shared Claude Code transcript collector (DX-2962) — incremental JSONL tailing for the danxbot worker and the platform-mcp MCP server's relay, so both run identical collector code.",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "source": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.ts",
+      "source": "./src/browser.ts",
+      "default": "./dist/browser.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/newms87/danxbot.git",
+    "directory": "packages/danx-session-telemetry"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "prepublishOnly": "bash ../../scripts/assert-tree-contains-origin-main.sh @50arms/session-telemetry",
+    "build": "tsc -p tsconfig.json",
+    "verify:boot": "bash scripts/verify-boot.sh",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.18"
+  }
+}