humanish 0.111.4 → 0.113.0

package/dist/run/display.js

@@ -2,7 +2,8 @@
 // library, `humanish runs`, `humanish stats` and review.md. Each of them calls runDisplay with the
 // same facts, so a run whose own ok is false shows as a pass on none of them, and two surfaces
 // cannot disagree about one run.
-import { classifyRunStatus, isRunStatusRecord } from "./status.js";
+import {} from "./status.js";
+import { runLiveness } from "./liveness.js";
 import { plural } from "./text.js";
 const LABELS = {
     running: "running",
@@ -72,38 +73,34 @@ function runDisplayLine(display) {
  * The facts for a run from its bundle. run.json's `outcome` decides when it has one. A bundle
  * without one is in progress, or was recorded before the field existed: its status record, when
  * given and naming the run, then says whether the run is alive and, for the older run, holds its ok.
- * With no record, a bundle whose simulations are still running is live.
+ * With no record, a bundle whose simulations are still running is interrupted.
  */
 export function bundleDisplayFacts(bundle, status, nowMs = Date.now()) {
-    const base = { mode: bundle.mode, verdict: bundle.review?.verdict };
+    const { liveness, record } = runLiveness(bundle.runId, status, bundle, nowMs);
+    const base = { liveness, mode: bundle.mode, verdict: bundle.review?.verdict };
     const outcome = bundle.outcome;
     if (outcome?.state === "interrupted")
-        return { ...base, liveness: "interrupted" };
+        return base;
     if (outcome?.state === "finished")
         return {
             ...base,
-            liveness: "finished",
             ok: outcome.ok,
             failure: outcome.execution.failures[0],
         };
-    if (isRunStatusRecord(status) && status.runId === bundle.runId)
-        return {
-            ...base,
-            liveness: classifyRunStatus(status, nowMs),
-            ...(typeof status.outcome?.ok === "boolean" ? { ok: status.outcome.ok } : {}),
-            ...(status.outcome?.execution?.failures[0] === undefined
-                ? {}
-                : { failure: status.outcome.execution.failures[0] }),
-        };
-    const inProgress = (bundle.simulations ?? []).some((simulation) => simulation?.status === "running");
-    return { ...base, liveness: inProgress ? "running" : "finished" };
+    return {
+        ...base,
+        ...(typeof record?.outcome?.ok === "boolean" ? { ok: record.outcome.ok } : {}),
+        ...(record?.outcome?.execution?.failures[0] === undefined
+            ? {}
+            : { failure: record.outcome.execution.failures[0] }),
+    };
 }
 /**
  * How review.md says the run ended: the display of the bundle it is rendered from, so a run whose
  * execution failed never reads as a pass beside its participants' verdict.
  */
-export function reviewOutcome(bundle) {
-    return runDisplayLine(runDisplay(bundleDisplayFacts(bundle)));
+export function reviewOutcome(bundle, status) {
+    return runDisplayLine(runDisplay(bundleDisplayFacts(bundle, status)));
 }
 /**
  * The summary and gaps a review shows beside its run's display. A run stopped while a participant

package/dist/run/dry-run.js

@@ -9,8 +9,8 @@ import {} from "./streams.js";
 import { participantEvent, participantIdsOf, participantRecord, participantStream, } from "./participant-records.js";
 import { implicitProjectDirectoryExists, readPackageName, validateCwd } from "./project.js";
 import { loadDryRunInputs } from "./dry-run-inputs.js";
-import { judgeExecution, judgePreview, OUTCOME_POLICIES, resultOk, verdictText, } from "./judge.js";
-import { reviewOutcome } from "./display.js";
+import { judgeExecution, judgePreview, OUTCOME_POLICIES, resultOk } from "./judge.js";
+import { renderReviewMarkdown } from "./review-markdown.js";
 import { cli } from "../cli/invocation.js";
 /**
  * The preview route's run. The run scope closes the run it started on every exit, including
@@ -68,7 +68,7 @@ async function runDryRunInScope(options, scope) {
         mode: options.dryRun ? "dry-run" : "live",
         study: options.study,
         warnings: options.warnings,
-        renderReview: renderReviewMarkdown,
+        renderReview: renderPreviewReview,
         // The run starts at the time its id and source were stamped with.
         now: () => Date.parse(createdAt),
         ...(options.observer === undefined ? {} : { observer: { open: options.observer.open } }),
@@ -170,28 +170,13 @@ function createReviewSummary(verdict) {
     };
 }
 /** The preview's review.md. */
-function renderReviewMarkdown(bundle) {
-    return `# humanish Run Review
-
-Run: ${bundle.runId}
-
-Mode: ${bundle.mode}
-
-Verdict: ${verdictText(bundle.review.verdict, bundle.mode)}
-
-Outcome: ${reviewOutcome(bundle)}
-
-${bundle.review.summary}
-
-## Public-Safety
-
-- Redaction: ${bundle.redaction.status}
-- Notes: ${bundle.redaction.notes}
-
-## Gaps
-
-${bundle.review.gaps.map((gap) => `- ${gap}`).join("\n")}
-`;
+function renderPreviewReview(bundle, status) {
+    return renderReviewMarkdown(bundle, [
+        "## Public-Safety",
+        "",
+        `- Redaction: ${bundle.redaction.status}`,
+        `- Notes: ${bundle.redaction.notes}`,
+    ], { style: "preview", status });
 }
 /**
  * Render through the finished run, so a directory swapped in under the same id is never rendered.

package/dist/run/judge.d.ts

@@ -41,6 +41,30 @@ export interface ParticipantFacts {
     /** selfReportedBlocker held for its session. */
     selfReportedBlocker: boolean;
 }
+/** The participant facts its bundle and result can name. */
+export interface ParticipantRecordFacts extends ParticipantFacts {
+    id?: string;
+    reason?: string;
+    skippedReason?: string;
+    reportedFriction?: boolean;
+    inProgress?: boolean;
+}
+/** Judge participant evidence for the bundle and the result in the same order. */
+export declare function judgeParticipantRecords(participants: readonly ParticipantRecordFacts[], wording?: {
+    sessionLabel?: string;
+    missingSessionMessage?: string;
+    runningReason?: string;
+    contractReason?: string;
+}): {
+    participants: {
+        status: "abandoned" | "blocked" | "contract_proof_only" | "failed" | "incomplete" | "passed" | "running" | "timed_out";
+        judgedStatus: "abandoned" | "blocked" | "failed" | "incomplete" | "passed" | "timed_out" | undefined;
+        reason: string;
+        notPassedMessage: string;
+        gapLine: string | undefined;
+    }[];
+    tally: import("./bundle.js").ParticipantOutcomes;
+};
 /**
  * The status a participant is judged under. A harness failure is failed, and a skipped participant
  * is blocked, as the fan-out bundle and the result write it. Otherwise it is the tallied

package/dist/run/judge.js

@@ -12,6 +12,7 @@
 //   4. foldScorerFailures, which every route with a scorer applies before the run finishes;
 //   5. the outcome: judgeExecution applies the route's policy to its execution failures, and
 //      resultOk gives the result's ok.
+import { tallyParticipantOutcomes } from "./outcomes.js";
 import { cli } from "../cli/invocation.js";
 /**
  * The participant said it reached the goal having taken no action and said nothing, and no stop
@@ -35,6 +36,59 @@ export function selfReportedBlocker(ending) {
         ending.closingReportReadsBlocked &&
         !ending.stopConditionMatched);
 }
+/** Judge participant evidence for the bundle and the result in the same order. */
+export function judgeParticipantRecords(participants, wording = {}) {
+    const records = participants.map((participant) => {
+        const status = participant.inProgress
+            ? "running"
+            : participant.skipped
+                ? "blocked"
+                : (participant.status ??
+                    (participant.sessionError === undefined ? "contract_proof_only" : "failed"));
+        const judged = participant.inProgress ? undefined : judgedStatus(participant);
+        return {
+            status,
+            judgedStatus: judged,
+            reason: participant.inProgress
+                ? (wording.runningReason ??
+                    "Live computer-use session is running; stream auth URL is available only through the attached Observer server.")
+                : (participant.skippedReason ??
+                    participant.reason ??
+                    participant.sessionError ??
+                    wording.contractReason ??
+                    "Dry run: the evidence shape was written without launching a desktop or spending provider tokens."),
+            notPassedMessage: participantNotPassedMessage(participant, wording),
+            gapLine: participant.inProgress || judged === "passed"
+                ? undefined
+                : `${participant.id ?? "Participant"}: ${participant.skippedReason ?? participant.sessionError ?? participant.reason ?? "did not pass"}`,
+        };
+    });
+    const terminal = records.filter((_, index) => participants[index].status !== undefined && !participants[index].inProgress);
+    return {
+        participants: records,
+        tally: tallyParticipantOutcomes(terminal.map((participant) => participant.judgedStatus), participants
+            .filter((participant) => participant.status !== undefined && !participant.inProgress)
+            .map((participant) => participant.reportedFriction === true)),
+    };
+}
+function participantNotPassedMessage(participant, wording) {
+    const label = wording.sessionLabel ?? "Computer-use session";
+    if (participant.sessionError !== undefined)
+        return participant.sessionError;
+    if (participant.skippedReason !== undefined)
+        return participant.skippedReason;
+    if (participant.noEngagement)
+        return "Actor took no actions and produced no message (likely a blank/still-loading screen); not a credible goal_satisfied.";
+    if (participant.selfReportedBlocker)
+        return "Actor reported goal_satisfied while its final message described a blocker or asked for missing instructions; not a credible pass.";
+    if (participant.completionReason === "harness_error")
+        return `${label} ended with a harness error: ${participant.reason}`;
+    if (participant.status === undefined && wording.missingSessionMessage !== undefined)
+        return wording.missingSessionMessage;
+    if (participant.status !== "passed")
+        return `${label} ended with ${participant.status ?? "unknown"}: ${participant.reason ?? "no terminal reason"}`;
+    return (wording.missingSessionMessage ?? "The computer-use run did not produce a terminal session.");
+}
 /**
  * The status a participant is judged under. A harness failure is failed, and a skipped participant
  * is blocked, as the fan-out bundle and the result write it. Otherwise it is the tallied

package/dist/run/liveness.d.ts

@@ -0,0 +1,18 @@
+import type { RunOutcome } from "./bundle.js";
+import { type RunLiveness, type RunStatusRecord } from "./status.js";
+interface LivenessBundle {
+    simulations?: ReadonlyArray<{
+        status?: string | undefined;
+    } | undefined> | undefined;
+    outcome?: RunOutcome | undefined;
+}
+/**
+ * One run's liveness: the bundle outcome, then usable status, then bundle-only evidence.
+ * `readRunIndex` reads in the same order; `humanish verify` calls this with both in hand. `record`
+ * is the status record the liveness came from, when there was one.
+ */
+export declare function runLiveness(runId: string, status: unknown, bundle: LivenessBundle, nowMs: number): {
+    liveness: RunLiveness;
+    record?: RunStatusRecord;
+};
+export {};

package/dist/run/liveness.js

@@ -0,0 +1,24 @@
+import { classifyRunStatus, isRunStatusRecord, } from "./status.js";
+/**
+ * The bundle-only reading, for a run with no usable status record. A bundle on disk usually means
+ * the run reached its final write. But a live run now flushes an in-progress bundle as it goes (so
+ * anything asking what a participant is doing has something to read), and that bundle marks its
+ * simulations `running`. With no status record there is no freshness to judge, and the
+ * reading of "it started, and nothing here says it finished" is interrupted, not finished.
+ */
+function bundleLiveness(bundle) {
+    const inProgress = (bundle.simulations ?? []).some((simulation) => simulation?.status === "running");
+    return inProgress ? "interrupted" : "finished";
+}
+/**
+ * One run's liveness: the bundle outcome, then usable status, then bundle-only evidence.
+ * `readRunIndex` reads in the same order; `humanish verify` calls this with both in hand. `record`
+ * is the status record the liveness came from, when there was one.
+ */
+export function runLiveness(runId, status, bundle, nowMs) {
+    if (bundle.outcome !== undefined)
+        return { liveness: bundle.outcome.state };
+    return isRunStatusRecord(status) && status.runId === runId
+        ? { liveness: classifyRunStatus(status, nowMs), record: status }
+        : { liveness: bundleLiveness(bundle) };
+}

package/dist/run/outcomes.d.ts

@@ -1,4 +1,4 @@
-import { type ActorStatus } from "../actors/contract.js";
+import { type ActorStatus, type ActorTrace } from "../actors/contract.js";
 import { type CuaGoalSource } from "../actors/goal-source.js";
 import type { TaskFunnel } from "../study/tasks.js";
 import type { ParticipantOutcomes, ReviewSummary, RunTaskFunnel } from "./bundle.js";
@@ -16,6 +16,13 @@ type ParticipantOutcomeDetail = {
     label?: string;
     goalSource?: CuaGoalSource;
 };
+/**
+ * How one participant's session ended, in words a participant summary can end on. A computer-use
+ * goal says where the claim came from, as the run's participant line does.
+ */
+export declare function sessionEndingInWords(trace: ActorTrace): string;
+/** "; the gaps list the other 2", or "all 3" when nobody passed. Empty when the gaps list nobody. */
+export declare function gapsListClause(listed: number, total: number): string;
 /** One line a stakeholder can read, with the denominator attached to every number. */
 export declare function formatParticipantOutcomes(outcomes: ParticipantOutcomes, terminalCauses?: readonly ParticipantOutcomeDetail[]): string;
 /** Presentation details tolerate optional legacy actor payloads without changing their tallies. */

package/dist/run/outcomes.js

@@ -1,6 +1,7 @@
 import { ACTOR_STATUSES } from "../actors/contract.js";
 import { cuaGoalSource, isCuaTrace, CUA_COMPLETION_NOTE, } from "../actors/goal-source.js";
 import { actorEnding } from "../actors/stop-cause.js";
+import { plural } from "./text.js";
 import { isNonNegativeSafeInteger, isRecord } from "./type-guards.js";
 /** Tally participant outcomes from actor statuses. Statuses this does not recognise are counted in
  *  `total` but nowhere else, so the parts can never exceed the whole. */
@@ -113,6 +114,46 @@ function participantCompletionLine(outcomes, terminalCauses) {
     }
     return goalLine;
 }
+/**
+ * How one participant's session ended, in words a participant summary can end on. A computer-use
+ * goal says where the claim came from, as the run's participant line does.
+ */
+export function sessionEndingInWords(trace) {
+    switch (trace.completionReason) {
+        case "goal_satisfied": {
+            const source = cuaGoalSource(trace);
+            if (source === "participant_report")
+                return "reported reaching the goal";
+            return source === "condition_matched" ? "met its completion condition" : "reached the goal";
+        }
+        case "turn_completed":
+            return "said it was done";
+        case "gave_up":
+            return "gave up";
+        case "blocked_approval":
+            return "was blocked waiting for an approval";
+        case "timed_out":
+            return "ran out of time";
+        case "budget_reached":
+            return "was stopped by a time or spend limit";
+        case "actor_error":
+            return "stopped on an error";
+        case "step_failed":
+            return "failed a scripted step";
+        case "harness_error":
+            return "was lost to a harness failure";
+        default:
+            return "ended";
+    }
+}
+/** "; the gaps list the other 2", or "all 3" when nobody passed. Empty when the gaps list nobody. */
+export function gapsListClause(listed, total) {
+    if (listed <= 0)
+        return "";
+    if (listed < total)
+        return `; the gaps list the other ${listed}`;
+    return total === 1 ? "; the gaps say why" : `; the gaps list all ${total}`;
+}
 /** One line a stakeholder can read, with the denominator attached to every number. */
 export function formatParticipantOutcomes(outcomes, terminalCauses = []) {
     if (outcomes.total === 0)
@@ -189,20 +230,25 @@ export function withCuaReviewProvenance(review, streams) {
             : !details.some((entry) => entry.goalSource !== undefined)))
         return review;
     const outcomes = formatParticipantOutcomes(review.participants, details);
-    // Preserve rerun context, participant narration and adapter-specific findings. Refreshing a
-    // historical summary qualifies its old tally instead of silently discarding that context.
-    const header = `Run gate: ${review.verdict}. Participants: ${outcomes}.${review.tasks ? ` Tasks: ${formatRunTaskFunnel(review.tasks)}.` : ""}`;
-    const prefix = `${header} Recorded summary: `;
-    const recorded = review.summary.startsWith(prefix)
-        ? review.summary.slice(prefix.length)
-        : review.summary;
-    const oldGoal = `${review.participants.reachedGoal}/${review.participants.total} reached the goal`;
-    const qualified = recorded
-        .split(oldGoal)
-        .join(participantCompletionLine(review.participants, details));
+    const tasks = review.tasks ? ` Tasks: ${formatRunTaskFunnel(review.tasks)}.` : "";
+    // A summary that states the bare count gets it qualified where it stands, keeping rerun context,
+    // the participant's own words and adapter findings around it.
+    const { reachedGoal, total } = review.participants;
+    const bareLine = `${reachedGoal}/${total} reached the goal`;
+    const qualifiedLine = participantCompletionLine(review.participants, details);
+    // A summary with no count gets it in a header. Earlier releases wrote a header in other words.
+    const header = `${plural(total, "participant")} took part: ${outcomes}.${tasks} `;
+    const olderHeader = `Run gate: ${review.verdict}. Participants: ${outcomes}.${tasks} Recorded summary: `;
+    const summary = review.summary.startsWith(olderHeader)
+        ? `${header}${review.summary.slice(olderHeader.length)}`
+        : review.summary.includes(bareLine)
+            ? review.summary.split(bareLine).join(qualifiedLine)
+            : review.summary.includes(qualifiedLine)
+                ? review.summary
+                : `${header}${review.summary}`;
     return {
         ...review,
-        summary: `${prefix}${qualified}`,
+        summary,
         gaps: review.participants.reachedGoal === 0
             ? review.gaps
             : [...review.gaps.filter((gap) => gap !== CUA_COMPLETION_NOTE), CUA_COMPLETION_NOTE],

package/dist/run/participant-caption.d.ts

@@ -0,0 +1,31 @@
+/** A participant, as much of it as a caption reads. */
+export interface CaptionFacts {
+    /** The roster id, on a route that has a roster. */
+    readonly id?: string;
+    /** The persona, which names the participant when there is no roster id or it is only a number. */
+    readonly personaId: string;
+    /** The participant's device, when it has one. */
+    readonly device?: {
+        readonly name: string;
+        readonly preset: {
+            readonly isMobile: boolean;
+        };
+    };
+}
+/** "Lobby host", or "Player two, phone" for a participant on a phone. */
+export declare function participantCaption(participant: CaptionFacts): string;
+/** The fields of a saved stream that name its participant. */
+export interface SavedCaptionFacts {
+    readonly label: string;
+    /** The participant id a computer-use stream records. */
+    readonly participantId?: string;
+    readonly personaId?: string;
+}
+/**
+ * The caption a saved stream shows: its label, which a route writes with `participantCaption`.
+ * Earlier releases wrote ids and taxonomy into the label (`lane-01 · browser`, `CUA participant
+ * <id>: <study>`, `Concurrent persona <id> (type:<t> / ...) · <study>`), so a stream saved that way
+ * is captioned again from the id it names. Older terminal and scripted labels use the
+ * recorded persona; a scripted mobile surface also identifies a phone.
+ */
+export declare function savedCaption(stream: SavedCaptionFacts): string;

package/dist/run/participant-caption.js

@@ -0,0 +1,60 @@
+// The words a reader sees for one participant. Routes write the caption as the stream label, and
+// the Observer, the TUI and findings show that label, so every surface names the participant the
+// same way. The participant's taxonomy and ids stay in the bundle data, out of the caption.
+/** Ids `participantIdAt` makes for an undeclared roster entry. They number a position. */
+const NUMBERED_ID = /^(lane|role)-\d+$/;
+/** An id in words: `lobby-host` reads "Lobby host". */
+function inWords(id) {
+    const words = id
+        .split(/[-_\s]+/)
+        .filter(Boolean)
+        .join(" ");
+    return `${words.charAt(0).toUpperCase()}${words.slice(1)}`;
+}
+/** A phone or a tablet. A desktop of any size goes unnamed, since most participants use one. */
+function deviceInWords(device) {
+    if (device === undefined)
+        return undefined;
+    if (device.preset.isMobile)
+        return "phone";
+    return device.name === "tablet" ? "tablet" : undefined;
+}
+/** "Lobby host", or "Player two, phone" for a participant on a phone. */
+export function participantCaption(participant) {
+    const { id, personaId } = participant;
+    const name = inWords(id === undefined || NUMBERED_ID.test(id) ? personaId : id);
+    const device = deviceInWords(participant.device);
+    return device === undefined ? name : `${name}, ${device}`;
+}
+const OLDER_SHARED_WORLD_LABEL = /^Concurrent persona (\S+)/;
+const OLDER_COMPUTER_USE_LABEL = /^CUA |^\S+ · browser$/;
+const OLDER_TERMINAL_OR_SCRIPTED_LABEL = /^(Terminal agent|Desktop browser surface|Mobile browser surface) · /;
+/**
+ * The caption a saved stream shows: its label, which a route writes with `participantCaption`.
+ * Earlier releases wrote ids and taxonomy into the label (`lane-01 · browser`, `CUA participant
+ * <id>: <study>`, `Concurrent persona <id> (type:<t> / ...) · <study>`), so a stream saved that way
+ * is captioned again from the id it names. Older terminal and scripted labels use the
+ * recorded persona; a scripted mobile surface also identifies a phone.
+ */
+export function savedCaption(stream) {
+    const { label, participantId, personaId } = stream;
+    const sharedWorldId = OLDER_SHARED_WORLD_LABEL.exec(label)?.[1];
+    if (sharedWorldId !== undefined) {
+        return participantCaption({ id: sharedWorldId, personaId: personaId ?? sharedWorldId });
+    }
+    if (OLDER_TERMINAL_OR_SCRIPTED_LABEL.test(label) && personaId !== undefined) {
+        return participantCaption({
+            personaId,
+            ...(label.startsWith("Mobile browser surface · ")
+                ? { device: { name: "mobile", preset: { isMobile: true } } }
+                : {}),
+        });
+    }
+    if (OLDER_COMPUTER_USE_LABEL.test(label) && personaId !== undefined) {
+        return participantCaption({
+            ...(participantId === undefined ? {} : { id: participantId }),
+            personaId,
+        });
+    }
+    return label;
+}

package/dist/run/participant-records.d.ts

@@ -1,4 +1,4 @@
-import type { RunEvent, RunProviderResource, RunSimulation } from "./bundle.js";
+import type { RunBundle, RunEvent, RunProviderResource, RunSimulation } from "./bundle.js";
 import type { RunStream } from "./streams.js";
 /** The ids a participant's saved records carry: its record id and its stream id. */
 export interface ParticipantIds {
@@ -25,4 +25,6 @@ export declare function recordIdOf(stream: RunStream): string;
 /** The record id a saved event names, when it names one. */
 export declare function eventRecordIdOf(event: RunEvent): string | undefined;
 /** The participant id an adapter recorded on a saved stream (a fan-out `lane-NN` id), when it has one. */
-export declare function streamParticipantIdOf(stream: RunStream): string | undefined;
+export declare function streamParticipantIdOf(stream: Pick<RunStream, "laneId">): string | undefined;
+/** The persona recorded for a stream, including dry runs without an actor trace. */
+export declare function recordedPersonaId(bundle: Partial<Pick<RunBundle, "simulations">>, stream: Partial<Pick<RunStream, "simId">>): string | undefined;

package/dist/run/participant-records.js

@@ -61,3 +61,9 @@ export function eventRecordIdOf(event) {
 export function streamParticipantIdOf(stream) {
     return stream.laneId;
 }
+/** The persona recorded for a stream, including dry runs without an actor trace. */
+export function recordedPersonaId(bundle, stream) {
+    if (stream.simId === undefined || !Array.isArray(bundle.simulations))
+        return undefined;
+    return bundle.simulations.find((record) => record?.id === stream.simId)?.personaId;
+}

package/dist/run/review-markdown.d.ts

@@ -0,0 +1,11 @@
+import type { RunBundle } from "./bundle.js";
+type ReviewBundle = Pick<RunBundle, "runId" | "mode" | "review"> & Partial<Pick<RunBundle, "outcome" | "simulations">> & {
+    scenario: Pick<RunBundle["scenario"], "title">;
+};
+/** The review's common head and gaps, around the route's evidence lines. */
+export declare function renderReviewMarkdown(bundle: ReviewBundle, middle: readonly string[], options?: {
+    beforeVerdict?: readonly string[];
+    style?: "preview";
+    status?: unknown;
+}): string;
+export {};

package/dist/run/review-markdown.js

@@ -0,0 +1,22 @@
+import { reviewOutcome } from "./display.js";
+import { verdictText } from "./judge.js";
+/** The review's common head and gaps, around the route's evidence lines. */
+export function renderReviewMarkdown(bundle, middle, options = {}) {
+    const preview = options.style === "preview";
+    const field = (name, value) => preview ? [`${name[0].toUpperCase()}${name.slice(1)}: ${value}`, ""] : [`- ${name}: ${value}`];
+    return [
+        `# ${preview ? "humanish Run Review" : bundle.scenario.title}`,
+        "",
+        ...field("run", bundle.runId),
+        ...field("mode", bundle.mode),
+        ...(options.beforeVerdict ?? []),
+        ...field("verdict", verdictText(bundle.review.verdict, bundle.mode)),
+        ...field("outcome", reviewOutcome(bundle, options.status)),
+        ...(preview ? [bundle.review.summary, ""] : field("summary", bundle.review.summary)),
+        ...middle,
+        ...(preview || bundle.review.gaps.length > 0
+            ? ["", "## Gaps", ...(preview ? [""] : []), ...bundle.review.gaps.map((gap) => `- ${gap}`)]
+            : []),
+        "",
+    ].join("\n");
+}

package/dist/run/run-cost.d.ts

@@ -34,6 +34,13 @@ export interface RunCost {
 }
 /** The accounting's analysis spend, or null when the run sent no analysis request. */
 export declare function analysisCostOf(accounting: Pick<AnalysisAccounting, "dispatched" | "unresolved" | "unpriced" | "estimatedUsd" | "providers" | "warnings">): RunAnalysisCost | null;
+/** The recorded estimate, or a supported zero for a dry run with no cost record. */
+export declare function runEstimateUsd(entry: {
+    estimatedCostUsd?: number | null | undefined;
+    mode?: string | null | undefined;
+}): number | null;
+/** Add known estimates, retaining unknown when neither component has a price. */
+export declare function sumEstimatedUsd(a: number | null, b: number | null): number | null;
 export declare function runCost(subtotal: RunCostSubtotal | null | undefined, analysis?: RunAnalysisCost | null): RunCost;
 /**
  * A run index entry's cost: its participants-and-desktops figure, complete or a lower bound when

package/dist/run/run-cost.js

@@ -11,25 +11,45 @@ export function analysisCostOf(accounting) {
         providers: [...accounting.providers],
     };
 }
+/** The recorded estimate, or a supported zero for a dry run with no cost record. */
+export function runEstimateUsd(entry) {
+    const usd = entry.estimatedCostUsd;
+    if (typeof usd === "number" && Number.isFinite(usd) && usd >= 0)
+        return usd;
+    return usd === undefined && entry.mode === "dry-run" ? 0 : null;
+}
+/** Add known estimates, retaining unknown when neither component has a price. */
+export function sumEstimatedUsd(a, b) {
+    const left = runEstimateUsd({ estimatedCostUsd: a });
+    const right = runEstimateUsd({ estimatedCostUsd: b });
+    return left === null && right === null ? null : round6((left ?? 0) + (right ?? 0));
+}
 export function runCost(subtotal, analysis) {
     if (subtotal === null || subtotal === undefined)
         return { run: null, analysis: null, total: null };
     const run = {
-        usd: typeof subtotal.estimatedTotalUsd === "number" ? subtotal.estimatedTotalUsd : null,
+        usd: runEstimateUsd({ estimatedCostUsd: subtotal.estimatedTotalUsd }),
         complete: subtotal.fullyEstimated === undefined ? null : subtotal.fullyEstimated,
         ratesAsOf: subtotal.ratesAsOf ?? null,
         placeholder: subtotal.placeholder === true,
     };
-    const spent = analysis ?? null;
-    const known = [run.usd, spent?.estimatedUsd].filter((usd) => typeof usd === "number");
-    if (known.length === 0)
+    const spent = analysis == null
+        ? null
+        : {
+            ...analysis,
+            estimatedUsd: runEstimateUsd({ estimatedCostUsd: analysis.estimatedUsd }),
+            complete: analysis.complete &&
+                runEstimateUsd({ estimatedCostUsd: analysis.estimatedUsd }) !== null,
+        };
+    const totalUsd = sumEstimatedUsd(run.usd, spent?.estimatedUsd ?? null);
+    if (totalUsd === null)
         return { run, analysis: spent, total: null };
     const lowerBound = run.usd === null || run.complete === false || spent?.complete === false;
     return {
         run,
         analysis: spent,
         total: {
-            usd: round6(known.reduce((sum, usd) => sum + usd, 0)),
+            usd: totalUsd,
             complete: lowerBound ? false : run.complete,
         },
     };