@thehammer/danx-session-telemetry 0.1.20 → 0.1.21

package/dist/claim-tracker.d.ts

@@ -0,0 +1,47 @@
+/** The one tool a sub-agent reaches the dashboard API through (the MCP server key is `danx-dashboard`). */
+export declare const DASHBOARD_API_TOOL_NAME = "mcp__danx-dashboard__danxbot_api";
+/** A card id as the issue routes name it, e.g. `DX-3962`. Also the wire's validation for every card id a claim carries. */
+export declare const ISSUE_ID_PATTERN: RegExp;
+/** Longest card id a claim may carry (`dispatches.issue_id` is `VARCHAR(32)`). */
+export declare const ISSUE_ID_MAX_LENGTH = 32;
+/**
+ * Bounds that keep one source's persisted state, and the stats write that carries
+ * it, bounded. A real sub-agent holds one or two cards, so neither is reachable;
+ * the OLDEST entry is the one dropped, because the newest claim is what the next
+ * reply is credited to.
+ */
+export declare const MAX_HELD_CLAIMS = 50;
+export declare const MAX_PENDING_TRANSITIONS = 50;
+/** One transition whose `tool_use` has been read and whose `tool_result` has not. */
+export interface PendingTransition {
+    op: "claim" | "release";
+    issueId: string;
+}
+/** One source's claim state at one transcript position. */
+export interface ClaimState {
+    /** Claimed cards, oldest first. */
+    held: string[];
+    /** In-flight transitions keyed by their `tool_use_id`. */
+    pending: Record<string, PendingTransition>;
+}
+export declare function emptyClaimState(): ClaimState;
+/**
+ * The per-process claim tracker: one state per sub-agent source. Fed every
+ * transcript line by `DispatchUsage` (operator-bridge mode only — the worker never
+ * constructs one), seeded from the stored cursor at attach, and snapshotted per
+ * source for the stats write.
+ */
+export declare class ClaimTracker {
+    private readonly states;
+    /** Replace a source's state — at attach (the stored cursor's claims) and on a past-EOF reset (empty). */
+    seed(source: string, state: ClaimState): void;
+    /** A copy of the source's state as of the last line fed; empty for a source that holds nothing. */
+    snapshot(source: string): ClaimState;
+    /** The card a reply whose first line is read NOW is credited to; `null` when the source holds none. */
+    issueFor(source: string): string | null;
+    /** An assistant line's content blocks: remember every claim / release the line asks for until its result arrives. */
+    observeAssistantBlocks(source: string, blocks: readonly unknown[]): void;
+    /** A user line's content blocks: settle every remembered transition whose result is here. */
+    observeResultBlocks(source: string, blocks: readonly unknown[]): void;
+    private stateOf;
+}

package/dist/claim-tracker.js

