@50arms/session-telemetry 0.0.0-stage → 0.1.66

package/dist/session-log-watcher.js

@@ -0,0 +1,1285 @@
+/**
+ * SessionLogWatcher — Polls Claude Code JSONL session files for new entries.
+ *
+ * DX-2962: moved unchanged from danxbot root `src/agent/session-log-watcher.ts`
+ * into this shared published package, so the danxbot worker and the
+ * `platform-mcp` MCP server's relay (DX-2954) run identical collector
+ * code. Only the imports changed — `../logger.js` -> `./internal-logger.js`
+ * (this package's own tiny logging shim, since root's `logger.ts` has ~300
+ * unrelated consumers and does not move), `../types.js` -> `./types.js`
+ * (moved — see that file's own header).
+ *
+ * Claude Code writes:
+ *   - Parent session:   ~/.claude/projects/<cwd-path>/<session-uuid>.jsonl
+ *   - Sub-agent sessions: ~/.claude/projects/<cwd-path>/<session-uuid>/subagents/agent-<hash>.jsonl
+ *                        + agent-<hash>.meta.json sidecar with {agentType, description, parentAgentId (nested only), ...}
+ *
+ * The watcher tails the parent file and all sub-agent files in parallel, parses
+ * new lines, converts them to AgentLogEntry, and emits to registered consumers.
+ * Sub-agent entries are decorated with lineage metadata (subagent_id,
+ * parent_session_id, agent_type) inside `data` so downstream consumers can
+ * attribute usage correctly — they flow under the SAME dispatch, not a separate session.
+ */
+import { existsSync, realpathSync } from "node:fs";
+import { open, readFile, readdir, stat } from "node:fs/promises";
+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;
+// 180s max wait for JSONL to appear. claude --resume on a clean-room with
+// slow pre-turn setup (SFC-deps provision, vitest cold start, mcp probe)
+// can take 60-90s before the first assistant turn writes to the JSONL.
+// 60s was too tight — matches DX-825 stall-threshold raise (5s→120s).
+const MAX_FILE_DISCOVERY_ATTEMPTS = 180;
+/**
+ * Tag prefix injected into the piped prompt by the launcher. The watcher scans
+ * JSONL files for this tag to deterministically find the correct session file
+ * for a given dispatch, avoiding mtime-based heuristics that can pick up the
+ * wrong file (e.g., an active human session).
+ */
+export const DISPATCH_TAG_PREFIX = "<!-- danxbot-dispatch:";
+/** The line `type`s the usage feed carries; every other type never reaches a {@link UsageLineConsumer}. */
+const USAGE_FEED_TYPES = new Set(["assistant", "user", "attachment", "system"]);
+/**
+ * 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);
+    };
+}
+/**
+ * DX-4922 - the session id a transcript file belongs to: `<session id>.jsonl` for the main transcript, and for a
+ * sub-agent file (`<session id>/subagents/agent-*.jsonl`) the directory above `subagents`. Verified on local
+ * transcripts: a sub-agent's lines carry its parent session's id, never its own agent id.
+ */
+export function transcriptSessionId(filePath) {
+    const dir = dirname(filePath);
+    if (basename(dir) === "subagents")
+        return basename(dirname(dir));
+    return basename(filePath, ".jsonl");
+}
+/**
+ * Encode a working directory to the subdir name Claude Code writes JSONL
+ * under. Replaces `/`, `.`, AND `_` with `-`. Verified empirically against
+ * on-disk entries: a dispatched-agent cwd like
+ * `/var/tmp/danxbot-clean-room/<hash>/repo__board__work__dani__DX-1` encodes to
+ * `-var-tmp-danxbot-clean-room-<hash>-repo--board--work--dani--DX-1` — each
+ * `__` key delimiter collapses to `--`.
+ *
+ * `realpathSync` runs first so the encoding matches what claude's own
+ * resolver produces — the agent's cwd is realpath'd by the kernel before
+ * claude reads `process.cwd()`. ENOENT falls back to the normalized path
+ * so callers can pre-compute encodings before the dir exists (e.g. unit
+ * tests that exercise the pure encoding contract).
+ *
+ * The `.`/`_` encoding matters: a hidden-dir segment (leading `.`) or a
+ * clean-room key's `__` delimiter that the encoder does NOT collapse produces
+ * a directory Claude Code never writes to — silently breaking
+ * SessionLogWatcher attachment. The separator-encoding regression tests
+ * below pin this.
+ *
+ * Claude 2.1.104+ (GitHub #51488 — symlinks under `~/.claude/projects/` are
+ * no longer followed) writes its transcript to this exact realpath-encoded
+ * dir as a REAL directory; the watcher reads the same path, so they converge
+ * with no symlink. A danxbot worker container binds `<repo>/claude-projects/`
+ * at `/home/danxbot/.claude/projects/` and relies on the same encoding for
+ * the bound subdir name; an operator's own interactive session on its
+ * machine uses the native dir. Keep the encoding logic centralized here so
+ * every caller stays in lockstep.
+ *
+ * DX-3069 — a Windows caller (an operator session on a Windows machine)
+ * passes an ALREADY-ABSOLUTE Windows cwd (`C:\Users\...`), which never
+ * starts with `/`. The prior
+ * `cwd.startsWith("/") ? cwd : "/" + cwd` unconditionally prepended `/`,
+ * producing a malformed path (`/C:\Users\...`) that `realpathSync` cannot
+ * resolve (ENOENT — Windows reads the leading `/C:` as its own root segment),
+ * so the code fell into the catch and kept that malformed string. The old
+ * regex (`/[/._]/g`) never touched `\` or `:`, so every backslash and the
+ * drive-letter colon survived verbatim into the "encoded" dir name, and
+ * `join(homedir(), ".claude", "projects", encoded)` then produced a NESTED,
+ * DOUBLED path — `C:\Users\...\.claude\projects\-C:\Users\...` — a directory
+ * Claude Code never writes to, so every watcher on Windows silently
+ * never found its own transcript. Verified empirically against a real Claude
+ * Code install on this machine: `C:\Users\newms\projects\danxbot` encodes on
+ * disk to `C--Users-newms-projects-danxbot` (`ls ~/.claude/projects`) — no
+ * leading dash, `:` and each `\` both become `-`, exactly like `/` and `.` do
+ * for a POSIX cwd. `isAbsolute` (platform-native — win32 on Windows, posix
+ * elsewhere) replaces the POSIX-only `startsWith("/")` check so an
+ * already-absolute Windows path is never re-prefixed, and the replacement
+ * regex now also covers `\` and `:` so no separator survives into the
+ * encoded name on either platform.
+ */
+export function encodeClaudeProjectsCwd(cwd) {
+    const normalized = isAbsolute(cwd) ? cwd : `/${cwd}`;
+    let resolved;
+    try {
+        resolved = realpathSync(normalized);
+    }
+    catch {
+        // Path doesn't exist yet — use as-is (agent may not have started)
+        resolved = normalized;
+    }
+    // Claude Code encodes its cwd into ~/.claude/projects/<dir> by replacing
+    // EVERY non-alphanumeric separator with `-`: `/`, `.`, and `_` on every
+    // platform, plus `\` and the drive-letter `:` on Windows. The `_` matters:
+    // the clean-room key (`cleanRoomKey`, DX-1511) joins its components with
+    // `__`, so Claude writes the dir as `--` on disk. Omitting `_` here made
+    // the watcher wait on a `__` path Claude never creates → "session file not
+    // found after 180s" on every clean-room dispatch.
+    return resolved.replace(/[/\\:._]/g, "-");
+}
+/**
+ * Derives the Claude Code session directory from a working directory path.
+ * Claude Code stores sessions at ~/.claude/projects/<encoded-cwd>/. See
+ * `encodeClaudeProjectsCwd` for the encoding contract.
+ */
+export function deriveSessionDir(cwd) {
+    return join(homedir(), ".claude", "projects", encodeClaudeProjectsCwd(cwd));
+}
+/**
+ * On-disk existence gate for a stored, resumable Claude session UUID
+ * (migration 061). Given the clean-room `cwd` a dispatch ran in and a
+ * session `uuid`, returns `true` iff `<uuid>.jsonl` lives under that cwd's
+ * encoded `~/.claude/projects/<encoded>/` dir.
+ *
+ * This is the deterministic precondition the issue-bound resume gates check
+ * BEFORE passing `--resume <uuid>`: a session pinned in cwd A is only
+ * resumable from cwd A (Claude Code keys JSONLs by encoded-cwd), so a uuid
+ * stored on a card but orphaned by a cwd / agent move resolves here to a
+ * different encoded dir, is not found, and the caller fails SOFT to a fresh
+ * launch. This is NOT a swallowed error (which fail-loud forbids) — it is a
+ * checked precondition: a genuinely-absent session legitimately means
+ * "start fresh", and the per-agent isolation DX-1071 enforced falls out for
+ * free (agent B's cwd never contains agent A's session file).
+ */
+export function sessionUuidExistsInCleanRoom(cwd, uuid) {
+    return existsSync(join(deriveSessionDir(cwd), `${uuid}.jsonl`));
+}
+/**
+ * Finds the newest .jsonl file in a directory.
+ * Returns the full path, or null if no .jsonl files exist.
+ */
+export async function findNewestJsonlFile(dir, sessionId) {
+    try {
+        const files = await readdir(dir);
+        const jsonlFiles = files.filter((f) => f.endsWith(".jsonl"));
+        if (jsonlFiles.length === 0)
+            return null;
+        // If a specific session ID is requested, look for that exact file
+        if (sessionId) {
+            const target = `${sessionId}.jsonl`;
+            if (jsonlFiles.includes(target)) {
+                return join(dir, target);
+            }
+            return null;
+        }
+        // Find the newest by mtime
+        let newest = null;
+        for (const file of jsonlFiles) {
+            const filePath = join(dir, file);
+            try {
+                const stats = await stat(filePath);
+                const mtime = stats.mtimeMs;
+                if (!newest || mtime > newest.mtime) {
+                    newest = { path: filePath, mtime };
+                }
+            }
+            catch (err) {
+                // DX-1201 — one unreadable/rotated sibling must NOT abort the whole
+                // mtime scan (see the matching guard in
+                // `findSessionFileByDispatchId`). A sibling deleted mid-scan
+                // (ENOENT) or otherwise unstattable just gets skipped.
+                const code = err.code;
+                if (code !== "ENOENT") {
+                    log.warn(`Skipping unstattable session file during newest-file scan: ${filePath} (${code ?? String(err)})`);
+                }
+                continue;
+            }
+        }
+        return newest?.path ?? null;
+    }
+    catch (err) {
+        // Directory doesn't exist yet — expected during agent startup
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+}
+/**
+ * Finds a JSONL session file that contains the dispatch tag for a specific job ID.
+ *
+ * Scans each `.jsonl` file for the dispatch tag
+ * `<!-- danxbot-dispatch:<dispatchId> -->`, injected into the piped prompt
+ * by the launcher.
+ *
+ * The tag's position depends on whether this is a fresh spawn or a
+ * `claude --resume`:
+ *   - **Fresh** — the tag is in the FIRST `user` entry, near the head of a
+ *     brand-new file.
+ *   - **Resume (DX-1106)** — claude appends the new dispatch's tagged
+ *     prompt to the END of the prior session's already-multi-MB JSONL, so
+ *     the tag sits in the TAIL, far past any fixed head window. A
+ *     head-only scan never matches a resumed session → the watcher gives
+ *     up after 180s → no session_uuid stamp, no heartbeat, no stall
+ *     detection for that dispatch.
+ *
+ * So we scan BOTH a head window and a tail window (they overlap, covering
+ * the whole file, for any file ≤ 2x`SCAN_BYTES`). A resumed tag always
+ * lands in the freshly-appended tail; a fresh tag always lands in the head.
+ *
+ * Returns the full path to the matching file, or null if no file matches.
+ */
+export async function findSessionFileByDispatchId(dir, dispatchId) {
+    const tag = `${DISPATCH_TAG_PREFIX}${dispatchId} -->`;
+    const SCAN_BYTES = 65_536; // 64KB — enough to cover a fresh prompt entry
+    // (head) or the appended resume prompt (tail).
+    try {
+        const files = await readdir(dir);
+        const jsonlFiles = files.filter((f) => f.endsWith(".jsonl"));
+        // 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")
+            return null;
+        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
+ * in `findSessionFileByDispatchId` share one read path.
+ */
+async function windowIncludesTag(fd, from, fileSize, maxBytes, tag) {
+    const len = Math.min(maxBytes, fileSize - from);
+    if (len <= 0)
+        return false;
+    const buffer = Buffer.alloc(len);
+    await fd.read(buffer, 0, len, from);
+    return buffer.toString("utf-8", 0, len).includes(tag);
+}
+/**
+ * Converts a raw JSONL entry from Claude Code's session log into an AgentLogEntry
+ * used by downstream consumers (stall detection, event forwarding).
+ */
+export function convertJsonlEntry(raw, lastTimestamp) {
+    const type = raw.type;
+    const timestamp = raw.timestamp
+        ? new Date(raw.timestamp).getTime()
+        : Date.now();
+    const deltaMs = lastTimestamp > 0 ? timestamp - lastTimestamp : 0;
+    const message = raw.message;
+    switch (type) {
+        case "assistant": {
+            if (!message)
+                return null;
+            const content = (message.content ?? []);
+            const usage = message.usage;
+            // Claude Code splits multi-block assistant turns (text + tool_use,
+            // thinking + text + tool_use, etc.) into one JSONL line per content
+            // block, but stamps the SAME response-level `message.usage` on every
+            // line. Surface `messageId` so downstream usage accumulators can dedupe
+            // — without it, every multi-block turn over-counts tokens 2-5x. See
+            // `.claude/rules/agent-dispatch.md`.
+            const messageId = typeof message.id === "string" && message.id.length > 0
+                ? message.id
+                : undefined;
+            // DX-1720 — surface the turn's model EXPLICITLY on `entry.data` so the
+            // usage accumulator buckets per-model usage without reaching into
+            // `raw`. `message.model` is the JSONL assistant turn's resolved model
+            // id (an exact version, not a line); undefined on the rare malformed turn.
+            const model = typeof message.model === "string" && message.model.length > 0
+                ? message.model
+                : undefined;
+            return {
+                entry: {
+                    timestamp,
+                    type: "assistant",
+                    summary: buildAssistantSummary(content),
+                    data: {
+                        messageId,
+                        model,
+                        content,
+                        usage,
+                        delta_ms: deltaMs,
+                        raw,
+                    },
+                },
+                timestamp,
+            };
+        }
+        case "user": {
+            if (!message)
+                return null;
+            const content = message.content;
+            if (typeof content === "string")
+                return null;
+            const contentArr = (content ?? []);
+            if (contentArr.length === 0)
+                return null;
+            const hasToolResults = contentArr.some((b) => b.type === "tool_result");
+            if (!hasToolResults)
+                return null;
+            return {
+                entry: {
+                    timestamp,
+                    type: "user",
+                    summary: buildToolResultSummary(contentArr),
+                    data: {
+                        content: contentArr,
+                        delta_ms: deltaMs,
+                        raw: raw,
+                    },
+                },
+                timestamp,
+            };
+        }
+        case "system": {
+            const subtype = raw.subtype;
+            if (subtype === "init") {
+                return {
+                    entry: {
+                        timestamp,
+                        type: "system",
+                        subtype: "init",
+                        summary: `Session initialized: ${raw.model || "unknown"}`,
+                        data: {
+                            session_id: raw.session_id,
+                            model: raw.model,
+                            tools: raw.tools,
+                            delta_ms: deltaMs,
+                            raw,
+                        },
+                    },
+                    timestamp,
+                };
+            }
+            return null;
+        }
+        case "result": {
+            const subtype = raw.subtype || "success";
+            const costUsd = raw.cost_usd || 0;
+            const numTurns = raw.num_turns || 0;
+            return {
+                entry: {
+                    timestamp,
+                    type: "result",
+                    subtype,
+                    summary: `${subtype}: ${numTurns} turns, $${costUsd.toFixed(4)}`,
+                    data: {
+                        subtype,
+                        result_text: raw.result || "",
+                        total_cost_usd: costUsd,
+                        num_turns: numTurns,
+                        duration_ms: raw.duration_ms || 0,
+                        duration_api_ms: raw.duration_api_ms || 0,
+                        is_error: Boolean(raw.is_error),
+                        delta_ms: deltaMs,
+                        raw,
+                    },
+                },
+                timestamp,
+            };
+        }
+        default:
+            // Skip metadata types: permission-mode, attachment, file-history-snapshot, queue-operation, last-prompt
+            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 = [];
+    usageConsumers = [];
+    pollTimer;
+    parentTail = null;
+    subagentsDir = null;
+    subagentTails = new Map();
+    parentSessionId = null;
+    sessionDir;
+    sessionId;
+    dispatchId;
+    pollIntervalMs;
+    startCursors;
+    startExistingFilesAtEof;
+    onCursorPastEof;
+    onSourceDiscovered;
+    onPollComplete;
+    subagentDiscoveryDone = false;
+    running = false;
+    polling = false;
+    // DX-2962: entries are NOT accumulated here — see `emitEntry`. Only
+    // consumers registered via `onEntry` observe entries; the watcher itself
+    // never holds a whole-process-lifetime list (that was the old
+    // `getEntries()` surface, deleted along with its accumulator — the
+    // pre-extraction contract kept an unbounded `AgentLogEntry[]` alive for
+    // the life of every dispatch, purely so three tests could read it back).
+    initSynthesized = false;
+    constructor(options) {
+        this.sessionDir = options.sessionDir ?? deriveSessionDir(options.cwd);
+        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;
+        this.onPollComplete = options.onPollComplete;
+    }
+    /**
+     * 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) {
+        this.consumers.push(consumer);
+    }
+    /**
+     * DX-3964 - register a usage-feed consumer: it receives the parsed raw line of every assistant, user,
+     * attachment and system line, in file order, with the same `EntryMeta` as `onEntry`. The ONLY subscribers are
+     * the collector's two consumers at each of its two sites (the worker and the operator session's relay): `DispatchUsage`
+     * and, DX-4498, the activity observer, which reads the sub-agent's brief and Claude Code's task notifications,
+     * neither of which is an entry. `convertJsonlEntry` and every
+     * `onEntry` subscriber keep seeing exactly what they saw before, because human prompts, attachments (tens of
+     * thousands of hook records) and system lines are not theirs.
+     *
+     * Each consumer runs in its own try/catch, as in `emitEntry`: a consumer that throws (a
+     * `LedgerLineDataError` on a line with no timestamp) never withholds the line from `onEntry` subscribers.
+     */
+    onUsageLine(consumer) {
+        this.usageConsumers.push(consumer);
+    }
+    /** Returns the discovered parent session file path, or null if not yet found. */
+    getSessionFilePath() {
+        return this.parentTail?.filePath ?? null;
+    }
+    /**
+     * Resolve this dispatch's JSONL session file by a one-shot disk scan,
+     * independent of the live tail loop (DX-1201).
+     *
+     * The live watcher records `session_uuid` lazily from the FIRST emitted
+     * entry. If discovery ever fails to attach within the dispatch's lifetime —
+     * a transient `open`/`stat`/`read` error on a busy shared session dir, or a
+     * timing window where the spawn finalizes before the first poll observed an
+     * entry — that lazy path never fires and the row's `session_uuid` stays
+     * NULL, breaking same-thread Slack resume (the dispatch is not resumable).
+     *
+     * This method gives the finalize backstop a deterministic, cause-agnostic
+     * way to resolve the file: by the time a dispatch finalizes, the agent's
+     * the dispatch-complete call's tool_use is already written to the JSONL, so the file
+     * is guaranteed present on disk. It scans the watcher's OWN `sessionDir`
+     * (the dir derived from `agentCwd` at construction — the same dir claude
+     * wrote to) for the dispatch tag. Returns the file path, or null when no
+     * dispatchId is set or no file carries the tag.
+     *
+     * Prefers the already-discovered `parentTail.filePath` when the live loop
+     * did attach — no redundant scan on the happy path.
+     */
+    async resolveSessionFileNow() {
+        if (this.parentTail?.filePath)
+            return this.parentTail.filePath;
+        if (!this.dispatchId)
+            return null;
+        return findSessionFileByDispatchId(this.sessionDir, this.dispatchId);
+    }
+    /** Start polling for session log entries. */
+    async start() {
+        if (this.running)
+            return;
+        this.running = true;
+        await this.discoverSessionFile();
+        if (this.running && this.parentTail) {
+            this.pollTimer = setInterval(() => this.poll(), this.pollIntervalMs);
+            await this.poll();
+        }
+    }
+    /** Stop polling and clean up. */
+    stop() {
+        this.running = false;
+        if (this.pollTimer) {
+            clearInterval(this.pollTimer);
+            this.pollTimer = undefined;
+        }
+    }
+    /**
+     * Read any JSONL bytes appended since the last scheduled poll tick. Used by
+     * the launcher's cleanup path to capture the agent's final assistant entry
+     * (the one carrying the closing `usage` block + the `tool_use` for
+     * the dispatch-complete call) before stop() halts polling. Without this, the row
+     * finalized by `DispatchTracker.finalize` snapshots stale `job.usage` and
+     * the dispatches table undercounts every token + counter field by exactly
+     * what the JSONL grew between ticks.
+     *
+     * Race contract: if a scheduled `poll()` is already in flight when drain
+     * is called, the first poll() invoked here would early-return at the
+     * `this.polling` guard and silently miss the tail. To avoid that silent
+     * skip we yield until the in-flight poll completes, then run our own
+     * poll. The combined effect is "every byte written before drain returns
+     * has been observed" — exactly the guarantee finalize depends on.
+     *
+     * No-op when the parent file has not been discovered (drain before
+     * start, or start aborted) — there is nothing to read. Safe to call
+     * after `stop()`; returns immediately.
+     */
+    async drain() {
+        if (!this.running || !this.parentTail)
+            return;
+        // Wait for any in-flight scheduled poll to finish so our subsequent
+        // poll() doesn't hit the `this.polling` guard. The await yields so
+        // setInterval-driven polls can complete; we only loop a few microtasks
+        // in the worst case (one scheduled poll cycle).
+        while (this.polling) {
+            await new Promise((resolve) => setImmediate(resolve));
+        }
+        await this.poll();
+    }
+    /**
+     * DX-5413 - the dispatch cleanup's last read, before `stop()`. An end signal (a sub-agent's spawn result or task-notification) read
+     * by one poll confirms the held final only at the NEXT poll's end, so a single drain would lose a final whose end signal first
+     * appears in it. Two drains read every line written before the first one began, in file order; a signal found by the first has
+     * its whole sub-agent read by the second, which confirms it. This holds whether or not the agent process has exited, so no
+     * cleanup path has to prove an exit first. A signal first written after the first drain began is not confirmed.
+     * The count is tied to the observer's one-poll delay (`endedAwaitingPoll` in activity-observer.ts): change one, change the other.
+     */
+    async drainFinal() {
+        await this.drain();
+        await this.drain();
+    }
+    /**
+     * Discover the JSONL session file. Polls until found or max attempts reached.
+     * For dispatched agents, the file appears shortly after the process starts.
+     */
+    async discoverSessionFile() {
+        for (let attempt = 0; attempt < MAX_FILE_DISCOVERY_ATTEMPTS; attempt++) {
+            if (!this.running)
+                return;
+            const filePath = this.dispatchId
+                ? await findSessionFileByDispatchId(this.sessionDir, this.dispatchId)
+                : await findNewestJsonlFile(this.sessionDir, this.sessionId);
+            if (filePath && (await this.setParentFile(filePath))) {
+                const tag = this.dispatchId ? `[Dispatch ${this.dispatchId}] ` : "";
+                log.info(`${tag}Watching session file: ${filePath}`);
+                return;
+            }
+            await new Promise((resolve) => setTimeout(resolve, FILE_DISCOVERY_POLL_MS));
+        }
+        log.error(`Session file not found after ${MAX_FILE_DISCOVERY_ATTEMPTS}s in ${this.sessionDir}`);
+    }
+    /**
+     * 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.
+     */
+    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;
+        this.parentTail = {
+            filePath,
+            byteOffset,
+            lineBuffer: "",
+            lineBufferStartOffset: byteOffset,
+            lastTimestamp: 0,
+            source: MAIN_SOURCE,
+            startOffset: byteOffset,
+            replayUntil,
+            discoveredAt: Date.now(),
+            lastWriteAt: 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.
+     * Guarded against concurrent polls and against stop() racing an in-flight poll.
+     */
+    async poll() {
+        if (this.polling || !this.parentTail || !this.running)
+            return;
+        this.polling = true;
+        try {
+            await this.pollFile(this.parentTail);
+            if (!this.running)
+                return;
+            await this.discoverNewSubagentFiles();
+            await this.refreshPendingAgentTypes();
+            for (const state of this.subagentTails.values()) {
+                if (!this.running)
+                    return;
+                await this.pollFile(state);
+            }
+        }
+        finally {
+            this.polling = false;
+        }
+        // DX-4508 — only a poll that ran to its end: a stop mid-poll returns above and reports nothing.
+        try {
+            this.onPollComplete?.();
+        }
+        catch (err) {
+            log.error("onPollComplete consumer error:", err);
+        }
+    }
+    /** Read any new bytes from `state.filePath` and emit resulting entries. */
+    async pollFile(state) {
+        const isSubagent = state.lineage !== undefined;
+        // Refresh lineage inline before reading new bytes so emissions reflect
+        // the latest meta.json + parent session id even if the central refresh
+        // missed this cycle. Closes the race in production where claude writes
+        // `.jsonl` then `.meta.json` and a poll catches the new bytes between
+        // those writes — without this, the entry would emit permanently stamped
+        // with agent_type=undefined. archived investigation.
+        if (isSubagent) {
+            await this.refreshLineage(state);
+        }
+        try {
+            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) {
+                return;
+            }
+            const fd = await open(state.filePath, "r");
+            try {
+                if (!this.running)
+                    return;
+                const bytesToRead = fileStats.size - state.byteOffset;
+                const buffer = Buffer.alloc(bytesToRead);
+                const { bytesRead } = await fd.read(buffer, 0, bytesToRead, state.byteOffset);
+                if (!this.running)
+                    return;
+                if (bytesRead === 0)
+                    return;
+                state.byteOffset += bytesRead;
+                const text = buffer.toString("utf-8", 0, bytesRead);
+                this.processText(text, state);
+            }
+            finally {
+                await fd.close();
+            }
+        }
+        catch (err) {
+            if (err.code === "ENOENT") {
+                if (isSubagent) {
+                    // Sub-agent file gone — drop it; next discoverNewSubagentFiles
+                    // will pick up any replacement.
+                    this.subagentTails.delete(state.filePath);
+                }
+                else {
+                    log.warn("Parent session file disappeared, attempting rediscovery");
+                    this.parentTail = null;
+                    this.subagentsDir = null;
+                    this.subagentTails.clear();
+                    // DX-5333: the adopted file's sub-agent directory gets its own first pass (its existing files are pre-existing).
+                    this.subagentDiscoveryDone = false;
+                    this.parentSessionId = null;
+                    await this.discoverSessionFile();
+                }
+            }
+            else {
+                log.error("Poll error:", err);
+            }
+        }
+    }
+    /**
+     * Re-enumerate the sub-agent directory and add tail states for any
+     * `agent-<hash>.jsonl` files not already being tailed.
+     */
+    async discoverNewSubagentFiles() {
+        if (!this.subagentsDir)
+            return;
+        let files;
+        try {
+            files = await readdir(this.subagentsDir);
+        }
+        catch (err) {
+            if (err.code === "ENOENT") {
+                // DX-5333 — a session's `subagents/` directory is created by its first spawn. An absent directory holds no
+                // pre-existing file, so the first pass is settled: the file that later appears started after attach and must
+                // not be reported `preexisting` (its start commit would go unstamped).
+                this.subagentDiscoveryDone = true;
+                return;
+            }
+            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;
+        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 meta = await this.readSubagentMeta(subagentId);
+            const start = await this.resolveStart(subagentId, fullPath, firstPass);
+            if (start === null) {
+                allResolved = false;
+                continue;
+            }
+            const { byteOffset, replayUntil } = start;
+            const discoveredAt = Date.now();
+            // DX-5110: a pre-existing file's last write, never the discovery time (see `SourceDiscoveredInfo.lastWriteAt`).
+            // The wire and the column are integers, and a real `mtimeMs` is fractional: floor it. A file that vanished between
+            // the `readdir` and here is retried next poll, like a `resolveStart` that could not settle.
+            let lastWriteAt = discoveredAt;
+            if (firstPass) {
+                try {
+                    lastWriteAt = Math.min(discoveredAt, Math.floor((await stat(fullPath)).mtimeMs));
+                }
+                catch {
+                    allResolved = false;
+                    continue;
+                }
+            }
+            this.subagentTails.set(fullPath, {
+                filePath: fullPath,
+                byteOffset,
+                lineBufferStartOffset: byteOffset,
+                lineBuffer: "",
+                lastTimestamp: 0,
+                source: subagentId,
+                startOffset: byteOffset,
+                replayUntil,
+                discoveredAt,
+                preexisting: firstPass,
+                lastWriteAt,
+                meta,
+                lineage: {
+                    subagent_id: subagentId,
+                    parent_session_id: this.parentSessionId,
+                    agent_type: meta?.agentType ?? undefined,
+                },
+            });
+            // 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, meta, discoveredAt, firstPass, lastWriteAt);
+        }
+        if (allResolved)
+            this.subagentDiscoveryDone = true;
+    }
+    /** Centralized lineage refresh — see `refreshLineage` for the per-state body. */
+    async refreshPendingAgentTypes() {
+        for (const state of this.subagentTails.values()) {
+            await this.refreshLineage(state);
+        }
+    }
+    /**
+     * Refresh `state.lineage` by re-reading the meta sidecar and back-filling
+     * parent_session_id from the most recent parent observation. Idempotent:
+     * once `agent_type` is set it stays set (never read meta twice). Used by
+     * both the centralized `refreshPendingAgentTypes` and the inline call from
+     * `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, meta, discoveredAt, preexisting, lastWriteAt) {
+        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` columns all spell absent as `null`.
+                // Normalizing here keeps every consumer from accepting both.
+                agentType: meta?.agentType ?? null,
+                description: meta?.description ?? null,
+                parentSource: meta?.parentSource ?? null,
+                foregroundToolUseId: meta?.foregroundToolUseId ?? null,
+                discoveredAt,
+                preexisting,
+                lastWriteAt,
+            });
+        }
+        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.
+        // DX-4498 — the whole sidecar (type, label, parent) is learned in one read, so it is re-read only until it exists.
+        const metaWasUnknown = state.meta === undefined;
+        if (metaWasUnknown) {
+            state.meta = await this.readSubagentMeta(state.lineage.subagent_id);
+            agent_type = state.meta?.agentType ?? undefined;
+        }
+        if (metaWasUnknown && state.meta !== 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, state.meta, state.discoveredAt, state.preexisting, state.lastWriteAt);
+        }
+        if (parent_session_id === null && this.parentSessionId !== null) {
+            parent_session_id = this.parentSessionId;
+        }
+        state.lineage = {
+            subagent_id: state.lineage.subagent_id,
+            parent_session_id,
+            agent_type,
+        };
+    }
+    /**
+     * Read the `<subagentId>.meta.json` sidecar (DX-4498: its type, label and spawning sub-agent). Returns
+     * undefined only for ENOENT (file not written yet). Malformed JSON or
+     * permission errors are logged at WARN and return undefined — the watcher
+     * must not crash on bad sidecar files, but the failure is visible in logs.
+     * A key the sidecar lacks, or carries as anything but a non-empty string, is `null`.
+     */
+    async readSubagentMeta(subagentId) {
+        if (!this.subagentsDir)
+            return undefined;
+        const metaPath = join(this.subagentsDir, `${subagentId}.meta.json`);
+        const text = (v) => (typeof v === "string" && v !== "" ? v : null);
+        try {
+            const raw = JSON.parse(await readFile(metaPath, "utf-8"));
+            const parentAgentId = text(raw.parentAgentId);
+            return {
+                agentType: text(raw.agentType),
+                description: text(raw.description),
+                // The parent's own transcript is `agent-<parentAgentId>.jsonl`, so this is its source key.
+                parentSource: parentAgentId === null ? null : `agent-${parentAgentId}`,
+                // DX-5333: only a foreground spawn's result marks its end; a background spawn's `async_launched` result arrives at launch.
+                foregroundToolUseId: raw.requestShape === "foreground" ? text(raw.toolUseId) : null,
+            };
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === "ENOENT")
+                return undefined;
+            log.warn(`Failed to read sub-agent meta for ${subagentId}: ${String(err)}`);
+            return undefined;
+        }
+    }
+    /** Process raw text from a file tail, handling partial lines across poll ticks. */
+    processText(text, state) {
+        state.lineBuffer += text;
+        let newlineIdx;
+        while ((newlineIdx = state.lineBuffer.indexOf("\n")) !== -1) {
+            const rawLine = state.lineBuffer.substring(0, newlineIdx);
+            const lineStart = state.lineBufferStartOffset;
+            state.lineBufferStartOffset += Buffer.byteLength(rawLine, "utf-8") + 1;
+            const line = rawLine.trim();
+            state.lineBuffer = state.lineBuffer.substring(newlineIdx + 1);
+            if (!line)
+                continue;
+            try {
+                const raw = JSON.parse(line);
+                this.handleRawEntry(raw, state, lineStart);
+            }
+            catch {
+                log.warn(`Skipping malformed JSONL line: ${line.substring(0, 100)}`);
+            }
+        }
+    }
+    /**
+     * Convert a raw JSONL entry and emit to consumers.
+     *
+     * Init synthesis (parent stream only): the persisted JSONL transcript never
+     * carries a `system/init` line in ANY runtime — Claude Code (2.1.201) only
+     * streams that event over stdout (`--output-format stream-json`), which the
+     * docker spawn path intentionally never reads (`spawn-docker-mode.ts`), and
+     * host's interactive JSONL never wrote one either. So we ALWAYS synthesize
+     * one from the first assistant message's sessionId and model, on host AND
+     * docker alike. Sub-agent streams never synthesize — their entries flow
+     * under the parent dispatch's existing session.
+     *
+     * IMPORTANT (DX-651): synthesized init events carry `tools: []` and
+     * `data.synthesized: true` — this watcher never observes the real
+     * MCP-registered tool / skill / agent list for EITHER runtime. Any consumer
+     * that wants to check what actually loaded (tools, skills, agents) MUST
+     * skip an entry carrying `data.synthesized === true` — treating it as a
+     * truthful docker `system/init` (as `declared-loaded-observer.ts` used to,
+     * gating on runtime alone) manufactures a guaranteed false
+     * declared-not-loaded drift for every dispatch with a non-empty declared
+     * skill/agent set. The pre-launch probe in `mcp-server-probe.ts` is the
+     * tool-registration check that works across both runtimes.
+     */
+    handleRawEntry(raw, state, lineStart) {
+        const isSubagent = state.lineage !== undefined;
+        if (typeof raw.type === "string" && USAGE_FEED_TYPES.has(raw.type)) {
+            const meta = this.entryMeta(state, lineStart);
+            for (const consumer of this.usageConsumers) {
+                try {
+                    consumer(raw, meta);
+                }
+                catch (err) {
+                    log.error("Usage line consumer error:", err);
+                }
+            }
+        }
+        if (!isSubagent && !this.initSynthesized && raw.type === "assistant") {
+            const message = raw.message;
+            const model = message?.model;
+            const sessionId = raw.sessionId;
+            if (sessionId || model) {
+                this.parentSessionId = sessionId ?? this.parentSessionId;
+                const initEntry = {
+                    timestamp: raw.timestamp
+                        ? new Date(raw.timestamp).getTime()
+                        : Date.now(),
+                    type: "system",
+                    subtype: "init",
+                    summary: `Session initialized: ${model || "unknown"}`,
+                    data: {
+                        session_id: sessionId || "",
+                        model: model || "",
+                        tools: [],
+                        delta_ms: 0,
+                        raw: {},
+                        synthesized: true,
+                    },
+                };
+                this.emitEntry(initEntry, state, lineStart);
+                this.initSynthesized = true;
+            }
+        }
+        const result = convertJsonlEntry(raw, state.lastTimestamp);
+        if (!result)
+            return;
+        if (!isSubagent &&
+            result.entry.type === "system" &&
+            result.entry.subtype === "init") {
+            this.initSynthesized = true;
+            const sid = result.entry.data.session_id;
+            if (sid)
+                this.parentSessionId = sid;
+        }
+        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);
+    }
+    /**
+     * 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.
+     */
+    entryMeta(state, byteOffset) {
+        return {
+            source: state.source,
+            byteOffset,
+            replay: byteOffset < state.replayUntil,
+            sessionId: transcriptSessionId(state.filePath),
+        };
+    }
+    /**
+     * Emit an entry to registered consumers. For sub-agent streams,
+     * `state.lineage` decorates `entry.data` so the emitted EventPayload
+     * (via mapEntryToEvents) inherits subagent_id/parent_session_id/agent_type.
+     *
+     * DX-2962: no longer also pushes onto an internal `this.entries` array —
+     * the pre-extraction watcher kept every entry alive for the life of the
+     * process purely so `getEntries()` (deleted) could hand it back to three
+     * tests; nothing else read it. Every real consumer subscribes via
+     * `onEntry` instead.
+     */
+    emitEntry(entry, state, byteOffset) {
+        if (state.lineage) {
+            entry.data = {
+                ...entry.data,
+                subagent_id: state.lineage.subagent_id,
+                parent_session_id: state.lineage.parent_session_id,
+                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 = this.entryMeta(state, byteOffset);
+        for (const consumer of this.consumers) {
+            try {
+                consumer(entry, meta);
+            }
+            catch (err) {
+                log.error("Consumer error:", err);
+            }
+        }
+    }
+}