@playola-radio/slipstream 0.1.0

package/dist/transcript/codex.js

@@ -0,0 +1,132 @@
+import { scopeFromPaths } from "./types.js";
+export function initialCodexState() {
+    return { pending: new Map() };
+}
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function parseMs(record) {
+    const ts = record.timestamp;
+    if (typeof ts !== 'string')
+        return undefined;
+    const ms = Date.parse(ts);
+    return Number.isNaN(ms) ? undefined : ms;
+}
+const PATCH_HEADER = /^\*\*\* (?:Add File|Update File|Delete File|Move to): (.+)$/;
+/** Extract every file path an apply_patch envelope names, in order. */
+function applyPatchPaths(patch) {
+    const paths = [];
+    for (const line of patch.split('\n')) {
+        const m = PATCH_HEADER.exec(line.trimEnd());
+        if (m)
+            paths.push(m[1].trim());
+    }
+    return paths;
+}
+function makeEvidence(ctx, recordId, toolName, scope, atMs, basis) {
+    return {
+        evidence_key: {
+            harness: ctx.harness,
+            harness_session_id: ctx.harnessSessionId,
+            record_id: recordId,
+        },
+        adapter_version: ctx.adapterVersion,
+        tool_name: toolName,
+        timestamp: { at_ms: atMs, basis },
+        file_scope: scope,
+    };
+}
+/** The scope a Codex call declares, or `skip` when it is entirely out of root. */
+function scopeForCall(payloadType, name, payload, ctx) {
+    if (payloadType === 'custom_tool_call' && name === 'apply_patch') {
+        const input = payload.input;
+        if (typeof input !== 'string') {
+            return {
+                scope: { kind: 'unknown', reason: 'apply_patch input was not text' },
+                diagnostics: [{ kind: 'malformed', detail: 'apply_patch without a text patch' }],
+            };
+        }
+        const paths = applyPatchPaths(input);
+        if (paths.length === 0) {
+            return {
+                scope: { kind: 'unknown', reason: 'apply_patch named no files' },
+                diagnostics: [{ kind: 'malformed', detail: 'apply_patch envelope named no files' }],
+            };
+        }
+        const scope = scopeFromPaths(paths, ctx);
+        if (!scope)
+            return 'skip';
+        return { scope, diagnostics: [] };
+    }
+    // A shell command or any unrecognized custom tool: a possible writer we cannot
+    // scope from its structured fields.
+    return {
+        scope: { kind: 'unknown', reason: `unmapped ${payloadType} ${name}` },
+        diagnostics: [],
+    };
+}
+function stepCall(state, record, payload, ctx) {
+    const callId = payload.call_id;
+    const name = payload.name;
+    const payloadType = payload.type;
+    // A missing/empty call_id is not a stable identity we can key: unsupported, never
+    // a fabricated or empty key that would collide across unrelated calls.
+    if (typeof callId !== 'string' || callId.length === 0) {
+        return { state, evidence: [], diagnostics: [{ kind: 'unsupported', detail: 'tool call without a stable call_id' }] };
+    }
+    if (typeof name !== 'string' || name.length === 0 || typeof payloadType !== 'string') {
+        return { state, evidence: [], diagnostics: [{ kind: 'malformed', detail: `call ${callId} without a name/type` }] };
+    }
+    const resolved = scopeForCall(payloadType, name, payload, ctx);
+    if (resolved === 'skip')
+        return { state, evidence: [], diagnostics: [] };
+    const atMs = parseMs(record);
+    if (atMs === undefined) {
+        return { state, evidence: [], diagnostics: [{ kind: 'malformed', detail: `call ${callId} has no usable timestamp` }] };
+    }
+    state.pending.set(callId, { toolName: name, scope: resolved.scope });
+    return {
+        state,
+        evidence: [makeEvidence(ctx, callId, name, resolved.scope, atMs, 'tool-start')],
+        diagnostics: resolved.diagnostics,
+    };
+}
+function stepOutput(state, record, payload, ctx) {
+    const callId = payload.call_id;
+    if (typeof callId !== 'string')
+        return { state, evidence: [], diagnostics: [] };
+    const memo = state.pending.get(callId);
+    if (!memo)
+        return { state, evidence: [], diagnostics: [] };
+    const atMs = parseMs(record);
+    // A matched output with an unusable timestamp is malformed, not a clean read:
+    // disclose it (as the call side does) rather than silently drop the endpoint.
+    if (atMs === undefined) {
+        return { state, evidence: [], diagnostics: [{ kind: 'malformed', detail: `call ${callId} output has no usable timestamp` }] };
+    }
+    return {
+        state,
+        evidence: [makeEvidence(ctx, callId, memo.toolName, memo.scope, atMs, 'tool-end')],
+        diagnostics: [],
+    };
+}
+/** Fold one parsed Codex rollout record into the running adapter state. */
+export function codexStep(state, record, ctx) {
+    if (!isObject(record)) {
+        return { state, evidence: [], diagnostics: [{ kind: 'malformed', detail: 'record is not an object' }] };
+    }
+    if (record.type !== 'response_item')
+        return { state, evidence: [], diagnostics: [] };
+    const payload = record.payload;
+    if (!isObject(payload) || typeof payload.type !== 'string') {
+        // A response_item always carries a typed payload; a null/absent/untyped one is
+        // a malformed envelope, disclosed so it stays distinct from a clean read.
+        return { state, evidence: [], diagnostics: [{ kind: 'malformed', detail: 'response_item without a typed payload' }] };
+    }
+    const t = payload.type;
+    if (t === 'function_call' || t === 'custom_tool_call')
+        return stepCall(state, record, payload, ctx);
+    if (t === 'function_call_output' || t === 'custom_tool_call_output')
+        return stepOutput(state, record, payload, ctx);
+    return { state, evidence: [], diagnostics: [] };
+}

