humanish 0.115.0 → 0.117.0

package/dist/routes/computer-use/single-bundle.js

@@ -2,7 +2,7 @@ import { participantAssignment } from "../../study/participant-assignment.js";
 import { redactText } from "../../evidence/redaction.js";
 import { REVIEW_SCHEMA, bundleArtifacts, bundleHead, } from "../../run/bundle.js";
 import {} from "../../run/streams.js";
-import { aggregateTaskFunnels, formatParticipantOutcomes, formatRunTaskFunnel, sessionEndingInWords, withCuaReviewProvenance, } from "../../run/outcomes.js";
+import { aggregateTaskFunnels, formatParticipantOutcomes, formatRunTaskFunnel, participantSummary, withCuaReviewProvenance, } from "../../run/outcomes.js";
 import { participantCaption } from "../../run/participant-caption.js";
 import { actorEnding } from "../../actors/stop-cause.js";
 import { describeSubjectState, phaseEventIdSuffix, publicSafeAppUrlLabel, subjectProvenanceMessage, } from "./bundle-parts.js";
@@ -103,13 +103,11 @@ function singleSimulation(args, view) {
         mode: "browser-sim",
         progress: args.inProgress === true ? 20 : 100,
         currentStep: reason,
-        summary: args.session
-            ? `${name} used the app ${browserPlace(args)}, and ${sessionEndingInWords(args.session.trace)}.`
-            : args.inProgress === true
-                ? `${name} is using the app ${browserPlace(args)}.`
-                : args.sessionError !== undefined
-                    ? `${name} did not finish a session: ${args.sessionError}`
-                    : `${name} would use ${publicAppUrl}; no session ran.`,
+        summary: participantSummary(name, { name: "the app", place: browserPlace(args), target: publicAppUrl }, {
+            trace: args.session?.trace,
+            sessionError: args.sessionError,
+            inProgress: args.inProgress === true,
+        }),
         startedAt: args.run.createdAt,
         updatedAt: args.run.createdAt,
     });
