toolroll 0.9.73 → 0.9.74

package/dist/live-children.js

@@ -0,0 +1,318 @@
+/**
+ * Subagents' records (docs/plans/agents-view.md §2.3): what each subagent a Claude run delegates to said and did, in
+ * `live/<run>.sub.jsonl`, beside — never inside — the run's own records. The run's own file, its step ids, sequence and
+ * caps are untouched: the parent recorder still drops every subagent event (stream-scope.ts).
+ *
+ * Routing is separate from open steps: a delegation (a Task/Agent call, the parent's own or a subagent's) maps its
+ * provider call id to a child stream, and the mapping outlives the call's result, so a background subagent's late
+ * first words still route. Each stream has its own recorder — its own open steps, key-block state and chunking, under
+ * the run's captured "Show commands" answer — and its ids are rewritten `c<s>s<n>`, a form the parent never uses.
+ * A close only ever reaches its own stream's steps. Bounded everywhere: 16 streams, 32 delegations, depth 2, 32 open
+ * child steps, the file's own size cap; what doesn't fit is counted, never shown. A checkpoint (each stream's parent,
+ * open steps and key state) is written when a stream opens and every 32 KiB, for a reader that starts mid-file.
+ *
+ * Display state, never evidence: the machine running the agent could alter the file.
+ */
+import { closeSync, constants, mkdirSync, openSync, writeSync } from "node:fs";
+import { LIVE_SUB_FILE_CAP, liveDir, liveSubLogPath } from "./live.js";
+import { createLiveRecorder } from "./live-records.js";
+import { primaryResultEvent, topLevelEvent } from "./stream-scope.js";
+export const CHILD_STREAMS_CAP = 16;
+export const CHILD_DELEGATIONS_CAP = 32;
+export const CHILD_OPEN_STEPS_CAP = 32;
+export const CHILD_DEPTH_CAP = 2;
+/** A checkpoint at least this often, in bytes of child records. */
+export const CHILD_CHECKPOINT_BYTES = 32 * 1024;
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+/** A provider call id: a plain, bounded string, or nothing — never a number or an array coerced into one. */
+const callId = (value) => (typeof value === "string" && value !== "" && value.length <= 200 ? value : null);
+const DELEGATES = new Set(["Task", "Agent"]);
+/** A checkpoint's display text: its first 60 characters (the line is already redacted). */
+const brief = (text) => (text.length <= 60 ? text : `${text.slice(0, 59)}…`);
+/** At most about this many bytes of one event's records reach the file; past it words and one-off steps give way to one
+ * `cut`, so a checkpoint (written between events) is never far behind any position. */
+export const CHILD_EVENT_WORDS_CAP = 64 * 1024;
+const delegationCalls = (content) => Array.isArray(content) ? content.map(object).filter((block) => block !== null && block["type"] === "tool_use" && DELEGATES.has(String(block["name"]))) : [];
+/** The child recorder: every stream event in, the subagents' records out. Hand `parentStep` to the run's own recorder
+ * (LiveRecorderOptions.onStep) so a delegation names the parent's step it really opened. Never throws. */
+export function createChildRecorder(options) {
+    const clock = options.clock ?? (() => new Date());
+    /** Provider call id → its delegation, or "ambiguous" once two callers have used the id (then nothing routes by it). */
+    const delegations = new Map();
+    const streams = [];
+    const parentNoted = new Map();
+    let dropped = 0;
+    let overWritten = false;
+    /** Register a delegation call; a repeated id (whoever repeats it) makes the id ambiguous: counted, never routed. */
+    const delegate = (id, depth, noted, via) => {
+        if (delegations.has(id)) {
+            delegations.set(id, "ambiguous");
+            dropped += 1;
+            return;
+        }
+        if (delegations.size >= CHILD_DELEGATIONS_CAP || depth > CHILD_DEPTH_CAP) {
+            dropped += 1;
+            return;
+        }
+        delegations.set(id, { depth, parent: noted?.id ?? null, ...(via === undefined ? {} : { via }), desc: noted?.target ?? null });
+    };
+    const checkpoint = (at) => ({ k: "ckpt", at, dropped, streams: streams.map(one => ({
+            s: one.s, parent: one.parent, ...(one.via === undefined ? {} : { via: one.via }), open: [...one.open], inKey: one.keys.inKey,
+            ...(one.keys.tail === undefined || one.keys.tail === "" ? {} : { tail: one.keys.tail }), ...(one.ended ? { ended: true } : {}),
+            // Display text cut short here so a checkpoint always fits its record (16 streams, 32 open steps).
+            ...(one.desc === null ? {} : { desc: brief(one.desc) }), at: one.startedAt,
+            ...(one.labels.size === 0 ? {} : { steps: [...one.labels].map(([id, label]) => ({ id, kind: label.kind, ...(label.target === undefined ? {} : { target: brief(label.target) }) })) }),
+            ...(one.endedAt === undefined ? {} : { endedAt: one.endedAt, ok: one.ok ?? null }),
+        })) });
+    /** A stream's own records: ids rewritten, open steps bounded across every stream, words bounded per event. */
+    const own = (stream, records, at) => {
+        const out = [];
+        const total = () => streams.reduce((sum, one) => sum + one.open.size, 0);
+        let bytes = 0, cut = false;
+        for (let record of records) {
+            if (record.k === "open")
+                continue;
+            // A close always lands, with its id and outcome; its output counts against the budget and goes first when over.
+            if (record.k === "done" && record.out !== undefined && bytes + Buffer.byteLength(JSON.stringify(record), "utf8") > CHILD_EVENT_WORDS_CAP) {
+                const { out: _out, ...bare } = record;
+                record = bare;
+                if (!cut)
+                    out.push({ k: "cut", at, s: stream.s });
+                cut = true;
+            }
+            bytes += Buffer.byteLength(JSON.stringify(record), "utf8");
+            // Past the event's budget, words and one-off steps give way to one `cut`; tracked steps and closes still land.
+            const over = bytes > CHILD_EVENT_WORDS_CAP;
+            const tracked = record.k === "done" || (record.k === "step" && record.once !== true && total() < CHILD_OPEN_STEPS_CAP);
+            if (over && !tracked && record.k !== "start") {
+                if (!cut)
+                    out.push({ k: "cut", at, s: stream.s });
+                cut = true;
+                continue;
+            }
+            if (record.k === "step") {
+                const id = `c${stream.s}${record.id}`;
+                if (!tracked) {
+                    out.push({ ...record, id, once: true, s: stream.s });
+                    continue;
+                }
+                stream.open.add(id);
+                stream.labels.set(id, { kind: record.kind, ...(record.target === undefined ? {} : { target: record.target }) });
+                out.push({ ...record, id, s: stream.s });
+            }
+            else if (record.k === "done") {
+                const id = `c${stream.s}${record.id}`;
+                if (!stream.open.delete(id)) {
+                    dropped += 1;
+                    continue;
+                } // never one this stream has open
+                stream.labels.delete(id);
+                out.push({ ...record, id, s: stream.s });
+            }
+            else
+                out.push({ ...record, s: stream.s });
+        }
+        return out;
+    };
+    const endStream = (stream, at, ok) => {
+        if (stream.ended)
+            return [];
+        const records = own(stream, stream.recorder.end(), at);
+        stream.ended = true;
+        stream.open.clear();
+        stream.labels.clear();
+        stream.endedAt = at;
+        stream.ok = ok;
+        return [...records, { k: "end", s: stream.s, at, ok }];
+    };
+    /** The main query ended: every subagent still speaking ends, and one that never spoke never will. */
+    const endAll = (at) => {
+        for (const entry of delegations.values())
+            if (entry !== "ambiguous" && entry.stream === undefined)
+                entry.ended = true;
+        return streams.flatMap(stream => endStream(stream, at, null));
+    };
+    const open = (into, at) => {
+        const keys = { inKey: false };
+        const noted = new Map();
+        const stream = { s: streams.length + 1, depth: into.depth, parent: into.parent, ...(into.via === undefined ? {} : { via: into.via }), desc: into.desc, startedAt: at,
+            recorder: createLiveRecorder({ ...options, keyState: keys, onStep: (call, id, target) => { if (call !== null)
+                    noted.set(call, { id, target }); } }),
+            keys, open: new Set(), ended: false, noted, labels: new Map() };
+        streams.push(stream);
+        into.stream = stream;
+        return stream;
+    };
+    return {
+        parentStep(call, id, target) {
+            if (call !== null)
+                parentNoted.set(call, { id, target });
+        },
+        observe(event) {
+            const noted = new Map(parentNoted);
+            parentNoted.clear();
+            try {
+                const at = clock().toISOString();
+                const content = event["type"] === "assistant" ? object(event["message"])?.["content"] : undefined;
+                if (topLevelEvent(event)) {
+                    // The parent's delegations, each named by the step the parent's recorder actually wrote for that call.
+                    for (const block of delegationCalls(content)) {
+                        const id = callId(block["id"]);
+                        if (id !== null)
+                            delegate(id, 1, noted.get(id));
+                    }
+                    return primaryResultEvent(event) ? endAll(at) : [];
+                }
+                const reference = callId(event["parent_tool_use_id"]);
+                const into = reference === null ? undefined : delegations.get(reference);
+                if (into === undefined || into === "ambiguous" || into.ended === true) {
+                    dropped += 1;
+                    return [];
+                } // unknown, ambiguous or over
+                let stream = into.stream;
+                const records = [];
+                if (stream === undefined) {
+                    if (streams.length >= CHILD_STREAMS_CAP) {
+                        dropped += 1;
+                        if (overWritten)
+                            return [];
+                        overWritten = true;
+                        return [{ k: "over", at }];
+                    }
+                    stream = open(into, at);
+                    records.push({ k: "child", s: stream.s, at, parent: stream.parent, ...(stream.via === undefined ? {} : { via: stream.via }), ...(into.desc === null ? {} : { desc: into.desc }) });
+                }
+                if (stream.ended) {
+                    dropped += 1;
+                    return records;
+                } // late: counted, never re-opened
+                // A delegation id seen before (here or anywhere) is refused before the subagent's recorder sees it: no step opens.
+                const blocks = Array.isArray(content) ? content : [];
+                const repeated = new Set(delegationCalls(blocks).map(block => callId(block["id"])).filter((id) => id === null ? false : delegations.has(id)));
+                let mine = { ...event, parent_tool_use_id: null };
+                if (repeated.size > 0) {
+                    for (const id of repeated) {
+                        delegations.set(id, "ambiguous");
+                        dropped += 1;
+                    }
+                    const kept = blocks.filter(part => { const block = object(part); return block === null || !(block["type"] === "tool_use" && repeated.has(String(block["id"]))); });
+                    mine = { ...mine, message: { ...object(event["message"]), content: kept } };
+                }
+                // A subagent's init starts its own redaction afresh, the half-seen marker included.
+                if (event["type"] === "system" && event["subtype"] === "init") {
+                    stream.keys.inKey = false;
+                    stream.keys.tail = "";
+                }
+                stream.noted.clear();
+                records.push(...own(stream, stream.recorder.observe(mine), at));
+                // Its own delegations nest under it, one level more, named by the steps its recorder wrote.
+                for (const block of delegationCalls(object(mine["message"])?.["content"])) {
+                    const id = callId(block["id"]);
+                    const step = id === null ? undefined : stream.noted.get(id);
+                    if (id !== null)
+                        delegate(id, stream.depth + 1, step === undefined ? undefined : { id: `c${stream.s}${step.id}`, target: step.target }, stream.s);
+                }
+                if (event["type"] === "result")
+                    records.push(...endStream(stream, at, event["is_error"] === true ? false : event["is_error"] === false ? true : null));
+                if (records.some(record => record.k === "child"))
+                    records.push(checkpoint(at));
+                return records;
+            }
+            catch {
+                return [];
+            }
+        },
+        end() {
+            try {
+                return endAll(clock().toISOString());
+            }
+            catch {
+                return [];
+            }
+        },
+        checkpoint() {
+            return checkpoint(clock().toISOString());
+        },
+    };
+}
+/**
+ * The subagents' file, opened the first time a subagent speaks (a run without one has none): created here (O_EXCL,
+ * O_NOFOLLOW, 0600, the live directory 0700), appended to, and closed with the run. It stops at LIVE_SUB_FILE_CAP
+ * with one `cap` record, reserved inside the cap. Fail-soft: no live view is ever worth a build.
+ */
+export function childLogWriter(root, runId) {
+    let fd = null;
+    let failed = false, capped = false;
+    let written = 0, sinceCheckpoint = 0;
+    const write = (line) => {
+        try {
+            writeSync(fd, line);
+            written += Buffer.byteLength(line, "utf8");
+            return true;
+        }
+        catch {
+            failed = true;
+            return false;
+        }
+    };
+    const fits = (text) => Buffer.byteLength(text, "utf8") <= 8 * 1024;
+    /** One record as its line. A close too long to keep sheds output lines until it fits — never itself, its id or its
+     * outcome — so replaying the file stays consistent; anything else too long becomes a `cut` of its stream. */
+    const line = (record) => {
+        let text = JSON.stringify(record);
+        if (!fits(text) && record.k === "done") {
+            const out = [...(record.out ?? [])];
+            do {
+                out.pop();
+                text = JSON.stringify(out.length === 0 ? (({ out: _out, ...bare }) => bare)(record) : { ...record, out });
+            } while (!fits(text) && out.length > 0);
+        }
+        return `${fits(text) ? text : JSON.stringify({ k: "cut", at: record.at, ...("s" in record ? { s: record.s } : {}) })}\n`;
+    };
+    const one = (record) => {
+        const text = line(record);
+        const capLine = line({ k: "cap", at: record.at, s: 0 });
+        if (written + Buffer.byteLength(text, "utf8") + Buffer.byteLength(capLine, "utf8") > LIVE_SUB_FILE_CAP) {
+            capped = true;
+            write(capLine);
+            return;
+        }
+        if (write(text))
+            sinceCheckpoint += Buffer.byteLength(text, "utf8");
+    };
+    return {
+        due() {
+            return fd !== null && !failed && !capped && sinceCheckpoint >= CHILD_CHECKPOINT_BYTES;
+        },
+        append(records, before) {
+            if (records.length === 0 || failed || capped)
+                return;
+            if (fd === null) {
+                try {
+                    mkdirSync(liveDir(root), { recursive: true, mode: 0o700 });
+                    fd = openSync(liveSubLogPath(root, runId), constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_APPEND | constants.O_NOFOLLOW, 0o600);
+                }
+                catch {
+                    failed = true;
+                    return;
+                }
+            }
+            for (const record of before === null ? records : [before, ...records]) {
+                if (failed || capped)
+                    return;
+                if (record.k === "ckpt")
+                    sinceCheckpoint = 0;
+                one(record);
+            }
+        },
+        close() {
+            if (fd !== null)
+                try {
+                    closeSync(fd);
+                }
+                catch { /* already gone */ }
+            fd = null;
+            failed = true;
+        },
+    };
+}

