humanish 0.139.1 → 0.141.0

package/dist/cli/findings.d.ts

@@ -1,7 +1,6 @@
-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 RunAnalysisPhase } from "../run/status.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 +115,35 @@ 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;
+    /**
+     * Where the run is before its findings, from status.json: its participants still running, or
+     * the automatic analysis its own process started. Undefined once neither applies.
+     */
+    progress?: {
+        stage: "participants";
+    }
+    /** The run ended while a participant stream was still running: nothing complete to analyze. */
+     | {
+        stage: "cut-off";
+        running: number;
+        streams: number;
+    } | {
+        stage: "analysis";
+        phase: RunAnalysisPhase;
+        /** status.json's last heartbeat. */
+        updatedAt: string;
+        /** The analyst the run's study gets, read only for an analysis whose process stopped. */
+        provider?: string;
+    };
+    /** When the view was built, for how long an analysis has run. */
+    nowMs?: number;
 }
 /** A study `run` can start live after a dry run. */
 interface LiveStudy {
@@ -126,24 +154,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,26 +1,30 @@
-// 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";
 import { costRefusal } from "../analysis/admission.js";
-import { DEFAULT_ANALYSIS_MAX_COST_USD } from "../analysis/automatic-config.js";
+import { DEFAULT_ANALYSIS_MAX_COST_USD, resolveAutomaticAnalysis, } from "../analysis/automatic-config.js";
+import { ANALYSIS_USUALLY_TAKES } from "../analysis/analysis-limits.js";
 import { bySeverity } from "../analysis/finding-lead.js";
 import { loadAnalysis } from "../analysis/load.js";
 import { projectShareCheckedAnalysis } from "../analysis/sharing.js";
-import { loadRunBundlePrepared, resolveRunPath } from "../run/locate.js";
+import { loadRunBundlePrepared, readRunJsonIfExists, resolveRunPath, runJsonValue, } from "../run/locate.js";
+import { classifyRunStatus, isRunStatusRecord, RUN_STATUS_FILE, runAnalysisPhase, } from "../run/status.js";
+import { TERMINAL_SIMULATION_STATUSES } from "../run/streams.js";
+import { formatDuration } from "../run/projection.js";
 import { resolvePhysicalCwd, runIdOf } from "../run/paths.js";
 import { studyProvenanceOf } from "../run/study-provenance.js";
 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 +156,69 @@ 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 view of a run whose findings are not written yet: participants still running, an analysis
+ * running, or an analysis whose process stopped before it finished. Undefined otherwise.
+ */
+function pendingFindings(source, job) {
+    const again = cli(`review --run ${source.runId}${source.cwdFlag}`);
+    const progress = source.progress;
+    if (progress?.stage === "participants" && job === undefined)
+        return withoutFindings(source, "running", null, source.analysisOffIn === undefined
+            ? "Participants are still running in this run, so no analysis has started. Automatic analysis starts when they finish, and the findings follow it."
+            : "Participants are still running in this run. Analysis is turned off in its study, so none starts when they finish.", again);
+    if (progress?.stage === "cut-off" && job === undefined)
+        return withoutFindings(source, "skipped", "ANALYSIS_RUN_INCOMPLETE", `This run ended while ${progress.running} of ${progress.streams} participant streams were still running, so its recording is incomplete and no analysis ran. Run the study again with the next command.`, cli(`run ${source.study?.id ?? "<study>"}${source.cwdFlag}`));
+    const phase = progress?.stage === "analysis" ? progress.phase : undefined;
+    const jobPending = job?.state === "queued" || job?.state === "running";
+    if (jobPending || (job === undefined && phase?.state === "running")) {
+        const since = phase === undefined
+            ? ""
+            : ` It started at ${phase.startedAt}, ${formatDuration(Math.max(0, (source.nowMs ?? Date.now()) - Date.parse(phase.startedAt)))} ago.`;
+        return withoutFindings(source, "running", null, `The automatic analysis is running.${since} Findings usually take ${ANALYSIS_USUALLY_TAKES}; check again then.`, again);
+    }
+    const stopped = (job?.state === "unknown" && job.reason === "AUTOMATIC_ANALYSIS_STOPPED") ||
+        (job === undefined && phase?.state === "stopped");
+    if (!stopped)
+        return undefined;
+    const at = job?.updatedAt ?? (progress?.stage === "analysis" ? progress.updatedAt : undefined);
+    return withoutFindings(source, "failed", "AUTOMATIC_ANALYSIS_STOPPED", `The automatic analysis stopped before it wrote findings: the process running it stopped updating its record${at === undefined ? "" : ` at ${at}`}, most likely because it ended. Analyze the run again with the next command.`, analyzeCommand(source, progress?.stage === "analysis" ? progress.provider : undefined));
+}
+/**
+ * A run that ended, by a signal, a process that left without publishing, or a heartbeat that
+ * stopped, while some participant stream was still running. Undefined for any other run.
+ */
+function cutOff(bundle, record, nowMs) {
+    if (bundle === undefined || bundle.outcome?.state === "finished")
+        return undefined;
+    if (bundle.outcome === undefined &&
+        (record === null || classifyRunStatus(record, nowMs) !== "interrupted"))
+        return undefined;
+    const running = bundle.streams.filter((stream) => !TERMINAL_SIMULATION_STATUSES.has(stream.status) || stream.liveActor !== undefined).length;
+    return running === 0 ? undefined : { stage: "cut-off", running, streams: bundle.streams.length };
+}
+/** The analyst the run's study gets, when its file still names the same study. */
+async function studyAnalyst(cwd, study) {
+    if (study?.path === undefined)
+        return undefined;
+    const resolved = await resolveStudyManifest(cwd, study.path).catch(() => null);
+    if (!resolved?.ok || resolved.config.id !== study.id)
+        return undefined;
+    const analysis = resolveAutomaticAnalysis(resolved.config.review?.analysis, resolved.config.actor);
+    return analysis.ok ? analysis.config?.provider : undefined;
+}
 /** 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")
@@ -188,8 +255,9 @@ export function analysisFindings(source) {
     if (loaded.warnings.includes("ANALYSIS_SENSITIVE_TEXT_QUARANTINED"))
         return withoutFindings(source, "unavailable", "ANALYSIS_SENSITIVE_TEXT_QUARANTINED", `The analysis text matched a sensitive-text pattern, so it is not printed. ${cli(`analyze show --run ${source.runId}${source.cwdFlag} --json`)} prints the raw record.`, null);
     const job = loaded.automatic;
-    if (job?.state === "queued" || job?.state === "running")
-        return withoutFindings(source, "running", null, "The automatic analysis is still running. Check again when it finishes.", cli(`review --run ${source.runId}${source.cwdFlag}`));
+    const pending = pendingFindings(source, job);
+    if (pending !== undefined)
+        return pending;
     if (analysis && analysis.result === null)
         return withoutFindings(source, "failed", analysis.error, `Analysis attempt ${analysis.id} ${analysis.status === "cancelled" ? "was cancelled" : "failed"}${analysis.error ? ` (${analysis.error})` : ""} and left no findings.`, analyzeCommand(source, analysis.provider));
     if (job?.state === "failed" || job?.state === "cancelled") {
@@ -200,6 +268,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 +323,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 +333,50 @@ 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 nowMs = Date.now();
+    const status = runJsonValue(await readRunJsonIfExists(prepared, RUN_STATUS_FILE));
+    const record = isRunStatusRecord(status) && status.runId === runIdOf(prepared) ? status : null;
+    const phase = record === null ? undefined : runAnalysisPhase(record, nowMs);
+    const stopped = phase?.state === "stopped" || loaded.automatic?.reason === "AUTOMATIC_ANALYSIS_STOPPED";
+    const provider = stopped ? await studyAnalyst(physical, study) : undefined;
+    const progress = phase !== undefined && record !== null
+        ? {
+            stage: "analysis",
+            phase,
+            updatedAt: record.updatedAt,
+            ...(provider === undefined ? {} : { provider }),
+        }
+        : bundle?.bundle.outcome === undefined &&
+            record !== null &&
+            classifyRunStatus(record, nowMs) === "running"
+            ? { stage: "participants" }
+            : cutOff(bundle?.bundle, record, nowMs);
+    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 }),
+        ...(progress === undefined ? {} : { progress }),
+        nowMs,
     };
 }
+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 +389,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") {
@@ -306,6 +315,7 @@ const ANALYSIS_REASON_TEXT = {
     AUTOMATIC_ANALYSIS_CANCELLATION_UNAVAILABLE: "outcome unknown: a cancellation could not be recorded",
     AUTOMATIC_ANALYSIS_STORAGE_UNAVAILABLE: "outcome unknown: analysis storage is unavailable",
     AUTOMATIC_ANALYSIS_OUTCOME_UNKNOWN: "outcome unknown",
+    AUTOMATIC_ANALYSIS_STOPPED: "outcome unknown: the process running it stopped before it finished",
 };
 export function analysisOutcomeText(analysis) {
     if (analysis.reason === null)

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/evidence/browser-hygiene.d.ts

@@ -4,4 +4,15 @@
  * place so browser-backed routes can prefer product pixels over browser UI.
  */
 export declare const CHROMIUM_EVIDENCE_HYGIENE_FLAGS: readonly ["--disable-background-networking", "--disable-component-update", "--disable-default-apps", "--disable-domain-reliability", "--disable-extensions", "--disable-sync", "--no-default-browser-check", "--no-first-run", "--password-store=basic", "--use-mock-keychain"];
-export declare function chromiumEvidenceProfilePreferencesJson(): string;
+/**
+ * The profile preference that lets a web `targetUrl`'s origin open the external app schemes
+ * without Chrome's prompt: the "always allow" choice Chrome stores per origin, which needs no root
+ * and no managed policy. Links from other origins still prompt. Undefined for any other target.
+ */
+export declare function externalAppPreferences(targetUrl: string | undefined): {
+    protocol_handler: {
+        allowed_origin_protocol_pairs: Record<string, Record<string, true>>;
+    };
+} | undefined;
+/** The profile's Preferences file, with externalAppPreferences for a web `targetUrl`. */
+export declare function chromiumEvidenceProfilePreferencesJson(targetUrl?: string): string;

package/dist/evidence/browser-hygiene.js

@@ -37,6 +37,49 @@ const CHROMIUM_EVIDENCE_PROFILE_PREFERENCES = {
         password_manager_enabled: false,
     },
 };
