@thehammer/danx-session-telemetry 0.1.16 → 0.1.18

package/dist/activity-observer.d.ts

@@ -11,36 +11,42 @@
  *
  * Claude Code's `SubagentStart` / `SubagentStop` hooks carry strictly more (an
  * `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).
+ * module cannot supply — a FINISH). They ship from the danxbot plugin in the
+ * claude-plugins repo (DX-3284, `danxbot/scripts/activity-report.mjs`), run the
+ * `activity` subcommand of `@thehammer/danx-dashboard-mcp`, and reach the server
+ * through `POST /api/plan-sessions/me/activity` — which writes the SAME
+ * `dispatch_activities` rows through the same one server writer.
  *
- * So the transcript is the producer, and the hooks are an ENRICHMENT layered on
- * the same rows:
+ * The transcript stays the producer because it needs no hook to be installed: a
+ * session with no plugin, and every WORKER dispatch, still gets a start row for
+ * each sub-agent from here. The hooks are an ENRICHMENT layered on the same rows:
  *
  * | Signal | Sub-agent start | Sub-agent finish | Background script |
  * |---|---|---|---|
  * | Transcript (here) | file discovered | dispatch terminal (`finishOpenActivities`) | not visible |
- * | Hooks (DX-3284) | `SubagentStart` | `SubagentStop` | `PostToolUse` start; end at dispatch terminal (no documented completion event) |
+ * | Hooks (DX-3284, operator sessions) | `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.
+ * **Where "running" closes.** An operator session's sub-agent closes at its
+ * `SubagentStop` hook. A WORKER dispatch has no hook reporting yet
+ * (`/me/activity` refuses a worker's session id as `session_is_worker`), so its
+ * sub-agents stay 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. A worker-side `SubagentStop` report is the
+ * fix, and is not built.
  *
  * ## Why the two producers cannot double-count
  *
  * Every row is an upsert keyed `(dispatch_id, kind, activity_id)`, and BOTH
  * producers derive `activity_id` from the same thing: the sub-agent's transcript
- * file basename. The watcher has it directly; a hook has it as the basename of
- * its `transcript_path`. That is also the key the ledger credits the sub-agent's
- * tokens under, which is how per-sub-agent tokens join to the running set
- * without this table carrying a token column.
+ * file basename, `agent-<agent_id>`. The watcher has it directly; a hook has the
+ * `agent_id` and builds the same basename from it (`subagentActivityId` in
+ * danx-dashboard-mcp's `activity.ts`). A hook's `transcript_path` is NOT the
+ * sub-agent's file — on these events it is the MAIN session's transcript, and only
+ * `SubagentStop` also carries the sub-agent's own as `agent_transcript_path`,
+ * which the subcommand uses to refuse a key that disagrees. That basename is also
+ * the key the ledger credits the sub-agent's tokens under, which is how
+ * per-sub-agent tokens join to the running set without this table carrying a
+ * token column.
  *
  * ## What this module deliberately does NOT do
  *
@@ -49,7 +55,7 @@
  * 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`),
- * unless DX-3284's `SubagentStop` hook closes a row first.
+ * unless the `SubagentStop` hook (DX-3284) 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

@@ -50,6 +50,13 @@ export declare class DispatchUsage {
      */
     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;
     /**
@@ -134,7 +141,7 @@ export declare class DispatchUsage {
      *
      * 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 one write carrying them has landed. That is
+     * 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

package/dist/dispatch-usage.js

@@ -70,6 +70,13 @@ export class DispatchUsage {
      */
     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 = [];
     /**
@@ -93,6 +100,11 @@ 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)) {
@@ -173,7 +185,7 @@ export class DispatchUsage {
      *
      * 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 one write carrying them has landed. That is
+     * 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
@@ -289,6 +301,7 @@ 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, carriesStartCursors } = this.buildCursorReports();
@@ -360,6 +373,9 @@ 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;
                     }
                 }

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/dist/stats-wire.d.ts

@@ -61,12 +61,14 @@ export type SourceCursorReports = Record<string, SourceCursorReport>;
  * DX-2954 — the running set's two kinds. `agent` is a sub-agent, produced from
  * the TRANSCRIPT: one row per sub-agent transcript file the session-log watcher
  * discovers (`packages/danx-session-telemetry/src/activity-observer.ts`; orchestrator decision, DX-2954
- * comment 8004). `bash` is a background script; nothing produces it yet — the
- * hook-side producer (`PostToolUse` on a backgrounded Bash call) is DX-3284's.
- * No hook event observes a background shell FINISHING (verified against the
- * hooks reference — see the Step 0 note on DX-2954), so an open row of either
- * kind is closed by the dispatch's own terminal write, never by inferring an
- * end from transcript lines.
+ * comment 8004), and — for an operator session — from the plugin's
+ * `SubagentStart` / `SubagentStop` hooks, which add the finish. `bash` is a
+ * background script, produced only by the plugin's `PostToolUse` hook on a
+ * backgrounded Bash call (DX-3284; the transcript cannot see it). No hook event
+ * observes a background shell FINISHING (verified against the hooks reference —
+ * see the Step 0 note on DX-2954), so an open `bash` row is closed by the
+ * dispatch's own terminal write, never by inferring an end from transcript
+ * lines.
  */
 export declare const ACTIVITY_KINDS: readonly ["agent", "bash"];
 export type ActivityKind = (typeof ACTIVITY_KINDS)[number];
@@ -76,12 +78,13 @@ export type ActivityKind = (typeof ACTIVITY_KINDS)[number];
  * fires twice, or a batch resent after a failed flush, must not duplicate it.
  *
  * `activityId` for a sub-agent is its transcript file's basename
- * (`agent-<hash>`) — the SAME value the ledger credits its tokens under as
+ * (`agent-<agent_id>`) — the SAME value the ledger credits its tokens under as
  * `source`, which is how per-sub-agent tokens join to the running set without
- * this table carrying a token column. Any future producer (DX-3284's hooks)
- * must derive it the same way — the basename of the hook's `transcript_path`,
- * never the hook's `agent_id` — or it upserts a duplicate row. For a
- * background script it is the Bash call's `tool_use_id`.
+ * this table carrying a token column. A hook producer builds it from the hook's
+ * `agent_id` as `agent-${agent_id}` (never the bare `agent_id`, and never from
+ * `transcript_path`, which on these events is the MAIN session's transcript) or
+ * it upserts a duplicate row. For a background script it is the Bash call's
+ * `tool_use_id`.
  */
 export interface ActivityChange {
     kind: ActivityKind;

package/dist/stats-wire.js

@@ -9,12 +9,14 @@ export const STATS_BATCH_CAP = 500;
  * DX-2954 — the running set's two kinds. `agent` is a sub-agent, produced from
  * the TRANSCRIPT: one row per sub-agent transcript file the session-log watcher
  * discovers (`packages/danx-session-telemetry/src/activity-observer.ts`; orchestrator decision, DX-2954
- * comment 8004). `bash` is a background script; nothing produces it yet — the
- * hook-side producer (`PostToolUse` on a backgrounded Bash call) is DX-3284's.
- * No hook event observes a background shell FINISHING (verified against the
- * hooks reference — see the Step 0 note on DX-2954), so an open row of either
- * kind is closed by the dispatch's own terminal write, never by inferring an
- * end from transcript lines.
+ * comment 8004), and — for an operator session — from the plugin's
+ * `SubagentStart` / `SubagentStop` hooks, which add the finish. `bash` is a
+ * background script, produced only by the plugin's `PostToolUse` hook on a
+ * backgrounded Bash call (DX-3284; the transcript cannot see it). No hook event
+ * observes a background shell FINISHING (verified against the hooks reference —
+ * see the Step 0 note on DX-2954), so an open `bash` row is closed by the
+ * dispatch's own terminal write, never by inferring an end from transcript
+ * lines.
  */
 export const ACTIVITY_KINDS = ["agent", "bash"];
 export function chunkEntries(entries, cap = STATS_BATCH_CAP) {

package/package.json

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