@itookit/dsht 0.3.8 → 0.5.1

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;
+}

package/dist/cli/verifier.d.ts

@@ -0,0 +1,60 @@
+import { runProcess } from '../shell/index.ts';
+import type { VerifierOutcome, VerifierPort, VerifierRequest } from '../controller/verifier.ts';
+/** What a child's error output says about why it failed, without carrying the output itself.
+ *
+ * A reason travels into the progress line, the verdict summary and the trace, and that log may be
+ * pasted into a report; the child's own words can name paths, projects or credentials. The class is
+ * the actionable half: `auth` and `host` are worth retrying differently, `config` never is.
+ */
+export type VerifierStderrClass = 'auth' | 'host' | 'config' | 'unknown';
+/** Classify a child's captured error output.
+ * @param text - Everything the child wrote to stderr, bounded by the caller.
+ * @returns The most actionable class the output matches.
+ */
+export declare function classifyVerifierOutput(text: string): VerifierStderrClass;
+/** Name the fault the child reported about itself, when this client wrote that line.
+ * @param text - Everything the child wrote to stderr.
+ * @returns The fault as one clause, or undefined when nothing recognized is there.
+ */
+export declare function childFault(text: string): string | undefined;
+/** Everything a forked verification needs from the client that owns it. */
+export interface ProcessVerifierOptions {
+    /** Program and arguments that start this client again: exec path, exec arguments, entry script. */
+    command: readonly string[];
+    /** Host URL as the operator gave it, so the child authenticates the same way. */
+    url: string;
+    /** Cookie directory the parent used, when it was explicit. */
+    authDir?: string;
+    /** Working directory for the child. */
+    cwd: string;
+    /** Environment for the child; it inherits the parent's, including DSH_TOKEN. */
+    env: NodeJS.ProcessEnv;
+    /** How long one verification may run. */
+    timeoutMs: number;
+    /** Creates the verifier's own session and names it; the controller owns the connection. */
+    createSession(title: string): Promise<string | undefined>;
+    /** Stops that session's turn on the host; without it a killed child leaves the agent running. */
+    cancelSession?(sessionId: string): Promise<void>;
+    /** Receives the child's output lines, so the parent can log why a verdict is missing. */
+    onLine(line: string, stream: 'stdout' | 'stderr'): void;
+    /** Quote the child's own (sanitized) words in a reason; off by default because that text leaves. */
+    verbose?: boolean;
+    /** Process runner, injectable so the logic can be tested without spawning a client. */
+    run?: typeof runProcess;
+}
+/** Run one verifier as a child client and read the file it leaves behind.
+ *
+ * The child is the same program as the parent but a different session, so it starts from an empty
+ * context: the prompt, the standard and the artifact on disk are all it knows.
+ */
+export declare class ProcessVerifier implements VerifierPort {
+    private readonly options;
+    /** This client forks itself, so the harness that judges is this one. */
+    readonly name = "dsht";
+    constructor(options: ProcessVerifierOptions);
+    /** @param request - Round identity, prompt and verdict path.
+     *  @param signal - Cancels the child; the run also stops at its own deadline.
+     *  @returns The verdict read back from the file, or a note explaining its absence.
+     */
+    verify(request: VerifierRequest, signal: AbortSignal): Promise<VerifierOutcome>;
+}

package/dist/cli/verifier.js

