humanish 0.106.1 → 0.108.0

package/dist/run/judge.js

@@ -6,7 +6,7 @@
 //      participantPassed, participantHarnessFailed);
 //   2. the judgment shapes (Judgment and judgmentOf, SharedWorldJudgment, ExecutionOutcome,
 //      OutcomePolicy);
-//   3. one judge per route: computer-use calls judgeOneParticipant (one lane, no rerun) or
+//   3. one judge per route: computer-use calls judgeOneParticipant (one participant, no rerun) or
 //      judgeParticipants, shared-world calls judgeSharedWorld, terminal calls judgeTerminal,
 //      scripted calls judgeScripted and preview calls judgePreview;
 //   4. foldScorerFailures, which every route with a scorer applies before the run finishes;
@@ -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 lane 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) {
@@ -98,6 +108,17 @@ export function verdictForStatus(status) {
 export function judgmentOf(verdict, dryRun) {
     return { verdict, passed: dryRun || verdict === "pass" };
 }
+/**
+ * The execution failure for one sandbox whose release is unconfirmed. `warning` is the route's
+ * release warning, already scrubbed. `recovery` says how to release it by hand; without one,
+ * reclaim kills by the id the run recorded at create time.
+ */
+export function sandboxCleanupFailure(owner, warning, runId, recovery) {
+    return {
+        kind: "sandbox-cleanup",
+        message: `${owner}: ${warning ?? "Sandbox release is unconfirmed."} ${recovery ?? `Reclaim it by recorded id with \`humanish reclaim --run ${runId}\`.`}`,
+    };
+}
 /** Each route's outcome policy, in one place. */
 export const OUTCOME_POLICIES = {
     "computer-use": { participants: "gate", sandboxCleanup: "warns", evidence: "fails" },
@@ -111,7 +132,7 @@ export const OUTCOME_POLICIES = {
  * A run with one participant: its tallied status is the verdict, so a hollow pass fails and a
  * self-reported blocker reads as blocked. Without a session, a harness failure fails the run and
  * a dry run is a contract. A run still in progress is a contract until it finishes. Computer-use
- * calls it for one lane with no rerun, and terminal calls it through judgeTerminal.
+ * calls it for one participant with no rerun, and terminal calls it through judgeTerminal.
  */
 export function judgeOneParticipant(args) {
     const status = args.participant === undefined ? undefined : judgedStatus(args.participant);
@@ -137,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) {
@@ -151,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 &&
@@ -220,14 +241,20 @@ export function foldScorerFailures(review, failures) {
     }
     return folded;
 }
-/** The run's execution outcome under its route's policy. A failure of a kind the policy lets warn is dropped. */
+/** The run's execution outcome under its route's policy. A failure of a kind the policy lets warn is a warning. */
 export function judgeExecution(failures, policy) {
-    const counted = failures.filter((failure) => failure.kind === "sandbox-cleanup"
+    const counts = (failure) => failure.kind === "sandbox-cleanup"
         ? policy.sandboxCleanup === "fails"
         : failure.kind === "evidence"
             ? policy.evidence === "fails"
-            : true);
-    return { succeeded: counted.length === 0, failures: counted };
+            : true;
+    const counted = failures.filter(counts);
+    const warnings = failures.filter((failure) => !counts(failure));
+    return {
+        succeeded: counted.length === 0,
+        failures: counted,
+        ...(warnings.length === 0 ? {} : { warnings }),
+    };
 }
 /**
  * The result's ok: the run worked as an execution, no scorer failed it, and on a gate route every

package/dist/run/locate.d.ts

@@ -2,6 +2,8 @@ import { type PreparedRunArtifactPaths } from "./paths.js";
 import { type PreparedSelectedOutputDirectory } from "./contained-output.js";
 import type { RunPointer } from "./results.js";
 import { type RunBundle } from "./bundle.js";
+/** The run input that resolves through latest.json rather than naming a run directory. */
+export declare const LATEST_RUN_ALIAS = "latest";
 /** Resolve "latest" or an explicit run id to its prepared artifact paths. */
 export declare function resolveRunPath(cwd: string, runInput: string): Promise<PreparedRunArtifactPaths | null>;
 export declare function readLatest(runsRoot: PreparedSelectedOutputDirectory): Promise<RunPointer | null>;

package/dist/run/locate.js

@@ -5,9 +5,11 @@ import { assertPreparedSelectedOutputDirectory, bindExistingManagedHumanishOutpu
 import { RUN_BUNDLE_FILE } from "./bundle.js";
 import { isRunBundle, isRunPointer } from "./bundle-shape.js";
 import { isNodeError } from "./type-guards.js";
+/** The run input that resolves through latest.json rather than naming a run directory. */
+export const LATEST_RUN_ALIAS = "latest";
 /** Resolve "latest" or an explicit run id to its prepared artifact paths. */
 export async function resolveRunPath(cwd, runInput) {
-    if (runInput === "latest") {
+    if (runInput === LATEST_RUN_ALIAS) {
         const runsRoot = await bindExistingManagedHumanishOutputDirectory(cwd, "runs");
         if (!runsRoot) {
             return null;

package/dist/run/outcomes.d.ts

@@ -1,16 +1,16 @@
 import { type ActorStatus } from "../actors/contract.js";
 import { type CuaGoalSource } from "../actors/goal-source.js";
 import type { TaskFunnel } from "../lab/tasks.js";
-import type { ParticipantOutcomes, ReviewSummary, StudyTaskFunnel } from "./bundle.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. */
 export declare function tallyParticipantOutcomes(statuses: readonly ActorStatus[], 
 /** Per-participant: did this one report friction or a defect? Same order as `statuses`. */
 reportedFriction?: readonly boolean[]): ParticipantOutcomes;
 /** Roll per-participant funnels up into the study funnel. Undefined when nothing measured one. */
-export declare function aggregateTaskFunnels(funnels: readonly TaskFunnel[]): StudyTaskFunnel | undefined;
+export declare function aggregateTaskFunnels(funnels: readonly TaskFunnel[]): RunTaskFunnel | undefined;
 /** The funnel as one line, denominator on every number: `signup 2/2 · verify-email 1/2`. */
-export declare function formatStudyTaskFunnel(funnel: StudyTaskFunnel): string;
+export declare function formatRunTaskFunnel(funnel: RunTaskFunnel): string;
 type ParticipantOutcomeDetail = {
     status: ActorStatus;
     label?: string;

package/dist/run/outcomes.js

@@ -68,7 +68,7 @@ export function aggregateTaskFunnels(funnels) {
     };
 }
 /** The funnel as one line, denominator on every number: `signup 2/2 · verify-email 1/2`. */
-export function formatStudyTaskFunnel(funnel) {
+export function formatRunTaskFunnel(funnel) {
     if (funnel.tasks.length === 0)
         return "no tasks declared";
     return funnel.tasks
@@ -138,7 +138,7 @@ export function formatParticipantOutcomes(outcomes, terminalCauses = []) {
     };
     append(outcomes.abandoned, ["abandoned"], "gave up");
     append(outcomes.ranOut, ["incomplete", "timed_out"], "interrupted (stop details unavailable)");
-    // "blocked" covers an approval the run could not give AND a blocker the participant reported in
+    // "blocked" covers an approval the run could not give and a blocker the participant reported in
     // its own words, so the label names no cause.
     if (outcomes.blocked > 0)
         parts.push(`${outcomes.blocked} blocked`);
@@ -191,7 +191,7 @@ export function withCuaReviewProvenance(review, streams) {
     const outcomes = formatParticipantOutcomes(review.participants, details);
     // Preserve rerun context, participant narration and adapter-specific findings. Refreshing a
     // historical summary qualifies its old tally instead of silently discarding that context.
-    const header = `Run gate: ${review.verdict}. Participants: ${outcomes}.${review.tasks ? ` Tasks: ${formatStudyTaskFunnel(review.tasks)}.` : ""}`;
+    const header = `Run gate: ${review.verdict}. Participants: ${outcomes}.${review.tasks ? ` Tasks: ${formatRunTaskFunnel(review.tasks)}.` : ""}`;
     const prefix = `${header} Recorded summary: `;
     const recorded = review.summary.startsWith(prefix)
         ? review.summary.slice(prefix.length)

package/dist/run/participant-records.d.ts

@@ -12,7 +12,7 @@ export declare function participantIds(position: number): ParticipantIds;
 /** A participant's record, at its 1-based place in the bundle, with its one stream. */
 export declare function participantRecord(ids: ParticipantIds, place: number, fields: Omit<RunSimulation, "id" | "index" | "streamIds">): RunSimulation;
 /**
- * A participant's stream. `participantId` is the route's own participant id (a fan-out lane's id),
+ * A participant's stream. `participantId` is the route's own participant id (a fan-out entry's `lane-NN` id),
  * saved right after the record id when the route has one.
  */
 export declare function participantStream(ids: ParticipantIds, fields: Omit<RunStream, "id" | "simId" | "laneId">, participantId?: string): RunStream;
@@ -24,5 +24,5 @@ export declare function participantResourceIds(ids: ParticipantIds, participantI
 export declare function recordIdOf(stream: RunStream): string;
 /** The record id a saved event names, when it names one. */
 export declare function eventRecordIdOf(event: RunEvent): string | undefined;
-/** The participant id an adapter recorded on a saved stream (a fan-out lane id), when it has one. */
+/** The participant id an adapter recorded on a saved stream (a fan-out `lane-NN` id), when it has one. */
 export declare function streamParticipantIdOf(stream: RunStream): string | undefined;

package/dist/run/participant-records.js

@@ -30,7 +30,7 @@ export function participantRecord(ids, place, fields) {
     };
 }
 /**
- * A participant's stream. `participantId` is the route's own participant id (a fan-out lane's id),
+ * A participant's stream. `participantId` is the route's own participant id (a fan-out entry's `lane-NN` id),
  * saved right after the record id when the route has one.
  */
 export function participantStream(ids, fields, participantId) {
@@ -57,7 +57,7 @@ export function recordIdOf(stream) {
 export function eventRecordIdOf(event) {
     return event.simId;
 }
-/** The participant id an adapter recorded on a saved stream (a fan-out lane id), when it has one. */
+/** The participant id an adapter recorded on a saved stream (a fan-out `lane-NN` id), when it has one. */
 export function streamParticipantIdOf(stream) {
     return stream.laneId;
 }

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) {
@@ -262,7 +262,7 @@ async function assertNoSymlinkDescendants(directory) {
     const entries = await readdir(directory, { withFileTypes: true });
     for (const entry of entries) {
         const child = path.join(directory, entry.name);
-        // A run directory can be written CONCURRENTLY with this walk — the atomic writer creates a
+        // A run directory can be written concurrently with this walk: the atomic writer creates a
         // `.humanish-write-*.tmp` sibling and renames it, and a run now also refreshes its own status
         // record on a cadence. An entry that vanished between readdir and lstat therefore proves
         // nothing except that it is gone, and a path that no longer exists cannot be a symlink escape:

package/dist/run/pricing.d.ts

@@ -10,12 +10,12 @@ export interface ModelRate {
      *  a reduced rate. Optional: absent means we do not model a discount and every input token is
      *  billed at `inputUsdPerToken`. */
     cachedInputUsdPerToken?: number;
-    /** USD per input token newly WRITTEN to the provider's prompt cache, when the provider bills
+    /** USD per input token newly written to the provider's prompt cache, when the provider bills
      *  writes (OpenAI: GPT-5.6+ bills `cache_write_tokens` at 1.25x the uncached input rate, as the
-     *  TOTAL rate for those tokens — not an extra charge on top). Absent = writes are free (every
+     *  total rate for those tokens, with no extra charge on top). Absent = writes are free (every
      *  pre-5.6 model) and any reported write tokens price at the plain input rate. */
     cacheWriteUsdPerToken?: number;
-    /** Long-context tier, when the provider re-prices the WHOLE request past an input-size
+    /** Long-context tier, when the provider re-prices the whole request past an input-size
      *  threshold (OpenAI GPT-5.6: >272K input tokens => 2x input-side, 1.5x output, full request).
      *  Priced exactly only when the usage carries per-request `turns` records; totals alone cannot
      *  say which requests crossed, so without turns the estimate stays on the short-context rate,
@@ -25,11 +25,11 @@ 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;
-    /** true = a stand-in NOT copied from a live sheet; the estimate carries this flag so a
+    /** true = a stand-in that was not copied from a live sheet; the estimate carries this flag so a
      *  placeholder rate is never mistaken for a confirmed one. */
     placeholder?: boolean;
 }
@@ -52,8 +52,8 @@ export interface DesktopResourceRate {
     source: string;
 }
 /**
- * The token-derived cost ESTIMATE for one actor lane. `estimatedCostUsd: null` = DECLARED ABSENT
- * (unknown rate or no token usage) — never coerced to 0. A non-null figure ALWAYS carries its
+ * The token-derived cost estimate for one actor trace. `estimatedCostUsd: null` = declared absent
+ * (unknown rate or no token usage) and is never coerced to 0. A non-null figure always carries its
  * pricing provenance (`ratesAsOf` + `source`) so the mechanism (a rate-table multiply) matches
  * the claim (an estimate, not a charge). Defined here so the rate table and the field that
  * consumes it live together; `ActorTrace` imports it type-only.
@@ -71,22 +71,26 @@ export interface ActorEstimatedCost {
     modelId?: string;
     /** true when the rate is a stand-in, not a live sheet. */
     placeholder?: boolean;
+    /** Set when usage arrived as runtime-turn totals that each sum several requests. No request's
+     *  own size is known, so no per-request long-context tier was applied: tokens are priced at the
+     *  base tier, cached input at the cached rate. */
+    basis?: "aggregated_turns_base_rate";
     breakdown?: {
         inputUsd: number;
         outputUsd: number;
         inputTokens: number;
         outputTokens: number;
         /** 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. */
+         *  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. */
         longContextTurns?: number;
     };
 }
-/** The desktop-minute cost ESTIMATE (host-side create->teardown span * a per-minute rate). Same
+/** The desktop-minute cost estimate (host-side create->teardown span * a per-minute rate). Same
  *  null-discipline as ActorEstimatedCost: `estimatedCostUsd: null` = not measured (no duration). */
 export interface DesktopCostEstimate {
     estimatedCostUsd: number | null;
@@ -100,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. */
@@ -108,17 +117,23 @@ export declare function estimateAllocatedDesktopCost(minutes: number | undefined
  *  precision. */
 export declare function round6(n: number): number;
 /**
- * Estimate one actor lane'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.
+ * 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.
  */
 export declare function estimateActorCostForExecution(usage: ActorTokenUsage | undefined, modelId: string | undefined, profile?: {
     billing?: unknown;
 }): ActorEstimatedCost;
+/**
+ * Price usage reported as runtime-turn totals, such as Codex `turn.completed`, which sums every
+ * request in the turn. Pricing a turn as one request would apply the long-context tier to the
+ * whole turn, so the per-turn records are dropped and the totals price on the base tier.
+ */
+export declare function estimateAggregatedTurnCost(tokenUsage: ActorTokenUsage | undefined, modelId: string | undefined): ActorEstimatedCost;
 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

@@ -1,18 +1,18 @@
-// OPERATOR-EDITABLE ESTIMATES — NOT authoritative prices. Providers change pricing without
-// notice. When they do, update BOTH the number AND the `asOf` date on the affected entry.
-// Every dollar figure humanish derives from this table is surfaced/persisted as an ESTIMATE,
-// labeled "estimated (rates as of <asOf>)", and is NEVER presented as an exact charge.
+// Operator-editable estimates, which are not authoritative prices. Providers change pricing without
+// notice. When they do, update both the number and the `asOf` date on the affected entry.
+// Every dollar figure humanish derives from this table is surfaced/persisted as an estimate,
+// labeled "estimated (rates as of <asOf>)", and is never presented as an exact charge.
 //
-// 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), NEVER a guessed or silent-zero cost (invariant 5). A bare
+// 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. 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
+// The gpt-5.6 long-context tier: >272K input tokens re-prices the full request at 2x
 // input-side / 1.5x output (developers.openai.com/api/docs/models/gpt-5.6-sol, 2026-08-18).
 const LONG_CONTEXT_TIER_272K = {
     thresholdInputTokens: 272_000,
@@ -41,17 +41,17 @@ function rateWithLongContextTier(inPer1M, cachedPer1M, writePer1M, outPer1M, asO
 const GPT56_SOL_PROMO_AS_OF = "2026-09-03";
 const GPT6_ASTRA_AS_OF = "2026-09-03";
 // Per-model rates, keyed on the model id that lands in trace.ids.model (lookup is
-// case-insensitive on a trimmed id). An id NOT present here is DECLARED ABSENT, never guessed.
+// 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).
@@ -74,7 +74,7 @@ export const MODEL_RATES = {
     "gpt-5.6-cyber": rateWithLongContextTier(12.5, 1.25, 15.625, 75),
     // Daybreak program aliases (blue -> sol, red -> cyber today). OpenAI repoints these as new
     // frontier models ship, so prefer the explicit tier id in labs; the entries exist so a
-    // configured alias still prices at what the alias bills TODAY.
+    // configured alias still prices at what the alias bills today.
     "daybreak-blue-latest": rateWithLongContextTier(4, 0.4, 5, 20, GPT56_SOL_PROMO_AS_OF),
     "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
@@ -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",
@@ -157,9 +164,9 @@ export function round6(n) {
     return Math.round(n * 1e6) / 1e6;
 }
 /**
- * Estimate one actor lane'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.
+ * 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.
  */
 export function estimateActorCostForExecution(usage, modelId, profile) {
     return profile?.billing === "account-unknown"
@@ -172,6 +179,18 @@ export function estimateActorCostForExecution(usage, modelId, profile) {
         }
         : estimateActorCost(usage, modelId);
 }
+/**
+ * Price usage reported as runtime-turn totals, such as Codex `turn.completed`, which sums every
+ * request in the turn. Pricing a turn as one request would apply the long-context tier to the
+ * whole turn, so the per-turn records are dropped and the totals price on the base tier.
+ */
+export function estimateAggregatedTurnCost(tokenUsage, modelId) {
+    const { turns: _turns, ...totals } = tokenUsage ?? {};
+    const estimate = estimateActorCost(tokenUsage === undefined ? undefined : totals, modelId);
+    return estimate.estimatedCostUsd === null
+        ? estimate
+        : { ...estimate, basis: "aggregated_turns_base_rate" };
+}
 export function estimateActorCost(tokenUsage, modelId, rates = MODEL_RATES) {
     if (!tokenUsage || (tokenUsage.input === undefined && tokenUsage.output === undefined)) {
         return {
@@ -193,15 +212,15 @@ export function estimateActorCost(tokenUsage, modelId, rates = MODEL_RATES) {
     }
     const inTok = tokenUsage.input ?? 0;
     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
+    // 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, 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 ?? [];
     const sumOf = (field) => turns.reduce((sum, turn) => sum + (turn[field] ?? 0), 0);
-    // The ledger is trusted only when it decomposes the totals EXACTLY — all four sums, not just
-    // input/output. A ledger that carries request sizes but not the cache splits would otherwise
+    // The ledger is trusted only when it decomposes the totals exactly, in all four sums including the
+    // cache splits. A ledger that carries request sizes but not the cache splits would otherwise
     // price every token at the full rate while the session totals sit ignored, overstating spend
     // 3.5-5x and tripping caps early. Inconsistent evidence falls back to the totals path, which
     // honors the declared splits on the base tier.
@@ -217,15 +236,15 @@ export function estimateActorCost(tokenUsage, modelId, rates = MODEL_RATES) {
     let writeTotal = 0;
     let longContextTurns = 0;
     // Price one request's usage at one tier. Cached input is billed at a fraction of the full rate,
-    // and on a session that threads provider state it is the MAJORITY of input — pricing it at the
-    // full rate overstates real spend by up to ~10x. Cache WRITES bill at their own rate (1.25x on
+    // 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;
@@ -281,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) {