humanish 0.115.0 → 0.116.0

package/dist/routes/computer-use/subject-projection.js

@@ -1,6 +1,6 @@
-// Each participant's subject projection and the subject-state marker, from the declared subject
-// and what the participants ran; the run-level subject aggregated from them; and the provenance argument the
-// bundle builders take.
+// How a computer-use run records its subject: each participant's subject and the subject-state
+// marker, from the declared subject and what the participants ran, and the run-level subject
+// aggregated from them. Both bundle shapes and the JSON result write what this module returns.
 import { commandDigestOf } from "../../subject/state.js";
 import { cuaDeclaredState } from "./plan.js";
 import {} from "../../run/bundle.js";
@@ -25,7 +25,7 @@ export function projectParticipantSubjects(args) {
             executed: outcome?.stateStepRecords ?? [],
         });
         return participantSubjectProjection({
-            kind: subject.kind,
+            subject,
             ...(publicRepo === undefined ? {} : { publicRepo }),
             subjectEnvNames,
             ...(outcome?.subjectCommit === undefined ? {} : { subjectCommit: outcome.subjectCommit }),
@@ -79,7 +79,7 @@ export function resolveSubjectState(args) {
  *  commit/dirty (no divergence is possible, unlike the clone route's per-participant
  *  in-sandbox commit). */
 function participantSubjectProjection(args) {
-    if (args.kind === "clone" && args.publicRepo) {
+    if (args.subject.kind === "clone" && args.publicRepo) {
         return {
             source: "clone",
             repo: args.publicRepo,
@@ -88,7 +88,7 @@ function participantSubjectProjection(args) {
             state: args.subjectState,
         };
     }
-    if (args.kind === "local-tree") {
+    if (args.subject.kind === "local-tree") {
         const archive = args.localTreeArchive;
         return {
             source: "local-tree",
@@ -100,32 +100,10 @@ function participantSubjectProjection(args) {
             state: args.subjectState,
         };
     }
-    return { source: "app-url", state: args.subjectState };
-}
-/** Narrow a resolved CuaSubjectProjection into the shape buildSingleParticipantBundle's
- *  subjectProvenance param wants (provisioned-route sources only; app-url stays undeclared, the
- *  default branch that builder already handles). */
-export function subjectProvenanceArg(subject, publicRepo, subjectEnvNames) {
-    if (subject.source === "clone" && publicRepo) {
-        return {
-            source: "clone",
-            repo: publicRepo,
-            ...(subject.commit === undefined ? {} : { commit: subject.commit }),
-            envNames: subjectEnvNames,
-            state: subject.state,
-        };
+    if (args.subject.kind === "desktop-cli") {
+        return { source: "desktop-cli", product: args.subject.product.name, state: args.subjectState };
     }
-    if (subject.source === "local-tree") {
-        return {
-            source: "local-tree",
-            ...(subject.archiveSha256 === undefined ? {} : { archiveSha256: subject.archiveSha256 }),
-            ...(subject.commit === undefined ? {} : { commit: subject.commit }),
-            ...(subject.dirty === undefined ? {} : { dirty: subject.dirty }),
-            envNames: subjectEnvNames,
-            state: subject.state,
-        };
-    }
-    return undefined;
+    return { source: "app-url", state: args.subjectState };
 }
 /**
  * The run-level subject for the top level and the bundle. Local-tree participants all pack from the

package/dist/routes/computer-use/types.d.ts

@@ -161,7 +161,7 @@ export interface CuaParticipantResult {
         killed: boolean;
         streamUrlPresent: boolean;
     };
-    subject: CuaSubjectProjection;
+    subject: RunSubjectProvenance;
     diagnostics?: CuaDiagnostics;
     /** Set when the participant was skipped (pinned reason string). */
     skippedReason?: string;
@@ -186,43 +186,6 @@ export interface CuaParticipantSummary {
     waves: number;
 }
 export type CuaActorStudyErrorCode = StudyResultErrorCode | "HUMANISH_COMPUTER_USE_FAILED" | "HUMANISH_COMPUTER_USE_KEYS_MISSING" | "HUMANISH_COMPUTER_USE_AGENT_MISSING" | "HUMANISH_COMPUTER_USE_AGENT_SIGNIN_REQUIRED" | "HUMANISH_COMPUTER_USE_SUBJECT_ENV_MISSING" | "HUMANISH_COMPUTER_USE_ACTOR_UNSUPPORTED" | "HUMANISH_COMPUTER_USE_SUBJECT_INVALID" | "HUMANISH_COMPUTER_USE_SUBJECT_UNSAFE" | "HUMANISH_COMPUTER_USE_EXECUTOR_NO_PROVIDER" | "HUMANISH_COMPUTER_USE_LOCAL_APP_NO_EXECUTOR" | "HUMANISH_COMPUTER_USE_LOCAL_DESKTOP_MISSING" | "HUMANISH_COMPUTER_USE_LOCAL_CAPACITY_EXCEEDED" | "HUMANISH_COMPUTER_USE_DESKTOP_OUT_OF_MEMORY" | "HUMANISH_COMPUTER_USE_FANOUT_INVALID" | "HUMANISH_COMPUTER_USE_RERUN_INVALID" | "HUMANISH_COMPUTER_USE_DEVICE_GEOMETRY" | "HUMANISH_COMPUTER_USE_UNPRICED_CAP" | "HUMANISH_COMPUTER_USE_COMMS_CATCH_UNREACHABLE" | "HUMANISH_COMPUTER_USE_COMMS_TOKEN_INVALID" | "HUMANISH_WATCH_ALLOW_REQUIRES_OAUTH" | "HUMANISH_WATCH_OAUTH_REQUIRES_TUNNEL" | "HUMANISH_WATCH_OPTION_CONFLICT" | "HUMANISH_WATCH_TUNNEL_REQUIRES_EXPOSE" | "HUMANISH_WATCH_EXPOSE_REQUIRES_EDGE_AUTH" | "HUMANISH_WATCH_EXPOSE_REQUIRES_LIVE_FOLLOW" | "HUMANISH_WATCH_SAFE_NOT_APPLICABLE" | "HUMANISH_SERVE_TUNNEL_NOT_FOUND" | "HUMANISH_SERVE_TUNNEL_START_FAILED";
-/** Subject provenance projection: what the actor actually drove. */
-export interface CuaSubjectProjection {
-    source: "app-url" | "clone" | "local-tree";
-    /** Clone-route only: the (possibly redacted) owner/repo slug. */
-    repo?: string;
-    /** Cloned commit SHA (clone route) or host-side HEAD at pack time (local-tree route, when
-     *  the packed root was a git work tree). */
-    commit?: string;
-    /** Local-tree-route only: 64-hex sha256 over the sorted packed-entries list: the content
-     *  pin for a tree that cannot be commit-pinned. Absent on dry-run (nothing was packed). */
-    archiveSha256?: string;
-    /** Local-tree-route only: host-side porcelain status at pack time (true when the working
-     *  tree had uncommitted changes). Absent when the packed root was not a git work tree. */
-    dirty?: boolean;
-    /** Declared env names provisioned for the subject (values never surface anywhere). */
-    envNames?: string[];
-    /** The subject's state story (seeded digests / unpinned external / declared-not-run /
-     *  undeclared): the same block the run bundle records. */
-    state: RunSubjectProvenance["state"];
-}
-/** The provisioned-route-only shape threaded through as buildSingleParticipantBundle's
- *  subjectProvenance arg (clone or local-tree; an app-url subject stays undeclared, which that
- *  builder's own default branch already handles without this type). */
-export type CuaSubjectProvenanceArg = {
-    source: "clone";
-    repo: string;
-    commit?: string;
-    envNames: string[];
-    state: RunSubjectProvenance["state"];
-} | {
-    source: "local-tree";
-    archiveSha256?: string;
-    commit?: string;
-    dirty?: boolean;
-    envNames: string[];
-    state: RunSubjectProvenance["state"];
-};
 export interface CuaActorStudyResult extends AutomaticAnalysisResult, StudyResultIdentity<"computer-use"> {
     /** True when the Observer verified the bundle, all live participants passed credibility checks
      * (or this is a dry-run), and no declared adapter/scorer verdict failed. */
@@ -253,7 +216,7 @@ export interface CuaActorStudyResult extends AutomaticAnalysisResult, StudyResul
     };
     /** Subject provenance: what the actor actually drove. At N>1 this is the
      *  unanimity-gated aggregate (top-level `commit` only when every participant resolved the same one). */
-    subject?: CuaSubjectProjection;
+    subject?: RunSubjectProvenance;
     /** The pre-flight participant plan (present once participants resolve; absent on early validation errors). */
     plan?: CuaParticipantPlan;
     /** Per-participant results, always present once participants resolve (length 1 at N=1). */
@@ -485,8 +448,8 @@ export interface CuaFanoutBundleArgs {
     run: BundleRun;
     specs: DesktopParticipantRun[];
     outcomes?: ParticipantRunOutcome[];
-    subjects: CuaSubjectProjection[];
-    aggregateSubject: CuaSubjectProjection;
+    subjects: RunSubjectProvenance[];
+    aggregateSubject: RunSubjectProvenance;
     descriptor: CuaActorDescriptor;
     appUrl: string;
     dryRun: boolean;

package/dist/routes/scripted/scenario.js

@@ -5,7 +5,7 @@ import { parse as parseYaml } from "yaml";
 import path from "node:path";
 import { parseBrowserPersonaJourneyFromScenario } from "../../actors/scripted-browser/journey.js";
 import { digestText } from "../../evidence/redaction.js";
-import { readContainedRegularFile, } from "../../run/contained-output.js";
+import { readContainedRegularFile, PROJECT_FILE_MAX_BYTES, refusalText, } from "../../run/contained-output.js";
 // Same public-safe token shape the study id uses; an id-style `scenario` must match it before
 // it is interpolated into a repo path.
 const SCENARIO_REF_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
@@ -20,6 +20,7 @@ export async function resolveScriptedScenario(projectRoot, ref) {
     const trimmed = ref.trim();
     let absolutePath;
     let source;
+    let read;
     if (scenarioRefLooksLikePath(trimmed)) {
         absolutePath = path.resolve(projectRoot.physicalPath, trimmed);
         const relative = path.relative(projectRoot.physicalPath, absolutePath);
@@ -42,22 +43,36 @@ export async function resolveScriptedScenario(projectRoot, ref) {
             path.posix.join("humanish", "scenarios", `${trimmed}.yaml`),
             path.posix.join("humanish", "scenarios", `${trimmed}.yml`),
         ];
-        const found = await firstExistingFile(projectRoot, candidates);
-        if (!found) {
+        const found = await firstScenarioFile(projectRoot, candidates);
+        if (found === null) {
             return {
                 ok: false,
                 message: `scenario "${trimmed}" was not found (looked for ${candidates.join(", ")}).`,
             };
         }
-        source = found;
-        absolutePath = path.join(projectRoot.physicalPath, found);
+        // A candidate that is there and refused stops the search: the next one is not the scenario.
+        if (found.read.status === "refused") {
+            return {
+                ok: false,
+                message: `scenario "${trimmed}" could not be read: ${refusalText(found.candidate, found.read)}.`,
+            };
+        }
+        source = found.candidate;
+        read = found.read;
+        absolutePath = path.join(projectRoot.physicalPath, found.candidate);
     }
     const relativeScenarioPath = path.relative(projectRoot.physicalPath, absolutePath);
-    const scenarioBytes = await readContainedRegularFile(projectRoot, relativeScenarioPath);
-    if (!scenarioBytes) {
+    read ??= await readContainedRegularFile(projectRoot, relativeScenarioPath, PROJECT_FILE_MAX_BYTES);
+    if (read.status === "refused" && read.reason === "too-large") {
+        return {
+            ok: false,
+            message: `scenario "${trimmed}" could not be read: ${refusalText(source, read)}.`,
+        };
+    }
+    if (read.status !== "read") {
         return { ok: false, message: `scenario "${trimmed}" could not be read (${source}).` };
     }
-    const text = scenarioBytes.toString("utf8");
+    const text = read.bytes.toString("utf8");
     let raw;
     try {
         raw = parseYaml(text);
@@ -92,11 +107,12 @@ function scenarioRefLooksLikePath(ref) {
         ref.includes("\\") ||
         ref.startsWith("."));
 }
-async function firstExistingFile(projectRoot, candidates) {
+/** The first candidate that is there, read or refused; null when none is. */
+async function firstScenarioFile(projectRoot, candidates) {
     for (const candidate of candidates) {
-        if ((await readContainedRegularFile(projectRoot, candidate)) !== null) {
-            return candidate;
-        }
+        const read = await readContainedRegularFile(projectRoot, candidate, PROJECT_FILE_MAX_BYTES);
+        if (read.status !== "missing")
+            return { candidate, read };
     }
     return null;
 }

package/dist/routes/scripted/session-result.js

@@ -2,7 +2,7 @@
 // path it names must be a safe path inside the run's artifact root. A result that fails is unsafe,
 // and the route stops without writing a bundle from it.
 import path from "node:path";
-import { readContainedRegularFile } from "../../run/contained-output.js";
+import { readContainedRegularFile, refusalText, RUN_ARTIFACT_MAX_BYTES, } from "../../run/contained-output.js";
 export class UnsafeScriptedSessionResultError extends Error {
     constructor(message) {
         super(message);
@@ -16,8 +16,11 @@ export async function existingScreenshots(runPaths, result) {
         if (!step.screenshotPath) {
             continue;
         }
-        const screenshot = await readContainedRegularFile(runPaths, step.screenshotPath);
-        if (screenshot && screenshot.byteLength > 0) {
+        const screenshot = await readContainedRegularFile(runPaths, step.screenshotPath, RUN_ARTIFACT_MAX_BYTES);
+        // A screenshot that is there and refused would leave the bundle without a frame it took.
+        if (screenshot.status === "refused")
+            throw new UnsafeScriptedSessionResultError(`Scripted session screenshot ${refusalText(step.screenshotPath, screenshot)}.`);
+        if (screenshot.status === "read" && screenshot.bytes.byteLength > 0) {
             existing.push(step.screenshotPath);
         }
     }

package/dist/routes/shared-world/bundle-records.js

@@ -6,7 +6,7 @@ import { participantEvent, participantRecord, participantStream, } from "../../r
 import { declaredScreenForRender } from "../../substrates/e2b/desktop-geometry.js";
 import { publicSafeRouteLabel } from "./provenance.js";
 import { participantCaption } from "../../run/participant-caption.js";
-import { sessionEndingInWords } from "../../run/outcomes.js";
+import { participantSummary } from "../../run/outcomes.js";
 function participantView(ctx, spec, index) {
     const { args, external } = ctx;
     const name = participantCaption({ id: spec.planned.id, personaId: spec.persona.id });
@@ -66,13 +66,7 @@ function sharedWorldSimulation(ctx, spec, index, view) {
         mode: "browser-sim",
         progress: inProgress ? 35 : 100,
         currentStep: view.reason,
-        summary: session
-            ? `${name} used the shared app and ${sessionEndingInWords(session.trace)}.`
-            : outcome?.sessionError !== undefined
-                ? `${name} did not finish a session: ${outcome.sessionError}`
-                : inProgress
-                    ? `${name} is using the shared app.`
-                    : `${name} would use the shared app; no session ran.`,
+        summary: participantSummary(name, { name: "the shared app" }, { trace: session?.trace, sessionError: outcome?.sessionError, inProgress }),
         startedAt: args.run.createdAt,
         updatedAt: args.run.createdAt,
     });

package/dist/routes/shared-world/participant-specs.d.ts

@@ -1,10 +1,8 @@
-import type { SharedWorldPlan } from "../../study/plan-types.js";
 import type { SharedWorldParticipant } from "../../study/plan-participants.js";
 import type { RunBundle } from "../../run/bundle.js";
 import type { DesktopParticipantRun, ParticipantRunOutcome } from "../computer-use/types.js";
 import { type DesktopParticipantDeps } from "../computer-use/participant-deps.js";
 import type { LiveParticipants, PlaneContext } from "./types.js";
-export declare function defaultSessionTimeoutMs(plan: SharedWorldPlan): number;
 /** Resolve an actor's participant URL against the harness-minted getHost base (entry is a
  *  same-origin relative path, validated at parse against serve.url). */
 export declare function resolveActorEntryUrl(baseUrl: string, entry: string | undefined): string;

package/dist/routes/shared-world/participant-specs.js

@@ -11,26 +11,7 @@ import { desktopParticipantDeps, } from "../computer-use/participant-deps.js";
 import { resolveCommittedPersonasForCwd } from "../../study/persona-resolve.js";
 import { participantAssignment } from "../../study/participant-assignment.js";
 import { redactText } from "../../evidence/redaction.js";
-import { MAX_SANDBOX_MS, SANDBOX_TIMEOUT_BUFFER_MS, SUBJECT_PROVISION_BUDGET_MS, } from "../../substrates/e2b/lifetime.js";
-import { DEFAULT_STATE_STEP_TIMEOUT_MS } from "../../subject/state.js";
-// The default per-participant session budget is derived from the route. On a provisioned route the
-// binding constraint is the subject sandbox (it must outlive every participant: timeoutMs +
-// provisioning + seeding + teardown buffer, and E2B refuses a sandbox over one hour), so the
-// derivation hands each participant the most that cap allows, capped at 15 minutes, floored at the
-// historical 300s so a seed-heavy study never gets less room than it always had. App-url
-// participants have no subject sandbox and default to 30 minutes (participant sandbox: 30m + 10m
-// buffer stays well under the hour). An explicit execution.timeoutMs is never adjusted. The handoff
-// latch scales off this (40%).
-const MAX_DERIVED_SESSION_MS = 15 * 60_000;
-const MIN_DERIVED_SESSION_MS = 300_000;
-const DEFAULT_APP_URL_SESSION_MS = 30 * 60_000;
-export function defaultSessionTimeoutMs(plan) {
-    if (plan.plane.kind !== "provisioned")
-        return DEFAULT_APP_URL_SESSION_MS;
-    const stateBudgetMs = (plan.plane.subject.state.seed ?? []).reduce((sum, step) => sum + (step.timeoutMs ?? DEFAULT_STATE_STEP_TIMEOUT_MS), 0);
-    const room = MAX_SANDBOX_MS - SUBJECT_PROVISION_BUDGET_MS - stateBudgetMs - SANDBOX_TIMEOUT_BUFFER_MS;
-    return Math.max(MIN_DERIVED_SESSION_MS, Math.min(MAX_DERIVED_SESSION_MS, room));
-}
+import { SANDBOX_TIMEOUT_BUFFER_MS } from "../../substrates/e2b/lifetime.js";
 // prose-check: model prompt (the participant model reads this, not a person)
 const DEFAULT_MISSION = "You are one of MANY users hitting a shared web application at the same time. The browser is already open at the app. Accomplish your role's task, then stop.";
 /** Resolve an actor's participant URL against the harness-minted getHost base (entry is a

package/dist/routes/shared-world/plan.d.ts

@@ -1,6 +1,7 @@
 import { type CuaActorDescriptor } from "../../actors/registry.js";
 import type { RoutePlanResult, RouteRefusal, SharedWorldPlan } from "../../study/plan-types.js";
 import type { StudyConfig, StudySubjectState } from "../../study/types.js";
+import { type SandboxCeiling } from "../../substrates/e2b/lifetime.js";
 import type { ConcurrentSharedWorldStudyErrorCode } from "./types.js";
 /** The error a shared-world study returns before a run starts. */
 export interface SharedWorldRefusal extends RouteRefusal<"shared-world", ConcurrentSharedWorldStudyErrorCode> {
@@ -18,6 +19,8 @@ export declare function planSharedWorldStudy(config: StudyConfig, input: {
     readonly dryRun: boolean;
     /** Whether deps.runSession is set: a caller's session runner cannot enforce maxOutputTokens. */
     readonly hasRunSession?: boolean;
+    /** The longest sandbox lifetime the operator's E2B plan allows (sandboxCeiling). */
+    readonly sandboxCeiling: SandboxCeiling;
 }): SharedWorldPlanResult;
 /** The provisioned plane's declared subject state. The external-public plane declares none. */
 export declare function planeStateOf(plan: SharedWorldPlan): StudySubjectState | undefined;

package/dist/routes/shared-world/plan.js

@@ -12,6 +12,8 @@ import { PUBLIC_TARGET_OWNER_PATTERN } from "../../study/parse/subject.js";
 import { REPO_SLUG_PATTERN } from "../../study/parse/values.js";
 import { concurrentSharedWorldValidationReason, desktopMediaValidationReason, externalPublicSharedWorldValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, taskProtocolValidationReason, } from "../../study/validation.js";
 import { unpricedCapCheck } from "../../study/requirements.js";
+import { DEFAULT_STATE_STEP_TIMEOUT_MS } from "../../subject/state.js";
+import { SANDBOX_TIMEOUT_BUFFER_MS, SUBJECT_PROVISION_BUDGET_MS, } from "../../substrates/e2b/lifetime.js";
 /** The registered descriptor for a planned actor; planSharedWorldStudy checked the registry. */
 export function sharedWorldDescriptorOf(actorType) {
     const descriptor = actorRegistry[actorType];
@@ -87,6 +89,9 @@ export function planSharedWorldStudy(config, input) {
     // subject.env on an app-url subject for the same reason.
     if (externalPublic && config.subject.env !== undefined)
         return refuse(invalid, "`subject.env` applies only to clone subjects or local-tree subjects (the served app's environment channel).", actor);
+    const ceiling = input.sandboxCeiling;
+    if (!ceiling.ok)
+        return refuse(invalid, ceiling.message, actor);
     const plane = planeOf(config);
     if (plane === undefined)
         throw new Error("shared-world validation admitted a plane it cannot plan");
@@ -105,9 +110,7 @@ export function planSharedWorldStudy(config, input) {
             actor,
             plane,
             concurrency: config.execution?.concurrency ?? plane.participants.length,
-            ...(config.execution?.timeoutMs === undefined
-                ? {}
-                : { sessionTimeoutMs: config.execution.timeoutMs }),
+            sessionTimeoutMs: config.execution?.timeoutMs ?? defaultSessionTimeoutMs(plane, ceiling.ms),
             brain,
             caps: planCaps(config),
             requirements: base.dryRun
@@ -128,6 +131,23 @@ export function planSharedWorldStudy(config, input) {
         },
     };
 }
+// The default per-participant session budget is derived from the plane. On a provisioned plane the
+// binding constraint is the subject sandbox (it must outlive every participant: timeoutMs +
+// provisioning + seeding + teardown buffer, under the sandbox ceiling), so the derivation hands each
+// participant the most the ceiling allows, capped at 15 minutes, floored at the historical 300s so
+// a seed-heavy study never gets less room than it always had. App-url participants have no subject
+// sandbox and default to 30 minutes (participant sandbox: 30m + 10m buffer stays under the hour).
+// An explicit execution.timeoutMs is never adjusted. The handoff latch scales off this (40%).
+const MAX_DERIVED_SESSION_MS = 15 * 60_000;
+const MIN_DERIVED_SESSION_MS = 300_000;
+const DEFAULT_APP_URL_SESSION_MS = 30 * 60_000;
+function defaultSessionTimeoutMs(plane, ceilingMs) {
+    if (plane.kind !== "provisioned")
+        return DEFAULT_APP_URL_SESSION_MS;
+    const stateBudgetMs = (plane.subject.state.seed ?? []).reduce((sum, step) => sum + (step.timeoutMs ?? DEFAULT_STATE_STEP_TIMEOUT_MS), 0);
+    const room = ceilingMs - SUBJECT_PROVISION_BUDGET_MS - stateBudgetMs - SANDBOX_TIMEOUT_BUFFER_MS;
+    return Math.max(MIN_DERIVED_SESSION_MS, Math.min(MAX_DERIVED_SESSION_MS, room));
+}
 /** The provisioned plane's declared subject state. The external-public plane declares none. */
 export function planeStateOf(plan) {
     return plan.plane.kind === "provisioned" ? plan.plane.subject.state : undefined;

package/dist/routes/shared-world/setup.js

@@ -9,7 +9,7 @@ import { prepareEmailReceiving, prepareExternalComms, receivingSourceOf, subject
 import { declaredOriginDigestOf } from "./external-public.js";
 import { packSubjectTree } from "./provisioned.js";
 import { emptyPlaneResults } from "./result.js";
-import { buildParticipantSpecs, defaultSessionTimeoutMs } from "./participant-specs.js";
+import { buildParticipantSpecs } from "./participant-specs.js";
 import { planeStateOf } from "./plan.js";
 import path from "node:path";
 import { e2bRequestTimeoutMs } from "../../substrates/e2b/lifetime.js";
@@ -87,7 +87,7 @@ export async function prepareConcurrentRun(study, scope) {
     const { run } = started;
     const { runId, createdAt, paths: runPaths, source } = run;
     const artifactRoot = runPaths.absoluteRunRoot;
-    const timeoutMs = plan.sessionTimeoutMs ?? defaultSessionTimeoutMs(plan);
+    const timeoutMs = plan.sessionTimeoutMs;
     const requestTimeoutMs = e2bRequestTimeoutMs(env);
     const redactScreenshots = plan.residual.policies?.redactScreenshots === true;
     const timers = deps.detachedTimers ?? {};

package/dist/routes/terminal/ledger.d.ts

@@ -1,21 +1,21 @@
-import type { ActorTokenUsage } from "../../actors/contract.js";
+import type { ActorTokenUsage, ActorTrace } from "../../actors/contract.js";
 import type { StudyCaps } from "../../study/types.js";
 import { type CostCategory } from "../../run/terminal-contract.js";
 import type { CostLine, NoSpendProof, TerminalCostLedger } from "./types.js";
 /**
  * Build the spend ledger from the captured session. The null discipline:
  *   - The `provider` line is populated from the actor trace's tokenUsage.costUsd when the trace
- *     carries it (a measured value, incl. a measured 0). When the trace carries no costUsd, the
- *     provider line is `null` = not measured (never guessed to 0 just because no-spend was intended).
+ *     carries it (a measured value, incl. a measured 0). Otherwise its `usd` is null = not
+ *     measured, and when the trace's `estimatedCost` prices the tokens, the line carries that
+ *     price as `estimatedUsd`: the figure run.json's model-tokens line gives, from the same
+ *     object. Tokens with no rate, and a run with no token count, say so in the note.
  *   - product/media/payment are `null` by default: core has no signal for those categories, and
  *     only a test can supply one, through `StudyDeps.costProbe`.
  * `injectedLines` lets a test supply known spend for a category,
  * exercising the fail-closed cap enforcement deterministically without a real billable run.
  */
 export declare function buildCostLedger(args: {
-    tokenCostUsd?: number;
-    /** Measured token counts, when the run produced them but no rate could price them. */
-    tokenUsage?: ActorTokenUsage;
+    trace: Pick<ActorTrace, "tokenUsage" | "estimatedCost">;
     injectedLines?: Partial<Record<CostCategory, CostLine>>;
 }): TerminalCostLedger;
 /** True when no cost line carries a dollar value, so a no-spend proof has nothing to stand on. */
@@ -26,9 +26,9 @@ export declare function noSpendLineMeasured(proof: Pick<NoSpendProof, "knownZero
  */
 export declare function noSpendNotEstablished(maxUsd: number): string;
 /**
- * What the ledger measured, in words: the dollar lines it knows, provider tokens it counted but
- * could not price, and the lines it has no signal for. A reader of a maxUsd=0 run must not take
- * an all-null ledger for a proven $0.
+ * What the ledger measured, in words: the dollar lines it knows, the provider tokens it counted
+ * with their estimate or as unpriced, and the lines it has no signal for. A reader of a maxUsd=0
+ * run must not take an all-null ledger for a proven $0.
  */
 export declare function describeMeasuredSpend(ledger: TerminalCostLedger, tokenUsage?: ActorTokenUsage): string;
 /** Derive the no-spend proof from the ledger. It vouches for known-zero lines and

package/dist/routes/terminal/ledger.js

@@ -4,48 +4,21 @@ import { COST_CATEGORIES } from "../../run/terminal-contract.js";
 /**
  * Build the spend ledger from the captured session. The null discipline:
  *   - The `provider` line is populated from the actor trace's tokenUsage.costUsd when the trace
- *     carries it (a measured value, incl. a measured 0). When the trace carries no costUsd, the
- *     provider line is `null` = not measured (never guessed to 0 just because no-spend was intended).
+ *     carries it (a measured value, incl. a measured 0). Otherwise its `usd` is null = not
+ *     measured, and when the trace's `estimatedCost` prices the tokens, the line carries that
+ *     price as `estimatedUsd`: the figure run.json's model-tokens line gives, from the same
+ *     object. Tokens with no rate, and a run with no token count, say so in the note.
  *   - product/media/payment are `null` by default: core has no signal for those categories, and
  *     only a test can supply one, through `StudyDeps.costProbe`.
  * `injectedLines` lets a test supply known spend for a category,
  * exercising the fail-closed cap enforcement deterministically without a real billable run.
  */
 export function buildCostLedger(args) {
-    const providerLine = typeof args.tokenCostUsd === "number"
-        ? {
-            usd: args.tokenCostUsd,
-            source: "provider-token-usage",
-            note: `Provider spend metered from the actor trace tokenUsage.costUsd (${args.tokenCostUsd} USD).`,
-        }
-        : args.tokenUsage
-            ? {
-                // Tokens counted, no rate to price them. This stays `usd: null` because a guessed
-                // dollar figure would be worse than none, but the note carries the measured fact so a
-                // reader never mistakes "no charge recorded" for "nothing was consumed".
-                usd: null,
-                source: "unpriced-token-usage",
-                note: `Provider spend unpriced: the run consumed ${describeTokenUsage(args.tokenUsage)}, ` +
-                    "but the terminal participant records the model as `codex` and humanish has no rate " +
-                    "for it, so no dollar figure is given. The token count is measured; the price is " +
-                    "not known. Recorded as null, never guessed as 0.",
-            }
-            : {
-                usd: null,
-                source: "unmeasured",
-                note: "Provider spend not measured: the actor trace carried no tokenUsage.costUsd in this run, so it is recorded as null and not guessed as 0.",
-            };
-    const unmeasured = (category) => ({
-        usd: null,
-        count: null,
-        source: "unmeasured",
-        note: `${category} spend not measured: humanish has no ${category} spend signal, and a study cannot supply one. Recorded as null, never guessed as 0.`,
-    });
     const lines = {
         product: args.injectedLines?.product ?? unmeasured("product"),
         media: args.injectedLines?.media ?? unmeasured("media"),
         payment: args.injectedLines?.payment ?? unmeasured("payment"),
-        provider: args.injectedLines?.provider ?? providerLine,
+        provider: args.injectedLines?.provider ?? providerLine(args.trace),
     };
     // knownTotalUsd sums only the non-null lines. A null line contributes nothing and is never
     // coerced to 0 (that would let an unmeasured category masquerade as a measured zero).
@@ -68,6 +41,51 @@ export function buildCostLedger(args) {
         fullyMeasured,
     };
 }
+function unmeasured(category) {
+    return {
+        usd: null,
+        count: null,
+        source: "unmeasured",
+        note: `${category} spend not measured: humanish has no ${category} spend signal, and a study cannot supply one. Recorded as null, never guessed as 0.`,
+    };
+}
+/** The participant's model tokens: a measured charge, an estimate, unpriced, or not counted. */
+function providerLine(trace) {
+    const { tokenUsage, estimatedCost } = trace;
+    if (typeof tokenUsage?.costUsd === "number")
+        return {
+            usd: tokenUsage.costUsd,
+            source: "provider-token-usage",
+            note: `Provider spend metered from the actor trace tokenUsage.costUsd (${tokenUsage.costUsd} USD).`,
+        };
+    if (tokenUsage === undefined)
+        return {
+            usd: null,
+            source: "unmeasured",
+            note: "Provider spend not measured: the actor trace carried no tokenUsage.costUsd in this run, so it is recorded as null and not guessed as 0.",
+        };
+    if (estimatedCost !== undefined && estimatedCost.estimatedCostUsd !== null)
+        return {
+            usd: null,
+            estimatedUsd: estimatedCost.estimatedCostUsd,
+            source: "estimated-token-usage",
+            note: `Provider spend estimated at ${estimatedCost.estimatedCostUsd} USD: the run consumed ` +
+                `${describeTokenUsage(tokenUsage)}, priced at ${estimatedCost.modelId ?? "the participant model's"} ` +
+                `rates as of ${estimatedCost.ratesAsOf}, as run.json's cost summary prices them. No provider ` +
+                "charge was measured, so usd stays null and caps.maxUsd does not count the estimate.",
+        };
+    // Tokens counted, no rate to price them. A guessed dollar figure would be worse than none, but
+    // the note carries the measured fact so a reader never mistakes "no charge recorded" for
+    // "nothing was consumed".
+    return {
+        usd: null,
+        source: "unpriced-token-usage",
+        note: `Provider spend unpriced: the run consumed ${describeTokenUsage(tokenUsage)}, but humanish ` +
+            `has no rate for ${estimatedCost?.modelId === undefined ? "the participant's model" : `the model ${estimatedCost.modelId}`}, ` +
+            "so no dollar figure is given. The token count is measured; the price is not known. " +
+            "Recorded as null, never guessed as 0.",
+    };
+}
 /** True when no cost line carries a dollar value, so a no-spend proof has nothing to stand on. */
 export function noSpendLineMeasured(proof) {
     return proof.knownZeroLines.length + proof.knownNonZeroLines.length === 0;
@@ -80,19 +98,24 @@ export function noSpendNotEstablished(maxUsd) {
     return `No-spend proof not established for maxUsd=${maxUsd}: no spend line was measured.`;
 }
 /**
- * What the ledger measured, in words: the dollar lines it knows, provider tokens it counted but
- * could not price, and the lines it has no signal for. A reader of a maxUsd=0 run must not take
- * an all-null ledger for a proven $0.
+ * What the ledger measured, in words: the dollar lines it knows, the provider tokens it counted
+ * with their estimate or as unpriced, and the lines it has no signal for. A reader of a maxUsd=0
+ * run must not take an all-null ledger for a proven $0.
  */
 export function describeMeasuredSpend(ledger, tokenUsage) {
     const measured = COST_CATEGORIES.filter((c) => ledger.lines[c].usd !== null).map((c) => `${c} ${ledger.lines[c].usd} USD`);
-    const unpricedProvider = ledger.lines.provider.source === "unpriced-token-usage";
-    const unmeasured = COST_CATEGORIES.filter((c) => ledger.lines[c].usd === null && !(c === "provider" && unpricedProvider));
+    const provider = ledger.lines.provider;
+    const countedProvider = provider.usd === null &&
+        (provider.source === "unpriced-token-usage" || provider.source === "estimated-token-usage");
+    const unmeasured = COST_CATEGORIES.filter((c) => ledger.lines[c].usd === null && !(c === "provider" && countedProvider));
+    const counts = tokenUsage === undefined ? "" : ` (${describeTokenUsage(tokenUsage)})`;
     return [
         measured.length > 0 ? `Measured: ${measured.join(", ")}.` : "",
-        unpricedProvider
-            ? `Provider tokens were consumed${tokenUsage === undefined ? "" : ` (${describeTokenUsage(tokenUsage)})`} and are unpriced, not zero.`
-            : "",
+        !countedProvider
+            ? ""
+            : provider.estimatedUsd === undefined
+                ? `Provider tokens were consumed${counts} and are unpriced, not zero.`
+                : `Provider tokens${counts} are estimated at ${provider.estimatedUsd} USD, the participant's model cost, which caps.maxUsd does not count.`,
         unmeasured.length > 0 ? `Not measured (null, not claimed zero): ${unmeasured.join(", ")}.` : "",
     ]
         .filter((part) => part.length > 0)

package/dist/routes/terminal/live-finish.js

@@ -81,17 +81,13 @@ async function settleLiveLedgers(inputs, trace, normalizedTranscript) {
     const { recordLifecycle, lifecycle, commandLog, interventions, terminalEvents } = inputs.recorder;
     // --- Spend ledger + no-spend proof + full caps enforcement (fail-closed). ---
     // The cost ledger is derived, with the null discipline: provider spend from the trace's
-    // tokenUsage.costUsd when present (else null = not measured), product/media/payment null by
-    // default (core has no signal). The costProbe hook lets tests inject known
-    // spend to exercise the fail-closed cap without a real billable run.
+    // tokenUsage.costUsd when present, else null with the trace's token estimate beside it, and
+    // product/media/payment null by default (core has no signal). The costProbe hook lets tests
+    // inject known spend to exercise the fail-closed cap without a real billable run.
     const injectedLines = costProbe?.(trace.tokenUsage?.costUsd === undefined ? {} : { tokenCostUsd: trace.tokenUsage.costUsd });
     if (costProbe)
         await validatePreparedRunArtifactPaths(runPaths);
-    const cost = buildCostLedger({
-        ...(trace.tokenUsage?.costUsd === undefined ? {} : { tokenCostUsd: trace.tokenUsage.costUsd }),
-        ...(trace.tokenUsage === undefined ? {} : { tokenUsage: trace.tokenUsage }),
-        ...(injectedLines ? { injectedLines } : {}),
-    });
+    const cost = buildCostLedger({ trace, ...(injectedLines ? { injectedLines } : {}) });
     const noSpendProof = buildNoSpendProof(cost, maxUsd ?? null, trace.tokenUsage);
     const proofVerdict = !noSpendProof.satisfied
         ? `No-spend proof not satisfied for maxUsd=${maxUsd ?? "null"}.`
@@ -138,8 +134,9 @@ export async function finishLiveTerminalSession(inputs) {
     const participant = terminalParticipantFacts(trace, session.error);
     const judgment = judgeTerminal({ dryRun: false, participant });
     // The run cost summary, as the computer-use route records it: the sandbox's compute time from
-    // its span and observed size, and the participant's tokens (unpriced for Codex). It is not part
-    // of the cap ledger above, whose lines sum against caps.maxUsd.
+    // its span and observed size, and the participant's tokens at trace.estimatedCost, the price the
+    // ledger's provider line also carries. It is not part of the cap ledger above, whose lines sum
+    // against caps.maxUsd.
     const desktops = session.runCostDesktops();
     const runCost = buildRunCostSummary({
         participants: [{ trace }],

package/dist/routes/terminal/plan.d.ts

@@ -1,5 +1,6 @@
 import type { RoutePlanResult, RouteRefusal, TerminalPlan } from "../../study/plan-types.js";
 import type { StudyConfig } from "../../study/types.js";
+import { type SandboxCeiling } from "../../substrates/e2b/lifetime.js";
 import { type TerminalProductStudyResult } from "./types.js";
 /** The error a terminal study returns before a run starts. `actor` names the registered actor. */
 export interface TerminalRefusal extends RouteRefusal<"terminal", NonNullable<TerminalProductStudyResult["error"]>["code"]> {
@@ -14,4 +15,6 @@ export declare function planTerminalStudy(config: StudyConfig, input: {
     readonly dryRun: boolean;
     /** A test's costProbe can measure spend lines, so a positive maxUsd can trip. */
     readonly hasCostProbe?: boolean;
+    /** The longest sandbox lifetime the operator's E2B plan allows (sandboxCeiling). */
+    readonly sandboxCeiling: SandboxCeiling;
 }): TerminalPlanResult;