@itookit/dsht 0.3.8 → 0.5.2

package/dist/cli/startup.js

@@ -0,0 +1,314 @@
+/** Startup automation: pick a workspace and a session, then run the requested slash lines.
+ *
+ * This is the scriptable half of the client — `dsht --ws X --session new --command "…"` — so a
+ * review can be launched without typing. It drives the same controller the UI drives, and reads only
+ * the outcome of each line: the presentational effects of a command belong to the UI.
+ */
+import { runCommand } from "../controller/index.js";
+import { errorText } from "../transport/wire.js";
+import { dirname } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { ensureDirectory, renameFile, writePrivateFile } from "../storage/index.js";
+import { latestAssistantText } from "../controller/loop.js";
+import { parseVerdict } from "../controller/loop-contract.js";
+import { needsHumanLine } from "../controller/verifier.js";
+import { authorize, normalize } from "../slash/index.js";
+const POLL_MS = 250;
+/** How long a connection, session or workspace operation may take. */
+const STEP_TIMEOUT_MS = 30_000;
+/** How long a forked child may wait for the session it was pointed at to stream its snapshot. */
+const PROMPT_SNAPSHOT_TIMEOUT_MS = 180_000;
+/** How long the verdict may take to appear after the turn was reported idle. */
+const VERDICT_GRACE_MS = 5_000;
+/** How often the reply is re-read while that grace lasts. */
+const VERDICT_POLL_MS = 200;
+/** Wait until one condition holds.
+ * @param condition - Predicate polled until true.
+ * @param what - Human-readable subject for the timeout message.
+ * @param timeoutMs - Longest wait.
+ */
+async function until(signal, condition, what, timeoutMs = STEP_TIMEOUT_MS) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        signal.throwIfAborted();
+        if (condition())
+            return;
+        if (Date.now() >= deadline)
+            throw new Error(`Timed out waiting for ${what}`);
+        await delay(POLL_MS, undefined, { signal });
+    }
+}
+/** Run the plan against a started controller.
+ * @param controller - Connected application facade.
+ * @param plan - Workspace, session and lines to run.
+ * @param log - Progress sink, usually stderr in headless mode.
+ * @returns Whether a started loop passed, nothing ran, or the run failed.
+ */
+export async function runStartup(controller, plan, log) {
+    const signal = controller.connection.signal();
+    // `online` alone is too early: the startup picker runs after it and would overwrite a selection
+    // made here, which is exactly how a forked verifier used to lose its session.
+    await until(signal, () => controller.state.online && controller.queries.connectionSettled, 'the host connection');
+    if (plan.workspace !== undefined && !await controller.actions.switchWorkspace(plan.workspace)) {
+        throw new Error(`Workspace not found: ${plan.workspace}`);
+    }
+    // An explicit `new`, or automation with no session named, starts a fresh conversation; the
+    // workspace defaults to the directory this client runs in, registered on demand.
+    if (plan.session === 'new' || plan.session === undefined && plan.commands.length > 0) {
+        await ensureWorkspace(controller, log);
+        if (!await controller.actions.createSession())
+            throw new Error('Could not create a session');
+    }
+    else if (plan.session !== undefined) {
+        if (!await controller.actions.selectSession(plan.session))
+            throw new Error(`Session not found: ${plan.session}`);
+    }
+    // A selected session is not sendable until its follow snapshot lands.
+    if (plan.commands.length) {
+        await until(signal, () => controller.state.screen === 'chat' && controller.state.sessionId !== undefined && controller.queries.record.ready, 'the session snapshot');
+    }
+    // Start-up lines are one-shot action commands; the cancellable port is only used by searches
+    // and exports, which have no meaning before the operator is present.
+    const port = { run: (_label, operation) => operation(controller.connection.signal()) };
+    for (const line of plan.commands) {
+        signal.throwIfAborted();
+        // The scripted half runs the same two stages the composer does after `interpret`: a headless
+        // caller has no menus or screens, but it has every application fact `normalize`/`authorize` read.
+        const command = normalize({ kind: 'line', line }, {
+            sessionSelected: controller.state.sessionId !== undefined,
+            question: controller.state.pending[0]?.kind === 'question',
+            pending: controller.state.pending.length > 0,
+        });
+        if (command.kind === 'error')
+            throw new Error(command.message);
+        const verdict = await authorizeWhenReady(controller, command);
+        if (!verdict.allow)
+            throw new Error(verdict.error.message);
+        const result = await runCommand(controller, verdict.command, port);
+        if (result === undefined) {
+            const reason = controller.state.lastFailure;
+            throw new Error(`Command was not accepted: ${line}${reason ? ` (${reason})` : ''}`);
+        }
+        if (result.outcome !== 'ok') {
+            const failure = result.effects.find(effect => effect.kind === 'error');
+            throw new Error(failure?.kind === 'error' ? failure.text : `Command failed (${result.outcome}): ${line}`);
+        }
+        if (result.disposition === 'retain')
+            throw new Error(`Command did not settle: ${line}`);
+        for (const effect of result.effects)
+            if (effect.kind === 'notice')
+                log(effect.text);
+    }
+    // Both counts are taken before the prompt, because a turn can start and finish between two polls.
+    const finishedBefore = controller.queries.turnsCompleted;
+    const repliesBefore = controller.queries.record.messages.length;
+    if (plan.prompt !== undefined) {
+        // Sending a prompt needs the follow snapshot, and a verifier starts the instant a busy turn ends,
+        // so this wait is longer than a normal startup step: the host can be slow to open the new stream.
+        try {
+            await until(signal, () => controller.state.sessionId !== undefined && controller.queries.record.ready, 'the verifier session snapshot', PROMPT_SNAPSHOT_TIMEOUT_MS);
+        }
+        catch (error) {
+            signal.throwIfAborted();
+            // Which of the three conditions failed is the whole diagnosis, so it travels with the error.
+            throw new Error(`${errorText(error)} (screen=${controller.state.screen}, session=${controller.state.sessionId ?? 'none'},`
+                + ` snapshot=${String(controller.queries.record.ready)}, online=${String(controller.state.online)})`);
+        }
+        if (!await controller.actions.prompt(plan.prompt)) {
+            signal.throwIfAborted();
+            const reason = controller.state.lastFailure;
+            throw new Error(`Prompt was not accepted${reason ? ` (${reason})` : ''}`);
+        }
+    }
+    if (controller.queries.loop !== undefined)
+        return await waitForLoop(controller, plan.timeoutSeconds * 1000, log);
+    if (plan.wait) {
+        const outcome = await waitForTurn(controller, finishedBefore, plan.timeoutSeconds * 1000, log);
+        if (outcome === 'idle' && plan.verdict !== undefined)
+            await writeVerdict(controller, plan.verdict, repliesBefore, log);
+        return outcome;
+    }
+    return 'idle';
+}
+/** Authorize one startup line, waiting out a fact the policy queues behind.
+ *
+ * There is no composer here to hold a line, and failing a scripted run because the client happened to
+ * be mid-turn would make `--command` unusable in exactly the automation it exists for; so the scripted
+ * caller waits for the same fact the UI queue waits for, bounded by the step timeout.
+ * @param controller - Connected facade whose facts decide.
+ * @param command - Normalized line to run.
+ * @returns The verdict once the line may run, or the refusal it will never outlive.
+ */
+async function authorizeWhenReady(controller, command) {
+    const signal = controller.connection.signal();
+    const deadline = Date.now() + STEP_TIMEOUT_MS;
+    for (;;) {
+        signal.throwIfAborted();
+        const verdict = authorize(command, {
+            sessionSelected: controller.state.sessionId !== undefined,
+            pending: controller.state.pending.length > 0,
+            during: controller.queries.loop?.active === true ? 'loop' : controller.queries.running ? 'turn' : 'idle',
+            foreground: controller.queries.foreground !== undefined,
+        });
+        if (!verdict.allow || verdict.defer === undefined)
+            return verdict;
+        if (Date.now() >= deadline)
+            throw new Error(`Timed out waiting for the client to be free: ${command.kind}`);
+        await delay(POLL_MS, undefined, { signal });
+    }
+}
+/** Persist the verdict this session's reply just produced.
+ *
+ * The agent judges; this client owns the protocol file: the reply is parsed here and written through
+ * a temporary file that is renamed into place, so a reader never sees a half-written verdict.
+ * A reply with no usable verdict changes nothing — the parent validates whatever is there.
+ * @param controller - Connected facade whose transcript holds the reply.
+ * @param target - File to write and the identity the verdict must declare.
+ * @param repliesBefore - Messages on the transcript before the prompt was sent: only a reply that
+ *   arrived after it can be this turn's, so an idle from an earlier or replayed turn cannot be read
+ *   as the verdict.
+ * @param log - Progress sink.
+ */
+async function writeVerdict(controller, target, repliesBefore, log) {
+    const signal = controller.connection.signal();
+    signal.throwIfAborted();
+    const [, kind = '', step = '', attempt = ''] = target.identity.split('/');
+    const expect = { verificationId: target.identity, kind, step: Number(step), attempt: Number(attempt) };
+    // The host reports the turn idle just before that reply is committed, so an immediate parse can
+    // find nothing; the verdict is only missing once it has had time to arrive. Waiting on an
+    // assistant reply that did not exist when the prompt was sent is what ties the verdict to this
+    // prompt: the prompt itself only adds a user message, and an earlier turn's reply is behind the
+    // baseline.
+    const replyArrived = () => controller.queries.record.messages
+        .slice(repliesBefore).some(message => message.role === 'Assistant');
+    let parsed = replyArrived() ? parseVerdict(latestAssistantText(controller.queries.record.messages), expect) : undefined;
+    const deadline = Date.now() + VERDICT_GRACE_MS;
+    while (parsed === undefined && Date.now() < deadline) {
+        await delay(VERDICT_POLL_MS, undefined, { signal });
+        if (replyArrived())
+            parsed = parseVerdict(latestAssistantText(controller.queries.record.messages), expect);
+    }
+    if (parsed === undefined) {
+        // Say what actually happened: "no reply yet", "no JSON at all" and "JSON that is not this round"
+        // are different faults, and one line here is what tells them apart without another live run.
+        if (!replyArrived()) {
+            log('Turn ended but no reply was committed after the prompt; leaving the verdict file untouched');
+            return;
+        }
+        const tail = latestAssistantText(controller.queries.record.messages).slice(-240).replace(/\s+/g, ' ');
+        log(`No parsable verdict in the reply; leaving the verdict file untouched (reply tail: ${tail})`);
+        return;
+    }
+    const body = JSON.stringify({
+        verificationId: target.identity, kind, step: Number(step), attempt: Number(attempt),
+        ...(parsed.score === undefined ? {} : { score: parsed.score }),
+        ...(parsed.status === undefined ? {} : { status: parsed.status }),
+        ...(parsed.blocked === true ? { blocked: true } : {}),
+        ...(parsed.evidence === undefined ? {} : { evidence: parsed.evidence }),
+        ...(parsed.findings === undefined ? {} : { top_findings: parsed.findings }),
+    });
+    await ensureDirectory(dirname(target.file));
+    const temporary = `${target.file}.part`;
+    await writePrivateFile(temporary, body);
+    await renameFile(temporary, target.file);
+    log(`Verdict written to ${target.file}`);
+}
+/** Follow a sent prompt's turn to its end, which is what lets a forked child exit by itself.
+ *
+ * The host's idle event is the same signal the scored loop trusts: it cannot be missed by polling,
+ * and a turn that starts and ends between two polls still counts.
+ * @param controller - Connected application facade.
+ * @param finishedBefore - Turns completed before the prompt was sent.
+ * @param timeoutMs - Longest wait.
+ * @param log - Progress sink.
+ * @returns `idle` when the turn ended, `failed` on timeout.
+ */
+async function waitForTurn(controller, finishedBefore, timeoutMs, log) {
+    const signal = controller.connection.signal();
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        signal.throwIfAborted();
+        if (controller.queries.turnsCompleted > finishedBefore) {
+            log('Turn finished');
+            return 'idle';
+        }
+        // A headless verifier cannot answer an approval or a question: stop and say what is needed,
+        // instead of waiting for the deadline and being retried as an infrastructure failure.
+        const request = humanRequest(controller);
+        if (request !== undefined) {
+            log(needsHumanLine(request));
+            return 'needs-human';
+        }
+        if (Date.now() >= deadline) {
+            log('Turn timed out');
+            return 'failed';
+        }
+        await delay(POLL_MS, undefined, { signal });
+    }
+}
+/** The host interaction this client cannot answer itself, when one is pending.
+ * @param controller - Connected facade whose selected session is the verifier's session.
+ * @returns The request to report, or undefined when nothing is pending.
+ */
+function humanRequest(controller) {
+    const [pending] = controller.state.pending;
+    if (pending === undefined)
+        return undefined;
+    if (pending.kind === 'approval') {
+        return { kind: 'approval', text: pending.description === '' ? 'a tool approval is required' : pending.description };
+    }
+    return { kind: 'question', text: pending.questions[0]?.question ?? 'a question was asked' };
+}
+/** Select the directory this client runs in, registering it when the host does not know it yet. */
+async function ensureWorkspace(controller, log) {
+    if (controller.state.workspaceId !== undefined)
+        return;
+    if (await controller.actions.switchWorkspace(controller.localDirectory))
+        return;
+    log(`Registering ${controller.localDirectory} as a workspace`);
+    if (!await controller.actions.createWorkspace(controller.localDirectory)) {
+        throw new Error(`Could not use ${controller.localDirectory} as a workspace`);
+    }
+}
+/** Follow a running loop to its terminal phase, reporting progress changes.
+ * @returns `passed` when the loop met its threshold, `failed` otherwise.
+ */
+async function waitForLoop(controller, timeoutMs, log) {
+    const signal = controller.connection.signal();
+    const deadline = Date.now() + timeoutMs;
+    let previous = '';
+    for (;;) {
+        signal.throwIfAborted();
+        const progress = controller.queries.loop;
+        if (progress === undefined || progress.phase !== 'running') {
+            // A cancelled loop usually means the connection ended; say so, or the exit code is a mystery.
+            const why = controller.state.lastFailure || controller.state.status;
+            const interaction = progress?.interaction;
+            // `passed` only claims the rounds that ran, so a headless reader is told which ones.
+            const scope = progress?.phase === 'passed' ? ` · ${progress.scope}` : '';
+            log(`Loop ${progress?.phase ?? 'gone'}${scope}${why ? ` · ${why}` : ''}`
+                + `${interaction === undefined ? '' : ` · ${interaction.kind}: ${interaction.text}`}`
+                + `${progress?.note === undefined ? '' : ` · ${progress.note}`}`);
+            if (progress?.phase === 'passed')
+                return 'passed';
+            // A run stopped on a host request is not a failure: it is waiting for a person, and phase 1
+            // deliberately has no in-process answer path.
+            return progress?.phase === 'needs-human' ? 'needs-human' : 'failed';
+        }
+        const label = progress.stepLabel === undefined ? '' : ` · ${progress.stepLabel}`;
+        // The note carries why an attempt was decided the way it was — including why verification was
+        // unavailable — so a headless run is diagnosable without a renderer.
+        const note = progress.note === undefined ? '' : ` · ${progress.note}`;
+        const line = `${progress.title}${label} · step ${progress.step}/${progress.to} · attempt ${progress.attempt}/${progress.tries} · best ${progress.best}/${progress.score}${note}`;
+        if (line !== previous) {
+            previous = line;
+            log(line);
+        }
+        if (Date.now() >= deadline) {
+            controller.actions.stopLoop();
+            log('Loop timed out and was stopped');
+            return 'failed';
+        }
+        await delay(POLL_MS, undefined, { signal });
+    }
+}

