@thehammer/danx-session-telemetry 0.1.12 → 0.1.13

package/dist/index.d.ts

@@ -15,7 +15,7 @@
  * usage display.
  */
 export { SessionLogWatcher, DISPATCH_TAG_PREFIX, encodeClaudeProjectsCwd, deriveSessionDir, sessionUuidExistsInCleanRoom, findNewestJsonlFile, findSessionFileByDispatchId, convertJsonlEntry, } from "./session-log-watcher.js";
-export type { EntryConsumer, SessionLogWatcherOptions, SourceCursorStart, CursorPastEofInfo, SourceDiscoveredInfo, EntryMeta, } from "./session-log-watcher.js";
+export type { EntryConsumer, SessionLogWatcherOptions, } from "./session-log-watcher.js";
 export type { AgentLogEntry, AgentLineage } from "./types.js";
 export { truncStr, summarizeToolInput, buildAssistantSummary, buildToolResultSummary, } from "./tool-summary.js";
 export * from "./usage-ledger.js";

package/dist/pricing.d.ts

@@ -1,8 +1,8 @@
 /**
  * DX-2963 — the ONE pricing function, shared by every consumer that turns
  * token counts into dollars: the danxbot server's usage-ledger writer (which
- * prices each credit once, when it is credited), the router's Haiku calls and
- * the skill-eval cost report. Moved here from danxbot root `src/agent/pricing.ts`
+ * prices each credit once, when it is credited), and the router's Haiku calls.
+ * Moved here from danxbot root `src/agent/pricing.ts`
  * so the counter and the price list live side by side, and exported through
  * the browser-safe `./browser` subpath (pure arithmetic, no `node:` imports).
  *

package/dist/pricing.js

@@ -1,8 +1,8 @@
 /**
  * DX-2963 — the ONE pricing function, shared by every consumer that turns
  * token counts into dollars: the danxbot server's usage-ledger writer (which
- * prices each credit once, when it is credited), the router's Haiku calls and
- * the skill-eval cost report. Moved here from danxbot root `src/agent/pricing.ts`
+ * prices each credit once, when it is credited), and the router's Haiku calls.
+ * Moved here from danxbot root `src/agent/pricing.ts`
  * so the counter and the price list live side by side, and exported through
  * the browser-safe `./browser` subpath (pure arithmetic, no `node:` imports).
  *

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

@@ -28,14 +28,7 @@ import type { AgentLogEntry } from "./types.js";
  * wrong file (e.g., an active human session).
  */
 export declare const DISPATCH_TAG_PREFIX = "<!-- danxbot-dispatch:";
-/**
- * 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;
+export type EntryConsumer = (entry: AgentLogEntry) => void;
 export interface SessionLogWatcherOptions {
     /** Working directory the agent was launched in. Used to derive the session directory. */
     cwd: string;
@@ -53,118 +46,32 @@ export interface SessionLogWatcherOptions {
      */
     dispatchId?: string;
     /**
-     * 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.
+     * 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.
      */
-    startCursors?: Record<string, SourceCursorStart>;
+    fromEof?: boolean;
     /**
-     * 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.
+     * 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.
      */
-    startExistingFilesAtEof?: boolean;
-    /**
-     * 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`.
-     */
-    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;
-}
-/**
- * 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;
+    existingSubagentFilesFromEof?: boolean;
 }
 /**
  * Encode a working directory to the subdir name Claude Code writes JSONL
@@ -279,29 +186,6 @@ 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;
@@ -313,62 +197,13 @@ export declare class SessionLogWatcher {
     private sessionId;
     private dispatchId;
     private pollIntervalMs;
-    private readonly startCursors;
-    private readonly startExistingFilesAtEof;
-    private readonly onCursorPastEof;
-    private readonly onSourceDiscovered;
+    private fromEof;
+    private existingSubagentFilesFromEof;
     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. */
