@thehammer/danx-session-telemetry 0.1.14 → 0.1.16

package/dist/stats-wire.d.ts

@@ -0,0 +1,227 @@
+/**
+ * DX-2963 — the stats-write wire contract, shared by the worker (sender) and
+ * the dashboard (the one server writer, `usage-ledger.ts`). DB-free so a
+ * DB-less worker can import it.
+ *
+ * A stats write carries ONLY ledger entries (one per reply: the per-field
+ * maximum usage seen so far, the reply's tool-use ids) that are new or changed
+ * since the last acknowledged write — never totals. Every total, the cost,
+ * the turn count and the tool-call count are derived from the ledger on the
+ * server, and the response hands them back.
+ */
+import type { LedgerEntry, LedgerUsage } from "./usage-ledger.js";
+/**
+ * DX-2963 — cap on entries per stats write. A from-0 backlog (a reattach, a
+ * session read from the start) is sent as consecutive capped batches, so one
+ * request never carries an unbounded body or holds the dispatch lock for an
+ * unbounded time. 500 entries is well under a second of upsert work.
+ */
+export declare const STATS_BATCH_CAP = 500;
+/**
+ * DX-2954 — the two offsets a collector keeps per `(dispatch, source)`, where
+ * `source` is the value the ledger keys by (`main`, or a sub-agent id).
+ *
+ *   - `acked` — the RESUME point: every line before it has had its ledger
+ *     entry acknowledged (and, once DX-2956 ships, its log line too).
+ *   - `delivered` — the highest line already handed to transcript subscribers.
+ *
+ * Lines between them are re-read on a restart and handed on as REPLAYS.
+ *
+ * "None stored" is the ABSENCE of a source's key, never `{acked: 0}` — 0 is a
+ * legitimate stored cursor meaning "start of file", and CP1 forbids a reader
+ * defaulting a missing persisted value.
+ */
+export interface SourceCursor {
+    acked: number;
+    delivered: number;
+}
+/** DX-2954 — per-source cursors. An absent key means none stored (never 0). */
+export type SourceCursors = Record<string, SourceCursor>;
+/**
+ * DX-2954 — the collector found its stored cursor PAST the end of the file (it
+ * was replaced or truncated) and restarted that source at 0. Reported so the
+ * server can record a `transcript_cursor_past_eof` event with both numbers.
+ *
+ * This is the ONE sanctioned backwards move of a stored `acked`: without it the
+ * write would be refused as a `cursor_regression` and the source would tail
+ * nothing for the rest of the dispatch (the pre-card watcher's `size <=
+ * byteOffset` early return, silently).
+ */
+export interface PastEofReset {
+    storedOffset: number;
+    fileSize: number;
+}
+/** DX-2954 — the payload form of a cursor: what a collector REPORTS. */
+export interface SourceCursorReport extends SourceCursor {
+    pastEof?: PastEofReset;
+}
+/** DX-2954 — per-source cursor reports, as a stats write carries them. */
+export type SourceCursorReports = Record<string, SourceCursorReport>;
+/**
+ * DX-2954 — the running set's two kinds. `agent` is a sub-agent, produced from
+ * the TRANSCRIPT: one row per sub-agent transcript file the session-log watcher
+ * discovers (`packages/danx-session-telemetry/src/activity-observer.ts`; orchestrator decision, DX-2954
+ * comment 8004). `bash` is a background script; nothing produces it yet — the
+ * hook-side producer (`PostToolUse` on a backgrounded Bash call) is DX-3284's.
+ * No hook event observes a background shell FINISHING (verified against the
+ * hooks reference — see the Step 0 note on DX-2954), so an open row of either
+ * kind is closed by the dispatch's own terminal write, never by inferring an
+ * end from transcript lines.
+ */
+export declare const ACTIVITY_KINDS: readonly ["agent", "bash"];
+export type ActivityKind = (typeof ACTIVITY_KINDS)[number];
+/**
+ * DX-2954 — one activity's current state, as a stats write reports it. Applied
+ * as an idempotent upsert keyed by `(dispatch, kind, activityId)`: a hook that
+ * fires twice, or a batch resent after a failed flush, must not duplicate it.
+ *
+ * `activityId` for a sub-agent is its transcript file's basename
+ * (`agent-<hash>`) — the SAME value the ledger credits its tokens under as
+ * `source`, which is how per-sub-agent tokens join to the running set without
+ * this table carrying a token column. Any future producer (DX-3284's hooks)
+ * must derive it the same way — the basename of the hook's `transcript_path`,
+ * never the hook's `agent_id` — or it upserts a duplicate row. For a
+ * background script it is the Bash call's `tool_use_id`.
+ */
+export interface ActivityChange {
+    kind: ActivityKind;
+    activityId: string;
+    /** The `agent_type` hook field; null for a background script. */
+    agentType: string | null;
+    /** The Bash call's `description`; null for a sub-agent. */
+    description: string | null;
+    startedAt: number;
+    lastActivityAt: number;
+    /** Epoch ms when it finished, or null while it is still running. */
+    finishedAt: number | null;
+}
+export interface StatsPayload {
+    entries: LedgerEntry[];
+    /**
+     * DX-2963 — the worker applied the end-of-file rule (its own row or its
+     * predecessor's is pre-card), so the dispatch inherits pre-card lineage.
+     *
+     * DX-2954 RETIRED this field (DX-3286 removes it): the cursor start order replaces the rule it
+     * carried. It is still ACCEPTED, and ignored, for exactly one release — a
+     * deploy restarts the dashboard before it relaunches the workers, so for a
+     * window old workers send it to the new server, and refusing it would throw
+     * away their terminal status. A payload carrying it records one visible
+     * `stats_field_ignored` event per dispatch. The release after this one drops
+     * the field, the `usage_pre_card_lineage` column and the two
+     * `handleReadDispatch` fields together.
+     */
+    preCardLineage?: true;
+    /**
+     * DX-2954 — this collector's cursors for every source it has opened. Optional
+     * because an old worker in the deploy window sends none; absent means
+     * "nothing to store", never "reset to 0".
+     */
+    sourceCursors?: SourceCursorReports;
+    /**
+     * DX-2954 — the running set's changes since the last write. Optional for the
+     * same deploy-window reason as {@link StatsPayload.sourceCursors}.
+     */
+    activities?: ActivityChange[];
+    /**
+     * DX-2954 — the session's own transcript file path, recorded on the
+     * dispatch's `jsonl_path`.
+     *
+     * **This is the ONE path field the stats wire carries, and the ONE exception
+     * to the card's privacy rule** that a heartbeat sends only numbers, ids,
+     * model names, the `speed` value and timestamps. It is sent once, in the
+     * first stats-bearing write, because an operator session has no other way to
+     * tell the server where its transcript lives (a worker's tracker already
+     * records it from the watcher). The strict parser below allows a path HERE
+     * and nowhere else — no other key may carry one.
+     */
+    transcriptPath?: string;
+}
+/** The dispatch's flat totals, as derived from its ledger. */
+export interface UsageTotals {
+    tokensIn: number;
+    tokensOut: number;
+    cacheRead: number;
+    /** 5-minute + 1-hour (+ any pre-card unsplit baseline) cache writes. */
+    cacheWrite: number;
+    tokensTotal: number;
+    costUsd: number;
+    turnCount: number;
+    toolCallCount: number;
+}
+/** Per-source (main / sub-agent id) credited usage. */
+export interface SourceUsage extends LedgerUsage {
+    costUsd: number;
+}
+export interface StatsResponse {
+    totals: UsageTotals;
+    bySource: Record<string, SourceUsage>;
+    /**
+     * Per sent `message_id`, the per-field total now credited for that reply
+     * across ALL dispatches — what the worker's ceiling estimate subtracts.
+     */
+    perMessage: Record<string, LedgerUsage>;
+    /**
+     * DX-2954 — the dispatch's STORED cursors after this write, per source. This
+     * is what a process takes at start to know where to read on from; an absent
+     * source key means none stored (distinct from 0).
+     */
+    sourceCursors: SourceCursors;
+    /**
+     * DX-2954 — sources whose reported `acked` was LOWER than the stored one and
+     * was therefore refused (a `cursor_regression` event was recorded for each).
+     * The rest of the write still applied. Empty on the happy path.
+     */
+    cursorRegressions: string[];
+    /** DX-2954 — running (`finished_at IS NULL`) activities after this write. */
+    runningActivities: number;
+}
+export declare function chunkEntries(entries: readonly LedgerEntry[], cap?: number): LedgerEntry[][];
+export declare class StatsPayloadError extends Error {
+}
+/**
+ * DX-2954 — cap on activity rows per stats write. The running set is bounded by
+ * how many sub-agents and background scripts one dispatch has ever started;
+ * this keeps a malformed or runaway sender from holding the dispatch lock while
+ * it upserts an unbounded list.
+ */
+export declare const ACTIVITY_BATCH_CAP = 500;
+/** DX-2954 — cap on sources per stats write, for the same reason. */
+export declare const CURSOR_BATCH_CAP = 500;
+/**
+ * DX-2954 — collapse a queue of activity changes to ONE per
+ * `(kind, activityId)`, applying the SAME merge the server's upsert applies.
+ *
+ * Both sides need this rule, so it is stated once, here, beside the wire types:
+ * the server merges an incoming row against what it has stored, and a SENDER
+ * merges the changes it has queued since its last write against each other. The
+ * two are the same operation on the same monotone fields, so a client-side
+ * collapse is lossless — the server reaches the identical row either way.
+ *
+ * Why a sender needs it at all: a producer reports an activity's full current
+ * state every time anything about it moves, and a chatty sub-agent moves its
+ * `lastActivityAt` continuously. Queuing those raw would grow one entry per
+ * change between writes, blow {@link ACTIVITY_BATCH_CAP}, and take the WHOLE
+ * stats write down with it — not merely the activity part — for a payload that
+ * describes a handful of activities.
+ *
+ * A plain last-one-wins would be WRONG here, which is why this merges field by
+ * field: `finishedAt` is `COALESCE(stored, incoming)` server-side, so a
+ * still-running report queued after a finish must not un-finish the row.
+ */
+export declare function collapseActivityChanges(changes: readonly ActivityChange[]): ActivityChange[];
+/**
+ * Strict parse of a stats body (fail loud — a malformed entry is a worker
+ * bug, never coerced). Refuses more than {@link STATS_BATCH_CAP} entries, and
+ * (DX-2954) any key outside {@link STATS_PAYLOAD_KEYS}.
+ */
+export declare function parseStatsPayload(body: unknown): StatsPayload;
+/**
+ * DX-2963 — a terminal dispatch is never written: the server refuses a stats
+ * write for one. Defined here (DB-free) so both sinks throw the SAME error —
+ * the getPool-direct writer directly, the worker client on the route's 409.
+ */
+export declare class DispatchUsageTerminalError extends Error {
+    readonly dispatchId: string;
+    readonly status: string;
+    constructor(dispatchId: string, status: string);
+}

