humanish 0.139.0 → 0.140.0

package/dist/analysis/automatic-config.js

@@ -27,14 +27,29 @@ const SENSITIVE_QUESTION = {
     ok: false,
     message: "review.analysis.question contains sensitive text and cannot be sent for analysis.",
 };
-/** The spend cap on an analysis the study did not declare. */
-export const DEFAULT_ANALYSIS_MAX_COST_USD = 3;
-/** Called for parsed manifests and direct library configs, before participant execution. */
-export function resolveAutomaticAnalysis(raw) {
+/** The spend cap on an OpenAI analysis the study did not declare. */
+export const DEFAULT_ANALYSIS_MAX_COST_USD = 10;
+/**
+ * The analysis a study gets when it declares none. A Codex local-agent participant signs in with a
+ * ChatGPT account and needs no API key, so its run is analyzed by the same account; every other
+ * participant gets the OpenAI analyst under the default cap. A Claude participant stays on OpenAI:
+ * moving it to the Codex account because OPENAI_API_KEY is missing would bill an account the study
+ * never named.
+ */
+function undeclaredAnalysis(participant) {
+    return participant?.type === "local-agent" && (participant.localAgent ?? "codex") === "codex"
+        ? { provider: "codex" }
+        : { maxCostUsd: DEFAULT_ANALYSIS_MAX_COST_USD };
+}
+/**
+ * Called for parsed manifests and direct library configs, before participant execution. An
+ * undefined `raw` is the study's default, chosen by its participant (the study's `actor`).
+ */
+export function resolveAutomaticAnalysis(raw, participant) {
     if (raw === false)
         return { ok: true, config: undefined };
     if (raw === undefined)
-        raw = { maxCostUsd: DEFAULT_ANALYSIS_MAX_COST_USD };
+        raw = undeclaredAnalysis(participant);
     if (raw === null ||
         typeof raw !== "object" ||
         Array.isArray(raw) ||
@@ -117,12 +132,13 @@ export function resolveAutomaticAnalysis(raw) {
     };
 }
 /** Metadata only: resolving the future live-run budget never reads keys or dispatches. With a
- * participant count it also gives the expected cost range for that many participants. */
-export function automaticAnalysisBudget(raw, route, participants) {
+ * participant count it also gives the expected cost range for that many participants, and with the
+ * study's participant it resolves an undeclared analysis the way the run will. */
+export function automaticAnalysisBudget(raw, route, participants, participant) {
     // The synthetic preview has no participants, so nothing is analyzed after it.
     if (route === "preview")
         return undefined;
-    const resolved = resolveAutomaticAnalysis(raw);
+    const resolved = resolveAutomaticAnalysis(raw, participant);
     if (!resolved.ok || !resolved.config)
         return undefined;
     const { config } = resolved;
@@ -150,7 +166,7 @@ export function analysisRequestsText(requests) {
 }
 export function formatAutomaticAnalysisBudget(budget) {
     if (budget.provider === "codex")
-        return `After live runs: Codex account analysis · ${budget.model} · separate restricted analyst with remote inference. Account limits apply; dollar cost and output-token ceiling are unknown. Set review.analysis: false to disable.`;
+        return `After live runs: ${budget.trigger === "default" ? "default " : ""}Codex account analysis · ${budget.model} · separate restricted analyst with remote inference. Account limits apply; dollar cost and output-token ceiling are unknown. Set review.analysis: false to disable.`;
     const rule = admissionRule(`$${budget.maxCostUsd}`);
     // The participants, and the requests that analyse them when there is more than one.
     const requests = analysisRequestsText(analysisRequestCount(Math.min(budget.participants ?? 0, EVIDENCE_LIMITS.participants)));

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

@@ -9,7 +9,7 @@ import { cliAnalysisOptions } from "./analysis-signals.js";
 import { onRunShutdown } from "./run-signals.js";
 import { parseStudyCount, parseParticipantIds, parseObserverPort, wantsJson, writeResult, } from "../io.js";
 import { exposureRequestFromOptions, followDecision, followObserver, planObserver, showObserver, staticObserverOpen, withObserverServer, } from "../observer-follow.js";
-import { writeRunFindings } from "../findings.js";
+import { writeRunResult } from "../run-findings.js";
 import { formatCuaStudyHuman } from "./study-format.js";
 import { resolveRouteShouldOpen } from "./study-route-open.js";
 import { refusedResult } from "../../run/study-result.js";
@@ -236,9 +236,8 @@ async function reportCuaRun(args, prepared, result, live) {
             ],
         };
     }
-    writeResult(args.command, args.io, output, (value) => formatCuaStudyHuman(value, args.config.subject));
+    await writeRunResult(args.command, args.io, args.options.cwd, 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)) {
         const followResult = output.observer?.ok
             ? output.observer

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

@@ -1,8 +1,8 @@
 import { automaticAnalysisSucceeded } from "../../analysis/automatic-completion.js";
 import { Command } from "commander";
 import { cliAnalysisOptions } from "./analysis-signals.js";
-import { wantsJson, writeResult } from "../io.js";
-import { writeRunFindings } from "../findings.js";
+import { wantsJson } from "../io.js";
+import { writeRunResult } from "../run-findings.js";
 import { showObserver } from "../observer-follow.js";
 import { formatScriptedStudyHuman } from "./study-format.js";
 import { observerOpen, resolveRouteShouldOpen, watchFinishedPlan } from "./study-route-open.js";
@@ -34,9 +34,8 @@ export function scriptedRouteRun(args) {
                 throw new Error(`Expected the scripted route, got ${outcome.route}.`);
             }
             const result = outcome.result;
-            writeResult(args.command, args.io, result, (value) => formatScriptedStudyHuman(value, args.config.subject));
+            await writeRunResult(args.command, args.io, args.options.cwd, 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.
             if (finishedPlan !== undefined && result.ok && result.observer !== undefined) {
                 await showObserver({

package/dist/cli/commands/study-route-shared-world.js

@@ -6,7 +6,7 @@ import { redactText } from "../../evidence/redaction.js";
 import { cliAnalysisOptions } from "./analysis-signals.js";
 import { parseObserverPort, wantsJson, writeResult, } from "../io.js";
 import { followDecision, followObserver, showObserver, staticObserverOpen, withObserverServer, } from "../observer-follow.js";
-import { writeRunFindings } from "../findings.js";
+import { writeRunResult } from "../run-findings.js";
 import { formatConcurrentSharedWorldStudyHuman } from "./study-format.js";
 import { resolveRouteShouldOpen, watchFinishedPlan } from "./study-route-open.js";
 import { refusedResult } from "../../run/study-result.js";
@@ -120,9 +120,8 @@ export function sharedWorldRouteRun(args) {
                     ],
                 };
             }
-            writeResult(args.command, args.io, output, formatConcurrentSharedWorldStudyHuman);
+            await writeRunResult(args.command, args.io, args.options.cwd, output, formatConcurrentSharedWorldStudyHuman);
             args.io.setExitCode(result.ok && automaticAnalysisSucceeded(result) ? 0 : 2);
-            await writeRunFindings(args.command, args.io, args.options.cwd, result);
             if (server && output.observer?.ok) {
                 await followObserver(args.io, output.observer, server);
             }

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

@@ -1,8 +1,8 @@
 import { automaticAnalysisSucceeded } from "../../analysis/automatic-completion.js";
 import { Command } from "commander";
 import { cliAnalysisOptions } from "./analysis-signals.js";
-import { wantsJson, writeResult } from "../io.js";
-import { writeRunFindings } from "../findings.js";
+import { wantsJson } from "../io.js";
+import { writeRunResult } from "../run-findings.js";
 import { showObserver } from "../observer-follow.js";
 import { formatTerminalStudyHuman } from "./study-format.js";
 import { observerOpen, resolveRouteShouldOpen, watchFinishedPlan } from "./study-route-open.js";
@@ -34,9 +34,8 @@ export function terminalRouteRun(args) {
                 throw new Error(`Expected the terminal route, got ${outcome.route}.`);
             }
             const result = outcome.result;
-            writeResult(args.command, args.io, result, formatTerminalStudyHuman);
+            await writeRunResult(args.command, args.io, args.options.cwd, result, formatTerminalStudyHuman);
             args.io.setExitCode(result.ok && automaticAnalysisSucceeded(result) ? 0 : 2);
-            await writeRunFindings(args.command, args.io, args.options.cwd, result);
             if (finishedPlan !== undefined && result.ok && result.observer !== undefined) {
                 await showObserver({
                     command: args.command,

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

@@ -138,7 +138,7 @@ export async function runStudyCommand(args) {
                 // Surface it so the invoker (who may not be the manifest author) knows executable code ran.
                 args.io.writeErr(`warning: review scorer ${scorer.provenance.ref} (${scorer.provenance.source}) is code that humanish loaded and ran in this process. Review it as you would any code you run.\n`);
             }
-            const analysisBudget = automaticAnalysisBudget(config.review?.analysis, route, computerUseParticipantCount(config));
+            const analysisBudget = automaticAnalysisBudget(config.review?.analysis, route, computerUseParticipantCount(config), config.actor);
             if (analysisBudget && resolveStudyDryRun(config, args.options.dryRun, true) === false) {
                 args.io.writeErr(`${formatAutomaticAnalysisBudget(analysisBudget)}\n`);
             }

package/dist/cli/doctor.d.ts

@@ -53,6 +53,8 @@ export declare function doctor(cwdInput: string, options?: {
     keyDeps?: KeyResolutionDeps;
     /** The hosted Codex participant's operator handshake; tests replace it. */
     codexParticipantReadiness?: StudySetupCheckArgs["codexParticipantReadiness"];
+    /** The Codex account analyst's setup check; tests replace it. */
+    codexAnalysisReadiness?: StudySetupCheckArgs["codexAnalysisReadiness"];
     /** What `--dotenv` loaded, so a key row names the file that supplied it. */
     dotenv?: DotenvLoad;
 }): Promise<DoctorResult>;

package/dist/cli/doctor.js

@@ -89,6 +89,9 @@ export async function doctor(cwdInput, options = {}) {
             ...(options.codexParticipantReadiness === undefined
                 ? {}
                 : { codexParticipantReadiness: options.codexParticipantReadiness }),
+            ...(options.codexAnalysisReadiness === undefined
+                ? {}
+                : { codexAnalysisReadiness: options.codexAnalysisReadiness }),
         })
         : undefined;
     // Without --study, each key row names the studies that need it instead of failing.

package/dist/cli/findings.d.ts

@@ -1,7 +1,5 @@
-import type { Command } from "commander";
-import type { AutomaticAnalysisOutcome } from "../analysis/job.js";
 import type { AnalysisArtifact, LoadedAnalysis } from "../analysis/types.js";
-import { type CliIo } from "./io.js";
+import { type RunStudyProvenance } from "../run/study-provenance.js";
 export declare const ANALYSIS_FINDINGS_SCHEMA = "humanish.analysis-findings.v1";
 type Finding = NonNullable<AnalysisArtifact["result"]>["findings"][number];
 type DesignFinding = NonNullable<NonNullable<AnalysisArtifact["result"]>["designFindings"]>[number];
@@ -116,6 +114,13 @@ interface FindingsSource {
     analysisOffIn?: string;
     /** For a dry run, the study a live run can start from, read when the view is built. */
     liveStudy?: LiveStudy;
+    /** The run's study, from its bundle. */
+    study?: Pick<RunStudyProvenance, "id" | "path">;
+    /**
+     * Whether Codex is signed in with a ChatGPT account on this machine, read only for an analysis
+     * skipped for a missing OpenAI key, whose next step it picks.
+     */
+    codexSignedIn?: boolean;
 }
 /** A study `run` can start live after a dry run. */
 interface LiveStudy {
@@ -126,24 +131,22 @@ interface LiveStudy {
     /** The study file to set `mode: live` in first, when the file still starts as a dry run. */
     setLiveIn?: string;
 }
+/** ` --cwd <dir>`, or "" when `cwd` is the current directory. */
+export declare function cwdFlag(cwd: string): string;
 /** The findings view of a run's selected analysis, or why it has none. */
 export declare function analysisFindings(source: FindingsSource): AnalysisFindings;
 /**
  * The run's bundle mode and its selected analysis: `analysisId`, or the version `analyze show`
  * defaults to. Null when the run is missing or its storage is unsafe.
  */
-export declare function readRunAnalysis(cwd: string, run: string, analysisId?: string): Promise<FindingsSource | null>;
+export declare function readRunAnalysis(cwd: string, run: string, analysisId?: string, deps?: FindingsDeps): Promise<FindingsSource | null>;
+/** What reading a run's findings needs from this machine; tests replace it. */
+export interface FindingsDeps {
+    /** Whether Codex is signed in with a ChatGPT account. */
+    codexSignedIn?: () => Promise<boolean>;
+}
 /** The view of a run that could not be found. */
 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 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,
- * since that line already says why.
- */
-export declare function writeRunFindings(command: Command, io: CliIo, cwd: string, result: {
-    runId?: string;
-    automaticAnalysis?: AutomaticAnalysisOutcome;
-}): Promise<void>;
+export declare function readRunFindings(cwd: string, run: string, analysisId?: string, deps?: FindingsDeps): Promise<AnalysisFindings>;
 export {};

package/dist/cli/findings.js

@@ -1,5 +1,6 @@
-// A run's analysis findings for `review`, `analyze show` and the end of a live `run`: the
-// `humanish.analysis-findings.v1` projection, read from the run. findings-text.ts prints it. The
+// A run's analysis findings for `review`, `analyze show` and the end of a live `run`
+// (run-findings.ts): the `humanish.analysis-findings.v1` projection, read from the run.
+// findings-text.ts prints it. The
 // analysis artifact stays the record; this reads the version `analyze show` selects and never
 // starts an analysis.
 import path from "node:path";
@@ -15,12 +16,11 @@ import { resolveStudyManifest } from "../study/discover.js";
 import { routeOf } from "../study/routing.js";
 import { plural } from "../run/text.js";
 import { shellQuote } from "../substrates/shell.js";
-import { analysisOutcomeText, wantsJson } from "./io.js";
-import { formatFindingsSummary } from "./findings-text.js";
+import { analysisOutcomeText } from "./io.js";
 import { cli } from "./invocation.js";
 export const ANALYSIS_FINDINGS_SCHEMA = "humanish.analysis-findings.v1";
 /** ` --cwd <dir>`, or "" when `cwd` is the current directory. */
-function cwdFlag(cwd) {
+export function cwdFlag(cwd) {
     if (path.resolve(cwd) === process.cwd())
         return "";
     return ` --cwd ${/^[\w@%+=:,./-]+$/.test(cwd) ? cwd : shellQuote(cwd)}`;
@@ -152,6 +152,18 @@ function dryRunFindings(source) {
         : `set mode: live in ${live.setLiveIn}, then run the next command.`;
     return withoutFindings(source, "dry_run", null, `${opening} Findings come from live runs: ${howLive}`, cli(`run ${live.run}${source.cwdFlag}`));
 }
+/**
+ * An analysis skipped because OPENAI_API_KEY is not set. With Codex signed in, the next step is the
+ * Codex account analyst, named as an opt-in: the study chose the OpenAI analyst, and switching
+ * the account that pays for it is the operator's choice.
+ */
+function missingKeyFindings(source, reason) {
+    const opening = "The automatic analysis was skipped because OPENAI_API_KEY is not set.";
+    if (source.codexSignedIn !== true)
+        return withoutFindings(source, "skipped", reason, `${opening} Set it with ${cli("keys set openai")}, then run the next command.`, analyzeCommand(source, undefined));
+    const file = source.study?.path === undefined ? "the study file" : source.study.path;
+    return withoutFindings(source, "skipped", reason, `${opening} Codex is signed in on this machine, so its ChatGPT account can analyze the run instead, sending the evidence to OpenAI under that account. The next command does it once; review.analysis.provider: codex in ${file} makes it this study's analyst.`, analyzeCommand(source, "codex"));
+}
 /** The findings view of a run's selected analysis, or why it has none. */
 export function analysisFindings(source) {
     if (source.mode !== undefined && source.mode !== "live")
@@ -200,6 +212,8 @@ export function analysisFindings(source) {
         const refusal = costRefusal(job.admission, `--run ${source.runId}${source.cwdFlag}`, cli);
         return withoutFindings(source, "skipped", job.reason, `The automatic analysis was refused before it started. ${refusal.text}`, refusal.command);
     }
+    if (job?.state === "skipped" && job.reason === "AUTOMATIC_ANALYSIS_KEY_MISSING")
+        return missingKeyFindings(source, job.reason);
     if (job?.state === "skipped") {
         const refused = job.reason === "AUTOMATIC_ANALYSIS_ADMISSION_REFUSED";
         return withoutFindings(source, "skipped", job.reason, `The automatic analysis was ${analysisOutcomeText(job)}.${refused ? " The dry run says why, and for a cost refusal names the --max-cost that admits it." : ""}`, job.reason === "AUTOMATIC_ANALYSIS_NO_PARTICIPANT_EVIDENCE"
@@ -253,7 +267,7 @@ async function liveStudyAfterDryRun(cwd, study) {
  * The run's bundle mode and its selected analysis: `analysisId`, or the version `analyze show`
  * defaults to. Null when the run is missing or its storage is unsafe.
  */
-export async function readRunAnalysis(cwd, run, analysisId) {
+export async function readRunAnalysis(cwd, run, analysisId, deps = {}) {
     const physical = await resolvePhysicalCwd(cwd);
     const prepared = await resolveRunPath(physical, run).catch(() => null);
     if (!prepared)
@@ -263,16 +277,30 @@ export async function readRunAnalysis(cwd, run, analysisId) {
     const study = bundle === null ? undefined : studyProvenanceOf(bundle.bundle);
     const analysisOffIn = mode === "live" ? await studyAnalysisOff(physical, study) : undefined;
     const liveStudy = mode !== undefined && mode !== "live" ? await liveStudyAfterDryRun(physical, study) : undefined;
+    const loaded = await loadAnalysis(prepared, analysisId);
+    const codexSignedIn = loaded.automatic?.reason === "AUTOMATIC_ANALYSIS_KEY_MISSING"
+        ? await (deps.codexSignedIn ?? codexSignedInHere)().catch(() => false)
+        : undefined;
     return {
         runId: runIdOf(prepared),
         mode,
         runRoot: prepared.relativeRunRoot,
-        loaded: await loadAnalysis(prepared, analysisId),
+        loaded,
         cwdFlag: cwdFlag(cwd),
         ...(analysisOffIn === undefined ? {} : { analysisOffIn }),
         ...(liveStudy === undefined ? {} : { liveStudy }),
+        ...(study === undefined
+            ? {}
+            : { study: { id: study.id, ...(study.path === undefined ? {} : { path: study.path }) } }),
+        ...(codexSignedIn === undefined ? {} : { codexSignedIn }),
     };
 }
+async function codexSignedInHere() {
+    const { detectLocalAgents } = await import("../actors/local-agent/cli.js");
+    const agents = await detectLocalAgents({ only: "codex" });
+    // The Codex analyst refuses an API-key login, so only a ChatGPT login counts.
+    return agents.some((agent) => agent.authStatus === "authenticated" && agent.billing === "account-unknown");
+}
 /** The view of a run that could not be found. */
 export function missingRunFindings(cwd, run) {
     const loaded = {
@@ -285,29 +313,7 @@ export function missingRunFindings(cwd, run) {
     return withoutFindings({ runId: run, mode: undefined, runRoot: "", loaded, cwdFlag: flag }, "unavailable", "ANALYSIS_RUN_NOT_FOUND", `Run ${run} was not found or its storage is unsafe.`, cli(`runs${flag}`));
 }
 /** The findings of a run's selected analysis, or why it has none. */
-export async function readRunFindings(cwd, run, analysisId) {
-    const source = await readRunAnalysis(cwd, run, analysisId);
+export async function readRunFindings(cwd, run, analysisId, deps = {}) {
+    const source = await readRunAnalysis(cwd, run, analysisId, deps);
     return source ? analysisFindings(source) : missingRunFindings(cwd, run);
 }
-/**
- * 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,
- * since that line already says why.
- */
-export async function writeRunFindings(command, io, cwd, result) {
-    const outcome = result.automaticAnalysis;
-    const analysisId = outcome?.result?.analysisId;
-    if (wantsJson(command) ||
-        result.runId === undefined ||
-        analysisId === undefined ||
-        (outcome?.state !== "complete" && outcome?.state !== "partial"))
-        return;
-    try {
-        const view = await readRunFindings(cwd, result.runId, analysisId);
-        const full = cli(`review --run ${view.runId}${cwdFlag(cwd)}`);
-        io.writeOut(`${formatFindingsSummary(view, full).join("\n")}\n`);
-    }
-    catch {
-        // The run's own result is already printed; review reads the same record later.
-    }
-}

package/dist/cli/io.d.ts

@@ -113,7 +113,11 @@ export declare function messageOutput(value: {
 export declare function humanError(error: CliError | undefined): HumanOutput;
 /** Prints a human formatter's output: text to stdout, an error to stderr through formatCliError. */
 export declare function writeHuman(command: Command, io: CliIo, human: HumanOutput): void;
-export declare function writeResult<T>(command: Command, io: CliIo, result: T, formatHuman: (result: T) => HumanOutput): void;
+/**
+ * Prints a result: JSON for --json, else the human formatter's text and, for a run, its analysis
+ * line. `analysisLines` replaces that line, for a caller that has read what the analysis left.
+ */
+export declare function writeResult<T>(command: Command, io: CliIo, result: T, formatHuman: (result: T) => HumanOutput, analysisLines?: readonly string[]): void;
 export declare function noteRunFacts(command: Command, facts: TelemetryProperties): void;
 /** Exported for tests: the facts writeResult read off a command's result document. */
 export declare function runFactsFor(command: Command): TelemetryProperties;

package/dist/cli/io.js

@@ -178,7 +178,11 @@ export function writeHuman(command, io, human) {
     if (human.error)
         io.writeErr(formatCliError(commandLabel(command), human.error));
 }
-export function writeResult(command, io, result, formatHuman) {
+/**
+ * Prints a result: JSON for --json, else the human formatter's text and, for a run, its analysis
+ * line. `analysisLines` replaces that line, for a caller that has read what the analysis left.
+ */
+export function writeResult(command, io, result, formatHuman, analysisLines) {
     const output = automaticAnalysisEnvelope(result);
     if (wantsJson(command)) {
         // Queued warnings are on stderr already; a JSON caller gets them in warnings[] as well.
@@ -186,9 +190,14 @@ export function writeResult(command, io, result, formatHuman) {
     }
     else {
         writeHuman(command, io, formatHuman(output));
+        if (analysisLines !== undefined) {
+            for (const line of analysisLines)
+                io.writeOut(`${line}\n`);
+        }
+        else if (
         // A run refused before it was created has no analysis to report, so its output ends with the
         // refusal. Its JSON keeps the skip record.
-        if (output !== null &&
+        output !== null &&
             typeof output === "object" &&
             "automaticAnalysis" in output &&
             output.runId !== "not-created") {

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

@@ -0,0 +1,19 @@
+import type { Command } from "commander";
+import type { AutomaticAnalysisOutcome } from "../analysis/job.js";
+import { type FindingsDeps } from "./findings.js";
+import { type CliIo, type HumanOutput } from "./io.js";
+interface RunResultShape {
+    runId?: string;
+    automaticAnalysis?: AutomaticAnalysisOutcome;
+    observer?: {
+        observerPath?: string;
+    };
+}
+/**
+ * Writes a finished run's result. After the route's own output it says what the automatic
+ * analysis did and the command a person runs next; when the analysis left findings, the top ones.
+ * `--json` carries the same message and command on `automaticAnalysis` and the findings summary
+ * as `findings`. A run with no analysis record is written as writeResult writes it.
+ */
+export declare function writeRunResult<T extends RunResultShape>(command: Command, io: CliIo, cwd: string, result: T, formatHuman: (result: T) => HumanOutput, deps?: FindingsDeps): Promise<void>;
+export {};

package/dist/cli/run-findings.js

@@ -0,0 +1,106 @@
+// The end of a live run's output: what its automatic analysis left, read from the run once and
+// written both ways. The human output gets the analysis line, then the top findings or the command
+// that gets them; `--json` gets the same message and command on `automaticAnalysis`, and a bounded
+// `findings` summary when the analysis left findings.
+import { cwdFlag, readRunFindings } from "./findings.js";
+import { formatFindingsSummary } from "./findings-text.js";
+import { cli } from "./invocation.js";
+import { analysisOutcomeText, wantsJson, writeResult } from "./io.js";
+/** At most this many findings go in `run --json`; `review --json` has every one. */
+const TOP_FINDINGS = 5;
+function findingsSummary(view, review, observerPath) {
+    return {
+        analysisId: view.analysisId,
+        status: view.status,
+        count: view.findings.length,
+        designFindingCount: view.designFindings === null ? null : view.designFindings.length,
+        top: view.findings.slice(0, TOP_FINDINGS).map((finding) => ({
+            id: finding.id,
+            title: finding.title,
+            headline: finding.headline,
+            impact: finding.impact,
+            confidence: finding.confidence,
+            participants: finding.affected.map((participant) => participant.streamId),
+        })),
+        review,
+        observer: observerPath === undefined ? null : `${observerPath}#/report`,
+        path: view.path,
+    };
+}
+/** What the run's analysis left: the message, the command, the human lines and any findings. */
+async function readRunReport(cwd, result, deps) {
+    const outcome = result.automaticAnalysis;
+    if (outcome === undefined || result.runId === undefined || result.runId === "not-created")
+        return undefined;
+    const outcomeLine = `analysis: ${analysisOutcomeText(outcome)}`;
+    const plain = {
+        message: `The automatic analysis was ${analysisOutcomeText(outcome)}.`,
+        nextCommand: null,
+        lines: [outcomeLine],
+    };
+    // A dry run left no evidence, and its own output names the live run.
+    if (outcome.reason === "AUTOMATIC_ANALYSIS_DRY_RUN")
+        return plain;
+    const analysisId = outcome.result?.analysisId;
+    const finished = outcome.state === "complete" || outcome.state === "partial";
+    let view;
+    try {
+        view = await readRunFindings(cwd, result.runId, finished ? analysisId : undefined, deps);
+    }
+    catch {
+        return plain;
+    }
+    const rejected = outcome.result?.rejectedOutputPath;
+    const rejectedLine = rejected
+        ? [
+            `analysis: ${outcome.result?.error?.code ?? "rejected"}; the rejected output is kept locally at ${rejected}`,
+        ]
+        : [];
+    const review = cli(`review --run ${view.runId}${cwdFlag(cwd)}`);
+    if (finished && (view.state === "ready" || view.state === "stale"))
+        return {
+            message: view.message,
+            nextCommand: review,
+            lines: [outcomeLine, ...rejectedLine, ...formatFindingsSummary(view, review)],
+            findings: findingsSummary(view, review, result.observer?.observerPath),
+        };
+    // The line reads "analysis: skipped because ...", as it does without the view.
+    const said = view.message.replace(/^The automatic analysis (?:was )?/, "");
+    return {
+        message: view.message,
+        nextCommand: view.next,
+        lines: [
+            `analysis: ${said}`,
+            ...rejectedLine,
+            ...(view.next === null ? [] : [`next: ${view.next}`]),
+        ],
+    };
+}
+/**
+ * Writes a finished run's result. After the route's own output it says what the automatic
+ * analysis did and the command a person runs next; when the analysis left findings, the top ones.
+ * `--json` carries the same message and command on `automaticAnalysis` and the findings summary
+ * as `findings`. A run with no analysis record is written as writeResult writes it.
+ */
+export async function writeRunResult(command, io, cwd, result, formatHuman, deps = {}) {
+    const report = await readRunReport(cwd, result, deps);
+    if (report === undefined || result.automaticAnalysis === undefined) {
+        writeResult(command, io, result, formatHuman);
+        return;
+    }
+    if (!wantsJson(command)) {
+        writeResult(command, io, result, formatHuman, report.lines);
+        return;
+    }
+    writeResult(command, io, {
+        ...result,
+        automaticAnalysis: {
+            ...result.automaticAnalysis,
+            message: report.message,
+            nextCommand: report.nextCommand,
+        },
+        ...(report.findings === undefined ? {} : { findings: report.findings }),
+    }, 
+    // JSON output never calls the human formatter.
+    () => "");
+}

package/dist/guest/bootstrap.d.ts

@@ -3,6 +3,7 @@ import type { Duplex } from "node:stream";
 import { type BrowserControlIdentity } from "../browser-control/protocol.js";
 import { createBrowserControlClient } from "../browser-control/client.js";
 import { type GuestMediaConfig } from "./media-config.js";
+import { type GuestDisplayConfig } from "./display-config.js";
 export declare const GUEST_BOOTSTRAP_VERSION = 1;
 export declare const GUEST_BOOTSTRAP_LIMITS: Readonly<{
     bytes: number;
@@ -18,7 +19,7 @@ export declare const GUEST_BOOTSTRAP_LIMITS: Readonly<{
 /** Same entry authority as the local desktop's opaque app-port forward. */
 export declare function validateGuestInitialUrl(value: string): string;
 export declare function guestReadyTimeoutMs(initialUrl?: string): number;
-export declare function encodeGuestBootstrap(identity: BrowserControlIdentity, ready?: boolean, initialUrl?: string, media?: GuestMediaConfig, recording?: DesktopRecordingConfig): Buffer;
+export declare function encodeGuestBootstrap(identity: BrowserControlIdentity, ready?: boolean, initialUrl?: string, media?: GuestMediaConfig, recording?: DesktopRecordingConfig, display?: GuestDisplayConfig): Buffer;
 export declare function parseGuestBootstrap(bytes: Buffer, revision: string, ready?: boolean): BrowserControlIdentity;
 /** Own the first frame and continue refusing early bytes until synchronous handoff. */
 export declare class GuestBootstrapReader {
@@ -31,6 +32,7 @@ export declare class GuestBootstrapReader {
     initialUrl: string | undefined;
     media: GuestMediaConfig | undefined;
     recording: DesktopRecordingConfig | undefined;
+    display: GuestDisplayConfig | undefined;
     private resolve;
     private reject;
     private readonly header;
@@ -52,4 +54,4 @@ export declare class GuestBootstrapReader {
     close(): void;
 }
 /** Fixed preface on an already acquired Firecracker stream; no path discovery/retry. */
-export declare function connectGuestBootstrap(stream: Duplex, identity: BrowserControlIdentity, signal: AbortSignal, initialUrl?: string, media?: GuestMediaConfig, recording?: DesktopRecordingConfig): Promise<ReturnType<typeof createBrowserControlClient>>;
+export declare function connectGuestBootstrap(stream: Duplex, identity: BrowserControlIdentity, signal: AbortSignal, initialUrl?: string, media?: GuestMediaConfig, recording?: DesktopRecordingConfig, display?: GuestDisplayConfig): Promise<ReturnType<typeof createBrowserControlClient>>;