package/dist/live-detail.d.ts

@@ -1,4 +1,4 @@
-import type { Store } from "./store.js";
+import { type Store } from "./store.js";
 /** The consent a "Show commands" form carries: a single-use nonce minted for this person and these exact terms. */
 export declare const LIVE_VIEW_CONSENT = "live-view";
 export declare function liveViewConsentDigest(repo: string): string;
@@ -19,8 +19,9 @@ export declare function setLiveCommands(store: Store, change: {
 }, now: Date): {
     said: string;
 };
-/** A run's trusted context for its live file: its own checkout, and its project's setting, read now. */
-export declare function liveLogContext(store: Store, taskRef: number, worktree: string | null): {
+/** A run's trusted context for its live file: its own checkout, and its project's setting, captured for the run now —
+ * before the file opens. The writer uses the captured answer: a capture that fails writes no commands. */
+export declare function liveLogContext(store: Store, runId: number, taskRef: number, worktree: string | null, now: Date): {
     base: string | null;
     commands: boolean;
 };

package/dist/live-detail.js

@@ -5,10 +5,13 @@
  * project with their password; turning it off is one step. Every change is
  * an action-ledger line.
  *
- * The writer reads it once, when it opens a run's live file: what is off
- * never reaches disk, and a change applies from the next run.
+ * Each run captures its answer once, before its live file opens
+ * (run_live_detail, v136): what is off never reaches disk, a change applies
+ * from the next run, and every reader withholds commands unless that run's
+ * own captured answer is on (never the transcript's say, never the setting now).
  */
 import { createHash } from "node:crypto";
+import { captureRunLiveDetail } from "./store.js";
 /** The consent a "Show commands" form carries: a single-use nonce minted for this person and these exact terms. */
 export const LIVE_VIEW_CONSENT = "live-view";
 export function liveViewConsentDigest(repo) {
@@ -38,8 +41,9 @@ export function setLiveCommands(store, change, now) {
     });
     return { said: change.commands ? "Commands now show in the live view for this project, from the next run." : "Commands are hidden in the live view for this project, from the next run." };
 }
-/** A run's trusted context for its live file: its own checkout, and its project's setting, read now. */
-export function liveLogContext(store, taskRef, worktree) {
+/** A run's trusted context for its live file: its own checkout, and its project's setting, captured for the run now —
+ * before the file opens. The writer uses the captured answer: a capture that fails writes no commands. */
+export function liveLogContext(store, runId, taskRef, worktree, now) {
     let repo = null;
     try {
         repo = store.refForId(taskRef)?.repo ?? null;
@@ -47,5 +51,5 @@ export function liveLogContext(store, taskRef, worktree) {
     catch {
         repo = null;
     }
-    return { base: worktree, commands: liveCommandsShown(store, repo) };
+    return { base: worktree, commands: captureRunLiveDetail(store, runId, liveCommandsShown(store, repo), now) };
 }

package/dist/live-input.js

@@ -27,18 +27,13 @@
  * touches the store; the builder's dispatcher records what happened.
  */
 import { randomUUID } from "node:crypto";
+import { primaryResultEvent, topLevelEvent } from "./stream-scope.js";
 /** What Resume sends a paused session: only a nudge to go on, never a note. */
 export const CONTINUE_TEXT = "continue";
 /** A stdin user frame, in the shape the harness reads. */
 export const userFrame = (text, uuid) => JSON.stringify({ type: "user", message: { role: "user", content: text }, uuid });
 /** A stdin interrupt: stop the current turn, keep the session. */
 export const interruptFrame = (requestId, cancelQueued = false) => JSON.stringify({ type: "control_request", request_id: requestId, request: { subtype: "interrupt", ...(cancelQueued ? { cancel_queued: true } : {}) } });
-/** The session's own words count; a subagent's (parent_tool_use_id set) or a background task's never do. */
-const topLevel = (event) => event["parent_tool_use_id"] === undefined || event["parent_tool_use_id"] === null;
-const primaryResult = (event) => {
-    const origin = event["origin"];
-    return origin === undefined || origin === null || (typeof origin === "object" && String(origin["kind"] ?? "") === "human");
-};
 export class LiveInput {
     maxTurns;
     #options;
@@ -150,8 +145,12 @@ export class LiveInput {
     }
     /** Every parsed stdout event, in order. */
     observe(event) {
+        // A subagent's events (parent_tool_use_id set) are never the session's: not its words, its control answers or its
+        // result (stream-scope.ts).
+        if (!topLevelEvent(event))
+            return;
         const type = String(event["type"] ?? "");
-        if (type === "assistant" && topLevel(event)) {
+        if (type === "assistant") {
             this.#turnActive = true;
             const message = event["message"];
             const id = typeof message?.["id"] === "string" ? message["id"] : `turn-${this.#turns.size + 1}`;
@@ -170,7 +169,7 @@ export class LiveInput {
             if (requestId !== null && this.#interrupts.has(requestId) && response?.["subtype"] === "success" && this.#paused)
                 this.#notifyPaused();
         }
-        else if (type === "result" && primaryResult(event)) {
+        else if (type === "result" && primaryResultEvent(event)) {
             this.#turnActive = false;
             this.#interrupts.clear();
             if (this.#paused) {

package/dist/live-main-read.d.ts

@@ -0,0 +1,19 @@
+import { type LiveRecord } from "./live-records.js";
+export type MainWindow = {
+    ok: true;
+    records: LiveRecord[];
+    cursor: string;
+    restarted: boolean;
+    earlier: boolean;
+    quarantined: number;
+    skipped: number;
+    more: boolean;
+} | {
+    ok: false;
+    reason: "missing" | "unavailable";
+};
+/** One window of a run's own live file. `commands` is the run's own captured answer (store.ts runLiveCommands). */
+export declare function readMainWindow(root: string, runId: number, cursor: string | null, options: {
+    key: Buffer;
+    commands: boolean;
+}): MainWindow;

package/dist/live-main-read.js

@@ -0,0 +1,91 @@
+/**
+ * Reading a run's own live file for the Agents view's tiles (docs/plans/agents-view.md §2.3, N1): through the checked
+ * opener, one bounded window per request, from a sealed cursor — or, with none, from the start of a small file or
+ * the last 256 KiB of a large one. The run's own file has no checkpoints (its format is unchanged), so a read that
+ * starts mid-file can't know whether it starts inside a key block: it reads as if inside one until an END marker or
+ * 64 KiB of text pass, and a line that can't be read puts it back in that state. Every record is re-checked and
+ * re-redacted (live-records.ts parseLiveRecord) and read under the run's own captured "Show commands" answer.
+ */
+import { closeSync } from "node:fs";
+import { withholdCommands } from "./live.js";
+import { CURSOR_CAP, openCursor, sealCursor, UNKNOWN_KEY_BYTES } from "./live-children-read.js";
+import { openLiveTrusted, READ_WINDOW, readLiveLines, SCAN_BUDGET } from "./live-open.js";
+import { parseLiveRecord, validKeyTail } from "./live-records.js";
+function unseal(cursor, key, run, gen) {
+    if (cursor.length > CURSOR_CAP)
+        return null;
+    const raw = openCursor(cursor, key);
+    if (raw === null || raw["run"] !== run || raw["gen"] !== gen)
+        return null;
+    const { off, skipping, inKey, tail, unknown } = raw;
+    if (!Number.isSafeInteger(off) || off < 0 || typeof skipping !== "boolean" || typeof inKey !== "boolean")
+        return null;
+    if (typeof tail !== "string" || !validKeyTail(tail) || !Number.isSafeInteger(unknown) || unknown < 0 || unknown > UNKNOWN_KEY_BYTES)
+        return null;
+    return { run, gen, off: off, skipping, inKey, tail, unknown: unknown };
+}
+/** The bytes of text a record line carries (its words or output, as written): what uncertainty runs down by. */
+function rawText(line) {
+    try {
+        const record = JSON.parse(line);
+        const lines = record["k"] === "say" ? record["t"] : record["k"] === "done" ? record["out"] : undefined;
+        return Array.isArray(lines) ? lines.reduce((sum, one) => sum + (typeof one === "string" ? Buffer.byteLength(one, "utf8") : 0), 0) : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+/** One window of a run's own live file. `commands` is the run's own captured answer (store.ts runLiveCommands). */
+export function readMainWindow(root, runId, cursor, options) {
+    const opened = openLiveTrusted(root, `${Math.trunc(runId)}.jsonl`);
+    if (opened === "missing" || opened === "unavailable")
+        return { ok: false, reason: opened };
+    try {
+        let state = cursor === null ? null : unseal(cursor, options.key, runId, opened.gen);
+        const restarted = cursor !== null && (state === null || state.off > opened.size);
+        let earlier = false;
+        if (state === null || state.off > opened.size) {
+            // A small file from its start (its state is known there); a large one from its last 256 KiB, key state unknown.
+            earlier = opened.size > SCAN_BUDGET;
+            state = earlier
+                ? { run: runId, gen: opened.gen, off: opened.size - SCAN_BUDGET, skipping: true, inKey: false, tail: "", unknown: UNKNOWN_KEY_BYTES }
+                : { run: runId, gen: opened.gen, off: 0, skipping: false, inKey: false, tail: "", unknown: 0 };
+        }
+        const from = state.off;
+        const read = readLiveLines(opened.fd, opened.size, state.off, state.skipping);
+        const unknowable = () => { state.unknown = UNKNOWN_KEY_BYTES; };
+        if (read.skipped > 0)
+            unknowable();
+        const records = [];
+        let quarantined = 0;
+        for (const line of read.lines) {
+            const keys = { inKey: state.inKey || state.unknown > 0, tail: state.tail };
+            const parsed = parseLiveRecord(line.text, keys);
+            if (parsed === null) {
+                quarantined += 1;
+                unknowable();
+                continue;
+            }
+            // `inKey` is a block actually seen open (only a valid END ends it); `unknown` is uncertainty, which also runs
+            // down by the text the record actually carried.
+            const observed = { inKey: state.inKey, tail: state.tail };
+            parseLiveRecord(line.text, observed);
+            state.inKey = keys.inKey ? observed.inKey : false;
+            state.unknown = keys.inKey ? Math.max(0, state.unknown - rawText(line.text)) : 0;
+            state.tail = keys.tail ?? "";
+            if (parsed.k === "say" && parsed.t.length === 0)
+                continue; // all inside a key block
+            records.push(...withholdCommands([parsed], options.commands));
+        }
+        state.off = read.next;
+        state.skipping = read.skipping;
+        const more = read.next < opened.size && read.next > from && (read.skipping || opened.size - from > READ_WINDOW);
+        return { ok: true, records, cursor: sealCursor(state, options.key), restarted, earlier, quarantined, skipped: read.skipped, more };
+    }
+    catch {
+        return { ok: false, reason: "unavailable" };
+    }
+    finally {
+        closeSync(opened.fd);
+    }
+}

package/dist/live-open.d.ts

@@ -0,0 +1,28 @@
+export declare const READ_WINDOW: number;
+export declare const SCAN_BUDGET: number;
+export type LiveOpened = {
+    fd: number;
+    gen: string;
+    size: number;
+};
+/** Test seams only: run between the checks, to swap things under the opener. */
+export type OpenSeams = {
+    afterOpen?: () => void;
+};
+/** Open `name` in the run's live directory under `root`, or say it is missing or unavailable. */
+export declare function openLiveTrusted(root: string, name: string, seams?: OpenSeams): LiveOpened | "missing" | "unavailable";
+export type LineRead = {
+    /** Complete lines, each with the offset just past its newline. */
+    lines: {
+        text: string;
+        end: number;
+    }[];
+    /** Where the next request starts. */
+    next: number;
+    /** Lines too long to show that were skipped here. */
+    skipped: number;
+    /** The scan budget ran out inside a line: the next request resumes discarding through that line's end. */
+    skipping: boolean;
+};
+/** Read complete lines from `from` (discarding first through the next newline when `skipping`), within the budgets. */
+export declare function readLiveLines(fd: number, size: number, from: number, skipping?: boolean): LineRead;