@thehammer/danx-session-telemetry 0.1.6 → 0.1.9

package/dist/browser.d.ts

@@ -14,9 +14,12 @@
  * dashboard SPA, a future browser-side usage display) can depend on this
  * subpath with zero risk of pulling in a Node builtin.
  *
- * DX-2963 adds the first real runtime export here: the one usage counter
- * and the pricing function, both pure arithmetic with no I/O. This card
- * (DX-2962) only creates the subpath and its no-`node:`-imports guarantee.
+ * DX-2963 adds the first real runtime exports here: the one usage counter
+ * (`usage-ledger.ts`) and the one pricing function (`pricing.ts`), both pure
+ * arithmetic with no I/O — `usage-snapshot.ts` in danxbot root (bundled by the
+ * frozen Vue SPA) imports through THIS subpath, never the main entry.
  */
 export type { AgentLogEntry, AgentLineage } from "./types.js";
 export { truncStr } from "./tool-summary.js";
+export * from "./usage-ledger.js";
+export * from "./pricing.js";

package/dist/browser.js

@@ -1,3 +1,6 @@
 // `truncStr` is pure string arithmetic (no `node:` imports, no I/O) — safe
 // to carry on the browser subpath alongside the two types above.
 export { truncStr } from "./tool-summary.js";
+// DX-2963 — counter + pricing (pure arithmetic, no `node:` imports).
+export * from "./usage-ledger.js";
+export * from "./pricing.js";

package/dist/index.d.ts

