@thehammer/danx-session-telemetry 0.1.44 → 0.1.45

package/dist/.source-hash

@@ -1 +1 @@
-a9b13a1f70c9a71a4aafa832d67aadc10e9e2c998beaf0230f13903d39c2d4c4
+3d2e532980e05f6c38b15f2a85eca3c84c3488c2afec7c285c5ac8a5c20ee254

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/package.json

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