toolroll 0.9.104 → 0.9.105

package/dist/live-bus.js

@@ -1,30 +1,3 @@
-/**
- * Live views push on write. Nothing here polls once a second.
- *
- * - The bus. Every connection's write wrapper (workspace-revision.ts)
- *   moves one counter per committed meaningful write. After each in-process
- *   transact() COMMIT, and whenever another process (the worker, the CLI)
- *   writes the database's write-ahead log, the revision is read once; when
- *   it moved, every subscriber hears `{ revision }`. A rolled-back or quiet
- *   write moves nothing and says nothing. A page left open with nothing
- *   being written costs no database work at all.
- * - The rooms. Each open task or flow is a room keyed by what it shows.
- *   When the bus speaks, a room rechecks every viewer's access (a signed-out
- *   or narrowed account is dropped), takes its fingerprint once, and only if
- *   that moved tells its pages `change` with the fingerprint and revision —
- *   an invalidation, never content. The page reads itself again under its
- *   own checks, so redaction stays the page's.
- * - The safety net. Every room also checks itself about every 30 s, so a
- *   missed signal heals; the page's connection sends a keep-alive between,
- *   each after every room proves its viewer again.
- * - One connection per page. A page opens one stream (GET /live) and joins
- *   every room it shows; each event names its room.
- * - Back-pressure. Each page's stream is bounded: a page that falls behind
- *   gets one `reload` and ends so its EventSource can reconnect.
- *
- * Transport seam: a future WebSocket (live cursors) subscribes to the same
- * LiveBus beside these SSE rooms; nothing in the Store or its write wrapper changes.
- */
 import { watch } from "node:fs";
 import { WORKSPACE_REVISION_KEY } from "./workspace-revision.js";
 export function createLiveBus() {
@@ -38,7 +11,7 @@ export function createLiveBus() {
                 try {
                     listener(change);
                 }
-                catch { /* one room never stops another */ }
+                catch { }
             }
         },
         revision: () => last,
@@ -46,17 +19,12 @@ export function createLiveBus() {
     };
 }
 const SIGNAL = "toolroll_live_written";
