humanish 0.107.0 → 0.109.0

package/dist/run/dry-run-inputs.d.ts

@@ -1,4 +1,4 @@
-import { type ResolvedPersona } from "../lab/persona.js";
+import { type ResolvedPersona } from "../study/persona.js";
 import type { PreparedSelectedOutputDirectory } from "./contained-output.js";
 import type { RunBundle } from "./bundle.js";
 export declare function loadDryRunInputs(projectRoot: PreparedSelectedOutputDirectory, humanishSource: "present" | "missing"): Promise<{

package/dist/run/dry-run-inputs.js

@@ -1,5 +1,5 @@
 import { parse as parseYaml } from "yaml";
-import { parseResolvedPersona } from "../lab/persona.js";
+import { parseResolvedPersona } from "../study/persona.js";
 import { digestText } from "../evidence/redaction.js";
 import { readImplicitProjectFile } from "./project.js";
 import { escapeRegExp } from "./text.js";
@@ -12,7 +12,7 @@ const builtinPersona = {
 const builtinScenario = {
     id: "builtin-first-run-smoke",
     title: "Built-in First-Run Smoke",
-    goal: "Create a public-safe dry-run contract bundle from built-in defaults.",
+    goal: "Write a public-safe dry-run bundle from built-in defaults.",
     source: "builtin:first-run-smoke",
     sourceDigest: "builtin",
 };

package/dist/run/dry-run.js

@@ -9,7 +9,7 @@ import {} from "./streams.js";
 import { participantEvent, participantIdsOf, participantRecord, participantStream, } from "./participant-records.js";
 import { implicitProjectDirectoryExists, readPackageName, validateCwd } from "./project.js";
 import { loadDryRunInputs } from "./dry-run-inputs.js";
-import { judgeExecution, judgePreview, OUTCOME_POLICIES, resultOk } from "./judge.js";
+import { judgeExecution, judgePreview, OUTCOME_POLICIES, resultOk, verdictText, } from "./judge.js";
 /**
  * The preview route's run. The run scope closes the run it started on every exit, including
  * the fail-closed ones. It renders an Observer only when `options.observer` asks for one.
@@ -33,14 +33,14 @@ async function runDryRunInScope(options, scope) {
     const warnings = [];
     if (cwdError)
         return refused(requestedCwd, warnings, cwdError);
-    const participants = normalizeParticipantCount(options.simCount);
+    const participants = normalizeParticipantCount(options.participantCount);
     if (participants === null) {
         return refused(requestedCwd, warnings, {
-            code: "HUMANISH_INVALID_SIM_COUNT",
+            code: "HUMANISH_INVALID_PARTICIPANT_COUNT",
             message: "--count must be a positive integer.",
         });
     }
-    // Bind the physical project, as the lab routes do: a symlinked cwd retargeted mid-run cannot
+    // Bind the physical project, as the routes do: a symlinked cwd retargeted mid-run cannot
     // redirect source reads or run storage into another project.
     const physicalCwd = await realpath(requestedCwd);
     const projectRoot = await prepareSelectedOutputDirectory(path.dirname(physicalCwd), physicalCwd);
@@ -48,7 +48,7 @@ async function runDryRunInScope(options, scope) {
     if (!options.dryRun) {
         return refused(requestedCwd, warnings, {
             code: "HUMANISH_LIVE_RUN_UNIMPLEMENTED",
-            message: "Only run --dry-run is implemented here. Run a lab for a live study.",
+            message: "humanish run needs a study. List studies with humanish study list, or run humanish run --dry-run for a sample bundle.",
         });
     }
     const createdAt = new Date().toISOString();
@@ -64,7 +64,7 @@ async function runDryRunInScope(options, scope) {
         runId: options.runId,
         mintRunId: () => `dryrun-${createdAt.replace(/[:.]/g, "-")}-${randomUUID().slice(0, 8)}`,
         mode: options.dryRun ? "dry-run" : "live",
-        lab: options.lab,
+        study: options.study,
         renderReview: renderReviewMarkdown,
         // The run starts at the time its id and source were stamped with.
         now: () => Date.parse(createdAt),
@@ -94,7 +94,7 @@ async function runDryRunInScope(options, scope) {
             {
                 at: createdAt,
                 event: "run.created",
-                message: `Synthetic dry-run contract bundle created with ${participants} simulated participant${participants === 1 ? "" : "s"}.`,
+                message: `Synthetic dry-run bundle created with ${participants} simulated participant${participants === 1 ? "" : "s"}.`,
             },
             {
                 at: createdAt,
@@ -117,7 +117,7 @@ async function runDryRunInScope(options, scope) {
         events: observerFixtures.events,
         redaction: {
             status: "passed",
-            notes: "Dry-run bundle contains synthetic contract proof only.",
+            notes: "Dry-run bundle: synthetic data only, nothing from a product.",
         },
         artifacts: bundleArtifacts(),
         review: createReviewSummary(judgment.verdict),
@@ -150,14 +150,14 @@ async function runDryRunInScope(options, scope) {
     };
 }
 /**
- * The preview's review, with the verdict judgePreview gave it. It claims artifact plumbing only,
- * never product behavior.
+ * The preview's review, with the verdict judgePreview gave it. It claims only that the run's
+ * files were written, never product behavior.
  */
 function createReviewSummary(verdict) {
     return {
         schema: REVIEW_SCHEMA,
         verdict,
-        summary: "Synthetic dry-run bundle was generated. This proves humanish artifact plumbing, not product behavior.",
+        summary: "Dry run: humanish wrote a synthetic run bundle. No product behavior was tested.",
         gaps: [
             "No browser was launched.",
             "No product state was verified.",
@@ -173,7 +173,7 @@ Run: ${bundle.runId}
 
 Mode: ${bundle.mode}
 
-Verdict: ${bundle.review.verdict}
+Verdict: ${verdictText(bundle.review.verdict, bundle.mode)}
 
 ${bundle.review.summary}
 
@@ -210,7 +210,7 @@ const SYNTHETIC_STREAM_TEMPLATES = [
         kind: "ui",
         mode: "browser-sim",
         label: "UI journey",
-        currentStep: "Route and viewport contract captured",
+        currentStep: "Route and viewport recorded",
         summary: "Simulated browser participant reserved for VNC playback, screenshots, route state, and interaction trace.",
         tail: "open target app\nresolve first-run route\ncapture viewport state\nrecord interaction trace",
         viewport: { width: 1440, height: 960, deviceScaleFactor: 1 },
@@ -219,19 +219,19 @@ const SYNTHETIC_STREAM_TEMPLATES = [
         kind: "terminal",
         mode: "cli-sim",
         label: "CLI actor",
-        currentStep: "Command transcript contract captured",
+        currentStep: "Command transcript recorded",
         summary: "Simulated CLI participant reserved for command-by-command persona runs with stdout/stderr and artifact links.",
         // Every command in a shipped sample tail must be one the CLI actually accepts: participants
         // read and run them. tests/surface/shipped-command-strings.test.ts checks this against the
         // command table.
-        tail: "$ humanish doctor\nok target cwd\nok humanish source\n$ humanish run first-run\ncontract proof emitted",
+        tail: "$ humanish doctor\nok target cwd\nok humanish source\n$ humanish run first-run\nhumanish run dry-run",
         viewport: undefined,
     },
     {
         kind: "tui",
         mode: "tui-sim",
         label: "TUI actor",
-        currentStep: "Terminal UI frame contract captured",
+        currentStep: "Terminal UI frame recorded",
         summary: "Simulated TUI participant reserved for PTY bytes, ANSI rendering, focus replay, and optional assisted attach.",
         tail: "\u001b[2mhumanish TUI frame\u001b[0m\n> persona: skeptical-power-user\n> scenario: onboarding-regression\nstatus: awaiting live PTY transport",
         viewport: undefined,
@@ -240,9 +240,9 @@ const SYNTHETIC_STREAM_TEMPLATES = [
         kind: "codex-ui",
         mode: "codex-app-sim",
         label: "Codex UI",
-        currentStep: "App-server embed contract captured",
+        currentStep: "App-server embed recorded",
         summary: "Simulated Codex UI participant reserved for app-server sessions that can be watched beside terminal evidence.",
-        tail: "codex-app-server session contract\nstate: not_connected\nembed: pending provider URL\nreceipts: planned",
+        tail: "codex-app-server session (dry run)\nstate: not_connected\nembed: pending provider URL\nreceipts: planned",
         viewport: { width: 1280, height: 900, deviceScaleFactor: 1 },
     },
 ];
@@ -255,7 +255,7 @@ function buildSyntheticObserverFixtures(args) {
             at: args.createdAt,
             level: "info",
             type: "observer.contract.created",
-            message: "Created public-safe observer stream contract.",
+            message: "Created the public-safe Observer streams.",
         },
     ];
     for (let index = 0; index < args.count; index += 1) {
@@ -324,7 +324,7 @@ function buildSyntheticObserverFixtures(args) {
             at: args.createdAt,
             level: "info",
             type: "sim.contract.ready",
-            message: `${template.label} stream contract ready.`,
+            message: `${template.label} stream ready.`,
         }), participantEvent(ids, {
             id: `event-${String(index + 1).padStart(3, "0")}-b`,
             at: args.createdAt,

package/dist/run/judge.d.ts

@@ -6,7 +6,7 @@ export interface BlockerFacts {
     completionReason: ActorCompletionReason;
     /** A harness-owned stop condition ended the session: a matched stopWhen or a completed dwell window. */
     stopConditionMatched: boolean;
-    /** What the participant declared in a field, when its provider has one (#570). */
+    /** What the participant declared in a field, when its provider has one. */
     declaredOutcome?: ParticipantDeclaredOutcome;
     /** The route's reading of the closing report: it describes a blocker or asks for instructions. */
     closingReportReadsBlocked: boolean;
@@ -23,7 +23,7 @@ export interface SessionEnding extends BlockerFacts {
 export declare function hollowCompletion(ending: SessionEnding): boolean;
 /**
  * The participant said it reached the goal but reported a blocker. A declared outcome is its own
- * word and wins (#570). Without one, the closing report is read, unless a stop condition ended the
+ * word and wins. Without one, the closing report is read, unless a stop condition ended the
  * session: a matched stopWhen is structured completion evidence and overrides the text.
  */
 export declare function selfReportedBlocker(ending: BlockerFacts): boolean;
@@ -60,12 +60,18 @@ export declare function participantHarnessFailed(participant: ParticipantFacts):
  * goal_satisfied claim with zero engagement is a session that ran out before anything happened;
  * one whose final message describes a blocker is a participant who could not proceed and said so.
  * Both keep their trace status (the claim is evidence); neither is a participant who reached the
- * goal. One rule for the single participant and the fan-out roll-up (#476).
+ * goal. One rule for the single participant and the fan-out roll-up.
  */
 export declare function participantStatus(status: ActorStatus, judgments: {
     noEngagement: boolean;
     selfReportedBlocker: boolean;
 } | undefined): ActorStatus;
+/**
+ * A verdict as review.md prints it. The schema keeps `contract_proof_only`, which a dry run always
+ * gets and a live run gets while it is in progress or when no participant result came back, so
+ * the reader sees "dry run" or "no verdict" by the run's mode.
+ */
+export declare function verdictText(verdict: Verdict, mode: "dry-run" | "live"): string;
 /** The review verdict for one participant's status. */
 export declare function verdictForStatus(status: ActorStatus): Verdict;
 declare const judged: unique symbol;
@@ -77,7 +83,7 @@ export interface Judgment {
     readonly verdict: Verdict;
     /**
      * The run met its route's pass rule: every expected participant passed and, on shared-world,
-     * the seats showed the concurrency verify requires. A dry run passes as a contract.
+     * the participants showed the concurrency verify requires. A dry run passes as a contract.
      */
     readonly passed: boolean;
     /** A type-only mark that judgmentOf made this judgment; it does not exist at runtime. */
@@ -126,13 +132,13 @@ export interface OutcomePolicy {
 export type JudgedRoute = "computer-use" | "shared-world" | "terminal" | "scripted" | "preview";
 /** Each route's outcome policy, in one place. */
 export declare const OUTCOME_POLICIES: Readonly<Record<JudgedRoute, OutcomePolicy>>;
-/** What a shared-world run observed about its one world, beside how each seat ended. */
+/** What a shared-world run observed about its one world, beside how each participant ended. */
 export interface SharedWorldFacts {
-    /** Two or more seats were live at the same time. */
+    /** Two or more participants were live at the same time. */
     overlap: boolean;
     /** Provisioned plane only: the shared state changed at or after the first overlap started. */
     stateChangedUnderOverlap?: boolean;
-    /** External-public plane only: every seat reached one lobby. */
+    /** External-public plane only: every participant reached one lobby. */
     lobbyConvergence?: boolean;
 }
 /** A shared-world run's judgment, with the world facts its review and result also report. */
@@ -162,15 +168,15 @@ export declare function judgeParticipants(args: {
     participants: ParticipantFacts[];
 }): Judgment;
 /**
- * Why a shared-world run whose seats all passed still fails, or undefined when its world facts
- * meet what verify's shared-world check requires of a pass: two seats live at the same time and,
- * on the provisioned plane, a shared-state change at or after the first overlap started.
+ * Why a shared-world run whose participants all passed still fails, or undefined when its world
+ * facts meet what verify's shared-world check requires of a pass: two participants live at the same
+ * time and, on the provisioned plane, a shared-state change at or after the first overlap started.
  */
 export declare function sharedWorldShortfall(world: SharedWorldFacts): string | undefined;
 /**
- * A shared-world run: it passes only when every expected seat passed and the world facts have no
- * shortfall, and otherwise fails (this route has no timed_out verdict). A dry run and a run still
- * in progress are contracts. Lobby convergence is recorded but not read.
+ * A shared-world run: it passes only when every expected participant passed and the world facts
+ * have no shortfall, and otherwise fails (this route has no timed_out verdict). A dry run and a run
+ * still in progress are contracts. Lobby convergence is recorded but not read.
  */
 export declare function judgeSharedWorld(args: {
     dryRun: boolean;

package/dist/run/judge.js

@@ -24,7 +24,7 @@ export function hollowCompletion(ending) {
 }
 /**
  * The participant said it reached the goal but reported a blocker. A declared outcome is its own
- * word and wins (#570). Without one, the closing report is read, unless a stop condition ended the
+ * word and wins. Without one, the closing report is read, unless a stop condition ended the
  * session: a matched stopWhen is structured completion evidence and overrides the text.
  */
 export function selfReportedBlocker(ending) {
@@ -65,7 +65,7 @@ export function participantHarnessFailed(participant) {
  * goal_satisfied claim with zero engagement is a session that ran out before anything happened;
  * one whose final message describes a blocker is a participant who could not proceed and said so.
  * Both keep their trace status (the claim is evidence); neither is a participant who reached the
- * goal. One rule for the single participant and the fan-out roll-up (#476).
+ * goal. One rule for the single participant and the fan-out roll-up.
  */
 export function participantStatus(status, judgments) {
     if (status !== "passed" || judgments === undefined)
@@ -76,6 +76,16 @@ export function participantStatus(status, judgments) {
         return "blocked";
     return status;
 }
+/**
+ * A verdict as review.md prints it. The schema keeps `contract_proof_only`, which a dry run always
+ * gets and a live run gets while it is in progress or when no participant result came back, so
+ * the reader sees "dry run" or "no verdict" by the run's mode.
+ */
+export function verdictText(verdict, mode) {
+    if (verdict !== "contract_proof_only")
+        return verdict;
+    return mode === "dry-run" ? "dry run" : "no verdict";
+}
 /** The review verdict for one participant's status. */
 export function verdictForStatus(status) {
     switch (status) {
@@ -148,9 +158,9 @@ export function judgeParticipants(args) {
     return judgmentOf(verdict, args.dryRun);
 }
 /**
- * Why a shared-world run whose seats all passed still fails, or undefined when its world facts
- * meet what verify's shared-world check requires of a pass: two seats live at the same time and,
- * on the provisioned plane, a shared-state change at or after the first overlap started.
+ * Why a shared-world run whose participants all passed still fails, or undefined when its world
+ * facts meet what verify's shared-world check requires of a pass: two participants live at the same
+ * time and, on the provisioned plane, a shared-state change at or after the first overlap started.
  */
 export function sharedWorldShortfall(world) {
     if (!world.overlap) {
@@ -162,9 +172,9 @@ export function sharedWorldShortfall(world) {
     return undefined;
 }
 /**
- * A shared-world run: it passes only when every expected seat passed and the world facts have no
- * shortfall, and otherwise fails (this route has no timed_out verdict). A dry run and a run still
- * in progress are contracts. Lobby convergence is recorded but not read.
+ * A shared-world run: it passes only when every expected participant passed and the world facts
+ * have no shortfall, and otherwise fails (this route has no timed_out verdict). A dry run and a run
+ * still in progress are contracts. Lobby convergence is recorded but not read.
  */
 export function judgeSharedWorld(args) {
     const passed = args.participants.length === args.expected &&

package/dist/run/outcomes.d.ts

@@ -1,6 +1,6 @@
 import { type ActorStatus } from "../actors/contract.js";
 import { type CuaGoalSource } from "../actors/goal-source.js";
-import type { TaskFunnel } from "../lab/tasks.js";
+import type { TaskFunnel } from "../study/tasks.js";
 import type { ParticipantOutcomes, ReviewSummary, RunTaskFunnel } from "./bundle.js";
 /** Tally participant outcomes from actor statuses. Statuses this does not recognise are counted in
  *  `total` but nowhere else, so the parts can never exceed the whole. */

package/dist/run/participant.d.ts

@@ -1,5 +1,5 @@
 import type { ActorPersonaRef } from "../actors/contract.js";
-import type { Participant } from "../lab/plan-participants.js";
+import type { Participant } from "../study/plan-participants.js";
 import type { RunParticipantAssignment } from "./streams.js";
 /**
  * A planned participant resolved for one run: the plan's record unchanged, plus what the route

package/dist/run/paths.d.ts

@@ -49,7 +49,7 @@ export declare function createRunArtifactPaths(cwdInput: string, runId: string):
 export declare function validatePreparedRunArtifactPaths(prepared: PreparedRunArtifactPaths): Promise<PreparedRunArtifactPaths>;
 /**
  * The physical project directory for a caller's cwd, bound before a run is resolved so a symlinked
- * cwd retargeted later cannot move reads or writes to another project (#1012). A cwd that does not
+ * cwd retargeted later cannot move reads or writes to another project. A cwd that does not
  * resolve is returned as given, so the caller still reports it missing.
  */
 export declare function resolvePhysicalCwd(cwdInput: string): Promise<string>;

package/dist/run/paths.js

@@ -107,7 +107,7 @@ export async function validatePreparedRunArtifactPaths(prepared) {
 }
 /**
  * The physical project directory for a caller's cwd, bound before a run is resolved so a symlinked
- * cwd retargeted later cannot move reads or writes to another project (#1012). A cwd that does not
+ * cwd retargeted later cannot move reads or writes to another project. A cwd that does not
  * resolve is returned as given, so the caller still reports it missing.
  */
 export async function resolvePhysicalCwd(cwdInput) {

package/dist/run/preflight-receipts.js

@@ -1,4 +1,4 @@
-// Sandbox receipts for `humanish lab preflight`. A probe has no run directory, so it journals its
+// Sandbox receipts for `humanish study check`. A probe has no run directory, so it journals its
 // sandbox under .humanish/preflight/<probe-id>/ before any work runs in it. A confirmed kill
 // removes the journal. A journal that stays means the probe's sandbox may still be running, and
 // `humanish reclaim --preflight` kills it by the recorded id once it is safe to.

package/dist/run/pricing.d.ts

@@ -25,7 +25,7 @@ export interface ModelRate {
         inputMultiplier: number;
         outputMultiplier: number;
     };
-    /** "YYYY-MM-DD" the entry was last checked against `source`. */
+    /** The `YYYY-MM-DD` date the entry was last checked against `source`. */
     asOf: string;
     /** Public pricing page the number came from (a comment/URL, never a secret). */
     source: string;
@@ -83,7 +83,7 @@ export interface ActorEstimatedCost {
         /** Of `inputTokens`, how many were billed at the reduced cached rate. Present only when the
          *  provider reported cache hits and the rate sheet models a cached rate. */
         cachedInputTokens?: number;
-        /** Of `inputTokens`, how many were billed at the cache-WRITE rate (OpenAI 5.6+). */
+        /** Of `inputTokens`, how many were billed at the cache-write rate (OpenAI 5.6+). */
         cacheWriteInputTokens?: number;
         /** How many requests crossed the long-context threshold and were re-tiered. Present only
          *  when per-request `turns` records made exact tiering possible. */
@@ -104,6 +104,11 @@ export interface DesktopCostEstimate {
     usdPerSecond?: number;
 }
 export declare const MODEL_RATES: Record<string, ModelRate>;
+/**
+ * The refusal for a spend cap on a model this table cannot price. It names the priced models,
+ * since an npm install cannot edit this file.
+ */
+export declare function unpricedCapMessage(model: string): string;
 export declare const DESKTOP_RATE: DesktopRate;
 export declare function isDesktopResources(value: unknown): value is DesktopResources;
 /** Price one observed allocation. Missing quantities/rates stay unknown, never a stock guess. */
@@ -113,8 +118,8 @@ export declare function estimateAllocatedDesktopCost(minutes: number | undefined
 export declare function round6(n: number): number;
 /**
  * Estimate one actor trace's model-token cost from its trace tokenUsage + model id. Deterministic;
- * the rate table is injectable (tests pass a fake sheet). Returns a DECLARED-ABSENT estimate
- * (estimatedCostUsd: null + a reason) for a missing rate or missing usage — never a guessed cost.
+ * the rate table is injectable (tests pass a fake sheet). Returns a declared-absent estimate
+ * (estimatedCostUsd: null + a reason) for a missing rate or missing usage, never a guessed cost.
  */
 export declare function estimateActorCostForExecution(usage: ActorTokenUsage | undefined, modelId: string | undefined, profile?: {
     billing?: unknown;
@@ -128,7 +133,7 @@ export declare function estimateAggregatedTurnCost(tokenUsage: ActorTokenUsage |
 export declare function estimateActorCost(tokenUsage: ActorTokenUsage | undefined, modelId: string | undefined, rates?: Record<string, ModelRate>): ActorEstimatedCost;
 /**
  * Estimate the E2B desktop-minute cost from a host-side create->teardown span (minutes). The rate
- * is injectable. Returns a DECLARED-ABSENT estimate (null + "no_duration") when no duration was
- * measured (no sandbox / unmeasurable span) — never a guessed 0.
+ * is injectable. Returns a declared-absent estimate (null + "no_duration") when no duration was
+ * measured (no sandbox / unmeasurable span), never a guessed 0.
  */
 export declare function estimateDesktopCost(minutes: number | undefined, rate?: DesktopRate): DesktopCostEstimate;

package/dist/run/pricing.js

@@ -6,10 +6,10 @@
 // This module is pure (node builtins only, no deps) and deterministic: the estimator functions take
 // an optional injected rate table/rate so tests drive assertions with a fake sheet and never depend
 // on the live numbers below. An unknown model/desktop rate yields a declared-absent estimate
-// (estimatedCostUsd: null + a reason) and never a guessed or silent-zero cost (invariant 5). A bare
+// (estimatedCostUsd: null + a reason) and never a guessed or silent-zero cost. A bare
 // `costUsd` elsewhere in the contract means a provider actually billed that amount; the
 // token-derived estimate here always lives under `estimatedCostUsd` so a reader can never confuse
-// an estimate for an authoritative charge (invariant 6).
+// an estimate for an authoritative charge.
 export const PRICING_SCHEMA = "humanish.pricing.v1";
 export const ACTOR_ESTIMATED_COST_SCHEMA = "humanish.actor-estimated-cost.v1";
 // The gpt-5.6 long-context tier: >272K input tokens re-prices the full request at 2x
@@ -44,14 +44,14 @@ const GPT6_ASTRA_AS_OF = "2026-09-03";
 // case-insensitive on a trimmed id). An id missing here is declared absent, never guessed.
 export const MODEL_RATES = {
     // OpenAI computer-use-preview (the classic CUA model). ~$3 / 1M input, ~$12 / 1M output.
-    // source: openai.com/api/pricing (verify — providers change without notice).
+    // source: openai.com/api/pricing (verify: providers change without notice).
     "computer-use-preview": {
         inputUsdPerToken: 3e-6,
         outputUsdPerToken: 12e-6,
         asOf: "2026-08-01",
         source: "openai.com/api/pricing (computer-use-preview)",
     },
-    // gpt-5.5: the PREVIOUS-generation CUA default, kept so pinned labs and old bundles still
+    // gpt-5.5: the previous-generation CUA default, kept so pinned labs and old bundles still
     // price. Pre-5.6 models bill no cache-write fee (prompt-caching guide) and no long-context
     // tier was published for it.
     "gpt-5.5": {
@@ -59,7 +59,7 @@ export const MODEL_RATES = {
         outputUsdPerToken: 30e-6,
         cachedInputUsdPerToken: 0.5e-6,
         asOf: "2026-08-05",
-        source: "openrouter.ai/openai/gpt-5.5 (gpt-5.5 no longer on openai.com/api/pricing; see #334)",
+        source: "openrouter.ai/openai/gpt-5.5 (gpt-5.5 is no longer listed on openai.com/api/pricing)",
     },
     // The gpt-5.6 family (live sheet 2026-08-18, standard tier, short-context base rates;
     // the longContext block prices the >272K re-tier when per-request turns are recorded).
@@ -67,7 +67,7 @@ export const MODEL_RATES = {
     // cyber = the Daybreak frontier tier.
     "gpt-5.6-sol": rateWithLongContextTier(4, 0.4, 5, 20, GPT56_SOL_PROMO_AS_OF),
     // "gpt-5.6" is OpenAI's own alias for gpt-5.6-sol (models index); priced identically so a
-    // lab configured with the alias never reads as unpriced.
+    // study configured with the alias never reads as unpriced.
     "gpt-5.6": rateWithLongContextTier(4, 0.4, 5, 20, GPT56_SOL_PROMO_AS_OF),
     "gpt-5.6-terra": rateWithLongContextTier(2, 0.2, 2.5, 12),
     "gpt-5.6-luna": rateWithLongContextTier(0.2, 0.02, 0.25, 1.2),
@@ -79,7 +79,7 @@ export const MODEL_RATES = {
     "daybreak-red-latest": rateWithLongContextTier(12.5, 1.25, 15.625, 75),
     // gpt-6-astra (shipped 2026-09-03; API access announced as rolling out). Same two mechanics
     // as the 5.6 family on the sheet: writes at 1.25x, >272K re-tiers at 2x input-side / 1.5x
-    // output ($20 / $2 / $25 / $75 long-context columns). These rates cover explicit lab
+    // output ($20 / $2 / $25 / $75 long-context columns). These rates cover explicit study
     // model choices and the study-analysis default; the computer-use default is separate.
     "gpt-6-astra": rateWithLongContextTier(10, 1, 12.5, 50, GPT6_ASTRA_AS_OF, GPT6_ASTRA_SOURCE),
 };
@@ -96,6 +96,13 @@ const DESKTOP_RESOURCE_RATE = {
 // 2026-09-05 had 8 vCPU / 8 GiB. This is the largest CPU/RAM combination on that public sheet, not
 // a provider billing ceiling or a claim about custom/enterprise templates. Runtime CUA estimates
 // use observed allocation resources through estimateAllocatedDesktopCost instead of this fallback.
+/**
+ * The refusal for a spend cap on a model this table cannot price. It names the priced models,
+ * since an npm install cannot edit this file.
+ */
+export function unpricedCapMessage(model) {
+    return `execution.caps sets a spend cap (maxUsd or maxTotalUsd), but humanish has no rate for model "${model}", so it cannot enforce the cap and refuses to start. Priced models: ${Object.keys(MODEL_RATES).sort().join(", ")}. Use one of them, or remove maxUsd and maxTotalUsd to run without a cap.`;
+}
 export const DESKTOP_RATE = {
     usdPerMinute: 0.00888,
     asOf: "2026-09-05",
@@ -158,8 +165,8 @@ export function round6(n) {
 }
 /**
  * Estimate one actor trace's model-token cost from its trace tokenUsage + model id. Deterministic;
- * the rate table is injectable (tests pass a fake sheet). Returns a DECLARED-ABSENT estimate
- * (estimatedCostUsd: null + a reason) for a missing rate or missing usage — never a guessed cost.
+ * the rate table is injectable (tests pass a fake sheet). Returns a declared-absent estimate
+ * (estimatedCostUsd: null + a reason) for a missing rate or missing usage, never a guessed cost.
  */
 export function estimateActorCostForExecution(usage, modelId, profile) {
     return profile?.billing === "account-unknown"
@@ -207,7 +214,7 @@ export function estimateActorCost(tokenUsage, modelId, rates = MODEL_RATES) {
     const outTok = tokenUsage.output ?? 0;
     // Long-context tiering needs to know each request's input size (the provider re-prices whole
     // requests past the threshold), so it engages only when per-turn usage records exist and their
-    // input sums to the reported total — a partial turn ledger must not silently price the missing
+    // input sums to the reported total, because a partial turn ledger must not silently price the missing
     // remainder at the wrong tier. Otherwise totals price on the base (short-context) rate, which is
     // the under-estimate direction and never trips a cap early.
     const turns = tokenUsage.turns ?? [];
@@ -232,12 +239,12 @@ export function estimateActorCost(tokenUsage, modelId, rates = MODEL_RATES) {
     // and on a session that threads provider state it is the majority of input, and pricing it at the
     // full rate overstates real spend by up to ~10x. Cache writes bill at their own rate (1.25x on
     // OpenAI 5.6+) as the total rate for those tokens; a sheet without a write rate prices writes as
-    // plain input (pre-5.6: writes are free-of-extra-fee, i.e. plain input). Every piece is honestly
-    // absent: no reported split means no discount and no surcharge assumed.
+    // plain input (pre-5.6: writes are free-of-extra-fee, i.e. plain input). An unreported piece
+    // stays absent: no reported split means no discount and no surcharge assumed.
     const priceRequest = (usage, tierable) => {
         const reqIn = usage.input ?? 0;
         const reqOut = usage.output ?? 0;
-        // Tiering applies only to a real per-REQUEST record: session totals crossing the threshold
+        // Tiering applies only to a real per-request record: session totals crossing the threshold
         // say nothing about any single request, so totals always price on the base tier.
         const long = tierable && rate.longContext !== undefined && reqIn > rate.longContext.thresholdInputTokens;
         const inMul = long ? rate.longContext.inputMultiplier : 1;
@@ -293,8 +300,8 @@ export function estimateActorCost(tokenUsage, modelId, rates = MODEL_RATES) {
 }
 /**
  * Estimate the E2B desktop-minute cost from a host-side create->teardown span (minutes). The rate
- * is injectable. Returns a DECLARED-ABSENT estimate (null + "no_duration") when no duration was
- * measured (no sandbox / unmeasurable span) — never a guessed 0.
+ * is injectable. Returns a declared-absent estimate (null + "no_duration") when no duration was
+ * measured (no sandbox / unmeasurable span), never a guessed 0.
  */
 export function estimateDesktopCost(minutes, rate = DESKTOP_RATE) {
     if (minutes === undefined || !Number.isFinite(minutes) || minutes < 0) {