humanish 0.112.0 → 0.114.0

package/dist/analysis/evidence-sources.js

@@ -204,7 +204,12 @@ function spreadOrder(entries) {
     }
     return result;
 }
-export function sourceOrder(entries, capturesOnly) {
+/** The trace messages that carry a participant's closing impressions. */
+export function impressionEventIds(stream) {
+    const impressions = stream.actor?.impressions;
+    return new Set(impressions?.status === "collected" ? impressions.items.map((item) => item.messageId) : []);
+}
+export function sourceOrder(entries, capturesOnly, impressions = new Set()) {
     const candidates = capturesOnly ? entries.filter((entry) => entry.capturePath !== null) : entries;
     const ordered = new Set();
     const admit = (entry) => {
@@ -214,6 +219,10 @@ export function sourceOrder(entries, capturesOnly) {
     // Actor endings precede appended run bookkeeping when text slots are scarce.
     if (!capturesOnly)
         admit(entries.findLast((entry) => !entry.kind.startsWith("run_event:")));
+    // The participant's closing impressions are its only opinions of the product; keep them all.
+    for (const entry of entries)
+        if (impressions.has(entry.eventId))
+            admit(entry);
     admit(candidates.at(-1));
     admit(candidates[0]);
     const afterCapture = [];

package/dist/analysis/evidence.js

@@ -6,7 +6,7 @@ import { isRecord } from "../run/type-guards.js";
 import { RUN_BUNDLE_FILE } from "../run/bundle.js";
 import { ACTION_CAPTURE_VERSION, } from "./types.js";
 import { digestAnalysisInput, hashAnalysisValue, validateAnalysisInputMetadata, } from "./validation.js";
-import { boundedText, fairShares, hasUnmappedCaptures, participantAssignment, participantSource, sourceEntries, sourceOrder, } from "./evidence-sources.js";
+import { boundedText, fairShares, hasUnmappedCaptures, participantAssignment, participantSource, sourceEntries, sourceOrder, impressionEventIds, } from "./evidence-sources.js";
 import { readBoundedFile, readBoundedFileResult } from "../run/evidence-files.js";
 export const EVIDENCE_LIMITS = Object.freeze({
     participants: 16,
@@ -312,7 +312,7 @@ function recordCaptureOmissions(packings, sel, omissions) {
             omissions.add("Some declared captures have no normalized trace reference.");
         for (const source of packing.captures.keys())
             packing.admitted.add(source);
-        for (const source of sourceOrder(packing.entries, false)) {
+        for (const source of sourceOrder(packing.entries, false, impressionEventIds(packing.stream))) {
             if (packing.admitted.size >= sel.evidenceShares[index])
                 break;
             packing.admitted.add(source);

package/dist/analysis/execute.d.ts

@@ -1,7 +1,7 @@
 import { type AnalysisArtifact, type AnalysisConfig, type AnalysisInput } from "./types.js";
 import { type AnalysisFetch, type AnalysisProvider } from "./provider.js";
 import type { RejectedAnalysisOutput } from "./diagnostics.js";
-export declare const ANALYSIS_PROMPT_VERSION = "study-evidence-7";
+export declare const ANALYSIS_PROMPT_VERSION = "study-evidence-8";
 export declare const isSupportedAnalysisModel: (model: string) => boolean;
 /** The OpenAI output limit when a study omits maxOutputTokens, and the most it may ask for. */
 export declare const DEFAULT_ANALYSIS_MAX_OUTPUT_TOKENS = 16384;
@@ -9,9 +9,14 @@ export declare const MAX_ANALYSIS_OUTPUT_TOKENS = 32768;
 export interface AnalysisAdmission {
     allowed: boolean;
     error: string | null;
+    /** The input tokens admission priced. */
     inputTokenAllowance: number | null;
     outputTokenAllowance: number | null;
+    /** The expected cost. Admission compares it, with a margin, with maxCostUsd. */
     estimatedCostUsd: number | null;
+    /** The cost if the analyst spends its whole output allowance. */
+    worstCaseCostUsd: number | null;
+    maxCostUsd: number | null;
     ratesAsOf: string | null;
 }
 export interface AnalysisProgress {
@@ -23,15 +28,24 @@ export interface AnalysisProgress {
 }
 /**
  * Local admission estimate, not a provider-enforced billed-spend guarantee. No token-count API
- * call, credential, or network access. One UTF-8 byte/token for all text/schema plus framing is
- * intentionally conservative. Each high-detail image is priced from its PNG size by the vision
- * guide's patch formula (see image-tokens.ts), or at the 3,000-token ceiling when its size or the
- * model's sizing is unknown. Unknown models/rates fail closed rather than inheriting those
- * assumptions.
+ * call, credential, or network access. admission.ts holds the cost model: text at a calibrated
+ * bytes-per-token ratio, the expected output, and the worst case that spends the whole output
+ * allowance. Each high-detail image is priced from its PNG size by the vision guide's patch
+ * formula (see image-tokens.ts), or at the 3,000-token ceiling when its size or the model's sizing
+ * is unknown. Unknown models/rates fail closed rather than inheriting those assumptions.
  * Known-sensitive decoded text denies admission with analysis_input_sensitive or
  * analysis_question_sensitive. Neither error includes rejected input values.
  */
 export declare function estimateAnalysisAdmission(input: AnalysisInput, config: AnalysisConfig): AnalysisAdmission;
+/**
+ * The expected cost of an analysis for this many participants before any evidence exists: from a
+ * packet with no evidence to one at the evidence limits with every capture at the image-token
+ * ceiling. Undefined for Codex and for a model without rates.
+ */
+export declare function analysisCostRange(config: AnalysisConfig, participants: number): {
+    low: number;
+    high: number;
+} | undefined;
 /** Only for an omitted output limit. Preserve the established allowance when
  * more reasoning/report space would refuse a study its declared budget admits.
  * This is one pre-dispatch choice, never a fallback request or a budget increase. */

package/dist/analysis/execute.js

@@ -1,5 +1,6 @@
 import { validCodexAnalysisConfig } from "./codex-config.js";
-import { highDetailImageTokens } from "./image-tokens.js";
+import { HIGH_DETAIL_IMAGE_TOKEN_CEILING, highDetailImageTokens } from "./image-tokens.js";
+import { estimateAnalysisCost } from "./admission.js";
 import { createHash, randomUUID } from "node:crypto";
 import { estimateActorCost, MODEL_RATES } from "../run/pricing.js";
 import { containsSensitive } from "../evidence/redaction.js";
@@ -10,7 +11,7 @@ import { checkAnalysisResult, hashAnalysisValue, analysisResponseSchema, analysi
 import { EVIDENCE_LIMITS } from "./evidence.js";
 import { truncatedFrameWarning, unknownNotificationsWarning, } from "../actors/codex/restricted-notifications.js";
 import { protocolAdditionsWarning, protocolIncompatibilityMessage, } from "../actors/codex/protocol-compat.js";
-export const ANALYSIS_PROMPT_VERSION = "study-evidence-7";
+export const ANALYSIS_PROMPT_VERSION = "study-evidence-8";
 const SUPPORTED_ANALYSIS_MODELS = Object.freeze([
     "gpt-6-astra",
     "gpt-5.5",
@@ -61,6 +62,8 @@ Write for the person who will act on the report: a designer, product manager or
 
 Separately, review the supplied captures as an experienced product designer would and report designFindings: problems a designer would notice in what the screens show, whether or not any participant mentioned them. Look at the size of text and controls (too small to read or to hit comfortably at this window size), layout and density (spread too wide or packed too tight for the task), visual hierarchy, legibility and contrast, wording and labels, consistency between screens, feedback after actions, and anything that makes the product look unfinished or untrustworthy. Judge the screens as the participants' personas would meet them: who they are and what they came to do. Each design finding names the screen in plain words, says what a designer notices, why it matters to a person using the product, and one concrete suggestion. Each must cite at least one supplied capture that shows the problem, and seenByStreamIds lists only participants whose cited captures show it. Rate severity by the effect on a person using the product: major when it misleads or blocks, moderate when it slows or confuses, minor when it is polish. Report only what the captures show; no capture, no design finding. Use D1, D2, and so on as IDs. An empty designFindings array is correct when the captures show no design problem worth a designer's time. Write design findings in the same plain register as headlines.
 
+Messages that begin "Impression (kind):" are a participant's closing impressions of the product, where kind is unclear, unfinished, untrustworthy, liked, missing or unlike my work. They are that participant's own opinions: use them as participant statements and quote the words after the label. An unlike my work impression says where the screen differs from how the persona does the same task in its own work or life; with a capture of that screen it is a strong design finding, which cites both. Without such a capture, an impression supports only a finding about what the participant said.
+
 Order findings by observed task impact, replication among exposed participants, and recovery. Preserve severity and confidence as separate fields. Do not compute a numeric frustration score or universal priority score. Use F1, F2, and so on as local finding IDs. Explain ordering with concrete evidence. Provide a short, testable next check for each finding. Say when recovery was not observed rather than claiming it was impossible. Keep titles and summaries concise and specific. The overall summary must be grounded in participant reviews and observations, including successful outcomes and evidence limits.`;
 function instructions(config) {
     return `${INSTRUCTIONS}\n\nResearcher question (null means use the standard review): ${JSON.stringify(config.question)}`;
@@ -126,11 +129,11 @@ function inputError(input) {
 }
 /**
  * Local admission estimate, not a provider-enforced billed-spend guarantee. No token-count API
- * call, credential, or network access. One UTF-8 byte/token for all text/schema plus framing is
- * intentionally conservative. Each high-detail image is priced from its PNG size by the vision
- * guide's patch formula (see image-tokens.ts), or at the 3,000-token ceiling when its size or the
- * model's sizing is unknown. Unknown models/rates fail closed rather than inheriting those
- * assumptions.
+ * call, credential, or network access. admission.ts holds the cost model: text at a calibrated
+ * bytes-per-token ratio, the expected output, and the worst case that spends the whole output
+ * allowance. Each high-detail image is priced from its PNG size by the vision guide's patch
+ * formula (see image-tokens.ts), or at the 3,000-token ceiling when its size or the model's sizing
+ * is unknown. Unknown models/rates fail closed rather than inheriting those assumptions.
  * Known-sensitive decoded text denies admission with analysis_input_sensitive or
  * analysis_question_sensitive. Neither error includes rejected input values.
  */
@@ -141,6 +144,8 @@ export function estimateAnalysisAdmission(input, config) {
         inputTokenAllowance: 0,
         outputTokenAllowance: 0,
         estimatedCostUsd: null,
+        worstCaseCostUsd: null,
+        maxCostUsd: null,
         ratesAsOf: null,
     });
     if ((config.provider === "codex"
@@ -172,6 +177,8 @@ export function estimateAnalysisAdmission(input, config) {
             inputTokenAllowance: null,
             outputTokenAllowance: null,
             estimatedCostUsd: null,
+            worstCaseCostUsd: null,
+            maxCostUsd: null,
             ratesAsOf: null,
         };
     const rate = MODEL_RATES[config.model];
@@ -182,32 +189,56 @@ export function estimateAnalysisAdmission(input, config) {
         !Number.isFinite(rate.outputUsdPerToken) ||
         rate.outputUsdPerToken < 0)
         return denied("analysis_rate_unknown");
-    const inputTokenAllowance = Buffer.byteLength(JSON.stringify({
-        instructions: instructions(config),
-        evidence: evidenceText(input),
-        schema: analysisResultJsonSchema,
-    })) +
-        2048 +
-        input.images.reduce((sum, image) => sum + highDetailImageTokens(config.model, image.dataUrl), 0);
-    const long = rate.longContext !== undefined && inputTokenAllowance > rate.longContext.thresholdInputTokens;
-    const inputRate = Math.max(rate.inputUsdPerToken, rate.cacheWriteUsdPerToken ?? 0, rate.cachedInputUsdPerToken ?? 0);
-    const estimate = inputTokenAllowance * inputRate * (long ? rate.longContext.inputMultiplier : 1) +
-        config.maxOutputTokens *
-            rate.outputUsdPerToken *
-            (long ? rate.longContext.outputMultiplier : 1);
-    // Round upward for admission; rounding a small positive boundary down could admit an overrun.
-    const estimatedCostUsd = Math.ceil(estimate * 1e6) / 1e6;
-    if (!Number.isFinite(estimatedCostUsd))
+    const cost = estimateAnalysisCost(rate, {
+        textBytes: Buffer.byteLength(instructions(config)) +
+            Buffer.byteLength(evidenceText(input)) +
+            Buffer.byteLength(JSON.stringify(analysisResultJsonSchema)),
+        imageTokens: input.images.reduce((sum, image) => sum + highDetailImageTokens(config.model, image.dataUrl), 0),
+        participants: input.participants.length,
+        outputAllowance: config.maxOutputTokens,
+    });
+    if (!Number.isFinite(cost.worstCaseCostUsd))
         return denied("analysis_rate_unknown");
+    const allowed = cost.admittedCostUsd <= config.maxCostUsd;
     return {
-        allowed: estimatedCostUsd <= config.maxCostUsd,
-        error: estimatedCostUsd <= config.maxCostUsd ? null : "analysis_budget_exceeded",
-        inputTokenAllowance,
+        allowed,
+        error: allowed ? null : "analysis_budget_exceeded",
+        inputTokenAllowance: cost.inputTokens,
         outputTokenAllowance: config.maxOutputTokens,
-        estimatedCostUsd,
+        estimatedCostUsd: cost.expectedCostUsd,
+        worstCaseCostUsd: cost.worstCaseCostUsd,
+        maxCostUsd: config.maxCostUsd,
         ratesAsOf: rate.asOf,
     };
 }
+/** Structure each evidence entry adds to the packet: ids, kind, timestamps and flags. The largest
+ * retained packet averaged 200 bytes. */
+const ENTRY_STRUCTURE_BYTES = 256;
+/**
+ * The expected cost of an analysis for this many participants before any evidence exists: from a
+ * packet with no evidence to one at the evidence limits with every capture at the image-token
+ * ceiling. Undefined for Codex and for a model without rates.
+ */
+export function analysisCostRange(config, participants) {
+    if (config.provider === "codex")
+        return undefined;
+    const rate = MODEL_RATES[config.model];
+    if (!rate || rate.placeholder)
+        return undefined;
+    const prompt = Buffer.byteLength(instructions(config)) +
+        Buffer.byteLength(JSON.stringify(analysisResultJsonSchema));
+    const size = {
+        participants: Math.min(participants, EVIDENCE_LIMITS.participants),
+        outputAllowance: config.maxOutputTokens,
+    };
+    const low = estimateAnalysisCost(rate, { ...size, textBytes: prompt, imageTokens: 0 });
+    const high = estimateAnalysisCost(rate, {
+        ...size,
+        textBytes: prompt + EVIDENCE_LIMITS.textBytes + EVIDENCE_LIMITS.evidence * ENTRY_STRUCTURE_BYTES,
+        imageTokens: EVIDENCE_LIMITS.captures * HIGH_DETAIL_IMAGE_TOKEN_CEILING,
+    });
+    return { low: low.expectedCostUsd, high: high.expectedCostUsd };
+}
 /** Only for an omitted output limit. Preserve the established allowance when
  * more reasoning/report space would refuse a study its declared budget admits.
  * This is one pre-dispatch choice, never a fallback request or a budget increase. */
@@ -462,9 +493,11 @@ function settleCompletedOutput(artifact, input, config, admission, response, onR
     artifact.result = checked.result;
     artifact.status = input.coverage.complete ? "complete" : "partial";
     artifact.error = null;
+    // A bill above the expected cost is a normal outcome. Only one above the worst case or the cap
+    // shows the estimate was wrong.
     if (config.provider !== "codex" &&
         ((response.usage?.output ?? 0) > config.maxOutputTokens ||
-            (artifact.usage.estimatedCostUsd ?? 0) > (admission.estimatedCostUsd ?? config.maxCostUsd) ||
+            (artifact.usage.estimatedCostUsd ?? 0) > (admission.worstCaseCostUsd ?? config.maxCostUsd) ||
             (artifact.usage.estimatedCostUsd ?? 0) > config.maxCostUsd)) {
         artifact.status = "partial";
         artifact.error = "analysis_admission_estimate_exceeded";

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,7 @@ import { appendAnalysisCorrection, assertAnalysisPublicationCapacity, listAnalys
 import { beginAnalysisExecution, writeAnalysisExecutionReceipt } from "./store-executions.js";
 import { keepRejectedAnalysisOutput } from "./diagnostics.js";
 import { loadAnalysis } from "./load.js";
+import { admittingMaxCost, costRefusalText, refusedCost } from "./admission.js";
 import { hashAnalysisValue } from "./validation.js";
 import { ANALYSIS_CORRECTION_SCHEMA, } from "./types.js";
 import { RUN_BUNDLE_FILE } from "../run/bundle.js";
@@ -188,17 +189,19 @@ 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);
         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: cost
+                    ? `${costRefusalText(cost)} To run it, raise the cap: humanish analyze --run ${base.run} --max-cost ${admittingMaxCost(cost)}`
                     : "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,144 @@
+import { renderObserver } from "../../observer/render.js";
+import { loadRunBundlePrepared, resolveRunPath } from "../../run/locate.js";
+import { addRunNote, formatRunTime, readRunNotes, runParticipantCaptions, } from "../../run/notes.js";
+import { 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;
+}
+const byRunTime = (notes) => [...notes].sort((left, right) => left.atMs - right.atMs || left.createdAt.localeCompare(right.createdAt));
+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] : []),
         ],
     };