-/**
- * Publish the workspace revision when it moves: after this process commits,
- * and when the database's write-ahead log changes under another process.
- * Signals in one turn of the event loop coalesce into one read.
- */
 export function followWorkspace(store, current, bus, options = {}) {
     let last = null;
     try {
         last = current();
     }
-    catch { /* the first signal reads it */ }
+    catch { }
     let scheduled = false, closed = false;
     let timer = null;
     const check = () => {
@@ -64,7 +32,6 @@ export function followWorkspace(store, current, bus, options = {}) {
         timer = null;
         if (closed)
             return;
-        // Never read inside an open transaction: what it wrote isn't committed yet.
         if (store.handle.isTransaction === true) {
             schedule(10);
             return;
@@ -75,7 +42,7 @@ export function followWorkspace(store, current, bus, options = {}) {
         }
         catch {
             schedule(250);
-            return; /* busy: read again shortly */
+            return;
         }
         if (now === last)
             return;
@@ -83,7 +50,6 @@ export function followWorkspace(store, current, bus, options = {}) {
         bus.publish({ revision: now });
     };
     const schedule = (delay = 0) => {
-        // With no page open, nobody needs the read.
         if (scheduled || closed || bus.listeners() === 0)
             return;
         scheduled = true;
@@ -91,10 +57,6 @@ export function followWorkspace(store, current, bus, options = {}) {
         timer.unref?.();
     };
     const unhook = store.onCommit(() => schedule());
-    // A write this process makes outside transact() (an autocommit statement)
-    // moves the revision too: a connection-local TEMP trigger on the revision
-    // row calls back here. Other processes never see it. The read waits for
-    // the statement's own commit, and a rollback leaves the revision unmoved.
     let signalled = false;
     const db = store.handle;
     if (typeof db.function === "function") {
@@ -105,7 +67,7 @@ export function followWorkspace(store, current, bus, options = {}) {
         CREATE TEMP TRIGGER IF NOT EXISTS ${SIGNAL}_insert AFTER INSERT ON main.service_cursor WHEN NEW.key = '${WORKSPACE_REVISION_KEY}' BEGIN SELECT ${SIGNAL}(); END;`);
             signalled = true;
         }
-        catch { /* commits and the safety net still reach the rooms */ }
+        catch { }
     }
     const file = options.file ?? null;
     let watcher = null;
@@ -116,7 +78,6 @@ export function followWorkspace(store, current, bus, options = {}) {
         catch {
             return null;
         } });
-        // The worker and CLI write from their own processes; their commits land in the WAL.
         watcher = start(`${file}-wal`, () => schedule());
         watcher?.on?.("error", () => { watcher?.close(); watcher = null; });
     }
@@ -133,17 +94,14 @@ export function followWorkspace(store, current, bus, options = {}) {
                 try {
                     db.exec(`DROP TRIGGER IF EXISTS temp.${SIGNAL}_update; DROP TRIGGER IF EXISTS temp.${SIGNAL}_insert;`);
                 }
-                catch { /* the database is closing */ }
+                catch { }
             }
         },
     };
 }
-/** About every 30 s a room checks itself; a keep-alive goes between. */
 export const SAFETY_NET_MS = 30_000;
 export const KEEP_ALIVE_MS = 15_000;
-/** What a page's stream may hold unsent before it is "behind". */
 export const STREAM_LIMIT_BYTES = 32 * 1024;
-/** One page's stream, bounded. Overflow is terminal, even below Node's drain threshold. */
 export class LiveStream {
     response;
     limit;
@@ -159,8 +117,6 @@ export class LiveStream {
         if (!this.open)
             return;
         this.ended = true;
-        // end(data) queues at most this final frame; it never waits for a drain
-        // that Node may not emit when our limit is below its high-water mark.
         try {
             this.response.end("event: reload\ndata: {}\n\n");
         }
@@ -186,14 +142,6 @@ export class LiveStream {
         this.write(": keep-alive\n\n");
     }
 }
-/**
- * One page's live connection: its bounded stream, one keep-alive, and every
- * room it joined. Each event names its room, so one EventSource serves the
- * whole page. It ends when the page goes, when it falls behind (one
- * `reload`), or when its last room lets it go. A keep-alive is a delivery
- * too: every room proves its viewer again first, so a page whose session
- * lapsed with nothing written hears its rooms go, never another frame.
- */
 export class LiveConnection {
     response;
     stream;
@@ -218,14 +166,9 @@ export class LiveConnection {
         if (this.open)
             this.stream.keepAlive();
     }
-    /** Run before each keep-alive: a room proves its viewer again (and leaves if it no longer passes). Returns the undo. */
     onKeepAlive(prove) { this.proofs.add(prove); return () => { this.proofs.delete(prove); }; }
     get open() { return !this.closed && this.stream.open; }
-    /** An event for one room: its data says which. */
     send(room, event, data = {}) { this.stream.send(event, { room, ...data }); }
-    /** A room leaves because its proof failed (a sign-out, a revoked or narrowed account): if that departure ends the
-     * connection, the page is told the stream `ended` and stops, rather than reconnecting at once into a request that
-     * can't sign in. Any other close — the page going, a later shutdown, an overflow — says nothing of it. */
     refuse(leave) {
         const outer = this.refusing;
         this.refusing = true;
@@ -236,7 +179,6 @@ export class LiveConnection {
             this.refusing = outer;
         }
     }
-    /** Run when the connection ends; returns the undo for a room that leaves first. */
     onClose(leave) { this.leaves.add(leave); return () => { this.leaves.delete(leave); }; }
     close() {
         if (this.closed)
@@ -254,17 +196,9 @@ export class LiveConnection {
         if (!this.response.writableEnded)
             this.response.end();
     }
-    /** Rooms joined and not yet left. */
     get rooms() { return this.leaves.size; }
 }
 const PRESENCE_SETTLE_MS = 150;
-/**
- * Rooms of open pages that hear the bus. `presence` says who else is here, as
- * each page should see it (null: the room has no presence). A viewer that no
- * longer passes its re-proof hears `gone` and leaves; a room whose subject is
- * gone (fingerprint null) sends everyone `gone`. A connection with no rooms
- * left ends.
- */
 export function createLiveRooms(fingerprint, presence, options = {}) {
     const bus = options.bus ?? null;
     const safetyNetMs = options.safetyNetMs ?? SAFETY_NET_MS;
@@ -275,7 +209,6 @@ export function createLiveRooms(fingerprint, presence, options = {}) {
     const announce = (key, room) => {
         if (presence === null || rooms.get(key) !== room)
             return;
-        // A page that moves from one card to the next leaves and joins at once: say it once, after it settles.
         if (room.settling !== null)
             clearTimeout(room.settling);
         room.settling = setTimeout(() => {
@@ -292,7 +225,6 @@ export function createLiveRooms(fingerprint, presence, options = {}) {
             return;
         room.viewers.delete(viewer);
         forget();
-        // The page's last room: its connection has nothing left to say.
         if (viewer.connection.rooms === 0)
             viewer.connection.close();
         if (room.viewers.size > 0) {
@@ -315,7 +247,6 @@ export function createLiveRooms(fingerprint, presence, options = {}) {
             unsubscribe = null;
         }
     };
-    /** The final delivery boundary, including queued frames and sends that may overflow. */
     const deliver = (key, room, viewer, event, data = {}) => {
         if (rooms.get(key) !== room || !room.viewers.has(viewer))
             return false;
@@ -327,9 +258,8 @@ export function createLiveRooms(fingerprint, presence, options = {}) {
         try {
             valid = viewer.valid();
         }
-        catch { /* A failed proof releases only this room. */ }
+        catch { }
         if (!valid || event === "gone") {
-            // A failed proof may send only the generic departure, never the pending room data.
             try {
                 viewer.connection.send(viewer.room, "gone");
             }
@@ -345,9 +275,7 @@ export function createLiveRooms(fingerprint, presence, options = {}) {
             viewer.connection.send(viewer.room, event, data);
         return viewer.connection.open && room.viewers.has(viewer);
     };
-    /** Recheck who may still see the room, then whether what it shows moved. */
     const refresh = (key, room, revision) => {
-        // A signed-out or narrowed account stops hearing about it, at the first write after.
         for (const viewer of [...room.viewers.keys()])
             deliver(key, room, viewer);
         if (rooms.get(key) !== room)
@@ -357,7 +285,6 @@ export function createLiveRooms(fingerprint, presence, options = {}) {
             now = fingerprint(key);
         }
         catch {
-            // A busy database: read again shortly rather than wait for the safety net.
             if (room.retry === null) {
                 room.retry = setTimeout(() => { room.retry = null; if (rooms.get(key) === room)
                     refresh(key, room, revision); }, 1_000);
@@ -396,7 +323,6 @@ export function createLiveRooms(fingerprint, presence, options = {}) {
                 refresh(key, room, change.revision);
                 continue;
             }
-            // Re-prove now; read once the burst settles.
             for (const viewer of [...room.viewers.keys()])
                 deliver(key, room, viewer);
             if (rooms.get(key) !== room || room.reading !== null)
@@ -414,7 +340,7 @@ export function createLiveRooms(fingerprint, presence, options = {}) {
                 try {
                     last = fingerprint(key);
                 }
-                catch { /* the next signal or the safety net reads it */ }
+                catch { }
                 const created = { viewers: new Map(), last, timer: setInterval(() => refresh(key, created, null), safetyNetMs), settling: null, retry: null, saidAt: 0, holding: null, revision: null, reading: null };
                 created.timer.unref();
                 room = created;

package/dist/live-children-read.js

@@ -1,17 +1,3 @@
-/**
- * Reading a run's subagents' file (docs/plans/agents-view.md §2.3, N1): forward from a sealed cursor, or — on a first
- * read or a cursor that doesn't hold — from the newest checkpoint near the end, and never from a guess.
- *
- * The file is display state the machine running the agent could alter, so the reader trusts nothing it reads back:
- * every record is re-checked (shape, caps, its stream open, a close only of its own stream's open step), re-redacted
- * under that stream's own key state, and read under the run's captured "Show commands" answer (never the file's).
- * What fails is quarantined: counted, never shown, never promoted to the run's own conversation.
- *
- * The cursor carries the state the next window needs — offset, file generation, each stream's parent, open steps and
- * key state — bounded (17 streams, 32 open steps, 4 KiB encoded), bound to this run and file, and sealed with an HMAC
- * under a key the caller keeps outside any build's reach. A valid cursor is state, never permission: the caller proves
- * access on every read. One that doesn't verify, or names another run or file, restarts visibly.
- */
 import { createHmac, timingSafeEqual } from "node:crypto";
 import { closeSync, readSync } from "node:fs";
 import { withholdCommands } from "./live.js";
@@ -19,14 +5,12 @@ import { openLiveTrusted, READ_WINDOW, readLiveLines, SCAN_BUDGET } from "./live
 import { parseLiveRecord, redactLiveLines, validKeyTail } from "./live-records.js";
 import { CHILD_OPEN_STEPS_CAP, CHILD_STREAMS_CAP } from "./live-children.js";
 export const CURSOR_CAP = 4 * 1024;
-/** Longer than any real key block: past this much of a stream's text with no END marker, its key state is known again. */
 export const UNKNOWN_KEY_BYTES = 64 * 1024;
 const RECORD_CAP = 8 * 1024;
 const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
 const streamNo = (value) => (Number.isInteger(value) && value >= 1 && value <= CHILD_STREAMS_CAP ? value : null);
 const PARENT = /^(?:s|c(?:[1-9]|1[0-6])s)[1-9][0-9]{0,8}$/;
 const childStep = (s) => new RegExp(`^c${s}(s[1-9][0-9]{0,8})$`);
-/** A stream list (from a checkpoint or a cursor) within every bound, or null. */
 function streamsOf(value) {
     if (!Array.isArray(value) || value.length > CHILD_STREAMS_CAP)
         return null;
@@ -40,14 +24,12 @@ function streamsOf(value) {
         const parent = one["parent"], via = one["via"], ids = one["open"], tail = one["tail"] ?? "";
         if (!(parent === null || (typeof parent === "string" && PARENT.test(parent))))
             return null;
-        // A subagent nests under one listed before it: no cycles, nothing dangling.
         if (via !== undefined && (streamNo(via) === null || !out.some(prior => prior.s === via)))
             return null;
         if (!Array.isArray(ids) || !ids.every(id => typeof id === "string" && childStep(s).test(id)) || new Set(ids).size !== ids.length)
             return null;
         if (typeof one["inKey"] !== "boolean" || typeof tail !== "string" || !validKeyTail(tail))
             return null;
-        // Absent means the default; an explicit null (or anything else) is not a value these fields take.
         const ended = one["ended"] === undefined ? false : one["ended"], unknown = one["unknown"] === undefined ? 0 : one["unknown"];
         if (typeof ended !== "boolean" || !Number.isSafeInteger(unknown) || unknown < 0 || unknown > UNKNOWN_KEY_BYTES)
             return null;
@@ -56,12 +38,10 @@ function streamsOf(value) {
     }
     return open <= CHILD_OPEN_STEPS_CAP ? out : null;
 }
-/** Seal a reader's state under the caller's key (the same form for the run's own file and its subagents'). */
 export function sealCursor(state, key) {
     const body = Buffer.from(JSON.stringify(state), "utf8").toString("base64url");
     return `${body}.${createHmac("sha256", key).update(body).digest("base64url")}`;
 }
-/** A sealed state's object when the seal holds and it is within the cap; null otherwise (the caller re-checks it). */
 export function openCursor(cursor, key) {
     if (cursor.length > CURSOR_CAP)
         return null;
@@ -95,8 +75,6 @@ function unseal(cursor, key, run, gen) {
         return null;
     }
 }
-/** Where a read with no usable cursor begins: the file's start when it is small, else the newest checkpoint in its last
- * SCAN_BUDGET bytes; with none there, nothing is shown until the next checkpoint (fails closed). */
 function bootstrap(fd, size, run, gen) {
     const empty = { run, gen, off: 0, skipping: false, awaiting: false, streams: [] };
     if (size <= SCAN_BUDGET)
@@ -117,13 +95,12 @@ function bootstrap(fd, size, run, gen) {
         if (lf === -1)
             break;
         if (buffer.subarray(at, lf).indexOf('"k":"ckpt"') !== -1) {
-            // A checkpoint this reader can use: one record, within the record cap, whose streams pass every bound.
             try {
                 const record = lf - at <= RECORD_CAP ? object(JSON.parse(buffer.subarray(at, lf).toString("utf8"))) : null;
                 if (record?.["k"] === "ckpt" && streamsOf(record["streams"]) !== null)
                     found = at;
             }
-            catch { /* not one */ }
+            catch { }
         }
         at = lf + 1;
     }
@@ -133,8 +110,6 @@ function bootstrap(fd, size, run, gen) {
 }
 const ISO = (value) => typeof value === "string" && value.length <= 40 && Number.isFinite(Date.parse(value)) ? value : undefined;
 const DISPLAY_KINDS = new Set(["session", "message", "edit", "command", "read", "search", "lookup", "plan", "delegate", "tool"]);
-/** A learned stream's display, from its checkpoint entry: each field checked, text re-redacted under the stream's own key
- * state (unknown for a stream first seen here, so a target reads hidden); anything malformed is simply left out. */
 function displayOf(one, entry, commands) {
     const desc = typeof entry?.["desc"] === "string" && entry["desc"].length <= 200 ? redactLiveLines([entry["desc"]])[0] : undefined;
     const at = ISO(entry?.["at"]);
@@ -150,7 +125,6 @@ function displayOf(one, entry, commands) {
             continue;
         const keys = { inKey: one.inKey || one.unknown > 0, tail: one.tail };
         const parsed = parseLiveRecord(JSON.stringify({ k: "step", at: at ?? "", id: local, kind, ...(target === undefined ? {} : { target }) }), keys);
-        // Under the run's own "Show commands" answer, like every other record.
         const [shown] = parsed === null ? [] : withholdCommands([parsed], commands);
         if (shown !== undefined && shown.k === "step")
             views.push({ ...shown, id, s: one.s });
@@ -161,18 +135,14 @@ function displayOf(one, entry, commands) {
     }
     return views;
 }
-/** One line under the state: what it shows, or null when it is quarantined (`counted` says whether it counts). */
-/** A record's own time, when it is a plain ISO time (display only). */
 const stampOf = (record) => {
     const at = record["at"];
     return typeof at === "string" && at.length <= 40 && Number.isFinite(Date.parse(at)) ? { at } : {};
 };
-/** The bytes of text a record carries (its words or its output): what uncertainty about a key block runs down by. */
 function scannedText(record) {
     const lines = record["k"] === "say" ? record["t"] : record["k"] === "done" ? record["out"] : undefined;
     return Array.isArray(lines) ? lines.reduce((sum, line) => sum + (typeof line === "string" ? Buffer.byteLength(line, "utf8") : 0), 0) : 0;
 }
-/** A line that couldn't be read may have carried a key marker for any stream: every stream's key state is unknown. */
 function unknowable(state) {
     for (const one of state.streams)
         one.unknown = UNKNOWN_KEY_BYTES;
@@ -194,12 +164,8 @@ function apply(state, text, commands) {
         return null;
     if (record["k"] === "ckpt") {
         const streams = streamsOf(record["streams"]);
-        // A checkpoint names every stream this reader already follows: one that drops a stream would let its number (and
-        // its open key block) be reused.
         if (streams === null || !state.streams.every(known => streams.some(next => next.s === known.s)))
             return null;
-        // The file's own word on key state never weakens what this reader knows: a stream it has followed keeps its own
-        // key state (the checkpoint can only add caution); one it first learns of here starts unknown.
         const learned = streams.filter(next => !state.streams.some(one => one.s === next.s));
         state.streams = streams.map(next => {
             const known = state.streams.find(one => one.s === next.s);
@@ -208,8 +174,6 @@ function apply(state, text, commands) {
                 : { ...next, inKey: known.inKey, tail: known.tail, unknown: next.inKey ? Math.max(known.unknown, UNKNOWN_KEY_BYTES) : known.unknown };
         });
         state.awaiting = false;
-        // A stream first learned here (a read that began mid-file) is shown as the subagent it is, its open steps, and how
-        // it ended — display only, read from the checkpoint and checked here, never kept in the sealed cursor.
         const raw = Array.isArray(record["streams"]) ? record["streams"] : [];
         return learned.flatMap(next => displayOf(state.streams.find(one => one.s === next.s), raw.map(object).find(entry => entry?.["s"] === next.s) ?? null, commands));
     }
@@ -247,7 +211,6 @@ function apply(state, text, commands) {
         stream.open = [];
         return [{ k: "end", s, ...stampOf(record), ok }];
     }
-    // The run's own record shape, under this stream's key state, with its id as the run's own recorder writes it.
     const id = record["id"];
     let local;
     if (id !== undefined) {
@@ -258,10 +221,8 @@ function apply(state, text, commands) {
     }
     const { s: _s, ...rest } = record;
     const body = JSON.stringify(local === undefined ? rest : { ...rest, id: local });
-    // Read on a copy of the key state; it is kept only if the record passes every check below.
     const keys = { inKey: stream.inKey || stream.unknown > 0, tail: stream.tail };
     const parsed = parseLiveRecord(body, keys);
-    // The block as actually observed (not forced by uncertainty): the same record read under the observed state.
     const observed = { inKey: stream.inKey, tail: stream.tail };
     parseLiveRecord(body, observed);
     if (parsed === null || parsed.k === "open")
@@ -269,25 +230,23 @@ function apply(state, text, commands) {
     if (parsed.k === "step" && parsed.once !== true) {
         const total = state.streams.reduce((sum, one) => sum + one.open.length, 0);
         if (total >= CHILD_OPEN_STEPS_CAP || stream.open.includes(id))
-            return null; // full, or already open
+            return null;
         stream.open.push(id);
     }
     else if (parsed.k === "done") {
         const at = stream.open.indexOf(id);
         if (at === -1)
-            return null; // never one this stream has open
+            return null;
         stream.open.splice(at, 1);
     }
-    // An observed block ends only at a valid END; uncertainty also runs down by the text this record actually carried.
     stream.inKey = keys.inKey ? observed.inKey : false;
     stream.unknown = keys.inKey ? Math.max(0, stream.unknown - scannedText(record)) : 0;
     stream.tail = keys.tail ?? "";
     if (parsed.k === "say" && parsed.t.length === 0)
-        return []; // all inside a key block: nothing to show
+        return [];
     const [shown] = withholdCommands([parsed], commands);
     return [{ ...shown, ...(local === undefined ? {} : { id: id }), s }];
 }
-/** One window of a run's subagents' file. `commands` is the run's own captured answer (store.ts runLiveCommands). */
 export function readChildWindow(root, runId, cursor, options) {
     const name = `${Math.trunc(runId)}.sub.jsonl`;
     const opened = openLiveTrusted(root, name);
@@ -299,7 +258,6 @@ export function readChildWindow(root, runId, cursor, options) {
         const restarted = cursor !== null && (state === null || state.off > opened.size);
         if (state === null || state.off > opened.size) {
             ({ state, earlier } = bootstrap(opened.fd, opened.size, runId, opened.gen));
-            // One request's reading budget: a bootstrap that scanned the end of the file reads nothing more now.
             if (earlier)
                 return { ok: true, records: [], cursor: seal(state, options.key), restarted, earlier, quarantined: 0, skipped: 0, more: true };
         }
@@ -320,7 +278,6 @@ export function readChildWindow(root, runId, cursor, options) {
         }
         state.off = read.next;
         state.skipping = read.skipping;
-        // More only when this read stopped short of what is written and moved: an unfinished last line waits for growth.
         const more = read.next < opened.size && (read.next > from) && (read.skipping || opened.size - from > READ_WINDOW);
         return { ok: true, records, cursor: seal(state, options.key), restarted, earlier: earlier || state.awaiting, quarantined, skipped: read.skipped, more };
     }

package/dist/live-children.js

@@ -1,18 +1,3 @@
-/**
- * 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";
@@ -21,29 +6,20 @@ 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");
@@ -59,12 +35,10 @@ export function createChildRecorder(options) {
     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);
@@ -72,7 +46,6 @@ export function createChildRecorder(options) {
         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;
@@ -81,7 +54,6 @@ export function createChildRecorder(options) {
                 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") {
@@ -105,7 +77,7 @@ export function createChildRecorder(options) {
                 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 });
             }
@@ -125,7 +97,6 @@ export function createChildRecorder(options) {
         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)
@@ -155,7 +126,6 @@ export function createChildRecorder(options) {
                 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)
@@ -168,7 +138,7 @@ export function createChildRecorder(options) {
                 if (into === undefined || into === "ambiguous" || into.ended === true) {
                     dropped += 1;
                     return [];
-                } // unknown, ambiguous or over
+                }
                 let stream = into.stream;
                 const records = [];
                 if (stream === undefined) {
@@ -185,8 +155,7 @@ export function createChildRecorder(options) {
                 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 };
@@ -198,14 +167,12 @@ export function createChildRecorder(options) {
                     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);
@@ -235,11 +202,6 @@ export function createChildRecorder(options) {
         },
     };
 }
-/**
- * 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;
@@ -256,8 +218,6 @@ export function childLogWriter(root, runId) {
         }
     };
     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") {
@@ -310,7 +270,7 @@ export function childLogWriter(root, runId) {
                 try {
                     closeSync(fd);
                 }
-                catch { /* already gone */ }
+                catch { }
             fd = null;
             failed = true;
         },