@thehammer/danx-session-telemetry 0.1.14 → 0.1.15

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

@@ -28,7 +28,21 @@ import type { AgentLogEntry } from "./types.js";
  * wrong file (e.g., an active human session).
  */
 export declare const DISPATCH_TAG_PREFIX = "<!-- danxbot-dispatch:";
-export type EntryConsumer = (entry: AgentLogEntry) => void;
+/**
+ * A consumer of transcript lines.
+ *
+ * DX-2954 added the second argument. A consumer that ignores it behaves exactly
+ * as before; a consumer with a SIDE EFFECT must read `meta.replay` and skip a
+ * re-read line (see {@link EntryMeta.replay}).
+ */
+export type EntryConsumer = (entry: AgentLogEntry, meta: EntryMeta) => void;
+/**
+ * DX-2954 — the ONE replay gate every side-effecting transcript subscriber goes
+ * through (Slack progress, the gpt-manager forwarder): it hands on only lines
+ * read for the FIRST time. A replay was already handed to the previous
+ * incarnation's subscribers, so acting on it again is a duplicate post/event.
+ */
+export declare function skipReplays(consumer: (entry: AgentLogEntry) => void): EntryConsumer;
 export interface SessionLogWatcherOptions {
     /** Working directory the agent was launched in. Used to derive the session directory. */
     cwd: string;
@@ -46,32 +60,125 @@ export interface SessionLogWatcherOptions {
      */
     dispatchId?: string;
     /**
-     * Skip every byte on disk at attach time and tail strictly forward from
-     * EOF. Set whenever the bytes already on disk belong to a PRIOR dispatch's
-     * accounting, so replaying them would double-count that dispatch's usage /
-     * tool calls against this one:
-     *   - the Phase 2c (DX-209) reattach pass — a prior worker incarnation
-     *     already accumulated the JSONL into the row's counters; and
-     *   - a `claude --resume <id>` resume (DX-2583) — claude appends this
-     *     dispatch's turns to the SAME session JSONL the prior dispatch(es)
-     *     already filled, so tailing from byte 0 re-sums the whole session's
-     *     history onto a fresh row (`attach-monitoring-stack.ts` sets this via
-     *     `seedFromEof` when `resumeSessionId` is present).
-     * Default `false` — a genuinely fresh spawn writes a brand-new file whose
-     * EOF is 0, so it ingests its own full file from the start.
+     * DX-2954 — where each source resumes: the cursors the SERVER has stored for
+     * this dispatch, keyed by source ({@link MAIN_SOURCE} for the main transcript,
+     * the sub-agent id for a sub-agent file).
+     *
+     * An ABSENT source key means no cursor is stored for it — never "start at 0".
+     * The two are different: 0 is a legitimate stored cursor meaning "start of
+     * file", and CP1 forbids defaulting a missing persisted value. See
+     * {@link SessionLogWatcherOptions.startExistingFilesAtEof} and the start-order
+     * table on {@link SessionLogWatcher} for what happens when a source has none.
+     *
+     * This REPLACED the pre-DX-2954 `fromEof` / `existingSubagentFilesFromEof`
+     * pair, which skipped straight to a file's end on every reattach and every
+     * `--resume` because there was nowhere to record how far a reader had got.
+     * That lost every line between the last write and the restart; a cursor does
+     * not.
+     */
+    startCursors?: Record<string, SourceCursorStart>;
+    /**
+     * DX-2954 — rule 4 of the start order: start every ALREADY-EXISTING file at
+     * its current end.
+     *
+     * Set ONLY by a WORKER dispatch that continues a session and has no cursor
+     * for ANY source — a row from before this card shipped, or a `--resume` whose
+     * predecessor predates it. Those files hold a prior dispatch's accounting with
+     * no ledger rows to dedupe against, so reading them from 0 re-sums the whole
+     * session (the 421M-cache-read inflation of DX-2583). A file that appears
+     * LATER is genuinely new and still starts at 0.
+     *
+     * It must never be set alongside cursors for some sources: rule 5 says a
+     * sub-agent file that appeared after the last stats write, on a dispatch that
+     * HAS cursors, starts at 0 so none of its lines are lost.
      */
-    fromEof?: boolean;
+    startExistingFilesAtEof?: boolean;
     /**
-     * DX-2963 — the end-of-file rule for PRE-CARD lineage. When set, every
-     * sub-agent file that ALREADY EXISTS on the first sub-agent discovery pass
-     * is opened at its end (like the main file under `fromEof`); a sub-agent
-     * file that appears later is read from byte 0. Set by the worker when its
-     * own dispatch row, or its predecessor's, is pre-card (stored totals with
-     * no ledger rows to dedupe against), so replies those totals already count
-     * are never credited again. DX-2954 replaces this with its cursor start
-     * order and deletes it.
+     * DX-2954 — a stored cursor was PAST the end of its file (the file was
+     * replaced or truncated), so that source restarted at 0.
+     *
+     * Without this the watcher would silently tail nothing for the rest of the
+     * dispatch: its `size <= byteOffset` early return is indistinguishable from
+     * "no new bytes". The caller records a visible `transcript_cursor_past_eof`
+     * event with both numbers and marks the reset in its next stats write, which
+     * is the ONE sanctioned backwards move of a stored `acked`.
      */
-    existingSubagentFilesFromEof?: boolean;
+    onCursorPastEof?: (info: CursorPastEofInfo) => void;
+    /**
+     * DX-2954 — a sub-agent transcript just came under tail for the first time,
+     * i.e. a sub-agent of this dispatch is RUNNING.
+     *
+     * This is the transcript-side producer of the dispatch's running set. It
+     * reports the sub-agent's ledger source key, which is the same value its
+     * `dispatch_activities.activity_id` and its per-source token total join on —
+     * so a hook-side producer reporting the same sub-agent by its
+     * `transcript_path` resolves to this same id and upserts the SAME row rather
+     * than a duplicate.
+     *
+     * Fired once per source, from the discovery pass, for sub-agent files only —
+     * never for the main transcript, which is the dispatch itself, not an activity
+     * within it.
+     */
+    onSourceDiscovered?: (info: SourceDiscoveredInfo) => void;
+}
+/** DX-2954 — one source's stored cursor pair, as a collector starts from it. */
+export interface SourceCursorStart {
+    /** The resume point: read on from here. */
+    acked: number;
+    /**
+     * The highest byte already handed to subscribers. Lines between `acked` and
+     * this are re-read and handed on marked as REPLAYS, so side-effecting
+     * subscribers skip them while the ledger and the log shipper still see them.
+     */
+    delivered: number;
+}
+/** DX-2954 — reported when a stored cursor was past its file's end. */
+export interface CursorPastEofInfo {
+    source: string;
+    storedOffset: number;
+    fileSize: number;
+}
+/** DX-2954 — reported when a sub-agent's transcript comes under tail. */
+export interface SourceDiscoveredInfo {
+    /** The sub-agent's ledger source key (its transcript file's basename). */
+    source: string;
+    /**
+     * The sub-agent's declared type, read from its own transcript. `null` when it
+     * has not written a line naming one yet — a hook-side report of the same
+     * sub-agent fills it in later without clobbering a value already stored.
+     */
+    agentType: string | null;
+    /** Epoch ms this watcher first saw the file. */
+    discoveredAt: number;
+    /**
+     * The file already existed when this watcher attached (found on its FIRST
+     * discovery pass). A consumer attached to a dispatch that CONTINUES an earlier
+     * one (a `--resume`, a dispatcher or thread resume) uses this to tell its
+     * predecessor's sub-agents, which ended with that process, from its own.
+     */
+    preexisting: boolean;
+}
+/**
+ * DX-2954 — what a consumer learns about the line it is being handed, beyond
+ * the entry itself.
+ */
+export interface EntryMeta {
+    /** {@link MAIN_SOURCE} for the main transcript, else the sub-agent id. */
+    source: string;
+    /** Byte offset of the line's first byte in its file. */
+    byteOffset: number;
+    /**
+     * This line was already handed to a PREVIOUS incarnation's subscribers (it
+     * falls below the source's stored `delivered` cursor) and is being handed
+     * again after a restart.
+     *
+     * Every subscriber with a SIDE EFFECT must skip a replay — re-posting Slack
+     * progress, re-forwarding to gpt-manager, or re-running the API-error
+     * detector on a predecessor's last lines are all real, visible damage. The
+     * ledger and the log shipper DO process replays: both are idempotent, and
+     * skipping them is what would lose data.
+     */
+    replay: boolean;
 }
 /**
  * Encode a working directory to the subdir name Claude Code writes JSONL
@@ -186,6 +293,29 @@ export declare function convertJsonlEntry(raw: Record<string, unknown>, lastTime
     entry: AgentLogEntry;
     timestamp: number;
 } | null;
+/**
+ * DX-2954 — WHERE EACH FILE STARTS. One ordered rule set, applied per source by
+ * {@link SessionLogWatcher.resolveStart}; the caller's job is only to hand in
+ * the right `startCursors` / `startExistingFilesAtEof`.
+ *
+ * | # | Condition | Start |
+ * |---|---|---|
+ * | 1 | the dispatch has a stored cursor for this source | its `acked`, replaying up to its `delivered` |
+ * | 2 | a worker dispatch continuing a session: its predecessor's cursor for this source (the caller resolves it INTO `startCursors`, so it arrives as rule 1) | the predecessor's final `acked`, replaying to its final `delivered` |
+ * | 3 | the FIRST dispatch of its Claude session — a new worker session, or any operator dispatch (always the only one for its session id, including one opened by a mid-session `plan_connect` and a forked session's new id) | 0 |
+ * | 4 | a WORKER dispatch continuing a session with NO cursor for ANY source (a row from before this card; a `--resume` whose predecessor predates it) — `startExistingFilesAtEof` | every ALREADY-EXISTING file at its current end |
+ * | 5 | otherwise — in particular a sub-agent file that appeared AFTER the last stats write, on a dispatch that has cursors for other sources | 0 |
+ *
+ * Rules 1 and 2 arrive identically because "where does this source resume" has
+ * ONE answer; rule 4 is the only branch that skips content, and it is narrow by
+ * construction (it cannot fire when ANY source has a cursor, so rule 5 keeps a
+ * late sub-agent file's lines).
+ *
+ * Rules 3 and 5 both read from 0, but for different reasons, and both are
+ * correct: a fresh session's full usage SHOULD be counted, and a forked
+ * session's copied history is read and credited nothing (the ledger's excess
+ * rule already covers it).
+ */
 export declare class SessionLogWatcher {
     private consumers;
     private pollTimer;
@@ -197,13 +327,62 @@ export declare class SessionLogWatcher {
     private sessionId;
     private dispatchId;
     private pollIntervalMs;
-    private fromEof;
-    private existingSubagentFilesFromEof;
+    private readonly startCursors;
+    private readonly startExistingFilesAtEof;
+    private readonly onCursorPastEof;
+    private readonly onSourceDiscovered;
     private subagentDiscoveryDone;
     private running;
     private polling;
     private initSynthesized;
     constructor(options: SessionLogWatcherOptions);
+    /**
+     * DX-2954 — resolve one file's starting offset and replay boundary, per the
+     * start order on {@link SessionLogWatcher}.
+     *
+     * `fileAlreadyExisted` distinguishes rule 4 (a file present when this watcher
+     * attached, on a continuing worker dispatch with no cursor anywhere) from
+     * rule 5 (a file that appeared later, which always starts at 0 so none of its
+     * lines are lost).
+     */
+    private resolveStart;
+    /**
+     * DX-2954 — every open source's cursor state.
+     *
+     * `delivered` is the byte up to which this watcher has handed lines to
+     * subscribers, which the collector reports as the `delivered` half of its
+     * stats write. `startOffset` is where this watcher OPENED the file, and it is
+     * the floor for the `acked` half: a source that started at EOF under rule 4
+     * must never report `acked: 0`, or the next restart would read the whole file
+     * from the start and re-sum the history rule 4 exists to skip.
+     */
+    cursorState(): Record<string, {
+        startOffset: number;
+        delivered: number;
+    }>;
+    /**
+     * DX-2954 — the main source's replay boundary (its stored `delivered` cursor),
+     * or 0 when it has none.
+     *
+     * Read with {@link SessionLogWatcher.mainStartOffset} to answer "did this
+     * watcher attach mid-session?". The offset alone is not enough: because `acked`
+     * lags `delivered` by one write, a crash right after the first cursor-bearing
+     * write leaves `{acked: 0, delivered: D}`, so the next attach starts at 0 while
+     * every byte up to D is a re-read.
+     */
+    mainReplayUntil(): number;
+    /**
+     * DX-2954 — the main transcript's starting offset once discovery has run, or
+     * `null` before that.
+     *
+     * This is what "is this a mid-session attach?" is derived from now. The
+     * declared-loaded observer used to be told `reattached: true` explicitly;
+     * a non-zero main start is the same fact stated as an observation rather than
+     * a flag, and it is true for every case that matters (a reattach, a
+     * `--resume`, a resumed operator session) without a caller having to
+     * enumerate them.
+     */
+    mainStartOffset(): number | null;
     /** Register a consumer callback that receives each new AgentLogEntry. */
     onEntry(consumer: EntryConsumer): void;
     /** Returns the discovered parent session file path, or null if not yet found. */
@@ -264,15 +443,10 @@ export declare class SessionLogWatcher {
     /**
      * Adopt a parent session file and derive the sub-agent directory.
      *
-     * When `this.fromEof` is set (Phase 2c reattach OR a DX-2583 resume — see
-     * the option's doc), seed `byteOffset` to the file's current size so the
-     * next poll reads strictly forward — historical entries are NOT re-emitted.
-     * A fresh `stat` failure (race
-     * with a delete that happens between discover and adopt) falls back to
-     * 0 so the watcher tails from the start; that is preferable to throwing
-     * during boot. `fromEof` does NOT skip sub-agent files: any sub-agent
-     * file claude writes AFTER reattach is genuinely new and should be
-     * tailed normally.
+     * DX-2954 — the starting offset comes from {@link SessionLogWatcher.resolveStart}
+     * (the cursor start order), not from a `fromEof` flag: the main source resumes
+     * at its stored `acked` cursor when it has one, and only a continuing worker
+     * dispatch with no cursor anywhere skips to the file's end.
      */
     private setParentFile;
     /**
@@ -297,6 +471,27 @@ export declare class SessionLogWatcher {
      * `pollFile` — the inline call is the defense-in-depth that closes the race
      * where bytes appear before `refreshPendingAgentTypes` has a chance to run.
      */
+    /**
+     * DX-2954 — report a running sub-agent to the consumer, normalizing the
+     * absent-type shape and CONTAINING any throw.
+     *
+     * The try/catch is not defensive padding; it mirrors `emitEntry`, which wraps
+     * every consumer for the same reason, and it is load-bearing here because of
+     * where this fires. `discoverNewSubagentFiles` has no `catch` of its own and
+     * `poll()` has `try/finally` without one, so an escaping throw would:
+     *
+     *   - on the first pass (inside `start()`), kill the watcher for the whole
+     *     dispatch — the caller only logs `start()`'s rejection;
+     *   - on a later interval tick, become an UNHANDLED REJECTION, which Node 20
+     *     turns into process exit — a worker crash caused by a consumer bug;
+     *   - either way abort the discovery loop mid-list, skipping
+     *     `subagentDiscoveryDone = true`, which leaves `firstPass` true forever and
+     *     sends later-appearing files down rule 4 instead of rule 5 — losing
+     *     exactly the lines that rule split exists to preserve.
+     *
+     * Reporting the running set must never cost the monitoring it rides on.
+     */
+    private emitSourceDiscovered;
     private refreshLineage;
     /**
      * Read agentType from the `<subagentId>.meta.json` sidecar. Returns