@thehammer/danx-session-telemetry 0.1.15 → 0.1.17

package/dist/activity-observer.d.ts

@@ -7,16 +7,17 @@
  * signal danxbot owns end-to-end: the session-log watcher discovering a
  * sub-agent's transcript file and then tailing it.
  *
- * ## Why the transcript, not a hook
+ * ## Why the transcript, and where the hooks come in
  *
  * Claude Code's `SubagentStart` / `SubagentStop` hooks carry strictly more (an
- * `agent_type` before the sub-agent has written anything; and, for a background
- * `Bash` shell, the ONLY finish signal that exists at all). But those hooks ship
- * from the plugin, which lives in a repo danxbot has no board for — so they
- * cannot land in this card (see DX-3284). Keying the running set solely on them
- * would mean shipping a set that is permanently empty: `subagent_count` would read 0 on
- * every dispatch, which is a REGRESSION against the transcript-derived counter
- * this card replaced, not a deferral.
+ * `agent_type` before the sub-agent has written anything, and — the part this
+ * module cannot supply — a FINISH). Those hooks ship from the danxbot plugin in
+ * the claude-plugins repo, and DX-3284 builds them, next. They were not built in
+ * DX-2954 itself, but not because a plugin change cannot ship from a danxbot
+ * card: DX-2954's own `transcript_path` change shipped as claude-plugins
+ * `c0c134d`. Keying the running set solely on them before they exist would ship
+ * a set that is permanently empty (`subagent_count` 0 on every dispatch, a
+ * REGRESSION against the transcript-derived counter this replaced).
  *
  * So the transcript is the producer, and the hooks are an ENRICHMENT layered on
  * the same rows:
@@ -24,7 +25,13 @@
  * | Signal | Sub-agent start | Sub-agent finish | Background script |
  * |---|---|---|---|
  * | Transcript (here) | file discovered | dispatch terminal (`finishOpenActivities`) | not visible |
- * | Hooks (DX-3284) | `SubagentStart` | `SubagentStop` | `PostToolUse` + its own stop |
+ * | Hooks (DX-3284) | `SubagentStart` | `SubagentStop` | `PostToolUse` start; end at dispatch terminal (no documented completion event) |
+ *
+ * **Until DX-3284 lands, "running" over-counts.** With no finish signal, every
+ * sub-agent this dispatch ever started stays in the running set until the
+ * dispatch itself ends, and the silent-too-long warning fires
+ * `RUNNING_ACTIVITY_SILENT_AFTER_MS` after a sub-agent that has in fact
+ * finished. `SubagentStop` is what closes that gap.
  *
  * ## Why the two producers cannot double-count
  *
@@ -41,9 +48,8 @@
  * signal — a finished sub-agent's file simply stops growing, which is
  * indistinguishable from a slow one. Guessing a finish from an idle gap would
  * mark a long-thinking sub-agent as complete. So open rows are closed exactly
- * once, at the dispatch's own terminal transition (`finishOpenActivities`), and
- * until DX-3284 lands the honest reading of a long-idle running row is what
- * `quietest_running_at` is for.
+ * once, at the dispatch's own terminal transition (`finishOpenActivities`),
+ * unless DX-3284's `SubagentStop` hook closes a row first.
  */
 import type { ActivityChange } from "./stats-wire.js";
 import type { EntryMeta, SourceDiscoveredInfo } from "./session-log-watcher.js";

package/dist/dispatch-usage.d.ts

