humanish 0.106.1 → 0.107.0

package/dist/run/detail.js

@@ -1,4 +1,4 @@
-// What ONE run is doing right now: who is in it, what they are thinking, how far they have got.
+// What one run is doing right now: who is in it, what they are thinking, how far they have got.
 // Unlike the run index, it opens the bundle, which is affordable for the one run someone is
 // looking at.
 //
@@ -7,7 +7,7 @@
 //   - `stream.actor` once it has finished.
 // Reading both means the same screen renders a run the whole way through rather than going blank
 // at the moment it completes.
-import { readAutomaticStudyAnalysis } from "../analysis/automatic.js";
+import { readAutomaticAnalysis } from "../analysis/automatic.js";
 import path from "node:path";
 import { estimateActorCostForExecution } from "./pricing.js";
 import { resolveRunPath } from "./locate.js";
@@ -18,7 +18,7 @@ const RUN_DETAIL_SCHEMA = "humanish.run-detail.v1";
 /**
  * The latest reasoning a participant has recorded.
  *
- * Takes the LAST reasoning item rather than the newest by timestamp: the trace is append-ordered by
+ * Takes the last reasoning item rather than the newest by timestamp: the trace is append-ordered by
  * construction, and half of a live flush may not carry `at` yet. An item still in flight is skipped
  * — a partial thought read mid-write would be quoted as though the participant had finished it.
  */
@@ -68,7 +68,7 @@ function participantFrom(stream, index) {
 /**
  * What a participant has spent, priced the same way whether the run is finished or in flight.
  *
- * A finished trace carries its own `estimatedCost`. A live one carries the RUNNING usage and the
+ * A finished trace carries its own `estimatedCost`. A live one carries the running usage and the
  * model it prices at, so the same estimator gives a figure mid-run instead of the screen reporting
  * the cost as unknown until the moment the run ends — which is the half of a run where knowing what
  * it is costing actually changes what you do.
@@ -98,7 +98,7 @@ function costOf(trace) {
  * Read one run's participants. Returns null when the run has no readable bundle yet — an ordinary
  * state for a run that has just started, not a failure.
  *
- * Reads the bundle NARROWLY rather than through `loadRunBundle`, which applies the strict
+ * Reads the bundle narrowly rather than through `loadRunBundle`, which applies the strict
  * evidence-of-record guard. That guard is right for verification and wrong here: a mid-run flush is
  * a partial document by definition, so validating it as a complete bundle would make the live view
  * — the only view that needs this — the one case that never renders. Nothing read here is treated
@@ -126,7 +126,7 @@ export async function readRunDetail(cwdInput, runId) {
     }
     const streams = Array.isArray(bundle.streams) ? bundle.streams : [];
     const observerAbsolute = path.join(runPaths.absoluteRunRoot, "observer", "index.html");
-    const automaticAnalysis = await readAutomaticStudyAnalysis(cwd, runId);
+    const automaticAnalysis = await readAutomaticAnalysis(cwd, runId);
     return {
         ...(automaticAnalysis === undefined ? {} : { automaticAnalysis }),
         schema: RUN_DETAIL_SCHEMA,

package/dist/run/dry-run.js

@@ -37,7 +37,7 @@ async function runDryRunInScope(options, scope) {
     if (participants === null) {
         return refused(requestedCwd, warnings, {
             code: "HUMANISH_INVALID_SIM_COUNT",
-            message: "--sims must be a positive integer.",
+            message: "--count must be a positive integer.",
         });
     }
     // Bind the physical project, as the lab routes do: a symlinked cwd retargeted mid-run cannot
@@ -66,6 +66,8 @@ async function runDryRunInScope(options, scope) {
         mode: options.dryRun ? "dry-run" : "live",
         lab: options.lab,
         renderReview: renderReviewMarkdown,
+        // The run starts at the time its id and source were stamped with.
+        now: () => Date.parse(createdAt),
         ...(options.observer === undefined ? {} : { observer: { open: options.observer.open } }),
     });
     if (!started.ok)
@@ -85,16 +87,7 @@ async function runDryRunInScope(options, scope) {
     });
     const judgment = judgePreview();
     const bundle = {
-        ...bundleHead({
-            runId,
-            mode: "dry-run",
-            participants,
-            createdAt,
-            cwd,
-            artifactRoot,
-            ...(options.lab === undefined ? {} : { lab: options.lab }),
-            source,
-        }),
+        ...bundleHead(run, { participants, cwd, artifactRoot, source }),
         persona: inputs.persona,
         scenario: inputs.scenario,
         lifecycle: [
@@ -211,7 +204,7 @@ async function renderPreviewObserver(finished, warnings) {
         return undefined;
     }
 }
-/** One synthetic stream per lane kind; the preview cycles through them. */
+/** One synthetic stream per stream kind (UI, terminal and the rest); the preview cycles through them. */
 const SYNTHETIC_STREAM_TEMPLATES = [
     {
         kind: "ui",

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

@@ -4,7 +4,7 @@ import { type PreparedOutputRoot } from "./contained-output.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 declare function isStudyEvidencePath(value: string): boolean;
+export declare function isEvidencePath(value: string): boolean;
 /**
  * True when `value` (at most `maxLength` characters) stays a plain relative path through up to five
  * rounds of percent-decoding: no round may match `unsafe`, have an empty, `.` or `..` segment, or
@@ -16,13 +16,13 @@ export declare function decodesToPlainRelativePath(value: string, maxLength: num
  * not turn an analysis budget into an unbounded read. No returned bytes have
  * authority to select another file or initiate a network request.
  */
-export declare function readBoundedStudyFile(root: PreparedOutputRoot, relativePath: string, maxBytes: number): Promise<Buffer | null>;
+export declare function readBoundedFile(root: PreparedOutputRoot, relativePath: string, maxBytes: number): Promise<Buffer | null>;
 /**
  * After a bounded read returned nothing: true when the file is absent, false when something is
  * there that could not be read. Errors other than ENOENT propagate.
  */
 export declare function pathMissing(filePath: string): Promise<boolean>;
-export type BoundedStudyFileResult = {
+export type BoundedFileResult = {
     state: "read";
     bytes: Buffer;
 } | {
@@ -32,4 +32,4 @@ export type BoundedStudyFileResult = {
     state: "unavailable";
 };
 /** Size refusals are distinguished only after the same contained regular-file checks. */
-export declare function readBoundedStudyFileResult(root: PreparedOutputRoot, relativePath: string, maxBytes: number): Promise<BoundedStudyFileResult>;
+export declare function readBoundedFileResult(root: PreparedOutputRoot, relativePath: string, maxBytes: number): Promise<BoundedFileResult>;

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.