@@ -18,3 +18,5 @@ export { SessionLogWatcher, DISPATCH_TAG_PREFIX, encodeClaudeProjectsCwd, derive
 export type { EntryConsumer, SessionLogWatcherOptions, } from "./session-log-watcher.js";
 export type { AgentLogEntry, AgentLineage } from "./types.js";
 export { truncStr, summarizeToolInput, buildAssistantSummary, buildToolResultSummary, } from "./tool-summary.js";
+export * from "./usage-ledger.js";
+export * from "./pricing.js";

package/dist/index.js

@@ -21,3 +21,7 @@ export { SessionLogWatcher, DISPATCH_TAG_PREFIX, encodeClaudeProjectsCwd, derive
 // truncate a string for display but have nothing else to do with the
 // transcript collector, e.g. `src/dashboard/dispatch-scout.ts`.
 export { truncStr, summarizeToolInput, buildAssistantSummary, buildToolResultSummary, } from "./tool-summary.js";
+// DX-2963 — the one usage counter and the one pricing function (also on the
+// browser-safe `./browser` subpath; both are pure arithmetic).
+export * from "./usage-ledger.js";
+export * from "./pricing.js";

package/dist/pricing.d.ts

@@ -0,0 +1,93 @@
+/**
+ * DX-2963 — the ONE pricing function, shared by every consumer that turns
+ * token counts into dollars: the danxbot server's usage-ledger writer (which
+ * prices each credit once, when it is credited), the router's Haiku calls and
+ * the skill-eval cost report. Moved here from danxbot root `src/agent/pricing.ts`
+ * so the counter and the price list live side by side, and exported through
+ * the browser-safe `./browser` subpath (pure arithmetic, no `node:` imports).
+ *
+ * Source of every row: Anthropic's official pricing page,
+ * https://platform.claude.com/docs/en/about-claude/pricing — read 2026-09-23
+ * (DX-2963 re-checked every row against it; the previous list had drifted:
+ * Sonnet 5 at $3/$15 and Haiku 4.5 at $0.80/$4 where the page says $2/$10 and
+ * $1/$5, and Opus 5 / Fable 5.1 / Opus 5.5 were missing).
+ *
+ * DX-3261 — re-checked the WHOLE table row-by-row against the same page
+ * again, 2026-09-24, https://platform.claude.com/docs/en/about-claude/pricing
+ * (the "Model pricing" table). Found: `claude-opus-4-7` and `claude-opus-4-5`
+ * were both missing (page: $5 in / $25 out / $0.50 cache hit, same row shape
+ * as Opus 4.8 / Opus 4.6 — added below). Every other standard-speed row
+ * matched exactly: Fable 5.1 ($10/$50, 0.025x hit), Fable 5 ($10/$50, hit
+ * $1), Opus 5.5 ($4/$20, 0.05x hit), Opus 5 / Opus 4.8 / Opus 4.6 ($5/$25,
+ * $0.50 hit), Opus 4 retired ($15/$75, $1.50 hit), Sonnet 5 ($2/$10, $0.20
+ * hit), Sonnet 4.6 / Sonnet 4.5 / Sonnet 4 ($3/$15, $0.30 hit), Haiku 4.5
+ * ($1/$5, $0.10 hit), and the derived 1.25x/2h cache-write multipliers on
+ * every row. Fast-mode rows unchanged: Opus 5.5 ($8/$40), Opus 5 / Opus 4.8
+ * ($10/$50) — Opus 4.7 fast mode returns an error per the page (never
+ * priced), and Opus 4.6 fast mode is handled separately below (the page
+ * states it runs at standard speed, billed at standard rates — not an
+ * unpriced fast row). Claude Mythos 5.1/5 (limited-availability, same rates
+ * as their Fable counterparts) and the two retired-elsewhere rows (Opus 4.1,
+ * Haiku 3.5) are not in Claude Code's own model-tag surface and are left out
+ * on the same basis the table already excludes them.
+ *
+ * DX-2963 — cache writes are TWO prices, never one: a 5-minute write is
+ * 1.25x base input and a 1-hour write is 2x base input. Claude Code reports
+ * each lifetime separately (`usage.cache_creation.ephemeral_5m_input_tokens` /
+ * `ephemeral_1h_input_tokens`), and both are material (top-level transcripts
+ * write almost only 1-hour, sub-agent transcripts mostly 5-minute), so each
+ * field is priced with its own price.
+ */
+/** Price per MILLION tokens, USD. */
+export interface ModelPrice {
+    input: number;
+    output: number;
+    cacheWrite5m: number;
+    cacheWrite1h: number;
+    cacheRead: number;
+}
+/** Token counts for one priced unit (a ledger credit, a model bucket, a call). */
+export interface PricedTokens {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite5m: number;
+    cacheWrite1h: number;
+}
+/**
+ * Claude Code's literal model tag on an API-error entry (rate limit, context
+ * overflow). Its tokens count in a dispatch's flat totals but it is never a
+ * real priced model, so it never enters `usage_by_model` or cost.
+ */
+export declare const SYNTHETIC_MODEL = "<synthetic>";
+/** The `usage.speed` value a fast-mode reply carries. */
+export declare const FAST_SPEED = "fast";
+export type PriceResult = {
+    kind: "priced";
+    costUsd: number;
+} | {
+    kind: "unpriced";
+    model: string;
+    speed: string;
+};
+/**
+ * Price one unit of usage. NEVER throws (DX-2963 replaces DX-1720's throw):
+ * an unknown model — or a fast reply on a model with no fast price — returns
+ * `{kind: "unpriced"}` so the caller counts the tokens, leaves the cost out
+ * and records a visible `unpriced_model` event, instead of one new model id
+ * failing every write (the live tick used to fail every 30 seconds on it).
+ * `<synthetic>` is never passed here: callers exclude it before pricing.
+ *
+ * DX-3261 — both tables are looked up with `Object.hasOwn`, never bracket
+ * access + truthiness (`table[model]`): a model id that collides with an
+ * inherited `Object.prototype` key (`"toString"`, `"constructor"`, …) would
+ * otherwise resolve to that inherited FUNCTION — truthy, so the `!p` guard
+ * never fires — and every subsequent `p.input` / `p.output` / … reads
+ * `undefined` off it, so the whole cost total becomes `NaN`. `Object.hasOwn`
+ * answers "does the row itself have this key" and can never be fooled by
+ * the prototype chain, so an unpriced model always returns `unpriced`
+ * cleanly, whatever its id looks like.
+ */
+export declare function priceUsage(model: string, speed: string, tokens: PricedTokens): PriceResult;
+/** True when `model` has a standard-speed price (used by tests + guards). */
+export declare function isPricedModel(model: string): boolean;

package/dist/pricing.js

@@ -0,0 +1,157 @@
+/**
+ * DX-2963 — the ONE pricing function, shared by every consumer that turns
+ * token counts into dollars: the danxbot server's usage-ledger writer (which
+ * prices each credit once, when it is credited), the router's Haiku calls and
+ * the skill-eval cost report. Moved here from danxbot root `src/agent/pricing.ts`
+ * so the counter and the price list live side by side, and exported through
+ * the browser-safe `./browser` subpath (pure arithmetic, no `node:` imports).
+ *
+ * Source of every row: Anthropic's official pricing page,
+ * https://platform.claude.com/docs/en/about-claude/pricing — read 2026-09-23
+ * (DX-2963 re-checked every row against it; the previous list had drifted:
+ * Sonnet 5 at $3/$15 and Haiku 4.5 at $0.80/$4 where the page says $2/$10 and
+ * $1/$5, and Opus 5 / Fable 5.1 / Opus 5.5 were missing).
+ *
+ * DX-3261 — re-checked the WHOLE table row-by-row against the same page
+ * again, 2026-09-24, https://platform.claude.com/docs/en/about-claude/pricing
+ * (the "Model pricing" table). Found: `claude-opus-4-7` and `claude-opus-4-5`
+ * were both missing (page: $5 in / $25 out / $0.50 cache hit, same row shape
+ * as Opus 4.8 / Opus 4.6 — added below). Every other standard-speed row
+ * matched exactly: Fable 5.1 ($10/$50, 0.025x hit), Fable 5 ($10/$50, hit
+ * $1), Opus 5.5 ($4/$20, 0.05x hit), Opus 5 / Opus 4.8 / Opus 4.6 ($5/$25,
+ * $0.50 hit), Opus 4 retired ($15/$75, $1.50 hit), Sonnet 5 ($2/$10, $0.20
+ * hit), Sonnet 4.6 / Sonnet 4.5 / Sonnet 4 ($3/$15, $0.30 hit), Haiku 4.5
+ * ($1/$5, $0.10 hit), and the derived 1.25x/2h cache-write multipliers on
+ * every row. Fast-mode rows unchanged: Opus 5.5 ($8/$40), Opus 5 / Opus 4.8
+ * ($10/$50) — Opus 4.7 fast mode returns an error per the page (never
+ * priced), and Opus 4.6 fast mode is handled separately below (the page
+ * states it runs at standard speed, billed at standard rates — not an
+ * unpriced fast row). Claude Mythos 5.1/5 (limited-availability, same rates
+ * as their Fable counterparts) and the two retired-elsewhere rows (Opus 4.1,
+ * Haiku 3.5) are not in Claude Code's own model-tag surface and are left out
+ * on the same basis the table already excludes them.
+ *
+ * DX-2963 — cache writes are TWO prices, never one: a 5-minute write is
+ * 1.25x base input and a 1-hour write is 2x base input. Claude Code reports
+ * each lifetime separately (`usage.cache_creation.ephemeral_5m_input_tokens` /
+ * `ephemeral_1h_input_tokens`), and both are material (top-level transcripts
+ * write almost only 1-hour, sub-agent transcripts mostly 5-minute), so each
+ * field is priced with its own price.
+ */
+/**
+ * Claude Code's literal model tag on an API-error entry (rate limit, context
+ * overflow). Its tokens count in a dispatch's flat totals but it is never a
+ * real priced model, so it never enters `usage_by_model` or cost.
+ */
+export const SYNTHETIC_MODEL = "<synthetic>";
+/** The `usage.speed` value a fast-mode reply carries. */
+export const FAST_SPEED = "fast";
+/**
+ * Build a row from base input/output with the page's caching multipliers
+ * (5m write 1.25x, 1h write 2x) and an explicit cache-hit price — the hit
+ * multiplier differs per model (0.1x standard, 0.025x Fable 5.1, 0.05x
+ * Opus 5.5), so it is stated per row rather than derived.
+ */
+function price(input, output, cacheRead) {
+    return {
+        input,
+        output,
+        cacheWrite5m: input * 1.25,
+        cacheWrite1h: input * 2,
+        cacheRead,
+    };
+}
+/** Standard-speed prices, keyed by the model id Claude Code writes in the JSONL. */
+const PRICING = {
+    // Claude Fable 5.1 — cache hits at 0.025x input ($0.25).
+    "claude-fable-5-1": price(10, 50, 0.25),
+    "claude-fable-5": price(10, 50, 1),
+    // Claude Opus 5.5 — cache hits at 0.05x input ($0.20).
+    "claude-opus-5-5": price(4, 20, 0.2),
+    "claude-opus-5": price(5, 25, 0.5),
+    "claude-opus-4-8": price(5, 25, 0.5),
+    "claude-opus-4-7": price(5, 25, 0.5),
+    "claude-opus-4-6": price(5, 25, 0.5),
+    "claude-opus-4-6-20250916": price(5, 25, 0.5),
+    "claude-opus-4-5": price(5, 25, 0.5),
+    "claude-opus-4-20250514": price(15, 75, 1.5),
+    "claude-sonnet-5": price(2, 10, 0.2),
+    "claude-sonnet-4-6": price(3, 15, 0.3),
+    "claude-sonnet-4-5-20250929": price(3, 15, 0.3),
+    "claude-sonnet-4-20250514": price(3, 15, 0.3),
+    "claude-haiku-4-5": price(1, 5, 0.1),
+    "claude-haiku-4-5-20251001": price(1, 5, 0.1),
+};
+/**
+ * Fast-mode prices (the page's "Fast mode pricing" section): premium
+ * input/output with the prompt-caching multipliers applied ON TOP (so a 5m
+ * write is 1.25x and a 1h write 2x of the fast input price, a hit 0.1x — the
+ * page states Opus 5.5's own 0.05x hit multiplier only for standard speed and
+ * says caching multipliers stack, so its fast hit is 0.05x of $8).
+ *
+ * DX-2963: the card names Opus 5 and Opus 4.8; the page re-read on
+ * 2026-09-23 also lists Opus 5.5 ($8 / $40), so it is priced too. A fast
+ * reply on any model NOT in this table is unpriced (tokens count, cost left
+ * out, a visible `unpriced_model` event) — never priced at the standard rate.
+ */
+const FAST_PRICING = {
+    "claude-opus-5-5": price(8, 40, 0.4),
+    "claude-opus-5": price(10, 50, 1),
+    "claude-opus-4-8": price(10, 50, 1),
+};
+/**
+ * DX-3261 — models whose `speed:"fast"` requests are billed at STANDARD
+ * rates, per the page's "Fast mode pricing" section: *"Fast mode is not
+ * available on Claude Opus 4.7 (requests with `speed: "fast"` return an
+ * error) or Claude Opus 4.6 (requests run at standard speed and are billed
+ * at standard rates)."* Opus 4.7 correctly falls through to `unpriced` below
+ * (it has no row in either table — matches the page's "returns an error").
+ * Opus 4.6 does NOT: DX-2963's own wording sent it down the same unpriced
+ * path as Opus 4.7, contradicting the page it pins — a fast-mode Opus 4.6
+ * reply silently lost its cost. The page wins: look it up in the STANDARD
+ * table instead of `unpriced`, never invent a separate fast row for it.
+ */
+const FAST_BILLS_AT_STANDARD_RATE = new Set([
+    "claude-opus-4-6",
+    "claude-opus-4-6-20250916",
+]);
+/**
+ * Price one unit of usage. NEVER throws (DX-2963 replaces DX-1720's throw):
+ * an unknown model — or a fast reply on a model with no fast price — returns
+ * `{kind: "unpriced"}` so the caller counts the tokens, leaves the cost out
+ * and records a visible `unpriced_model` event, instead of one new model id
+ * failing every write (the live tick used to fail every 30 seconds on it).
+ * `<synthetic>` is never passed here: callers exclude it before pricing.
+ *
+ * DX-3261 — both tables are looked up with `Object.hasOwn`, never bracket
+ * access + truthiness (`table[model]`): a model id that collides with an
+ * inherited `Object.prototype` key (`"toString"`, `"constructor"`, …) would
+ * otherwise resolve to that inherited FUNCTION — truthy, so the `!p` guard
+ * never fires — and every subsequent `p.input` / `p.output` / … reads
+ * `undefined` off it, so the whole cost total becomes `NaN`. `Object.hasOwn`
+ * answers "does the row itself have this key" and can never be fooled by
+ * the prototype chain, so an unpriced model always returns `unpriced`
+ * cleanly, whatever its id looks like.
+ */
+export function priceUsage(model, speed, tokens) {
+    const useFastTable = speed === FAST_SPEED && !FAST_BILLS_AT_STANDARD_RATE.has(model);
+    const table = useFastTable ? FAST_PRICING : PRICING;
+    if (!Object.hasOwn(table, model))
+        return { kind: "unpriced", model, speed };
+    const p = table[model];
+    return {
+        kind: "priced",
+        costUsd: (tokens.input * p.input +
+            tokens.output * p.output +
+            tokens.cacheRead * p.cacheRead +
+            tokens.cacheWrite5m * p.cacheWrite5m +
+            tokens.cacheWrite1h * p.cacheWrite1h) /
+            1_000_000,
+    };
+}
+/** True when `model` has a standard-speed price (used by tests + guards). */
+export function isPricedModel(model) {
+    // DX-3261 — `in` walks the prototype chain (`"toString" in {}` is `true`);
+    // `Object.hasOwn` can't be fooled by it. See `priceUsage`'s own comment.
+    return Object.hasOwn(PRICING, model);
+}

package/dist/session-log-watcher.d.ts

@@ -61,6 +61,17 @@ export interface SessionLogWatcherOptions {
      * EOF is 0, so it ingests its own full file from the start.
      */
     fromEof?: boolean;
+    /**
+     * DX-2963 — the end-of-file rule for PRE-CARD lineage. When set, every
+     * sub-agent file that ALREADY EXISTS on the first sub-agent discovery pass
+     * is opened at its end (like the main file under `fromEof`); a sub-agent
+     * file that appears later is read from byte 0. Set by the worker when its
+     * own dispatch row, or its predecessor's, is pre-card (stored totals with
+     * no ledger rows to dedupe against), so replies those totals already count
+     * are never credited again. DX-2954 replaces this with its cursor start
+     * order and deletes it.
+     */
+    existingSubagentFilesFromEof?: boolean;
 }
 /**
  * Encode a working directory to the subdir name Claude Code writes JSONL
@@ -186,6 +197,8 @@ export declare class SessionLogWatcher {
     private dispatchId;
     private pollIntervalMs;
     private fromEof;
+    private existingSubagentFilesFromEof;
+    private subagentDiscoveryDone;
     private running;
     private polling;
     private initSynthesized;

package/dist/session-log-watcher.js

@@ -424,6 +424,8 @@ export class SessionLogWatcher {
     dispatchId;
     pollIntervalMs;
     fromEof;
+    existingSubagentFilesFromEof;
+    subagentDiscoveryDone = false;
     running = false;
     polling = false;
     // DX-2962: entries are NOT accumulated here — see `emitEntry`. Only
@@ -439,6 +441,8 @@ export class SessionLogWatcher {
         this.dispatchId = options.dispatchId;
         this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
         this.fromEof = options.fromEof ?? false;
+        this.existingSubagentFilesFromEof =
+            options.existingSubagentFilesFromEof ?? false;
     }
     /** Register a consumer callback that receives each new AgentLogEntry. */
     onEntry(consumer) {
@@ -577,6 +581,7 @@ export class SessionLogWatcher {
             filePath,
             byteOffset,
             lineBuffer: "",
+            lineBufferStartOffset: byteOffset,
             lastTimestamp: 0,
         };
         this.subagentsDir = join(dirname(filePath), basename(filePath, ".jsonl"), "subagents");
@@ -680,6 +685,10 @@ export class SessionLogWatcher {
             log.error("Failed to enumerate sub-agent directory:", err);
             return;
         }
+        // DX-2963 — the FIRST discovery pass sees exactly the sub-agent files
+        // that existed when this watcher attached; only those may open at EOF.
+        const openExistingAtEof = this.existingSubagentFilesFromEof && !this.subagentDiscoveryDone;
+        this.subagentDiscoveryDone = true;
         for (const file of files) {
             if (!file.endsWith(".jsonl"))
                 continue;
@@ -688,9 +697,19 @@ export class SessionLogWatcher {
                 continue;
             const subagentId = basename(file, ".jsonl");
             const agentType = await this.readAgentType(subagentId);
+            let startOffset = 0;
+            if (openExistingAtEof) {
+                try {
+                    startOffset = (await stat(fullPath)).size;
+                }
+                catch (err) {
+                    log.warn(`existingSubagentFilesFromEof: stat failed for ${fullPath}; tailing from 0: ${String(err)}`);
+                }
+            }
             this.subagentTails.set(fullPath, {
                 filePath: fullPath,
-                byteOffset: 0,
+                byteOffset: startOffset,
+                lineBufferStartOffset: startOffset,
                 lineBuffer: "",
                 lastTimestamp: 0,
                 lineage: {
@@ -759,13 +778,16 @@ export class SessionLogWatcher {
         state.lineBuffer += text;
         let newlineIdx;
         while ((newlineIdx = state.lineBuffer.indexOf("\n")) !== -1) {
-            const line = state.lineBuffer.substring(0, newlineIdx).trim();
+            const rawLine = state.lineBuffer.substring(0, newlineIdx);
+            const lineStart = state.lineBufferStartOffset;
+            state.lineBufferStartOffset += Buffer.byteLength(rawLine, "utf-8") + 1;
+            const line = rawLine.trim();
             state.lineBuffer = state.lineBuffer.substring(newlineIdx + 1);
             if (!line)
                 continue;
             try {
                 const raw = JSON.parse(line);
-                this.handleRawEntry(raw, state);
+                this.handleRawEntry(raw, state, lineStart);
             }
             catch {
                 log.warn(`Skipping malformed JSONL line: ${line.substring(0, 100)}`);
@@ -795,7 +817,7 @@ export class SessionLogWatcher {
      * skill/agent set. The pre-launch probe in `mcp-server-probe.ts` is the
      * tool-registration check that works across both runtimes.
      */
-    handleRawEntry(raw, state) {
+    handleRawEntry(raw, state, lineStart) {
         const isSubagent = state.lineage !== undefined;
         if (!isSubagent && !this.initSynthesized && raw.type === "assistant") {
             const message = raw.message;
@@ -835,6 +857,8 @@ export class SessionLogWatcher {
                 this.parentSessionId = sid;
         }
         state.lastTimestamp = result.timestamp;
+        // DX-2963 — the line's own byte offset (see `TailState.lineBufferStartOffset`).
+        result.entry.data = { ...result.entry.data, byte_offset: lineStart };
         this.emitEntry(result.entry, state);
     }
     /**

package/dist/usage-ledger.d.ts

@@ -0,0 +1,141 @@
+/**
+ * DX-2963 — the ONE usage counter. Turns Claude Code transcript lines into
+ * per-reply usage-ledger entries; every counter in danxbot (the worker's
+ * accumulator, the skill-eval probe, the stall sweep's productivity signal,
+ * the cross-consumer tests) uses it instead of its own summing.
+ *
+ * The rule it implements, measured on real transcripts (DX-2963 card,
+ * 2026-09-18): Claude Code writes one assistant reply as SEVERAL lines that
+ * share a `message.id`, and the later lines carry the real (larger) usage —
+ * the last line held the maximum in 28,121 of 28,124 multi-line replies. A
+ * reply's usage is therefore the per-FIELD MAXIMUM over its lines, never its
+ * first line (the old rule every counter shared, which undercounted output
+ * 3.17x on sub-agent transcripts) and never a sum (which over-counts).
+ * Far-later repeats of a `message.id` are replays of re-written history and
+ * never raise usage, so a max-based counter credits them nothing for free.
+ *
+ * Pure arithmetic — no `node:` imports — so it is exported through the
+ * browser-safe `./browser` subpath as well as the main entry.
+ */
+import type { PricedTokens } from "./pricing.js";
+import type { AgentLogEntry } from "./types.js";
+/** Per-reply usage, both cache-write lifetimes kept apart (priced apart). */
+export type LedgerUsage = PricedTokens;
+/**
+ * One reply's ledger entry as the collector reports it: the per-field
+ * MAXIMUM usage seen over the reply's lines so far, plus every `tool_use`
+ * id seen in it.
+ */
+export interface LedgerEntry {
+    /** `message.id`, or the synthetic `nomsg:<source>:<byteOffset>` key. */
+    messageId: string;
+    /** `"main"` for the dispatch's own transcript, else the sub-agent id. */
+    source: string;
+    /** First non-empty `message.model` seen for the reply; `null` if none. */
+    model: string | null;
+    /** `usage.speed` (`standard` / `fast`); `"standard"` when the line has none. */
+    speed: string;
+    usage: LedgerUsage;
+    /** The reply's own transcript timestamp (its FIRST line's), epoch ms. */
+    repliedAt: number;
+    toolUseIds: string[];
+}
+/** The fields of one assistant line the counter needs. */
+export interface LedgerLine {
+    messageId: string | undefined;
+    source: string;
+    /** Byte offset of the line's first byte in its file — keys a line with no id. */
+    byteOffset: number;
+    model: string | undefined;
+    /** The line's raw `message.usage` block, if it carries one. */
+    usage: Record<string, unknown> | undefined;
+    /** The line's transcript timestamp, epoch ms. */
+    timestamp: number;
+    /** `tool_use` block ids on this line. */
+    toolUseIds: readonly string[];
+}
+export declare 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 declare 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 declare function syntheticMessageKey(source: string, byteOffset: number): string;
+export declare function isSyntheticMessageKey(key: string): boolean;
+/**
+ * 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 declare function parseUsageBlock(raw: Record<string, unknown>): LedgerUsage;
+export declare function zeroUsage(): LedgerUsage;
+export declare const LEDGER_USAGE_FIELDS: readonly ["input", "output", "cacheRead", "cacheWrite5m", "cacheWrite1h"];
+export declare function maxUsage(a: LedgerUsage, b: LedgerUsage): LedgerUsage;
+export declare function addUsage(a: LedgerUsage, b: LedgerUsage): LedgerUsage;
+/** Per-field `max(0, a - b)`. */
+export declare function excessUsage(a: LedgerUsage, b: LedgerUsage): LedgerUsage;
+export declare function isZeroUsage(u: LedgerUsage): boolean;
+/** Window tokens: input + output + both cache writes (the account-window unit). */
+export declare function windowTokensOfUsage(u: LedgerUsage): number;
+/** All five fields summed. */
+export declare function totalTokensOfUsage(u: LedgerUsage): number;
+/**
+ * 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 declare class UsageLedgerCounter {
+    private readonly entries;
+    private readonly changed;
+    observe(line: LedgerLine): boolean;
+    /** Entries changed since the last call, as snapshots; clears the queue. */
+    takeChanged(): LedgerEntry[];
+    /** Put entries back on the changed queue (a write that failed). */
+    requeue(messageIds: readonly string[]): void;
+    get(messageId: string): LedgerEntry | undefined;
+    all(): LedgerEntry[];
+    /** Per-field sum of every reply's maximum — the transcript's true total. */
+    totals(): LedgerUsage;
+    /** Distinct tool-use ids across all replies. */
+    toolUseCount(): number;
+}
+/**
+ * Pull the counter's {@link LedgerLine} fields out of one raw transcript
+ * line (a parsed JSONL object). Returns `null` for anything that is not an
+ * assistant line. Shared by every counter that reads a transcript from disk
+ * (the dashboard's reader, the skill-eval probe, the stall sweep).
+ */
+export declare function ledgerLineFromRaw(raw: Record<string, unknown>, source: string, byteOffset: number): LedgerLine | null;
+/**
+ * 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 declare function observeTranscriptText(counter: UsageLedgerCounter, text: string, source: string, startByteOffset?: number): void;
+/**
+ * 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 declare function ledgerLineFromLogEntry(entry: AgentLogEntry): LedgerLine | null;

package/dist/usage-ledger.js

@@ -0,0 +1,318 @@
+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`, `usage-ledger-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();
+    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,
+                repliedAt: line.timestamp,
+                toolUseIds: [...new Set(line.toolUseIds)],
+            });
+            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 (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 }, toolUseIds: [...e.toolUseIds] };
+}
+/**
+ * Pull the counter's {@link LedgerLine} fields out of one raw transcript
+ * line (a parsed JSONL object). Returns `null` for anything that is not an
+ * assistant line. Shared by every counter that reads a transcript from disk
+ * (the dashboard's reader, the skill-eval probe, the stall sweep).
+ */
+export function ledgerLineFromRaw(raw, source, byteOffset) {
+    if (raw.type !== "assistant")
+        return null;
+    const message = raw.message;
+    if (!message)
+        return null;
+    const content = Array.isArray(message.content)
+        ? message.content
+        : [];
+    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.
+    if (!Number.isFinite(ts)) {
+        throw new LedgerLineDataError(`ledgerLineFromRaw: unparseable/missing timestamp (raw.timestamp=${JSON.stringify(raw.timestamp)})`);
+    }
+    return {
+        messageId: typeof message.id === "string" && message.id.length > 0 ? message.id : undefined,
+        source,
+        byteOffset,
+        model: typeof message.model === "string" && message.model.length > 0
+            ? message.model
+            : undefined,
+        usage: message.usage && typeof message.usage === "object"
+            ? message.usage
+            : undefined,
+        timestamp: ts,
+        toolUseIds: content
+            .filter((b) => b.type === "tool_use" && typeof b.id === "string")
+            .map((b) => b.id),
+    };
+}
+/**
+ * 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, 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);
+        if (line)
+            counter.observe(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;
+    // 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. Harmless when a real
+    // `messageId` is present (byteOffset is never used to key that line), so
+    // only fail when the line actually needs it.
+    if (!hasMessageId && typeof d.byte_offset !== "number") {
+        throw new LedgerLineDataError(`ledgerLineFromLogEntry: missing/invalid byte_offset on a no-message-id line (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: d.usage && typeof d.usage === "object"
+            ? d.usage
+            : undefined,
+        timestamp: entry.timestamp,
+        toolUseIds: content
+            .filter((b) => b.type === "tool_use" && typeof b.id === "string")
+            .map((b) => b.id),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/danx-session-telemetry",
-  "version": "0.1.6",
+  "version": "0.1.9",
   "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",