@@ -43,6 +43,20 @@ export declare class DispatchUsage {
      * its own resume point instead of regressing it.
      */
     private readonly ackedCursor;
+    /**
+     * DX-2954 (AC 34324) — the cursors this process STARTED from, reported
+     * verbatim for every source the watcher has not opened yet until one write
+     * carrying them has landed. See {@link DispatchUsage.buildCursorReports}.
+     */
+    private startCursors;
+    private startCursorsPersisted;
+    /**
+     * DX-2954 — set the moment the first flush begins. `attachCursors` after that
+     * point would set the starting cursors AFTER a write that carried none, and
+     * `startCursorsPersisted` (set by any landed write) would then keep them from
+     * ever being carried — the exact AC 34324 loss, silently. So it fails loud.
+     */
+    private flushBegan;
     /** Past-EOF resets to report once, then forget. */
     private pastEof;
     /**
@@ -118,25 +132,36 @@ 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.
      *
-     * ## KNOWN GAP: the process-start write carries no cursors
+     * ## The process-start write carries the STARTING cursors (AC 34324)
      *
      * `attachMonitoringStack` deliberately does NOT await `watcher.start()` —
      * file discovery polls for up to 180 s and must not block the spawn — and the
      * process-start stats write fires immediately after it. At that moment the
-     * watcher has opened no file, so `cursorState()` is empty and this returns no
-     * reports. Cursors first reach the server on the write AFTER discovery, one
-     * stats tick (15-30 s) later.
+     * watcher has opened no file, so its live `cursorState()` is empty.
+     *
+     * So every source in the cursors this process STARTED from that the watcher
+     * has not opened yet is reported VERBATIM — the exact `{acked, delivered}`
+     * pair it resumed from — until a write that carries them has landed. That is
+     * what makes "every attach persists its starting cursors" true on the FIRST
+     * write rather than one stats tick (15-30 s) later: a reattach of this row
+     * inside its first interval reads them back (start-order rule 1) and starts
+     * exactly where this process did, instead of finding no cursor, resolving
+     * rule 4 and skipping every line written since spawn. A fresh session's
+     * starting cursor is explicit too (`resolveStartCursors` rule 3 returns the
+     * main source at 0), and a `--resume`'s is its predecessor's (rule 2).
+     *
+     * Verbatim is the only honest claim for a source this process has not read:
+     * a higher `acked` would let a restart skip the replay window it has not
+     * re-credited, a lower one is refused as a regression. For the same reason
+     * the start write does not PROMOTE such a source's acknowledged floor — it
+     * delivered nothing there — so it stays out of `deliveredAtSend`.
      *
-     * The bound this puts on the card's "every attach persists its starting
-     * cursors in its first stats write": a dispatch that dies inside its first
-     * stats interval stores no cursor at all, so a later dispatch continuing its
-     * session resolves start-order rule 4 (existing files at EOF) and does not
-     * count that first interval's usage. The ledger keeps this from ever
-     * DOUBLE-counting; the cost is the same bounded loss the card already accepts
-     * for the deploy transition. Closing it properly means persisting the starting
-     * cursor on discovery rather than on the next tick — a watcher-discovery
-     * callback wired into the ordered stats channel — which is a separate change,
-     * not something to bolt onto the flush path.
+     * The one case with nothing to carry is rule 4 (a continuing dispatch with no
+     * cursor for ANY source): its start is "each existing file's end at
+     * discovery", which does not exist until discovery runs. Its cursors reach
+     * the server on the first write after discovery. Rule 4 is the pre-card
+     * deploy transition only — every dispatch since this card stores cursors on
+     * its first write — so that bounded window is the one the card accepts.
      */
     private buildCursorReports;
     /**

package/dist/dispatch-usage.js

@@ -63,6 +63,20 @@ export class DispatchUsage {
      * its own resume point instead of regressing it.
      */
     ackedCursor = 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
+     * carrying them has landed. See {@link DispatchUsage.buildCursorReports}.
+     */
+    startCursors = {};
+    startCursorsPersisted = false;
+    /**
+     * DX-2954 — set the moment the first flush begins. `attachCursors` after that
+     * point would set the starting cursors AFTER a write that carried none, and
+     * `startCursorsPersisted` (set by any landed write) would then keep them from
+     * ever being carried — the exact AC 34324 loss, silently. So it fails loud.
+     */
+    flushBegan = false;
     /** Past-EOF resets to report once, then forget. */
     pastEof = [];
     /**
@@ -86,7 +100,13 @@ export class DispatchUsage {
      * each write.
      */
     attachCursors(readCursorState, startCursors) {
+        // DX-2954 (AC 34324): the starting cursors ride the process-start write, so
+        // they must be attached BEFORE any write is attempted.
+        if (this.flushBegan) {
+            throw new Error("DispatchUsage.attachCursors: called after the first stats write began — the starting cursors would never be persisted");
+        }
         this.readCursorState = readCursorState;
+        this.startCursors = startCursors;
         for (const [source, cursor] of Object.entries(startCursors)) {
             this.ackedCursor.set(source, cursor.acked);
         }
@@ -156,34 +176,56 @@ 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.
      *
-     * ## KNOWN GAP: the process-start write carries no cursors
+     * ## The process-start write carries the STARTING cursors (AC 34324)
      *
      * `attachMonitoringStack` deliberately does NOT await `watcher.start()` —
      * file discovery polls for up to 180 s and must not block the spawn — and the
      * process-start stats write fires immediately after it. At that moment the
-     * watcher has opened no file, so `cursorState()` is empty and this returns no
-     * reports. Cursors first reach the server on the write AFTER discovery, one
-     * stats tick (15-30 s) later.
+     * watcher has opened no file, so its live `cursorState()` is empty.
      *
-     * The bound this puts on the card's "every attach persists its starting
-     * cursors in its first stats write": a dispatch that dies inside its first
-     * stats interval stores no cursor at all, so a later dispatch continuing its
-     * session resolves start-order rule 4 (existing files at EOF) and does not
-     * count that first interval's usage. The ledger keeps this from ever
-     * DOUBLE-counting; the cost is the same bounded loss the card already accepts
-     * for the deploy transition. Closing it properly means persisting the starting
-     * cursor on discovery rather than on the next tick — a watcher-discovery
-     * callback wired into the ordered stats channel — which is a separate change,
-     * not something to bolt onto the flush path.
+     * So every source in the cursors this process STARTED from that the watcher
+     * has not opened yet is reported VERBATIM — the exact `{acked, delivered}`
+     * pair it resumed from — until a write that carries them has landed. That is
+     * what makes "every attach persists its starting cursors" true on the FIRST
+     * write rather than one stats tick (15-30 s) later: a reattach of this row
+     * inside its first interval reads them back (start-order rule 1) and starts
+     * exactly where this process did, instead of finding no cursor, resolving
+     * rule 4 and skipping every line written since spawn. A fresh session's
+     * starting cursor is explicit too (`resolveStartCursors` rule 3 returns the
+     * main source at 0), and a `--resume`'s is its predecessor's (rule 2).
+     *
+     * Verbatim is the only honest claim for a source this process has not read:
+     * a higher `acked` would let a restart skip the replay window it has not
+     * re-credited, a lower one is refused as a regression. For the same reason
+     * the start write does not PROMOTE such a source's acknowledged floor — it
+     * delivered nothing there — so it stays out of `deliveredAtSend`.
+     *
+     * The one case with nothing to carry is rule 4 (a continuing dispatch with no
+     * cursor for ANY source): its start is "each existing file's end at
+     * discovery", which does not exist until discovery runs. Its cursors reach
+     * the server on the first write after discovery. Rule 4 is the pre-card
+     * deploy transition only — every dispatch since this card stores cursors on
+     * its first write — so that bounded window is the one the card accepts.
      */
     buildCursorReports() {
         const reports = {};
         const deliveredAtSend = new Map();
-        if (!this.readCursorState)
-            return { reports, deliveredAtSend, reportedResets: [] };
+        if (!this.readCursorState) {
+            return { reports, deliveredAtSend, reportedResets: [], carriesStartCursors: false };
+        }
         const resetBySource = new Map(this.pastEof.map((p) => [p.source, p]));
         const reportedResets = [];
-        for (const [source, state] of Object.entries(this.readCursorState())) {
+        const live = this.readCursorState();
+        let carriesStartCursors = false;
+        if (!this.startCursorsPersisted) {
+            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 };
+                carriesStartCursors = true;
+            }
+        }
+        for (const [source, state] of Object.entries(live)) {
             // `acked` floors at the source's START offset: a source opened at EOF
             // 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.
@@ -201,7 +243,7 @@ export class DispatchUsage {
         // 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 };
+        return { reports, deliveredAtSend, reportedResets, carriesStartCursors };
     }
     /**
      * DX-2954 — whether the cursor half has anything new to say. An IDLE dispatch
@@ -259,9 +301,10 @@ export class DispatchUsage {
         return this.queue(async () => {
             if (this.refused)
                 return "refused";
+            this.flushBegan = true;
             const changed = this.counter.takeChanged();
             const batches = chunkEntries(changed);
-            const { reports, deliveredAtSend, reportedResets } = this.buildCursorReports();
+            const { reports, deliveredAtSend, 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.
@@ -282,7 +325,12 @@ export class DispatchUsage {
             const pastEofSent = reportedResets;
             const sentResets = new Set(reportedResets);
             this.pastEof = this.pastEof.filter((p) => !sentResets.has(p));
-            const haveSideData = this.cursorsMoved(reports) ||
+            // `carriesStartCursors` forces the write on its own: a starting pair like
+            // `{acked: 0, delivered: 0}` never looks "moved", and a process-start write
+            // whose last batch failed must still deliver it on a later, otherwise idle
+            // tick.
+            const haveSideData = carriesStartCursors ||
+                this.cursorsMoved(reports) ||
                 activities.length > 0 ||
                 (this.transcriptPath !== null && !this.transcriptPathSent);
             if (batches.length === 0 && (!this.started || haveSideData))
@@ -325,6 +373,10 @@ export class DispatchUsage {
                         }
                         if (payload.transcriptPath !== undefined)
                             this.transcriptPathSent = true;
+                        // Safe on ANY landed write: `attachCursors` refuses to run after the
+                        // first flush began, so every starting cursor was either carried by
+                        // this write or is superseded by a live one that this write reported.
+                        this.startCursorsPersisted = true;
                     }
                 }
                 catch (err) {

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

@@ -76,7 +76,7 @@ export interface SessionLogWatcherOptions {
      * That lost every line between the last write and the restart; a cursor does
      * not.
      */
-    startCursors?: Record<string, SourceCursorStart>;
+    startCursors: Record<string, SourceCursorStart>;
     /**
      * DX-2954 — rule 4 of the start order: start every ALREADY-EXISTING file at
      * its current end.

package/dist/session-log-watcher.js

@@ -507,7 +507,7 @@ export class SessionLogWatcher {
         this.sessionId = options.sessionId;
         this.dispatchId = options.dispatchId;
         this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
-        this.startCursors = options.startCursors ?? {};
+        this.startCursors = options.startCursors;
         this.startExistingFilesAtEof = options.startExistingFilesAtEof ?? false;
         this.onCursorPastEof = options.onCursorPastEof;
         this.onSourceDiscovered = options.onSourceDiscovered;

package/package.json

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