humanish 0.113.0 → 0.114.0

package/CHANGELOG.md

@@ -8,6 +8,28 @@ The Unreleased section holds the full notes for the next version until it is tag
 
 ## Unreleased
 
+## 0.114.0: Reviewer notes, expected analysis cost, percent-encoded UTF-8 in verify (2026-10-08)
+
+humanish 0.114.0 lets a reviewer note a moment of a recorded run, admits post-run analysis on its
+expected cost, and reads percent escapes as UTF-8 when it checks a run for secrets. Pause the study
+timeline in an Observer served on 127.0.0.1 and choose "Add a note at 02:31", or run
+`humanish notes <run> --add --at 02:31 "text"`. Each note is saved as its own file under `notes/`
+in the run directory, marked on the study timeline and listed under "Reviewer notes" in Findings,
+and `verify`, HTML export and feedback drafts read it. Analysis admission now prices input at 3
+bytes per token and output at 12,000 tokens plus 1,000 per participant, and runs an analysis when
+that expected cost plus 10% is within the cap, so the default $3 cap no longer refuses analyses
+billed at $1 to $2. A refusal names the expected cost, the worst case, the cap and the
+`humanish analyze --max-cost` command that admits it, and `study check` and live starts give the
+expected cost range for the study's participant count. In `analyze --json`,
+`admission.estimatedCostUsd` is now the expected cost. OpenAI computer-use traces list the
+impressions request in `conversation.requests` with `kind: impressions`. `verify` and bundle
+export also read percent escapes as UTF-8, so a percent-encoded password that starts with a
+non-ASCII letter grades its run blocked, and the known-value scrub finds a percent-encoded value
+with non-ASCII characters. The scrub also checks its matches against redaction markers by binary
+search, so 1 MiB of markers and values takes well under a second instead of about 5 s.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.114.0)
+
 ## 0.113.0: Participant impressions, mission and persona warnings, local desktop capacity, key status, update notice (2026-10-07)
 
 humanish 0.113.0 asks computer-use participants what they thought at the end of a session, warns

package/CONTEXT.md

@@ -41,6 +41,7 @@ bundle and output fields keep older spellings; the second table maps them.
 | analysis            | An independent model reading of a finished run's retained evidence, kept apart from participant feedback. Supported live runs request it automatically, and `humanish analyze` runs it on demand. It records findings and observations as `humanish.study-analysis.v1`.                                                                                                                                                                                                                                                               | `src/analysis/`; `runAutomaticAnalysis` in `src/analysis/automatic.ts`; `analyzeRun` in `src/analysis/service.ts`; `ANALYSIS_SCHEMA` in `src/analysis/types.ts`                                                                                                                                                                                                                                             |
 | finding             | A result of analysis, with citations to evidence in the run. Each finding groups the observations that support it.                                                                                                                                                                                                                                                                                                                                                                                                                    | `src/analysis/`                                                                                                                                                                                                                                                                                                                                                                                             |
 | observation         | One claim in analysis with its basis, evidence ids and limitation. `concernReviews[]` gives each material concern's observation a disposition: `finding`, `context` or `unsupported`.                                                                                                                                                                                                                                                                                                                                                 | `src/analysis/`                                                                                                                                                                                                                                                                                                                                                                                             |
+| reviewer note       | Free text a person adds at a moment of a recorded run, for one participant or the whole run, kept in the run directory as its own file, `notes/<id>.json` (`humanish.run-note.v1`). It is not participant feedback or analysis. `humanish notes` and an Observer served on loopback add notes.                                                                                                                                                                                                                                        | `addRunNote` in `src/run/notes.ts`; `readRunNotes` in `src/run/note-files.ts`; `createNotesWriter` in `src/observer/notes-route.ts`                                                                                                                                                                                                                                                                         |
 
 ## Read these field spellings as the concept they name
 

package/README.md

