humanish 0.113.0 → 0.115.0

package/dist/analysis/finding-lead.d.ts

@@ -0,0 +1,27 @@
+import type { AnalysisCorrection, AnalysisResult } from "./types.js";
+type Severity = NonNullable<AnalysisResult["designFindings"]>[number]["severity"];
+export interface FindingLead {
+    /** The reviewer's amended claim, or the plain headline. */
+    headline: string;
+    /**
+     * The line under the headline: the plain experience, or after an amendment a sentence saying the
+     * reviewer's claim replaced the headline and account. Null when the analysis wrote no experience.
+     */
+    account: string | null;
+    /** The headline is a reviewer's amended claim. */
+    corrected: boolean;
+}
+/**
+ * The headline and account a finding leads with, given its latest human review note. An amendment
+ * replaces both, since they describe the claim the reviewer replaced. Null for an analysis written
+ * before headlines, which leads with the finding's title.
+ */
+export declare function findingLead(finding: {
+    headline?: string | null;
+    experience?: string | null;
+}, correction: Pick<AnalysisCorrection, "status" | "replacementClaim"> | null | undefined): FindingLead | null;
+/** Design findings most severe first, in a new array; equal severity keeps the analysis order. */
+export declare function bySeverity<T extends {
+    severity: Severity;
+}>(findings: readonly T[]): T[];
+export {};

package/dist/analysis/finding-lead.js

@@ -0,0 +1,23 @@
+// How a finding opens for a reader, the same in `review`, a feedback draft and the Observer. The
+// Observer bundles this module, so it imports types only (observer/tests/contract-lock.test.ts).
+/**
+ * The headline and account a finding leads with, given its latest human review note. An amendment
+ * replaces both, since they describe the claim the reviewer replaced. Null for an analysis written
+ * before headlines, which leads with the finding's title.
+ */
+export function findingLead(finding, correction) {
+    if (finding.headline === undefined || finding.headline === null)
+        return null;
+    if (correction?.status === "amended" && correction.replacementClaim)
+        return {
+            headline: correction.replacementClaim,
+            account: "Corrected in human review. The reviewer's claim replaces the original headline and account.",
+            corrected: true,
+        };
+    return { headline: finding.headline, account: finding.experience ?? null, corrected: false };
+}
+const SEVERITY_ORDER = ["major", "moderate", "minor"];
+/** Design findings most severe first, in a new array; equal severity keeps the analysis order. */
+export function bySeverity(findings) {
+    return findings.toSorted((a, b) => SEVERITY_ORDER.indexOf(a.severity) - SEVERITY_ORDER.indexOf(b.severity));
+}

package/dist/analysis/image-tokens.d.ts

@@ -1 +1,3 @@
+/** 2,500 patches × 1.2: what any image costs on these models when its size is unknown. */
+export declare const HIGH_DETAIL_IMAGE_TOKEN_CEILING = 3000;
 export declare function highDetailImageTokens(model: string, dataUrl: string): number;

package/dist/analysis/image-tokens.js

@@ -16,7 +16,7 @@ const HIGH_DETAIL_SIZING = Object.freeze({
     "gpt-5.5": { patchBudget: 2500, multiplierTenths: 12 },
 });
 /** 2,500 patches × 1.2: what any image costs on these models when its size is unknown. */