@@ -0,0 +1,205 @@
+/**
+ * DX-3962 — which card a sub-agent is working, read from the sub-agent's OWN
+ * transcript.
+ *
+ * An operator session builds most cards through sub-agents that claim the card
+ * with a manual `pickup`, which creates no dispatch row. Every such claim is in
+ * the sub-agent's transcript: a `danxbot_api` `tool_use`
+ * `POST /api/issues/<ID>/transition {action: "pickup"}` and, later, the
+ * `tool_result` carrying the server's answer. This tracker turns those into the
+ * card id every one of the sub-agent's replies is credited to.
+ *
+ * ## The rule (DX-3962 plan-architecture finding 5)
+ *
+ * Per source, an ORDERED set of claimed cards.
+ *   - a successful `pickup` appends the card, or moves it to the end when it is
+ *     already held;
+ *   - a successful `complete` / `cancel` / `block` / `rollback_pickup` of a held
+ *     card BY THE SAME SOURCE removes it. (`review` is not a transition action —
+ *     Review is a derived status, `issues/derive/status.ts` — so the card's list
+ *     of releases names only the four that exist.)
+ *   - a reply's card is the LAST element of the set at the reply's first line, by
+ *     transcript order, never wall clock. An empty set is `null`.
+ *
+ * Success is read from the RESULT, never the request: a claim or release takes
+ * effect only on the `tool_result` for its own `tool_use_id` whose body is
+ * `{"ok": true, ...}`. A refused pickup (409) never attributes and a refused
+ * release never releases.
+ *
+ * `main` never attributes (epic decision): its replies roll up to the plan or the
+ * board. Quality-gate verdicts, comments and edits are not transitions, so they
+ * never set a claim — a reviewer touching several cards stays unattributed.
+ * Documented unattributed cases: a nested sub-agent with no pickup of its own, and
+ * the reply that issued the pickup call itself (its first line precedes the
+ * successful result).
+ *
+ * ## The state belongs to a transcript position
+ *
+ * The state is the held set PLUS the transitions whose `tool_use` has been read
+ * and whose `tool_result` has not (`pending`). Both are persisted beside the
+ * source's read cursor (`dispatch_source_cursors.claims`): a bridge that restarts
+ * resumes at its stored `acked` offset, and a pickup that sits before it is never
+ * re-read, so without the state every later reply would go unattributed. The
+ * pending half closes the narrow window where the restart lands between a pickup's
+ * `tool_use` and its `tool_result`.
+ *
+ * Pure bookkeeping — no `node:` imports, so it rides the browser-safe subpath too.
+ */
+import { MAIN_SOURCE } from "./usage-ledger.js";
+/** The one tool a sub-agent reaches the dashboard API through (the MCP server key is `danx-dashboard`). */
+export const DASHBOARD_API_TOOL_NAME = "mcp__danx-dashboard__danxbot_api";
+/** A card id as the issue routes name it, e.g. `DX-3962`. Also the wire's validation for every card id a claim carries. */
+export const ISSUE_ID_PATTERN = /^[A-Za-z][A-Za-z0-9]*-[0-9]+$/;
+/** Longest card id a claim may carry (`dispatches.issue_id` is `VARCHAR(32)`). */
+export const ISSUE_ID_MAX_LENGTH = 32;
+/** The transition that claims a card. */
+const CLAIM_ACTION = "pickup";
+/** The transitions that end a sub-agent's hold on a card. */
+const RELEASE_ACTIONS = new Set(["complete", "cancel", "block", "rollback_pickup"]);
+const TRANSITION_PATH = /^\/api\/issues\/([A-Za-z][A-Za-z0-9]*-[0-9]+)\/transition$/;
+/**
+ * Bounds that keep one source's persisted state, and the stats write that carries
+ * it, bounded. A real sub-agent holds one or two cards, so neither is reachable;
+ * the OLDEST entry is the one dropped, because the newest claim is what the next
+ * reply is credited to.
+ */
+export const MAX_HELD_CLAIMS = 50;
+export const MAX_PENDING_TRANSITIONS = 50;
+export function emptyClaimState() {
+    return { held: [], pending: {} };
+}
+function cloneState(s) {
+    return {
+        held: [...s.held],
+        pending: Object.fromEntries(Object.entries(s.pending).map(([id, p]) => [id, { ...p }])),
+    };
+}
+/** The server's answer to a `danxbot_api` call is the JSON text `{"ok": true|false, "status": ...}`; only a leading `ok:true` is a success. */
+const OK_TRUE = /^\s*\{\s*"ok"\s*:\s*true\b/;
+function resultText(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .map((part) => {
+        const p = part;
+        return p !== null && typeof p === "object" && p.type === "text" && typeof p.text === "string" ? p.text : "";
+    })
+        .join("");
+}
+/**
+ * Whether a `tool_result` block reports a successful `danxbot_api` call. Anything
+ * that is not a leading `{"ok": true` is NOT a success: an errored tool call, a
+ * 409's `{"ok": false, ...}`, a refusal, text the tool never produces. A truncated
+ * body still starts with its `ok`, so a large answer reads correctly.
+ */
+function resultSucceeded(block) {
+    if (block.is_error === true)
+        return false;
+    return OK_TRUE.test(resultText(block.content));
+}
+/** The transition a `tool_use` block asks for, or `null` when it is not a claim or release of a card. */
+function transitionOf(block) {
+    if (block.type !== "tool_use" || block.name !== DASHBOARD_API_TOOL_NAME)
+        return null;
+    const input = block.input;
+    if (input === null || typeof input !== "object")
+        return null;
+    if (typeof input.method !== "string" || input.method.toUpperCase() !== "POST")
+        return null;
+    if (typeof input.path !== "string")
+        return null;
+    const match = TRANSITION_PATH.exec(input.path);
+    if (match === null)
+        return null;
+    const body = input.body;
+    if (body === null || typeof body !== "object" || typeof body.action !== "string")
+        return null;
+    if (match[1].length > ISSUE_ID_MAX_LENGTH)
+        return null;
+    if (body.action === CLAIM_ACTION)
+        return { op: "claim", issueId: match[1] };
+    if (RELEASE_ACTIONS.has(body.action))
+        return { op: "release", issueId: match[1] };
+    return null;
+}
+/**
+ * The per-process claim tracker: one state per sub-agent source. Fed every
+ * transcript line by `DispatchUsage` (operator-bridge mode only — the worker never
+ * constructs one), seeded from the stored cursor at attach, and snapshotted per
+ * source for the stats write.
+ */
+export class ClaimTracker {
+    states = new Map();
+    /** Replace a source's state — at attach (the stored cursor's claims) and on a past-EOF reset (empty). */
+    seed(source, state) {
+        if (source === MAIN_SOURCE)
+            return;
+        this.states.set(source, cloneState(state));
+    }
+    /** A copy of the source's state as of the last line fed; empty for a source that holds nothing. */
+    snapshot(source) {
+        const state = this.states.get(source);
+        return state === undefined ? emptyClaimState() : cloneState(state);
+    }
+    /** The card a reply whose first line is read NOW is credited to; `null` when the source holds none. */
+    issueFor(source) {
+        const held = this.states.get(source)?.held;
+        return held === undefined || held.length === 0 ? null : held[held.length - 1];
+    }
+    /** An assistant line's content blocks: remember every claim / release the line asks for until its result arrives. */
+    observeAssistantBlocks(source, blocks) {
+        if (source === MAIN_SOURCE)
+            return;
+        for (const raw of blocks) {
+            const block = raw;
+            if (block === null || typeof block !== "object" || typeof block.id !== "string")
+                continue;
+            const transition = transitionOf(block);
+            if (transition === null)
+                continue;
+            const state = this.stateOf(source);
+            delete state.pending[block.id];
+            state.pending[block.id] = transition;
+            const ids = Object.keys(state.pending);
+            for (const stale of ids.slice(0, Math.max(0, ids.length - MAX_PENDING_TRANSITIONS)))
+                delete state.pending[stale];
+        }
+    }
+    /** A user line's content blocks: settle every remembered transition whose result is here. */
+    observeResultBlocks(source, blocks) {
+        if (source === MAIN_SOURCE)
+            return;
+        const state = this.states.get(source);
+        if (state === undefined)
+            return;
+        for (const raw of blocks) {
+            const block = raw;
+            if (block === null || typeof block !== "object" || block.type !== "tool_result")
+                continue;
+            if (typeof block.tool_use_id !== "string")
+                continue;
+            const pending = state.pending[block.tool_use_id];
+            if (pending === undefined)
+                continue;
+            delete state.pending[block.tool_use_id];
+            if (!resultSucceeded(block))
+                continue;
+            state.held = state.held.filter((id) => id !== pending.issueId);
+            if (pending.op === "claim") {
+                state.held.push(pending.issueId);
+                if (state.held.length > MAX_HELD_CLAIMS)
+                    state.held = state.held.slice(state.held.length - MAX_HELD_CLAIMS);
+            }
+        }
+    }
+    stateOf(source) {
+        let state = this.states.get(source);
+        if (state === undefined) {
+            state = emptyClaimState();
+            this.states.set(source, state);
+        }
+        return state;
+    }
+}

package/dist/dispatch-usage.d.ts

@@ -26,14 +26,39 @@ export interface StatsSink {
 }
 export declare function zeroUsageTotals(): UsageTotals;
 export type FlushOutcome = "ok" | "failed" | "refused";
+/**
+ * DX-3962 - which transcript owner a collector is built for. It decides whether
+ * replies are attributed to cards, and it has no default: every construction names
+ * its path.
+ *
+ *   - `"worker"` - a dispatched worker. NO claim tracker, and every entry's
+ *     `issueId` is `null` whatever the transcript contains (a worker picks its card
+ *     up server-side, its transcript has no pickup, and its dispatch row already
+ *     carries the card). The server refuses a non-null `issueId` from a non-operator
+ *     dispatch by refusing the WHOLE batch, which would stall the worker's stats,
+ *     token ceiling and spend alert on every resend - so a worker is structurally
+ *     unable to send one.
+ *   - `"operator-bridge"` - the desktop bridge of an operator session
+ *     (`danx-dashboard-mcp`'s `session-stats.ts`), the only path that attributes.
+ */
+export type DispatchUsageMode = "worker" | "operator-bridge";
 export declare class DispatchUsage {
     readonly counter: UsageLedgerCounter;
+    /** DX-3962 - `null` in `"worker"` mode: the worker can never create a claim, so it can never send an `issueId`. */
+    private readonly claims;
+    /**
+     * DX-3962 - per source, the claim state as of its `acked` offset: what the next
+     * write reports with `acked`, promoted together with it. The state the tracker
+     * holds NOW belongs to `delivered`, which runs ahead.
+     */
+    private readonly ackedClaims;
     private serverTotals;
     private readonly acked;
     private healthy;
     private refused;
     private started;
     private readonly queue;
+    constructor(mode: DispatchUsageMode);
     /** How to read the watcher's live per-source cursor state. */
     private readCursorState;
     /**
@@ -179,6 +204,7 @@ export declare class DispatchUsage {
      * estimate does not count it twice (see {@link DispatchUsage.unacknowledged}).
      */
     observeEntry(entry: AgentLogEntry, replay?: boolean): void;
+    private observeReply;
     /**
      * 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,8 @@
  * DB-free: runs in the DB-less worker. The sink decides the transport
  * (HTTP on a registered worker, getPool-direct on the dashboard).
  */
-import { UsageLedgerCounter, ledgerLineFromLogEntry, excessUsage, syntheticMessageKey, } from "./usage-ledger.js";
+import { MAIN_SOURCE, UsageLedgerCounter, ledgerLineFromLogEntry, excessUsage, syntheticMessageKey, } 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";
 import { createLogger } from "./internal-logger.js";
@@ -33,26 +34,25 @@ export function zeroUsageTotals() {
         toolCallCount: 0,
     };
 }
-/*
- * DX-2954 — `isPreCardUsageRow` was DELETED here, along with
- * `src/agent/pre-card-lineage.ts` and `markPreCardLineage` below.
- *
- * It answered "did this row count usage before the ledger existed?", which
- * mattered only because a dispatch had nowhere to record HOW FAR it had read:
- * the choice was between re-reading a file from 0 (double-counting) and skipping
- * to its end (losing everything since the last write). `src/agent/start-cursors.ts`
- * dissolves the question — a row WITH stored cursors resumes from them whatever
- * its lineage, and a row WITHOUT any is exactly the case the start order's rule
- * 4 covers. Nothing writes `usage_pre_card_lineage` any more.
- */
 export class DispatchUsage {
     counter = new UsageLedgerCounter();
+    /** DX-3962 - `null` in `"worker"` mode: the worker can never create a claim, so it can never send an `issueId`. */
+    claims;
+    /**
+     * DX-3962 - per source, the claim state as of its `acked` offset: what the next
+     * write reports with `acked`, promoted together with it. The state the tracker
+     * holds NOW belongs to `delivered`, which runs ahead.
+     */
+    ackedClaims = new Map();
     serverTotals = zeroUsageTotals();
     acked = new Map();
     healthy = true;
     refused = false;
     started = false;
     queue = createUsageWriteQueue();
+    constructor(mode) {
+        this.claims = mode === "operator-bridge" ? new ClaimTracker() : null;
+    }
     // ── DX-2954: the cursor half ──────────────────────────────────────────────
     /** How to read the watcher's live per-source cursor state. */
     readCursorState = null;
@@ -109,6 +109,10 @@ export class DispatchUsage {
         this.startCursors = startCursors;
         for (const [source, cursor] of Object.entries(startCursors)) {
             this.ackedCursor.set(source, cursor.acked);
+            // DX-3962 - the watcher reads each source from its stored `acked`, so the tracker starts from the claims
+            // stored with that offset: a pickup before it is never read again.
+            this.ackedClaims.set(source, cursor.claims);
+            this.claims?.seed(source, cursor.claims);
         }
     }
     /**
@@ -125,6 +129,10 @@ 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-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());
+        this.claims?.seed(info.source, emptyClaimState());
     }
     /**
      * DX-2954 — queue running-set changes for the next write.
@@ -210,8 +218,9 @@ export class DispatchUsage {
     buildCursorReports() {
         const reports = {};
         const deliveredAtSend = new Map();
+        const claimsAtSend = new Map();
         if (!this.readCursorState) {
-            return { reports, deliveredAtSend, reportedResets: [], carriesStartCursors: false };
+            return { reports, deliveredAtSend, claimsAtSend, reportedResets: [], carriesStartCursors: false };
         }
         const resetBySource = new Map(this.pastEof.map((p) => [p.source, p]));
         const reportedResets = [];
@@ -221,7 +230,7 @@ export class DispatchUsage {
             for (const [source, start] of Object.entries(this.startCursors)) {
                 if (source in live)
                     continue; // the live state supersedes it once opened
-                reports[source] = { acked: start.acked, delivered: start.delivered };
+                reports[source] = { acked: start.acked, delivered: start.delivered, claims: start.claims };
                 carriesStartCursors = true;
             }
         }
@@ -230,7 +239,13 @@ export class DispatchUsage {
             // under rule 4 must never claim byte 0 as acknowledged, or the next
             // restart would read the whole file and re-sum the history rule 4 skipped.
             const acked = Math.max(this.ackedCursor.get(source) ?? 0, state.startOffset);
-            const report = { acked, delivered: state.delivered };
+            // The claims reported with `acked` are the state AS OF `acked`, never the tracker's current state (which
+            // belongs to `delivered`): a restart resumes at `acked`, so that is the position the claims must describe.
+            const report = {
+                acked,
+                delivered: state.delivered,
+                claims: this.ackedClaims.get(source) ?? emptyClaimState(),
+            };
             const reset = resetBySource.get(source);
             if (reset) {
                 report.pastEof = { storedOffset: reset.storedOffset, fileSize: reset.fileSize };
@@ -238,12 +253,13 @@ export class DispatchUsage {
             }
             reports[source] = report;
             deliveredAtSend.set(source, state.delivered);
+            claimsAtSend.set(source, this.claims?.snapshot(source) ?? emptyClaimState());
         }
         // Only the resets that actually reached a report are consumed. A reset for a
         // source that has left `cursorState()` (its tail dropped on ENOENT) would
         // otherwise be taken and forgotten, leaving the stored `acked` at a value the
         // file can never satisfy.
-        return { reports, deliveredAtSend, reportedResets, carriesStartCursors };
+        return { reports, deliveredAtSend, claimsAtSend, reportedResets, carriesStartCursors };
     }
     /**
      * DX-2954 — whether the cursor half has anything new to say. An IDLE dispatch
@@ -272,9 +288,21 @@ export class DispatchUsage {
      * 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;
+        // 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)
-            return;
+        if (line)
+            this.observeReply(line, replay);
+        // 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
@@ -304,7 +332,7 @@ export class DispatchUsage {
             this.flushBegan = true;
             const changed = this.counter.takeChanged();
             const batches = chunkEntries(changed);
-            const { reports, deliveredAtSend, reportedResets, carriesStartCursors } = this.buildCursorReports();
+            const { reports, deliveredAtSend, claimsAtSend, reportedResets, carriesStartCursors } = this.buildCursorReports();
             // TAKE the queued side data, exactly as `counter.takeChanged()` does, so a
             // hook that fires during the await lands in the NEXT write rather than
             // being silently dropped by a post-write reset of the live array.
@@ -370,6 +398,8 @@ export class DispatchUsage {
                             if (refused.has(source) || resetMidFlight.has(source))
                                 continue;
                             this.ackedCursor.set(source, delivered);
+                            // DX-3962 - the claims advance with the offset they describe, never ahead of it.
+                            this.ackedClaims.set(source, claimsAtSend.get(source));
                         }
                         if (payload.transcriptPath !== undefined)
                             this.transcriptPathSent = true;

package/dist/index.d.ts

@@ -21,6 +21,7 @@ export { truncStr, summarizeToolInput, buildAssistantSummary, buildToolResultSum
 export * from "./usage-ledger.js";
 export * from "./pricing.js";
 export * from "./stats-wire.js";
+export * from "./claim-tracker.js";
 export * from "./dispatch-usage.js";
 export * from "./activity-observer.js";
 export * from "./write-queue.js";

package/dist/index.js

@@ -32,6 +32,7 @@ export * from "./pricing.js";
 // running-set changes, the transcript-side running-set producer, and the FIFO
 // that orders a dispatch's writes.
 export * from "./stats-wire.js";
+export * from "./claim-tracker.js";
 export * from "./dispatch-usage.js";
 export * from "./activity-observer.js";
 export * from "./write-queue.js";

package/dist/stats-wire.d.ts

@@ -10,6 +10,7 @@
  * server, and the response hands them back.
  */
 import type { LedgerEntry, LedgerUsage } from "./usage-ledger.js";
+import { type ClaimState } from "./claim-tracker.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
@@ -27,6 +28,11 @@ export declare const STATS_BATCH_CAP = 500;
  *
  * Lines between them are re-read on a restart and handed on as REPLAYS.
  *
+ * `claims` (DX-3962) is the source's claim state AS OF `acked` - the card(s) the
+ * sub-agent holds, so a collector that resumes at `acked` attributes the next
+ * reply to the right card without re-reading the pickup that sits before it.
+ * A worker's is always empty: it has no claim tracker.
+ *
  * "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.
@@ -34,6 +40,7 @@ export declare const STATS_BATCH_CAP = 500;
 export interface SourceCursor {
     acked: number;
     delivered: number;
+    claims: ClaimState;
 }
 /** DX-2954 — per-source cursors. An absent key means none stored (never 0). */
 export type SourceCursors = Record<string, SourceCursor>;

package/dist/stats-wire.js

@@ -1,3 +1,4 @@
+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
  * session read from the start) is sent as consecutive capped batches, so one
@@ -109,7 +110,52 @@ export function collapseActivityChanges(changes) {
     }
     return [...byKey.values()];
 }
