humanish 0.106.0 → 0.107.0

package/dist/run/{study-files.js → evidence-files.js}

@@ -12,7 +12,7 @@ import { isNodeError } from "./type-guards.js";
  * percent-decoded up to five times, and each round must still be a plain relative path, so an
  * encoded `..` or separator cannot survive into a later decode.
  */
-export function isStudyEvidencePath(value) {
+export function isEvidencePath(value) {
     return decodesToPlainRelativePath(value, 1024, /[\\:\x00-\x1f\x7f]|^\//);
 }
 /**
@@ -54,8 +54,8 @@ export function decodesToPlainRelativePath(value, maxLength, unsafe) {
  * not turn an analysis budget into an unbounded read. No returned bytes have
  * authority to select another file or initiate a network request.
  */
-export async function readBoundedStudyFile(root, relativePath, maxBytes) {
-    const result = await readBoundedStudyFileResult(root, relativePath, maxBytes);
+export async function readBoundedFile(root, relativePath, maxBytes) {
+    const result = await readBoundedFileResult(root, relativePath, maxBytes);
     return result.state === "read" ? result.bytes : null;
 }
 /**
@@ -89,8 +89,8 @@ export async function pathMissing(filePath) {
 }
 const unavailable = { state: "unavailable" };
 /** Size refusals are distinguished only after the same contained regular-file checks. */
-export async function readBoundedStudyFileResult(root, relativePath, maxBytes) {
-    if (!isStudyEvidencePath(relativePath) || !Number.isSafeInteger(maxBytes) || maxBytes < 1)
+export async function readBoundedFileResult(root, relativePath, maxBytes) {
+    if (!isEvidencePath(relativePath) || !Number.isSafeInteger(maxBytes) || maxBytes < 1)
         return unavailable;
     const validateRoot = async () => {
         if ("physicalRunRoot" in root) {

package/dist/run/feedback-shape.js

@@ -31,7 +31,7 @@ export function isRunFeedbackCandidate(value) {
         isFeedbackNextState(value.proposed_next_state) &&
         Array.isArray(value.acceptance_proof) &&
         value.acceptance_proof.every((item) => typeof item === "string") &&
-        // Optional, adapter-namespaced product-noun block: when present, validate only its SHAPE
+        // Optional, adapter-namespaced product-noun block: when present, validate only its shape
         // (a non-empty namespace + a data record). Core never inspects the keys inside `data`.
         (value.adapter === undefined || isFeedbackAdapterBlock(value.adapter)));
 }

package/dist/run/judge.d.ts

@@ -60,7 +60,7 @@ 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 lane and the fan-out roll-up (#476).
+ * goal. One rule for the single participant and the fan-out roll-up (#476).
  */
 export declare function participantStatus(status: ActorStatus, judgments: {
     noEngagement: boolean;
@@ -86,7 +86,7 @@ export interface Judgment {
 /** The judgment for a verdict: a run passes when its verdict is pass, and a dry run passes. */
 export declare function judgmentOf(verdict: Verdict, dryRun: boolean): Judgment;
 /** What kind of execution failure a run recorded. */
-type ExecutionFailureKind = "harness" | "provider-cleanup" | "sandbox-cleanup" | "evidence" | "cap" | "run";
+type ExecutionFailureKind = "harness" | "provider-cleanup" | "provider-policy" | "sandbox-cleanup" | "evidence" | "cap" | "run";
 /** One way the run failed as an execution. The message is scrubbed; status.json shows it. */
 export interface ExecutionFailure {
     kind: ExecutionFailureKind;
@@ -98,7 +98,19 @@ export interface ExecutionOutcome {
     succeeded: boolean;
     /** The failures the policy counts, in the order the route recorded them. */
     failures: ExecutionFailure[];
+    /**
+     * The failures the policy lets warn, such as a sandbox whose release is unconfirmed on a route
+     * whose evidence stands. They leave `succeeded` and the result's ok alone but stay visible in
+     * status.json. Omitted when there are none.
+     */
+    warnings?: ExecutionFailure[];
 }
+/**
+ * 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 declare function sandboxCleanupFailure(owner: string, warning: string | undefined, runId: string, recovery?: string): ExecutionFailure;
 /**
  * How a route turns the facts into its result's ok. A gate route needs every participant to
  * pass. On an evidence route a participant that failed, was blocked or timed out is captured
@@ -131,7 +143,7 @@ export interface SharedWorldJudgment extends Judgment {
  * 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 declare function judgeOneParticipant(args: {
     dryRun: boolean;
@@ -195,7 +207,7 @@ export declare function judgePreview(): Judgment;
  * stays as it was, so scoring can never improve a verdict. No failures returns the review as is.
  */
 export declare function foldScorerFailures(review: ReviewSummary, failures: readonly string[]): ReviewSummary;
-/** 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 declare function judgeExecution(failures: readonly ExecutionFailure[], policy: OutcomePolicy): ExecutionOutcome;
 /**
  * The result's ok: the run worked as an execution, no scorer failed it, and on a gate route every

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;
@@ -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 (#476).
  */
 export function participantStatus(status, judgments) {
     if (status !== "passed" || judgments === undefined)
@@ -98,6 +98,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 +122,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);
@@ -220,14 +231,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.js

@@ -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,
@@ -29,7 +29,7 @@ export interface ModelRate {
     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,13 +71,17 @@ 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+). */
         cacheWriteInputTokens?: number;
@@ -86,7 +90,7 @@ export interface ActorEstimatedCost {
         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;
@@ -108,13 +112,19 @@ 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;
+ * 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

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 (invariant 5). 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).
 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,7 +41,7 @@ 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).
@@ -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
@@ -157,7 +157,7 @@ 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;
+ * 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.
  */
@@ -172,6 +172,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 +205,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
+    // 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
     // 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,8 +229,8 @@ 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.

package/dist/run/projection.d.ts

@@ -40,11 +40,11 @@ export interface LabExpectation {
     costUnknown: number;
 }
 /**
- * Derive what to expect from a lab's own history. Only FINISHED runs count: an interrupted run's
+ * Derive what to expect from a lab's own history. Only finished runs count: an interrupted run's
  * duration is the length of an accident, not of a study, and including it would quietly bias the
  * estimate the operator uses to decide whether to press Start.
  *
- * MODE MATTERS, and mixing modes is a lie rather than an imprecision. A dry run spends nothing and
+ * The mode matters: mixing modes produces a false figure. A dry run spends nothing and
  * takes no time, so a median over nine dry runs and one live one reports that a live run is free —
  * next to a control that spends money. Pass the mode the figure is about; omit it only for a
  * summary that is not attached to an action.
@@ -59,7 +59,7 @@ export declare function expectationLine(expectation: LabExpectation): string;
 /**
  * The one line a lab may say about itself, wherever it is shown.
  *
- * Prefers LIVE figures: cost and duration are what someone reads before spending, and a median
+ * Prefers live figures: cost and duration are what someone reads before spending, and a median
  * diluted by dry runs reports a live study as cheaper and faster than it has ever been. With no
  * live history it reports the count and claims nothing about time or money — which is why this is
  * shared rather than reimplemented per surface, since the two disagreeing is the whole failure.
@@ -104,15 +104,15 @@ export declare function livenessLabel(entry: Pick<RunIndexEntry, "liveness" | "v
 /** A lab as the labs list shows it: what is declared, joined to what actually happened. */
 export interface LabRow {
     /**
-     * Stable identity for THIS ROW. A manifest's path when it has one, else the lab id — because two
+     * Stable identity for this row. A manifest's path when it has one, else the lab id, because two
      * manifests can declare the same id, and keying rows by id makes them collapse into a pair of
      * indistinguishable duplicates.
      */
     key: string;
-    /** The declared id. Run history attributes to this, so it is NOT unique across manifests. */
+    /** The declared id. Run history attributes to this, so it is not unique across manifests. */
     labId: string;
     /**
-     * The handle an operator would actually type. Lab resolution is by FILENAME, so the manifest
+     * The handle an operator would actually type. Lab resolution is by filename, so the manifest
      * `\`.humanish/labs/persona-contrast-live.yaml\`` is reached as `persona-contrast-live` even when
      * the id inside it says something else.
      */
@@ -120,25 +120,25 @@ export interface LabRow {
     /** The manifest's own title, when it has one. */
     title?: string;
     /**
-     * The shortest label that is UNIQUE among the rows it is listed with: the title when no other
+     * The shortest label that is unique among the rows it is listed with: the title when no other
      * lab shares it, else the filename, else the full path. A list is only navigable if every row can
      * be told from every other one, and a title is not guaranteed to be distinct — two manifests in
-     * this repo carry the same title AND the same declared id, differing only by filename.
+     * this repo carry the same title and the same declared id, differing only by filename.
      */
     label: string;
-    /** The manifest's own words, for the list to say what this study IS. */
+    /** The manifest's own words, for the list to say what this study is. */
     description?: string;
     /** Repo-relative manifest path, absent for a lab known only from run history. */
     path?: string;
     origin?: "committed" | "ignored" | "explicit";
     /**
-     * False for a lab that has runs but NO manifest here — renamed, deleted, or run from a path that
+     * False for a lab that has runs but no manifest here: renamed, deleted, or run from a path that
      * is gone. Its runs are still evidence and must stay reachable, so it is listed and marked rather
      * than dropped.
      */
     declared: boolean;
     /**
-     * How many OTHER manifests declare this same lab id. Above zero, the run history below is shared
+     * How many other manifests declare this same lab id. Above zero, the run history below is shared
      * between them and cannot be attributed to one file — worth saying, because it is a
      * misconfiguration the operator almost certainly does not know about.
      */
@@ -169,13 +169,13 @@ export interface DeclaredLab {
  * deleted — that evidence still exists on disk, so dropping those rows would make real runs
  * unreachable from the surface that is supposed to list them.
  *
- * ONE ROW PER MANIFEST, not per id. The two are not the same thing: a manifest is addressed by its
+ * One row per manifest, not per id. The two are not the same thing: a manifest is addressed by its
  * filename while its runs attribute to the id declared inside it, so several files can legitimately
  * share an id. Collapsing them hides a real file; keying by id duplicates a row with no way to tell
  * the copies apart. Both happen in practice — this repo has exactly that pair.
  *
  * Order puts a lab someone is working in first, then labs by how recently they ran, then declared
- * labs that have never run (alphabetically BY WHAT IS DISPLAYED, so the order on screen is the
+ * labs that have never run (alphabetically by the displayed label, so the order on screen is the
  * order a reader can predict), then labs known only from history.
  */
 export declare function labRows(declared: readonly DeclaredLab[], entries: readonly RunIndexEntry[]): {