-const HIGH_DETAIL_IMAGE_TOKEN_CEILING = 3000;
+export const HIGH_DETAIL_IMAGE_TOKEN_CEILING = 3000;
 const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
 /** Width and height from a PNG data URL's IHDR chunk; undefined for anything else. */
 function pngDimensions(dataUrl) {

package/dist/analysis/job.d.ts

@@ -1,6 +1,7 @@
 import type { AnalyzeResult } from "./service.js";
 import { z } from "zod";
 import { type PreparedRunArtifactPaths } from "../run/paths.js";
+import type { RefusedAnalysisCost } from "./admission.js";
 export declare const AUTOMATIC_ANALYSIS_DIRECTORY = "analysis-automatic";
 export declare const AUTOMATIC_ANALYSIS_STALE_MS = 15000;
 /** Execution metadata only. Never a participant outcome or permission to dispatch. */
@@ -11,6 +12,8 @@ export interface AutomaticAnalysisView {
     /** Safe stable code, not provider text. */
     reason: string | null;
     updatedAt: string;
+    /** What the analysis would have cost, when admission refused it for its cost. */
+    admission?: RefusedAnalysisCost;
 }
 export interface AutomaticAnalysisOutcome {
     state: "complete" | "partial" | "failed" | "cancelled" | "skipped" | "unknown";
@@ -69,6 +72,11 @@ declare const jobSchema: z.ZodObject<{
     receiptSha256: z.ZodNullable<z.ZodString>;
     startedAt: z.ZodNullable<z.ZodISODateTime>;
     finishedAt: z.ZodNullable<z.ZodISODateTime>;
+    admission: z.ZodOptional<z.ZodObject<{
+        expectedCostUsd: z.ZodNumber;
+        worstCaseCostUsd: z.ZodNumber;
+        maxCostUsd: z.ZodNumber;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 type JobRecord = z.infer<typeof jobSchema>;
 /** Also guards direct HTML projection callers, not only the contained-file reader. */
@@ -86,7 +94,7 @@ export declare function readAutomaticAnalysisPrepared(prepared: PreparedRunArtif
 export interface AutomaticAnalysisJob {
     readonly attemptId: string;
     /** Serialized, awaited durability boundary. A failed write must prevent dispatch. */
-    update(update: Partial<Pick<JobRecord, "state" | "analysisId" | "reason" | "sourceRunSha256" | "inputDigest" | "startedAt" | "analysisSha256" | "receiptSha256">>): Promise<void>;
+    update(update: Partial<Pick<JobRecord, "state" | "analysisId" | "reason" | "sourceRunSha256" | "inputDigest" | "startedAt" | "analysisSha256" | "receiptSha256" | "admission">>): Promise<void>;
     touch(): Promise<void>;
     cancellationRequested(): Promise<boolean>;
 }

package/dist/analysis/job.js

@@ -52,6 +52,12 @@ const reasons = [
 const id = z.string().regex(ANALYSIS_ID_PATTERN);
 const date = z.iso.datetime();
 const digest = z.string().regex(SHA256_HEX_PATTERN);
+const usd = z.number().min(0).max(1e9);
+const refusedCostSchema = z.strictObject({
+    expectedCostUsd: usd,
+    worstCaseCostUsd: usd,
+    maxCostUsd: usd,
+});
 const jobSchema = z.strictObject({
     schema: z.literal(AUTOMATIC_ANALYSIS_SCHEMA),
     runId: id,
@@ -70,6 +76,7 @@ const jobSchema = z.strictObject({
     receiptSha256: digest.nullable(),
     startedAt: date.nullable(),
     finishedAt: date.nullable(),
+    admission: refusedCostSchema.optional(),
 });
 const cancelSchema = z.strictObject({
     schema: z.literal(CANCEL_SCHEMA),
@@ -111,11 +118,12 @@ export function projectAutomaticAnalysisView(value) {
     if (value === undefined)
         return undefined;
     const parsed = jobSchema
-        .pick({ state: true, analysisId: true, reason: true, updatedAt: true })
+        .pick({ state: true, analysisId: true, reason: true, updatedAt: true, admission: true })
         .safeParse(value);
     if (!parsed.success || containsSensitive(JSON.stringify(parsed.data)))
         return unknown();
-    return parsed.data;
+    const { admission, ...view } = parsed.data;
+    return admission === undefined ? view : { ...view, admission };
 }
 async function bindJob(prepared) {
     await validatePreparedRunRootIdentity(prepared);
@@ -162,6 +170,7 @@ export async function readAutomaticAnalysisPrepared(prepared, now = Date.now())
             analysisId: record.analysisId,
             reason: record.reason,
             updatedAt: record.updatedAt,
+            ...(record.admission === undefined ? {} : { admission: record.admission }),
         };
         const updated = Date.parse(record.updatedAt);
         if (updated > now || (pending(record.state) && now - updated > AUTOMATIC_ANALYSIS_STALE_MS)) {

package/dist/analysis/service.js

@@ -17,6 +17,8 @@ import { appendAnalysisCorrection, assertAnalysisPublicationCapacity, listAnalys
 import { beginAnalysisExecution, writeAnalysisExecutionReceipt } from "./store-executions.js";
 import { keepRejectedAnalysisOutput } from "./diagnostics.js";
 import { loadAnalysis } from "./load.js";
+import { costRefusal, refusedCost } from "./admission.js";
+import { cli } from "../cli/invocation.js";
 import { hashAnalysisValue } from "./validation.js";
 import { ANALYSIS_CORRECTION_SCHEMA, } from "./types.js";
 import { RUN_BUNDLE_FILE } from "../run/bundle.js";
@@ -188,17 +190,20 @@ function analyzeConfigRefusal(config) {
 }
 /** The result when admission refuses the attempt, or when a dry run stops after admission. */
 function admissionOnlyResult(base, config) {
-    if (!base.admission.allowed)
+    if (!base.admission.allowed) {
+        const cost = refusedCost(base.admission);
+        const refusal = cost && costRefusal(cost, `--run ${base.run}`, cli);
         return {
             ...base,
             ok: false,
             error: {
                 code: base.admission.error ?? "analysis_admission_denied",
-                message: base.admission.error === "analysis_budget_exceeded"
-                    ? "The conservative admission estimate exceeds --max-cost. No provider request was sent."
+                message: refusal
+                    ? `${refusal.text} ${refusal.command}`
                     : "The analysis input or configuration did not pass admission. No provider request was sent.",
             },
         };
+    }
     return {
         ...base,
         ok: true,

package/dist/cli/commands/analyze.js

@@ -29,7 +29,7 @@ export function registerAnalyzeCommand(parent, io) {
         .option("--run <id>", RUN_OPTION_DESCRIPTION, "latest")
         .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--provider <name>", "Analyst: openai (default) or restricted codex account. No provider fallback.")
-        .option("--max-cost <usd>", "Required for OpenAI, also with --dry-run: send nothing when the estimated cost in USD is above this. The estimate is not a billing cap. Unsupported for Codex.")
+        .option("--max-cost <usd>", "Required for OpenAI, also with --dry-run: send nothing when the expected cost in USD, plus a 10% margin, is above this. It does not limit billing. Unsupported for Codex.")
         .option("--model <id>", "Supported vision model. OpenAI uses high effort; qualified Codex account analysis uses low effort.", DEFAULT_ANALYSIS_MODEL)
         .option("--question <text>", "Additional reviewer question; does not change participant instructions.")
         .option("--timeout-ms <ms>", "Request timeout, at most 600000 ms.", String(DEFAULT_ANALYSIS_TIMEOUT_MS))
@@ -125,7 +125,7 @@ async function handleAnalyze(io, options, command) {
             if (value.ok && value.dryRun && selected.config?.provider === "codex")
                 return "Local evidence and configuration passed admission. Codex CLI, login and model access were not checked. Dollar cost and output-token ceiling are unknown. No provider request sent.\n";
             if (value.ok && value.dryRun)
-                return `Admission estimate: $${value.admission?.estimatedCostUsd ?? "unknown"}; output allowance: ${value.admission?.outputTokenAllowance ?? "unknown"} tokens including reasoning. No request sent.\n`;
+                return admittedDryRunText(value.admission);
             const lines = [];
             if (value.artifactPath)
                 lines.push(`${value.reused ? "Reused" : "Saved"} ${value.status} analysis: ${value.artifactPath}`);
@@ -231,3 +231,8 @@ async function handleAnalyzeCorrect(io, options, command) {
         io.setExitCode(2);
     }
 }
+/** An admitted dry run's costs: the expected cost, the worst case and the cap it was admitted under. */
+function admittedDryRunText(admission) {
+    const usd = (value) => value === null || value === undefined ? "unknown" : `$${value.toFixed(2)}`;
+    return `Expected cost: ${usd(admission?.estimatedCostUsd)}. Worst case: ${usd(admission?.worstCaseCostUsd)}, if the analyst writes its whole ${admission?.outputTokenAllowance ?? "unknown"}-token output allowance, reasoning included. Admitted under the $${admission?.maxCostUsd ?? "unknown"} cap. No request sent.\n`;
+}

package/dist/cli/commands/notes.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+import { type CliIo } from "../io.js";
+export declare function registerNotesCommand(parent: Command, io: CliIo): void;

package/dist/cli/commands/notes.js

@@ -0,0 +1,145 @@
+import { renderObserver } from "../../observer/render.js";
+import { loadRunBundlePrepared, resolveRunPath } from "../../run/locate.js";
+import { readRunNotes } from "../../run/note-files.js";
+import { byRunTime } from "../../run/note-shape.js";
+import { addRunNote, formatRunTime } from "../../run/notes.js";
+import { runParticipantCaptions, streamParticipantIdOf } from "../../run/participant-records.js";
+import { resolvePhysicalCwd, runIdOf } from "../../run/paths.js";
+import { runNotFoundMessage } from "../../run/run-not-found.js";
+import { cli } from "../invocation.js";
+import { CWD_OPTION_DESCRIPTION, humanError, JSON_OPTION_DESCRIPTION, writeResult, } from "../io.js";
+const NOTES_RESULT_SCHEMA = "humanish.notes-result.v1";
+export function registerNotesCommand(parent, io) {
+    parent
+        .command("notes")
+        .description("List the reviewer notes on a run, or add one at a moment of its recording. A note's time counts from the run's first timed capture, as the Observer's study timeline shows it.")
+        .summary("List or add reviewer notes on a run.")
+        // The text is read from the words after the run, not declared, so the root command list
+        // stays as narrow as its other rows and an unquoted note still arrives whole.
+        .usage("[options] <run> [text...]")
+        .argument("<run>", "Run id, or latest.")
+        .allowExcessArguments(true)
+        .option("--add", "Add a note. Its text is the words after the run; --at gives the moment.")
+        .option("--at <mm:ss>", "With --add: the moment, in minutes and seconds, such as 02:31.")
+        .option("--participant <id>", "With --add: the participant's id from the study, or its stream id. Leave it out for a note on the whole run.")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .addHelpText("after", [
+        "",
+        "Examples:",
+        "  humanish notes latest",
+        '  humanish notes latest --add --at 02:31 "The save button was hidden here."',
+        '  humanish notes <runId> --add --at 00:45 --participant <id> "They gave up."',
+        "",
+        "Each note is saved in the run directory as notes/<id>.json. Text that looks like a secret",
+        "or a local path is replaced before it is saved, and verify scans notes like other run text.",
+    ].join("\n"))
+        .action((run, options, command) => {
+        const words = command.args.slice(1);
+        return handleNotes(io, run, words.length > 0 ? words.join(" ") : undefined, options, command);
+    });
+}
+/** Minutes and seconds as the Observer shows them, `02:31`, in milliseconds; null otherwise. */
+function parseRunTime(value) {
+    const match = /^(\d{1,4}):([0-5]\d)$/.exec(value.trim());
+    return match ? (Number(match[1]) * 60 + Number(match[2])) * 1000 : null;
+}
+async function handleNotes(io, run, text, options, command) {
+    const base = {
+        schema: NOTES_RESULT_SCHEMA,
+        cwd: options.cwd,
+        run,
+        notes: [],
+        participants: [],
+        warnings: [],
+    };
+    const fail = (code, message) => {
+        writeResult(command, io, { ...base, ok: false, error: { code, message } }, formatNotesHuman);
+        io.setExitCode(2);
+    };
+    const adding = options.add === true;
+    if (!adding && (text !== undefined || options.at !== undefined))
+        return fail("HUMANISH_NOTES_OPTION_CONFLICT", `Adding a note needs --add: ${cli(`notes ${run} --add --at 02:31 "text"`)}.`);
+    if (adding && (options.at === undefined || text === undefined))
+        return fail("HUMANISH_NOTES_OPTION_CONFLICT", `--add needs --at and the note's text: ${cli(`notes ${run} --add --at 02:31 "text"`)}.`);
+    const atMs = options.at === undefined ? null : parseRunTime(options.at);
+    if (adding && atMs === null)
+        return fail("HUMANISH_NOTE_INVALID_TIME", `--at ${options.at ?? ""} is not a time on the run clock. Give minutes and seconds from the run's first capture, as the Observer shows them, such as 02:31.`);
+    const cwd = await resolvePhysicalCwd(options.cwd);
+    const prepared = await resolveRunPath(cwd, run).catch(() => null);
+    if (!prepared)
+        return fail("HUMANISH_RUN_NOT_FOUND", await runNotFoundMessage(cwd, run));
+    const runId = runIdOf(prepared);
+    let added;
+    const warnings = [];
+    if (adding && atMs !== null && text !== undefined) {
+        const result = await addRunNote(prepared, {
+            atMs,
+            participant: options.participant ?? null,
+            text,
+        });
+        if (!result.ok)
+            return fail(result.error.code, result.error.message);
+        added = result.note;
+        if (result.scrubbed)
+            warnings.push("Part of the note looked like a secret or a local path, so it was replaced before the note was saved.");
+        // The saved Observer page shows notes read-only, so it is rendered again with the new one.
+        const rendered = await renderObserver(cwd, runId, { open: false, expectedRun: prepared })
+            .then((observer) => observer.ok)
+            .catch(() => false);
+        if (!rendered)
+            warnings.push(`The note is saved, but the run's saved Observer page could not be rendered again. ${cli(`observe --run ${runId}`)} shows it.`);
+    }
+    const notes = await readRunNotes(prepared);
+    // A note file that cannot be read is named and left as it is; the others are listed.
+    warnings.push(...notes.skipped);
+    const result = {
+        ...base,
+        ok: true,
+        run: runId,
+        notes: byRunTime(notes.notes),
+        participants: await participantsOf(cwd, prepared),
+        ...(added === undefined ? {} : { added }),
+        warnings,
+    };
+    writeResult(command, io, result, formatNotesHuman);
+    io.setExitCode(0);
+}
+/** The run's participants with their captions; none when its run.json cannot be read. */
+async function participantsOf(cwd, prepared) {
+    const loaded = await loadRunBundlePrepared(cwd, prepared).catch(() => null);
+    if (!loaded)
+        return [];
+    const captions = runParticipantCaptions(loaded.bundle);
+    return loaded.bundle.streams.map((stream) => {
+        const participantId = streamParticipantIdOf(stream);
+        return {
+            id: stream.id,
+            ...(participantId === undefined ? {} : { participantId }),
+            caption: captions.get(stream.id) ?? stream.id,
+        };
+    });
+}
+/** Who a note is about, as a person reads it. */
+function participantName(result, participant) {
+    if (participant === null)
+        return "whole run";
+    return result.participants.find((entry) => entry.id === participant)?.caption ?? participant;
+}
+function noteLine(note, name, width) {
+    const head = `  ${formatRunTime(note.atMs)}  ${name.padEnd(width)}  `;
+    const [first = "", ...rest] = note.text.split("\n");
+    return [`${head}${note.author}: ${first}`, ...rest.map((line) => `         ${line}`)].join("\n");
+}
+function formatNotesHuman(result) {
+    if (!result.ok)
+        return humanError(result.error);
+    const warnings = result.warnings.map((warning) => `warning: ${warning}\n`).join("");
+    if (result.added)
+        return `Added a note at ${formatRunTime(result.added.atMs)} ${result.added.participant === null ? "on the whole run" : `for ${participantName(result, result.added.participant)}`} to run ${result.run}. The Observer marks it on the study timeline, and ${cli(`notes ${result.run}`)} lists every note.\n${warnings}`;
+    if (result.notes.length === 0)
+        return `Run ${result.run} has no reviewer notes. Add one: ${cli(`notes ${result.run} --add --at 00:30 "text"`)}\n${warnings}`;
+    const names = result.notes.map((note) => participantName(result, note.participant));
+    const width = Math.max(...names.map((name) => name.length));
+    return `${[`Reviewer notes on run ${result.run}: ${result.notes.length}`, ...result.notes.map((note, index) => noteLine(note, names[index], width))].join("\n")}\n${warnings}`;
+}

package/dist/cli/commands/observe.js

@@ -152,7 +152,7 @@ async function observeRun(io, options, command) {
         ...(openResult.command ? { openCommand: openResult.command } : {}),
         warnings: [
             ...rendered.warnings,
-            "Observer is served read-only over loopback http on 127.0.0.1; only this run's bundle directory is exposed.",
+            "Observer is served over loopback http on 127.0.0.1; only this run's bundle directory is exposed, and the one change the page can make is adding a reviewer note.",
             ...(openResult.warning ? [openResult.warning] : []),
         ],
     };

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

@@ -7,6 +7,7 @@ import { warnAndQueue } from "../deprecations.js";
 import { planStudy, resolveStudyDryRun } from "../../study/plan.js";
 import { keyNamesOf } from "../../study/requirements.js";
 import { routeOf } from "../../study/plan.js";
+import { computerUseParticipantCount } from "../../study/routing.js";
 import { computerUseRouteRun } from "./study-route-computer-use.js";
 import { runRoute } from "./study-route-run.js";
 import { scriptedRouteRun } from "./study-route-scripted.js";
@@ -130,7 +131,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);
+            const analysisBudget = automaticAnalysisBudget(config.review?.analysis, route, computerUseParticipantCount(config));
             if (analysisBudget && resolveStudyDryRun(config, args.options.dryRun, true) === false) {
                 args.io.writeErr(`${formatAutomaticAnalysisBudget(analysisBudget)}\n`);
             }

package/dist/cli/findings.js

@@ -2,7 +2,9 @@
 // `humanish.analysis-findings.v1` projection and its text. 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 { bySeverity, findingLead } from "../analysis/finding-lead.js";
 import { loadAnalysis } from "../analysis/load.js";
 import { projectShareCheckedAnalysis } from "../analysis/sharing.js";
 import { loadRunBundlePrepared, resolveRunPath } from "../run/locate.js";
@@ -63,20 +65,13 @@ function evidenceOf(finding, analysis, runRoot) {
         ...entry,
     }));
 }
-const SEVERITY_RANK = {
-    major: 0,
-    moderate: 1,
-    minor: 2,
-};
 /** Most severe first; equal severity keeps the analysis order. */
 function designFindingViews(analysis, runRoot) {
     const designFindings = analysis.result?.designFindings;
     if (designFindings === undefined)
         return null;
     const labels = new Map(analysis.participants.map((p) => [p.streamId, p.label]));
-    return [...designFindings]
-        .sort((a, b) => SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity])
-        .map((finding) => ({
+    return bySeverity(designFindings).map((finding) => ({
         id: finding.id,
         headline: finding.headline,
         screen: finding.screen,
@@ -199,9 +194,13 @@ export function analysisFindings(source) {
         const outcome = analysisOutcomeText(job);
         return withoutFindings(source, "failed", job.reason, `The automatic analysis ${outcome.startsWith("failed") ? "" : "was "}${outcome}.`, analyzeCommand(source, job.reason === "AUTOMATIC_ANALYSIS_CODEX_UNAVAILABLE" ? "codex" : undefined));
     }
+    if (job?.state === "skipped" && job.admission) {
+        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") {
         const refused = job.reason === "AUTOMATIC_ANALYSIS_ADMISSION_REFUSED";
-        return withoutFindings(source, "skipped", job.reason, `The automatic analysis was ${analysisOutcomeText(job)}.${refused ? " The dry run prints its cost estimate; run it again with a --max-cost above the estimate." : ""}`, job.reason === "AUTOMATIC_ANALYSIS_NO_PARTICIPANT_EVIDENCE"
+        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"
             ? null
             : `${analyzeCommand(source, undefined)}${refused ? " --dry-run" : ""}`);
     }
@@ -339,18 +338,6 @@ function captureFiles(evidence, runRoot) {
             .map((entry) => (runRoot ? path.relative(runRoot, entry.capture) : entry.capture))),
     ];
 }
-/**
- * What a reader sees first: the headline, or the reviewer's claim when a review amended the finding,
- * since the headline and experience describe the claim it replaced. Null before headlines existed.
- */
-function leadOf(finding) {
-    const amended = finding.correction?.status === "amended" ? finding.correction : null;
-    if (finding.headline === null)
-        return null;
-    return amended?.replacementClaim
-        ? { headline: amended.replacementClaim, corrected: true }
-        : { headline: finding.headline, corrected: false };
-}
 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]));
@@ -358,19 +345,13 @@ function findingLines(finding, runRoot) {
     const streams = [...affectedIds, ...cited.filter((id) => !labels.has(id))];
     const captures = captureFiles(finding.evidence, runRoot);
     const correction = finding.correction;
-    const lead = leadOf(finding);
+    const lead = findingLead(finding, correction);
     return [
         ...(lead === null
             ? [`${finding.id} ${finding.title}`]
             : [
                 `${finding.id} ${lead.headline}`,
-                ...(lead.corrected
-                    ? [
-                        "   Corrected in human review. The reviewer's claim replaces the original headline and account.",
-                    ]
-                    : finding.experience === null
-                        ? []
-                        : [`   ${finding.experience}`]),
+                ...(lead.account === null ? [] : [`   ${lead.account}`]),
                 `   evidence: ${finding.title}`,
             ]),
         `   impact: ${IMPACT_TEXT[finding.impact]} · confidence: ${finding.confidence} · recovery: ${RECOVERY_TEXT[finding.recovery]}`,
@@ -448,7 +429,7 @@ export function formatFindingsSummary(view, fullCommand, limit = 3) {
         `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 = leadOf(finding);
+            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})`;

package/dist/cli/io.d.ts

@@ -138,4 +138,5 @@ export declare function analysisOutcomeText(analysis: {
     state: string;
     reason: string | null;
 }): string;
+/** Preserve the run's own result while making requested post-processing failures machine-visible. */
 export declare function automaticAnalysisEnvelope<T>(result: T): T;

package/dist/cli/io.js

@@ -1,5 +1,5 @@
-import { automaticAnalysisSucceeded, defaultAnalysisOverBudget, } from "../analysis/automatic-completion.js";
-import { DEFAULT_ANALYSIS_MAX_COST_USD } from "../analysis/automatic-config.js";
+import { automaticAnalysisSucceeded, } from "../analysis/automatic-completion.js";
+import { costRefusal, refusedCost } from "../analysis/admission.js";
 import { Command, Option } from "commander";
 import { loadEnvFile, recordDotenvNames } from "../keys/env-file.js";
 import { discoverProviderKeys } from "../keys/key-resolution.js";
@@ -188,13 +188,15 @@ export function writeResult(command, io, result, formatHuman) {
         writeHuman(command, io, formatHuman(output));
         if (output !== null && typeof output === "object" && "automaticAnalysis" in output) {
             const analysis = output.automaticAnalysis;
-            if (analysis)
+            const cost = analysis?.result?.admission && refusedCost(analysis.result.admission);
+            const refusal = cost && costRefusal(cost, `--run ${analysis.result?.run ?? "latest"}`, cli);
+            if (refusal)
+                io.writeOut(`analysis: refused before it started. ${refusal.text} ${refusal.command}\n`);
+            else if (analysis)
                 io.writeOut(`analysis: ${analysisOutcomeText(analysis)}\n`);
             const rejected = analysis?.result?.rejectedOutputPath;
             if (rejected)
                 io.writeOut(`analysis: ${analysis.result?.error?.code ?? "rejected"}; the rejected output is kept locally at ${rejected}\n`);
-            if (defaultAnalysisOverBudget(output))
-                io.writeOut(overBudgetAnalysisHint(output));
         }
     }
     markInvocationEnvelopeWritten(command);
@@ -286,7 +288,7 @@ const ANALYSIS_REASON_TEXT = {
     AUTOMATIC_ANALYSIS_SOURCE_UNAVAILABLE: "skipped because the run's evidence could not be read",
     AUTOMATIC_ANALYSIS_ALREADY_REQUESTED: "skipped because this run's analysis was already requested",
     AUTOMATIC_ANALYSIS_BUSY: "skipped because another analysis is running",
-    AUTOMATIC_ANALYSIS_ADMISSION_REFUSED: "not started because its configuration or question was refused",
+    AUTOMATIC_ANALYSIS_ADMISSION_REFUSED: "refused before it started: its configuration, question, evidence or cost did not pass admission",
     AUTOMATIC_ANALYSIS_CLEANUP_UNCONFIRMED: "not started because the run's cleanup was not confirmed",
     AUTOMATIC_ANALYSIS_REUSED: "complete, reusing an earlier analysis of the same evidence",
     AUTOMATIC_ANALYSIS_LIMITATIONS: "partial, because it covered only part of the evidence",
@@ -306,12 +308,6 @@ export function analysisOutcomeText(analysis) {
     return ANALYSIS_REASON_TEXT[analysis.reason] ?? `${analysis.state} (${analysis.reason})`;
 }
 /** Preserve the run's own result while making requested post-processing failures machine-visible. */
-function overBudgetAnalysisHint(result) {
-    const estimate = result.automaticAnalysis?.result?.admission?.estimatedCostUsd ?? null;
-    const suggested = Math.ceil(estimate ?? DEFAULT_ANALYSIS_MAX_COST_USD + 1);
-    const shown = estimate === null ? "" : ` ($${estimate.toFixed(2)})`;
-    return `analysis: its estimate${shown} is over the default $${DEFAULT_ANALYSIS_MAX_COST_USD} cap, so no request was sent. To analyze this run: ${cli(`analyze --run ${result.runId ?? "latest"} --max-cost ${suggested}`)}\n`;
-}
 export function automaticAnalysisEnvelope(result) {
     if (result === null ||
         typeof result !== "object" ||

package/dist/cli/program.js

@@ -13,6 +13,7 @@ import { registerCommsCommands } from "./commands/comms.js";
 import { registerFeedbackCommands } from "./commands/feedback.js";
 import { registerStudyCommands } from "./commands/study.js";
 import { registerMigrateCommand } from "./commands/migrate.js";
+import { registerNotesCommand } from "./commands/notes.js";
 import { registerObserveCommand } from "./commands/observe.js";
 import { registerCleanupCommand, registerExportCommand, registerReclaimCommand, registerReviewCommand, registerRunCommand, registerRunsCommand, registerRuntimeCommands, registerStatsCommand, registerVerifyCommand, } from "./commands/runs.js";
 import { registerDoctorCommand, registerInitCommand, registerKeysCommand, registerTelemetryCommand, } from "./commands/setup.js";
@@ -392,6 +393,7 @@ export function createProgram(io = {}) {
     registerVerifyCommand(program, cliIo);
     registerReviewCommand(program, cliIo);
     registerAnalyzeCommand(program, cliIo);
+    registerNotesCommand(program, cliIo);
     registerFeedbackCommands(program, cliIo);
     registerExportCommand(program, cliIo);
     registerRunsCommand(program, cliIo);