-const CURSOR_KEYS = new Set(["acked", "delivered", "pastEof"]);
+const CURSOR_KEYS = new Set(["acked", "delivered", "claims", "pastEof"]);
+const CLAIM_STATE_KEYS = new Set(["held", "pending"]);
+const PENDING_KEYS = new Set(["op", "issueId"]);
+/** DX-3962 - a card id as a claim or a ledger entry names it: the issue routes' own shape, within the column's width. */
+function isIssueId(v) {
+    return typeof v === "string" && v.length <= ISSUE_ID_MAX_LENGTH && ISSUE_ID_PATTERN.test(v);
+}
+/** DX-3962 - strict parse of one source's claim state (a collector bug, never coerced). */
+function parseClaimState(raw, where) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        throw new StatsPayloadError(where);
+    const c = raw;
+    for (const k of Object.keys(c)) {
+        if (!CLAIM_STATE_KEYS.has(k))
+            throw new StatsPayloadError(`${where}.${k} is not a claim-state field`);
+    }
+    if (!Array.isArray(c.held) || c.held.length > MAX_HELD_CLAIMS || !c.held.every(isIssueId)) {
+        throw new StatsPayloadError(`${where}.held must be at most ${MAX_HELD_CLAIMS} card ids`);
+    }
+    if (!c.pending || typeof c.pending !== "object" || Array.isArray(c.pending)) {
+        throw new StatsPayloadError(`${where}.pending must be an object`);
+    }
+    const pendingEntries = Object.entries(c.pending);
+    if (pendingEntries.length > MAX_PENDING_TRANSITIONS) {
+        throw new StatsPayloadError(`${where}.pending exceeds the cap of ${MAX_PENDING_TRANSITIONS}`);
+    }
+    const pending = {};
+    for (const [toolUseId, value] of pendingEntries) {
+        const w = `${where}.pending[${toolUseId}]`;
+        if (!toolUseId)
+            throw new StatsPayloadError(`${where}.pending key must be a non-empty tool-use id`);
+        if (!value || typeof value !== "object")
+            throw new StatsPayloadError(w);
+        const p = value;
+        for (const k of Object.keys(p)) {
+            if (!PENDING_KEYS.has(k))
+                throw new StatsPayloadError(`${w}.${k} is not a pending-transition field`);
+        }
+        if (p.op !== "claim" && p.op !== "release")
+            throw new StatsPayloadError(`${w}.op must be claim or release`);
+        if (!isIssueId(p.issueId))
+            throw new StatsPayloadError(`${w}.issueId`);
+        pending[toolUseId] = { op: p.op, issueId: p.issueId };
+    }
+    return { held: [...c.held], pending };
+}
 const PAST_EOF_KEYS = new Set(["storedOffset", "fileSize"]);
 function parsePastEof(raw, where) {
     if (!raw || typeof raw !== "object")
@@ -156,7 +202,11 @@ function parseSourceCursors(raw) {
         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 };
+        const report = {
+            acked: c.acked,
+            delivered: c.delivered,
+            claims: parseClaimState(c.claims, `sourceCursors[${source}].claims`),
+        };
         if (c.pastEof !== undefined) {
             report.pastEof = parsePastEof(c.pastEof, `sourceCursors[${source}].pastEof`);
         }
@@ -265,6 +315,10 @@ export function parseStatsPayload(body) {
         if (!Array.isArray(e.toolUseIds) || e.toolUseIds.some((t) => typeof t !== "string")) {
             throw new StatsPayloadError(`${where}.toolUseIds`);
         }
+        // DX-3962 - REQUIRED, `null` or a card id: an entry that omits it comes from a collector that predates
+        // attribution, which the MCP version floor refuses rather than this parser tolerating.
+        if (e.issueId !== null && !isIssueId(e.issueId))
+            throw new StatsPayloadError(`${where}.issueId`);
         return {
             messageId: e.messageId,
             source: e.source,
@@ -279,6 +333,7 @@ export function parseStatsPayload(body) {
                 cacheWrite1h: u.cacheWrite1h,
             },
             toolUseIds: e.toolUseIds,
+            issueId: e.issueId,
         };
     });
     const payload = { entries };

