@thehammer/danx-session-telemetry 0.1.44 → 0.1.46

package/dist/dispatch-usage.d.ts

@@ -68,6 +68,13 @@ export declare class DispatchUsage {
      * its own resume point instead of regressing it.
      */
     private readonly ackedCursor;
+    /**
+     * DX-3972 - per source, the `acked` the server holds for this dispatch: the `acked` of the last ACKNOWLEDGED
+     * report that carried the source. It is NOT {@link DispatchUsage.ackedCursor}: that is what the NEXT report
+     * claims (one write behind `delivered`), this is what the LAST one claimed. The terminal catch-up
+     * ({@link DispatchUsage.flushFinal}) is needed exactly while this lags the watcher's `delivered`.
+     */
+    private readonly storedAcked;
     /**
      * DX-2954 (AC 34324) — the cursors this process STARTED from, reported
      * verbatim for every source the watcher has not opened yet until one write
@@ -157,6 +164,18 @@ export declare class DispatchUsage {
      * excess rule) and every side-effecting subscriber skips it — so the cost is
      * one window of re-read, never a double count or a duplicate side effect.
      *
+     * ## The terminal write closes the lag (DX-3972)
+     *
+     * A restart is a crash, and a crash's window is the cost above. A dispatch that
+     * ENDS is not one: its watcher is drained and stopped, so every line it read has been
+     * fed to this collector and nothing will raise a reply any more. The terminal
+     * {@link DispatchUsage.flushFinal} therefore reports `acked` equal to `delivered` for
+     * every source it has opened (see {@link DispatchUsage.catchUpReports}), and a
+     * `--resume` of the session starts at the end of what this dispatch read instead of
+     * replaying the whole file. Without it a dispatch with ONE line-bearing write ended at
+     * `{acked: 0, delivered: EOF}`, and every resume of the session re-read the whole
+     * transcript and re-shipped it into its own `dispatch_logs`.
+     *
      * ## The process-start write carries the STARTING cursors (AC 34324)
      *
      * `attachMonitoringStack` deliberately does NOT await `watcher.start()` —
@@ -195,6 +214,20 @@ export declare class DispatchUsage {
      * is why a write is not forced merely because cursors EXIST.
      */
     private cursorsMoved;
+    /**
+     * DX-3972 - the TERMINAL write's reports: the tick's reports with every source this process has read claiming its
+     * whole `delivered` as `acked`, and the claim state AS OF that offset (the tracker's current state belongs to
+     * `delivered`, so it describes the new `acked` exactly, never a later position). Sources the watcher has not
+     * opened (a start cursor reported verbatim) are untouched: this process read nothing there to claim.
+     */
+    private catchUpReports;
+    /**
+     * DX-3972 - whether the terminal write has anything to say: the server's `acked` still lags what the catch-up now
+     * claims. `ackedCursor` (the NEXT tick's claim) cannot tell, because a dispatch whose last write reported
+     * `delivered` with an older `acked` has `ackedCursor === delivered` and still lags; {@link DispatchUsage.storedAcked}
+     * is what the server holds. A source never reported at all has no entry, so it counts as lagging.
+     */
+    private storedAckedLags;
     /**
      * 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
@@ -221,6 +254,21 @@ export declare class DispatchUsage {
      * acknowledged ahead of the entries it covers.
      */
     flush(sink: StatsSink, dispatchId: string): Promise<FlushOutcome>;
+    /**
+     * DX-3972 - the TERMINAL write: {@link DispatchUsage.flush} that also catches the stored `acked` up to
+     * `delivered` for every source (see {@link DispatchUsage.catchUpReports}). Call it once, when the dispatch ends,
+     * after the watcher is drained and stopped (that is the whole precondition: every line it read has reached this
+     * collector, so `delivered` is covered by the entries this very write carries), and BEFORE the row goes terminal
+     * (the server refuses a terminal dispatch's stats, which would drop the catch-up silently). A write that does not
+     * land promotes nothing, exactly as in a tick; a dispatch already caught up sends no write.
+     *
+     * It does NOT wait for the dispatch's log shipper: the spawn path flushes it before this call, the reattach path
+     * after (`reattach.ts` `_cleanup`), so on a reattach `acked` can claim a line whose `dispatch_logs` row is still in
+     * the shipper's buffer. The shipper is best-effort today and a resume's shipper skips replays either way, so
+     * nothing is lost that was not already; acking only after the log line is acknowledged is DX-2956's change.
+     */
+    flushFinal(sink: StatsSink, dispatchId: string): Promise<FlushOutcome>;
+    private write;
     /** The dispatch's totals as the server last returned them. */
     totals(): UsageTotals;
     /** Window tokens (input + output + cache writes) of the server totals. */

package/dist/dispatch-usage.js

@@ -63,6 +63,13 @@ export class DispatchUsage {
      * its own resume point instead of regressing it.
      */
     ackedCursor = new Map();
+    /**
+     * DX-3972 - per source, the `acked` the server holds for this dispatch: the `acked` of the last ACKNOWLEDGED
+     * report that carried the source. It is NOT {@link DispatchUsage.ackedCursor}: that is what the NEXT report
+     * claims (one write behind `delivered`), this is what the LAST one claimed. The terminal catch-up
+     * ({@link DispatchUsage.flushFinal}) is needed exactly while this lags the watcher's `delivered`.
+     */
+    storedAcked = new Map();
     /**
      * DX-2954 (AC 34324) — the cursors this process STARTED from, reported
      * verbatim for every source the watcher has not opened yet until one write
@@ -186,6 +193,18 @@ export class DispatchUsage {
      * excess rule) and every side-effecting subscriber skips it — so the cost is
      * one window of re-read, never a double count or a duplicate side effect.
      *
+     * ## The terminal write closes the lag (DX-3972)
+     *
+     * A restart is a crash, and a crash's window is the cost above. A dispatch that
+     * ENDS is not one: its watcher is drained and stopped, so every line it read has been
+     * fed to this collector and nothing will raise a reply any more. The terminal
+     * {@link DispatchUsage.flushFinal} therefore reports `acked` equal to `delivered` for
+     * every source it has opened (see {@link DispatchUsage.catchUpReports}), and a
+     * `--resume` of the session starts at the end of what this dispatch read instead of
+     * replaying the whole file. Without it a dispatch with ONE line-bearing write ended at
+     * `{acked: 0, delivered: EOF}`, and every resume of the session re-read the whole
+     * transcript and re-shipped it into its own `dispatch_logs`.
+     *
      * ## The process-start write carries the STARTING cursors (AC 34324)
      *
      * `attachMonitoringStack` deliberately does NOT await `watcher.start()` —
@@ -281,6 +300,32 @@ export class DispatchUsage {
         }
         return false;
     }
+    /**
+     * DX-3972 - the TERMINAL write's reports: the tick's reports with every source this process has read claiming its
+     * whole `delivered` as `acked`, and the claim state AS OF that offset (the tracker's current state belongs to
+     * `delivered`, so it describes the new `acked` exactly, never a later position). Sources the watcher has not
+     * opened (a start cursor reported verbatim) are untouched: this process read nothing there to claim.
+     */
+    catchUpReports(reports, deliveredAtSend, claimsAtSend) {
+        const caughtUp = { ...reports };
+        for (const [source, delivered] of deliveredAtSend) {
+            caughtUp[source] = { ...reports[source], acked: delivered, claims: claimsAtSend.get(source) };
+        }
+        return caughtUp;
+    }
+    /**
+     * DX-3972 - whether the terminal write has anything to say: the server's `acked` still lags what the catch-up now
+     * claims. `ackedCursor` (the NEXT tick's claim) cannot tell, because a dispatch whose last write reported
+     * `delivered` with an older `acked` has `ackedCursor === delivered` and still lags; {@link DispatchUsage.storedAcked}
+     * is what the server holds. A source never reported at all has no entry, so it counts as lagging.
+     */
+    storedAckedLags(reports) {
+        for (const [source, report] of Object.entries(reports)) {
+            if (report.pastEof !== undefined || report.acked !== this.storedAcked.get(source))
+                return true;
+        }
+        return false;
+    }
     /**
      * 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
@@ -329,13 +374,36 @@ export class DispatchUsage {
      * acknowledged ahead of the entries it covers.
      */
     flush(sink, dispatchId) {
+        return this.write(sink, dispatchId, false);
+    }
+    /**
+     * DX-3972 - the TERMINAL write: {@link DispatchUsage.flush} that also catches the stored `acked` up to
+     * `delivered` for every source (see {@link DispatchUsage.catchUpReports}). Call it once, when the dispatch ends,
+     * after the watcher is drained and stopped (that is the whole precondition: every line it read has reached this
+     * collector, so `delivered` is covered by the entries this very write carries), and BEFORE the row goes terminal
+     * (the server refuses a terminal dispatch's stats, which would drop the catch-up silently). A write that does not
+     * land promotes nothing, exactly as in a tick; a dispatch already caught up sends no write.
+     *
+     * It does NOT wait for the dispatch's log shipper: the spawn path flushes it before this call, the reattach path
+     * after (`reattach.ts` `_cleanup`), so on a reattach `acked` can claim a line whose `dispatch_logs` row is still in
+     * the shipper's buffer. The shipper is best-effort today and a resume's shipper skips replays either way, so
+     * nothing is lost that was not already; acking only after the log line is acknowledged is DX-2956's change.
+     */
+    flushFinal(sink, dispatchId) {
+        return this.write(sink, dispatchId, true);
+    }
+    write(sink, dispatchId, catchUp) {
         return this.queue(async () => {
             if (this.refused)
                 return "refused";
             this.flushBegan = true;
             const changed = this.counter.takeChanged();
             const batches = chunkEntries(changed);
-            const { reports, deliveredAtSend, claimsAtSend, reportedResets, carriesStartCursors } = this.buildCursorReports();
+            const built = this.buildCursorReports();
+            const { deliveredAtSend, claimsAtSend, reportedResets, carriesStartCursors } = built;
+            const reports = catchUp
+                ? this.catchUpReports(built.reports, deliveredAtSend, claimsAtSend)
+                : built.reports;
             // 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.
@@ -361,7 +429,7 @@ export class DispatchUsage {
             // whose last batch failed must still deliver it on a later, otherwise idle
             // tick.
             const haveSideData = carriesStartCursors ||
-                this.cursorsMoved(reports) ||
+                (catchUp ? this.storedAckedLags(reports) : this.cursorsMoved(reports)) ||
                 activities.length > 0 ||
                 (this.transcriptPath !== null && !this.transcriptPathSent);
             if (batches.length === 0 && (!this.started || haveSideData))
@@ -390,6 +458,11 @@ export class DispatchUsage {
                         // there. A source the server REFUSED as a regression keeps its own
                         // stored value, so we must not promote ours past it.
                         const refused = new Set(res.cursorRegressions);
+                        // DX-3972 - what the server now holds as each reported source's `acked` (a refused source kept its own).
+                        for (const [source, report] of Object.entries(reports)) {
+                            if (!refused.has(source))
+                                this.storedAcked.set(source, report.acked);
+                        }
                         // A source whose file was found truncated WHILE this write was in
                         // flight must NOT have its floor promoted. `recordPastEof` dropped
                         // that floor to 0 on purpose; re-raising it here would make the next

package/dist/stats-wire.d.ts

@@ -135,20 +135,6 @@ export type ActivityEndStatus = (typeof ACTIVITY_END_STATUSES)[number];
 export declare const CURRENT_ACTIVITY_MAX_CHARS = 120;
 export interface StatsPayload {
     entries: LedgerEntry[];
-    /**
-     * DX-2963 — the worker applied the end-of-file rule (its own row or its
-     * predecessor's is pre-card), so the dispatch inherits pre-card lineage.
-     *
-     * DX-2954 RETIRED this field (DX-3286 removes it): the cursor start order replaces the rule it
-     * carried. It is still ACCEPTED, and ignored, for exactly one release — a
-     * deploy restarts the dashboard before it relaunches the workers, so for a
-     * window old workers send it to the new server, and refusing it would throw
-     * away their terminal status. A payload carrying it records one visible
-     * `stats_field_ignored` event per dispatch. The release after this one drops
-     * the field, the `usage_pre_card_lineage` column and the two
-     * `handleReadDispatch` fields together.
-     */
-    preCardLineage?: true;
     /**
      * DX-2954 — this collector's cursors for every source it has opened. Optional
      * because an old worker in the deploy window sends none; absent means

package/dist/stats-wire.js

@@ -46,13 +46,10 @@ const USAGE_KEYS = ["input", "output", "cacheRead", "cacheWrite5m", "cacheWrite1
  * consumer) fails loud instead of being silently dropped — the pre-DX-2954
  * parser rebuilt the object field by field and swallowed every extra key.
  *
- * `preCardLineage` is on this list for exactly one release, until DX-3286 (see its doc on
- * {@link StatsPayload}); `transcriptPath` is the ONE key allowed to carry a
- * filesystem path.
+ * `transcriptPath` is the ONE key allowed to carry a filesystem path.
  */
 const STATS_PAYLOAD_KEYS = new Set([
     "entries",
-    "preCardLineage",
     "sourceCursors",
     "activities",
     "transcriptPath",
@@ -364,9 +361,6 @@ export function parseStatsPayload(body) {
     if (b.entries.length > STATS_BATCH_CAP) {
         throw new StatsPayloadError(`entries exceeds the cap of ${STATS_BATCH_CAP}`);
     }
-    if (b.preCardLineage !== undefined && b.preCardLineage !== true) {
-        throw new StatsPayloadError("preCardLineage must be true when present");
-    }
     if (b.transcriptPath !== undefined && (typeof b.transcriptPath !== "string" || !b.transcriptPath)) {
         throw new StatsPayloadError("transcriptPath must be a non-empty string when present");
     }
@@ -427,8 +421,6 @@ export function parseStatsPayload(body) {
         };
     });
     const payload = { entries };
-    if (b.preCardLineage === true)
-        payload.preCardLineage = true;
     if (b.sourceCursors !== undefined)
         payload.sourceCursors = parseSourceCursors(b.sourceCursors);
     if (b.activities !== undefined)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/danx-session-telemetry",
-  "version": "0.1.44",
+  "version": "0.1.46",
   "description": "Shared Claude Code transcript collector (DX-2962) — incremental JSONL tailing for the danxbot worker and the danx-dashboard-mcp MCP server's relay, so both run identical collector code.",
   "license": "MIT",
   "type": "module",

package/dist/.source-hash

@@ -1 +0,0 @@
-a9b13a1f70c9a71a4aafa832d67aadc10e9e2c998beaf0230f13903d39c2d4c4