package/dist/transcript/discovery.js

@@ -0,0 +1,365 @@
+/**
+ * Transcript discovery: find every transcript that may hold evidence for one
+ * captured worktree, honestly.
+ *
+ * Two harness layouts:
+ * - Claude Code stores `<home>/projects/<slug>/<sessionId>.jsonl`, where the slug
+ *   is the worktree path with '/'→'-'. The slug directory IS the worktree binding,
+ *   so membership is the cwd filter; each file name is the harness session id.
+ * - Codex stores date-partitioned rollouts NOT organized by worktree, so we scan
+ *   and filter by the canonicalized `session_meta.cwd` being inside the root. mtime
+ *   is never an eligibility boundary (an old session can resume). A bounded scan
+ *   discloses `discovery-limited` rather than pretend the search was exhaustive.
+ *
+ * "Different harness sessions in the same worktree" are all legitimate candidates
+ * (Stage 3: two agents in one worktree are both captured); each keeps its own
+ * native session id, so their invocation identities never collide.
+ */
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+export const CLAUDE_ADAPTER_VERSION = 'claude-code/1';
+export const CODEX_ADAPTER_VERSION = 'codex/1';
+/** Claude's on-disk slug for a worktree: the absolute path with '/'→'-'. */
+export function claudeSlug(root) {
+    return root.replace(/\//g, '-');
+}
+function baseName(path) {
+    const i = path.lastIndexOf('/');
+    return i >= 0 ? path.slice(i + 1) : path;
+}
+/** True when `child` is `root` itself or nested inside it (same canonical space). */
+export function isWithinRoot(root, child) {
+    if (child === root)
+        return true;
+    const rel = relative(root, child);
+    return rel !== '' && rel !== '..' && !rel.startsWith(`..${sep}`) && rel[0] !== '/';
+}
+/** A generous bound on symlink hops while degrading a broken cwd, defeating a
+ * symlink cycle. Beyond it, a cwd is too pathological to place cheaply, so we
+ * disclose it rather than silently drop what might be an in-root candidate. */
+const MAX_UNRESOLVED_HOPS = 64;
+/** Path segments, dropping empty and `.` parts. */
+function segmentsOf(path) {
+    return path.split('/').filter((s) => s !== '' && s !== '.');
+}
+/**
+ * True when an UNRESOLVABLE cwd could still sit inside the capture root, so it is
+ * an in-root candidate we failed to read rather than a genuine non-candidate.
+ *
+ * A textual check is unreliable both ways: the raw string may be in the root's
+ * alias namespace (cwd `/tmp/proj/gone` for canonical root `/private/tmp/proj`)
+ * yet be in-root, or textually in-root yet escape through an internal symlink
+ * (`/work/proj/link/gone` where `link` -> `/other/project`). So we resolve the
+ * cwd the way `realpath` would — but `realpath` on the whole string fails because
+ * of the deleted tail. Instead we walk it component by component and let the
+ * KERNEL canonicalize every component that still exists: `realpath` on a living
+ * component resolves symlinks, case-insensitive names, and unicode normalization
+ * exactly, rather than reimplementing those rules. We keep a canonical prefix
+ * `base`: for each component, `realpath(base/seg)` supplies its true form; only
+ * when that component does NOT resolve do we fall back to `probe`. A truly
+ * nonexistent component contains no symlinks below it, so a `..` after it is
+ * resolved lexically (exact); a `..` can also pop back above a gap into living
+ * space, which the continued walk re-canonicalizes. A component that exists only
+ * as a broken symlink is followed by splicing its literal target, so any `..`
+ * after it is evaluated against the target, not the link's own parent.
+ *
+ * A cwd that places outside the root is a different worktree's session, skipped
+ * silently so unrelated dead sessions never degrade this root's coverage.
+ * Undecidable cases (an uninspectable component, a symlink cycle past the hop
+ * cap) fail toward disclosure: never claim non-membership we did not establish.
+ */
+async function unresolvedCwdMayBeInRoot(io, root, cwd) {
+    const queue = segmentsOf(cwd);
+    let cursor = 0;
+    let base = '/';
+    let symlinkHops = 0;
+    while (cursor < queue.length) {
+        const seg = queue[cursor];
+        cursor += 1;
+        if (seg === '..') {
+            base = dirname(base); // popping a canonical prefix is exact
+            continue;
+        }
+        const candidate = base === '/' ? `/${seg}` : `${base}/${seg}`;
+        // Let the kernel canonicalize any component that still resolves (dir, file, or
+        // a symlink whose target resolves): this handles symlinks, case-insensitive
+        // names, and unicode normalization exactly instead of reimplementing them.
+        const canonical = await io.realpath(candidate);
+        if (canonical !== undefined) {
+            base = canonical;
+            continue;
+        }
+        // The component does not fully resolve; distinguish the reasons.
+        const probe = await io.probe(candidate);
+        if (probe.kind === 'absent') {
+            // Confirmed nonexistent (ENOENT/ENOTDIR): no symlinks live below it, so
+            // advancing the prefix lexically is exact. A later `..` may still pop back
+            // above this gap into living space, which the continued walk re-resolves.
+            base = candidate;
+            continue;
+        }
+        if (probe.kind === 'symlink') {
+            // A symlink whose target does not resolve (dangling, or reaching through
+            // deleted space). Follow its literal target so a `..` after it is evaluated
+            // against the target and the target's living parts get canonicalized above.
+            symlinkHops += 1;
+            if (symlinkHops > MAX_UNRESOLVED_HOPS)
+                return true; // cycle: disclose
+            if (isAbsolute(probe.target))
+                base = '/';
+            queue.splice(cursor, 0, ...segmentsOf(probe.target));
+            continue;
+        }
+        return true; // uninspectable (e.g. permissions): cannot rule out membership
+    }
+    return isWithinRoot(root, base);
+}
+/**
+ * Classify a recorded cwd against the capture root, the single membership rule
+ * shared by both harnesses. The recorded cwd — never the on-disk location — is
+ * what establishes which worktree a transcript belongs to, so a slug collision
+ * (Claude) or a shared global sessions dir (Codex) cannot bind another worktree's
+ * session to this root.
+ */
+async function classifyCwd(io, root, cwd) {
+    const canonicalCwd = await io.realpath(cwd);
+    if (canonicalCwd === undefined) {
+        return (await unresolvedCwdMayBeInRoot(io, root, cwd))
+            ? { kind: 'unresolved-in-root' }
+            : { kind: 'out-of-root' };
+    }
+    if (!isWithinRoot(root, canonicalCwd))
+        return { kind: 'out-of-root' };
+    // If the recorded cwd is a non-canonical alias reached through a symlinked
+    // ANCESTOR, its root form relativizes a record's absolute paths the same way
+    // capture's canonical root does. Only trust an alias root that canonicalizes
+    // back to the capture root: a leaf symlink (e.g. /links/alias -> root/pkg)
+    // yields a bogus ancestor (/links) that would mis-scope or invent evidence.
+    let rootAliases;
+    if (cwd !== canonicalCwd) {
+        const aliasRoot = resolve(cwd, relative(canonicalCwd, root));
+        if ((await io.realpath(aliasRoot)) === root)
+            rootAliases = [aliasRoot];
+    }
+    return { kind: 'in-root', cwd: canonicalCwd, ...(rootAliases !== undefined ? { rootAliases } : {}) };
+}
+function readLineCwd(line) {
+    let obj;
+    try {
+        obj = JSON.parse(line);
+    }
+    catch {
+        return { kind: 'malformed' };
+    }
+    // A valid JSON scalar or `null` parses cleanly but is not a cwd-bearing record;
+    // it carries no cwd, it is not malformed. Guard before property access so a bare
+    // `null` line cannot throw past the catch and abort the whole discovery tick.
+    if (typeof obj !== 'object' || obj === null)
+        return { kind: 'no-cwd' };
+    const cwd = obj.cwd;
+    return typeof cwd === 'string' && cwd.length > 0 ? { kind: 'cwd', cwd } : { kind: 'no-cwd' };
+}
+/**
+ * Search a Claude transcript for the working directory it declares. A session's
+ * first records are a cwd-less preamble (ai-title, queue-operation, attachments),
+ * so the first line rarely carries the cwd; scan a bounded head for the first
+ * record that does.
+ *
+ * `none` means the searched head was read cleanly and genuinely holds no cwd yet —
+ * an empty or still-preamble transcript — which the caller withholds (pending) and
+ * re-checks once more is written. `unconfirmed` means a cwd could exist but the
+ * head could NOT be searched through to rule it out — the scan hit its budget
+ * (truncated), a line was skipped (oversized/undecodable) or malformed, or the head
+ * was unreadable — so membership cannot be trusted; the caller discloses it rather
+ * than treat it as a clean preamble or slug-trust a candidate that could belong to
+ * a slug-colliding sibling worktree.
+ */
+async function resolveClaudeCwd(io, path, firstLine, firstId) {
+    const first = readLineCwd(firstLine);
+    // The cwd came off the first line: pin to that read's generation (`firstId`).
+    if (first.kind === 'cwd')
+        return { kind: 'found', cwd: first.cwd, id: firstId };
+    let sawMalformed = first.kind === 'malformed';
+    const head = await io.readHeadLines(path);
+    // The first line already read, so the file is non-empty; an unreadable or
+    // raced-to-empty head here leaves membership unconfirmable.
+    if (!head.ok)
+        return { kind: 'unconfirmed', reason: 'inaccessible', detail: 'the head could not be read' };
+    for (const line of head.lines) {
+        const parsed = readLineCwd(line);
+        // The cwd came off the head scan: pin to the head read's generation, the exact
+        // bytes this cwd was decoded from (not the earlier first-line read, which may
+        // predate a replacement the head then read through).
+        if (parsed.kind === 'cwd')
+            return { kind: 'found', cwd: parsed.cwd, id: head.id };
+        if (parsed.kind === 'malformed')
+            sawMalformed = true;
+    }
+    // No cwd in the searched head. Only a head that was read through cleanly (every
+    // line examined, none skipped, none malformed, nothing beyond the window) is a
+    // genuine still-preamble transcript; anything else is a gap we must disclose so a
+    // cwd we could not read is never mistaken for a cwd that is not there yet.
+    if (head.truncated) {
+        return { kind: 'unconfirmed', reason: 'inaccessible', detail: 'a cwd may lie beyond the truncated head' };
+    }
+    if (head.skipped) {
+        return { kind: 'unconfirmed', reason: 'inaccessible', detail: 'an oversized or undecodable head line may carry the cwd' };
+    }
+    if (sawMalformed) {
+        return { kind: 'unconfirmed', reason: 'malformed', detail: 'a malformed head line may carry the cwd' };
+    }
+    return { kind: 'none' };
+}
+export async function discoverClaude(io, home, root) {
+    const dir = `${home}/projects/${claudeSlug(root)}`;
+    const listed = await io.listDir(dir);
+    if (!listed.ok) {
+        return { bindings: [], issues: [{ kind: listed.reason, detail: `claude project dir ${dir}` }] };
+    }
+    const bindings = [];
+    const issues = [];
+    for (const path of listed.paths) {
+        const sessionId = baseName(path).slice(0, -'.jsonl'.length);
+        // The slug directory alone cannot establish membership: two distinct roots can
+        // collide onto one slug (e.g. /work/a-b and /work/a/b). So a transcript is bound
+        // ONLY once its recorded cwd has been read and confirmed in-root — it is never
+        // slug-trusted. Until confirmation:
+        //   - an empty or still-preamble transcript is withheld with no issue (pending
+        //     coverage); it is re-checked next tick once more is written, and no record
+        //     is ingested under an unconfirmed binding (so a colliding sibling's records
+        //     landing before confirmation can never be credited to this root);
+        //   - a transcript whose membership cannot be confirmed (unreadable/oversized or
+        //     truncated head, or an in-root cwd that will not resolve) is disclosed.
+        const head = await io.readFirstLine(path);
+        if (!head.ok) {
+            if (head.reason === 'empty')
+                continue; // not yet written: withhold, stays pending
+            // A first line that exists but could not be read (malformed, e.g. invalid
+            // UTF-8 or an unbounded line; or inaccessible): disclose the gap.
+            issues.push({ kind: head.reason, detail: `claude transcript ${path}` });
+            continue;
+        }
+        const resolution = await resolveClaudeCwd(io, path, head.line, head.id);
+        if (resolution.kind === 'none')
+            continue; // a cwd-less preamble so far: withhold, pending
+        if (resolution.kind === 'unconfirmed') {
+            issues.push({
+                kind: resolution.reason,
+                detail: `claude transcript ${path} membership unconfirmed: ${resolution.detail}`,
+            });
+            continue;
+        }
+        const cls = await classifyCwd(io, root, resolution.cwd);
+        if (cls.kind === 'out-of-root')
+            continue; // a slug-colliding other worktree
+        if (cls.kind === 'unresolved-in-root') {
+            issues.push({
+                kind: 'inaccessible',
+                detail: `claude transcript ${path} cwd ${resolution.cwd} could not be resolved`,
+            });
+            continue;
+        }
+        bindings.push({
+            path,
+            ctx: {
+                harness: 'claude-code',
+                harnessSessionId: sessionId,
+                root,
+                cwd: cls.cwd,
+                adapterVersion: CLAUDE_ADAPTER_VERSION,
+                ...(cls.rootAliases !== undefined ? { rootAliases: cls.rootAliases } : {}),
+            },
+            generation: resolution.id,
+        });
+    }
+    return { bindings, issues };
+}
+function parseSessionMeta(line) {
+    try {
+        const obj = JSON.parse(line);
+        if (obj.type !== 'session_meta')
+            return undefined;
+        const payload = obj.payload;
+        if (typeof payload !== 'object' || payload === null)
+            return undefined;
+        const p = payload;
+        // An empty id or cwd is not a usable session identity/scope: keying evidence
+        // under "" would collapse unrelated sessions, so treat it as malformed (undefined).
+        if (typeof p.id !== 'string' || p.id.length === 0 || typeof p.cwd !== 'string' || p.cwd.length === 0) {
+            return undefined;
+        }
+        return { id: p.id, cwd: p.cwd };
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function discoverCodex(io, home, root, limit) {
+    const dir = `${home}/sessions`;
+    const listed = await io.listTreeJsonl(dir, limit);
+    if ('ok' in listed && listed.ok === false) {
+        return { bindings: [], issues: [{ kind: listed.reason, detail: `codex sessions dir ${dir}` }] };
+    }
+    const { paths, truncated, incomplete } = listed;
+    const issues = [];
+    if (truncated) {
+        issues.push({
+            kind: 'discovery-limited',
+            detail: `codex session scan hit the ${limit}-file cap; some transcripts may be unread`,
+        });
+    }
+    if (incomplete) {
+        issues.push({
+            kind: 'inaccessible',
+            detail: `some codex session subdirectories under ${dir} were unreadable`,
+        });
+    }
+    const bindings = [];
+    for (const path of paths) {
+        // A file we cannot read or parse is a candidate we cannot rule out, so it is
+        // disclosed as an issue — never silently skipped (which would let a readable
+        // sibling conceal it and report coverage as clean).
+        const head = await io.readFirstLine(path);
+        if (!head.ok) {
+            issues.push({
+                kind: head.reason === 'inaccessible' ? 'inaccessible' : 'malformed',
+                detail: `codex rollout ${path}`,
+            });
+            continue;
+        }
+        const meta = parseSessionMeta(head.line);
+        if (!meta) {
+            issues.push({ kind: 'malformed', detail: `codex rollout ${path} has no session_meta` });
+            continue;
+        }
+        const cls = await classifyCwd(io, root, meta.cwd);
+        if (cls.kind === 'out-of-root')
+            continue;
+        if (cls.kind === 'unresolved-in-root') {
+            // An in-root candidate we failed to read: disclose the gap rather than let a
+            // readable sibling report clean coverage. A cwd whose nearest living ancestor
+            // is outside the root is a different worktree's session, skipped silently.
+            issues.push({ kind: 'inaccessible', detail: `codex rollout ${path} cwd ${meta.cwd} could not be resolved` });
+            continue;
+        }
+        bindings.push({
+            path,
+            ctx: {
+                harness: 'codex',
+                harnessSessionId: meta.id,
+                root,
+                cwd: cls.cwd,
+                adapterVersion: CODEX_ADAPTER_VERSION,
+                ...(cls.rootAliases !== undefined ? { rootAliases: cls.rootAliases } : {}),
+            },
+            // The Codex ctx derives entirely from line 1 (session_meta), so the generation
+            // is the first-line read that produced it.
+            generation: head.id,
+        });
+    }
+    return { bindings, issues };
+}
+export async function discover(harness, io, home, root, codexScanLimit) {
+    return harness === 'claude-code'
+        ? discoverClaude(io, home, root)
+        : discoverCodex(io, home, root, codexScanLimit);
+}

package/dist/transcript/file-reader.js

@@ -0,0 +1,128 @@
+const READ_CHUNK_BYTES = 1 << 20; // 1 MiB
+// A fatal decoder so an invalid-UTF-8 line is rejected rather than silently decoded
+// to replacement characters (which could fabricate a path). Reused across polls;
+// safe because each call is a one-shot decode (no streaming state).
+const LINE_DECODER = new TextDecoder('utf8', { fatal: true });
+export function createTranscriptFileReader(opts) {
+    const { path, io, sink, stepper, generation } = opts;
+    const readChunkBytes = opts.readChunkBytes ?? READ_CHUNK_BYTES;
+    let offset = 0;
+    let lastSize = 0;
+    let issues = [];
+    const rereadFromZero = () => {
+        offset = 0;
+        issues = [];
+        stepper.reset();
+    };
+    // Ingest every record for one line; false means a retryable stop (advance held).
+    const ingestLine = async (records) => {
+        for (const record of records) {
+            let outcome;
+            try {
+                outcome = await sink.ingest(record);
+            }
+            catch {
+                return false; // append failure — retry the whole line next poll
+            }
+            if (outcome.status === 'rejected')
+                return false;
+        }
+        return true;
+    };
+    // The (dev, ino) of the bytes `rd` supplied is not the pinned generation: the file
+    // at this path was replaced (an atomic rename-into-place) with content discovery has
+    // NOT re-confirmed. Because the id and the bytes came from the SAME handle, this
+    // catches a replace at any instant up to the read — there is no stat-then-open window
+    // through which a replacement's bytes could be read while a prior generation's id was
+    // validated. Ingesting them would credit the new file's records to the prior
+    // generation's session and scope, so refuse: report `unconfirmed`, offset untouched.
+    // The next discovery tick re-derives the binding for the new generation and, if it
+    // too is a confirmed in-root member, recreates this reader against it.
+    const isPinned = (rd) => rd.id.dev === generation.dev && rd.id.ino === generation.ino;
+    // Returns true if backpressure held the offset at a line (retry next poll).
+    const ingestBuffer = async (buf) => {
+        // Split on newline BYTES, not decoded characters: invalid UTF-8 decodes to
+        // a 3-byte replacement char, so measuring a decoded line's length would
+        // advance the cursor past bytes that were never there and skip live records.
+        // Bytes after the last newline are an incomplete line, left for a later poll.
+        let lineStart = 0;
+        for (let i = 0; i < buf.length; i++) {
+            if (buf[i] !== 0x0a)
+                continue;
+            const lineBytes = i - lineStart + 1; // through the newline
+            const slice = buf.subarray(lineStart, i);
+            lineStart = i + 1;
+            let decoded;
+            try {
+                decoded = LINE_DECODER.decode(slice);
+            }
+            catch {
+                // Invalid UTF-8: decoding it lossily would coin replacement characters and
+                // could fabricate a path, so disclose it malformed and advance past it.
+                issues.push({ kind: 'malformed', detail: 'transcript line was not valid UTF-8' });
+                offset += lineBytes;
+                continue;
+            }
+            const trimmed = decoded.trim();
+            if (trimmed.length > 0) {
+                let record;
+                try {
+                    record = JSON.parse(trimmed);
+                }
+                catch {
+                    issues.push({ kind: 'malformed', detail: 'transcript line was not valid JSON' });
+                    offset += lineBytes;
+                    continue;
+                }
+                const out = stepper.step(record);
+                if (out.diagnostics.length > 0)
+                    issues.push(...out.diagnostics);
+                if (out.evidence.length > 0) {
+                    const ok = await ingestLine(out.evidence);
+                    if (!ok)
+                        return true; // backpressure: hold offset at this line
+                }
+            }
+            offset += lineBytes;
+        }
+        return false;
+    };
+    const poll = async () => {
+        let backpressured = false;
+        let readSize = readChunkBytes;
+        for (;;) {
+            const rd = await io.readFrom(path, offset, readSize);
+            if (!rd.ok) {
+                return { state: rd.reason === 'missing' ? 'missing' : 'inaccessible', issues, backpressured };
+            }
+            if (!isPinned(rd)) {
+                return { state: 'unconfirmed', issues, backpressured: false };
+            }
+            if (rd.size < lastSize) {
+                rereadFromZero();
+                lastSize = 0;
+                readSize = readChunkBytes;
+                continue;
+            }
+            lastSize = rd.size;
+            const chunkStart = offset;
+            if (await ingestBuffer(rd.bytes)) {
+                backpressured = true;
+                break;
+            }
+            if (offset >= rd.size)
+                break; // drained to EOF
+            if (offset > chunkStart) {
+                readSize = readChunkBytes;
+                continue;
+            }
+            // No complete line consumed this read (offset === chunkStart).
+            if (chunkStart + rd.bytes.length >= rd.size)
+                break; // unterminated tail: hold
+            readSize = rd.size - offset; // one line exceeds the window: read it whole next
+        }
+        const state = issues.length > 0 ? 'degraded' : 'readable';
+        return { state, issues, backpressured };
+    };
+    return { poll };
+}