@smthrs/gateway 0.35.0 → 1.0.0-rc.3

package/dist/esm/RunTrace.js

@@ -0,0 +1,2105 @@
+/**
+ * The run trace model (factory spec 06, "the run trace": one card shows every
+ * run).
+ *
+ * A run is a recursive program: the agent writes REPL cells in a code
+ * container, every `ctx.call` is a durable span, and each turn is a frame. The
+ * control journal already records exactly that (`@smthrs/agent` AgentSession
+ * journals turn-opened, model-settled, cell-produced, cell-call-started,
+ * cell-call-settled, cell-printed, cell-settled, resolved), and the gateway
+ * serves it as the `run-events` projection the run card already reads. This
+ * module folds those records into a span tree, run → frame → cell → call, and
+ * the geometry of one bar per span on a shared time axis. No second data
+ * source: what the journal does not carry (realm variables, child runs' own
+ * frames) the model does not invent.
+ *
+ * Pure: the card renders the model, the tests read it from a fixture.
+ * @since 1.0.0
+ */
+import { CallFact } from "@smthrs/journal";
+import { CallPresentation, FlowActivity } from "@smthrs/registry/Descriptor";
+import { Schema } from "effect";
+import { callScope, openCallIndex } from "./Diagnosis.js";
+import { engineExecutionEvidence, engineTraceFromJournal } from "./EngineTrace.js";
+import { ACTION_RENDERINGS } from "./internal/actionRenderings.js";
+import { callEventFilter, nativeStepEvent, uniqueCallEvents } from "./internal/callEvents.js";
+import { inspectLabel } from "./internal/inspectLabels.js";
+export { inspectLabel } from "./internal/inspectLabels.js";
+const TERMINAL_RUN = new Set(["completed", "failed", "cancelled", "no-capacity"]);
+const asRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
+const asString = (value) => typeof value === "string" ? value : undefined;
+const asNumber = (value) => typeof value === "number" && Number.isFinite(value) ? value : undefined;
+/** The record's time: the agent's own `at` stamp when it carries one, the journal's otherwise (the gateway's rule). */
+const timeOf = (record, payload) => asNumber(payload.at) ?? asNumber(record.occurredAt) ?? 0;
+/** One line of text for a value the journal traced, or nothing. */
+const textOf = (value) => {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value === "string")
+        return value;
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+};
+/** The payload fields the pane does not already show by name. */
+const restOf = (payload, shown) => {
+    const rest = {};
+    for (const [key, value] of Object.entries(payload)) {
+        if (shown.includes(key) || key === "at" || key === "journalVersion")
+            continue;
+        rest[key] = value;
+    }
+    return Object.keys(rest).length === 0 ? undefined : rest;
+};
+const builder = (id, kind, label, status, startedAt, detail) => ({ id, kind, label, status, startedAt, children: [], detail });
+/** Compatibility for journals whose descriptors predate presentation metadata. */
+const legacy = (activity, pending, success, failure, subject, result) => ({
+    ...(activity === undefined ? {} : { activity }),
+    presentation: { verb: { pending, success, failure }, subject, result }
+});
+const LEGACY_PRESENTATION = new Map([
+    // `bash` has no compatibility activity for the same reason `@smthrs/std`
+    // declares none: what a shell call does is in the command, which the rule
+    // below reads off the record.
+    ["bash", legacy(undefined, "running", "ran", "failed to run", "command", "command")],
+    ["test", legacy("tests", "running", "ran", "failed to run", "selection", "tests")],
+    ["edit", legacy("writes", "editing", "edited", "failed to edit", "path", "edit")],
+    ["write", legacy("writes", "writing", "wrote", "failed to write", "path", "write")],
+    ["apply_patch", legacy("writes", "patching", "patched", "failed to patch", "patch", "patch")],
+    ["read", legacy("reads", "reading", "read", "failed to read", "path", "read")],
+    ["grep", legacy("reads", "searching", "searched", "failed to search", "pattern", "matches")],
+    ["glob", legacy("reads", "listing", "listed", "failed to list", "pattern", "paths")],
+    ["ls", legacy("reads", "listing", "listed", "failed to list", "path", "entries")]
+]);
+/** Read only the descriptor's validated display fields; a call input is never metadata. */
+const recordedMetadata = (value, flowName) => {
+    const descriptor = asRecord(value);
+    if (descriptor.name !== flowName)
+        return undefined;
+    if (descriptor.activity === undefined && descriptor.presentation === undefined)
+        return undefined;
+    const activity = Schema.is(FlowActivity)(descriptor.activity) ? descriptor.activity : undefined;
+    const presentation = Schema.is(CallPresentation)(descriptor.presentation) ? descriptor.presentation : undefined;
+    return { activity, presentation };
+};
+/**
+ * The name a queued checkpoint mint carries (`QuickJSSandbox` `checkpointFlow`).
+ * A mint journals `control.agent.checkpoint-minted` and never a call, so no
+ * call in a journal wears this name today; the dominant-call rule skips it
+ * anyway, so a host that binds a flow by that name cannot make a frame's
+ * headline read as bookkeeping.
+ */
+const CHECKPOINT_FLOW = "checkpoint";
+/** The command line a call ran, for the flows that run one. */
+const commandOf = (input) => {
+    const fields = asRecord(input);
+    return asString(fields.command) ?? asString(fields.script);
+};
+/** The last segment of a path: the name a person calls the file. */
+const basename = (path) => path.split("/").filter((part) => part !== "").pop() ?? path;
+/**
+ * The files a V4A patch names (`@smthrs/std` ApplyPatch's `*** Add File: `,
+ * `*** Delete File: ` and `*** Update File: ` markers).
+ *
+ * `apply_patch` carries its entire patch in one `input` string, and the patch
+ * is not the subject: what it patches is. A string that is not a patch names no
+ * files and yields none, so a flow that happens to call its field `input` is
+ * not mistaken for one.
+ */
+const patchedPaths = (patch) => {
+    const paths = [];
+    for (const line of patch.split("\n")) {
+        const named = /^\*\*\* (?:Add|Delete|Update) File:\s*(\S.*)$/.exec(line.trim())?.[1];
+        if (named !== undefined)
+            paths.push(named.trim());
+    }
+    return paths;
+};
+/**
+ * Several files in the room one name has: the first named, the rest counted.
+ *
+ * A multi-file patch's line and a frame's write pin both say it through here,
+ * so `views.py +1` means one thing wherever the card prints it. The count is a
+ * fact the journal carried, never an estimate. No file, no words.
+ */
+const filesLabel = (paths) => {
+    const first = paths[0];
+    if (first === undefined)
+        return "";
+    return paths.length === 1 ? basename(first) : `${basename(first)} +${paths.length - 1}`;
+};
+/** The files an edit-like call names: its `path`, or every file its patch names. */
+const writtenPaths = (input) => {
+    const fields = asRecord(input);
+    const path = asString(fields.path);
+    if (path !== undefined)
+        return [path];
+    const patch = asString(fields.input);
+    return patch === undefined ? [] : patchedPaths(patch);
+};
+/**
+ * What one recorded call was about, in the shape its declaration chose.
+ *
+ * Exported because the run header names the same subject as the row beneath
+ * it: two readings of one input is two answers to one question.
+ *
+ * @param input the call input, as journaled
+ * @param format the declared subject field, when the declaration named one
+ *
+ * @category utilities
+ * @since 1.0.0
+ */
+export const callSubject = (input, format) => {
+    const fields = asRecord(input);
+    if (format === "none")
+        return "";
+    if (format === "path")
+        return asString(fields.path) === undefined ? "" : basename(fields.path);
+    if (format === "command")
+        return commandOf(input) ?? "";
+    if (format === "patch")
+        return filesLabel(patchedPaths(asString(fields.input) ?? ""));
+    if (format === "pattern")
+        return asString(fields.pattern) ?? "";
+    if (format === "selection")
+        return stringList(fields.selection)?.join(" ") ?? "";
+    const path = asString(fields.path);
+    if (path !== undefined)
+        return basename(path);
+    const command = commandOf(input);
+    if (command !== undefined)
+        return command;
+    const patch = asString(fields.input);
+    if (patch !== undefined) {
+        // The patch is not the subject; the files it patches are.
+        const files = filesLabel(patchedPaths(patch));
+        if (files !== "")
+            return files;
+    }
+    // `test` names what it selected (`@smthrs/std` TestRun `Input.selection`).
+    // An omitted selection means the record named nothing; that the flow would
+    // then run everything is the flow's default, not a fact this record carries.
+    const selection = Array.isArray(fields.selection)
+        ? fields.selection.filter((one) => typeof one === "string")
+        : undefined;
+    if (selection !== undefined && selection.length > 0)
+        return selection.join(" ");
+    return asString(fields.pattern) ?? "";
+};
+/**
+ * Legacy shell journals have no structured activity. Recognize only direct
+ * invocations of known runners. Shell composition, expansion and quoted
+ * programs remain unknown. Arguments can narrow a check without changing
+ * its activity; no command here establishes a plan's required coverage.
+ */
+const shellActivity = (command) => {
+    if (/[;&|<>`$\n\r]/.test(command))
+        return "other";
+    const words = command.trim().split(/\s+/);
+    const first = words[0];
+    if (["pytest", "vitest", "jest"].includes(first))
+        return "tests";
+    if (/^python[23]?$/.test(first) && words[1] === "-m" && ["pytest", "unittest"].includes(words[2] ?? "")) {
+        return "tests";
+    }
+    if (first === "bun" && words[1] === "test")
+        return "tests";
+    if (["pnpm", "npm", "bun"].includes(first)) {
+        if (words[1] === "test" || (words[1] === "run" && words[2] === "test"))
+            return "tests";
+        if (words[1] === "exec" && ["vitest", "jest"].includes(words[2] ?? ""))
+            return "tests";
+        if (words[1] === "run" && ["check", "typecheck", "lint"].includes(words[2] ?? ""))
+            return "checks";
+    }
+    if (first === "go" && words[1] === "test")
+        return "tests";
+    if (first === "cargo" && words[1] === "test")
+        return "tests";
+    if (first === "tsc")
+        return "checks";
+    return "other";
+};
+/**
+ * The one reading of a recorded call's semantics, shared by the rows, the
+ * phase bands and the run header.
+ *
+ * Precedence, and why: the record's own `descriptor` wins, because it is what
+ * the declaration said when the call was made, and only a record that carries
+ * none falls back to {@link LEGACY_PRESENTATION}, which is a guess about the
+ * flows that were journaled before a declaration could say anything. A flow the
+ * table does not know stays unknown, and unknown is said as unknown.
+ *
+ * `bash` is the one activity read off the call rather than the declaration.
+ * `@smthrs/std` declares none for it on purpose — the same flow runs a test
+ * suite, a type check and `cat` — so a recognised runner in the recorded
+ * command is the only thing that names the activity, and an explicit
+ * declaration still outranks it.
+ *
+ * @param flowName the flow the record names
+ * @param payload the `cell-call-started` payload, as journaled
+ *
+ * @category utilities
+ * @since 1.0.0
+ */
+export const callSemantics = (flowName, payload) => {
+    const recorded = recordedMetadata(payload.descriptor, flowName);
+    const metadata = recorded ?? LEGACY_PRESENTATION.get(flowName);
+    const activity = metadata?.activity
+        ?? (flowName === "bash" ? shellActivity(commandOf(payload.input) ?? "") : undefined);
+    return {
+        ...(activity === undefined ? {} : { activity }),
+        ...(metadata?.presentation === undefined ? {} : { presentation: metadata.presentation })
+    };
+};
+const stringList = (value) => Array.isArray(value) && value.every((entry) => typeof entry === "string") ? value : undefined;
+const countOf = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+const counted = (value, noun, plural = `${noun}s`) => `${value} ${value === 1 ? noun : plural}`;
+/** Known output fields only. Unknown objects remain in the call's raw output. */
+const resultOf = (value, format) => {
+    if (format === "none")
+        return "";
+    if (typeof value === "string")
+        return clip(value) ?? "";
+    const fields = asRecord(value);
+    if (fields.truncated === true && typeof fields.digest === "string")
+        return "";
+    switch (format) {
+        case "read": {
+            const start = countOf(fields.startLine);
+            const end = countOf(fields.endLine);
+            return start !== undefined && start > 0 && end !== undefined && end >= start - 1
+                ? counted(end - start + 1, "line") :
+                "";
+        }
+        case "write":
+            return countOf(fields.bytesWritten) === undefined ? "" : counted(fields.bytesWritten, "byte");
+        case "edit":
+            return countOf(fields.replacements) === undefined ? "" : counted(fields.replacements, "replacement");
+        case "patch": {
+            const groups = [stringList(fields.added), stringList(fields.modified), stringList(fields.deleted)];
+            return groups.every((group) => group !== undefined) ? counted(new Set(groups.flat()).size, "file") : "";
+        }
+        case "tests": {
+            const passed = countOf(fields.passed);
+            const failed = stringList(fields.failed);
+            if (fields.parsed === true && passed !== undefined && failed !== undefined && fields.invalidProbe === undefined) {
+                const exit = countOf(fields.exitCode);
+                return `${passed} passed${failed.length > 0 ? ` · ${failed.length} failed` : exit !== undefined && exit !== 0 ? ` · exit ${exit}` : ""}`;
+            }
+            return countOf(fields.exitCode) === undefined ? "" : `exit ${fields.exitCode}`;
+        }
+        case "command":
+            return countOf(fields.exitCode) === undefined ? "" : `exit ${fields.exitCode}`;
+        case "matches":
+            return Array.isArray(fields.matches) ? counted(fields.matches.length, "match", "matches") : "";
+        case "paths":
+            return stringList(fields.paths) === undefined
+                ? ""
+                : counted(fields.paths.length, "file");
+        case "entries":
+            return Array.isArray(fields.entries) ? counted(fields.entries.length, "entry", "entries") : "";
+        default:
+            return "";
+    }
+};
+/** A note body from the sentences the payload carried; a field the record omitted contributes nothing. */
+const bodyOf = (...sentences) => sentences.filter((sentence) => sentence !== undefined).join(" ");
+/** One quoted line of evidence, bounded the way the turn list bounds prose. */
+const clip = (value) => {
+    const line = asString(value);
+    if (line === undefined || line === "")
+        return undefined;
+    return line.length <= 160 ? line : `${line.slice(0, 159).trimEnd()}…`;
+};
+/** Whether the frame made an edit-like call the journal recorded settling successfully. */
+const madeAWrite = (entry) => entry.calls.some((call) => call.activity === "writes" && call.settled?.failed === false && !call.settled.denied);
+/**
+ * The call a frame's line is about: a change it made, else the check it ran,
+ * else the first thing it asked for.
+ *
+ * The phase rules and the lines read the same answer, so the two can never
+ * disagree about whether the journal said anything about a frame at all.
+ */
+const dominantCall = (entry) => entry.calls.find((one) => one.activity === "writes")
+    ?? entry.calls.find((one) => one.activity === "checks" || one.activity === "tests")
+    ?? entry.calls.find((one) => one.flowName !== CHECKPOINT_FLOW);
+const disciplineInit = (runId) => ({
+    runId,
+    frames: [],
+    notes: [],
+    milestones: [],
+    owners: [],
+    open: [],
+    frame: undefined,
+    lastAt: 0,
+    lineOf: new WeakMap()
+});
+/** One record of the discipline fold; the state is advanced in place. */
+const disciplineStep = (state, record) => {
+    const { runId, frames, notes, milestones, owners, open } = state;
+    let frame = state.frame;
+    /** Where a discipline record attaches: the open frame, else the run itself. */
+    const here = () => frame?.id ?? `run:${runId}`;
+    const note = (seq, tone, title, body, evidence) => {
+        const quoted = evidence.filter((line) => line !== undefined);
+        notes.push({ seq, spanId: here(), tone, title, body, ...(quoted.length === 0 ? {} : { evidence: quoted }) });
+    };
+    /** A moment, owned by the frame that recorded it, exactly the way a note is. */
+    const pin = (seq, at, label, tone) => {
+        milestones.push({ seq, at, label, tone, spanId: here() });
+    };
+    {
+        const kind = record.kind ?? "";
+        const payload = asRecord(record.payload);
+        const at = timeOf(record, payload);
+        const seq = record.sequence ?? 0;
+        state.lastAt = Math.max(state.lastAt, at);
+        if (frame !== undefined)
+            frame.endedAt = Math.max(frame.endedAt, at);
+        switch (kind) {
+            case "control.agent.turn-opened": {
+                frame = {
+                    id: `frame-${frames.length + 1}`,
+                    frame: frames.length + 1,
+                    seq,
+                    startedAt: at,
+                    endedAt: at,
+                    blocked: false,
+                    calls: []
+                };
+                frames.push(frame);
+                break;
+            }
+            case "control.agent.cell-call-started": {
+                const flowName = asString(payload.flowName) ?? "";
+                const metadata = callSemantics(flowName, payload);
+                const call = {
+                    flowName,
+                    callId: asString(payload.callId),
+                    input: payload.input,
+                    activity: metadata.activity,
+                    presentation: metadata.presentation,
+                    signature: `${flowName} ${textOf(payload.input) ?? ""}`
+                };
+                open.push(call);
+                // A call journaled outside a frame belongs to no frame, and the tree
+                // above puts it on the run. It is still open work, so it still pairs.
+                frame?.calls.push(call);
+                break;
+            }
+            case "control.agent.cell-call-settled": {
+                if (payload.outcome !== "success" && payload.outcome !== "failure")
+                    break;
+                const index = openCallIndex(open, asString(payload.callId), asString(payload.flowName));
+                const call = index < 0 ? undefined : open.splice(index, 1)[0];
+                if (call === undefined)
+                    break;
+                const failed = asString(payload.outcome) === "failure";
+                // `ask` settles SUCCESSFULLY with the person's answer (`AgentSession`
+                // answers `{ answer, approved }`), so a refusal is a denial and not a
+                // failure. That is the call that settles with a denial.
+                const denied = !failed && asRecord(payload.value).approved === false;
+                call.settled = {
+                    failed,
+                    result: (failed ? textOf(payload.message) : textOf(payload.value)) ?? "",
+                    denied,
+                    value: payload.value
+                };
+                if (denied && frame !== undefined)
+                    frame.blocked = true;
+                // A write is the fastest thing a run does, so its band is always too
+                // narrow to carry a label, and its own marker is the only way to reach
+                // the moment that matters most.
+                if (!failed && !denied && call.activity === "writes") {
+                    // A pin is its label, so a pin with none is a marker nobody can read
+                    // and nobody can tell from the next one. The journal gave this call
+                    // no file; no file, no pin.
+                    const paths = [...new Set(writtenPaths(call.input))];
+                    const minted = frame?.wrote;
+                    if (minted !== undefined) {
+                        // A frame's writes are ONE moment. A frame that edits fifteen files
+                        // does it inside a second, so a pin per file is fifteen names
+                        // stacked over a point on the axis nobody can aim between. The pin
+                        // stays where the frame started writing, on the file it names, and
+                        // counts the rest; a file written twice is still one file.
+                        for (const path of paths)
+                            if (!minted.paths.includes(path))
+                                minted.paths.push(path);
+                        milestones[minted.milestone] = { ...milestones[minted.milestone], label: filesLabel(minted.paths) };
+                    }
+                    else if (paths.length > 0) {
+                        // A write journaled outside a frame has no frame to be counted
+                        // into, so it stays a moment of its own.
+                        if (frame !== undefined)
+                            frame.wrote = { milestone: milestones.length, paths };
+                        pin(seq, at, filesLabel(paths), "brand");
+                    }
+                }
+                break;
+            }
+            case "control.agent.mutation-observed": {
+                const mutated = payload.mutated === true;
+                if (frame !== undefined)
+                    frame.mutated = mutated;
+                if (frame !== undefined && payload.basis === "observed" && typeof payload.mutated === "boolean") {
+                    frame.observedMutation = payload.mutated;
+                }
+                // Written for every frame, so only a frame that changed something is
+                // worth a note. `basis` is the body because a `declared` answer is
+                // paperwork and an `observed` one is a fact about the tree, and a
+                // reader must not have to guess which one they are holding. `paths` is
+                // a COUNT of what the measurement covered, not the paths themselves,
+                // so it is not quotable evidence and is not quoted.
+                if (mutated) {
+                    note(seq, asString(payload.basis) === "observed" ? "good" : "warn", "changed", asString(payload.basis) ?? "", []);
+                }
+                break;
+            }
+            case "control.agent.permission-required": {
+                if (frame !== undefined)
+                    frame.blocked = true;
+                pin(seq, at, "permission", "warn");
+                break;
+            }
+            case "control.agent.suspended": {
+                if (frame !== undefined)
+                    frame.blocked = true;
+                break;
+            }
+            case "control.agent.checkpoint-minted": {
+                note(seq, "good", "checkpoint", asString(payload.ref) ?? "", []);
+                break;
+            }
+            case "control.agent.read-only-demanded": {
+                // The caps are this run's own armed numbers, read off the payload: a
+                // host overrides any of them, so a constant here would print a number
+                // the run never used.
+                const streak = asNumber(payload.streak);
+                const cap = asNumber(payload.cap);
+                const nextFrame = asNumber(payload.nextFrame);
+                const nextAction = asString(payload.nextAction);
+                note(seq, "warn", "read-only", bodyOf(streak === undefined || cap === undefined ? undefined : `${streak} of ${cap} frames changed nothing.`, nextFrame === undefined || nextAction === undefined ? undefined : `Frame ${nextFrame}: ${nextAction}.`), []);
+                pin(seq, at, "read-only", "warn");
+                break;
+            }
+            case "control.agent.repeat-demanded": {
+                const spent = asNumber(payload.frames);
+                const cap = asNumber(payload.cap);
+                const nextFrame = asNumber(payload.nextFrame);
+                note(seq, "warn", "repeat", bodyOf(spent === undefined || cap === undefined ? undefined : `${spent} of ${cap} frames repeated calls.`, nextFrame === undefined ? undefined : `Frame ${nextFrame}.`), []);
+                pin(seq, at, "repeat", "warn");
+                break;
+            }
+            case "control.agent.narrowed-demanded": {
+                const flow = asString(payload.flow);
+                const nextFrame = asNumber(payload.nextFrame);
+                note(seq, "bad", "narrowed", bodyOf(flow === undefined ? undefined : `${flow} ran narrower than the reading it stands in for.`, nextFrame === undefined ? undefined : `Frame ${nextFrame}.`), [clip(payload.broader), clip(payload.narrower)]);
+                pin(seq, at, "narrowed", "bad");
+                break;
+            }
+            case "control.agent.unmoved-demanded": {
+                const nextFrame = asNumber(payload.nextFrame);
+                // Both digests or neither: one alone cannot tell an unmoved tree from a
+                // measurement that never happened, and either may be the empty string.
+                const opened = clip(payload.openedDigest);
+                const current = clip(payload.currentDigest);
+                note(seq, "bad", "unmoved", bodyOf("The tree the run opened on is the tree it closed on.", nextFrame === undefined ? undefined : `Frame ${nextFrame}.`), opened === undefined || current === undefined ? [] : [opened, current]);
+                pin(seq, at, "unmoved", "bad");
+                break;
+            }
+            case "control.agent.unresolved-demanded": {
+                const flow = asString(payload.flow);
+                const nextFrame = asNumber(payload.nextFrame);
+                note(seq, "bad", "unresolved", bodyOf(flow === undefined ? undefined : `${flow} failed and was not answered.`, nextFrame === undefined ? undefined : `Frame ${nextFrame}.`), [clip(payload.failed), clip(payload.instead)]);
+                pin(seq, at, "unresolved", "bad");
+                break;
+            }
+            case "control.agent.claim-demanded": {
+                // Written on EVERY evaluation, and a reading that neither handed the
+                // completion back nor refused it cost the run nothing and changed
+                // nothing, so only those two are moments anyone would scrub to. A
+                // refusal is the larger of them: it ends the run and takes its answer.
+                if (payload.demanded !== true && payload.refused !== true)
+                    break;
+                const complete = asNumber(payload.complete);
+                const overclaims = asNumber(payload.overclaims);
+                const nextFrame = asNumber(payload.nextFrame);
+                note(seq, "bad", payload.refused === true ? "claim refused" : "claim", bodyOf(complete === undefined || overclaims === undefined
+                    ? undefined
+                    : `complete ${complete}, overclaims ${overclaims}.`, nextFrame === undefined ? undefined : `Frame ${nextFrame}.`), []);
+                pin(seq, at, payload.refused === true ? "claim refused" : "claim", "bad");
+                break;
+            }
+            /*
+             * The five kinds `AgentSession`'s `default` arm once journaled with
+             * `payload: {}`, however rich their `AgentEvent` schema was:
+             * cell-rejected-in-frame, read-only-demand-issued,
+             * narrow-only-demanded, steering-drained and sufficiency-observed.
+             * Their whole payload is late (`AgentSession` `lateFields`), so one
+             * record carries every field or none, and each arm below reads what its
+             * record has: a legacy record still folds, and still says nothing the
+             * record does not carry. A note with no body and no evidence is a title
+             * on its own, so a fieldless record writes none.
+             */
+            case "control.agent.cell-rejected-in-frame": {
+                // A refused reply is a model call the frame paid for. The code is why
+                // the parse refused it; the message is what the frame said back.
+                const attempt = asNumber(payload.attempt);
+                const code = asString(payload.code);
+                const body = bodyOf(code === undefined ? undefined : `${code}.`, attempt === undefined ? undefined : `Attempt ${attempt}.`);
+                if (body !== "")
+                    note(seq, "warn", "rejected", body, [clip(payload.message)]);
+                break;
+            }
+            case "control.agent.read-only-demand-issued": {
+                // The issuance's own numbers. `read-only-demanded` above carries the
+                // same demand's later answer, and a run that crashes between the two
+                // boundaries still has this one.
+                const streak = asNumber(payload.streak);
+                const cap = asNumber(payload.cap);
+                const nextFrame = asNumber(payload.nextFrame);
+                const body = bodyOf(streak === undefined || cap === undefined ? undefined : `${streak} of ${cap} frames changed nothing.`, nextFrame === undefined ? undefined : `Frame ${nextFrame}.`);
+                if (body !== "")
+                    note(seq, "warn", "read-only", body, []);
+                pin(seq, at, "read-only", "warn");
+                break;
+            }
+            case "control.agent.narrow-only-demanded": {
+                // The sibling of `narrowed-demanded`: that one fires when a broader
+                // reading exists and was not re-run, this one when none was ever
+                // taken. There is no broader input to quote, so the subjects the
+                // demand is about stand in its place.
+                const flow = asString(payload.flow);
+                const targets = Array.isArray(payload.targets)
+                    ? payload.targets.filter((one) => typeof one === "string")
+                    : [];
+                const nextFrame = asNumber(payload.nextFrame);
+                const body = bodyOf(flow === undefined || targets.length === 0
+                    ? undefined
+                    : `${flow} ran on ${targets.join(", ")} and nothing broader.`, nextFrame === undefined ? undefined : `Frame ${nextFrame}.`);
+                if (body !== "")
+                    note(seq, "warn", "narrow-only", body, [clip(payload.check)]);
+                pin(seq, at, "narrow-only", "warn");
+                break;
+            }
+            case "control.agent.steering-drained": {
+                // A drain is written at every frame boundary, and the queue is empty
+                // at almost all of them. Only messages ON the record establish that a
+                // person reached the run, so an empty drain is not a moment and a
+                // legacy record — which carries no messages either way — cannot be
+                // read as one. A steer too large to trace was still delivered; the
+                // record says so even where its words are gone.
+                const messages = Array.isArray(payload.messages) ? payload.messages : [];
+                if (messages.length === 0)
+                    break;
+                note(seq, "warn", "steering", messages.length === 1 ? "1 steer." : `${messages.length} steers.`, messages.map((message) => clip(asRecord(message).text)));
+                pin(seq, at, "steering", "warn");
+                break;
+            }
+            case "control.agent.sufficiency-observed": {
+                // The one observation that rewards a run rather than braking it: a
+                // failing check answered by a passing one. The two inputs are the
+                // whole of it, so they are quoted.
+                const flow = asString(payload.flow);
+                const nextFrame = asNumber(payload.nextFrame);
+                const body = bodyOf(flow === undefined ? undefined : `${flow} failed before the change and passed after it.`, nextFrame === undefined ? undefined : `Frame ${nextFrame}.`);
+                if (body !== "")
+                    note(seq, "good", "sufficiency", body, [clip(payload.failed), clip(payload.passed)]);
+                pin(seq, at, "sufficiency", "good");
+                break;
+            }
+            case "control.run.completed":
+            case "control.run.failed":
+            case "control.run.cancelled": {
+                const verdict = kind.slice("control.run.".length);
+                // A person's stop reads as the product word every surface uses, and
+                // is never drawn as a failure.
+                if (verdict === "cancelled")
+                    pin(seq, at, "stopped", "muted");
+                else
+                    pin(seq, at, verdict, verdict === "completed" ? "good" : "bad");
+                break;
+            }
+            default:
+                break;
+        }
+        // After the record's own arm, so a turn-opened belongs to the frame it
+        // opened: the rule `here()` already gives a note and a pin.
+        owners.push({ seq, spanId: here() });
+    }
+    state.frame = frame;
+};
+/**
+ * What {@link disciplineStep} has read so far, as the model's arrays.
+ *
+ * The derived rows are rebuilt from the frames; the recorded ones are copied,
+ * so a model taken now never sees a record stepped after it.
+ */
+const disciplineModel = (state) => {
+    const { frames, lastAt } = state;
+    const notes = state.notes.slice();
+    const milestones = state.milestones.slice();
+    const owners = state.owners.slice();
+    // A measured unchanged tree is authoritative even when a write succeeded.
+    const changed = frames.map((entry) => entry.observedMutation ?? (entry.mutated === true || madeAWrite(entry)));
+    // A repeated call is only evidence of a stall inside a STREAK, and only
+    // across a span the workspace never moved in.
+    //
+    // Re-running one check after an edit is the OPPOSITE of a stall: it is the
+    // answer `control.agent.sufficiency-observed` rewards. A rule that flagged
+    // any second occurrence of a call would mark that good frame and a looping
+    // one identically, and a rule that only checked THIS frame for a change
+    // would still flag it, because the edit it answers happened in the frame
+    // before. So a change resets what a first occurrence is: a call is judged
+    // against the last time it ran on THIS tree, never against a run from before
+    // an edit landed. On top of that a repeat counts only where the frames beside
+    // it repeat too — each of them recording no change of its own — and
+    // `repeatOf` is set only inside a streak of two or more such frames. Every
+    // substantive call must repeat a settled reading; a fresh call, new result,
+    // or pending result means this frame has not been shown to be redundant.
+    const firstSeen = new Map();
+    const repeatedFrom = new Map();
+    const redundant = [];
+    frames.forEach((entry, index) => {
+        const calls = entry.calls.filter((call) => call.flowName !== CHECKPOINT_FLOW);
+        for (const call of calls) {
+            if (call.settled === undefined)
+                continue;
+            // A call settles once, so its reading is built once, not per model taken.
+            call.reading ??= `${call.signature} ${JSON.stringify(call.settled)}`;
+            const reading = call.reading;
+            const seen = firstSeen.get(reading);
+            if (seen === undefined)
+                firstSeen.set(reading, entry.frame);
+            else if (seen < entry.frame)
+                repeatedFrom.set(call, seen);
+        }
+        redundant.push(calls.length > 0 && calls.every((call) => repeatedFrom.has(call)));
+        // The tree moved in this frame, so every call recorded before it ran
+        // against a tree that no longer exists and none of them can be repeated.
+        if (changed[index] === true)
+            firstSeen.clear();
+    });
+    const stalling = frames.map((_frame, index) => redundant[index] === true && changed[index] !== true);
+    const stuck = stalling.map((flag, index) => flag && (stalling[index - 1] === true || stalling[index + 1] === true));
+    // Phase, most specific rule first. The last rule is the honesty one: every
+    // other word is a claim about what the frame was doing, and `researching` is
+    // as much of a claim as the rest. A frame this fold cannot name one call for
+    // is a frame it declines to write a line about, so it declines to name a
+    // phase for it too.
+    const phases = frames.map((entry, index) => entry.blocked
+        ? "blocked"
+        : stuck[index] === true
+            ? "stuck"
+            : changed[index] === true || entry.calls.some((call) => call.activity === "writes")
+                ? "implementing"
+                : entry.calls.some((call) => call.activity === "checks" || call.activity === "tests")
+                    ? "testing"
+                    : entry.calls.some((call) => call.activity === "reads")
+                        ? "researching"
+                        : "unrecorded");
+    const bands = [];
+    frames.forEach((entry, index) => {
+        const phase = phases[index];
+        // A frame's band ends where the next frame opens, and the last one ends
+        // where the journal does: the rule the tree's own frames close by.
+        const endedAt = frames[index + 1]?.startedAt ?? Math.max(entry.endedAt, lastAt);
+        const last = bands[bands.length - 1];
+        if (last !== undefined && last.phase === phase) {
+            bands[bands.length - 1] = { ...last, endedAt, frames: [...last.frames, entry.id] };
+            return;
+        }
+        bands.push({ phase, startedAt: entry.startedAt, endedAt, frames: [entry.id], seq: entry.seq });
+    });
+    const lines = frames.flatMap((entry, index) => {
+        const call = dominantCall(entry);
+        // A frame that called nothing has no line. Absence is absence.
+        if (call === undefined)
+            return [];
+        const repeatOf = stuck[index] === true ? repeatedFrom.get(call) : undefined;
+        const held = state.lineOf.get(entry);
+        if (held !== undefined && held.call === call && held.settled === call.settled && held.repeatOf === repeatOf) {
+            return [held.line];
+        }
+        const outcome = call.settled === undefined
+            ? "pending"
+            : call.settled.failed || call.settled.denied
+                ? "failure"
+                : "success";
+        const line = {
+            spanId: entry.id,
+            frame: entry.frame,
+            verb: call.presentation?.verb[outcome] ??
+                `${call.flowName}${outcome === "pending" ? " pending" : outcome === "failure" ? " failed" : ""}`,
+            subject: callSubject(call.input, call.presentation?.subject),
+            // Read supported output fields through the descriptor's presentation.
+            // The selected call retains the raw value, including unsupported shapes.
+            result: call.settled?.failed === true
+                ? clip(call.settled.result) ?? ""
+                : resultOf(call.settled?.value, call.presentation?.result),
+            failed: call.settled?.failed === true,
+            wrote: call.activity === "writes" && call.settled?.failed === false && !call.settled.denied,
+            ...(repeatOf === undefined ? {} : { repeatOf })
+        };
+        state.lineOf.set(entry, { call, settled: call.settled, repeatOf, line });
+        return [line];
+    });
+    return { bands, milestones, lines, notes, owners };
+};
+const isEngineRow = (record) => record.kind === "control.engine.event" || record.kind === "control.engine.projection-gap";
+const foldInit = (run) => ({
+    run,
+    root: builder(`run:${run.runId}`, "run", `run ${run.runId} · ${run.flowId}`, "running", 0, {
+        ...(run.kind === undefined ? {} : { fields: { kind: run.kind } })
+    }),
+    frame: undefined,
+    cell: undefined,
+    frames: 0,
+    calls: 0,
+    seat: undefined,
+    lastAt: 0,
+    count: 0,
+    verdict: undefined,
+    openCalls: [],
+    approvals: new Map(),
+    discipline: disciplineInit(run.runId),
+    engine: [],
+    engineTrace: undefined,
+    frozen: new WeakMap(),
+    dirty: new Set(),
+    topOf: new WeakMap()
+});
+/**
+ * Folds one record, in sequence order, into a dispatch's trace.
+ *
+ * Frames open on `turn-opened` and close when the next opens or the run ends;
+ * cells open on `cell-produced` and close on `cell-settled`; calls open on
+ * `cell-call-started` under the open cell (or the frame, when a call is
+ * journaled outside a cell) and settle by stable call identity the way the gateway's own
+ * `run-tree` pairs them, so a call's `call-N` id is the node id the
+ * `node-output` projection knows it by. A journal with no records yields the
+ * run root alone, wearing the run's status: the honest empty trace.
+ *
+ * The same records fold a second time, into what a person would say the run
+ * was doing: see {@link disciplineStep}.
+ */
+const foldStep = (state, record) => {
+    if (isEngineRow(record)) {
+        state.engine.push(record);
+        state.engineTrace = undefined;
+    }
+    // route receives only the records kept by the shared call-event filter.
+    const { root, openCalls, approvals, dirty, topOf } = state;
+    let { frame, cell, frames, calls, seat } = state;
+    const top = frame ?? cell;
+    if (top !== undefined)
+        dirty.add(top);
+    /** Marks the run's child that `span` sits under as changed. */
+    const touch = (span) => {
+        // Both callers retrieve spans registered in topOf when they were opened.
+        dirty.add(topOf.get(span));
+    };
+    /** Where a new span attaches: the open cell, else the open frame, else the run. */
+    const parent = () => cell ?? frame ?? root;
+    const closeCell = (at, status) => {
+        if (cell === undefined)
+            return;
+        cell.endedAt = at;
+        cell.status = status;
+        cell = undefined;
+    };
+    const closeFrame = (at) => {
+        if (frame === undefined)
+            return;
+        closeCell(at, cell?.children.some((child) => child.status === "failed") === true ? "failed" : "completed");
+        frame.endedAt = at;
+        frame.status = frame.children.some((child) => child.status === "failed") ? "failed" : "completed";
+        frame = undefined;
+    };
+    {
+        const kind = record.kind ?? "";
+        const payload = asRecord(record.payload);
+        const at = timeOf(record, payload);
+        if (state.count === 0) {
+            root.startedAt = at;
+            state.lastAt = at;
+        }
+        else
+            state.lastAt = Math.max(state.lastAt, at);
+        state.count += 1;
+        const opened = { sequence: record.sequence, event: kind };
+        switch (kind) {
+            case "control.engine.event":
+            case "control.engine.projection-gap":
+            case "control.engine.projection-started":
+            case "control.engine.projection-settled":
+                // Native records have their own identities and lifecycle. Never put
+                // them under whichever agent frame happened to be open at ingestion.
+                break;
+            case "control.agent.turn-opened": {
+                closeFrame(at);
+                frames += 1;
+                seat = asString(payload.seat) ?? seat;
+                frame = builder(`frame-${frames}`, "frame", `frame ${frames}${seat === undefined ? "" : ` · ${seat}`}`, "running", at, {
+                    ...opened,
+                    ...(seat === undefined ? {} : { seat }),
+                    fields: restOf(payload, ["seat"])
+                });
+                root.children.push(frame);
+                break;
+            }
+            case "control.agent.model-settled": {
+                const usage = asRecord(payload.usage);
+                const duration = asNumber(payload.durationMillis);
+                const span = builder(`model-${record.sequence ?? at}`, "model", "model", "completed", duration === undefined ? at : at - duration, {
+                    ...opened,
+                    ...(seat === undefined ? {} : { seat }),
+                    output: textOf(payload.text),
+                    usage: { inputTokens: asNumber(usage.inputTokens), outputTokens: asNumber(usage.outputTokens) },
+                    fields: restOf(payload, ["text", "usage", "durationMillis"])
+                });
+                span.endedAt = at;
+                (frame ?? root).children.push(span);
+                break;
+            }
+            case "control.agent.cell-produced": {
+                closeCell(at, "completed");
+                const language = asString(payload.language);
+                cell = builder(`cell-${record.sequence ?? at}`, "cell", `cell${language === undefined ? "" : ` · ${language}`}`, "running", at, {
+                    ...opened,
+                    source: asString(payload.text),
+                    fields: restOf(payload, ["text", "language"])
+                });
+                (frame ?? root).children.push(cell);
+                break;
+            }
+            case "control.agent.cell-call-started": {
+                calls += 1;
+                const recordedName = asString(payload.flowName);
+                const flowName = recordedName ?? `call-${calls}`;
+                const span = builder(`call-${calls}`, "call", inspectLabel(flowName), "running", at, {
+                    ...opened,
+                    ...(recordedName === undefined ? {} : { flowName: recordedName }),
+                    input: payload.input,
+                    fields: restOf(payload, ["flowName", "input"])
+                });
+                openCalls.push({ flowName, callId: asString(payload.callId), span });
+                topOf.set(span, frame ?? cell ?? span);
+                parent().children.push(span);
+                break;
+            }
+            case "control.agent.cell-call-settled": {
+                const index = openCallIndex(openCalls, asString(payload.callId), asString(payload.flowName));
+                const settled = index < 0 ? undefined : openCalls.splice(index, 1)[0];
+                if (settled === undefined)
+                    break;
+                const failed = asString(payload.outcome) === "failure";
+                touch(settled.span);
+                settled.span.endedAt = at;
+                settled.span.status = failed ? "failed" : "completed";
+                settled.span.detail = {
+                    ...settled.span.detail,
+                    ...(failed ? { message: textOf(payload.message) } : { output: textOf(payload.value) }),
+                    ...(!failed && settled.flowName === "agent/spawn" && asString(asRecord(payload.value).child) !== undefined
+                        ? { childRunId: asString(asRecord(payload.value).child) }
+                        : {})
+                };
+                break;
+            }
+            case "control.agent.cell-printed": {
+                if (cell === undefined) {
+                    parent().children.push(builder(`printed-${record.sequence ?? at}`, "event", "printed", "completed", at, {
+                        ...opened,
+                        printed: textOf(payload.text)
+                    }));
+                    break;
+                }
+                cell.detail = {
+                    ...cell.detail,
+                    printed: [cell.detail.printed, textOf(payload.text)].filter((text) => text !== undefined).join("\n")
+                };
+                break;
+            }
+            case "control.agent.cell-settled": {
+                closeCell(at, asString(payload.outcome) === "failure" ? "failed" : "completed");
+                break;
+            }
+            case "control.agent.resolved": {
+                const span = builder(`resolved-${record.sequence ?? at}`, "resolved", "resolved", "completed", at, {
+                    ...opened,
+                    output: textOf(payload.text)
+                });
+                span.endedAt = at;
+                (frame ?? root).children.push(span);
+                break;
+            }
+            case "control.approval.requested": {
+                const requestId = asString(payload.requestId) ?? `approval-${record.sequence ?? at}`;
+                const question = asString(payload.question);
+                const span = builder(`approval-${requestId}`, "approval", `approval${question === undefined ? "" : ` · ${question}`}`, "waiting", at, {
+                    ...opened,
+                    fields: restOf(payload, ["question", "requestId", "payload", "runId"])
+                });
+                approvals.set(requestId, span);
+                topOf.set(span, frame ?? span);
+                (frame ?? root).children.push(span);
+                break;
+            }
+            case "control.approval.approved":
+            case "control.approval.denied": {
+                const decided = kind === "control.approval.approved" ? "approved" : "denied";
+                const key = asString(payload.tokenId) ?? asString(payload.requestId);
+                const span = key === undefined
+                    ? [...approvals.values()].find((entry) => entry.status === "waiting")
+                    : approvals.get(key);
+                if (span === undefined)
+                    break;
+                touch(span);
+                span.status = decided;
+                span.endedAt = at;
+                break;
+            }
+            case "control.run.completed":
+            case "control.run.failed":
+            case "control.run.cancelled": {
+                closeFrame(at);
+                root.endedAt = at;
+                // The journal's own verdict outranks the card's phase word: a scrub to this record shows the run settled.
+                state.verdict = kind.slice("control.run.".length);
+                break;
+            }
+            default: {
+                if (!kind.startsWith("control."))
+                    break;
+                const span = builder(`event-${record.sequence ?? at}`, "event", kind.slice("control.".length), "completed", at, {
+                    ...opened,
+                    fields: restOf(payload, [])
+                });
+                span.endedAt = at;
+                parent().children.push(span);
+                if (kind === "control.agent.turn-closed" && payload.step !== undefined) {
+                    const closed = frame;
+                    closeFrame(at);
+                    if (closed !== undefined && payload.outcome === "suspended")
+                        closed.status = "waiting";
+                    if (closed !== undefined && payload.outcome === "aborted")
+                        closed.status = "cancelled";
+                }
+            }
+        }
+    }
+    Object.assign(state, { frame, cell, frames, calls, seat });
+    const after = frame ?? cell;
+    if (after !== undefined)
+        dirty.add(after);
+    disciplineStep(state.discipline, record);
+};
+/**
+ * The trace {@link foldStep} has read so far, as the run with `status` would
+ * show it.
+ *
+ * Nothing live is mutated. A settled run closes its open frame where the
+ * journal ends, so that close is applied to the frozen copy only.
+ */
+const foldModel = (state, status, journal, engine) => {
+    const { root, frame, cell, lastAt } = state;
+    const closed = new Map();
+    const statusOf = (node) => closed.get(node)?.status ?? node.status;
+    // A settled run leaves no frame open: the last frame ends where the journal does.
+    const terminal = TERMINAL_RUN.has(status);
+    if (terminal && frame !== undefined) {
+        if (cell !== undefined) {
+            closed.set(cell, {
+                status: cell.children.some((child) => child.status === "failed") ? "failed" : "completed",
+                endedAt: lastAt
+            });
+        }
+        closed.set(frame, {
+            status: frame.children.some((child) => statusOf(child) === "failed") ? "failed" : "completed",
+            endedAt: lastAt
+        });
+    }
+    if (engine === undefined && state.engineTrace === undefined)
+        state.engineTrace = engineTraceFromJournal(state.engine);
+    const children = [...root.children, ...(engine ?? state.engineTrace)];
+    closed.set(root, {
+        status: state.verdict ?? status,
+        endedAt: root.endedAt ?? (terminal && state.count > 0 ? lastAt : Number.NaN)
+    });
+    const freeze = (node, depth, members) => freezeWith(node, depth, members.map((child) => freeze(child, depth + 1, child.children)));
+    const freezeWith = (node, depth, frozenChildren) => {
+        const override = closed.get(node);
+        const nodeStatus = override?.status ?? node.status;
+        const endedAt = override === undefined || Number.isNaN(override.endedAt) ? node.endedAt : override.endedAt;
+        const held = state.frozen.get(node);
+        if (held !== undefined && held.depth === depth && held.label === node.label && held.status === nodeStatus &&
+            held.startedAt === node.startedAt && held.endedAt === endedAt && held.detail === node.detail &&
+            held.children.length === frozenChildren.length &&
+            held.children.every((child, index) => child === frozenChildren[index]))
+            return held;
+        const span = {
+            id: node.id,
+            kind: node.kind,
+            label: node.label,
+            status: nodeStatus,
+            startedAt: node.startedAt,
+            ...(endedAt === undefined ? {} : { endedAt }),
+            depth,
+            children: frozenChildren,
+            detail: node.detail
+        };
+        state.frozen.set(node, span);
+        return span;
+    };
+    // A child no step touched since the last model is a closed subtree: its
+    // frozen span stands, and nothing under it is walked again.
+    const settledChild = (child) => {
+        if (state.dirty.has(child) || closed.has(child))
+            return undefined;
+        const held = state.frozen.get(child);
+        return held?.depth === 1 ? held : undefined;
+    };
+    const frozenChildren = children.map((child) => settledChild(child) ?? freeze(child, 1, child.children));
+    state.dirty.clear();
+    const frozenRoot = freezeWith(root, 0, frozenChildren);
+    const rows = [];
+    const walk = (span) => {
+        rows.push(span);
+        for (const child of span.children)
+            walk(child);
+    };
+    walk(frozenRoot);
+    let start = Number.POSITIVE_INFINITY;
+    let end = 0;
+    let running = 0;
+    let failed = 0;
+    for (const span of rows) {
+        start = Math.min(start, span.startedAt);
+        end = Math.max(end, span.endedAt ?? span.startedAt);
+        if (span.kind !== "run" && span.status === "running")
+            running += 1;
+        if (span.kind !== "run" && span.status === "failed")
+            failed += 1;
+    }
+    const extent = state.count === 0 || !Number.isFinite(start)
+        ? { start: 0, end: 0 }
+        : { start, end: Math.max(end, start) };
+    return {
+        journal,
+        root: frozenRoot,
+        rows,
+        extent,
+        counts: { spans: rows.length - 1, running, failed },
+        ...disciplineModel(state.discipline)
+    };
+};
+const sequenceOf = (record) => record.sequence ?? 0;
+const TERMINAL_KINDS = new Set([
+    "control.run.completed",
+    "control.run.failed",
+    "control.run.cancelled"
+]);
+/** One deduplicated record to the fold of the dispatch it was recorded under. */
+const route = (state, record) => {
+    // A run verdict stamped with another run's id (a child's, riding in this
+    // journal) must not settle this run's trace or pin its milestone.
+    if (record.kind?.startsWith("control.run.") === true && record.runId !== undefined && record.runId !== state.run.runId) {
+        return;
+    }
+    state.firstAt = Math.min(state.firstAt, timeOf(record, asRecord(record.payload)));
+    if (TERMINAL_KINDS.has(record.kind ?? ""))
+        state.terminal = record;
+    const scope = callScope(record);
+    if (scope === undefined)
+        return foldStep(state.base, record);
+    let group = state.groups.get(scope);
+    if (group === undefined) {
+        group = foldInit(state.run);
+        state.groups.set(scope, group);
+    }
+    foldStep(group, record);
+};
+/** Refolds `arrived` from nothing: the batch rules, exactly. */
+const reseed = (state, arrived) => {
+    const journal = [...arrived].sort((left, right) => sequenceOf(left) - sequenceOf(right));
+    const filter = callEventFilter();
+    for (const record of journal)
+        filter.push(record);
+    Object.assign(state, {
+        arrived,
+        journal,
+        filter,
+        base: foldInit(state.run),
+        groups: new Map(),
+        engine: journal.filter(isEngineRow),
+        engineTrace: undefined,
+        firstAt: Number.POSITIVE_INFINITY,
+        terminal: undefined,
+        memo: undefined
+    });
+    for (const record of uniqueCallEvents(journal))
+        route(state, record);
+};
+/**
+ * Folds `records` into a fold that later records can be stepped onto.
+ *
+ * @param run the run the journal belongs to
+ * @param records its journal so far, in any order
+ *
+ * @category constructors
+ * @since 1.0.0
+ */
+export const traceFold = (run, records = []) => {
+    const state = {
+        run: { runId: run.runId, flowId: run.flowId, ...(run.kind === undefined ? {} : { kind: run.kind }) }
+    };
+    state.source = undefined;
+    reseed(state, [...records]);
+    return state;
+};
+/**
+ * Folds one more record onto `fold`, which it returns.
+ *
+ * A record in sequence order costs its own work. One that arrives before a
+ * sequence already stepped, or a native fact that supersedes telemetry the
+ * fold already placed, refolds the journal, because the batch rules move an
+ * earlier record for both.
+ *
+ * @param fold the fold; consumed
+ * @param record the next journal record
+ *
+ * @category combinators
+ * @since 1.0.0
+ */
+export const traceFoldStep = (fold, record) => {
+    const state = fold;
+    state.memo = undefined;
+    state.arrived.push(record);
+    const last = state.journal.at(-1);
+    if (last !== undefined && !(sequenceOf(record) >= sequenceOf(last))) {
+        reseed(state, state.arrived);
+        return fold;
+    }
+    state.journal.push(record);
+    if (isEngineRow(record)) {
+        state.engine.push(record);
+        state.engineTrace = undefined;
+    }
+    const verdict = state.filter.push(record);
+    if (verdict._tag === "rewrite")
+        reseed(state, state.arrived);
+    else if (verdict._tag === "keep")
+        route(state, verdict.event);
+    return fold;
+};
+/**
+ * Brings `fold` up to `records`, stepping only what it has not read.
+ *
+ * `records` extends the array the fold last read when every earlier element is
+ * the same object; anything else, or a different run, starts a new fold. The
+ * comparison is against the records the fold consumed, not the caller's array,
+ * so growing or rewriting that same array in place is seen. A reader that
+ * re-renders one growing journal therefore pays per new record.
+ *
+ * @param fold the fold the reader holds, if any; consumed
+ * @param run the run the journal belongs to
+ * @param records the whole journal as the reader now holds it
+ *
+ * @category combinators
+ * @since 1.0.0
+ */
+export const traceFoldSync = (fold, run, records) => {
+    const held = fold;
+    const source = held?.source;
+    const extends_ = held !== undefined && source !== undefined && held.run.runId === run.runId &&
+        held.run.flowId === run.flowId && held.run.kind === run.kind && records.length >= source.length &&
+        source.every((record, index) => records[index] === record);
+    const next = extends_ ? held : traceFold(run);
+    for (let index = extends_ ? source.length : 0; index < records.length; index++)
+        traceFoldStep(next, records[index]);
+    next.source = records.slice();
+    return next;
+};
+/**
+ * The trace a fold has read, as the run with `status` shows it.
+ *
+ * Taken again without a step between, it is the same object.
+ *
+ * @param fold the fold
+ * @param status the run card's phase word
+ *
+ * @category utilities
+ * @since 1.0.0
+ */
+export const traceFoldModel = (fold, status) => {
+    const state = fold;
+    if (state.memo?.status === status)
+        return state.memo.model;
+    const model = mergeModel(state, status);
+    state.memo = { status, model };
+    return model;
+};
+const mergeModel = (state, status) => {
+    const journal = state.journal.slice();
+    if (state.groups.size === 0) {
+        if (state.engineTrace === undefined)
+            state.engineTrace = engineTraceFromJournal(state.engine);
+        return foldModel(state.base, status, journal, state.engineTrace);
+    }
+    const base = foldModel(state.base, status, journal);
+    const children = [...base.root.children];
+    const bands = [...base.bands];
+    const milestones = [...base.milestones];
+    const lines = [...base.lines];
+    const notes = [...base.notes];
+    const owners = [...base.owners];
+    const terminal = state.terminal;
+    const terminalAt = terminal === undefined ? undefined : timeOf(terminal, asRecord(terminal.payload));
+    for (const [scope, group] of state.groups) {
+        const prefix = `step:${encodeURIComponent(scope)}/`;
+        const scoped = foldModel(group, "running", journal);
+        const rename = (span) => ({
+            ...span,
+            id: `${prefix}${span.id}`,
+            children: span.children.map(rename),
+            ...(span.status === "running" && TERMINAL_RUN.has(base.root.status) ?
+                {
+                    // A terminal run proves work stopped. It does not prove which open
+                    // step succeeded or caused the run to fail.
+                    status: "stopped",
+                    ...(terminalAt === undefined ? {} : { endedAt: terminalAt })
+                } :
+                {})
+        });
+        children.push(...scoped.root.children.map(rename));
+        bands.push(...scoped.bands.map((band) => ({ ...band, frames: band.frames.map((id) => `${prefix}${id}`) })));
+        // A moment, a line, a note and a position all name the frame they were
+        // recorded under, so the merge renames each of them the same way: the
+        // step's own frame, or this run's root for what the step recorded outside
+        // any frame.
+        const owned = (spanId) => spanId === scoped.root.id ? base.root.id : `${prefix}${spanId}`;
+        milestones.push(...scoped.milestones.map((one) => ({ ...one, spanId: owned(one.spanId) })));
+        lines.push(...scoped.lines.map((line) => ({ ...line, spanId: `${prefix}${line.spanId}` })));
+        notes.push(...scoped.notes.map((note) => ({ ...note, spanId: owned(note.spanId) })));
+        owners.push(...scoped.owners.map((one) => ({ ...one, spanId: owned(one.spanId) })));
+    }
+    children.sort((left, right) => left.startedAt - right.startedAt || (left.detail.sequence ?? 0) - (right.detail.sequence ?? 0));
+    const root = { ...base.root, startedAt: state.firstAt, children };
+    const rows = [];
+    const walk = (span) => {
+        rows.push(span);
+        span.children.forEach(walk);
+    };
+    walk(root);
+    const positions = new Map(rows.map((span, index) => [span.id, index]));
+    // Each step folds its own frames from 1, so a merged run would print two
+    // rows numbered 1 and a `same as 1` that names either. The merged list
+    // numbers the rows a person reads, and a repeat names the renumbered row of
+    // the step that recorded it.
+    const merged = lines.sort((left, right) => positions.get(left.spanId) - positions.get(right.spanId));
+    const stepOf = (spanId) => spanId.slice(0, spanId.lastIndexOf("/") + 1);
+    const renumbered = new Map(merged.map((line, index) => [`${stepOf(line.spanId)}${line.frame}`, index + 1]));
+    let start = Number.POSITIVE_INFINITY;
+    let end = Number.NEGATIVE_INFINITY;
+    for (const span of rows) {
+        start = Math.min(start, span.startedAt);
+        end = Math.max(end, span.endedAt ?? span.startedAt);
+    }
+    return {
+        journal,
+        root,
+        rows,
+        extent: { start, end },
+        counts: {
+            spans: rows.length - 1,
+            running: rows.filter((span) => span.kind !== "run" && span.status === "running").length,
+            failed: rows.filter((span) => span.kind !== "run" && span.status === "failed").length
+        },
+        bands: bands.sort((left, right) => left.startedAt - right.startedAt || left.seq - right.seq),
+        milestones: milestones.sort((left, right) => left.seq - right.seq),
+        lines: merged.map((line, index) => ({
+            ...line,
+            frame: index + 1,
+            ...(line.repeatOf === undefined
+                ? {}
+                : { repeatOf: renumbered.get(`${stepOf(line.spanId)}${line.repeatOf}`) })
+        })),
+        notes: notes.sort((left, right) => left.seq - right.seq),
+        owners: owners.sort((left, right) => left.seq - right.seq)
+    };
+};
+/**
+ * Fold each recorded dispatch independently, keeping prompt-run addresses unchanged.
+ *
+ * The same fold a live reader advances with {@link traceFoldStep}, taken over
+ * the whole journal at once.
+ *
+ * The options the card carries are accepted and read by nothing: a plan's
+ * check targets are a coverage requirement, and a requirement is not evidence
+ * that any call ran it. Every word this fold says is read off a record.
+ *
+ * @category utilities
+ * @since 1.0.0
+ */
+export const traceFromJournal = (run, records, _options = {}) => traceFoldModel(traceFold(run, records), run.status);
+/**
+ * One span's bar on the shared axis, as percentages. An open span runs to the
+ * axis end; an instant span is zero width and renders as a marker.
+ *
+ * @param span the span
+ * @param extent the axis
+ *
+ * @category utilities
+ * @since 1.0.0
+ */
+export const waterfallGeometry = (span, extent) => {
+    const width = Math.max(extent.end - extent.start, 1);
+    const from = span.startedAt;
+    const to = span.endedAt ?? extent.end;
+    const left = ((from - extent.start) / width) * 100;
+    const bar = Math.max(((to - from) / width) * 100, 0);
+    return { left: Math.round(left * 100) / 100, width: Math.round(bar * 100) / 100 };
+};
+/**
+ * The axis the phase strip measures on: the bands' own span when the journal
+ * opened frames, the run's whole extent when it opened none.
+ *
+ * A milestone is a journal record, and the records that write one do not need a
+ * frame: a journal of `read-only-demanded` and `sufficiency-observed` with no
+ * `turn-opened` carries two moments and opens no band. Milestones therefore
+ * survive without bands, and the axis that places them cannot be read off the
+ * bands alone. The other choice — dropping a moment because no band was drawn
+ * beside it — would be this fold deciding a record the journal made did not
+ * happen, which is the one thing it may never do.
+ *
+ * @param model the trace
+ *
+ * @category utilities
+ * @since 1.0.0
+ */
+export const phaseExtent = (model) => {
+    return model.bands.length === 0 ? model.extent : {
+        start: Math.min(...model.bands.map((band) => band.startedAt)),
+        end: Math.max(...model.bands.map((band) => band.endedAt))
+    };
+};
+/**
+ * One band's share of that axis, as percentages, the way the waterfall measures
+ * a span.
+ *
+ * A run whose frames all land in one millisecond recorded no elapsed time. Read
+ * against a floored axis every such band is zero wide at left 0, so the whole
+ * strip collapses onto the left edge and says nothing at all. The bands' ORDER
+ * is a journal fact even where their durations are not, so with no duration to
+ * measure the ordinal IS the axis: equal slices, left to right.
+ *
+ * @param band the band
+ * @param extent the axis, from {@link phaseExtent}
+ * @param index the band's place in the strip
+ * @param count how many bands the strip holds
+ *
+ * @category utilities
+ * @since 1.0.0
+ */
+export const phaseBandGeometry = (band, extent, index, count) => {
+    const round = (value) => Math.round(value * 100) / 100;
+    const axis = extent.end - extent.start;
+    if (axis <= 0) {
+        const share = 100 / Math.max(count, 1);
+        return { left: round(index * share), width: round(share) };
+    }
+    return {
+        left: round(((band.startedAt - extent.start) / axis) * 100),
+        width: round((Math.max(band.endedAt - band.startedAt, 0) / axis) * 100)
+    };
+};
+/** The flows whose spans are messages between a coordinator and its workers (spec 06 §3). */
+const MESSAGE_FLOWS = new Set(["agent/send", "agent/await"]);
+/** Whether a span, or any span under it, passes the filter.
+ *
+ * @category utilities
+ * @since 1.0.0
+ */
+export const spanMatches = (span, filter) => {
+    const own = filter === "all"
+        ? true
+        : filter === "running"
+            ? span.status === "running" || span.status === "waiting"
+            : filter === "failed"
+                ? span.status === "failed"
+                : filter === "model"
+                    ? span.kind === "model"
+                    : filter === "flow"
+                        ? span.kind === "call" || span.kind === "execution" || span.kind === "attempt"
+                        : span.kind === "call" && MESSAGE_FLOWS.has(span.label);
+    return own || span.children.some((child) => spanMatches(child, filter));
+};
+/**
+ * Stable filter identifiers accepted by run trace commands.
+ *
+ * @category utilities
+ * @since 1.0.0
+ */
+export const TRACE_FILTER_IDS = [
+    "all",
+    "running",
+    "failed",
+    "model",
+    "flow",
+    "messages"
+];
+const FILTER_LABELS = {
+    all: "all",
+    running: "running",
+    failed: "failed",
+    model: "model calls",
+    flow: "flow calls",
+    messages: "messages"
+};
+/**
+ * The filter chips a run of this kind shows (spec 06 §2 and §3): a prototype
+ * has `all | messages | failed` and nothing else; every other run has the
+ * shared set. `messages` is a prototype's conversation across workers, so it
+ * is not offered elsewhere.
+ *
+ * @param kind the run's kind
+ *
+ * @category utilities
+ * @since 1.0.0
+ */
+export const traceFiltersFor = (kind) => (kind === "prototype"
+    ? ["all", "messages", "failed"]
+    : ["all", "running", "failed", "model", "flow"]).map((id) => [id, FILTER_LABELS[id]]);
+/** Whether a filter word is one the trace knows.
+ *
+ * @category utilities
+ * @since 1.0.0
+ */
+export const isTraceFilter = (value) => TRACE_FILTER_IDS.includes(value);
+/** The first prose line outside fenced code, bounded for the cheap turn list. Full text stays in the model span. */
+const proseLine = (text) => {
+    if (text === undefined)
+        return undefined;
+    let fence;
+    for (const line of text.split("\n")) {
+        const trimmed = line.trim();
+        const marker = /^(?:`{3,}|~{3,})/.exec(trimmed)?.[0];
+        if (marker !== undefined) {
+            if (fence === undefined)
+                fence = marker;
+            else if (marker[0] === fence[0] && marker.length >= fence.length)
+                fence = undefined;
+            continue;
+        }
+        if (fence !== undefined || trimmed === "")
+            continue;
+        // A code-only response or the journal's truncated-field object is not explanatory prose.
+        if (/^(?:[[{]|(?:const|let|var|await|import|export|function|return)\b)/.test(trimmed))
+            return undefined;
+        const words = trimmed.replace(/^#{1,6}\s+|^[-*+]\s+|^>\s+/, "").replace(/\s+/g, " ");
+        const sentence = words.match(/^.*?[.!?](?=\s|$)/)?.[0] ?? `${words}.`;
+        return sentence.length <= 180 ? sentence : `${sentence.slice(0, 179).trimEnd()}…`;
+    }
+    return undefined;
+};
+/** One cheap line per turn; falls back to actual call names when the model recorded only code.
+ *
+ * @category utilities
+ * @since 1.0.0
+ */
+export const turnNarratives = (model) => model.root.children.filter((span) => span.kind === "frame").map((frame, index) => {
+    const text = frame.children.filter((span) => span.kind === "model").map((span) => proseLine(span.detail.output))
+        .find((value) => value !== undefined);
+    if (text !== undefined)
+        return { frame, number: index + 1, text, source: "model" };
+    const names = [];
+    const walk = (span) => {
+        if (span.kind === "call" && !names.includes(span.label))
+            names.push(span.label);
+        for (const child of span.children)
+            walk(child);
+    };
+    walk(frame);
+    return names.length > 0
+        ? {
+            frame,
+            number: index + 1,
+            text: `The agent called ${names.slice(0, 3).join(", ")}${names.length > 3 ? ` and ${names.length - 3} other flows` : ""}.`,
+            source: "calls"
+        }
+        : {
+            frame,
+            number: index + 1,
+            text: frame.children.some((span) => span.kind === "cell")
+                ? "The agent produced a script; no flow calls were recorded in this turn."
+                : frame.children.some((span) => span.kind === "model")
+                    ? "The model responded; no script or flow calls were recorded in this turn."
+                    : "The turn started; no model response or flow calls have been recorded.",
+            source: "journal"
+        };
+});
+/** The recorded ancestry of a selection, for breadcrumbs and the selected turn's scoped call tree.
+ *
+ * @category utilities
+ * @since 1.0.0
+ */
+export const spanPath = (model, id) => {
+    const visit = (span) => {
+        if (span.id === id)
+            return [span];
+        for (const child of span.children) {
+            const path = visit(child);
+            if (path !== undefined)
+                return [span, ...path];
+        }
+        return undefined;
+    };
+    return visit(model.root) ?? [model.root];
+};
+/** A duration in the trace's units: milliseconds under a second, seconds under a minute, minutes and seconds under an hour, hours and minutes after.
+ *
+ * @category utilities
+ * @since 1.0.0
+ */
+export const durationWords = (ms) => {
+    if (ms < 1000)
+        return `${Math.round(ms)}ms`;
+    // Round before splitting, so 59.96s reads 1m00s rather than 60.0s, and 51m59.6s reads 52m00s rather than 51m60s.
+    if (ms < 59_950)
+        return `${(ms / 1000).toFixed(1)}s`;
+    const total = Math.round(ms / 1000);
+    if (total < 3600) {
+        const minutes = Math.floor(total / 60);
+        return `${minutes}m${String(total - minutes * 60).padStart(2, "0")}s`;
+    }
+    const minutes = Math.round(ms / 60_000);
+    const hours = Math.floor(minutes / 60);
+    return `${hours}h${String(minutes - hours * 60).padStart(2, "0")}m`;
+};
+const memoryItems = (value) => Array.isArray(value) ?
+    value.flatMap((raw) => {
+        const item = typeof raw === "object" && raw !== null ? raw : undefined;
+        return item?.kind === "memory" && typeof item.id === "string" && typeof item.p === "number"
+            ? [{ id: item.id, kind: "memory", relevance: 1 - item.p }]
+            : [];
+    }) :
+    [];
+/**
+ * What memory a run was brought, from the `control.agent.relevance-settled`
+ * rows of its `run-events` projection: ids and probabilities, never text. A
+ * reading also weighs flows, skills and instructions; only memory counts here.
+ * An item any reading kept is in; one only ever withheld is withheld; both
+ * most relevant first. A row whose verdicts were not retained is no reading.
+ * Undefined when Jev never read for the run.
+ *
+ * @category folds
+ * @since 1.0.0
+ */
+export const runMemoryOf = (records) => {
+    const kept = new Map();
+    const withheld = new Map();
+    let read = false;
+    for (const record of records) {
+        if (record.kind !== "control.agent.relevance-settled")
+            continue;
+        const payload = typeof record.payload === "object" && record.payload !== null
+            ? record.payload
+            : {};
+        if (!Array.isArray(payload.kept) && !Array.isArray(payload.withheld))
+            continue;
+        read = true;
+        for (const item of memoryItems(payload.kept))
+            kept.set(item.id, item);
+        for (const item of memoryItems(payload.withheld))
+            withheld.set(item.id, item);
+    }
+    if (!read)
+        return undefined;
+    const byRelevance = (left, right) => right.relevance - left.relevance || left.id.localeCompare(right.id);
+    return {
+        kept: [...kept.values()].sort(byRelevance),
+        withheld: [...withheld.values()].filter((item) => !kept.has(item.id)).sort(byRelevance)
+    };
+};
+/** The system part an agent step's task travels in (`Agent.ts`). */
+const TASK_PREFIX = "The task for this run:\n\n";
+/** The agent's task from a traced request: its own `task` field, or the task
+ * part of its system text when that fit the journal. Parsed when it is JSON. */
+const taskOf = (request) => {
+    const parts = Array.isArray(request.system) ? request.system : [];
+    const part = parts.find((text) => typeof text === "string" && text.startsWith(TASK_PREFIX));
+    const task = typeof request.task === "string" ? request.task : part?.slice(TASK_PREFIX.length);
+    if (task === undefined)
+        return undefined;
+    try {
+        return JSON.parse(task);
+    }
+    catch {
+        return task;
+    }
+};
+const hexDigest = /^[0-9a-f]{64}$/;
+/** A transcript cell shows an excerpt; the journal keeps the full record. */
+const cellText = (value) => {
+    const text = textOf(value);
+    return text === undefined || text.length <= 2000 ? text : `${text.slice(0, 2000)}…`;
+};
+/** The recorded presentation of a tool call: "Read t5.md", "Failed to write t5.md". */
+const callCellLabel = (started, failed) => {
+    const descriptor = asRecord(started.descriptor);
+    const presentation = asRecord(descriptor.presentation);
+    const verbs = asRecord(presentation.verb);
+    const name = started.flowName;
+    const verb = asString(failed ? verbs.failure : verbs.success) ?? (failed ? `failed ${name}` : name);
+    const subjectKey = asString(presentation.subject);
+    const subject = subjectKey === undefined ? undefined : asString(asRecord(started.input)[subjectKey]);
+    const text = subject === undefined ? verb : `${verb} ${subject}`;
+    return text.charAt(0).toUpperCase() + text.slice(1);
+};
+const callCellKind = (started) => {
+    const activity = asString(asRecord(started.descriptor).activity);
+    const name = started.flowName;
+    return name === "ask" ? "ask" : activity === "reads" ? "read" : activity === "writes" ? "edit" : "run";
+};
+const decodeCallFact = Schema.decodeUnknownOption(CallFact.Fact);
+/** A native tool-call fact and the dispatch digest its scope names. */
+const callFactOf = (record) => {
+    if (record.kind !== "control.engine.event")
+        return undefined;
+    const envelope = asRecord(record.payload);
+    if (envelope.version !== 1 || envelope.eventType !== CallFact.eventType || envelope.sourceSequence !== 0) {
+        return undefined;
+    }
+    const fact = decodeCallFact(envelope.payload);
+    if (fact._tag === "None" || envelope.sourceId !== `call-fact-v1:${fact.value.callId}:${fact.value.phase}`) {
+        return undefined;
+    }
+    const stepId = /@([0-9a-f]{64}):\d+#\d+$/.exec(fact.value.identity.runId)?.[1];
+    return stepId === undefined ? undefined : { stepId, fact: fact.value };
+};
+/**
+ * The agent transcript of every native dispatch in `journal`: model replies,
+ * cells with what they printed, and tool calls, in journal order. Keyed by the
+ * dispatch's step key digest, which the engine's node settlement names in
+ * `stepKeyDigests`. Pure over the records; no model call.
+ */
+const stepTranscripts = (journal) => {
+    const transcripts = new Map();
+    const entry = (key) => {
+        let found = transcripts.get(key);
+        if (found === undefined)
+            transcripts.set(key, found = { cells: [], tokens: 0, models: 0 });
+        return found;
+    };
+    const lastCell = new Map();
+    const calls = new Map();
+    for (const record of journal) {
+        const sequence = record.sequence ?? 0;
+        const step = nativeStepEvent(record);
+        if (step !== undefined) {
+            const payload = asRecord(step.payload);
+            // nativeStepEvent has decoded StepFact.Scope, whose stepId is a 64-digit hex string.
+            const stepId = asString(asRecord(payload.step).stepId);
+            const transcript = entry(stepId);
+            if (step.kind === "control.agent.model-requested" && transcript.input === undefined) {
+                const task = taskOf(payload);
+                if (task !== undefined)
+                    transcript.input = task;
+            }
+            else if (step.kind === "control.agent.model-settled") {
+                const usage = asRecord(payload.usage);
+                const tokens = (asNumber(usage.inputTokens) ?? 0) + (asNumber(usage.outputTokens) ?? 0);
+                const duration = asNumber(payload.durationMillis);
+                const text = cellText(payload.text);
+                transcript.tokens += tokens;
+                transcript.models += 1;
+                transcript.cells.push({
+                    id: `cell:${sequence}`,
+                    kind: "think",
+                    label: "Model reply",
+                    ...(text === undefined ? {} : { quote: text }),
+                    tokens,
+                    ...(duration === undefined ? {} : { took_s: Math.max(0, duration) / 1000 })
+                });
+            }
+            else if (step.kind === "control.agent.cell-produced") {
+                const code = cellText(payload.text);
+                const cell = {
+                    id: `cell:${sequence}`,
+                    kind: "run",
+                    label: "Ran a cell",
+                    ...(code === undefined ? {} : { code })
+                };
+                transcript.cells.push(cell);
+                lastCell.set(stepId, cell);
+            }
+            else if (step.kind === "control.agent.cell-printed") {
+                const cell = lastCell.get(stepId);
+                const printed = cellText(payload.text);
+                if (cell !== undefined && printed !== undefined && printed !== "") {
+                    cell.output = cell.output === undefined ? printed : `${cell.output}\n${printed}`;
+                }
+            }
+            else if (step.kind === "control.agent.cell-settled") {
+                const cell = lastCell.get(stepId);
+                if (cell !== undefined)
+                    cell.tone = asString(payload.outcome) === "failure" ? "fail" : "ok";
+            }
+            continue;
+        }
+        const call = callFactOf(record);
+        if (call === undefined)
+            continue;
+        const handle = `${call.stepId}:${call.fact.callId}`;
+        if (call.fact.phase === "invoked") {
+            const input = cellText(call.fact.input);
+            const cell = {
+                id: `cell:${sequence}`,
+                kind: callCellKind(call.fact),
+                label: callCellLabel(call.fact, false),
+                ...(input === undefined ? {} : { code: input }),
+                tone: "live"
+            };
+            entry(call.stepId).cells.push(cell);
+            calls.set(handle, { cell, started: call.fact });
+            continue;
+        }
+        const open = calls.get(handle);
+        if (open === undefined)
+            continue;
+        const failed = call.fact.outcome === "failure";
+        open.cell.label = callCellLabel(open.started, failed);
+        open.cell.tone = failed ? "fail" : "ok";
+        const result = failed ? cellText(call.fact.message) : cellText(call.fact.value);
+        if (result !== undefined)
+            open.cell.output = result;
+    }
+    return transcripts;
+};
+/** The dispatches a settled engine node drove, as `<execution id>:<step key digest>`. */
+const nodeDispatches = (row) => {
+    if (!row.id.startsWith("engine-node:"))
+        return [];
+    const fields = asRecord(row.detail.fields);
+    const execution = asString(fields.executionId);
+    const digests = asRecord(fields.payload).stepKeyDigests;
+    if (execution === undefined || !Array.isArray(digests))
+        return [];
+    return [
+        ...new Set(digests.filter((digest) => typeof digest === "string" && hexDigest.test(digest)))
+    ]
+        .map((digest) => `${execution}:${digest}`);
+};
+/** Plan node kinds that only shape the plan (@smthrs/plan); a child flow's own nodes are its steps. */
+const PLAN_STRUCTURE = new Set([
+    "Succeed",
+    "Fail",
+    "All",
+    "Race",
+    "Map",
+    "AndThen",
+    "Branch",
+    "Catch",
+    "FlowCall",
+    "FunctionIdentity",
+    "PlannedReference"
+]);
+/** A check receipt's leading scalar fields, read from a preview the engine
+ * may have cut short (its evidence comes last): `{"checkId":…,"status":…`. */
+const RECEIPT_HEAD = /^\{"checkId":"[^"\\]*"(?:,"[A-Za-z]+":(?:"[^"\\]*"|-?\d+))*,"status":"(passed|failed|superseded)"/;
+/** How many checks a step's recorded output reports failed: a check receipt
+ * (`{checkId, status, …}`, possibly a cut-short preview) or a list of them;
+ * zero for any other output. */
+const checkFailures = (output) => {
+    if (output === undefined)
+        return 0;
+    const head = RECEIPT_HEAD.exec(output);
+    if (head !== null)
+        return head[1] === "failed" ? 1 : 0;
+    let value;
+    try {
+        value = JSON.parse(output);
+    }
+    catch {
+        return 0;
+    }
+    return (Array.isArray(value) ? value : []).filter((receipt) => {
+        const record = asRecord(receipt);
+        return typeof record.checkId === "string" && record.status === "failed";
+    }).length;
+};
+/** Each recorded engine node's kind and action, by its trace span id (without instance). */
+const engineNodeShapes = (journal) => {
+    const shapes = new Map();
+    for (const record of journal) {
+        if (record.kind !== "control.engine.event")
+            continue;
+        const envelope = asRecord(record.payload);
+        const executionId = asString(envelope.executionId);
+        const generation = asNumber(envelope.generation);
+        const payload = asRecord(envelope.payload);
+        if (executionId === undefined || generation === undefined)
+            continue;
+        const prefix = `engine-node:${encodeURIComponent(`${encodeURIComponent(executionId)}:${generation}`)}:`;
+        if (envelope.eventType === "flows.engine.plan-recorded" || envelope.eventType === "flows.engine.subgraph-appended") {
+            const nodes = asRecord(payload.graph).nodes;
+            for (const node of Array.isArray(nodes) ? nodes : []) {
+                const shape = asRecord(node);
+                const id = asString(shape.id);
+                if (id !== undefined) {
+                    shapes.set(prefix + encodeURIComponent(id), { kind: asString(shape.kind), action: asString(shape.action) });
+                }
+            }
+        }
+        else if (envelope.eventType === "flows.engine.node-scheduled") {
+            const id = asString(payload.nodeId);
+            if (id === undefined)
+                continue;
+            const known = shapes.get(prefix + encodeURIComponent(id));
+            shapes.set(prefix + encodeURIComponent(id), {
+                kind: asString(payload.kind) ?? known?.kind,
+                action: asString(payload.action) ?? known?.action
+            });
+        }
+    }
+    return shapes;
+};
+/** Adapt the canonical trace to the install monitor. IDs and timestamps come
+ * from recorded spans; inspection never evaluates flow bodies or presentations.
+ * @since 1.0.0
+ * @category constructors
+ */
+export const monitorFromJournal = (run, records, at) => {
+    const last = records.reduce((last, row) => Math.max(last, row.sequence ?? 0), 0);
+    const journal = at === undefined ? records : records.filter((row) => (row.sequence ?? 0) <= at);
+    // A historical frame must not inherit the current run's terminal status.
+    const lifecycleRow = [...journal].reverse().find((row) => /^control\.run\.(running|waiting-approval|paused|suspended|held|completed|failed|cancelled|interrupted)$/.test(row.kind ?? "") &&
+        (row.runId === undefined || row.runId === run.runId));
+    const status = at === undefined ? run.status : lifecycleRow?.kind?.split(".").at(-1) ?? "running";
+    const state = (value) => value === "completed" || value === "done" ? "done" : value === "failed" ?
+        "failed"
+        : value === "cancelled" || value === "interrupted" ?
+            "interrupted" :
+            value === "held" ?
+                "held"
+                : value === "waiting" || value === "waiting-approval" || value === "paused" || value === "suspended"
+                    ? "waiting"
+                    : "running";
+    const trace = traceFromJournal({ ...run, status }, journal);
+    const engineLabel = (label) => ACTION_RENDERINGS[label] === null || /^<(?:boundary:|quota-park>|structured-output-count>)/.test(label);
+    const bookkeeping = (row) => engineLabel(row.label);
+    const transcripts = stepTranscripts(journal);
+    // Every call below is a member of trace.rows, so both lookups are total.
+    const dispatchesOf = new Map(trace.rows.map((row) => [row.id, nodeDispatches(row)]));
+    // A step is a node that dispatched an action. Plan structure (sequences,
+    // branches, maps) and child-flow calls, whose own nodes are the steps, are
+    // never steps of their own.
+    const structural = (kind) => kind !== undefined && PLAN_STRUCTURE.has(kind);
+    const nodeShapes = engineNodeShapes(journal);
+    const calls = trace.rows.filter((row) => {
+        // A tool call an agent made inside a step is a cell of that step's
+        // transcript (step:<scope>/…), never a step of its own.
+        if (row.kind !== "call" || bookkeeping(row) || row.id.startsWith("step:"))
+            return false;
+        const shape = nodeShapes.get(row.id.replace(/#\d+$/, ""));
+        return shape === undefined || !structural(shape.kind);
+    });
+    const transcriptOf = (row) => {
+        const parts = dispatchesOf.get(row.id).flatMap((dispatch) => {
+            const found = transcripts.get(dispatch.slice(dispatch.lastIndexOf(":") + 1));
+            return found === undefined ? [] : [found];
+        });
+        return {
+            cells: parts.flatMap((part) => part.cells).sort((left, right) => Number(left.id.slice(5)) - Number(right.id.slice(5))),
+            tokens: parts.reduce((total, part) => total + part.tokens, 0),
+            models: parts.reduce((total, part) => total + part.models, 0),
+            input: parts.find((part) => part.input !== undefined)?.input
+        };
+    };
+    const steps = calls.map((row) => {
+        const meter = dispatchesOf.get(row.id);
+        const transcript = transcriptOf(row);
+        return {
+            ...(() => {
+                const matched = /^(engine-node:.*)#(\d+)$/.exec(row.id);
+                const id = matched?.[1] ?? row.id;
+                const k = Number(matched?.[2] ?? 1);
+                return { key: `${id}#${k}`, id, k };
+            })(),
+            label: row.label,
+            state: row.status,
+            started_at: new Date(row.startedAt).toISOString(),
+            ...(row.endedAt === undefined
+                ? {}
+                : { ended_at: new Date(row.endedAt).toISOString(), took_s: Math.max(0, row.endedAt - row.startedAt) / 1000 }),
+            ...(row.detail.input !== undefined
+                ? { input: row.detail.input }
+                : transcript.input !== undefined
+                    ? { input: transcript.input }
+                    : {}),
+            ...(row.detail.output === undefined ? {} : { output: row.detail.output }),
+            // The install prices these dispatches from its metered proxy rows and
+            // replaces them with `usage`; the journal's own token count rides along.
+            ...(meter.length === 0 ? {} : { meter }),
+            ...(transcript.models === 0 ? {} : { model_calls: transcript.models, tokens: transcript.tokens })
+        };
+    });
+    const tone = (value) => value === "failed" ?
+        "fail"
+        : value === "completed"
+            ? "ok"
+            : value === "waiting"
+                ? "wait"
+                : "live";
+    const phases = calls.map((row, index) => {
+        const transcript = transcriptOf(row).cells;
+        const failedChecks = checkFailures(row.detail.output);
+        const cells = transcript.length > 0
+            ? transcript
+            : [{
+                    id: `cell:${row.id}`,
+                    kind: /Edited/.test(row.label) ? "edit" : /Read/.test(row.label) ? "read" : "run",
+                    label: row.label,
+                    ...(row.detail.output === undefined ? {} : { output: row.detail.output }),
+                    tone: tone(row.status)
+                }];
+        return {
+            id: `phase:${row.id}`,
+            step: steps[index].key,
+            // The title is the Appendix C label plus the outcome its recorded
+            // output reports: "Ran checks · 1 failed".
+            title: failedChecks === 0 ? row.label : `${row.label} · ${failedChecks} failed`,
+            took_s: Math.max(0, (row.endedAt ?? row.startedAt) - row.startedAt) / 1000,
+            tone: failedChecks === 0 ? tone(row.status) : "fail",
+            cells
+        };
+    });
+    const declaredGraph = engineExecutionEvidence(journal).filter((execution) => execution.coherent).flatMap((execution) => {
+        const prefix = `engine-node:${encodeURIComponent(`${encodeURIComponent(execution.executionId)}:${execution.generation}`)}:`;
+        const nodes = execution.graph?.nodes ?? [];
+        const hidden = new Map(nodes.filter((node) => engineLabel(node.action ?? node.id) || structural(node.kind))
+            .map((node) => [node.id, node]));
+        // Engine bookkeeping stays in the Engine row. Its dependency edges still
+        // order the visible steps, including across several hidden boundaries.
+        const visibleDeps = (id, seen) => {
+            const node = hidden.get(id);
+            if (node === undefined)
+                return [prefix + encodeURIComponent(id)];
+            if (seen.has(id))
+                return [];
+            return node.dependsOn.flatMap((dependency) => visibleDeps(dependency, new Set([...seen, id])));
+        };
+        return nodes.filter((node) => !hidden.has(node.id)).map((node) => {
+            const id = prefix + encodeURIComponent(node.id);
+            const instances = calls.filter((row) => row.id.startsWith(`${id}#`));
+            const current = instances.at(-1);
+            return {
+                id,
+                label: inspectLabel(node.action ?? node.id),
+                // A branch not taken never ran: it stays next, even in a finished run.
+                state: current === undefined || current.status === "skipped" ?
+                    "next" :
+                    current.status === "completed" ?
+                        "done"
+                        : current.status === "failed"
+                            ? "failed"
+                            : current.status === "waiting"
+                                ? "waiting"
+                                : "current",
+                deps: [...new Set(node.dependsOn.flatMap((dependency) => visibleDeps(dependency, new Set([node.id]))))]
+            };
+        });
+    });
+    const usageOf = (row) => (row.detail.usage?.inputTokens ?? 0) + (row.detail.usage?.outputTokens ?? 0);
+    const tokens = trace.rows.reduce((total, row) => total + usageOf(row), 0);
+    // Model calls no native dispatch recorded (a legacy agent journal) can
+    // never be joined to metered rows; the install refuses to price them.
+    const unmetered = trace.rows.filter((row) => row.kind === "model" && asRecord(row.detail.fields).step === undefined)
+        .reduce((total, row) => total + usageOf(row), 0);
+    const approvalWaits = trace.rows.filter((row) => row.kind === "approval").map((row) => ({
+        id: row.id,
+        kind: "approval",
+        label: row.label,
+        since: new Date(row.startedAt).toISOString(),
+        ...(row.endedAt === undefined
+            ? {}
+            : {
+                settled: { by: { kind: "system", color_index: 7 }, at: new Date(row.endedAt).toISOString() }
+            })
+    }));
+    // The machine records its declared custom view as data. Only the shipped
+    // text renderer is supported; module paths, HTML and executable data never
+    // cross this seam. Replay selects the last declaration in its own prefix.
+    const custom = [...journal].reverse().find(row => (row.runId === undefined || row.runId === run.runId) &&
+        row.kind === "control.engine.event" && asRecord(row.payload).eventType === "flows.run.presentation");
+    const presentation = asRecord(asRecord(custom?.payload).payload);
+    const text = asString(presentation.text);
+    const customView = presentation.kind === "text" && text !== undefined && text.length <= 65536 &&
+        Object.keys(presentation).every(key => key === "kind" || key === "text")
+        ? { presentation: { kind: "text", text } } : {};
+    return {
+        ...customView,
+        id: run.runId,
+        flow: run.flowId,
+        version: "",
+        title: run.flowId,
+        state: state(status),
+        attempts: [{
+                n: 1,
+                run_id: run.runId,
+                state: state(status),
+                steps,
+                phases,
+                graph: declaredGraph.length > 0 ?
+                    declaredGraph :
+                    calls.map((row) => ({
+                        id: row.id,
+                        label: row.label,
+                        state: row.status === "skipped" ? "next" : row.status === "completed" ?
+                            "done"
+                            : row.status === "failed"
+                                ? "failed"
+                                : row.status === "waiting"
+                                    ? "waiting"
+                                    : "current",
+                        deps: []
+                    }))
+            }],
+        waits: [
+            ...approvalWaits,
+            ...engineExecutionEvidence(journal).filter((execution) => execution.coherent).flatMap((execution) => execution.waits.map((wait) => ({
+                id: wait.id,
+                kind: wait.kind,
+                label: inspectLabel("wait"),
+                since: new Date(wait.since).toISOString(),
+                ...(wait.settledAt === undefined
+                    ? {}
+                    : {
+                        settled: {
+                            by: { kind: "system", color_index: 7 },
+                            at: new Date(wait.settledAt).toISOString()
+                        }
+                    })
+            })))
+        ],
+        tokens,
+        // Spend is priced where model calls are metered. The host never publishes
+        // an unknown total as zero: a run with model tokens leaves cost to the install.
+        time_s: Math.max(0, trace.extent.end - trace.extent.start) / 1000,
+        ...(tokens === 0 ? { cost_usd: 0 } : {}),
+        ...(unmetered === 0 ? {} : { unmetered_tokens: unmetered }),
+        engine: trace.rows.filter((row) => row.kind === "event" || row.kind === "execution" || row.kind === "attempt" || bookkeeping(row)).map((row) => ({ label: row.label, detail: row.detail.output ?? row.detail.message ?? "" })),
+        journal: journal.map((row) => ({
+            seq: row.sequence ?? 0,
+            at: new Date(row.occurredAt ?? 0).toISOString(),
+            type: row.kind ?? "event",
+            text: JSON.stringify(row.payload) ?? "null"
+        })),
+        ...(at === undefined ? {} : { replay: { at: Math.min(at, last), last } })
+    };
+};
+//# sourceMappingURL=RunTrace.js.map