package/dist/stats-wire.js

@@ -0,0 +1,307 @@
+/**
+ * DX-2963 — cap on entries per stats write. A from-0 backlog (a reattach, a
+ * session read from the start) is sent as consecutive capped batches, so one
+ * request never carries an unbounded body or holds the dispatch lock for an
+ * unbounded time. 500 entries is well under a second of upsert work.
+ */
+export const STATS_BATCH_CAP = 500;
+/**
+ * DX-2954 — the running set's two kinds. `agent` is a sub-agent, produced from
+ * the TRANSCRIPT: one row per sub-agent transcript file the session-log watcher
+ * discovers (`packages/danx-session-telemetry/src/activity-observer.ts`; orchestrator decision, DX-2954
+ * comment 8004). `bash` is a background script; nothing produces it yet — the
+ * hook-side producer (`PostToolUse` on a backgrounded Bash call) is DX-3284's.
+ * No hook event observes a background shell FINISHING (verified against the
+ * hooks reference — see the Step 0 note on DX-2954), so an open row of either
+ * kind is closed by the dispatch's own terminal write, never by inferring an
+ * end from transcript lines.
+ */
+export const ACTIVITY_KINDS = ["agent", "bash"];
+export function chunkEntries(entries, cap = STATS_BATCH_CAP) {
+    const out = [];
+    for (let i = 0; i < entries.length; i += cap)
+        out.push(entries.slice(i, i + cap));
+    return out;
+}
+export class StatsPayloadError extends Error {
+}
+function isNonNegInt(v) {
+    return typeof v === "number" && Number.isInteger(v) && v >= 0;
+}
+const USAGE_KEYS = ["input", "output", "cacheRead", "cacheWrite5m", "cacheWrite1h"];
+/**
+ * DX-2954 — the ONLY keys a stats body may carry. An unknown key is a 400, so
+ * a worker that invents a field (or a renamed one that never reached a
+ * consumer) fails loud instead of being silently dropped — the pre-DX-2954
+ * parser rebuilt the object field by field and swallowed every extra key.
+ *
+ * `preCardLineage` is on this list for exactly one release, until DX-3286 (see its doc on
+ * {@link StatsPayload}); `transcriptPath` is the ONE key allowed to carry a
+ * filesystem path.
+ */
+const STATS_PAYLOAD_KEYS = new Set([
+    "entries",
+    "preCardLineage",
+    "sourceCursors",
+    "activities",
+    "transcriptPath",
+]);
+/**
+ * DX-2954 — cap on activity rows per stats write. The running set is bounded by
+ * how many sub-agents and background scripts one dispatch has ever started;
+ * this keeps a malformed or runaway sender from holding the dispatch lock while
+ * it upserts an unbounded list.
+ */
+export const ACTIVITY_BATCH_CAP = 500;
+/** DX-2954 — cap on sources per stats write, for the same reason. */
+export const CURSOR_BATCH_CAP = 500;
+/**
+ * DX-2954 — collapse a queue of activity changes to ONE per
+ * `(kind, activityId)`, applying the SAME merge the server's upsert applies.
+ *
+ * Both sides need this rule, so it is stated once, here, beside the wire types:
+ * the server merges an incoming row against what it has stored, and a SENDER
+ * merges the changes it has queued since its last write against each other. The
+ * two are the same operation on the same monotone fields, so a client-side
+ * collapse is lossless — the server reaches the identical row either way.
+ *
+ * Why a sender needs it at all: a producer reports an activity's full current
+ * state every time anything about it moves, and a chatty sub-agent moves its
+ * `lastActivityAt` continuously. Queuing those raw would grow one entry per
+ * change between writes, blow {@link ACTIVITY_BATCH_CAP}, and take the WHOLE
+ * stats write down with it — not merely the activity part — for a payload that
+ * describes a handful of activities.
+ *
+ * A plain last-one-wins would be WRONG here, which is why this merges field by
+ * field: `finishedAt` is `COALESCE(stored, incoming)` server-side, so a
+ * still-running report queued after a finish must not un-finish the row.
+ */
+export function collapseActivityChanges(changes) {
+    const byKey = new Map();
+    for (const c of changes) {
+        // NUL separator: neither a kind (a fixed enum) nor an activity id (a
+        // transcript basename or a tool-use id) can contain one, so no pair of
+        // distinct keys can collide into one string.
+        const key = `${c.kind}\u0000${c.activityId}`;
+        const prior = byKey.get(key);
+        if (prior === undefined) {
+            byKey.set(key, { ...c });
+            continue;
+        }
+        byKey.set(key, {
+            kind: c.kind,
+            activityId: c.activityId,
+            // COALESCE(incoming, stored) — a later report may FILL one in, never erase
+            // it (a Bash launch knows the description, a sub-agent stop knows the type;
+            // neither knows the other's).
+            agentType: c.agentType ?? prior.agentType,
+            description: c.description ?? prior.description,
+            // LEAST — a start never moves later.
+            startedAt: Math.min(prior.startedAt, c.startedAt),
+            // GREATEST — liveness never moves backwards.
+            lastActivityAt: Math.max(prior.lastActivityAt, c.lastActivityAt),
+            // COALESCE(stored, incoming) — the FIRST finish wins; a later
+            // still-running report must never resurrect a stopped activity.
+            finishedAt: prior.finishedAt ?? c.finishedAt,
+        });
+    }
+    return [...byKey.values()];
+}
+const CURSOR_KEYS = new Set(["acked", "delivered", "pastEof"]);
+const PAST_EOF_KEYS = new Set(["storedOffset", "fileSize"]);
+function parsePastEof(raw, where) {
+    if (!raw || typeof raw !== "object")
+        throw new StatsPayloadError(where);
+    const p = raw;
+    for (const k of Object.keys(p)) {
+        if (!PAST_EOF_KEYS.has(k))
+            throw new StatsPayloadError(`${where}.${k} is not a pastEof field`);
+    }
+    if (!isNonNegInt(p.storedOffset))
+        throw new StatsPayloadError(`${where}.storedOffset`);
+    if (!isNonNegInt(p.fileSize))
+        throw new StatsPayloadError(`${where}.fileSize`);
+    return { storedOffset: p.storedOffset, fileSize: p.fileSize };
+}
+function parseSourceCursors(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new StatsPayloadError("sourceCursors must be an object");
+    }
+    const entries = Object.entries(raw);
+    if (entries.length > CURSOR_BATCH_CAP) {
+        throw new StatsPayloadError(`sourceCursors exceeds the cap of ${CURSOR_BATCH_CAP}`);
+    }
+    const out = {};
+    for (const [source, value] of entries) {
+        if (!source)
+            throw new StatsPayloadError("sourceCursors key must be a non-empty source");
+        if (!value || typeof value !== "object") {
+            throw new StatsPayloadError(`sourceCursors[${source}] must be an object`);
+        }
+        const c = value;
+        for (const k of Object.keys(c)) {
+            if (!CURSOR_KEYS.has(k)) {
+                throw new StatsPayloadError(`sourceCursors[${source}].${k} is not a cursor field`);
+            }
+        }
+        if (!isNonNegInt(c.acked))
+            throw new StatsPayloadError(`sourceCursors[${source}].acked`);
+        if (!isNonNegInt(c.delivered))
+            throw new StatsPayloadError(`sourceCursors[${source}].delivered`);
+        // `delivered` is the highest line HANDED ON, `acked` the highest
+        // ACKNOWLEDGED — acknowledging a line necessarily means it was handed on
+        // first, so delivered < acked is structurally impossible and a sender bug.
+        if (c.delivered < c.acked) {
+            throw new StatsPayloadError(`sourceCursors[${source}]: delivered (${c.delivered}) is behind acked (${c.acked})`);
+        }
+        const report = { acked: c.acked, delivered: c.delivered };
+        if (c.pastEof !== undefined) {
+            report.pastEof = parsePastEof(c.pastEof, `sourceCursors[${source}].pastEof`);
+        }
+        out[source] = report;
+    }
+    return out;
+}
+const ACTIVITY_KEYS = new Set([
+    "kind",
+    "activityId",
+    "agentType",
+    "description",
+    "startedAt",
+    "lastActivityAt",
+    "finishedAt",
+]);
+function parseActivities(raw) {
+    if (!Array.isArray(raw))
+        throw new StatsPayloadError("activities must be an array");
+    if (raw.length > ACTIVITY_BATCH_CAP) {
+        throw new StatsPayloadError(`activities exceeds the cap of ${ACTIVITY_BATCH_CAP}`);
+    }
+    return raw.map((entry, i) => {
+        const where = `activities[${i}]`;
+        if (!entry || typeof entry !== "object")
+            throw new StatsPayloadError(where);
+        const a = entry;
+        for (const k of Object.keys(a)) {
+            if (!ACTIVITY_KEYS.has(k))
+                throw new StatsPayloadError(`${where}.${k} is not an activity field`);
+        }
+        if (typeof a.kind !== "string" || !ACTIVITY_KINDS.includes(a.kind)) {
+            throw new StatsPayloadError(`${where}.kind must be one of ${ACTIVITY_KINDS.join(", ")}`);
+        }
+        if (typeof a.activityId !== "string" || !a.activityId) {
+            throw new StatsPayloadError(`${where}.activityId`);
+        }
+        if (a.agentType !== null && typeof a.agentType !== "string") {
+            throw new StatsPayloadError(`${where}.agentType`);
+        }
+        if (a.description !== null && typeof a.description !== "string") {
+            throw new StatsPayloadError(`${where}.description`);
+        }
+        if (!isNonNegInt(a.startedAt))
+            throw new StatsPayloadError(`${where}.startedAt`);
+        if (!isNonNegInt(a.lastActivityAt))
+            throw new StatsPayloadError(`${where}.lastActivityAt`);
+        if (a.finishedAt !== null && !isNonNegInt(a.finishedAt)) {
+            throw new StatsPayloadError(`${where}.finishedAt`);
+        }
+        return {
+            kind: a.kind,
+            activityId: a.activityId,
+            agentType: a.agentType,
+            description: a.description,
+            startedAt: a.startedAt,
+            lastActivityAt: a.lastActivityAt,
+            finishedAt: a.finishedAt,
+        };
+    });
+}
+/**
+ * Strict parse of a stats body (fail loud — a malformed entry is a worker
+ * bug, never coerced). Refuses more than {@link STATS_BATCH_CAP} entries, and
+ * (DX-2954) any key outside {@link STATS_PAYLOAD_KEYS}.
+ */
+export function parseStatsPayload(body) {
+    if (!body || typeof body !== "object")
+        throw new StatsPayloadError("body must be an object");
+    const b = body;
+    const unknown = Object.keys(b).filter((k) => !STATS_PAYLOAD_KEYS.has(k));
+    if (unknown.length > 0) {
+        throw new StatsPayloadError(`unknown field(s): ${unknown.join(", ")} — allowed: ${[...STATS_PAYLOAD_KEYS].join(", ")}`);
+    }
+    if (!Array.isArray(b.entries))
+        throw new StatsPayloadError("entries must be an array");
+    if (b.entries.length > STATS_BATCH_CAP) {
+        throw new StatsPayloadError(`entries exceeds the cap of ${STATS_BATCH_CAP}`);
+    }
+    if (b.preCardLineage !== undefined && b.preCardLineage !== true) {
+        throw new StatsPayloadError("preCardLineage must be true when present");
+    }
+    if (b.transcriptPath !== undefined && (typeof b.transcriptPath !== "string" || !b.transcriptPath)) {
+        throw new StatsPayloadError("transcriptPath must be a non-empty string when present");
+    }
+    const entries = b.entries.map((raw, i) => {
+        const e = raw;
+        const where = `entries[${i}]`;
+        if (typeof e.messageId !== "string" || !e.messageId)
+            throw new StatsPayloadError(`${where}.messageId`);
+        if (typeof e.source !== "string" || !e.source)
+            throw new StatsPayloadError(`${where}.source`);
+        if (e.model !== null && typeof e.model !== "string")
+            throw new StatsPayloadError(`${where}.model`);
+        if (typeof e.speed !== "string" || !e.speed)
+            throw new StatsPayloadError(`${where}.speed`);
+        if (!isNonNegInt(e.repliedAt))
+            throw new StatsPayloadError(`${where}.repliedAt`);
+        const u = e.usage;
+        if (!u || typeof u !== "object")
+            throw new StatsPayloadError(`${where}.usage`);
+        for (const k of USAGE_KEYS) {
+            if (!isNonNegInt(u[k]))
+                throw new StatsPayloadError(`${where}.usage.${k}`);
+        }
+        if (!Array.isArray(e.toolUseIds) || e.toolUseIds.some((t) => typeof t !== "string")) {
+            throw new StatsPayloadError(`${where}.toolUseIds`);
+        }
+        return {
+            messageId: e.messageId,
+            source: e.source,
+            model: e.model,
+            speed: e.speed,
+            repliedAt: e.repliedAt,
+            usage: {
+                input: u.input,
+                output: u.output,
+                cacheRead: u.cacheRead,
+                cacheWrite5m: u.cacheWrite5m,
+                cacheWrite1h: u.cacheWrite1h,
+            },
+            toolUseIds: e.toolUseIds,
+        };
+    });
+    const payload = { entries };
+    if (b.preCardLineage === true)
+        payload.preCardLineage = true;
+    if (b.sourceCursors !== undefined)
+        payload.sourceCursors = parseSourceCursors(b.sourceCursors);
+    if (b.activities !== undefined)
+        payload.activities = parseActivities(b.activities);
+    if (b.transcriptPath !== undefined)
+        payload.transcriptPath = b.transcriptPath;
+    return payload;
+}
+/**
+ * DX-2963 — a terminal dispatch is never written: the server refuses a stats
+ * write for one. Defined here (DB-free) so both sinks throw the SAME error —
+ * the getPool-direct writer directly, the worker client on the route's 409.
+ */
+export class DispatchUsageTerminalError extends Error {
+    dispatchId;
+    status;
+    constructor(dispatchId, status) {
+        super(`usage ledger: dispatch ${dispatchId} is terminal (${status}) — a terminal dispatch is never written`);
+        this.dispatchId = dispatchId;
+        this.status = status;
+        this.name = "DispatchUsageTerminalError";
+    }
+}

package/dist/usage-ledger.js

@@ -32,7 +32,7 @@ export function isSyntheticMessageKey(key) {
  * 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`, `usage-ledger-wire.ts`) REQUIRES an
+ * (`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 —

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,6 @@
 {
   "name": "@thehammer/danx-session-telemetry",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "Shared Claude Code transcript collector (DX-2962) — incremental JSONL tailing for the danxbot worker and the danx-dashboard-mcp desktop bridge, so both run identical collector code.",
   "license": "MIT",
   "type": "module",