@thehammer/danx-session-telemetry 0.1.13 → 0.1.15

package/dist/session-log-watcher.js

@@ -26,6 +26,7 @@ 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;
@@ -41,6 +42,19 @@ const MAX_FILE_DISCOVERY_ATTEMPTS = 180;
  * wrong file (e.g., an active human session).
  */
 export const DISPATCH_TAG_PREFIX = "<!-- danxbot-dispatch:";
+/**
+ * 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 function skipReplays(consumer) {
+    return (entry, meta) => {
+        if (meta.replay)
+            return;
+        consumer(entry);
+    };
+}
 /**
  * Encode a working directory to the subdir name Claude Code writes JSONL
  * under. Replaces `/`, `.`, AND `_` with `-`. Verified empirically against
@@ -219,52 +233,29 @@ export async function findSessionFileByDispatchId(dir, dispatchId) {
     try {
         const files = await readdir(dir);
         const jsonlFiles = files.filter((f) => f.endsWith(".jsonl"));
-        for (const file of jsonlFiles) {
-            const filePath = join(dir, file);
-            let fd;
-            try {
-                fd = await open(filePath, "r");
-                const fileStats = await stat(filePath);
-                if (await windowIncludesTag(fd, 0, fileStats.size, SCAN_BYTES, tag)) {
-                    return filePath;
-                }
-                // Resume: the new tag is at the tail of a large prior-session file.
-                // Skip when the file fits in one head window (already fully read).
-                if (fileStats.size > SCAN_BYTES) {
-                    const tailStart = fileStats.size - SCAN_BYTES;
-                    if (await windowIncludesTag(fd, tailStart, fileStats.size, SCAN_BYTES, tag)) {
-                        return filePath;
-                    }
-                }
-            }
-            catch (err) {
-                // DX-1201 — a single unreadable SIBLING file must NOT abort the
-                // whole scan. Dispatched agents share a busy session dir (e.g.
-                // every issue-worker dispatch of one repo writing under the same
-                // encoded `~/.claude/projects/<cwd>/` dir), so any one of the
-                // co-located multi-MB files can momentarily fail an `open`/`stat`/
-                // `read`: ENOENT (sibling rotated/deleted mid-scan), ESTALE (a
-                // worktree torn down under the agent), EACCES (perms race), EMFILE
-                // (fd pressure across N concurrent watchers). Before this guard the
-                // throw propagated out of the per-file body and rejected the entire
-                // `findSessionFileByDispatchId` call → `discoverSessionFile` →
-                // `start()` (fire-and-forget, no `.catch`) → the watcher silently
-                // never attached → null `session_uuid` + zero usage/tool-call
-                // counters on ~20% of host dispatches (intermittent because the
-                // outcome hinged on `readdir` ordering vs the failing sibling).
-                // Skip this file and keep scanning the rest — the tagged file the
-                // caller actually wants may be later in the directory.
-                const code = err.code;
-                if (code !== "ENOENT") {
-                    log.warn(`Skipping unreadable session file during dispatch-tag scan: ${filePath} (${code ?? String(err)})`);
-                }
-                continue;
-            }
-            finally {
-                await fd?.close();
-            }
-        }
-        return null;
+        // DX-3395 — scan every sibling CONCURRENTLY instead of one at a time.
+        // A dispatched agent's cwd is a busy, SHARED session dir (DX-1201's own
+        // comment below: every issue-worker dispatch of one card writes under
+        // the same encoded `~/.claude/projects/<cwd>/` dir), so this directory
+        // accumulates one multi-MB `.jsonl` per distinct session ever launched
+        // there. The previous `for...of` paid each sibling's bounded
+        // open+stat+read (<=2*SCAN_BYTES) back-to-back even though they are
+        // independent filesystem operations the OS can service in parallel —
+        // this is the ONE stage DX-3395's resume-latency investigation found
+        // that is both real, sequential, and entirely danxbot-owned (unlike the
+        // dominant cost, `claude --resume`'s own session reload, which lives
+        // outside this codebase — see the card for the measured comparison).
+        // `Promise.all` lets every sibling's I/O overlap; each check keeps its
+        // own try/catch (unchanged from the DX-1201 per-file isolation below),
+        // so one unreadable sibling still can never abort the others. At most
+        // ONE sibling can ever contain a given dispatch's unique tag, so which
+        // promise settles first is never ambiguous — the result is looked up by
+        // `files`' ORIGINAL index, so the return value stays deterministic
+        // regardless of resolution order (proven by the multi-sibling test in
+        // `session-log-watcher.test.ts`).
+        const hits = await Promise.all(jsonlFiles.map((file) => fileContainsTag(dir, file, tag, SCAN_BYTES)));
+        const index = hits.findIndex(Boolean);
+        return index === -1 ? null : join(dir, jsonlFiles[index]);
     }
     catch (err) {
         if (err.code === "ENOENT")
@@ -272,6 +263,56 @@ export async function findSessionFileByDispatchId(dir, dispatchId) {
         throw err;
     }
 }
+/**
+ * One sibling's head+tail scan for `findSessionFileByDispatchId`'s
+ * concurrent `Promise.all` — factored out so each file's try/catch/finally
+ * is self-contained and never affects any other sibling's check.
+ */
+async function fileContainsTag(dir, file, tag, scanBytes) {
+    const filePath = join(dir, file);
+    let fd;
+    try {
+        fd = await open(filePath, "r");
+        const fileStats = await stat(filePath);
+        if (await windowIncludesTag(fd, 0, fileStats.size, scanBytes, tag)) {
+            return true;
+        }
+        // Resume: the new tag is at the tail of a large prior-session file.
+        // Skip when the file fits in one head window (already fully read).
+        if (fileStats.size > scanBytes) {
+            const tailStart = fileStats.size - scanBytes;
+            if (await windowIncludesTag(fd, tailStart, fileStats.size, scanBytes, tag)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    catch (err) {
+        // DX-1201 — a single unreadable SIBLING file must NOT abort the
+        // whole scan. Dispatched agents share a busy session dir (e.g.
+        // every issue-worker dispatch of one repo writing under the same
+        // encoded `~/.claude/projects/<cwd>/` dir), so any one of the
+        // co-located multi-MB files can momentarily fail an `open`/`stat`/
+        // `read`: ENOENT (sibling rotated/deleted mid-scan), ESTALE (a
+        // worktree torn down under the agent), EACCES (perms race), EMFILE
+        // (fd pressure across N concurrent watchers). Before this guard the
+        // throw propagated out of the per-file body and rejected the entire
+        // `findSessionFileByDispatchId` call → `discoverSessionFile` →
+        // `start()` (fire-and-forget, no `.catch`) → the watcher silently
+        // never attached → null `session_uuid` + zero usage/tool-call
+        // counters on ~20% of host dispatches (intermittent because the
+        // outcome hinged on `readdir` ordering vs the failing sibling).
+        // Report this sibling as a non-match and let the others resolve.
+        const code = err.code;
+        if (code !== "ENOENT") {
+            log.warn(`Skipping unreadable session file during dispatch-tag scan: ${filePath} (${code ?? String(err)})`);
+        }
+        return false;
+    }
+    finally {
+        await fd?.close();
+    }
+}
 /**
  * Read a `<= maxBytes` window starting at `from` (clamped to the file) and
  * report whether `tag` appears in it. Factored out so the head + tail scans
@@ -413,6 +454,29 @@ 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;
@@ -424,8 +488,10 @@ export class SessionLogWatcher {
     sessionId;
     dispatchId;
     pollIntervalMs;
-    fromEof;
-    existingSubagentFilesFromEof;
+    startCursors;
+    startExistingFilesAtEof;
+    onCursorPastEof;
+    onSourceDiscovered;
     subagentDiscoveryDone = false;
     running = false;
     polling = false;
@@ -441,9 +507,110 @@ export class SessionLogWatcher {
         this.sessionId = options.sessionId;
         this.dispatchId = options.dispatchId;
         this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
-        this.fromEof = options.fromEof ?? false;
-        this.existingSubagentFilesFromEof =
-            options.existingSubagentFilesFromEof ?? false;
+        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;
     }
     /** Register a consumer callback that receives each new AgentLogEntry. */
     onEntry(consumer) {
@@ -544,8 +711,7 @@ 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;
@@ -557,35 +723,36 @@ export 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.
      */
     async setParentFile(filePath) {
-        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)}`);
-            }
-        }
+        // 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;
         this.parentTail = {
             filePath,
             byteOffset,
             lineBuffer: "",
             lineBufferStartOffset: byteOffset,
             lastTimestamp: 0,
+            source: MAIN_SOURCE,
+            startOffset: byteOffset,
+            replayUntil,
+            discoveredAt: Date.now(),
+            preexisting: false,
         };
         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.
@@ -627,8 +794,41 @@ export class SessionLogWatcher {
             const fileStats = await stat(state.filePath);
             if (!this.running)
                 return;
-            if (fileStats.size <= state.byteOffset)
+            // 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) {
                 return;
+            }
             const fd = await open(state.filePath, "r");
             try {
                 if (!this.running)
@@ -686,40 +886,63 @@ export class SessionLogWatcher {
             log.error("Failed to enumerate sub-agent directory:", err);
             return;
         }
-        // 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;
+        // 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;
         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);
-            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 start = await this.resolveStart(subagentId, fullPath, firstPass);
+            if (start === null) {
+                allResolved = false;
+                continue;
             }
+            const { byteOffset, replayUntil } = start;
+            const discoveredAt = Date.now();
             this.subagentTails.set(fullPath, {
                 filePath: fullPath,
-                byteOffset: startOffset,
-                lineBufferStartOffset: startOffset,
+                byteOffset,
+                lineBufferStartOffset: byteOffset,
                 lineBuffer: "",
                 lastTimestamp: 0,
+                source: subagentId,
+                startOffset: byteOffset,
+                replayUntil,
+                discoveredAt,
+                preexisting: firstPass,
                 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, firstPass);
         }
+        if (allResolved)
+            this.subagentDiscoveryDone = true;
     }
     /** Centralized lineage refresh — see `refreshLineage` for the per-state body. */
     async refreshPendingAgentTypes() {
@@ -735,13 +958,63 @@ 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, preexisting) {
+        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,
+                preexisting,
+            });
+        }
+        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, state.preexisting);
+        }
         if (parent_session_id === null && this.parentSessionId !== null) {
             parent_session_id = this.parentSessionId;
         }
@@ -842,7 +1115,7 @@ export class SessionLogWatcher {
                         synthesized: true,
                     },
                 };
-                this.emitEntry(initEntry, state);
+                this.emitEntry(initEntry, state, lineStart);
                 this.initSynthesized = true;
             }
         }
@@ -860,7 +1133,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);
+        this.emitEntry(result.entry, state, lineStart);
     }
     /**
      * Emit an entry to registered consumers. For sub-agent streams,
@@ -873,7 +1146,7 @@ export class SessionLogWatcher {
      * tests; nothing else read it. Every real consumer subscribes via
      * `onEntry` instead.
      */
-    emitEntry(entry, state) {
+    emitEntry(entry, state, byteOffset) {
         if (state.lineage) {
             entry.data = {
                 ...entry.data,
@@ -882,9 +1155,18 @@ 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);
+                consumer(entry, meta);
             }
             catch (err) {
                 log.error("Consumer error:", err);