package/dist/cli/trace-summary.d.ts

@@ -0,0 +1,78 @@
+/** Reading a trace back as a few lines: what ran, what was refused, and what never finished.
+ *
+ * The trace is written for a machine (`slash.md` §7) and a reader only ever asks a handful of
+ * questions of it: which commands ran and how they ended, which session writes were serialized, what
+ * owned the client and for how long, how the loops and verifications went, and whether any span is
+ * still open. This module answers exactly those, from the lines alone, so it can be tested without a
+ * file and reused by a future `--json` consumer.
+ *
+ * It never re-derives a fact the trace did not record: an event it does not know is counted as
+ * skipped rather than guessed at.
+ */
+/** One loop run as the trace describes it. */
+export interface TraceLoopRun {
+    readonly runId: string;
+    readonly kind: string;
+    /** Steps the run sent, counted from its `sent` events. */
+    readonly sent: number;
+    /** Phase the run ended in, when it reached one. */
+    readonly result?: string;
+    /** Why it ended, when the end recorded a reason. */
+    readonly reason?: string;
+}
+/** Everything `dsht trace` reports about one trace file. */
+export interface TraceSummary {
+    readonly path: string;
+    /** Events read, and lines that were not events (unparsable or foreign). */
+    readonly events: number;
+    readonly skipped: number;
+    /** First and last event timestamps, when the trace has any. */
+    readonly from?: string;
+    readonly to?: string;
+    /** Submissions: how they ended and which command kinds they were. */
+    readonly commands: {
+        readonly total: number;
+        readonly outcomes: Record<string, number>;
+        readonly kinds: Record<string, number>;
+    };
+    /** Session writes: total, by lane and by target session. */
+    readonly mutations: {
+        readonly total: number;
+        readonly lanes: Record<string, number>;
+        readonly sessions: Record<string, number>;
+    };
+    /** Foreground slots: total, cancelled, the longest one, and any left open. */
+    readonly operations: {
+        readonly total: number;
+        readonly cancelled: number;
+        readonly longestMs?: number;
+        readonly longest?: string;
+        readonly open: number;
+    };
+    readonly loops: readonly TraceLoopRun[];
+    /** Verification tasks: how many started, and how they concluded.
+     *
+     * `begin` is not derivable from the outcomes — a task whose process died mid-flight has neither —
+     * so both are reported and the formatter points out the gap.
+     */
+    readonly verifiers: {
+        readonly begin: number;
+        readonly verified: number;
+        readonly unavailable: number;
+        readonly cancelled: number;
+        readonly byClass: Record<string, number>;
+    };
+    /** Spans that began and never ended, oldest first. */
+    readonly anomalies: readonly string[];
+}
+/** Summarize one trace file's lines.
+ * @param lines - Raw trace lines, oldest first, header and blanks included.
+ * @param path - File the lines came from, for the report.
+ * @returns The summary a reader wants.
+ */
+export declare function summarizeTrace(lines: readonly string[], path?: string): TraceSummary;
+/** Render a summary as the lines `dsht trace` prints.
+ * @param summary - Result of `summarizeTrace`.
+ * @returns Plain lines, one fact per line, without a trailing newline.
+ */
+export declare function formatTraceSummary(summary: TraceSummary): string[];