@@ -219,7 +219,7 @@ The OpenAI API default stays unchanged. See the [analysis contract](docs/contrac
 coverage limits, estimated cost controls, corrections and sharing behavior.
 
 Supported live studies generate findings automatically after participants finish,
-using a separate $3 admission estimate limit with `gpt-6-astra` and high reasoning.
+using a separate $3 cap on the expected cost with `gpt-6-astra` and high reasoning.
 This is additional to participant execution costs, and is not a hard provider
 billing cap. To disable the extra request:
 

package/dist/actors/computer-use/openai-conversation.js

@@ -73,7 +73,7 @@ export class OpenAiConversation {
         const sent = this.newItems(req);
         return {
             body: () => closing === undefined ? this.turnBody(req, sent) : this.closingBody(req, sent, closing),
-            accept: (reply) => this.accept(reply, closing !== undefined, sent),
+            accept: (reply) => this.accept(reply, closing, sent),
         };
     }
     /**
@@ -171,10 +171,10 @@ export class OpenAiConversation {
     accept(reply, closing, sent) {
         // Recorded before the reply is accepted: accepting can cut the carried history, and the record
         // counts what this request carried.
-        if (!closing)
-            this.evidence.requested(this.mode, this.carried, sent);
+        if (closing !== "report")
+            this.evidence.requested(this.mode, this.carried, sent, closing);
         const parsed = parseOpenAiResponse(reply);
-        if (!closing && parsed.turn.interruption === "output_limit")
+        if (closing === undefined && parsed.turn.interruption === "output_limit")
             return parsed.turn;
         if (parsed.turn.responseId !== undefined)
             this.lastResponseId = parsed.turn.responseId;
@@ -206,10 +206,11 @@ class ConversationRecord {
         // Counted like requests[], which includes replies set aside at their output limit.
         this.switchedAtRequest = this.requests.length + 1;
     }
-    /** A participant request went out with `sent` after `conversation`. */
-    requested(mode, conversation, sent) {
+    /** A participant turn or impressions request went out with `sent` after `conversation`. */
+    requested(mode, conversation, sent, kind) {
+        const marker = kind === undefined ? {} : { kind };
         if (mode !== "explicit_context") {
-            this.requests.push({ mode: "threaded" });
+            this.requests.push({ mode: "threaded", ...marker });
             return;
         }
         const carried = conversation.size();
@@ -217,6 +218,7 @@ class ConversationRecord {
         this.summarizedTurns = carried.notedTurns;
         this.requests.push({
             mode: "explicit_context",
+            ...marker,
             carriedExchanges: carried.exchanges,
             carriedScreenshots: carried.screenshots,
             estimatedInputTokens: carried.estimatedTokens + estimateTokens(sent),

package/dist/actors/contract.d.ts

@@ -261,11 +261,13 @@ export interface ActorConversation {
      */
     summarizedTurns: number;
     /**
-     * Per participant request, in order: its mode and, in explicit_context, what it carried and its
-     * estimated input. `tokenUsage.turns` has each request's billed input.
+     * Per participant turn or impressions request, in order: its mode and, in explicit_context,
+     * what it carried and its estimated input. `tokenUsage.turns` has each request's billed input.
      */
     requests: Array<{
         mode: "threaded" | "explicit_context";
+        /** Present for the impressions-only request; absent for participant turns and older bundles. */
+        kind?: "impressions";
         carriedExchanges?: number;
         carriedScreenshots?: number;
         estimatedInputTokens?: number;

package/dist/analysis/admission.d.ts

@@ -0,0 +1,37 @@
+import type { ModelRate } from "../run/pricing.js";
+/** Admission compares the expected cost times this margin with the cap. */
+export declare const ADMISSION_MARGIN = 1.1;
+export interface AnalysisRequestSize {
+    /** UTF-8 bytes of the instructions, the evidence packet and the result schema. */
+    textBytes: number;
+    imageTokens: number;
+    participants: number;
+    /** The request's output limit. The worst case spends all of it. */
+    outputAllowance: number;
+}
+export interface AnalysisCostEstimate {
+    inputTokens: number;
+    expectedOutputTokens: number;
+    expectedCostUsd: number;
+    worstCaseCostUsd: number;
+    /** The expected cost with the margin, never above the worst case: what admission compares. */
+    admittedCostUsd: number;
+}
+export declare function estimateAnalysisCost(rate: ModelRate, size: AnalysisRequestSize): AnalysisCostEstimate;
+/** The numbers a cost refusal reports. */
+export interface RefusedAnalysisCost {
+    expectedCostUsd: number;
+    worstCaseCostUsd: number;
+    maxCostUsd: number;
+}
+/** The --max-cost that admits a refused analysis: its worst case, rounded up to a whole dollar. */
+export declare function admittingMaxCost(cost: RefusedAnalysisCost): number;
+/** Why admission refused an analysis, in plain words. */
+export declare function costRefusalText(cost: RefusedAnalysisCost): string;
+/** The admission's refused cost, when it refused the analysis for its cost. */
+export declare function refusedCost(admission: {
+    error: string | null;
+    estimatedCostUsd: number | null;
+    worstCaseCostUsd: number | null;
+    maxCostUsd: number | null;
+}): RefusedAnalysisCost | undefined;

package/dist/analysis/admission.js

@@ -0,0 +1,60 @@
+// The admission cost model for one study analysis request: the expected cost, the worst case, and
+// the figure admission compares with the cap.
+/**
+ * UTF-8 bytes per input token for the instructions, evidence packet and schema. On 148 billed
+ * gpt-6-astra analyses the evidence packet ran 3.1 to 3.3 bytes per token and the instructions
+ * more, so 3 stays above every billed input. Chinese, Japanese and Korean text is 3 bytes per
+ * character in UTF-8, so it also counts at least a token per character.
+ */
+const BYTES_PER_INPUT_TOKEN = 3;
+/** Request framing on top of the text and the images. */
+const FRAMING_TOKENS = 2048;
+/**
+ * The output an analysis is expected to write, reasoning included. The most any billed analysis
+ * used was 12,511 tokens for one participant and 16,722 for eight.
+ */
+const EXPECTED_OUTPUT_TOKENS = 12_000;
+const EXPECTED_OUTPUT_TOKENS_PER_PARTICIPANT = 1_000;
+/** Admission compares the expected cost times this margin with the cap. */
+export const ADMISSION_MARGIN = 1.1;
+/** Rounded up to the micro-dollar, so a small positive boundary never rounds into admission. */
+const roundUp = (usd) => Math.ceil(usd * 1e6) / 1e6;
+/** One request's cost. Input is priced at the highest input rate the model bills, cache writes
+ * included, and the long-context tier re-prices the whole request past its threshold. */
+function requestCost(rate, inputTokens, outputTokens) {
+    const long = rate.longContext !== undefined && inputTokens > rate.longContext.thresholdInputTokens;
+    const inputRate = Math.max(rate.inputUsdPerToken, rate.cacheWriteUsdPerToken ?? 0, rate.cachedInputUsdPerToken ?? 0);
+    return roundUp(inputTokens * inputRate * (long ? rate.longContext.inputMultiplier : 1) +
+        outputTokens * rate.outputUsdPerToken * (long ? rate.longContext.outputMultiplier : 1));
+}
+export function estimateAnalysisCost(rate, size) {
+    const inputTokens = Math.ceil(size.textBytes / BYTES_PER_INPUT_TOKEN) + FRAMING_TOKENS + size.imageTokens;
+    const expectedOutputTokens = Math.min(size.outputAllowance, EXPECTED_OUTPUT_TOKENS + EXPECTED_OUTPUT_TOKENS_PER_PARTICIPANT * size.participants);
+    const expectedCostUsd = requestCost(rate, inputTokens, expectedOutputTokens);
+    const worstCaseCostUsd = requestCost(rate, inputTokens, size.outputAllowance);
+    return {
+        inputTokens,
+        expectedOutputTokens,
+        expectedCostUsd,
+        worstCaseCostUsd,
+        admittedCostUsd: Math.min(worstCaseCostUsd, roundUp(expectedCostUsd * ADMISSION_MARGIN)),
+    };
+}
+/** The --max-cost that admits a refused analysis: its worst case, rounded up to a whole dollar. */
+export function admittingMaxCost(cost) {
+    return Math.max(1, Math.ceil(cost.worstCaseCostUsd));
+}
+/** Why admission refused an analysis, in plain words. */
+export function costRefusalText(cost) {
+    return `The expected cost is $${cost.expectedCostUsd.toFixed(2)} and the worst case is $${cost.worstCaseCostUsd.toFixed(2)}. With a ${Math.round((ADMISSION_MARGIN - 1) * 100)}% margin the expected cost is over the $${cost.maxCostUsd} cap, so no request was sent.`;
+}
+/** The admission's refused cost, when it refused the analysis for its cost. */
+export function refusedCost(admission) {
+    const { error, estimatedCostUsd, worstCaseCostUsd, maxCostUsd } = admission;
+    return error === "analysis_budget_exceeded" &&
+        estimatedCostUsd !== null &&
+        worstCaseCostUsd !== null &&
+        maxCostUsd !== null
+        ? { expectedCostUsd: estimatedCostUsd, worstCaseCostUsd, maxCostUsd }
+        : undefined;
+}

package/dist/analysis/automatic-completion.d.ts

@@ -35,10 +35,4 @@ export declare function completeAutomaticAnalysis<T extends {
     /** The route's reason not to analyze this run; see AutomaticAnalysisDeps.refusal. */
     refusal?: AutomaticAnalysisDeps["refusal"];
 }): Promise<T & AutomaticAnalysisResult>;
-/**
- * True when an analysis the study never declared was refused because its conservative estimate is
- * over the default cap. The author did not ask for it, so the refusal does not fail the run;
- * `humanish analyze --max-cost` can still run it.
- */
-export declare function defaultAnalysisOverBudget(result: AutomaticAnalysisResult): boolean;
 export declare function automaticAnalysisSucceeded(result: AutomaticAnalysisResult): boolean;

package/dist/analysis/automatic-completion.js

@@ -85,11 +85,11 @@ export async function completeAutomaticAnalysis(result, finished, config, input,
     }
 }
 /**
- * True when an analysis the study never declared was refused because its conservative estimate is
- * over the default cap. The author did not ask for it, so the refusal does not fail the run;
+ * True when an analysis the study never declared was refused because its expected cost, with the
+ * admission margin, is over the default cap. The author did not ask for it, so the refusal does not fail the run;
  * `humanish analyze --max-cost` can still run it.
  */
-export function defaultAnalysisOverBudget(result) {
+function defaultAnalysisOverBudget(result) {
     const value = result.automaticAnalysis;
     return (result.automaticAnalysisTrigger === "default" &&
         value?.state === "skipped" &&

package/dist/analysis/automatic-config.d.ts

@@ -34,8 +34,16 @@ export interface AutomaticAnalysisBudget {
     model: string;
     maxCostUsd: number | null;
     trigger: "default" | "explicit";
+    /** The participants the expected cost range is for. */
+    participants?: number;
+    /** The expected cost, from a run that keeps no evidence to one at the evidence limits. */
+    expectedCostUsd?: {
+        low: number;
+        high: number;
+    };
 }
-/** Metadata only: resolving the future live-run budget never reads keys or dispatches. */
-export declare function automaticAnalysisBudget(raw: unknown, route: StudyRoute): AutomaticAnalysisBudget | undefined;
+/** Metadata only: resolving the future live-run budget never reads keys or dispatches. With a
+ * participant count it also gives the expected cost range for that many participants. */
+export declare function automaticAnalysisBudget(raw: unknown, route: StudyRoute, participants?: number): AutomaticAnalysisBudget | undefined;
 export declare function formatAutomaticAnalysisBudget(budget: AutomaticAnalysisBudget): string;
 export {};

package/dist/analysis/automatic-config.js

@@ -1,5 +1,7 @@
 import { CODEX_ANALYSIS_MODEL, codexAnalysisIdentity } from "./codex-config.js";
-import { DEFAULT_ANALYSIS_MAX_OUTPUT_TOKENS, MAX_ANALYSIS_OUTPUT_TOKENS, isSupportedAnalysisModel, } from "./execute.js";
+import { DEFAULT_ANALYSIS_MAX_OUTPUT_TOKENS, MAX_ANALYSIS_OUTPUT_TOKENS, analysisCostRange, isSupportedAnalysisModel, } from "./execute.js";
+import { ADMISSION_MARGIN } from "./admission.js";
+import { plural } from "../run/text.js";
 import { containsSensitive } from "../evidence/redaction.js";
 export const DEFAULT_ANALYSIS_TIMEOUT_MS = 600_000;
 const MAX_ANALYSIS_TIMEOUT_MS = 600_000;
@@ -111,25 +113,38 @@ export function resolveAutomaticAnalysis(raw) {
         ...(value.maxOutputTokens === undefined ? { preferLargerOutput: true } : {}),
     };
 }
-/** Metadata only: resolving the future live-run budget never reads keys or dispatches. */
-export function automaticAnalysisBudget(raw, route) {
+/** Metadata only: resolving the future live-run budget never reads keys or dispatches. With a
+ * participant count it also gives the expected cost range for that many participants. */
+export function automaticAnalysisBudget(raw, route, participants) {
     // The synthetic preview has no participants, so nothing is analyzed after it.
     if (route === "preview")
         return undefined;
     const resolved = resolveAutomaticAnalysis(raw);
-    return resolved.ok && resolved.config
-        ? {
-            ...(resolved.config.provider === "codex"
-                ? { provider: "codex", billing: "account-unknown" }
-                : {}),
-            model: resolved.config.model,
-            maxCostUsd: resolved.config.maxCostUsd,
-            trigger: raw === undefined ? "default" : "explicit",
-        }
-        : undefined;
+    if (!resolved.ok || !resolved.config)
+        return undefined;
+    const { config } = resolved;
+    const range = participants === undefined || config.provider === "codex"
+        ? undefined
+        : analysisCostRange(resolved.preferLargerOutput
+            ? { ...config, maxOutputTokens: MAX_ANALYSIS_OUTPUT_TOKENS }
+            : config, participants);
+    return {
+        ...(config.provider === "codex"
+            ? { provider: "codex", billing: "account-unknown" }
+            : {}),
+        model: config.model,
+        maxCostUsd: config.maxCostUsd,
+        trigger: raw === undefined ? "default" : "explicit",
+        ...(range === undefined || participants === undefined
+            ? {}
+            : { participants, expectedCostUsd: range }),
+    };
 }
 export function formatAutomaticAnalysisBudget(budget) {
     if (budget.provider === "codex")
         return `After live runs: Codex account analysis · ${budget.model} · separate restricted analyst with remote inference. Account limits apply; dollar cost and output-token ceiling are unknown. Set review.analysis: false to disable.`;
-    return `After live runs: ${budget.trigger} analysis · ${budget.model} · refused before it starts if its estimate is over $${budget.maxCostUsd}; this is not a billing cap. Set review.analysis: false to disable.`;
+    const range = budget.expectedCostUsd === undefined || budget.participants === undefined
+        ? ""
+        : ` · expected $${budget.expectedCostUsd.low.toFixed(2)} to $${budget.expectedCostUsd.high.toFixed(2)} for ${plural(budget.participants, "participant")}, depending on how much evidence the run keeps`;
+    return `After live runs: ${budget.trigger} analysis · ${budget.model}${range} · refused before it starts if the expected cost plus a ${Math.round((ADMISSION_MARGIN - 1) * 100)}% margin is over $${budget.maxCostUsd}; this is not a billing cap. Set review.analysis: false to disable.`;
 }

package/dist/analysis/automatic.js

@@ -5,6 +5,7 @@ import { refreshObserver, analyzeRun, readCompletedAnalysisSource, resolveAnalys
 import { preferLargerAnalysisOutput, ANALYSIS_PROMPT_VERSION } from "./execute.js";
 import { captureEvidence } from "./evidence.js";
 import { hashAnalysisValue } from "./validation.js";
+import { refusedCost } from "./admission.js";
 import { claimAutomaticAnalysis, readAutomaticAnalysisPrepared, requestAutomaticAnalysisCancellationPrepared, } from "./job.js";
 import { ANALYSIS_ID_PATTERN } from "./types.js";
 import { readAnalysisVersion } from "./store.js";
@@ -105,6 +106,11 @@ async function readAutomaticSource(cwd, prepared, configInput, deps, hasKey) {
         return skipped("AUTOMATIC_ANALYSIS_SOURCE_UNAVAILABLE");
     }
 }
+/** The cost of an analysis admission refused for its cost, kept so review and Observer can say it. */
+function withRefusedCost(result) {
+    const cost = result?.admission && refusedCost(result.admission);
+    return cost ? { admission: cost } : {};
+}
 /**
  * Bind the job's terminal metadata to the exact safely published execution. Reads never promote a
  * completed-looking sidecar without rechecking these bindings. Null when storage failed.
@@ -130,6 +136,7 @@ async function persistOutcome(job, prepared, outcome) {
                     receiptSha256: hashAnalysisValue(receipt),
                 }),
             ...(entry?.analysis ? { analysisSha256: hashAnalysisValue(entry.analysis) } : {}),
+            ...withRefusedCost(outcome.result),
         });
         const persisted = await readAutomaticAnalysisPrepared(prepared);
         return persisted?.state === "unknown"

package/dist/analysis/execute.d.ts

@@ -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";
@@ -128,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.
  */
@@ -143,6 +144,8 @@ export function estimateAnalysisAdmission(input, config) {
         inputTokenAllowance: 0,
         outputTokenAllowance: 0,
         estimatedCostUsd: null,
+        worstCaseCostUsd: null,
+        maxCostUsd: null,
         ratesAsOf: null,
     });
     if ((config.provider === "codex"
@@ -174,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];
@@ -184,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. */
@@ -464,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)) {