humanish 0.111.3 → 0.112.0

package/dist/routes/terminal/trace.js

@@ -4,50 +4,45 @@ import { TAIL_CHARS } from "./types.js";
 /**
  * Per-chunk sanitization cannot recognize a value split across deliveries. Redact those complete
  * known values before persistence without collapsing events or changing stdout/stderr ordering.
- * Work backwards through matches so edits to later text leave earlier offsets valid.
+ * `spansOf` finds them in the joined text: RunSecrets.spans, which also finds a value in an
+ * encoded form or split by a terminal escape sequence. Work backwards through the spans so edits
+ * to later text leave earlier offsets valid.
  */
-export function scrubSplitKnownValues(events, knownValues, discardedPrefixes) {
+export function scrubSplitKnownValues(events, spansOf, discardedPrefixes) {
     for (const order of ["stdout", "stderr", "combined"]) {
         const chunks = order === "combined" ? [...events] : events.filter((event) => event.stream === order);
         // A virtual final chunk makes a key crossing the capture cap recognizable. Edits to retained
         // events redact evidence; the raw overlap and this virtual chunk are never persisted.
         if (discardedPrefixes[order])
             chunks.push({ chunk: discardedPrefixes[order] });
-        for (const value of knownValues) {
-            if (!value)
+        let offset = 0;
+        const starts = chunks.map((event) => {
+            const start = offset;
+            offset += event.chunk.length;
+            return start;
+        });
+        const text = chunks.map((event) => event.chunk).join("");
+        for (const [at, end] of [...spansOf(text)].reverse()) {
+            let first = 0;
+            while (first + 1 < starts.length && (starts[first + 1] ?? Infinity) <= at)
+                first += 1;
+            let last = first;
+            while (last + 1 < starts.length && (starts[last + 1] ?? Infinity) < end)
+                last += 1;
+            const firstChunk = chunks[first];
+            const lastChunk = chunks[last];
+            if (!firstChunk || !lastChunk)
                 continue;
-            let offset = 0;
-            const starts = chunks.map((event) => {
-                const start = offset;
-                offset += event.chunk.length;
-                return start;
-            });
-            const text = chunks.map((event) => event.chunk).join("");
-            const matches = [];
-            for (let at = text.indexOf(value); at !== -1; at = text.indexOf(value, at + value.length))
-                matches.push(at);
-            for (const at of matches.reverse()) {
-                let first = 0;
-                while (first + 1 < starts.length && (starts[first + 1] ?? Infinity) <= at)
-                    first += 1;
-                let last = first;
-                while (last + 1 < starts.length && (starts[last + 1] ?? Infinity) < at + value.length)
-                    last += 1;
-                const firstChunk = chunks[first];
-                const lastChunk = chunks[last];
-                if (!firstChunk || !lastChunk)
-                    continue;
-                const before = firstChunk.chunk.slice(0, at - (starts[first] ?? 0));
-                const after = lastChunk.chunk.slice(at + value.length - (starts[last] ?? 0));
-                firstChunk.chunk = `${before}[REDACTED_SECRET]${first === last ? after : ""}`;
-                for (let index = first + 1; index < last; index += 1) {
-                    const middle = chunks[index];
-                    if (middle)
-                        middle.chunk = "";
-                }
-                if (first !== last)
-                    lastChunk.chunk = after;
+            const before = firstChunk.chunk.slice(0, at - (starts[first] ?? 0));
+            const after = lastChunk.chunk.slice(end - (starts[last] ?? 0));
+            firstChunk.chunk = `${before}[REDACTED_SECRET]${first === last ? after : ""}`;
+            for (let index = first + 1; index < last; index += 1) {
+                const middle = chunks[index];
+                if (middle)
+                    middle.chunk = "";
             }
+            if (first !== last)
+                lastChunk.chunk = after;
         }
     }
 }

package/dist/run/costs.js

@@ -1,4 +1,4 @@
-import { round6 } from "./pricing.js";
+import { runEstimateUsd, sumEstimatedUsd } from "./run-cost.js";
 import { bindExistingRunArtifactPaths } from "./paths.js";
 import { contradictsAccountBilling } from "../verify/costs.js";
 import { EVIDENCE_LIMITS } from "../analysis/evidence.js";
@@ -20,13 +20,9 @@ export function emptyCostTotals() {
         analysisHistoryUncertainRuns: 0,
     };
 }
-const isKnownUsd = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0;
-function sumKnown(a, b) {
-    return a === null && b === null ? null : round6((a ?? 0) + (b ?? 0));
-}
 export function addCostTotals(into, next) {
     for (const key of ["estimatedTotalUsd", "runEstimatedUsd", "analysisEstimatedUsd"]) {
-        into[key] = sumKnown(into[key], next[key]);
+        into[key] = sumEstimatedUsd(into[key], next[key]);
     }
     for (const key of [
         "incompleteRunEstimates",
@@ -49,11 +45,7 @@ export async function readCostTotals(cwd, entry) {
     const analysisWarnings = [];
     // A dry run makes no model request and creates no desktop, so with no figure it costs $0. A
     // recorded unknown (null) figure stays unknown.
-    costs.runEstimatedUsd = isKnownUsd(entry.estimatedCostUsd)
-        ? entry.estimatedCostUsd
-        : entry.estimatedCostUsd === undefined && entry.mode === "dry-run"
-            ? 0
-            : null;
+    costs.runEstimatedUsd = runEstimateUsd(entry);
     try {
         const prepared = await bindExistingRunArtifactPaths(cwd, entry.runId);
         const bytes = await readBoundedFile(prepared, RUN_BUNDLE_FILE, EVIDENCE_LIMITS.sourceBytes);
@@ -70,9 +62,7 @@ export async function readCostTotals(cwd, entry) {
             runWarnings.push("RUN_COST_ID_MISMATCH");
         }
         if (bundle?.cost !== undefined) {
-            costs.runEstimatedUsd = isKnownUsd(bundle.cost?.estimatedTotalUsd)
-                ? bundle.cost.estimatedTotalUsd
-                : null;
+            costs.runEstimatedUsd = runEstimateUsd({ estimatedCostUsd: bundle.cost?.estimatedTotalUsd });
             if (bundle.cost?.fullyEstimated !== true || costs.runEstimatedUsd === null) {
                 costs.incompleteRunEstimates = 1;
                 runWarnings.push("RUN_COST_PARTIAL_OR_UNKNOWN");
@@ -102,7 +92,7 @@ export async function readCostTotals(cwd, entry) {
         costs.analysisHistoryUncertainRuns = 1;
         analysisWarnings.push("STUDY_COST_ACCOUNTING_UNAVAILABLE");
     }
-    costs.estimatedTotalUsd = sumKnown(costs.runEstimatedUsd, costs.analysisEstimatedUsd);
+    costs.estimatedTotalUsd = sumEstimatedUsd(costs.runEstimatedUsd, costs.analysisEstimatedUsd);
     return {
         runId: entry.runId,
         costs,
@@ -153,16 +143,15 @@ export async function readAnalysisAccounting(prepared) {
         }
         if (!usage.dispatched) {
             accounting.notDispatched += 1;
-            accounting.estimatedUsd = sumKnown(accounting.estimatedUsd, 0);
+            accounting.estimatedUsd = sumEstimatedUsd(accounting.estimatedUsd, 0);
             continue;
         }
         accounting.dispatched += 1;
         if (record.receipt)
             providers.add(record.receipt.provider);
-        if (isKnownUsd(usage.estimatedCostUsd)) {
-            accounting.estimatedUsd = sumKnown(accounting.estimatedUsd, usage.estimatedCostUsd);
-        }
-        if (!isKnownUsd(usage.estimatedCostUsd) || !usage.usageComplete)
+        const estimatedUsd = runEstimateUsd({ estimatedCostUsd: usage.estimatedCostUsd });
+        accounting.estimatedUsd = sumEstimatedUsd(accounting.estimatedUsd, estimatedUsd);
+        if (estimatedUsd === null || !usage.usageComplete)
             accounting.unpriced += 1;
     }
     // A skipped or queued automatic job says nothing about earlier manual requests. Only final

package/dist/run/detail.d.ts

@@ -11,7 +11,7 @@ interface RunThought {
 export interface RunParticipant {
     /** Stream id: stable within a run, and what distinguishes participants of one study. */
     id: string;
-    /** What to call them on screen: the participant's own label, else the persona id. */
+    /** What to call them on screen: the caption the Observer shows, else the persona id. */
     label: string;
     /** The persona id, when the trace recorded one. */
     personaId?: string;

package/dist/run/detail.js

@@ -12,6 +12,8 @@ import path from "node:path";
 import { estimateActorCostForExecution } from "./pricing.js";
 import { resolveRunPath } from "./locate.js";
 import { RUN_BUNDLE_FILE } from "./bundle.js";
+import { savedCaption } from "./participant-caption.js";
+import { streamParticipantIdOf } from "./participant-records.js";
 import { readContainedRegularFile } from "./contained-output.js";
 import { isPathInside, resolvePhysicalCwd } from "./paths.js";
 const RUN_DETAIL_SCHEMA = "humanish.run-detail.v1";
@@ -47,13 +49,20 @@ function participantFrom(stream, index) {
     const trace = stream.liveActor ?? stream.actor ?? {};
     const id = stream.id ?? `stream-${index + 1}`;
     const personaId = trace.persona?.id;
+    const participantId = streamParticipantIdOf(stream);
     // Computed once: calling it twice to test-then-use reads as though the two could differ.
     const thought = latestThought(trace);
     const status = trace.status ?? stream.status;
     const thoughts = (trace.items ?? []).filter((item) => item?.kind === "reasoning").length;
     return {
         id,
-        label: stream.label ?? personaId ?? id,
+        label: stream.label === undefined
+            ? (personaId ?? id)
+            : savedCaption({
+                label: stream.label,
+                ...(participantId === undefined ? {} : { participantId }),
+                ...(personaId === undefined ? {} : { personaId }),
+            }),
         ...(personaId === undefined ? {} : { personaId }),
         traits: Array.isArray(trace.persona?.traitsApplied) ? trace.persona.traitsApplied : [],
         ...(status === undefined ? {} : { status }),

package/dist/run/display.d.ts

@@ -49,14 +49,14 @@ export interface DisplayedBundle {
  * 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 declare function bundleDisplayFacts(bundle: DisplayedBundle, status?: unknown, nowMs?: number): RunDisplayFacts;
 /**
  * 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 declare function reviewOutcome(bundle: DisplayedBundle): string;
+export declare function reviewOutcome(bundle: DisplayedBundle, status?: unknown): string;
 /**
  * The summary and gaps a review shows beside its run's display. A run stopped while a participant
  * was still running keeps the review its last live flush wrote, which describes that session as

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,30 @@
+/** 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, without a device.
+ */
+export declare function savedCaption(stream: SavedCaptionFacts): string;