package/dist/cli/trace-summary.js

@@ -0,0 +1,241 @@
+/** Reading a trace back as a few lines: what ran, what was refused, and what never finished.
+ *
+ * The trace is written for a machine (`slash.md` §7) and a reader only ever asks a handful of
+ * questions of it: which commands ran and how they ended, which session writes were serialized, what
+ * owned the client and for how long, how the loops and verifications went, and whether any span is
+ * still open. This module answers exactly those, from the lines alone, so it can be tested without a
+ * file and reused by a future `--json` consumer.
+ *
+ * It never re-derives a fact the trace did not record: an event it does not know is counted as
+ * skipped rather than guessed at.
+ */
+/** Count one key in a tally. */
+function count(tally, key) {
+    tally[key] = (tally[key] ?? 0) + 1;
+}
+/** Name one loop run in a report; a pre-`runId` trace has no identity to show. */
+function label(runId) { return runId === '' ? '<no-run-id>' : runId; }
+/** Read the identifier a span pairs on, or undefined when the event carries none. */
+function spanId(record) {
+    for (const field of ['commandId', 'id', 'runId']) {
+        const value = record[field];
+        if (typeof value === 'string' || typeof value === 'number')
+            return String(value);
+    }
+    return undefined;
+}
+/** Summarize one trace file's lines.
+ * @param lines - Raw trace lines, oldest first, header and blanks included.
+ * @param path - File the lines came from, for the report.
+ * @returns The summary a reader wants.
+ */
+export function summarizeTrace(lines, path = '') {
+    const outcomes = {};
+    const kinds = {};
+    const lanes = {};
+    const sessions = {};
+    const byClass = {};
+    const runs = new Map();
+    const openCommands = new Map();
+    const openOperations = new Map();
+    const openLoops = new Map();
+    const orphans = [];
+    const anomalies = [];
+    let events = 0;
+    let skipped = 0;
+    let from;
+    let to;
+    let commandEnds = 0;
+    let operations = 0;
+    let cancelled = 0;
+    let longestMs;
+    let longest;
+    let verifierBegins = 0;
+    let verified = 0;
+    let unavailable = 0;
+    let verifierCancelled = 0;
+    for (const line of lines) {
+        if (line === '' || line.startsWith('#'))
+            continue;
+        let record;
+        try {
+            record = JSON.parse(line);
+        }
+        catch {
+            skipped++;
+            continue;
+        }
+        if (typeof record.event !== 'string') {
+            skipped++;
+            continue;
+        }
+        events++;
+        const time = typeof record.time === 'string' ? record.time : undefined;
+        if (time !== undefined) {
+            from ??= time;
+            to = time;
+        }
+        const id = spanId(record);
+        switch (record.event) {
+            case 'command': {
+                if (record.phase === 'begin') {
+                    if (id !== undefined)
+                        openCommands.set(id, String(record.kind ?? 'unknown'));
+                    break;
+                }
+                // A held line was accepted but not run; only a `begin`/`end` pair is an execution.
+                if (record.phase === 'queued')
+                    break;
+                commandEnds++;
+                const paired = id !== undefined && openCommands.delete(id);
+                // A trace written before `command begin/end` has one phaseless event per line, whose fate is
+                // the old `accepted` flag; reading it as an end keeps an existing file useful, and a phaseless
+                // line is never reported as an orphan end.
+                if (record.phase === 'end' && id !== undefined && !paired) {
+                    orphans.push(`command ${id} (${String(record.kind ?? 'unknown')}): end without begin`);
+                }
+                const outcome = typeof record.outcome === 'string' ? record.outcome : record.accepted === true ? 'ok' : 'rejected';
+                count(outcomes, outcome);
+                count(kinds, String(record.kind ?? 'unknown'));
+                break;
+            }
+            case 'mutation':
+                count(lanes, String(record.lane ?? 'unknown'));
+                count(sessions, String(record.session ?? 'unknown'));
+                break;
+            case 'foreground': {
+                if (record.phase === 'begin') {
+                    operations++;
+                    if (id !== undefined)
+                        openOperations.set(id, { label: String(record.label ?? record.kind ?? ''), startedAt: time === undefined ? 0 : Date.parse(time) });
+                    break;
+                }
+                if (id === undefined)
+                    break;
+                const started = openOperations.get(id);
+                openOperations.delete(id);
+                if (started === undefined)
+                    orphans.push(`foreground ${id}: end without begin`);
+                if (record.cancelled === true)
+                    cancelled++;
+                if (started !== undefined && time !== undefined) {
+                    const ms = Date.parse(time) - started.startedAt;
+                    if (Number.isFinite(ms) && (longestMs === undefined || ms > longestMs)) {
+                        longestMs = ms;
+                        longest = started.label;
+                    }
+                }
+                break;
+            }
+            case 'loop': {
+                // Events that describe a submission rather than a run (`command`, `form`, `rejected`) are not
+                // a run and must not invent one. A trace written before `runId` existed has one key for the
+                // run events it did record; they still pair, they just cannot be told apart per run.
+                const runId = typeof record.runId === 'string' ? record.runId : undefined;
+                const describesRun = runId !== undefined || record.phase === 'begin' || record.phase === 'sent' || record.phase === 'end';
+                if (!describesRun)
+                    break;
+                const key = runId ?? '';
+                const run = runs.get(key) ?? { kind: 'unknown', sent: 0 };
+                if (typeof record.kind === 'string')
+                    run.kind = record.kind;
+                if (record.phase === 'begin')
+                    openLoops.set(key, run.kind);
+                if (record.phase === 'sent')
+                    run.sent++;
+                if (record.phase === 'end') {
+                    if (!openLoops.delete(key))
+                        orphans.push(`loop ${label(key)} (${run.kind}): end without begin`);
+                    run.result = String(record.result ?? 'unknown');
+                    if (record.reason !== undefined)
+                        run.reason = String(record.reason);
+                }
+                runs.set(key, run);
+                break;
+            }
+            case 'verify': {
+                if (record.phase === 'begin') {
+                    verifierBegins++;
+                    break;
+                }
+                if (record.phase === 'verified') {
+                    verified++;
+                    break;
+                }
+                if (record.phase === 'cancelled' || record.phase === 'abandoned') {
+                    verifierCancelled++;
+                    break;
+                }
+                if (record.phase === 'unavailable') {
+                    unavailable++;
+                    const match = /stderrClass (\w+)/.exec(String(record.reason ?? ''));
+                    if (match?.[1] !== undefined)
+                        count(byClass, match[1]);
+                }
+                break;
+            }
+            default: break;
+        }
+    }
+    for (const [id, kind] of openCommands)
+        anomalies.push(`command ${id} (${kind}): begin without end`);
+    for (const id of openOperations.keys())
+        anomalies.push(`foreground ${id}: begin without end`);
+    for (const [runId, kind] of openLoops)
+        anomalies.push(`loop ${label(runId)} (${kind}): begin without end`);
+    // An end whose begin is missing means the window dropped it or the writer is broken; either way the
+    // reader has to see it, because the pairing is what makes the rest of the file trustworthy.
+    anomalies.push(...orphans);
+    return {
+        path, events, skipped,
+        ...(from === undefined ? {} : { from }),
+        ...(to === undefined ? {} : { to }),
+        commands: { total: commandEnds, outcomes, kinds },
+        mutations: { total: Object.values(lanes).reduce((sum, value) => sum + value, 0), lanes, sessions },
+        operations: { total: operations, cancelled, ...(longestMs === undefined ? {} : { longestMs, longest }), open: openOperations.size },
+        loops: [...runs.entries()].map(([runId, run]) => ({ runId, ...run })),
+        verifiers: { begin: verifierBegins, verified, unavailable, cancelled: verifierCancelled, byClass },
+        anomalies,
+    };
+}
+/** Render one tally as `key value · key value`, widest count first. */
+function tally(text) {
+    return Object.entries(text).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+        .map(([key, value]) => `${key} ${value}`).join(' · ');
+}
+/** Render a summary as the lines `dsht trace` prints.
+ * @param summary - Result of `summarizeTrace`.
+ * @returns Plain lines, one fact per line, without a trailing newline.
+ */
+export function formatTraceSummary(summary) {
+    const lines = [`trace · ${summary.path}`, `events ${summary.events}${summary.skipped === 0 ? '' : ` (+${summary.skipped} unreadable)`}`
+            + `${summary.from === undefined ? '' : ` · ${summary.from} → ${summary.to}`}`];
+    if (summary.commands.total > 0) {
+        lines.push(`commands ${summary.commands.total}: ${tally(summary.commands.outcomes)}`);
+        lines.push(`  kinds: ${tally(summary.commands.kinds)}`);
+    }
+    if (summary.mutations.total > 0) {
+        lines.push(`session writes ${summary.mutations.total}: ${tally(summary.mutations.lanes)}`);
+        lines.push(`  by session: ${tally(summary.mutations.sessions)}`);
+    }
+    const { longestMs, longest } = summary.operations;
+    if (summary.operations.total > 0) {
+        const slowest = longestMs === undefined ? '' : ` · longest ${(longestMs / 1000).toFixed(1)}s (${longest})`;
+        lines.push(`foreground ${summary.operations.total}: cancelled ${summary.operations.cancelled}${slowest}`);
+    }
+    for (const run of summary.loops) {
+        const end = run.result === undefined ? 'unfinished' : `${run.result}${run.reason === undefined ? '' : ` (${run.reason})`}`;
+        lines.push(`loop ${label(run.runId)} · ${run.kind} · sent ${run.sent} → ${end}`);
+    }
+    const { begin, verified, unavailable, cancelled: verifierCancelled, byClass } = summary.verifiers;
+    if (begin > 0 || verified + unavailable + verifierCancelled > 0) {
+        const classes = Object.keys(byClass).length === 0 ? '' : ` (${tally(byClass)})`;
+        const concluded = verified + unavailable + verifierCancelled;
+        lines.push(`verifiers: begin ${begin} · verified ${verified} · unavailable ${unavailable}${classes}`
+            + ` · cancelled ${verifierCancelled}`
+            + (begin > concluded ? ` · ${begin - concluded} without a conclusion` : ''));
+    }
+    for (const anomaly of summary.anomalies)
+        lines.push(`anomaly · ${anomaly}`);
+    return lines;
+}