@thehammer/danx-session-telemetry 0.1.1

package/README.md

@@ -0,0 +1,66 @@
+# `@thehammer/danx-session-telemetry`
+
+DX-2962 — the shared Claude Code transcript collector, extracted from
+danxbot root's `src/agent/session-log-watcher.ts` so the danxbot worker and
+the `danx-dashboard-mcp` desktop bridge (DX-2954) run **identical** collector
+code, instead of the worker's copy silently diverging from a re-implementation
+inside the MCP package.
+
+## What's here
+
+- `session-log-watcher.ts` — `SessionLogWatcher`: incremental tailing of a
+  Claude Code session's main + sub-agent JSONL transcripts. No whole-transcript
+  buffer — small per-reply bookkeeping only, and only for the life of the
+  process (see its own header for the DX-2962 "unbounded entries list
+  deleted" note).
+- `types.ts` — `AgentLogEntry` / `AgentLineage`, the collector's emitted
+  shape. Canonical home now; danxbot root's `src/types.ts` re-exports both
+  names verbatim.
+- `tool-summary.ts` — human-readable summary builders the collector uses.
+- `internal-logger.ts` — this package's own tiny logging shim (see its
+  header for why it does not reuse root's `src/logger.ts`).
+- `index.ts` — the main entry (Node-only; imports `node:fs`/`node:path`/`node:os`).
+- `browser.ts` — the `./browser` subpath. Zero `node:` imports, enforced by
+  `src/__tests__/no-node-imports.test.ts`. Today it re-exports only the two
+  types (`AgentLogEntry`/`AgentLineage`); DX-2963 adds the first runtime
+  export (the usage counter + pricing function).
+
+## Isolation
+
+This package **never imports from the danxbot root repo**. Everything it
+needs (logging, tool-summary formatting, the entry/lineage types) is either
+moved in wholesale (when the root file had no other consumer) or
+re-implemented minimally as this package's own dependency (when the root
+file — like `src/logger.ts`, with ~300 unrelated consumers — was never a
+candidate to move). See `session-log-watcher.ts` and `internal-logger.ts`'s
+own header comments for the per-file reasoning.
+
+## How consumers resolve this package (DX-2962 AC3)
+
+| Consumer | Mechanism | Why |
+|---|---|---|
+| **danxbot worker** (root repo, `tsx src/index.ts`) | npm **workspace** link (`"workspaces": ["packages/*"]` in root `package.json`, `"@thehammer/danx-session-telemetry"` in root `dependencies`) | The worker and this package always ship from the SAME repo commit — a workspace link means the worker runs whatever source the current commit carries, with zero drift risk and no dependency on registry propagation timing. The Docker image builds `dist/` for it in a dedicated builder stage (mirroring `dashboard-builder`/`frontend-builder` in `Dockerfile`) since the final image's `npm ci --omit=dev` never installs this package's own `devDependencies` (`typescript`). |
+| **`danx-dashboard-mcp` desktop bridge** (separate npm-published package, DX-2954) | Ordinary npm dependency, **pinned to the exact published version** the worker's commit ships | The bridge is a genuinely separate installable artifact (`npx -y @thehammer/danx-dashboard-mcp`), so it cannot workspace-link into danxbot's own checkout — it needs the real published bytes. Pinning exact (not `^`/`~`) is what makes "worker and MCP run identical collector code for any given release" true: MCP's own version bump is the only thing that ever changes what collector code it runs. |
+| **Dashboard server / dashboard SPA** (`src/dashboard/*`, `dashboard/*`) | Same npm dependency shape as the worker (dashboard's `src/` is root-repo code, so it resolves through the SAME root workspace link as the worker; `dashboard/` is its own separate npm package — DX-2963, the first real consumer there, adds an ordinary `dashboard/package.json` dependency, resolved by Vite/Vitest/`vue-tsc` through plain node_modules resolution, no alias needed) | No `@backend`-style alias is needed for an npm dependency the way one is needed for `dashboard/`'s reach into root `src/` — that alias exists because `dashboard/` is a SEPARATE package with no other way to reach root source; a real npm dependency resolves through ordinary node_modules lookup in every one of Vite's two configs, Vitest, `vue-tsc`, and the `dashboard-builder` Dockerfile stage (which already runs `cd dashboard && npm ci` AFTER the root repo — including `packages/`— is copied in, so the dependency is resolvable with zero Dockerfile change). `dashboard/` is FROZEN (`.claude/rules/ui-deprecation.md`) — this card adds no dependency there since nothing consumes it yet; DX-2963 adds the one line when it wires the real counter into `DispatchDetail.vue`/`DispatchList.vue`. |
+
+## Release order (DX-2962 AC3)
+
+1. Publish this package (`make publish-danx-session-telemetry`).
+2. Publish `danx-dashboard-mcp` (only once it depends on this package — DX-2954).
+3. Deploy the danxbot backend.
+4. Move the plugin's bridge-version pin.
+
+Publishing comes before deploying because the publish-drift gate
+(`src/dispatch/publish-drift-gate.ts`) refuses a finalize whose bumped
+`packages/*/package.json` version is not yet live on npm.
+
+## Boot check
+
+`npm run verify:boot` (wired into `make publish-danx-session-telemetry`,
+mirroring `packages/danx-dashboard-mcp/scripts/verify-boot.sh`) packs the
+freshly-built package with `npm pack`, installs the tarball into a clean
+temp directory (the way an `npm install` consumer actually would — not a
+relative `require` back into this checkout), and imports both the main
+entry and the `./browser` subpath, calling one exported function from each.
+A broken `exports` map, a missing `dist/` file, or an accidental `node:`
+leak into `browser.ts` fails the publish before anything reaches npm.

package/dist/browser.d.ts

@@ -0,0 +1,22 @@
+/**
+ * DX-2962 — browser-safe subpath (`@thehammer/danx-session-telemetry/browser`).
+ *
+ * This file MUST NEVER import a `node:` builtin, directly or transitively —
+ * enforced by `src/__tests__/no-node-imports.test.ts`, which greps every
+ * file this module reaches. `session-log-watcher.ts` (the main entry's
+ * collector) imports `node:fs`/`node:fs/promises`/`node:os`/`node:path`, so
+ * it — and `internal-logger.ts` and `tool-summary.ts`, which it alone pulls
+ * in — are deliberately NOT re-exported here.
+ *
+ * Only the two type-only exports are browser-safe today: `AgentLogEntry` /
+ * `AgentLineage` carry no runtime code at all, so any consumer that needs
+ * to describe a transcript entry's SHAPE (the dashboard server, the
+ * dashboard SPA, a future browser-side usage display) can depend on this
+ * subpath with zero risk of pulling in a Node builtin.
+ *
+ * DX-2963 adds the first real runtime export here: the one usage counter
+ * and the pricing function, both pure arithmetic with no I/O. This card
+ * (DX-2962) only creates the subpath and its no-`node:`-imports guarantee.
+ */
+export type { AgentLogEntry, AgentLineage } from "./types.js";
+export { truncStr } from "./tool-summary.js";

package/dist/browser.js

@@ -0,0 +1,3 @@
+// `truncStr` is pure string arithmetic (no `node:` imports, no I/O) — safe
+// to carry on the browser subpath alongside the two types above.
+export { truncStr } from "./tool-summary.js";

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * DX-2962 — `@thehammer/danx-session-telemetry` main entry point.
+ *
+ * The shared Claude Code transcript collector: incremental tailing of the
+ * main and sub-agent JSONL transcripts, with no whole-transcript buffer
+ * (small per-reply bookkeeping only, kept in memory for the life of the
+ * process — see `session-log-watcher.ts`'s header). Consumed by the
+ * danxbot worker (Node, workspace-linked — see the README) and, from
+ * DX-2954, the `danx-dashboard-mcp` desktop bridge (Node, npm-installed at
+ * a pinned exact version).
+ *
+ * A browser-safe subset with NO `node:` imports lives at the `./browser`
+ * subpath (see `browser.ts`) for consumers that cannot import Node builtins
+ * — the dashboard server, the dashboard SPA, and any future browser-side
+ * usage display.
+ */
+export { SessionLogWatcher, DISPATCH_TAG_PREFIX, encodeClaudeProjectsCwd, deriveSessionDir, sessionUuidExistsInCleanRoom, findNewestJsonlFile, findSessionFileByDispatchId, convertJsonlEntry, } from "./session-log-watcher.js";
+export type { EntryConsumer, SessionLogWatcherOptions, } from "./session-log-watcher.js";
+export type { AgentLogEntry, AgentLineage } from "./types.js";
+export { truncStr, summarizeToolInput, buildAssistantSummary, buildToolResultSummary, } from "./tool-summary.js";

package/dist/index.js

@@ -0,0 +1,23 @@
+/**
+ * DX-2962 — `@thehammer/danx-session-telemetry` main entry point.
+ *
+ * The shared Claude Code transcript collector: incremental tailing of the
+ * main and sub-agent JSONL transcripts, with no whole-transcript buffer
+ * (small per-reply bookkeeping only, kept in memory for the life of the
+ * process — see `session-log-watcher.ts`'s header). Consumed by the
+ * danxbot worker (Node, workspace-linked — see the README) and, from
+ * DX-2954, the `danx-dashboard-mcp` desktop bridge (Node, npm-installed at
+ * a pinned exact version).
+ *
+ * A browser-safe subset with NO `node:` imports lives at the `./browser`
+ * subpath (see `browser.ts`) for consumers that cannot import Node builtins
+ * — the dashboard server, the dashboard SPA, and any future browser-side
+ * usage display.
+ */
+export { SessionLogWatcher, DISPATCH_TAG_PREFIX, encodeClaudeProjectsCwd, deriveSessionDir, sessionUuidExistsInCleanRoom, findNewestJsonlFile, findSessionFileByDispatchId, convertJsonlEntry, } from "./session-log-watcher.js";
+// `truncStr` is a generic, dependency-free string helper that moved here
+// alongside the rest of `tool-summary.ts` (it has no other home now that
+// file is gone from root) — re-exported for danxbot root consumers that
+// truncate a string for display but have nothing else to do with the
+// transcript collector, e.g. `src/dashboard/dispatch-scout.ts`.
+export { truncStr, summarizeToolInput, buildAssistantSummary, buildToolResultSummary, } from "./tool-summary.js";

package/dist/internal-logger.d.ts

@@ -0,0 +1,16 @@
+/**
+ * DX-2962: minimal package-local logging shim. The collector previously
+ * imported danxbot root's `src/logger.ts` (`createLogger`), but that file
+ * is root-repo-only and this package must never reach back into the root
+ * repo (see the package README "Isolation"). `createLogger`'s own
+ * consumers span ~300+ unrelated root files, so it is not something this
+ * extraction "moves" — only the three log levels the collector actually
+ * calls (`info`/`warn`/`error`) are reproduced here, deliberately smaller
+ * than the root abstraction it replaces for this package's own use.
+ */
+export interface Logger {
+    info(message: string): void;
+    warn(message: string, error?: unknown): void;
+    error(message: string, error?: unknown): void;
+}
+export declare function createLogger(component: string): Logger;

package/dist/internal-logger.js

@@ -0,0 +1,24 @@
+function emit(level, component, message, error) {
+    const entry = {
+        timestamp: new Date().toISOString(),
+        level,
+        component,
+        message,
+    };
+    if (error instanceof Error) {
+        entry.error = error.message;
+        entry.stack = error.stack;
+    }
+    else if (error !== undefined) {
+        entry.error = String(error);
+    }
+    const writer = level === "info" ? console.log : console.error;
+    writer(JSON.stringify(entry));
+}
+export function createLogger(component) {
+    return {
+        info: (message) => emit("info", component, message),
+        warn: (message, error) => emit("warn", component, message, error),
+        error: (message, error) => emit("error", component, message, error),
+    };
+}

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

@@ -0,0 +1,310 @@
+/**
+ * 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
+ * `danx-dashboard-mcp` desktop bridge (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}
+ *
+ * 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:";
+export type EntryConsumer = (entry: AgentLogEntry) => void;
+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;
+    /**
+     * Skip every byte on disk at attach time and tail strictly forward from
+     * EOF. Set whenever the bytes already on disk belong to a PRIOR dispatch's
+     * accounting, so replaying them would double-count that dispatch's usage /
+     * tool calls against this one:
+     *   - the Phase 2c (DX-209) reattach pass — a prior worker incarnation
+     *     already accumulated the JSONL into the row's counters; and
+     *   - a `claude --resume <id>` resume (DX-2583) — claude appends this
+     *     dispatch's turns to the SAME session JSONL the prior dispatch(es)
+     *     already filled, so tailing from byte 0 re-sums the whole session's
+     *     history onto a fresh row (`attach-monitoring-stack.ts` sets this via
+     *     `seedFromEof` when `resumeSessionId` is present).
+     * Default `false` — a genuinely fresh spawn writes a brand-new file whose
+     * EOF is 0, so it ingests its own full file from the start.
+     */
+    fromEof?: boolean;
+}
+/**
+ * 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 for every host-mode dispatch. The
+ * separator-encoding regression tests below pin this.
+ *
+ * Host mode (claude 2.1.104+, GitHub #51488 — symlinks under
+ * `~/.claude/projects/` are no longer followed) lets claude write its
+ * transcript to this exact realpath-encoded dir as a REAL directory; the
+ * watcher reads the same path, so they converge with no symlink. Docker
+ * binds `<repo>/claude-projects/` at `/home/danxbot/.claude/projects/` and
+ * relies on the same encoding for the bound subdir name. Keep the encoding
+ * logic centralized here so both runtimes stay in lockstep.
+ */
+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 ≤ 2×`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;
+export declare class SessionLogWatcher {
+    private consumers;
+    private pollTimer;
+    private parentTail;
+    private subagentsDir;
+    private subagentTails;
+    private parentSessionId;
+    private sessionDir;
+    private sessionId;
+    private dispatchId;
+    private pollIntervalMs;
+    private fromEof;
+    private running;
+    private polling;
+    private initSynthesized;
+    constructor(options: SessionLogWatcherOptions);
+    /** Register a consumer callback that receives each new AgentLogEntry. */
+    onEntry(consumer: EntryConsumer): void;
+    /** Returns the discovered parent session file path, or null if not yet found. */
+    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
+     * `danxbot_complete` 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
+     * `danxbot_complete`) 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>;
+    /**
+     * 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.
+     *
+     * When `this.fromEof` is set (Phase 2c reattach OR a DX-2583 resume — see
+     * the option's doc), seed `byteOffset` to the file's current size so the
+     * next poll reads strictly forward — historical entries are NOT re-emitted.
+     * A fresh `stat` failure (race
+     * with a delete that happens between discover and adopt) falls back to
+     * 0 so the watcher tails from the start; that is preferable to throwing
+     * during boot. `fromEof` does NOT skip sub-agent files: any sub-agent
+     * file claude writes AFTER reattach is genuinely new and should be
+     * tailed normally.
+     */
+    private setParentFile;
+    /**
+     * 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.
+     */
+    private refreshLineage;
+    /**
+     * Read agentType from the `<subagentId>.meta.json` sidecar. 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.
+     */
+    private readAgentType;
+    /** 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;
+    /**
+     * 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;
+}