@thehammer/danx-session-telemetry 0.1.22 → 0.1.24

package/dist/.source-hash

@@ -0,0 +1 @@
+89cd1ca4f2b51d45e885401f25cd2013ae9a293b3f3788aa820d45ea63e2a004

package/dist/browser.d.ts

@@ -22,4 +22,6 @@
 export type { AgentLogEntry, AgentLineage } from "./types.js";
 export { truncStr } from "./tool-summary.js";
 export * from "./usage-ledger.js";
+export * from "./ledger-timing.js";
+export * from "./transcript-timing.js";
 export * from "./pricing.js";

package/dist/browser.js

@@ -3,4 +3,6 @@
 export { truncStr } from "./tool-summary.js";
 // DX-2963 — counter + pricing (pure arithmetic, no `node:` imports).
 export * from "./usage-ledger.js";
+export * from "./ledger-timing.js";
+export * from "./transcript-timing.js";
 export * from "./pricing.js";

package/dist/dispatch-usage.d.ts

@@ -17,8 +17,7 @@
  * (HTTP on a registered worker, getPool-direct on the dashboard).
  */
 import { UsageLedgerCounter } from "./usage-ledger.js";
-import type { CursorPastEofInfo } from "./session-log-watcher.js";
-import type { AgentLogEntry } from "./types.js";
+import type { CursorPastEofInfo, EntryMeta } from "./session-log-watcher.js";
 import { type ActivityChange, type SourceCursors, type StatsPayload, type StatsResponse, type UsageTotals } from "./stats-wire.js";
 /** Where stats writes go — both dispatch-row sinks implement it. */
 export interface StatsSink {
@@ -196,15 +195,17 @@ export declare class DispatchUsage {
      */
     private cursorsMoved;
     /**
-     * Feed one watcher entry. Only assistant lines carry usage / tool ids.
+     * Feed one raw transcript line of the usage feed set (assistant, user, attachment, system), in file order.
+     * DX-3964 - the usage collector is fed from the watcher's collector-only `onUsageLine` subscription, never from
+     * `onEntry`: `convertJsonlEntry` drops human prompts, attachments and system lines, and widening it would hand
+     * every other `onEntry` subscriber a new volume of entries.
      *
-     * `replay` (DX-2954) marks a line re-read after a restart. The line STILL goes
-     * to the counter — the ledger is idempotent and dropping it would lose usage a
-     * restart is meant to recover — but its id is remembered so the local ceiling
-     * estimate does not count it twice (see {@link DispatchUsage.unacknowledged}).
+     * `meta.replay` (DX-2954) marks a line re-read after a restart. The line STILL goes to the counter - the
+     * ledger is idempotent and dropping it would lose usage a restart is meant to recover - but a replayed
+     * assistant reply's id is remembered so the local ceiling estimate does not count it twice (see
+     * {@link DispatchUsage.unacknowledged}).
      */
-    observeEntry(entry: AgentLogEntry, replay?: boolean): void;
-    private observeReply;
+    observeRawLine(raw: Record<string, unknown>, meta: EntryMeta): void;
     /**
      * Ship every changed entry in capped batches, one after another. The first
      * call always writes (even with nothing to send) so the process takes the

package/dist/dispatch-usage.js

@@ -16,7 +16,7 @@
  * DB-free: runs in the DB-less worker. The sink decides the transport
  * (HTTP on a registered worker, getPool-direct on the dashboard).
  */
-import { MAIN_SOURCE, UsageLedgerCounter, ledgerLineFromLogEntry, excessUsage, syntheticMessageKey, } from "./usage-ledger.js";
+import { UsageLedgerCounter, ledgerLineFromRaw, excessUsage, } from "./usage-ledger.js";
 import { ClaimTracker, emptyClaimState } from "./claim-tracker.js";
 import { ACTIVITY_BATCH_CAP, DispatchUsageTerminalError, chunkEntries, collapseActivityChanges, } from "./stats-wire.js";
 import { createUsageWriteQueue } from "./write-queue.js";
@@ -129,6 +129,8 @@ export class DispatchUsage {
         // that can never be satisfied. The bytes we believed acknowledged do not
         // exist any more, so claiming them is simply false.
         this.ackedCursor.set(info.source, 0);
+        // DX-3964 - the source is read again from 0: its timing reducer starts fresh, first-line-anchored.
+        this.counter.resetSource(info.source);
         // DX-3962 - the claims recorded against the old file name a transcript that is gone; the source re-earns them
         // from the lines it re-reads from 0 (the server clears the stored claims in the same statement as the cursor).
         this.ackedClaims.set(info.source, emptyClaimState());
@@ -280,37 +282,38 @@ export class DispatchUsage {
         return false;
     }
     /**
-     * Feed one watcher entry. Only assistant lines carry usage / tool ids.
+     * Feed one raw transcript line of the usage feed set (assistant, user, attachment, system), in file order.
+     * DX-3964 - the usage collector is fed from the watcher's collector-only `onUsageLine` subscription, never from
+     * `onEntry`: `convertJsonlEntry` drops human prompts, attachments and system lines, and widening it would hand
+     * every other `onEntry` subscriber a new volume of entries.
      *
-     * `replay` (DX-2954) marks a line re-read after a restart. The line STILL goes
-     * to the counter — the ledger is idempotent and dropping it would lose usage a
-     * restart is meant to recover — but its id is remembered so the local ceiling
-     * estimate does not count it twice (see {@link DispatchUsage.unacknowledged}).
+     * `meta.replay` (DX-2954) marks a line re-read after a restart. The line STILL goes to the counter - the
+     * ledger is idempotent and dropping it would lose usage a restart is meant to recover - but a replayed
+     * assistant reply's id is remembered so the local ceiling estimate does not count it twice (see
+     * {@link DispatchUsage.unacknowledged}).
      */
-    observeEntry(entry, replay = false) {
-        const content = Array.isArray(entry.data.content) ? entry.data.content : [];
-        const source = typeof entry.data.subagent_id === "string" ? entry.data.subagent_id : MAIN_SOURCE;
+    observeRawLine(raw, meta) {
+        const line = ledgerLineFromRaw(raw, meta.source, meta.byteOffset);
+        if (!line)
+            return;
+        const message = raw.message;
+        const content = Array.isArray(message?.content) ? message.content : [];
         // DX-3962 - a `tool_result` settles a pickup / release the source asked for earlier.
-        if (entry.type === "user")
-            this.claims?.observeResultBlocks(source, content);
-        const line = ledgerLineFromLogEntry(entry);
-        if (line)
-            this.observeReply(line, replay);
+        if (line.kind === "user")
+            this.claims?.observeResultBlocks(meta.source, content);
+        if (line.kind === "assistant") {
+            line.line.issueId = this.claims?.issueFor(meta.source) ?? null;
+            // The counter's OWN key, not `line.messageId`: a usage line with no `message.id` is keyed by
+            // `syntheticMessageKey(source, byteOffset)`, and recording a different key here would leave that reply's
+            // replay unrecognised - the exact double-count this set prevents.
+            if (meta.replay)
+                this.replayedMessageIds.add(line.replyKey);
+        }
+        this.counter.observeLine(line);
         // AFTER the reply is counted: a reply is credited to the card held at its FIRST line, so the pickup this line
         // itself asks for takes effect only on its result, and never on the reply that issued it.
-        if (entry.type === "assistant")
-            this.claims?.observeAssistantBlocks(source, content);
-    }
-    observeReply(line, replay) {
-        line.issueId = this.claims?.issueFor(line.source) ?? null;
-        // The counter's OWN key, not `line.messageId`: a usage line with no
-        // `message.id` is keyed by `syntheticMessageKey(source, byteOffset)`
-        // (`usage-ledger.ts`), and recording a different key here would leave that
-        // reply's replay unrecognised — the exact double-count this set prevents.
-        if (replay) {
-            this.replayedMessageIds.add(line.messageId ?? syntheticMessageKey(line.source, line.byteOffset));
-        }
-        this.counter.observe(line);
+        if (line.kind === "assistant")
+            this.claims?.observeAssistantBlocks(meta.source, content);
     }
     /**
      * Ship every changed entry in capped batches, one after another. The first

package/dist/index.d.ts

@@ -15,10 +15,12 @@
  * usage display.
  */
 export { SessionLogWatcher, DISPATCH_TAG_PREFIX, encodeClaudeProjectsCwd, deriveSessionDir, sessionUuidExistsInCleanRoom, findNewestJsonlFile, findSessionFileByDispatchId, convertJsonlEntry, skipReplays, } from "./session-log-watcher.js";
-export type { EntryConsumer, SessionLogWatcherOptions, SourceCursorStart, CursorPastEofInfo, SourceDiscoveredInfo, EntryMeta, } from "./session-log-watcher.js";
+export type { EntryConsumer, UsageLineConsumer, SessionLogWatcherOptions, SourceCursorStart, CursorPastEofInfo, SourceDiscoveredInfo, EntryMeta, } 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 "./ledger-timing.js";
+export * from "./transcript-timing.js";
 export * from "./pricing.js";
 export * from "./stats-wire.js";
 export * from "./claim-tracker.js";

package/dist/index.js

@@ -24,6 +24,8 @@ export { truncStr, summarizeToolInput, buildAssistantSummary, buildToolResultSum
 // 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 "./ledger-timing.js";
+export * from "./transcript-timing.js";
 export * from "./pricing.js";
 // DX-2954 — the ONE stats collector and its wire, shared by the danxbot worker
 // and the desktop bridge (operator sessions) so both report the same stats the

package/dist/ledger-timing.d.ts

@@ -0,0 +1,26 @@
+/**
+ * DX-3964 - one reply's measured time and code churn. Its own block on
+ * {@link LedgerEntry}, never part of {@link LedgerUsage}: `LedgerUsage` is the
+ * priced token set that `LEDGER_USAGE_FIELDS` iterates into pricing, per-model
+ * buckets and the worker's token estimate, and none of those may see these.
+ * Every field only GROWS as the reply's lines (and the tool results that settle
+ * them) are read, so the ledger's `excess = max - credited` makes a replay credit
+ * nothing twice.
+ */
+export interface LedgerTiming {
+    /** Request sent to the reply's last block written, ms (`## Definitions` on DX-3964). */
+    apiMs: number;
+    /** Credited gaps in the source's own timeline owned by this reply, ms. */
+    agentMs: number;
+    /** Lines the reply's successful Edit/Write calls added. */
+    linesAdded: number;
+    /** Lines the reply's successful Edit/Write calls removed. */
+    linesRemoved: number;
+}
+export declare const LEDGER_TIMING_FIELDS: readonly ["apiMs", "agentMs", "linesAdded", "linesRemoved"];
+export declare function zeroTiming(): LedgerTiming;
+export declare function maxTiming(a: LedgerTiming, b: LedgerTiming): LedgerTiming;
+export declare function addTiming(a: LedgerTiming, b: LedgerTiming): LedgerTiming;
+/** Per-field `max(0, a - b)`. */
+export declare function excessTiming(a: LedgerTiming, b: LedgerTiming): LedgerTiming;
+export declare function isZeroTiming(t: LedgerTiming): boolean;

package/dist/ledger-timing.js

@@ -0,0 +1,31 @@
+export const LEDGER_TIMING_FIELDS = [
+    "apiMs",
+    "agentMs",
+    "linesAdded",
+    "linesRemoved",
+];
+export function zeroTiming() {
+    return { apiMs: 0, agentMs: 0, linesAdded: 0, linesRemoved: 0 };
+}
+export function maxTiming(a, b) {
+    const out = zeroTiming();
+    for (const f of LEDGER_TIMING_FIELDS)
+        out[f] = Math.max(a[f], b[f]);
+    return out;
+}
+export function addTiming(a, b) {
+    const out = zeroTiming();
+    for (const f of LEDGER_TIMING_FIELDS)
+        out[f] = a[f] + b[f];
+    return out;
+}
+/** Per-field `max(0, a - b)`. */
+export function excessTiming(a, b) {
+    const out = zeroTiming();
+    for (const f of LEDGER_TIMING_FIELDS)
+        out[f] = Math.max(0, a[f] - b[f]);
+    return out;
+}
+export function isZeroTiming(t) {
+    return LEDGER_TIMING_FIELDS.every((f) => t[f] === 0);
+}

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

@@ -36,6 +36,12 @@ export declare const DISPATCH_TAG_PREFIX = "<!-- danxbot-dispatch:";
  * re-read line (see {@link EntryMeta.replay}).
  */
 export type EntryConsumer = (entry: AgentLogEntry, meta: EntryMeta) => void;
+/**
+ * DX-3964 - a consumer of the usage feed: the PARSED RAW line (assistant, user, attachment or system - nothing
+ * else) with the same {@link EntryMeta} an `onEntry` consumer gets. Collector-only: see
+ * {@link SessionLogWatcher.onUsageLine}.
+ */
+export type UsageLineConsumer = (raw: Record<string, unknown>, meta: EntryMeta) => void;
 /**
  * DX-2954 — the ONE replay gate every side-effecting transcript subscriber goes
  * through (Slack progress, the gpt-manager forwarder): it hands on only lines
@@ -279,7 +285,7 @@ export declare function findNewestJsonlFile(dir: string, sessionId?: string): Pr
  *     detection for that dispatch.
  *
  * So we scan BOTH a head window and a tail window (they overlap, covering
- * the whole file, for any file ≤ 2×`SCAN_BYTES`). A resumed tag always
+ * the whole file, for any file ≤ 2x`SCAN_BYTES`). A resumed tag always
  * lands in the freshly-appended tail; a fresh tag always lands in the head.
  *
  * Returns the full path to the matching file, or null if no file matches.
@@ -318,6 +324,7 @@ export declare function convertJsonlEntry(raw: Record<string, unknown>, lastTime
  */
 export declare class SessionLogWatcher {
     private consumers;
+    private usageConsumers;
     private pollTimer;
     private parentTail;
     private subagentsDir;
@@ -385,6 +392,17 @@ export declare class SessionLogWatcher {
     mainStartOffset(): number | null;
     /** Register a consumer callback that receives each new AgentLogEntry. */
     onEntry(consumer: EntryConsumer): void;
+    /**
+     * DX-3964 - register a usage-feed consumer: it receives the parsed raw line of every assistant, user,
+     * attachment and system line, in file order, with the same `EntryMeta` as `onEntry`. The ONLY subscribers are
+     * the two `DispatchUsage` feed sites (the worker and the operator bridge): `convertJsonlEntry` and every
+     * `onEntry` subscriber keep seeing exactly what they saw before, because human prompts, attachments (tens of
+     * thousands of hook records) and system lines are not theirs.
+     *
+     * Each consumer runs in its own try/catch, as in `emitEntry`: a consumer that throws (a
+     * `LedgerLineDataError` on a line with no timestamp) never withholds the line from `onEntry` subscribers.
+     */
+    onUsageLine(consumer: UsageLineConsumer): void;
     /** Returns the discovered parent session file path, or null if not yet found. */
     getSessionFilePath(): string | null;
     /**
@@ -526,6 +544,13 @@ export declare class SessionLogWatcher {
      * tool-registration check that works across both runtimes.
      */
     private handleRawEntry;
+    /**
+     * DX-2954 — a line whose FIRST byte lies below the source's stored
+     * `delivered` cursor was already handed to a previous incarnation's
+     * subscribers. Strictly `<`: `delivered` is an exclusive end (the next
+     * unread byte), so a line starting exactly AT it is new.
+     */
+    private entryMeta;
     /**
      * Emit an entry to registered consumers. For sub-agent streams,
      * `state.lineage` decorates `entry.data` so the emitted EventPayload

package/dist/session-log-watcher.js

@@ -42,6 +42,8 @@ const MAX_FILE_DISCOVERY_ATTEMPTS = 180;
  * wrong file (e.g., an active human session).
  */
 export const DISPATCH_TAG_PREFIX = "<!-- danxbot-dispatch:";
+/** The line `type`s the usage feed carries; every other type never reaches a {@link UsageLineConsumer}. */
+const USAGE_FEED_TYPES = new Set(["assistant", "user", "attachment", "system"]);
 /**
  * DX-2954 — the ONE replay gate every side-effecting transcript subscriber goes
  * through (Slack progress, the gpt-manager forwarder): it hands on only lines
@@ -221,7 +223,7 @@ export async function findNewestJsonlFile(dir, sessionId) {
  *     detection for that dispatch.
  *
  * So we scan BOTH a head window and a tail window (they overlap, covering
- * the whole file, for any file ≤ 2×`SCAN_BYTES`). A resumed tag always
+ * the whole file, for any file ≤ 2x`SCAN_BYTES`). A resumed tag always
  * lands in the freshly-appended tail; a fresh tag always lands in the head.
  *
  * Returns the full path to the matching file, or null if no file matches.
@@ -347,7 +349,7 @@ export function convertJsonlEntry(raw, lastTimestamp) {
             // thinking + text + tool_use, etc.) into one JSONL line per content
             // block, but stamps the SAME response-level `message.usage` on every
             // line. Surface `messageId` so downstream usage accumulators can dedupe
-            // — without it, every multi-block turn over-counts tokens 2-5×. See
+            // — without it, every multi-block turn over-counts tokens 2-5x. See
             // `.claude/rules/agent-dispatch.md`.
             const messageId = typeof message.id === "string" && message.id.length > 0
                 ? message.id
@@ -479,6 +481,7 @@ export function convertJsonlEntry(raw, lastTimestamp) {
  */
 export class SessionLogWatcher {
     consumers = [];
+    usageConsumers = [];
     pollTimer;
     parentTail = null;
     subagentsDir = null;
@@ -616,6 +619,19 @@ export class SessionLogWatcher {
     onEntry(consumer) {
         this.consumers.push(consumer);
     }
+    /**
+     * DX-3964 - register a usage-feed consumer: it receives the parsed raw line of every assistant, user,
+     * attachment and system line, in file order, with the same `EntryMeta` as `onEntry`. The ONLY subscribers are
+     * the two `DispatchUsage` feed sites (the worker and the operator bridge): `convertJsonlEntry` and every
+     * `onEntry` subscriber keep seeing exactly what they saw before, because human prompts, attachments (tens of
+     * thousands of hook records) and system lines are not theirs.
+     *
+     * Each consumer runs in its own try/catch, as in `emitEntry`: a consumer that throws (a
+     * `LedgerLineDataError` on a line with no timestamp) never withholds the line from `onEntry` subscribers.
+     */
+    onUsageLine(consumer) {
+        this.usageConsumers.push(consumer);
+    }
     /** Returns the discovered parent session file path, or null if not yet found. */
     getSessionFilePath() {
         return this.parentTail?.filePath ?? null;
@@ -1093,6 +1109,17 @@ export class SessionLogWatcher {
      */
     handleRawEntry(raw, state, lineStart) {
         const isSubagent = state.lineage !== undefined;
+        if (typeof raw.type === "string" && USAGE_FEED_TYPES.has(raw.type)) {
+            const meta = this.entryMeta(state, lineStart);
+            for (const consumer of this.usageConsumers) {
+                try {
+                    consumer(raw, meta);
+                }
+                catch (err) {
+                    log.error("Usage line consumer error:", err);
+                }
+            }
+        }
         if (!isSubagent && !this.initSynthesized && raw.type === "assistant") {
             const message = raw.message;
             const model = message?.model;
@@ -1135,6 +1162,15 @@ export class SessionLogWatcher {
         result.entry.data = { ...result.entry.data, byte_offset: lineStart };
         this.emitEntry(result.entry, state, lineStart);
     }
+    /**
+     * DX-2954 — a line whose FIRST byte lies below the source's stored
+     * `delivered` cursor was already handed to a previous incarnation's
+     * subscribers. Strictly `<`: `delivered` is an exclusive end (the next
+     * unread byte), so a line starting exactly AT it is new.
+     */
+    entryMeta(state, byteOffset) {
+        return { source: state.source, byteOffset, replay: byteOffset < state.replayUntil };
+    }
     /**
      * Emit an entry to registered consumers. For sub-agent streams,
      * `state.lineage` decorates `entry.data` so the emitted EventPayload

package/dist/stats-wire.js

@@ -1,3 +1,4 @@
+import { LEDGER_TIMING_FIELDS } from "./ledger-timing.js";
 import { ISSUE_ID_MAX_LENGTH, ISSUE_ID_PATTERN, MAX_HELD_CLAIMS, MAX_PENDING_TRANSITIONS, } from "./claim-tracker.js";
 /**
  * DX-2963 — cap on entries per stats write. A from-0 backlog (a reattach, a
@@ -327,6 +328,17 @@ export function parseStatsPayload(body) {
             if (!isNonNegInt(u[k]))
                 throw new StatsPayloadError(`${where}.usage.${k}`);
         }
+        // DX-3964 - REQUIRED: an entry without `timing` comes from a collector that predates it, which the MCP
+        // version floor refuses rather than this parser tolerating.
+        const t = e.timing;
+        if (!t || typeof t !== "object" || Array.isArray(t))
+            throw new StatsPayloadError(`${where}.timing`);
+        const timing = {};
+        for (const k of LEDGER_TIMING_FIELDS) {
+            if (!isNonNegInt(t[k]))
+                throw new StatsPayloadError(`${where}.timing.${k}`);
+            timing[k] = t[k];
+        }
         if (!Array.isArray(e.toolUseIds) || e.toolUseIds.some((t) => typeof t !== "string")) {
             throw new StatsPayloadError(`${where}.toolUseIds`);
         }
@@ -347,6 +359,7 @@ export function parseStatsPayload(body) {
                 cacheWrite5m: u.cacheWrite5m,
                 cacheWrite1h: u.cacheWrite1h,
             },
+            timing,
             toolUseIds: e.toolUseIds,
             issueId: e.issueId,
         };

package/dist/transcript-timing.d.ts

@@ -0,0 +1,87 @@
+/**
+ * DX-3964 - the per-source reducer that turns a transcript's lines into each reply's
+ * API time, agent time and lines added/removed, exactly per the `## Definitions` DX-3975
+ * measured on 18 real transcripts. Pure arithmetic (no `node:` imports), so the
+ * browser-safe entry exports it too.
+ *
+ * One reducer per SOURCE (one transcript file). It is fed every assistant, user,
+ * attachment and system line of that file in FILE ORDER, and reports, per reply, values
+ * that only ever grow as lines are appended (max semantics), so the ledger's
+ * `excess = max - credited` makes a resend, resume or restart credit nothing twice.
+ *
+ *  - Never sort by timestamp: `hwm` (the largest timestamp seen) is a running maximum
+ *    and a line older than it yields a 0 gap and never moves it back.
+ *  - A reducer that starts mid-file anchors `hwm` on the first assistant or tool_result
+ *    line it sees (a stale queued attachment at a restart must not be a gap), and
+ *    credits only what it derived from lines in its own window.
+ */
+import type { LedgerLine } from "./usage-ledger.js";
+import { type LedgerTiming } from "./ledger-timing.js";
+/** A single gap above this is a suspend or an unanswered prompt, never work. */
+export declare const MAX_CREDITED_GAP_MS = 600000;
+export interface TimingToolUse {
+    id: string;
+    name: string;
+    input: Record<string, unknown> | null;
+}
+export interface PatchHunk {
+    lines: readonly string[];
+}
+export interface TimingToolResult {
+    toolUseId: string;
+    isError: boolean;
+    /** The result's text (a string content, or its text blocks joined). */
+    text: string;
+    /** `toolUseResult.structuredPatch` of the line carrying exactly this one result; absent from sub-agent transcripts. */
+    structuredPatch: readonly PatchHunk[] | null;
+}
+/** One transcript line of the fed set (assistant, user, attachment, system), parsed. */
+export type TranscriptLine = {
+    kind: "assistant";
+    line: LedgerLine;
+    /** The counter's own key for the reply (`message.id`, or the synthetic per-offset key). */
+    replyKey: string;
+    byteOffset: number;
+    /** `message.model` is `<synthetic>` (API error text): it measures nothing. */
+    synthetic: boolean;
+    toolUses: readonly TimingToolUse[];
+} | {
+    kind: "user";
+    source: string;
+    timestamp: number;
+    byteOffset: number;
+    /** Empty for a human prompt (string content, an array with no tool_result, an `isMeta` line). */
+    results: readonly TimingToolResult[];
+} | {
+    kind: "attachment" | "system";
+    source: string;
+    timestamp: number;
+    byteOffset: number;
+};
+export declare function timestampOf(t: TranscriptLine): number;
+export declare class SourceTimingReducer {
+    /** `null` until anchored. */
+    private hwm;
+    private candidates;
+    /** Gap time ending at an attachment or system line: owned by the next reply to start. */
+    private carried;
+    private readonly replies;
+    private readonly tools;
+    private readonly pendingEdits;
+    /** Feed one line; returns the current values of every reply it touched. */
+    feed(t: TranscriptLine): Map<string, LedgerTiming>;
+    private feedAssistant;
+    private feedUser;
+    /** `S`: the largest request-side timestamp since the previous assistant line, clamped to the reply's first line. */
+    private sendTimeFor;
+}
+/** Number of lines in `s` (a trailing newline does not start another line). */
+export declare function countLines(s: string): number;
+/**
+ * The line diff of one Edit's `old_string` against its `new_string`: split on newline, common prefix and suffix trimmed,
+ * then the longest common subsequence. Equals Claude Code's own `structuredPatch` on 908 of 916 measured Edits.
+ */
+export declare function lineDiffCounts(oldText: string, newText: string): {
+    added: number;
+    removed: number;
+};

package/dist/transcript-timing.js

@@ -0,0 +1,230 @@
+import { zeroTiming } from "./ledger-timing.js";
+/** A single gap above this is a suspend or an unanswered prompt, never work. */
+export const MAX_CREDITED_GAP_MS = 600_000;
+/** Tools whose result is a parent WAITING on a child that carries that time in its own source. */
+const WAITING_TOOLS = new Set(["Agent", "Task"]);
+export function timestampOf(t) {
+    return t.kind === "assistant" ? t.line.timestamp : t.timestamp;
+}
+function snapshot(r) {
+    if (r.synthetic)
+        return zeroTiming();
+    return {
+        apiMs: Math.max(0, r.lastTs - r.sendTime),
+        agentMs: r.agentMs,
+        linesAdded: r.linesAdded,
+        linesRemoved: r.linesRemoved,
+    };
+}
+export class SourceTimingReducer {
+    /** `null` until anchored. */
+    hwm = null;
+    candidates = [];
+    /** Gap time ending at an attachment or system line: owned by the next reply to start. */
+    carried = 0;
+    replies = new Map();
+    tools = new Map();
+    pendingEdits = new Map();
+    /** Feed one line; returns the current values of every reply it touched. */
+    feed(t) {
+        const touched = new Set();
+        const ts = timestampOf(t);
+        let gap = 0;
+        if (this.hwm === null) {
+            // A reducer that starts mid-file anchors on its first assistant or tool_result line; a fresh file's own
+            // first line (offset 0) anchors it too. Before the anchor nothing is credited and nothing is remembered.
+            const anchors = t.byteOffset === 0 || t.kind === "assistant" || (t.kind === "user" && t.results.length > 0);
+            if (!anchors)
+                return new Map();
+            this.hwm = ts;
+        }
+        else {
+            gap = Math.max(0, ts - this.hwm);
+            if (gap > MAX_CREDITED_GAP_MS)
+                gap = 0;
+            this.hwm = Math.max(this.hwm, ts);
+        }
+        switch (t.kind) {
+            case "assistant":
+                this.feedAssistant(t, ts, gap, touched);
+                break;
+            case "user":
+                this.feedUser(t, gap, touched);
+                this.candidates.push({ ts, attachment: false });
+                break;
+            case "attachment":
+                this.carried += gap;
+                this.candidates.push({ ts, attachment: true });
+                break;
+            case "system":
+                this.carried += gap;
+                break;
+        }
+        const out = new Map();
+        for (const key of touched)
+            out.set(key, snapshot(this.replies.get(key)));
+        return out;
+    }
+    feedAssistant(t, ts, gap, touched) {
+        let reply = this.replies.get(t.replyKey);
+        if (!reply) {
+            reply = {
+                sendTime: this.sendTimeFor(ts),
+                lastTs: ts,
+                synthetic: t.synthetic,
+                agentMs: this.carried,
+                linesAdded: 0,
+                linesRemoved: 0,
+                settled: new Set(),
+            };
+            this.carried = 0;
+            this.replies.set(t.replyKey, reply);
+        }
+        reply.lastTs = Math.max(reply.lastTs, ts);
+        reply.agentMs += gap;
+        touched.add(t.replyKey);
+        // Request-send candidates are the lines AFTER the previous assistant line, so every assistant line resets them.
+        this.candidates = [];
+        for (const use of t.toolUses) {
+            this.tools.set(use.id, { replyKey: t.replyKey, name: use.name });
+            if ((use.name === "Edit" || use.name === "Write") && use.input !== null && !reply.settled.has(use.id)) {
+                this.pendingEdits.set(use.id, { replyKey: t.replyKey, name: use.name, input: use.input });
+            }
+        }
+    }
+    feedUser(t, gap, touched) {
+        if (t.results.length === 0)
+            return; // a human prompt: the gap ending here is user or idle time
+        const owner = this.tools.get(t.results[0].toolUseId);
+        // A gap ending at an Agent/Task result is a parent waiting on a child whose own source carries that time.
+        if (owner && !WAITING_TOOLS.has(owner.name)) {
+            const reply = this.replies.get(owner.replyKey);
+            if (reply) {
+                reply.agentMs += gap;
+                touched.add(owner.replyKey);
+            }
+        }
+        for (const result of t.results) {
+            const pending = this.pendingEdits.get(result.toolUseId);
+            if (!pending)
+                continue;
+            this.pendingEdits.delete(result.toolUseId);
+            const reply = this.replies.get(pending.replyKey);
+            if (!reply)
+                continue;
+            reply.settled.add(result.toolUseId);
+            if (result.isError)
+                continue;
+            const lines = linesOf(pending, result);
+            reply.linesAdded += lines.added;
+            reply.linesRemoved += lines.removed;
+            touched.add(pending.replyKey);
+        }
+    }
+    /** `S`: the largest request-side timestamp since the previous assistant line, clamped to the reply's first line. */
+    sendTimeFor(firstTs) {
+        let best = null;
+        for (const c of this.candidates) {
+            // A `deferred_tools_record` attachment is written AFTER the response starts.
+            if (c.attachment && c.ts >= firstTs)
+                continue;
+            if (best === null || c.ts > best)
+                best = c.ts;
+        }
+        return best === null ? firstTs : Math.min(firstTs, best);
+    }
+}
+/** Number of lines in `s` (a trailing newline does not start another line). */
+export function countLines(s) {
+    if (s === "")
+        return 0;
+    const n = s.split("\n").length;
+    return s.endsWith("\n") ? n - 1 : n;
+}
+function patchCounts(patch) {
+    let added = 0;
+    let removed = 0;
+    for (const hunk of patch) {
+        for (const line of hunk.lines) {
+            if (line.startsWith("+"))
+                added++;
+            else if (line.startsWith("-"))
+                removed++;
+        }
+    }
+    return { added, removed };
+}
+function splitLines(s) {
+    return s === "" ? [] : s.split("\n");
+}
+/** Myers' shortest edit script length (insertions + deletions) between two line lists. */
+function editDistance(a, b) {
+    const n = a.length;
+    const m = b.length;
+    const max = n + m;
+    if (max === 0)
+        return 0;
+    const off = max;
+    const v = new Int32Array(2 * max + 2);
+    for (let d = 0; d <= max; d++) {
+        for (let k = -d; k <= d; k += 2) {
+            let x;
+            if (k === -d || (k !== d && v[off + k - 1] < v[off + k + 1]))
+                x = v[off + k + 1];
+            else
+                x = v[off + k - 1] + 1;
+            let y = x - k;
+            while (x < n && y < m && a[x] === b[y]) {
+                x++;
+                y++;
+            }
+            v[off + k] = x;
+            if (x >= n && y >= m)
+                return d;
+        }
+    }
+    throw new Error("editDistance: unreachable, the edit script is at most n + m long");
+}
+/**
+ * The line diff of one Edit's `old_string` against its `new_string`: split on newline, common prefix and suffix trimmed,
+ * then the longest common subsequence. Equals Claude Code's own `structuredPatch` on 908 of 916 measured Edits.
+ */
+export function lineDiffCounts(oldText, newText) {
+    const a = splitLines(oldText);
+    const b = splitLines(newText);
+    let start = 0;
+    while (start < a.length && start < b.length && a[start] === b[start])
+        start++;
+    let endA = a.length;
+    let endB = b.length;
+    while (endA > start && endB > start && a[endA - 1] === b[endB - 1]) {
+        endA--;
+        endB--;
+    }
+    const ta = a.slice(start, endA);
+    const tb = b.slice(start, endB);
+    const d = editDistance(ta, tb);
+    const lcs = (ta.length + tb.length - d) / 2;
+    return { added: tb.length - lcs, removed: ta.length - lcs };
+}
+function stringInput(input, key) {
+    const v = input[key];
+    return typeof v === "string" ? v : "";
+}
+/** The lines one successful Edit or Write result credits. Any other tool never reaches here. */
+function linesOf(pending, result) {
+    if (pending.name === "Edit") {
+        if (pending.input.replace_all === true && result.structuredPatch !== null) {
+            return patchCounts(result.structuredPatch);
+        }
+        return lineDiffCounts(stringInput(pending.input, "old_string"), stringInput(pending.input, "new_string"));
+    }
+    if (result.text.includes("File created successfully")) {
+        return { added: countLines(stringInput(pending.input, "content")), removed: 0 };
+    }
+    // An overwrite: the previous content is not in the input, so only a patch (main and worker transcripts) can say.
+    if (result.text.includes("has been updated successfully") && result.structuredPatch !== null) {
+        return patchCounts(result.structuredPatch);
+    }
+    return { added: 0, removed: 0 };
+}

package/dist/usage-ledger.d.ts

@@ -18,6 +18,8 @@
  * browser-safe `./browser` subpath as well as the main entry.
  */
 import type { PricedTokens } from "./pricing.js";
+import { type LedgerTiming } from "./ledger-timing.js";
+import { type TranscriptLine } from "./transcript-timing.js";
 import type { AgentLogEntry } from "./types.js";
 /** Per-reply usage, both cache-write lifetimes kept apart (priced apart). */
 export type LedgerUsage = PricedTokens;
@@ -36,6 +38,8 @@ export interface LedgerEntry {
     /** `usage.speed` (`standard` / `fast`); `"standard"` when the line has none. */
     speed: string;
     usage: LedgerUsage;
+    /** DX-3964 - the reply's measured time and lines; see {@link LedgerTiming}. */
+    timing: LedgerTiming;
     /** The reply's own transcript timestamp (its FIRST line's), epoch ms. */
     repliedAt: number;
     toolUseIds: string[];
@@ -114,6 +118,21 @@ export declare function totalTokensOfUsage(u: LedgerUsage): number;
 export declare class UsageLedgerCounter {
     private readonly entries;
     private readonly changed;
+    /** DX-3964 - one timing reducer per source (transcript file); see `transcript-timing.ts`. */
+    private readonly reducers;
+    /**
+     * 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: TranscriptLine): boolean;
+    /**
+     * 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: string): void;
     observe(line: LedgerLine): boolean;
     /** Entries changed since the last call, as snapshots; clears the queue. */
     takeChanged(): LedgerEntry[];
@@ -127,12 +146,12 @@ export declare class UsageLedgerCounter {
     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, `claude-probe.ts`, the stall sweep).
+ * 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 declare function ledgerLineFromRaw(raw: Record<string, unknown>, source: string, byteOffset: number): LedgerLine | null;
+export declare function ledgerLineFromRaw(raw: Record<string, unknown>, source: string, byteOffset: number): TranscriptLine | 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

package/dist/usage-ledger.js

@@ -1,3 +1,5 @@
+import { LEDGER_TIMING_FIELDS, maxTiming, zeroTiming } from "./ledger-timing.js";
+import { SourceTimingReducer, } from "./transcript-timing.js";
 export const MAIN_SOURCE = "main";
 /**
  * DX-3261 — a producer handed this module a line it cannot safely key or
@@ -119,6 +121,44 @@ function readSpeed(usage) {
 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-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;
+        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;
+    }
+    /**
+     * 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)
@@ -138,6 +178,7 @@ export class UsageLedgerCounter {
                 model: line.model ?? null,
                 speed: readSpeed(line.usage),
                 usage,
+                timing: zeroTiming(),
                 repliedAt: line.timestamp,
                 toolUseIds: [...new Set(line.toolUseIds)],
                 issueId: line.issueId,
@@ -209,47 +250,109 @@ export class UsageLedgerCounter {
     }
 }
 function snapshot(e) {
-    return { ...e, usage: { ...e.usage }, toolUseIds: [...e.toolUseIds] };
+    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
+        : [];
+}
+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,
+    }));
 }
 /**
- * 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, `claude-probe.ts`, the stall sweep).
+ * 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) {
-    if (raw.type !== "assistant")
+    const type = raw.type;
+    if (typeof type !== "string" || !FED_TYPES.has(type))
         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)})`);
+    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,
+            },
+            replyKey: messageId ?? syntheticMessageKey(source, byteOffset),
+            byteOffset,
+            synthetic: model === "<synthetic>",
+            toolUses,
+        };
     }
-    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),
-        issueId: null,
-    };
+    const timestamp = parseTimestamp(raw, "ledgerLineFromRaw");
+    if (type === "user") {
+        return { kind: "user", source, timestamp, byteOffset, results: toolResultsOf(raw, blocksOf(message)) };
+    }
+    return { kind: type, source, timestamp, byteOffset };
 }
 /**
  * Count a whole transcript text (one file) into a counter. Byte offsets are
@@ -275,7 +378,7 @@ export function observeTranscriptText(counter, text, source, startByteOffset = 0
         }
         const line = ledgerLineFromRaw(parsed, source, lineOffset);
         if (line)
-            counter.observe(line);
+            counter.observeLine(line);
     }
 }
 /**

package/package.json

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