@@ -429,10 +264,15 @@ export declare class SessionLogWatcher {
     /**
      * Adopt a parent session file and derive the sub-agent directory.
      *
-     * 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.
+     * 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.
      */
     private setParentFile;
     /**
@@ -457,27 +297,6 @@ 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

package/dist/session-log-watcher.js

@@ -26,7 +26,6 @@ import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join } from "node:path";
 import { createLogger } from "./internal-logger.js";
 import { buildAssistantSummary, buildToolResultSummary, } from "./tool-summary.js";
-import { MAIN_SOURCE } from "./usage-ledger.js";
 const log = createLogger("session-log-watcher");
 const DEFAULT_POLL_INTERVAL_MS = 5_000;
 const FILE_DISCOVERY_POLL_MS = 1_000;
@@ -414,29 +413,6 @@ export function convertJsonlEntry(raw, lastTimestamp) {
             return 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 class SessionLogWatcher {
     consumers = [];
     pollTimer;
@@ -448,10 +424,8 @@ export class SessionLogWatcher {
     sessionId;
     dispatchId;
     pollIntervalMs;
-    startCursors;
-    startExistingFilesAtEof;
-    onCursorPastEof;
-    onSourceDiscovered;
+    fromEof;
+    existingSubagentFilesFromEof;
     subagentDiscoveryDone = false;
     running = false;
     polling = false;
@@ -467,110 +441,9 @@ export class SessionLogWatcher {
         this.sessionId = options.sessionId;
         this.dispatchId = options.dispatchId;
         this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
-        this.startCursors = options.startCursors ?? {};
-        this.startExistingFilesAtEof = options.startExistingFilesAtEof ?? false;
-        this.onCursorPastEof = options.onCursorPastEof;
-        this.onSourceDiscovered = options.onSourceDiscovered;
-    }
-    /**
-     * 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).
-     */
-    async resolveStart(source, filePath, fileAlreadyExisted) {
-        const stored = this.startCursors[source];
-        // Rules 1-2: this dispatch's own stored cursor, or the predecessor's that
-        // the caller already resolved into `startCursors`. Both arrive here the
-        // same way, because "where does this source resume" has ONE answer.
-        if (stored !== undefined) {
-            return { byteOffset: stored.acked, replayUntil: stored.delivered };
-        }
-        // Rule 4: no cursor for ANY source on a continuing worker dispatch.
-        if (this.startExistingFilesAtEof && fileAlreadyExisted) {
-            try {
-                const size = (await stat(filePath)).size;
-                return { byteOffset: size, replayUntil: 0 };
-            }
-            catch (err) {
-                // NOT a fall-back to 0. This branch fires precisely on the rows whose
-                // stored totals already count this file, so reading it from the start
-                // re-sums the whole session — the 421M-cache-read inflation (DX-2583)
-                // that rule 4 exists to prevent. `null` means "do not open this source
-                // yet"; the caller leaves it undiscovered and the next poll retries,
-                // still treating it as pre-existing.
-                log.warn(`startExistingFilesAtEof: stat failed for ${filePath}; NOT opening it this pass (reading from 0 would re-sum the session): ${String(err)}`);
-                return null;
-            }
-        }
-        // Rules 3 and 5: the first dispatch of a session, and any file that appeared
-        // after the last stats write, both read from the start.
-        return { byteOffset: 0, replayUntil: 0 };
-    }
-    /**
-     * 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() {
-        // `delivered` is `lineBufferStartOffset`, NOT `byteOffset`.
-        //
-        // `pollFile` advances `byteOffset` by every byte it READ, and `processText`
-        // deliberately buffers a trailing newline-less line (the whole reason
-        // `lineBuffer` exists — a poll routinely catches a line mid-append). So
-        // `byteOffset` can sit PAST the first byte of a line that was never emitted;
-        // promoting that to `acked` makes a restart open the file mid-JSON, and the
-        // fragment is dropped as a malformed line — losing that reply's usage, its
-        // tool-use ids and its side effects permanently.
-        //
-        // `lineBufferStartOffset` is the start of the next UNCONSUMED line, which is
-        // exactly the resume point. It equals `byteOffset` whenever the buffer is
-        // empty, so the happy path is unchanged.
-        const at = (s) => ({
-            startOffset: s.startOffset,
-            delivered: s.lineBufferStartOffset,
-        });
-        const out = {};
-        if (this.parentTail)
-            out[this.parentTail.source] = at(this.parentTail);
-        for (const state of this.subagentTails.values())
-            out[state.source] = at(state);
-        return out;
-    }
-    /**
-     * 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() {
-        return this.parentTail?.replayUntil ?? 0;
-    }
-    /**
-     * 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() {
-        return this.parentTail?.startOffset ?? null;
+        this.fromEof = options.fromEof ?? false;
+        this.existingSubagentFilesFromEof =
+            options.existingSubagentFilesFromEof ?? false;
     }
     /** Register a consumer callback that receives each new AgentLogEntry. */
     onEntry(consumer) {
@@ -671,7 +544,8 @@ export class SessionLogWatcher {
             const filePath = this.dispatchId
                 ? await findSessionFileByDispatchId(this.sessionDir, this.dispatchId)
                 : await findNewestJsonlFile(this.sessionDir, this.sessionId);
-            if (filePath && (await this.setParentFile(filePath))) {
+            if (filePath) {
+                await this.setParentFile(filePath);
                 const tag = this.dispatchId ? `[Dispatch ${this.dispatchId}] ` : "";
                 log.info(`${tag}Watching session file: ${filePath}`);
                 return;
@@ -683,35 +557,35 @@ export class SessionLogWatcher {
     /**
      * Adopt a parent session file and derive the sub-agent directory.
      *
-     * 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.
+     * 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.
      */
     async setParentFile(filePath) {
-        // DX-2954 — the main transcript's source key is always MAIN_SOURCE, and it
-        // ALWAYS counts as already-existing: by the time discovery found this file
-        // it is on disk, which is exactly what rule 4 asks about.
-        const start = await this.resolveStart(MAIN_SOURCE, filePath, true);
-        // `null` = its start offset could not be established safely (see
-        // `resolveStart`). Report the failure so discovery retries rather than
-        // adopting the file at a guessed offset.
-        if (start === null)
-            return false;
-        const { byteOffset, replayUntil } = start;
+        let byteOffset = 0;
+        if (this.fromEof) {
+            try {
+                const fileStats = await stat(filePath);
+                byteOffset = fileStats.size;
+            }
+            catch (err) {
+                log.warn(`fromEof: stat failed for ${filePath}; tailing from 0: ${String(err)}`);
+            }
+        }
         this.parentTail = {
             filePath,
             byteOffset,
             lineBuffer: "",
             lineBufferStartOffset: byteOffset,
             lastTimestamp: 0,
-            source: MAIN_SOURCE,
-            startOffset: byteOffset,
-            replayUntil,
-            discoveredAt: Date.now(),
         };
         this.subagentsDir = join(dirname(filePath), basename(filePath, ".jsonl"), "subagents");
-        return true;
     }
     /**
      * Poll all known files: the parent session, then re-enumerate + tail sub-agent files.
@@ -753,41 +627,8 @@ export class SessionLogWatcher {
             const fileStats = await stat(state.filePath);
             if (!this.running)
                 return;
-            // DX-2954 — a cursor PAST the end of the file means the file was replaced
-            // or truncated under us. `size === byteOffset` is the ordinary "no new
-            // bytes" case; only a STRICTLY smaller file is the pathological one, and
-            // before this card it fell into the same early return and silently tailed
-            // nothing for the rest of the dispatch. Restart that source at 0 and
-            // report it, so the caller records a visible event and marks the reset in
-            // its next stats write (the one sanctioned backwards move of `acked`).
-            if (fileStats.size < state.byteOffset) {
-                this.onCursorPastEof?.({
-                    source: state.source,
-                    storedOffset: state.byteOffset,
-                    fileSize: fileStats.size,
-                });
-                state.byteOffset = 0;
-                state.lineBufferStartOffset = 0;
-                state.lineBuffer = "";
-                // `startOffset` moves to 0 with it: it is the FLOOR the collector uses
-                // for this source's reported `acked`, so leaving it at the old (now
-                // impossible) offset would make the next write claim to have
-                // acknowledged bytes the file no longer has.
-                state.startOffset = 0;
-                // Nothing below the new position was ever delivered from THIS file's
-                // current content, so nothing in it is a replay.
-                state.replayUntil = 0;
-                // The replacement file's first entry must not have its `delta_ms`
-                // computed against the OLD file's last timestamp (which can produce a
-                // negative or absurd gap). This is a different file; its timeline starts
-                // fresh.
-                state.lastTimestamp = 0;
-                if (fileStats.size === 0)
-                    return;
-            }
-            else if (fileStats.size === state.byteOffset) {
+            if (fileStats.size <= state.byteOffset)
                 return;
-            }
             const fd = await open(state.filePath, "r");
             try {
                 if (!this.running)
@@ -845,62 +686,40 @@ export class SessionLogWatcher {
             log.error("Failed to enumerate sub-agent directory:", err);
             return;
         }
-        // DX-2954 — the FIRST discovery pass sees exactly the sub-agent files that
-        // existed when this watcher attached. Only those can satisfy rule 4's
-        // "already existing"; a file found on a LATER pass appeared after the attach
-        // and always reads from 0 (rule 5), so none of its lines are lost.
-        const firstPass = !this.subagentDiscoveryDone;
-        // Marked done only if this pass established a start offset for EVERY file it
-        // saw. A file skipped by `resolveStart` must still count as PRE-EXISTING on
-        // the retry — treating it as "appeared later" would send it to rule 5 (read
-        // from 0) and re-sum exactly the history rule 4 skipped.
-        let allResolved = true;
+        // DX-2963 — the FIRST discovery pass sees exactly the sub-agent files
+        // that existed when this watcher attached; only those may open at EOF.
+        const openExistingAtEof = this.existingSubagentFilesFromEof && !this.subagentDiscoveryDone;
+        this.subagentDiscoveryDone = true;
         for (const file of files) {
             if (!file.endsWith(".jsonl"))
                 continue;
             const fullPath = join(this.subagentsDir, file);
             if (this.subagentTails.has(fullPath))
                 continue;
-            // A sub-agent's ledger source key IS its file's basename (`agent-<hash>`),
-            // the same value `usage-ledger.ts` credits usage under and the same value
-            // `dispatch_activities.activity_id` holds — so a cursor, a per-source
-            // token total and a running-set row all join on one key.
             const subagentId = basename(file, ".jsonl");
             const agentType = await this.readAgentType(subagentId);
-            const start = await this.resolveStart(subagentId, fullPath, firstPass);
-            if (start === null) {
-                allResolved = false;
-                continue;
+            let startOffset = 0;
+            if (openExistingAtEof) {
+                try {
+                    startOffset = (await stat(fullPath)).size;
+                }
+                catch (err) {
+                    log.warn(`existingSubagentFilesFromEof: stat failed for ${fullPath}; tailing from 0: ${String(err)}`);
+                }
             }
-            const { byteOffset, replayUntil } = start;
-            const discoveredAt = Date.now();
             this.subagentTails.set(fullPath, {
                 filePath: fullPath,
-                byteOffset,
-                lineBufferStartOffset: byteOffset,
+                byteOffset: startOffset,
+                lineBufferStartOffset: startOffset,
                 lineBuffer: "",
                 lastTimestamp: 0,
-                source: subagentId,
-                startOffset: byteOffset,
-                replayUntil,
-                discoveredAt,
                 lineage: {
                     subagent_id: subagentId,
                     parent_session_id: this.parentSessionId,
                     agent_type: agentType,
                 },
             });
-            // DX-2954 — fired AFTER the tail is registered, so a consumer that throws
-            // cannot leave a half-registered source, and the `subagentTails.has()`
-            // guard above makes it exactly-once per source for this watcher's life. A
-            // re-discovery by a RESTARTED watcher fires again by design: the row it
-            // reports is an idempotent upsert keyed on this same id, and re-reporting
-            // is how a reattached collector re-learns the sub-agents that were already
-            // running before it existed.
-            this.emitSourceDiscovered(subagentId, agentType, discoveredAt);
         }
-        if (allResolved)
-            this.subagentDiscoveryDone = true;
     }
     /** Centralized lineage refresh — see `refreshLineage` for the per-state body. */
     async refreshPendingAgentTypes() {
@@ -916,62 +735,13 @@ export 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.
-     */
-    emitSourceDiscovered(source, agentType, discoveredAt) {
-        try {
-            this.onSourceDiscovered?.({
-                source,
-                // ONE absent-shape on the wire, never two: this class's own reader
-                // answers `undefined` for "no meta file yet", while the stats payload and
-                // the `dispatch_activities.agent_type` column both spell absent as
-                // `null`. Normalizing here keeps every consumer from accepting both.
-                agentType: agentType ?? null,
-                discoveredAt,
-            });
-        }
-        catch (err) {
-            log.error("onSourceDiscovered consumer error:", err);
-        }
-    }
     async refreshLineage(state) {
         if (!state.lineage)
             return;
         let { agent_type, parent_session_id } = state.lineage;
-        // DX-2954 — remember whether the type was still unknown coming in, so the
-        // `undefined -> string` transition can be reported. Discovery reads the
-        // sidecar the instant the `.jsonl` appears, and claude writes the `.jsonl`
-        // BEFORE the `.meta.json` (the race this method exists for), so "no type
-        // yet" at discovery is the COMMON case, not an edge. Without a report here
-        // the running-set row's `agent_type` would stay NULL for the whole dispatch
-        // even though the watcher learned the real value one poll later.
-        const typeWasUnknown = agent_type === undefined;
         if (agent_type === undefined) {
             agent_type = await this.readAgentType(state.lineage.subagent_id);
         }
-        if (typeWasUnknown && agent_type !== undefined && state.source !== MAIN_SOURCE) {
-            // The ORIGINAL discovery stamp, never a fresh `Date.now()`: this is the
-            // same activity, learning its type late, not a new one starting now.
-            this.emitSourceDiscovered(state.source, agent_type, state.discoveredAt);
-        }
         if (parent_session_id === null && this.parentSessionId !== null) {
             parent_session_id = this.parentSessionId;
         }
@@ -1072,7 +842,7 @@ export class SessionLogWatcher {
                         synthesized: true,
                     },
                 };
-                this.emitEntry(initEntry, state, lineStart);
+                this.emitEntry(initEntry, state);
                 this.initSynthesized = true;
             }
         }
@@ -1090,7 +860,7 @@ export class SessionLogWatcher {
         state.lastTimestamp = result.timestamp;
         // DX-2963 — the line's own byte offset (see `TailState.lineBufferStartOffset`).
         result.entry.data = { ...result.entry.data, byte_offset: lineStart };
-        this.emitEntry(result.entry, state, lineStart);
+        this.emitEntry(result.entry, state);
     }
     /**
      * Emit an entry to registered consumers. For sub-agent streams,
@@ -1103,7 +873,7 @@ export class SessionLogWatcher {
      * tests; nothing else read it. Every real consumer subscribes via
      * `onEntry` instead.
      */
-    emitEntry(entry, state, byteOffset) {
+    emitEntry(entry, state) {
         if (state.lineage) {
             entry.data = {
                 ...entry.data,
@@ -1112,18 +882,9 @@ export class SessionLogWatcher {
                 agent_type: state.lineage.agent_type,
             };
         }
-        // DX-2954 — a line whose FIRST byte lies below the source's stored
-        // `delivered` cursor was already handed to a previous incarnation's
-        // subscribers. Strictly `<`: `delivered` is an exclusive end (the next
-        // unread byte), so a line starting exactly AT it is new.
-        const meta = {
-            source: state.source,
-            byteOffset,
-            replay: byteOffset < state.replayUntil,
-        };
         for (const consumer of this.consumers) {
             try {
-                consumer(entry, meta);
+                consumer(entry);
             }
             catch (err) {
                 log.error("Consumer error:", err);

package/dist/usage-ledger.d.ts

@@ -1,7 +1,7 @@
 /**
  * DX-2963 — the ONE usage counter. Turns Claude Code transcript lines into
  * per-reply usage-ledger entries; every counter in danxbot (the worker's
- * accumulator, the skill-eval probe, the stall sweep's productivity signal,
+ * accumulator, `claude-probe.ts`'s usage summer, the stall sweep's productivity signal,
  * the cross-consumer tests) uses it instead of its own summing.
  *
  * The rule it implements, measured on real transcripts (DX-2963 card,
@@ -121,7 +121,7 @@ export declare class UsageLedgerCounter {
  * Pull the counter's {@link LedgerLine} fields out of one raw transcript
  * line (a parsed JSONL object). Returns `null` for anything that is not an
  * assistant line. Shared by every counter that reads a transcript from disk
- * (the dashboard's reader, the skill-eval probe, the stall sweep).
+ * (the dashboard's reader, `claude-probe.ts`, the stall sweep).
  */
 export declare function ledgerLineFromRaw(raw: Record<string, unknown>, source: string, byteOffset: number): LedgerLine | null;
 /**

package/dist/usage-ledger.js

@@ -214,7 +214,7 @@ function snapshot(e) {
  * Pull the counter's {@link LedgerLine} fields out of one raw transcript
  * line (a parsed JSONL object). Returns `null` for anything that is not an
  * assistant line. Shared by every counter that reads a transcript from disk
- * (the dashboard's reader, the skill-eval probe, the stall sweep).
+ * (the dashboard's reader, `claude-probe.ts`, the stall sweep).
  */
 export function ledgerLineFromRaw(raw, source, byteOffset) {
     if (raw.type !== "assistant")

package/package.json

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