package/dist/usage-ledger.d.ts

@@ -39,6 +39,13 @@ export interface LedgerEntry {
     /** The reply's own transcript timestamp (its FIRST line's), epoch ms. */
     repliedAt: number;
     toolUseIds: string[];
+    /**
+     * DX-3962 - the card this reply is credited to, or `null`. Fixed by the
+     * reply's FIRST line and never changed by a later one. Only an operator-bridge
+     * collector (`DispatchUsage`, `"operator-bridge"` mode) ever sets it; every
+     * other producer of an entry carries `null`.
+     */
+    issueId: string | null;
 }
 /** The fields of one assistant line the counter needs. */
 export interface LedgerLine {
@@ -53,6 +60,8 @@ export interface LedgerLine {
     timestamp: number;
     /** `tool_use` block ids on this line. */
     toolUseIds: readonly string[];
+    /** DX-3962 - the card the line's reply is credited to when this is its first line; see {@link LedgerEntry.issueId}. */
+    issueId: string | null;
 }
 export declare const MAIN_SOURCE = "main";
 /**

package/dist/usage-ledger.js

@@ -140,6 +140,7 @@ export class UsageLedgerCounter {
                 usage,
                 repliedAt: line.timestamp,
                 toolUseIds: [...new Set(line.toolUseIds)],
+                issueId: line.issueId,
             });
             this.changed.add(key);
             return true;
@@ -247,6 +248,7 @@ export function ledgerLineFromRaw(raw, source, byteOffset) {
         toolUseIds: content
             .filter((b) => b.type === "tool_use" && typeof b.id === "string")
             .map((b) => b.id),
+        issueId: null,
     };
 }
 /**
@@ -318,5 +320,6 @@ export function ledgerLineFromLogEntry(entry) {
         usage: hasUsage ? d.usage : undefined,
         timestamp: entry.timestamp,
         toolUseIds,
+        issueId: null,
     };
 }

package/package.json

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