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

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

@@ -0,0 +1,616 @@
+/**
+ * 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 type { AgentLogEntry } from "./types.js";
+/**
+ * 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 declare const DISPATCH_TAG_PREFIX = "<!-- danxbot-dispatch:";
+/**
+ * A consumer of transcript lines.
+ *
+ * DX-2954 added the second argument. A consumer that ignores it behaves exactly
+ * as before; a consumer with a SIDE EFFECT must read `meta.replay` and skip a
+ * re-read line (see {@link EntryMeta.replay}).
+ */
+export type EntryConsumer = (entry: AgentLogEntry, meta: EntryMeta) => void;
+/**
+ * DX-3964 - a consumer of the usage feed: the PARSED RAW line (assistant, user, attachment or system - nothing
+ * else) with the same {@link EntryMeta} an `onEntry` consumer gets. Collector-only (the usage counter and the
+ * activity observer): see
+ * {@link SessionLogWatcher.onUsageLine}.
+ */
+export type UsageLineConsumer = (raw: Record<string, unknown>, meta: EntryMeta) => void;
+/**
+ * DX-2954 — the ONE replay gate every side-effecting transcript subscriber goes
+ * through (Slack progress, the gpt-manager forwarder): it hands on only lines
+ * read for the FIRST time. A replay was already handed to the previous
+ * incarnation's subscribers, so acting on it again is a duplicate post/event.
+ */
+export declare function skipReplays(consumer: (entry: AgentLogEntry) => void): EntryConsumer;
+export interface SessionLogWatcherOptions {
+    /** Working directory the agent was launched in. Used to derive the session directory. */
+    cwd: string;
+    /** How often to poll for new entries in milliseconds. Default: 5000. */
+    pollIntervalMs?: number;
+    /** Specific session ID to watch. If omitted, watches the newest .jsonl file. */
+    sessionId?: string;
+    /** Override the session directory path (for testing). */
+    sessionDir?: string;
+    /**
+     * Dispatch job ID to search for in JSONL file content.
+     * When set, the watcher scans files for the `<!-- danxbot-dispatch:<id> -->` tag
+     * instead of picking the newest file by mtime. This prevents picking up the wrong
+     * session file (e.g., an active human session) when the agent's file doesn't exist yet.
+     */
+    dispatchId?: string;
+    /**
+     * DX-2954 — where each source resumes: the cursors the SERVER has stored for
+     * this dispatch, keyed by source ({@link MAIN_SOURCE} for the main transcript,
+     * the sub-agent id for a sub-agent file).
+     *
+     * An ABSENT source key means no cursor is stored for it — never "start at 0".
+     * The two are different: 0 is a legitimate stored cursor meaning "start of
+     * file", and CP1 forbids defaulting a missing persisted value. See
+     * {@link SessionLogWatcherOptions.startExistingFilesAtEof} and the start-order
+     * table on {@link SessionLogWatcher} for what happens when a source has none.
+     *
+     * This REPLACED the pre-DX-2954 `fromEof` / `existingSubagentFilesFromEof`
+     * pair, which skipped straight to a file's end on every reattach and every
+     * `--resume` because there was nowhere to record how far a reader had got.
+     * That lost every line between the last write and the restart; a cursor does
+     * not.
+     */
+    startCursors: Record<string, SourceCursorStart>;
+    /**
+     * DX-2954 — rule 4 of the start order: start every ALREADY-EXISTING file at
+     * its current end.
+     *
+     * Set ONLY by a WORKER dispatch that continues a session and has no cursor
+     * for ANY source — a row from before this card shipped, or a `--resume` whose
+     * predecessor predates it. Those files hold a prior dispatch's accounting with
+     * no ledger rows to dedupe against, so reading them from 0 re-sums the whole
+     * session (the 421M-cache-read inflation of DX-2583). A file that appears
+     * LATER is genuinely new and still starts at 0.
+     *
+     * It must never be set alongside cursors for some sources: rule 5 says a
+     * sub-agent file that appeared after the last stats write, on a dispatch that
+     * HAS cursors, starts at 0 so none of its lines are lost.
+     */
+    startExistingFilesAtEof?: boolean;
+    /**
+     * DX-2954 — a stored cursor was PAST the end of its file (the file was
+     * replaced or truncated), so that source restarted at 0.
+     *
+     * Without this the watcher would silently tail nothing for the rest of the
+     * dispatch: its `size <= byteOffset` early return is indistinguishable from
+     * "no new bytes". The caller records a visible `transcript_cursor_past_eof`
+     * event with both numbers and marks the reset in its next stats write, which
+     * is the ONE sanctioned backwards move of a stored `acked`.
+     */
+    onCursorPastEof?: (info: CursorPastEofInfo) => void;
+    /**
+     * DX-2954 — a sub-agent transcript just came under tail for the first time,
+     * i.e. a sub-agent of this dispatch is RUNNING.
+     *
+     * This is the transcript-side producer of the dispatch's running set. It
+     * reports the sub-agent's ledger source key, which is the same value its
+     * `dispatch_activities.activity_id` and its per-source token total join on —
+     * so a hook-side producer reporting the same sub-agent by its `agent_id`
+     * (`agent-` + the id, DX-3284) resolves to this same id and upserts the SAME
+     * row rather than a duplicate.
+     *
+     * Fired once per source, from the discovery pass, for sub-agent files only —
+     * never for the main transcript, which is the dispatch itself, not an activity
+     * within it.
+     */
+    onSourceDiscovered?: (info: SourceDiscoveredInfo) => void;
+    /**
+     * DX-4508 — one poll (the main transcript, sub-agent discovery, then every sub-agent file) has finished handing its
+     * lines to subscribers. The live sub-agent view (`platform-mcp subagents-live`) prints one line per poll from
+     * it, so a reader sees every change one poll made together. A throw is contained like every consumer's.
+     */
+    onPollComplete?: () => void;
+}
+/** DX-2954 — one source's stored cursor pair, as a collector starts from it. */
+export interface SourceCursorStart {
+    /** The resume point: read on from here. */
+    acked: number;
+    /**
+     * The highest byte already handed to subscribers. Lines between `acked` and
+     * this are re-read and handed on marked as REPLAYS, so side-effecting
+     * subscribers skip them while the ledger and the log shipper still see them.
+     */
+    delivered: number;
+}
+/** DX-2954 — reported when a stored cursor was past its file's end. */
+export interface CursorPastEofInfo {
+    source: string;
+    storedOffset: number;
+    fileSize: number;
+}
+/** DX-2954 — reported when a sub-agent's transcript comes under tail. */
+export interface SourceDiscoveredInfo {
+    /** The sub-agent's ledger source key (its transcript file's basename). */
+    source: string;
+    /**
+     * The sub-agent's declared type, read from its `meta.json` sidecar. `null` when
+     * Claude Code has not written the sidecar yet — it is reported again once read,
+     * and a hook-side report of the same sub-agent fills it in without clobbering a
+     * value already stored.
+     */
+    agentType: string | null;
+    /** DX-4498 — the label the spawning `Agent` call gave it (`meta.json` `description`); null until the sidecar is read. */
+    description: string | null;
+    /** DX-4498 — the source key of the sub-agent that spawned it (`agent-<parentAgentId>`); null for one the session spawned. */
+    parentSource: string | null;
+    /**
+     * DX-5333 — the `tool_use` id of the spawner's call that started this sub-agent, only when its `meta.json` `requestShape` is
+     * `foreground` (the spawner then waits for it, and the result of that call is written when the sub-agent is done). Null for a
+     * background spawn (its result arrives at launch), a sidecar not yet read, or one without the key.
+     */
+    foregroundToolUseId: string | null;
+    /** Epoch ms this watcher first saw the file. */
+    discoveredAt: number;
+    /**
+     * The file already existed when this watcher attached (found on its FIRST
+     * discovery pass). A consumer attached to a dispatch that CONTINUES an earlier
+     * one (a `--resume`, a dispatcher or thread resume) uses this to tell its
+     * predecessor's sub-agents, which ended with that process, from its own.
+     */
+    preexisting: boolean;
+    /**
+     * DX-5110 — epoch ms the sub-agent last wrote: the file's mtime when it already existed at attach (a restarted
+     * collector re-discovers every finished sub-agent, and reporting those as active "now" revived them), else the
+     * discovery time. A consumer's initial `lastActivityAt`, never the discovery wall clock.
+     */
+    lastWriteAt: number;
+}
+/**
+ * DX-2954 — what a consumer learns about the line it is being handed, beyond
+ * the entry itself.
+ */
+export interface EntryMeta {
+    /** {@link MAIN_SOURCE} for the main transcript, else the sub-agent id. */
+    source: string;
+    /** Byte offset of the line's first byte in its file. */
+    byteOffset: number;
+    /**
+     * This line was already handed to a PREVIOUS incarnation's subscribers (it
+     * falls below the source's stored `delivered` cursor) and is being handed
+     * again after a restart.
+     *
+     * Every subscriber with a SIDE EFFECT must skip a replay — re-posting Slack
+     * progress, re-forwarding to gpt-manager, or re-running the API-error
+     * detector on a predecessor's last lines are all real, visible damage. The
+     * ledger and the log shipper DO process replays: both are idempotent, and
+     * skipping them is what would lose data.
+     */
+    replay: boolean;
+    /**
+     * DX-4922 - the session whose transcript this line is read from, taken from the file's own location (never from a
+     * line: a forked session's file starts with copies of its parent's lines, which keep the PARENT's `sessionId`). A
+     * main transcript is `<session id>.jsonl`; a sub-agent's is `<session id>/subagents/agent-*.jsonl`, and the lines of
+     * both carry that session id.
+     */
+    sessionId: string;
+}
+/**
+ * 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 declare function transcriptSessionId(filePath: string): string;
+/**
+ * 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 declare function encodeClaudeProjectsCwd(cwd: string): string;
+/**
+ * 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 declare function deriveSessionDir(cwd: string): string;
+/**
+ * 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 declare function sessionUuidExistsInCleanRoom(cwd: string, uuid: string): boolean;
+/**
+ * Finds the newest .jsonl file in a directory.
+ * Returns the full path, or null if no .jsonl files exist.
+ */
+export declare function findNewestJsonlFile(dir: string, sessionId?: string): Promise<string | null>;
+/**
+ * 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 declare function findSessionFileByDispatchId(dir: string, dispatchId: string): Promise<string | null>;
+/**
+ * Converts a raw JSONL entry from Claude Code's session log into an AgentLogEntry
+ * used by downstream consumers (stall detection, event forwarding).
+ */
+export declare function convertJsonlEntry(raw: Record<string, unknown>, lastTimestamp: number): {
+    entry: AgentLogEntry;
+    timestamp: number;
+} | null;
+/**
+ * DX-2954 — WHERE EACH FILE STARTS. One ordered rule set, applied per source by
+ * {@link SessionLogWatcher.resolveStart}; the caller's job is only to hand in
+ * the right `startCursors` / `startExistingFilesAtEof`.
+ *
+ * | # | Condition | Start |
+ * |---|---|---|
+ * | 1 | the dispatch has a stored cursor for this source | its `acked`, replaying up to its `delivered` |
+ * | 2 | a worker dispatch continuing a session: its predecessor's cursor for this source (the caller resolves it INTO `startCursors`, so it arrives as rule 1) | the predecessor's final `acked`, replaying to its final `delivered` |
+ * | 3 | the FIRST dispatch of its Claude session — a new worker session, or any operator dispatch (always the only one for its session id, including one opened by a mid-session `plan_connect` and a forked session's new id) | 0 |
+ * | 4 | a WORKER dispatch continuing a session with NO cursor for ANY source (a row from before this card; a `--resume` whose predecessor predates it) — `startExistingFilesAtEof` | every ALREADY-EXISTING file at its current end |
+ * | 5 | otherwise — in particular a sub-agent file that appeared AFTER the last stats write, on a dispatch that has cursors for other sources | 0 |
+ *
+ * Rules 1 and 2 arrive identically because "where does this source resume" has
+ * ONE answer; rule 4 is the only branch that skips content, and it is narrow by
+ * construction (it cannot fire when ANY source has a cursor, so rule 5 keeps a
+ * late sub-agent file's lines).
+ *
+ * Rules 3 and 5 both read from 0, but for different reasons, and both are
+ * correct: a fresh session's full usage SHOULD be counted, and a forked
+ * session's copied history is read and credited nothing (the ledger's excess
+ * rule already covers it).
+ */
+export declare class SessionLogWatcher {
+    private consumers;
+    private usageConsumers;
+    private pollTimer;
+    private parentTail;
+    private subagentsDir;
+    private subagentTails;
+    private parentSessionId;
+    private sessionDir;
+    private sessionId;
+    private dispatchId;
+    private pollIntervalMs;
+    private readonly startCursors;
+    private readonly startExistingFilesAtEof;
+    private readonly onCursorPastEof;
+    private readonly onSourceDiscovered;
+    private readonly onPollComplete;
+    private subagentDiscoveryDone;
+    private running;
+    private polling;
+    private initSynthesized;
+    constructor(options: SessionLogWatcherOptions);
+    /**
+     * DX-2954 — resolve one file's starting offset and replay boundary, per the
+     * start order on {@link SessionLogWatcher}.
+     *
+     * `fileAlreadyExisted` distinguishes rule 4 (a file present when this watcher
+     * attached, on a continuing worker dispatch with no cursor anywhere) from
+     * rule 5 (a file that appeared later, which always starts at 0 so none of its
+     * lines are lost).
+     */
+    private resolveStart;
+    /**
+     * DX-2954 — every open source's cursor state.
+     *
+     * `delivered` is the byte up to which this watcher has handed lines to
+     * subscribers, which the collector reports as the `delivered` half of its
+     * stats write. `startOffset` is where this watcher OPENED the file, and it is
+     * the floor for the `acked` half: a source that started at EOF under rule 4
+     * must never report `acked: 0`, or the next restart would read the whole file
+     * from the start and re-sum the history rule 4 exists to skip.
+     */
+    cursorState(): Record<string, {
+        startOffset: number;
+        delivered: number;
+    }>;
+    /**
+     * DX-2954 — the main source's replay boundary (its stored `delivered` cursor),
+     * or 0 when it has none.
+     *
+     * Read with {@link SessionLogWatcher.mainStartOffset} to answer "did this
+     * watcher attach mid-session?". The offset alone is not enough: because `acked`
+     * lags `delivered` by one write, a crash right after the first cursor-bearing
+     * write leaves `{acked: 0, delivered: D}`, so the next attach starts at 0 while
+     * every byte up to D is a re-read.
+     */
+    mainReplayUntil(): number;
+    /**
+     * DX-2954 — the main transcript's starting offset once discovery has run, or
+     * `null` before that.
+     *
+     * This is what "is this a mid-session attach?" is derived from now. The
+     * declared-loaded observer used to be told `reattached: true` explicitly;
+     * a non-zero main start is the same fact stated as an observation rather than
+     * a flag, and it is true for every case that matters (a reattach, a
+     * `--resume`, a resumed operator session) without a caller having to
+     * enumerate them.
+     */
+    mainStartOffset(): number | null;
+    /** Register a consumer callback that receives each new AgentLogEntry. */
+    onEntry(consumer: EntryConsumer): void;
+    /**
+     * 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: UsageLineConsumer): void;
+    /** Returns the discovered parent session file path, or null if not yet found. */
+    getSessionFilePath(): string | 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.
+     */
+    resolveSessionFileNow(): Promise<string | null>;
+    /** Start polling for session log entries. */
+    start(): Promise<void>;
+    /** Stop polling and clean up. */
+    stop(): void;
+    /**
+     * 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.
+     */
+    drain(): Promise<void>;
+    /**
+     * 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.
+     */
+    drainFinal(): Promise<void>;
+    /**
+     * Discover the JSONL session file. Polls until found or max attempts reached.
+     * For dispatched agents, the file appears shortly after the process starts.
+     */
+    private discoverSessionFile;
+    /**
+     * 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.
+     */
+    private setParentFile;
+    /**
+     * 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.
+     */
+    private poll;
+    /** Read any new bytes from `state.filePath` and emit resulting entries. */
+    private pollFile;
+    /**
+     * Re-enumerate the sub-agent directory and add tail states for any
+     * `agent-<hash>.jsonl` files not already being tailed.
+     */
+    private discoverNewSubagentFiles;
+    /** Centralized lineage refresh — see `refreshLineage` for the per-state body. */
+    private refreshPendingAgentTypes;
+    /**
+     * 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.
+     */
+    private emitSourceDiscovered;
+    private refreshLineage;
+    /**
+     * 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`.
+     */
+    private readSubagentMeta;
+    /** Process raw text from a file tail, handling partial lines across poll ticks. */
+    private processText;
+    /**
+     * 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.
+     */
+    private handleRawEntry;
+    /**
+     * 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.
+     */
+    private entryMeta;
+    /**
+     * 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.
+     */
+    private emitEntry;
+}