@@ -0,0 +1,242 @@
+/** Verification by a child `dsht` process: its own session, its own context, a file back.
+ *
+ * The reviewed session cannot judge itself fairly, and an in-host subagent still shares the process
+ * that produced the work. This implementation forks the client itself, points the child at a fresh
+ * named session, and reads the verdict file that session writes — so the verdict arrives through a
+ * file written on disk rather than through the reviewer's own reply.
+ */
+import { createHash } from 'node:crypto';
+import { dirname, join } from 'node:path';
+import { runProcess } from "../shell/index.js";
+import { ensureDirectory, readText, removeFile } from "../storage/index.js";
+import { parseVerdict } from "../controller/loop-contract.js";
+import { sanitizeTraceText } from "../text.js";
+import { parseNeedsHumanLine } from "../controller/verifier.js";
+/** How long a cancellation request may wait for the host's answer before local cleanup proceeds. */
+const CANCEL_CONFIRM_MS = 1_000;
+/** How much of the child's error output is kept to classify it; the text itself is never reported. */
+const VERIFIER_STDERR_LIMIT = 4_096;
+/** Classify a child's captured error output.
+ * @param text - Everything the child wrote to stderr, bounded by the caller.
+ * @returns The most actionable class the output matches.
+ */
+export function classifyVerifierOutput(text) {
+    if (/unauthor|forbidden|401|403|credential|log ?in|token/i.test(text))
+        return 'auth';
+    if (/econnrefused|econnreset|enotfound|fetch failed|timed? ?out|socket|50[234]|unreachable/i.test(text))
+        return 'host';
+    if (/config|yaml|invalid|missing|enoent|no such file|usage|unknown option/i.test(text))
+        return 'config';
+    return 'unknown';
+}
+/** The faults this client's own child reports on stderr, named so a missing verdict explains itself.
+ *
+ * These sentences are written by `runStartup` in this same program, so naming them leaks nothing and
+ * needs no model text: the alternative is the keyword class below, which reads our own diagnosis as
+ * `unknown`. Anything else the child writes still goes through that class.
+ */
+const CHILD_FAULTS = [
+    { pattern: /no parsable verdict in the reply/i, note: 'no JSON verdict in the reply' },
+    { pattern: /no reply was committed after the prompt/i, note: 'no reply committed after the turn' },
+];
+/** Name the fault the child reported about itself, when this client wrote that line.
+ * @param text - Everything the child wrote to stderr.
+ * @returns The fault as one clause, or undefined when nothing recognized is there.
+ */
+export function childFault(text) {
+    return CHILD_FAULTS.find(fault => fault.pattern.test(text))?.note;
+}
+/** Content fingerprint of a workspace file, or undefined when it cannot be read from here.
+ *
+ * A remote host's workspace is not on this filesystem, so an unreadable artifact means the check
+ * cannot be made — which is reported as a boundary rather than treated as tampering.
+ * @param path - Absolute path of the file.
+ * @returns SHA-256 of its text, or undefined when it is not readable.
+ */
+async function fingerprint(path) {
+    const text = await readText(path);
+    return text === undefined ? undefined : createHash('sha256').update(text).digest('hex');
+}
+/** Run one verifier as a child client and read the file it leaves behind.
+ *
+ * The child is the same program as the parent but a different session, so it starts from an empty
+ * context: the prompt, the standard and the artifact on disk are all it knows.
+ */
+export class ProcessVerifier {
+    options;
+    /** This client forks itself, so the harness that judges is this one. */
+    name = 'dsht';
+    constructor(options) {
+        this.options = options;
+    }
+    /** @param request - Round identity, prompt and verdict path.
+     *  @param signal - Cancels the child; the run also stops at its own deadline.
+     *  @returns The verdict read back from the file, or a note explaining its absence.
+     */
+    async verify(request, signal) {
+        const run = this.options.run ?? runProcess;
+        const file = request.file;
+        // Cancelled before anything happened: no session, no child, no verdict file.
+        if (signal.aborted)
+            return { type: 'cancelled' };
+        await ensureDirectory(dirname(file));
+        // A verdict left by an earlier run must never be read as this one's.
+        await removeFile(file);
+        // "Do not modify the artifact" is an instruction until it can be checked: fingerprint it when
+        // the workspace this request declares is readable from here, and let a changed artifact void the
+        // verdict. Which file that is comes from the request, never from this process's own directory.
+        const artifactPath = request.artifact === undefined ? undefined : join(request.workspace, request.artifact);
+        const before = artifactPath === undefined ? undefined : await fingerprint(artifactPath);
+        const controller = new AbortController();
+        let sessionId;
+        let cancelled = false;
+        let timedOut = false;
+        /** Settles when the host answered the cancel request, so the outcome can say if it was confirmed. */
+        let confirmation;
+        let confirmed;
+        // The host owns the turn, so a killed child proves nothing about it. Cancellation is therefore a
+        // request with a short, bounded wait: local cleanup never blocks on a host that never answers.
+        const requestCancel = (id) => {
+            const cancel = this.options.cancelSession;
+            if (cancel === undefined || confirmation !== undefined)
+                return;
+            confirmation = Promise.resolve(cancel(id)).then(() => { confirmed = true; }, () => { confirmed = false; });
+        };
+        const stop = () => {
+            if (sessionId !== undefined)
+                requestCancel(sessionId);
+            controller.abort();
+        };
+        const onAbort = () => { cancelled = true; stop(); };
+        const onTimeout = () => { timedOut = true; stop(); };
+        const timer = setTimeout(onTimeout, this.options.timeoutMs);
+        // Registered before the session exists, so an abort during creation cannot slip past the listener.
+        signal.addEventListener('abort', onAbort, { once: true });
+        if (signal.aborted)
+            onAbort();
+        /** How the remote cancellation ended, and whether the remote turn is known to be stopped.
+         *
+         * `stopped: false` is what forbids a retry: starting a second remote task while the first may
+         * still be running doubles the cost and the side effects.
+         */
+        const cancelNote = async () => {
+            if (confirmation === undefined) {
+                return this.options.cancelSession === undefined
+                    ? { note: 'host cannot cancel', stopped: false }
+                    : { note: 'no verifier session to cancel', stopped: true };
+            }
+            const settled = await Promise.race([
+                confirmation.then(() => true),
+                new Promise(resolve => { const wait = setTimeout(() => resolve(false), CANCEL_CONFIRM_MS); wait.unref(); }),
+            ]);
+            if (!settled)
+                return { note: `remote cancel unconfirmed after ${CANCEL_CONFIRM_MS} ms`, stopped: false };
+            return confirmed === true
+                ? { note: 'remote cancel confirmed', stopped: true }
+                : { note: 'remote cancel rejected', stopped: false };
+        };
+        try {
+            const created = await this.options.createSession(request.title);
+            if (created === undefined)
+                return { type: 'unavailable', reason: 'could not create a verifier session' };
+            sessionId = created;
+            if (cancelled || timedOut) {
+                // The abort or the deadline landed while the session was being created: cancel what was just
+                // made and never spawn a child that would send a prompt nobody is waiting for.
+                requestCancel(created);
+                const { note, stopped } = await cancelNote();
+                return cancelled
+                    ? { type: 'cancelled' }
+                    : { type: 'unavailable', reason: `verifier timed out after ${this.options.timeoutMs} ms · ${note}`, sessionId,
+                        ...(stopped ? {} : { retryable: false }) };
+            }
+            const [program, ...leading] = this.options.command;
+            // A missing entry is a configuration error, not an outage: retrying cannot fix it.
+            if (program === undefined)
+                return { type: 'unavailable', reason: 'no client entry to fork', retryable: false };
+            const args = [...leading,
+                '--url', this.options.url,
+                ...(this.options.authDir === undefined ? [] : ['--auth-dir', this.options.authDir]),
+                '--session', created,
+                '--prompt', request.prompt,
+                // The child judges and this client owns the protocol file, so the verdict is written by the
+                // child from its own reply rather than by the model choosing a path and opening a file.
+                '--verdict', file, '--verdict-identity', request.verificationId,
+                '--wait', '--headless', '--no-memory-log'];
+            // The child reports an interaction it cannot answer on the line below; the same parser keeps
+            // both sides of the contract together, and every other line is passed through untouched.
+            let human;
+            // The child's output is kept only to classify why it failed: `stderrText` for the class, and the
+            // last line for the operator who explicitly asked for text (`--trace-verbose`). Neither is
+            // reported by default, because a reason reaches the progress line and the trace, and that log
+            // may be pasted into a report.
+            let stderrText = '';
+            let lastLine = '';
+            const onLine = (line, stream) => {
+                human ??= parseNeedsHumanLine(line);
+                const trimmed = line.trim();
+                if (trimmed !== '') {
+                    lastLine = trimmed;
+                    if (stream === 'stderr')
+                        stderrText = `${stderrText}${trimmed}\n`.slice(-VERIFIER_STDERR_LIMIT);
+                }
+                this.options.onLine(line, stream);
+            };
+            /** A missing or unusable verdict stated as facts, with the child's words only on request. */
+            const reasonFor = (lead) => {
+                // What this client's own child said about the failure beats the keyword class: "no JSON in the
+                // reply" and "no reply committed" are different faults with different next steps, and both used
+                // to be reported as `stderrClass unknown`. A child that said nothing gets no class at all,
+                // because "unknown" would be noise on the ordinary "exited without writing a file" case.
+                const fault = childFault(stderrText);
+                const base = fault !== undefined ? `${lead} · ${fault}`
+                    : stderrText === '' ? lead : `${lead} · stderrClass ${classifyVerifierOutput(stderrText)}`;
+                return this.options.verbose === true && lastLine !== '' ? `${base} · ${sanitizeTraceText(lastLine)}` : base;
+            };
+            const exit = await run(program, args, {
+                cwd: this.options.cwd, env: this.options.env, signal: controller.signal, onLine,
+            });
+            // A cancelled review decides nothing, and is not a verifier outage either.
+            if (cancelled)
+                return { type: 'cancelled' };
+            // The child stopped because the host wants a human: cancel the turn it left waiting (bounded,
+            // reported), and hand the request to the caller instead of retrying into the same block.
+            if (human !== undefined) {
+                requestCancel(created);
+                await cancelNote();
+                return { type: 'needs-human', request: human, sessionId };
+            }
+            // A task that ran out of time is abandoned: a file that appeared as it died must not decide
+            // the attempt, or a killed verifier could still pass the round. When the host never confirmed
+            // the cancel, a retry could overlap a turn that is still running, so it is not offered one.
+            if (timedOut) {
+                const { note, stopped } = await cancelNote();
+                return { type: 'unavailable', reason: `verifier timed out after ${this.options.timeoutMs} ms · ${note}`, sessionId,
+                    ...(stopped ? {} : { retryable: false }) };
+            }
+            const text = await readText(file);
+            if (text === undefined) {
+                const why = exit.code === null ? `signal ${exit.signal ?? 'unknown'}` : `exit ${exit.code}`;
+                return { type: 'unavailable', reason: reasonFor(`verifier wrote no verdict (${why})`), sessionId };
+            }
+            if (before !== undefined) {
+                const after = artifactPath === undefined ? undefined : await fingerprint(artifactPath);
+                // Which process wrote it is not knowable here, so the reason states the fact rather than an
+                // attribution: the file this verdict is about is not the file that was judged.
+                if (after !== before) {
+                    return { type: 'unavailable', sessionId,
+                        reason: `reviewed artifact changed during verification (${request.artifact} · ${before.slice(0, 8)} → ${after?.slice(0, 8) ?? 'unreadable'})` };
+                }
+            }
+            const result = parseVerdict(text, { verificationId: request.verificationId,
+                kind: request.kind, step: request.step, attempt: request.attempt });
+            if (result === undefined)
+                return { type: 'unavailable', reason: reasonFor('verifier verdict was unusable'), sessionId };
+            return { type: 'verified', result, sessionId };
+        }
+        finally {
+            clearTimeout(timer);
+            signal.removeEventListener('abort', onAbort);
+        }
+    }
+}