humanish 0.115.0 → 0.117.0

package/dist/cli/commands/run-signals.js

@@ -134,7 +134,11 @@ async function stopActiveRuns(io, signal, stopping, options) {
     // not swept; verify grades a file that names a receipt's id local_only.
     Promise.all(stopping
         .filter((stop) => stop.report !== null)
-        .map((stop) => scrubRunSandboxIds(stop.run.paths).catch(() => undefined))));
+        .map((stop) => scrubRunSandboxIds(stop.run.paths).catch((error) => {
+        // A file the sweep refused to read may still name a sandbox; say which.
+        if (error instanceof Error)
+            say(io, `humanish: ${signal}: ${error.message}`);
+    }))));
     const finished = await withDeadline(work, deadlineMs, options.deadline);
     for (const stop of stopping) {
         if (stop.report === null)

package/dist/cli/commands/runs.js

@@ -11,7 +11,8 @@ import { addRunOptions, handleRun } from "./run-command.js";
 import { applyEnvFileOption, CWD_OPTION_DESCRIPTION, DOTENV_OPTION_DESCRIPTION, dotenvPathOf, envFileAliasOption, JSON_OPTION_DESCRIPTION, parsePositiveInteger, RUN_OPTION_DESCRIPTION, writeResult, humanError, } from "../io.js";
 import { plural } from "../../run/text.js";
 import { warnAndQueue } from "../deprecations.js";
-import { formatFindings, readRunFindings } from "../findings.js";
+import { readRunFindings } from "../findings.js";
+import { formatFindings } from "../findings-text.js";
 import { cli } from "../invocation.js";
 export function registerRunCommand(parent, io) {
     addRunOptions(parent

package/dist/cli/commands/setup.js

@@ -1,5 +1,5 @@
 import { Command } from "commander";
-import { listUserKeys, resolveKeyName, setUserKey, unsetUserKey, userKeyStorePath, } from "../../keys/key-resolution.js";
+import { KEY_VENDORS, listUserKeys, resolveKeyName, setUserKey, unsetUserKey, userKeyStorePath, } from "../../keys/key-resolution.js";
 import { askForMissingKeys, formatKeyStatus, keyStatus, otherStoredKeys, } from "../../keys/key-status.js";
 import { promptSecret } from "../secret-prompt.js";
 import { runInit } from "../../study/init.js";
@@ -270,7 +270,7 @@ export function registerKeysCommand(parent, io) {
         .action(async (_options, command) => writeKeyStatus(command, io));
     keys
         .command("set")
-        .argument("[vendor-or-name]", "A vendor alias (openai, e2b, anthropic, github, agentmail) or a raw ENV_NAME. Without one, a terminal asks for each missing key in turn.")
+        .argument("[vendor-or-name]", `A vendor alias (${KEY_VENDORS.join(", ")}) or a raw ENV_NAME. Without one, a terminal asks for each missing key in turn.`)
         .description("Store one provider key in the user store (0600), prompted with hidden input. With no key named, ask for each missing key in turn.")
         .option("--stdin", "Read the value from stdin instead of prompting (for agents/pipes).")
         .option("--json", JSON_OPTION_DESCRIPTION)
@@ -288,7 +288,7 @@ export function registerKeysCommand(parent, io) {
                 action: "set",
                 store: storePath,
                 names: [],
-                message: `Not a vendor alias or valid env name: ${vendorOrName}. Vendors: openai, e2b, anthropic, github, agentmail.`,
+                message: `Not a vendor alias or valid env name: ${vendorOrName}. Vendors: ${KEY_VENDORS.join(", ")}.`,
             };
             writeResult(command, io, result, formatKeysHuman);
             io.setExitCode(2);

package/dist/cli/commands/study-format.d.ts

@@ -3,7 +3,10 @@ import type { CuaActorStudyResult } from "../../routes/computer-use/types.js";
 import type { ScriptedBrowserStudyResult } from "../../routes/scripted/types.js";
 import type { TerminalProductStudyResult } from "../../routes/terminal/types.js";
 import type { ConcurrentSharedWorldStudyResult } from "../../routes/shared-world/types.js";
+import type { StudySubject } from "../../study/types.js";
 export declare function formatConcurrentSharedWorldStudyHuman(result: ConcurrentSharedWorldStudyResult): HumanOutput;
 export declare function formatTerminalStudyHuman(result: TerminalProductStudyResult): HumanOutput;
-export declare function formatScriptedStudyHuman(result: ScriptedBrowserStudyResult): HumanOutput;
-export declare function formatCuaStudyHuman(result: CuaActorStudyResult): HumanOutput;
+/** `subject` is the study's declared subject, which names it when the result has no URL. */
+export declare function formatScriptedStudyHuman(result: ScriptedBrowserStudyResult, subject: StudySubject): HumanOutput;
+/** `subject` is the study's declared subject, which names it when the result has no URL. */
+export declare function formatCuaStudyHuman(result: CuaActorStudyResult, subject: StudySubject): HumanOutput;

package/dist/cli/commands/study-format.js

@@ -1,12 +1,18 @@
 import { participantCaption } from "../../run/participant-caption.js";
 import { formatCuaDiagnostics, formatCuaStopCause } from "../../routes/computer-use/diagnostics.js";
-/** A run's first lines: the command that ran, whether it was a dry run, how it ended, and its route. */
+/**
+ * A run's first lines: the command that ran, whether it was a dry run, how it ended, and its route.
+ * `runOk` is the run's own ok, which automaticAnalysisEnvelope keeps when an analysis that did not
+ * complete turns `ok` false. That run finished, and the line says so.
+ */
 function runHeader(result, route) {
     const kind = result.dryRun === true ? "dry run" : result.dryRun === false ? "live run" : "run";
-    return [
-        `humanish run ${result.studyId}: ${kind} ${result.ok ? "finished" : "failed"}`,
-        `route: ${route}`,
-    ];
+    const ending = result.ok
+        ? "finished"
+        : result.runOk === true
+            ? "finished; the analysis did not complete"
+            : "failed";
+    return [`humanish run ${result.studyId}: ${kind} ${ending}`, `route: ${route}`];
 }
 /**
  * A run's human output: its lines on stdout and, when it failed with an error, that error on
@@ -31,6 +37,18 @@ function sandboxIdsLine(result) {
         ? [`sandbox ids: .humanish/runs/${result.runId}/sandbox-receipts.ndjson`]
         : [];
 }
+/**
+ * How a run's output names its subject: by the URL its participants open. A product studied at a
+ * desktop has no URL, so it is named with its source, as in `humanish (desktop-cli)`. A refusal
+ * made before the route resolved a URL has none either, so it names the URL the study declares.
+ */
+function subjectName(appUrl, subject) {
+    if (appUrl !== "")
+        return appUrl;
+    if (subject.product !== undefined)
+        return `${subject.product.name} (${subject.source})`;
+    return subject.appUrl ?? subject.serve?.url ?? subject.source;
+}
 /** A participant's status in words: a dry run's placeholder status says that nothing ran live. */
 function participantStatus(status) {
     return status === "contract_proof_only" ? "dry run, nothing ran live" : status;
@@ -83,12 +101,13 @@ export function formatTerminalStudyHuman(result) {
         ...result.warnings.map((warning) => `warning: ${warning}`),
     ]);
 }
-export function formatScriptedStudyHuman(result) {
+/** `subject` is the study's declared subject, which names it when the result has no URL. */
+export function formatScriptedStudyHuman(result, subject) {
     return withError(result.error, [
         ...runHeader(result, "scripted"),
         `run: ${result.runId}`,
         `actor: ${result.actor}`,
-        `subject: ${result.appUrl}`,
+        `subject: ${subjectName(result.appUrl, subject)}`,
         ...(result.scenario
             ? [
                 `scenario: ${result.scenario.id} @ ${result.scenario.sourceDigest.slice(0, 12)} (${result.scenario.source}, ${result.scenario.steps} step${result.scenario.steps === 1 ? "" : "s"})`,
@@ -108,12 +127,13 @@ export function formatScriptedStudyHuman(result) {
         ...result.warnings.map((warning) => `warning: ${warning}`),
     ]);
 }
-export function formatCuaStudyHuman(result) {
+/** `subject` is the study's declared subject, which names it when the result has no URL. */
+export function formatCuaStudyHuman(result, subject) {
     return withError(result.error, [
         ...runHeader(result, "computer-use"),
         `run: ${result.runId}`,
         `actor: ${result.actor}`,
-        `subject: ${result.appUrl}`,
+        `subject: ${subjectName(result.appUrl, subject)}`,
         ...(result.subject?.source === "clone"
             ? [
                 `repo: ${result.subject.repo}${result.subject.commit ? `@${result.subject.commit.slice(0, 12)}` : ""}${result.subject.envNames && result.subject.envNames.length > 0 ? ` env=[${result.subject.envNames.join(", ")}]` : ""}`,

package/dist/cli/commands/study-route-computer-use.js

@@ -57,7 +57,7 @@ function refuseCua(args, dryRun, code, message) {
         dryRun,
         runId: args.options.runId ?? "not-created",
     });
-    writeResult(args.command, args.io, result, formatCuaStudyHuman);
+    writeResult(args.command, args.io, result, (value) => formatCuaStudyHuman(value, args.config.subject));
     args.io.setExitCode(2);
 }
 /** Parses the options, or writes the refusal and returns undefined. */
@@ -236,7 +236,7 @@ async function reportCuaRun(args, prepared, result, live) {
             ],
         };
     }
-    writeResult(args.command, args.io, output, formatCuaStudyHuman);
+    writeResult(args.command, args.io, output, (value) => formatCuaStudyHuman(value, args.config.subject));
     args.io.setExitCode(result.ok && automaticAnalysisSucceeded(result) ? 0 : 2);
     await writeRunFindings(args.command, args.io, args.options.cwd, result);
     if (server && (result.observer?.ok || attachedObserver)) {

package/dist/cli/commands/study-route-scripted.js

@@ -34,7 +34,7 @@ export function scriptedRouteRun(args) {
                 throw new Error(`Expected the scripted route, got ${outcome.route}.`);
             }
             const result = outcome.result;
-            writeResult(args.command, args.io, result, formatScriptedStudyHuman);
+            writeResult(args.command, args.io, result, (value) => formatScriptedStudyHuman(value, args.config.subject));
             args.io.setExitCode(result.ok && automaticAnalysisSucceeded(result) ? 0 : 2);
             await writeRunFindings(args.command, args.io, args.options.cwd, result);
             // Watch mode serves the Observer the route rendered through its finished run.

package/dist/cli/commands/tui.js

@@ -1,7 +1,8 @@
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
 import { Command } from "commander";
-import { setUserKey } from "../../keys/key-resolution.js";
+import { LISTED_KEYS, setUserKey } from "../../keys/key-resolution.js";
+import { keyStatus, keyStatusLine } from "../../keys/key-status.js";
 import { saveCommsConnection } from "../../comms/connections.js";
 import { readCommsSetup } from "../../comms/setup.js";
 import { checkCommsConnection, configureCommsStudy, } from "../../comms/setup.js";
@@ -160,13 +161,11 @@ async function runTuiSession(loaded, runtime, cwd, discoveredKeys) {
         runIndexCache: new RunIndexCache(),
         observerSession: createTuiObserverSession(cwd),
     };
-    let connectionNotice;
+    let returnTo;
     try {
         for (;;) {
             const outcome = await loaded.startTui({
-                ...(connectionNotice === undefined
-                    ? {}
-                    : { initialScreen: "connections", connectionNotice }),
+                ...returnTo,
                 cwd,
                 version: { cli: CLI_VERSION },
                 capabilities: tuiCapabilities(session),
@@ -175,9 +174,17 @@ async function runTuiSession(loaded, runtime, cwd, discoveredKeys) {
             });
             if (typeof outcome === "number")
                 return outcome;
-            if (outcome.action !== "agentmail-key")
+            returnTo =
+                outcome.action === "agentmail-key"
+                    ? { initialScreen: "connections", connectionNotice: await storeAgentmailKey(session) }
+                    : outcome.action === "provider-key"
+                        ? {
+                            initialScreen: "keys",
+                            connectionNotice: await storeProviderKey(session, outcome.name),
+                        }
+                        : undefined;
+            if (returnTo === undefined)
                 return 1;
-            connectionNotice = await storeAgentmailKey(session);
         }
     }
     finally {
@@ -197,6 +204,14 @@ function connectionEnv(session) {
 function tuiCapabilities(session) {
     const { cwd, runtime, sessionEnv, runIndexCache, observerSession } = session;
     return {
+        keys: {
+            // The project's overlay and the stores, as `humanish keys` reads them from this directory.
+            status: async () => (await keyStatus({ cwd, env: connectionEnv(session) })).map((row) => ({
+                name: row.name,
+                set: row.source !== null,
+                line: keyStatusLine(row),
+            })),
+        },
         comms: {
             read: async () => ({
                 ...(await readCommsSetup(cwd, connectionEnv(session))),
@@ -270,21 +285,48 @@ function tuiCapabilities(session) {
         },
     };
 }
+const ENTRY_CANCELLED = "Key entry cancelled. Nothing was changed.";
+const ENTRY_FAILED = "Could not store the key. Use a single non-empty line and check key-store permissions.";
+/**
+ * Asks for one key with hidden input, after the surface has unmounted, and stores it in the user
+ * store. Only the host reads the credential. A value that discovery filled into this session is
+ * dropped so the stored one is read; an explicit env or file value still wins.
+ */
+async function promptAndStoreKey(session, name, label) {
+    const { runtime, sessionEnv } = session;
+    const value = await runtime.promptSecret(label, runtime.stdin, runtime.stdout);
+    if (value === null || value === "")
+        return "cancelled";
+    setUserKey(name, value, sessionEnv);
+    if (session.discoveredKeys.has(name))
+        delete sessionEnv[name];
+    return "stored";
+}
+/**
+ * A key from the keys screen, asked for and stored as `humanish keys set <vendor>` does. Resolves to
+ * the notice the remounted keys screen shows.
+ */
+async function storeProviderKey(session, name) {
+    if (!LISTED_KEYS.some((key) => key.name === name))
+        return `${name} is not a key humanish keys lists. Nothing was changed.`;
+    try {
+        return (await promptAndStoreKey(session, name, `Value for ${name}`)) === "stored"
+            ? `${name} stored.`
+            : ENTRY_CANCELLED;
+    }
+    catch {
+        return ENTRY_FAILED;
+    }
+}
 /**
  * Prompts for the AgentMail key after the surface has unmounted, stores it and checks it. Resolves
  * to the notice the remounted connections screen shows.
  */
 async function storeAgentmailKey(session) {
-    const { cwd, runtime, sessionEnv } = session;
-    // startTui has unmounted: only the host reads the credential, then remounts the view.
-    const value = await runtime.promptSecret("AgentMail API key", runtime.stdin, runtime.stdout);
-    if (value === null || value === "")
-        return "Key entry cancelled. Nothing was changed.";
+    const { cwd, runtime } = session;
     try {
-        setUserKey("AGENTMAIL_API_KEY", value, sessionEnv);
-        // Refresh only a value filled implicitly by discovery; explicit env/file wins.
-        if (session.discoveredKeys.has("AGENTMAIL_API_KEY"))
-            delete sessionEnv.AGENTMAIL_API_KEY;
+        if ((await promptAndStoreKey(session, "AGENTMAIL_API_KEY", "AgentMail API key")) !== "stored")
+            return ENTRY_CANCELLED;
         const saved = await saveCommsConnection(cwd);
         const storedNotice = saved.ok
             ? "Key stored. Project connection saved."
@@ -301,6 +343,6 @@ async function storeAgentmailKey(session) {
             : `${storedNotice} ${check.message}`;
     }
     catch {
-        return "Could not store the key. Use a single non-empty line and check key-store permissions.";
+        return ENTRY_FAILED;
     }
 }

package/dist/cli/doctor.js

@@ -2,8 +2,9 @@ import { readFile, readdir } from "node:fs/promises";
 import { homedir } from "node:os";
 import { existsSync } from "node:fs";
 import path from "node:path";
-import { probeKeySources, } from "../keys/key-resolution.js";
+import { DOCTOR_KEYS, probeKeySources, } from "../keys/key-resolution.js";
 import { desktopPeerAdvice, humanishInstall, } from "../substrates/e2b/peer-install.js";
+import { describeSandboxCeiling, sandboxCeiling } from "../substrates/e2b/lifetime.js";
 import { nodeSupportsTui, terminalSurfaceMessage, TUI_BUNDLE_URL } from "../tui/contract.js";
 import { detectLocalAgents, localAgentDoctorMessage, localAgentReady, NO_LOCAL_AGENT_MESSAGE, } from "../actors/local-agent/cli.js";
 import { leftoverClaudeTranscripts } from "../actors/local-agent/claude-participant.js";
@@ -95,6 +96,7 @@ export async function doctor(cwdInput, options = {}) {
     const checks = [
         ...(await projectChecks(projectRoot)),
         await desktopSdkCheck(setup),
+        sandboxCeilingCheck(env),
         terminalSurfaceCheck(),
         ...versionCheck(env),
         ...localAgentChecks(agents),
@@ -191,6 +193,11 @@ async function runtimeIgnoreCheck(projectRoot) {
             : `.gitignore does not list .humanish/; run ${cli("init --yes")}`,
     };
 }
+/** The longest sandbox lifetime the E2B planners allow, and where that number came from. */
+function sandboxCeilingCheck(env) {
+    const ceiling = sandboxCeiling(env);
+    return { name: "e2b sandbox ceiling", ok: ceiling.ok, message: describeSandboxCeiling(ceiling) };
+}
 /**
  * The optional peer dep every live browser and terminal route needs. `npx -y humanish` does not
  * pull optional peers, so without this check an adopter's first live run fails on it, safely and at
@@ -266,7 +273,7 @@ function versionCheck(env) {
 }
 /** Probes the live-run keys, plus the receiving-email key a real-comms study names. */
 async function probeDoctorKeys(cwd, env, study, keyDeps, dotenv) {
-    const keyNames = new Set(["OPENAI_API_KEY", "E2B_API_KEY", "GH_TOKEN", "CODEX_API_KEY"]);
+    const keyNames = new Set(DOCTOR_KEYS);
     let receivingKey = null;
     if (study) {
         const { resolveStudyManifest } = await import("../study/discover.js");

package/dist/cli/findings-text.d.ts

@@ -0,0 +1,5 @@
+import type { AnalysisFindings } from "./findings.js";
+/** The full findings block: the analysis, every finding with its evidence, and its limitations. */
+export declare function formatFindings(view: AnalysisFindings): string[];
+/** At most `limit` findings, one line each, and the command that prints all of them. */
+export declare function formatFindingsSummary(view: AnalysisFindings, fullCommand: string, limit?: number): string[];

package/dist/cli/findings-text.js

@@ -0,0 +1,169 @@
+// The text of a run's `humanish.analysis-findings.v1` view (findings.ts): the full block `review`
+// and `analyze show` print, and the summary at the end of a live `run`. It reads only the view.
+import path from "node:path";
+import { findingLead } from "../analysis/finding-lead.js";
+import { plural } from "../run/text.js";
+const IMPACT_TEXT = {
+    blocked_task: "blocked task",
+    friction: "friction",
+    recovery: "recovery",
+    uncertain: "uncertain",
+};
+const RECOVERY_TEXT = {
+    recovered: "recovered",
+    not_observed: "no recovery observed",
+    unknown: "recovery unknown",
+};
+/** `+1:05` from milliseconds since the first retained capture. */
+function elapsedText(ms) {
+    const seconds = Math.floor(ms / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    const ss = String(seconds % 60).padStart(2, "0");
+    return hours > 0
+        ? `+${hours}:${String(minutes % 60).padStart(2, "0")}:${ss}`
+        : `+${minutes}:${ss}`;
+}
+/** One participant's cited moments: each frame once, at its earliest cited time. */
+function momentsText(evidence) {
+    const frames = new Map();
+    let unframed = 0;
+    for (const entry of evidence) {
+        if (entry.frame === null) {
+            unframed++;
+            continue;
+        }
+        const earlier = frames.get(entry.frame);
+        if (earlier === undefined ||
+            (entry.elapsedMs !== null && (earlier ?? Infinity) > entry.elapsedMs))
+            frames.set(entry.frame, entry.elapsedMs);
+    }
+    const parts = [...frames]
+        .sort(([a], [b]) => a - b)
+        .map(([frame, ms]) => `frame ${frame}${ms === null ? "" : ` at ${elapsedText(ms)}`}`);
+    if (unframed > 0)
+        parts.push(`${plural(unframed, "item")} with no frame`);
+    return parts.join(", ");
+}
+/** The capture files, relative to the run directory, in frame order. */
+function captureFiles(evidence, runRoot) {
+    return [
+        ...new Set(evidence
+            .filter((entry) => entry.capture !== null)
+            .sort((a, b) => (a.frame ?? 0) - (b.frame ?? 0))
+            .map((entry) => (runRoot ? path.relative(runRoot, entry.capture) : entry.capture))),
+    ];
+}
+function findingLines(finding, runRoot) {
+    const cited = [...new Set(finding.evidence.map((entry) => entry.streamId))];
+    const labels = new Map(finding.affected.map((p) => [p.streamId, p.label]));
+    const affectedIds = finding.affected.map((p) => p.streamId);
+    const streams = [...affectedIds, ...cited.filter((id) => !labels.has(id))];
+    const captures = captureFiles(finding.evidence, runRoot);
+    const correction = finding.correction;
+    const lead = findingLead(finding, correction);
+    return [
+        ...(lead === null
+            ? [`${finding.id} ${finding.title}`]
+            : [
+                `${finding.id} ${lead.headline}`,
+                ...(lead.account === null ? [] : [`   ${lead.account}`]),
+                `   evidence: ${finding.title}`,
+            ]),
+        `   impact: ${IMPACT_TEXT[finding.impact]} · confidence: ${finding.confidence} · recovery: ${RECOVERY_TEXT[finding.recovery]}`,
+        `   ${finding.summary}`,
+        `   affected: ${finding.affected.length} of ${plural(finding.exposedCount, "exposed participant")}`,
+        ...streams.map((streamId) => {
+            const moments = momentsText(finding.evidence.filter((entry) => entry.streamId === streamId));
+            const label = `${labels.get(streamId) ?? streamId}${labels.has(streamId) ? "" : " (cited, not affected)"}`;
+            return `   - ${label}${moments ? `: ${moments}` : ""}`;
+        }),
+        ...(captures.length === 0 ? [] : [`   captures: ${captures.join(", ")}`]),
+        `   next step: ${finding.nextStep}`,
+        ...(correction === null
+            ? []
+            : [
+                `   human review: ${correction.status}, ${correction.reason}${correction.replacementClaim ? ` Amended claim: ${correction.replacementClaim}` : ""}`,
+            ]),
+    ];
+}
+function designFindingLines(finding, runRoot) {
+    const captures = captureFiles(finding.evidence, runRoot);
+    return [
+        `${finding.id} ${finding.severity}: ${finding.headline}`,
+        `   screen: ${finding.screen}`,
+        `   notice: ${finding.notice}`,
+        `   why it matters: ${finding.whyItMatters}`,
+        `   suggestion: ${finding.suggestion}`,
+        `   seen by: ${finding.seenBy.map((p) => p.label).join(", ")} · confidence: ${finding.confidence}`,
+        ...(captures.length === 0 ? [] : [`   captures: ${captures.join(", ")}`]),
+    ];
+}
+/** Nothing for an analysis written before design findings. */
+function designSection(view) {
+    const design = view.designFindings;
+    if (design === null)
+        return [];
+    if (design.length === 0)
+        return ["", "design findings: none in the reviewed captures"];
+    return [
+        "",
+        `design findings: ${design.length}, most severe first`,
+        ...design.flatMap((finding, index) => [
+            ...(index === 0 ? [] : [""]),
+            ...designFindingLines(finding, view.runPath ?? ""),
+        ]),
+    ];
+}
+/** The full findings block: the analysis, every finding with its evidence, and its limitations. */
+export function formatFindings(view) {
+    if (view.state !== "ready" && view.state !== "stale")
+        return [`findings: none. ${view.message}`, ...(view.next ? [`next: ${view.next}`] : [])];
+    const model = [view.provider, view.model].filter(Boolean).join(" ");
+    const cost = view.estimatedCostUsd === null ? "" : `, estimated $${view.estimatedCostUsd.toFixed(2)}`;
+    return [
+        `findings: ${view.findings.length} from analysis ${view.analysisId} (${view.status}, ${model}${cost})`,
+        ...(view.state === "stale" ? [`warning: ${view.message}`, `next: ${view.next}`] : []),
+        ...(view.summary ? [view.summary] : []),
+        ...view.findings.flatMap((finding) => ["", ...findingLines(finding, view.runPath ?? "")]),
+        ...designSection(view),
+        ...(view.limitations.length === 0
+            ? []
+            : ["", "limitations:", ...view.limitations.map((limitation) => `- ${limitation}`)]),
+        ...view.warnings.map((warning) => `warning: ${warning}`),
+        "",
+        `analysis: ${view.path}`,
+    ];
+}
+/** At most `limit` findings, one line each, and the command that prints all of them. */
+export function formatFindingsSummary(view, fullCommand, limit = 3) {
+    if (view.state !== "ready" && view.state !== "stale")
+        return [`findings: ${view.message}`, ...(view.next ? [`next: ${view.next}`] : [])];
+    const shown = view.findings.slice(0, limit);
+    const design = view.designFindings;
+    return [
+        `findings: ${view.findings.length === 0 ? "none" : view.findings.length}${view.state === "stale" ? " (stale)" : ""}`,
+        ...shown.map((finding) => {
+            const qualities = `${IMPACT_TEXT[finding.impact]}, ${finding.confidence} confidence, ${RECOVERY_TEXT[finding.recovery]}`;
+            const lead = findingLead(finding, finding.correction);
+            if (lead === null)
+                return `- ${finding.id} ${qualities}: ${finding.title}`;
+            return `- ${finding.id} ${lead.headline} (${lead.corrected ? "corrected in human review" : qualities})`;
+        }),
+        ...(view.findings.length > limit
+            ? [`- and ${plural(view.findings.length - limit, "more finding")}`]
+            : []),
+        ...(design === null
+            ? []
+            : [
+                `design findings: ${design.length === 0 ? "none" : design.length}`,
+                ...design
+                    .slice(0, limit)
+                    .map((finding) => `- ${finding.id} ${finding.severity}: ${finding.headline}`),
+                ...(design.length > limit
+                    ? [`- and ${plural(design.length - limit, "more design finding")}`]
+                    : []),
+            ]),
+        `all findings: ${fullCommand}`,
+    ];
+}

package/dist/cli/findings.d.ts

@@ -137,10 +137,6 @@ export declare function readRunAnalysis(cwd: string, run: string, analysisId?: s
 export declare function missingRunFindings(cwd: string, run: string): AnalysisFindings;
 /** The findings of a run's selected analysis, or why it has none. */
 export declare function readRunFindings(cwd: string, run: string, analysisId?: string): Promise<AnalysisFindings>;
-/** The full findings block: the analysis, every finding with its evidence, and its limitations. */
-export declare function formatFindings(view: AnalysisFindings): string[];
-/** At most `limit` findings, one line each, and the command that prints all of them. */
-export declare function formatFindingsSummary(view: AnalysisFindings, fullCommand: string, limit?: number): string[];
 /**
  * The end of a live run's human output, after its `analysis:` line: the findings of the analysis
  * the run just completed. Prints nothing for --json, or when the run's analysis did not complete,