@@ -183,6 +181,7 @@ function singleStream(args, view) {
 }
 function singleEvents(args, view) {
     const { publicAppUrl, desktopGeometry } = view;
+    const { subject } = args;
     const events = [
         {
             id: "event-000-created",
@@ -191,30 +190,32 @@ function singleEvents(args, view) {
             type: "cua-lab.run.created",
             message: `Created a computer-use run for ${args.studyId} (actor ${args.actorId}).`,
         },
-        args.subjectProvenance
+        subject.source === "clone" || subject.source === "local-tree"
             ? participantEvent(SINGLE, {
                 id: "event-001-subject",
                 at: args.run.createdAt,
                 level: "info",
                 type: "cua-lab.subject.provenance",
                 // Claim "cloned/packed and served" only when it actually happened.
-                message: `${subjectProvenanceMessage(args.subjectProvenance, publicAppUrl, args.dryRun, args.session !== undefined)} (subject env names: ${args.subjectProvenance.envNames.length > 0 ? args.subjectProvenance.envNames.join(", ") : "none"}; values never persisted); state: ${describeSubjectState(args.subjectProvenance.state, args.dryRun)}.`,
+                message: `${subjectProvenanceMessage(subject, publicAppUrl, args.dryRun, args.session !== undefined)} (subject env names: ${subject.envNames !== undefined && subject.envNames.length > 0 ? subject.envNames.join(", ") : "none"}; values never persisted); state: ${describeSubjectState(subject.state, args.dryRun)}.`,
             })
             : participantEvent(SINGLE, {
                 id: "event-001-subject",
                 at: args.run.createdAt,
                 level: "info",
                 type: "cua-lab.subject.declared",
-                // Declare what the subject was, including the absence of a pin. A
-                // local-app / in-process subject is an already-running local dev server the caller
-                // provisioned; it cannot be commit-pinned, so its provenance is unpinned and
-                // no E2B desktop was created. A plain app-url entry runs inside the desktop sandbox, or,
-                // on the local VM, reaches the host's loopback from the VM's browser.
-                message: args.entryKind === "local-app"
-                    ? `Subject app declared at ${publicAppUrl}: a running local dev server driven in this process, with no clone and no E2B desktop. Provenance: provided by the caller and unpinned, because a running dev server has no commit to pin.`
-                    : runnerSubstrate(args) === "local-desktop"
-                        ? `Subject app declared at ${publicAppUrl} (the host's loopback, opened from a browser on a local VM).`
-                        : `Subject app declared at ${publicAppUrl} (loopback inside the desktop sandbox).`,
+                // Declare what the subject was, including the absence of a pin. A desktop-cli product
+                // is named, since it has no URL. A local-app / in-process subject is an already-running
+                // local dev server the caller provisioned; it cannot be commit-pinned, so its provenance
+                // is unpinned and no E2B desktop was created. A plain app-url entry runs inside the
+                // desktop sandbox, or, on the local VM, reaches the host's loopback from the VM's browser.
+                message: subject.source === "desktop-cli"
+                    ? `Subject product declared: ${subject.product}, used from a terminal window inside the desktop sandbox.`
+                    : args.entryKind === "local-app"
+                        ? `Subject app declared at ${publicAppUrl}: a running local dev server driven in this process, with no clone and no E2B desktop. Provenance: provided by the caller and unpinned, because a running dev server has no commit to pin.`
+                        : runnerSubstrate(args) === "local-desktop"
+                            ? `Subject app declared at ${publicAppUrl} (the host's loopback, opened from a browser on a local VM).`
+                            : `Subject app declared at ${publicAppUrl} (loopback inside the desktop sandbox).`,
             }),
         args.session
             ? participantEvent(SINGLE, {
@@ -428,11 +429,7 @@ export function buildSingleParticipantBundle(args) {
         ...(args.providerResources === undefined || args.providerResources.length === 0
             ? {}
             : { providerResources: args.providerResources }),
-        // Structured subject provenance: code pin + state story. Uniform, and
-        // stated on app-url bundles too: the caller minted the URL, its state is the caller's.
-        // CuaSubjectProvenanceArg's two variants (clone, local-tree) are already RunSubjectProvenance-
-        // shaped, so no reconstruction is needed beyond the app-url fallback.
-        subject: args.subjectProvenance ?? { source: "app-url", state: { provenance: "undeclared" } },
+        subject: args.subject,
         ...(cost === undefined ? {} : { cost }),
     };
 }

package/dist/routes/computer-use/subject-projection.d.ts

@@ -2,7 +2,7 @@ import type { ComputerUsePlan } from "../../study/plan-types.js";
 import type { StudySubjectState } from "../../study/types.js";
 import { type RunSubjectProvenance, type RunSubjectStateStepRecord } from "../../run/bundle.js";
 import { type LocalTreeArchive } from "../../subject/local-tree-archive.js";
-import { type DesktopParticipantRun, type CuaSubjectProjection, type CuaSubjectProvenanceArg, type ParticipantRunOutcome } from "./types.js";
+import { type DesktopParticipantRun, type ParticipantRunOutcome } from "./types.js";
 /**
  * Each participant's subject projection. A participant's outcome adds the subject commit it resolved and the
  * state steps it executed; without outcomes (dry run, or a run still in progress) the declared
@@ -15,7 +15,7 @@ export declare function projectParticipantSubjects(args: {
     runs: readonly DesktopParticipantRun[];
     outcomes: readonly ParticipantRunOutcome[] | undefined;
     dryRun: boolean;
-}): CuaSubjectProjection[];
+}): RunSubjectProvenance[];
 /**
  * Resolve the bundle's state marker from the declaration and what actually ran.
  * Precedence: external declared → "unpinned" (seed records, if any, stay attached; a
@@ -28,10 +28,6 @@ export declare function resolveSubjectState(args: {
     dryRun: boolean;
     executed: RunSubjectStateStepRecord[];
 }): RunSubjectProvenance["state"];
-/** 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 declare function subjectProvenanceArg(subject: CuaSubjectProjection, publicRepo: string | undefined, subjectEnvNames: string[]): CuaSubjectProvenanceArg | undefined;
 /**
  * The run-level subject for the top level and the bundle. Local-tree participants all pack from the
  * same once-per-run archive, so every participant already carries the identical archiveSha256/commit/dirty and
@@ -39,11 +35,11 @@ export declare function subjectProvenanceArg(subject: CuaSubjectProjection, publ
  * commit; the aggregate carries it only when every participant agrees, and warns when they diverge.
  */
 export declare function aggregateCuaSubject(args: {
-    subjects: readonly CuaSubjectProjection[];
+    subjects: readonly RunSubjectProvenance[];
     outcomes: readonly ParticipantRunOutcome[] | undefined;
     participantCount: number;
     dryRun: boolean;
 }): {
-    subject: CuaSubjectProjection;
+    subject: RunSubjectProvenance;
     warnings: string[];
 };

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;
@@ -185,44 +185,7 @@ export interface CuaParticipantSummary {
     concurrency: number;
     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 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_SUBJECT_BUILD_FAILED" | "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";
 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

@@ -10,8 +10,10 @@ import { brainOf, planCaps, desktopRequirements, isNonEmpty, planBase, } from ".
 import { sharedWorldParticipants } from "../../study/plan-participants.js";
 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 { concurrentSharedWorldValidationReason, desktopMediaValidationReason, externalPublicSharedWorldValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, taskProtocolValidationReason, waitLimitValidationReason, } 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];
@@ -53,6 +55,7 @@ export function planSharedWorldStudy(config, input) {
     // A library caller's config skips the parser, which refuses these first.
     studyUrlCredentialReason(config) ??
         outputTokenLimitValidationReason(config) ??
+        waitLimitValidationReason(config) ??
         (externalPublic
             ? externalPublicSharedWorldValidationReason(config)
             : concurrentSharedWorldValidationReason(config));
@@ -87,6 +90,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 +111,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 +132,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