-export function chromiumEvidenceProfilePreferencesJson() {
-    return JSON.stringify(CHROMIUM_EVIDENCE_PROFILE_PREFERENCES);
+/**
+ * Schemes whose links Chrome hands to another app after asking "Open xdg-open?". The desktop's
+ * stand-ins answer them (src/substrates/e2b/desktop-handoff.ts), so the prompt is browser chrome
+ * a person on their own computer would not see for that app. Chrome never asks for mailto.
+ */
+const EXTERNAL_APP_SCHEMES = [
+    "callto",
+    "facetime",
+    "facetime-audio",
+    "geo",
+    "maps",
+    "mms",
+    "msteams",
+    "sip",
+    "skype",
+    "slack",
+    "sms",
+    "tel",
+    "webcal",
+    "whatsapp",
+    "zoommtg",
+];
+/**
+ * The profile preference that lets a web `targetUrl`'s origin open the external app schemes
+ * without Chrome's prompt: the "always allow" choice Chrome stores per origin, which needs no root
+ * and no managed policy. Links from other origins still prompt. Undefined for any other target.
+ */
+export function externalAppPreferences(targetUrl) {
+    const target = targetUrl === undefined ? null : URL.parse(targetUrl);
+    if (target === null || !/^https?:$/.test(target.protocol))
+        return undefined;
+    return {
+        protocol_handler: {
+            allowed_origin_protocol_pairs: {
+                [target.origin]: Object.fromEntries(EXTERNAL_APP_SCHEMES.map((scheme) => [scheme, true])),
+            },
+        },
+    };
+}
+/** The profile's Preferences file, with externalAppPreferences for a web `targetUrl`. */
+export function chromiumEvidenceProfilePreferencesJson(targetUrl) {
+    return JSON.stringify({
+        ...CHROMIUM_EVIDENCE_PROFILE_PREFERENCES,
+        ...externalAppPreferences(targetUrl),
+    });
 }

package/dist/feedback/export-bundle.js

@@ -47,7 +47,7 @@ function omittedReason(relative) {
         return "automatic execution intent and liveness do not transfer to a derivative";
     if (isAnalysisRecordPath(relative))
         return "analysis records bind original evidence hashes; reanalyze the derivative";
-    if (relative.startsWith(".analysis-lock/"))
+    if (relative.startsWith(".analysis-lock"))
         return "local analysis execution lock";
     return (OMITTED.get(relative) ??
         (["feedback/draft.json", "feedback/issue.md"].includes(relative)

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