humanish 0.110.3 → 0.111.0

package/dist/routes/scripted/route.js

@@ -6,7 +6,7 @@
 //
 // Spend: scripted steps make no model requests, and their traces record zero token usage. A local
 // app-url run spends no sandbox minutes; a live clone run spends E2B minutes to clone and serve the
-// subject. `scenario.mode: live` is required anyway, because a live run actuates a real browser
+// subject. `mode: live` is required anyway, because a live run actuates a real browser
 // against a real app (it fills forms and clicks buttons). A dry run parses and digest-pins the
 // scenario and writes the contract bundle without touching anything.
 //
@@ -31,6 +31,7 @@ import { ScriptedSubject } from "./subject.js";
 import { runScriptedSessions, writeSurfaceTraces } from "./surface-sessions.js";
 import {} from "./types.js";
 import { studyResultIdentity } from "../../run/study-result.js";
+import { actorOf } from "../../study/study-fields.js";
 /**
  * A refused scripted study's result, at the refusal's stage: a before-scope refusal has its own field
  * order and no analysis record; the others come after the output directory checks.
@@ -38,7 +39,7 @@ import { studyResultIdentity } from "../../run/study-result.js";
 export async function scriptedStudyRefusal(options, refusal) {
     const { config, dryRun } = options;
     const cwd = path.resolve(options.cwd);
-    const actorType = config.actors[0]?.type ?? "";
+    const actorType = actorOf(config)?.type ?? "";
     if (refusal.beforeScope)
         return {
             ...studyResultIdentity("scripted", config.id),
@@ -94,6 +95,8 @@ async function runScriptedPlanInScope(plan, input, scope) {
         mintRunId: makeScriptedRunId,
         mode: dryRun ? "dry-run" : "live",
         study: plan.study,
+        // Only a clone subject is served from a sandbox; an app-url run drives a local browser.
+        sandboxes: setup.clone ? undefined : "none",
         renderReview: renderScriptedReviewMarkdown,
         observer: { open: input.open === true, render: setup.deps.renderObserver },
     });
@@ -144,6 +147,7 @@ async function runScriptedPlanInScope(plan, input, scope) {
                 deps: setup.deps,
                 browserCommand: setup.browserCommand,
                 runPaths,
+                onSessionStart: () => run.participantStarted(),
             });
         }
         catch (error) {

package/dist/routes/scripted/scenario.d.ts

@@ -8,7 +8,7 @@ interface ResolvedScriptedScenario {
     sourceDigest: string;
 }
 /**
- * Resolve and consume `scenario.ref`. Path-style refs (contain a separator or end .yaml/.yml)
+ * Resolve and consume `scenario`. Path-style refs (contain a separator or end .yaml/.yml)
  * resolve against cwd and are clamped inside it: a ../../ escape is rejected, never recorded
  * as repo-relative provenance. Id-style refs must be public-safe tokens and resolve to
  * humanish/scenarios/<ref>.yaml (then .yml). Every failure mode is fail-closed. planScriptedStudy

package/dist/routes/scripted/scenario.js

@@ -1,4 +1,4 @@
-// Resolve a scripted-browser study's `scenario.ref` to a committed scenario file and parse its
+// Resolve a scripted-browser study's `scenario` to a committed scenario file and parse its
 // `browser.steps` into the journey the actor runs. The ref is an id or a repo-relative path that must
 // stay inside the project; provenance records it repo-relative with the scenario's digest.
 import { parse as parseYaml } from "yaml";
@@ -6,11 +6,11 @@ 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";
-// Same public-safe token shape the study id uses; an id-style scenario.ref must match it before
+// 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_.-]*$/;
 /**
- * Resolve and consume `scenario.ref`. Path-style refs (contain a separator or end .yaml/.yml)
+ * Resolve and consume `scenario`. Path-style refs (contain a separator or end .yaml/.yml)
  * resolve against cwd and are clamped inside it: a ../../ escape is rejected, never recorded
  * as repo-relative provenance. Id-style refs must be public-safe tokens and resolve to
  * humanish/scenarios/<ref>.yaml (then .yml). Every failure mode is fail-closed. planScriptedStudy

package/dist/routes/scripted/surface-sessions.d.ts

@@ -8,6 +8,8 @@ export declare function runScriptedSessions(session: Required<Pick<ScriptedBrows
     deps: StudyDeps;
     browserCommand: string | undefined;
     runPaths: PreparedRunArtifactPaths;
+    /** Called as each surface's session starts, before it can throw or return. */
+    onSessionStart: () => void;
 }): Promise<ScriptedBrowserSessionResult[]>;
 /** Writes each surface's actor-<surface>.json, as the computer-use route writes actor.json. */
 export declare function writeSurfaceTraces(runPaths: PreparedRunArtifactPaths, results: readonly ScriptedBrowserSessionResult[]): Promise<void>;

package/dist/routes/scripted/surface-sessions.js

@@ -7,9 +7,10 @@ import { validateScriptedSessionResult } from "./session-result.js";
 /** One session per surface, in parallel. */
 export function runScriptedSessions(session, run) {
     const { appUrl, evidenceAppUrl, urlPolicy, journey, persona, timeoutMs, artifactRoot } = session;
-    const { surfaces, deps, browserCommand, runPaths } = run;
+    const { surfaces, deps, browserCommand, runPaths, onSessionStart } = run;
     const runSession = deps.runScriptedSession;
     return Promise.all(surfaces.map((surface) => {
+        onSessionStart();
         const sessionOptions = {
             appUrl,
             evidenceAppUrl,

package/dist/routes/scripted/types.d.ts

@@ -47,7 +47,7 @@ export interface ScriptedBrowserStudyResult extends AutomaticAnalysisResult, Stu
         killed: boolean;
     };
     hostDigest?: string;
-    /** The consumed scenario.ref: digest-pinned provenance of the executable steps. */
+    /** The consumed `scenario`: digest-pinned provenance of the executable steps. */
     scenario?: {
         id: string;
         source: string;
@@ -58,7 +58,7 @@ export interface ScriptedBrowserStudyResult extends AutomaticAnalysisResult, Stu
     observer?: ObserverResult;
     warnings: string[];
     error?: {
-        code: "HUMANISH_STUDY_ANALYSIS_INVALID" | "HUMANISH_STUDY_TASKS_UNSUPPORTED" | "HUMANISH_STUDY_OPTION_UNSUPPORTED" | "HUMANISH_STUDY_V2_UNSUPPORTED" | "HUMANISH_SCRIPTED_FAILED" | "HUMANISH_SCRIPTED_ACTOR_UNSUPPORTED" | "HUMANISH_SCRIPTED_SCENARIO_INVALID" | "HUMANISH_SCRIPTED_SUBJECT_UNSAFE" | "HUMANISH_SCRIPTED_BROWSER_MISSING" | "HUMANISH_SCRIPTED_KEYS_MISSING" | "HUMANISH_SCRIPTED_SUBJECT_ENV_MISSING" | "HUMANISH_SCRIPTED_GETHOST_UNAVAILABLE" | "HUMANISH_RUN_ID_IN_USE";
+        code: "HUMANISH_STUDY_ANALYSIS_INVALID" | "HUMANISH_STUDY_TASKS_UNSUPPORTED" | "HUMANISH_STUDY_OPTION_UNSUPPORTED" | "HUMANISH_STUDY_V2_UNSUPPORTED" | "HUMANISH_STUDY_INVALID" | "HUMANISH_SCRIPTED_FAILED" | "HUMANISH_SCRIPTED_ACTOR_UNSUPPORTED" | "HUMANISH_SCRIPTED_SCENARIO_INVALID" | "HUMANISH_SCRIPTED_SUBJECT_UNSAFE" | "HUMANISH_SCRIPTED_BROWSER_MISSING" | "HUMANISH_SCRIPTED_KEYS_MISSING" | "HUMANISH_SCRIPTED_SUBJECT_ENV_MISSING" | "HUMANISH_SCRIPTED_GETHOST_UNAVAILABLE" | "HUMANISH_RUN_ID_IN_USE";
         message: string;
     };
 }

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

@@ -30,7 +30,7 @@ const HANDOFF_DEADLINE_BUDGET_FRACTION = 0.4;
 // convergence proof): at most this many single-frame reads before the participant is assumed to be
 // somewhere without a code. Each reader stops the instant it has what it needs, so in practice only
 // a handful fire (a participant reaches its /lobby within a few turns). NOTE: these reads are
-// out-of-band OpenAI calls (external-public route only) and are left out of execution.caps.maxUsd,
+// out-of-band OpenAI calls (external-public route only) and are left out of caps.maxUsd,
 // so this hard cap is what bounds their spend (each read is one cheap single-frame OCR call). If
 // this route ever runs under a strict budget, fold the estimate in.
 const MAX_LOBBY_CODE_VISION_READS = 30;

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

@@ -167,7 +167,11 @@ export function participantRunDeps(ctx, live, scrubKnownValues) {
         studyCwd: ctx.cwd,
         redactScreenshots: ctx.redactScreenshots,
         scrubKnownValues,
-        runSession: ctx.runSession,
+        // A session that throws returns no trace; the run still records that it started.
+        runSession: (options) => {
+            ctx.run.participantStarted();
+            return ctx.runSession(options);
+        },
         // A local-agent brain runs each participant on the operator's signed-in agent, as on computer
         // use.
         brain: ctx.plan.brain,
@@ -196,7 +200,7 @@ export function participantRunDeps(ctx, live, scrubKnownValues) {
  * scrubbed of the run's known secret values.
  */
 export async function buildParticipantSpecs(participants, cwd, scrubKnownValues) {
-    // Only the personas the participants use: an actors[0].persona that every participant overrides
+    // Only the personas the participants use: an actor.persona that every participant overrides
     // is never applied, so it is not read.
     const personaResolution = await resolveCommittedPersonasForCwd(cwd, participants.map((participant) => participant.personaId));
     const actorSpecs = participants.map((participant) => buildActorSpec(participant, personaResolution.personas));

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

@@ -6,12 +6,13 @@ import { DEFAULT_OPENAI_CU_MODEL } from "../../actors/computer-use/openai-provid
 import { studyUrlCredentialReason } from "../../study/url-credentials.js";
 import { actorRegistry, isCuaActorDescriptor, } from "../../actors/registry.js";
 import { resolveAutomaticAnalysis } from "../../analysis/automatic-config.js";
-import { brainOf, capsOf, desktopRequirements, isNonEmpty, planBase, } from "../../study/plan-base.js";
+import { brainOf, planCaps, desktopRequirements, isNonEmpty, planBase, } from "../../study/plan-base.js";
 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, scenarioCapsValidationReason, taskProtocolValidationReason, } from "../../study/validation.js";
+import { concurrentSharedWorldValidationReason, desktopMediaValidationReason, externalPublicSharedWorldValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, taskProtocolValidationReason, } from "../../study/validation.js";
 import { MODEL_RATES, unpricedCapMessage } from "../../run/pricing.js";
+import { actorOf, capsOf } from "../../study/study-fields.js";
 /** The registered descriptor for a planned actor; planSharedWorldStudy checked the registry. */
 export function sharedWorldDescriptorOf(actorType) {
     const descriptor = actorRegistry[actorType];
@@ -38,7 +39,7 @@ export function planSharedWorldStudy(config, input) {
     const tasksReason = taskProtocolValidationReason(config, false);
     if (tasksReason)
         return refuse("HUMANISH_STUDY_TASKS_UNSUPPORTED", tasksReason);
-    const actorType = config.actors[0]?.type ?? "";
+    const actorType = actorOf(config)?.type ?? "";
     const descriptor = actorRegistry[actorType];
     if (!descriptor || !isCuaActorDescriptor(descriptor))
         return refuse("HUMANISH_SHARED_WORLD_ACTOR_UNSUPPORTED", `actor.type "${actorType}" is not a registered computer-use actor.`);
@@ -53,17 +54,16 @@ export function planSharedWorldStudy(config, input) {
     // A library caller's config skips the parser, which refuses these first.
     studyUrlCredentialReason(config) ??
         outputTokenLimitValidationReason(config) ??
-        scenarioCapsValidationReason(config) ??
         (externalPublic
             ? externalPublicSharedWorldValidationReason(config)
             : concurrentSharedWorldValidationReason(config));
     if (invalidReason)
         return refuse(invalid, invalidReason, actor);
-    if (config.actors[0]?.maxOutputTokens !== undefined && input.hasRunSession === true)
+    if (actorOf(config)?.maxOutputTokens !== undefined && input.hasRunSession === true)
         return refuse(invalid, "maxOutputTokens cannot be enforced by a custom runSession.", actor);
-    const caps = config.execution?.caps;
+    const caps = capsOf(config);
     if (!input.dryRun && (caps?.maxUsd !== undefined || caps?.maxTotalUsd !== undefined)) {
-        const model = (config.actors[0]?.model ?? DEFAULT_OPENAI_CU_MODEL).trim().toLowerCase();
+        const model = (actorOf(config)?.model ?? DEFAULT_OPENAI_CU_MODEL).trim().toLowerCase();
         if (!MODEL_RATES[model])
             return refuse("HUMANISH_SHARED_WORLD_UNPRICED_CAP", unpricedCapMessage(model), actor);
     }
@@ -106,7 +106,7 @@ export function planSharedWorldStudy(config, input) {
                 ? {}
                 : { sessionTimeoutMs: config.execution.timeoutMs }),
             brain,
-            caps: capsOf(config),
+            caps: planCaps(config),
             requirements: base.dryRun
                 ? []
                 : [

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

@@ -48,7 +48,7 @@ import { prepareConcurrentRun } from "./setup.js";
 import { browserRouteScorer } from "../../study/adapter-scorer-loader.js";
 import { withLateScorer } from "../../study/route-inputs.js";
 import {} from "./types.js";
-import { rosterOf } from "../../study/parse/actors.js";
+import { actorOf, participantList } from "../../study/study-fields.js";
 /** The shared-world code for each local-agent refusal, kind for kind with computer-use. */
 const LOCAL_AGENT_REFUSAL_CODES = {
     "agent-missing": "HUMANISH_SHARED_WORLD_AGENT_MISSING",
@@ -59,11 +59,11 @@ const LOCAL_AGENT_REFUSAL_CODES = {
 /** A refused shared-world study's result: the route's envelope, and a refusal's analysis record. */
 export function sharedWorldStudyRefusal(options, refusal) {
     const { config, dryRun } = options;
-    const declared = rosterOf(config.actors[0]) ?? [];
+    const declared = participantList(config) ?? [];
     const fail = concurrentStudyFailure({
         cwd: path.resolve(options.cwd),
         studyId: config.id,
-        actor: config.actors[0]?.type ?? "",
+        actor: actorOf(config)?.type ?? "",
         participantCount: declared.length,
         // The parser fills concurrency for multi-participant studies, so this fallback serves only
         // library callers: every declared participant runs at once unless the author declared a cap.

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

@@ -54,7 +54,7 @@ export interface SharedWorldRunInput {
      *  core-stamped onto the bundle as evidence. Absent for library callers. */
     scorerProvenance?: RunScorerProvenance;
 }
-export type ConcurrentSharedWorldStudyErrorCode = "HUMANISH_STUDY_ANALYSIS_INVALID" | "HUMANISH_STUDY_TASKS_UNSUPPORTED" | "HUMANISH_STUDY_OPTION_UNSUPPORTED" | "HUMANISH_STUDY_V2_UNSUPPORTED" | "HUMANISH_SHARED_WORLD_FAILED" | "HUMANISH_SHARED_WORLD_ACTOR_UNSUPPORTED" | "HUMANISH_SHARED_WORLD_INVALID" | "HUMANISH_SHARED_WORLD_KEYS_MISSING"
+export type ConcurrentSharedWorldStudyErrorCode = "HUMANISH_STUDY_ANALYSIS_INVALID" | "HUMANISH_STUDY_TASKS_UNSUPPORTED" | "HUMANISH_STUDY_OPTION_UNSUPPORTED" | "HUMANISH_STUDY_V2_UNSUPPORTED" | "HUMANISH_STUDY_INVALID" | "HUMANISH_SHARED_WORLD_FAILED" | "HUMANISH_SHARED_WORLD_ACTOR_UNSUPPORTED" | "HUMANISH_SHARED_WORLD_INVALID" | "HUMANISH_SHARED_WORLD_KEYS_MISSING"
 /** A local-agent brain's CLI is not on `PATH`. */
  | "HUMANISH_SHARED_WORLD_AGENT_MISSING"
 /** A local-agent brain's CLI is signed out, or could not report its sign-in status. */

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

@@ -1,5 +1,5 @@
 import type { ActorPersonaRef, ActorTrace } from "../../actors/contract.js";
-import type { StudyScenarioCaps, StudyRuntimeAuth } from "../../study/types.js";
+import type { StudyCaps, StudyRuntimeAuth } from "../../study/types.js";
 import { type RunBundle, type RunCostSummary, type BundleRun } from "../../run/bundle.js";
 import { type Verdict } from "../../run/judge.js";
 import type { TerminalLedgers } from "./types.js";
@@ -21,7 +21,7 @@ export declare function buildTerminalProductBundle(args: {
     persona: ActorPersonaRef;
     productName: string;
     publicSurfaces: string[];
-    caps?: StudyScenarioCaps;
+    caps?: StudyCaps;
     runtimeAuth?: string;
     stdin: "disabled" | "planned" | "sent";
     policies: {
@@ -51,7 +51,7 @@ export declare function buildLiveTerminalProductBundle(args: {
     persona: ActorPersonaRef;
     productName: string;
     publicSurfaces: string[];
-    caps?: StudyScenarioCaps;
+    caps?: StudyCaps;
     runtimeAuthKeyName: string;
     runtimeAuth?: StudyRuntimeAuth;
     policies: {

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

@@ -1,5 +1,5 @@
 import type { ActorTokenUsage } from "../../actors/contract.js";
-import type { StudyScenarioCaps } from "../../study/types.js";
+import type { StudyCaps } from "../../study/types.js";
 import { type CostCategory } from "../../run/terminal-contract.js";
 import type { CostLine, NoSpendProof, TerminalCostLedger } from "./types.js";
 /**
@@ -41,7 +41,7 @@ export declare function buildNoSpendProof(ledger: TerminalCostLedger, maxUsd: nu
  * grant a green pass: the no-spend proof reports them as unmeasured. maxMinutes is wall-clock and is
  * enforced separately (runWithWallClock); it is not a ledger-derived cap.
  */
-export declare function evaluateCapsAgainstLedger(ledger: TerminalCostLedger, caps: StudyScenarioCaps): {
+export declare function evaluateCapsAgainstLedger(ledger: TerminalCostLedger, caps: StudyCaps): {
     ok: true;
 } | {
     ok: false;

package/dist/routes/terminal/lifetime.js

@@ -1,5 +1,5 @@
 // How long a live terminal sandbox may live. Its server-side timeout has to cover everything that
-// runs in it before the codex command, the command's own wall clock (scenario.caps.maxMinutes) and
+// runs in it before the codex command, the command's own wall clock (caps.maxMinutes) and
 // the reclamation buffer after that clock's kill. A timeout shorter than that lets E2B kill the
 // sandbox before the command's deadline and before the evidence is read.
 import { NODE_BOOTSTRAP_TIMEOUT_MS } from "../../subject/node-bootstrap.js";

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

@@ -117,7 +117,7 @@ export async function finishLiveTerminalSession(inputs) {
     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 scenario.caps.maxUsd.
+    // 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.js

@@ -13,6 +13,7 @@ import { NODE_BOOTSTRAP_TIMEOUT_MS } from "../../subject/node-bootstrap.js";
 import { terminalSandboxTimeoutMs } from "./lifetime.js";
 import { isExactRuntimeVersion, TERMINAL_RUNTIME_VERSION_TIMEOUT_MS } from "./runtime.js";
 import { PRODUCT_SETUP_TIMEOUT_MS, TERMINAL_SANDBOX_TIMEOUT_BUFFER_MS, } from "./types.js";
+import { actorOf, capsOf } from "../../study/study-fields.js";
 /**
  * Plan a terminal-product study. It is called for any config handed to the terminal runner, not
  * only one routeOf sends here, so a config for another route gets this route's refusal.
@@ -40,12 +41,12 @@ export function planTerminalStudy(config, input) {
     const tasksReason = taskProtocolValidationReason(config, false);
     if (tasksReason)
         return refuse("HUMANISH_STUDY_TASKS_UNSUPPORTED", tasksReason);
-    const actorType = config.actors[0]?.type ?? "";
+    const actorType = actorOf(config)?.type ?? "";
     const descriptor = actorRegistry[actorType];
     if (!descriptor || !isTerminalActorDescriptor(descriptor))
         return refuse("HUMANISH_TERMINAL_ACTOR_UNSUPPORTED", `actor.type "${actorType}" is not a registered terminal actor.`);
     const runtimeVersion = config.execution?.runtime?.version;
-    const actor = config.actors[0];
+    const actor = actorOf(config);
     if ((config.execution?.runtime !== undefined && !isExactRuntimeVersion(runtimeVersion)) ||
         (actor?.model !== undefined &&
             (typeof actor.model !== "string" || actor.model.trim().length === 0)) ||
@@ -83,7 +84,7 @@ export function planTerminalStudy(config, input) {
         ...(egressAllow === undefined ? {} : { egressAllow }),
         ...(stdin === undefined ? {} : { stdin }),
     };
-    const caps = config.scenario?.caps;
+    const caps = capsOf(config);
     if (input.dryRun)
         return { ok: true, plan: { ...shared, dryRun: true, ...(caps ? { caps } : {}) } };
     // The live route injects the runtime key into one command only, and only a registered actor

package/dist/routes/terminal/route.js

@@ -17,7 +17,7 @@
 //      spending. Opt-in openai-env injects the raw key command-scoped, never through
 //      Sandbox.create({envs}).
 //      Enforced in credentials.ts and runtime-auth.ts.
-//   2. Fail-closed cap. The live key is never exercised without scenario.caps in force: maxUsd
+//   2. Fail-closed cap. The live key is never exercised without `caps` in force: maxUsd
 //      (default/require 0 = no-spend) + maxMinutes (wall-clock kill of the codex command).
 //      Enforced in plan.ts (caps required), live-sandbox.ts and lifetime.ts (the wall clock).
 //   3. Public surfaces only. The mission references only subject.product.publicSurfaces + the
@@ -54,6 +54,7 @@ import { terminalRouteScorer } from "../../study/adapter-scorer-loader.js";
 import { withLateScorer } from "../../study/route-inputs.js";
 import {} from "./types.js";
 import { studyResultIdentity } from "../../run/study-result.js";
+import { actorOf } from "../../study/study-fields.js";
 /** A refused terminal study's result: the route's envelope, and the analysis record a refusal gets. */
 export function terminalStudyRefusal(options, refusal) {
     const { config, dryRun } = options;
@@ -61,7 +62,7 @@ export function terminalStudyRefusal(options, refusal) {
         ...studyResultIdentity("terminal", config.id),
         ok: false,
         cwd: path.resolve(options.cwd),
-        actor: refusal.actor ?? config.actors[0]?.type ?? "",
+        actor: refusal.actor ?? actorOf(config)?.type ?? "",
         product: config.subject.product?.name ?? "",
         dryRun,
         runId: options.runId ?? "not-created",

package/dist/routes/terminal/session.js

@@ -111,6 +111,7 @@ export async function runLiveTerminalSession(args) {
         if ((await session.bootstrap()) &&
             (await session.verifyRuntimeVersion()) &&
             (await session.prepareProduct())) {
+            run.participantStarted();
             await session.execCodex();
         }
     }

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

@@ -171,7 +171,7 @@ export interface TerminalProductStudyResult extends AutomaticAnalysisResult, Stu
     observer?: ObserverResult;
     warnings: string[];
     error?: {
-        code: "HUMANISH_STUDY_ANALYSIS_INVALID" | "HUMANISH_STUDY_TASKS_UNSUPPORTED" | "HUMANISH_STUDY_OPTION_UNSUPPORTED" | "HUMANISH_STUDY_V2_UNSUPPORTED" | "HUMANISH_TERMINAL_FAILED" | "HUMANISH_TERMINAL_ACTOR_UNSUPPORTED" | "HUMANISH_TERMINAL_SUBJECT_INVALID" | "HUMANISH_TERMINAL_KEYPLACEMENT_INVALID" | "HUMANISH_TERMINAL_RUNTIME_AUTH_MISSING" | "HUMANISH_TERMINAL_KEYS_MISSING" | "HUMANISH_TERMINAL_CAPS_MISSING" | "HUMANISH_TERMINAL_CAPS_INVALID" | "HUMANISH_TERMINAL_UNPRICED_CAP" | "HUMANISH_TERMINAL_CAPS_EXCEEDED" | "HUMANISH_TERMINAL_CREDENTIAL_DENIED" | "HUMANISH_TERMINAL_CLEANUP_UNPROVEN" | "HUMANISH_RUN_ID_IN_USE";
+        code: "HUMANISH_STUDY_ANALYSIS_INVALID" | "HUMANISH_STUDY_TASKS_UNSUPPORTED" | "HUMANISH_STUDY_OPTION_UNSUPPORTED" | "HUMANISH_STUDY_V2_UNSUPPORTED" | "HUMANISH_STUDY_INVALID" | "HUMANISH_TERMINAL_FAILED" | "HUMANISH_TERMINAL_ACTOR_UNSUPPORTED" | "HUMANISH_TERMINAL_SUBJECT_INVALID" | "HUMANISH_TERMINAL_KEYPLACEMENT_INVALID" | "HUMANISH_TERMINAL_RUNTIME_AUTH_MISSING" | "HUMANISH_TERMINAL_KEYS_MISSING" | "HUMANISH_TERMINAL_CAPS_MISSING" | "HUMANISH_TERMINAL_CAPS_INVALID" | "HUMANISH_TERMINAL_UNPRICED_CAP" | "HUMANISH_TERMINAL_CAPS_EXCEEDED" | "HUMANISH_TERMINAL_CREDENTIAL_DENIED" | "HUMANISH_TERMINAL_CLEANUP_UNPROVEN" | "HUMANISH_RUN_ID_IN_USE";
         message: string;
     };
 }

package/dist/run/display.d.ts

@@ -57,3 +57,13 @@ export declare function bundleDisplayFacts(bundle: DisplayedBundle, status?: unk
  * execution failed never reads as a pass beside its participants' verdict.
  */
 export declare function reviewOutcome(bundle: DisplayedBundle): string;
+/**
+ * The summary and gaps a review shows beside its run's display. A run stopped while a participant
+ * was still running keeps the review its last live flush wrote, which describes that session as
+ * running. Once runDisplay reads the run as interrupted, the review says how many participants the
+ * stop cut off instead.
+ */
+export declare function displayedReview<T extends {
+    summary: string;
+    gaps: string[];
+}>(review: T, bundle: DisplayedBundle, display: RunDisplay): T;

package/dist/run/display.js

@@ -3,6 +3,7 @@
 // same facts, so a run whose own ok is false shows as a pass on none of them, and two surfaces
 // cannot disagree about one run.
 import { classifyRunStatus, isRunStatusRecord } from "./status.js";
+import { plural } from "./text.js";
 const LABELS = {
     running: "running",
     interrupted: "interrupted",
@@ -104,3 +105,24 @@ export function bundleDisplayFacts(bundle, status, nowMs = Date.now()) {
 export function reviewOutcome(bundle) {
     return runDisplayLine(runDisplay(bundleDisplayFacts(bundle)));
 }
+/**
+ * The summary and gaps a review shows beside its run's display. A run stopped while a participant
+ * was still running keeps the review its last live flush wrote, which describes that session as
+ * running. Once runDisplay reads the run as interrupted, the review says how many participants the
+ * stop cut off instead.
+ */
+export function displayedReview(review, bundle, display) {
+    const records = bundle.simulations ?? [];
+    const running = records.filter((record) => record?.status === "running").length;
+    if (display.state !== "interrupted" || running === 0)
+        return review;
+    const signal = bundle.outcome?.state === "interrupted" ? ` by ${bundle.outcome.signal}` : "";
+    const one = running === 1;
+    return {
+        ...review,
+        summary: `Interrupted${signal} while ${running} of ${plural(records.length, "participant")} ${one ? "was" : "were"} still running.`,
+        gaps: [
+            `${plural(running, "participant")} ${one ? "has" : "have"} no verdict: the run stopped before ${one ? "its session" : "their sessions"} ended.`,
+        ],
+    };
+}

package/dist/run/reclaim.d.ts

@@ -20,9 +20,10 @@ export interface ReclaimResult {
     createsInFlight: number;
     /**
      * Why there was nothing to look for: `dry-run` when run.json or status.json records the run as
-     * a dry run, which creates no sandboxes. Reclaim then contacts E2B for nothing.
+     * a dry run, which creates no sandboxes, and `no-sandbox` when status.json records that the
+     * route created none for this run. Reclaim then contacts E2B for nothing.
      */
-    reason?: "dry-run";
+    reason?: NoSandboxReason;
     warnings: string[];
     error?: {
         code: "HUMANISH_RECLAIM_RUN_NOT_FOUND" | "HUMANISH_RECLAIM_E2B_DEBUG" | "HUMANISH_RECLAIM_MODULE_UNAVAILABLE" | "HUMANISH_RECLAIM_RECEIPTS_UNREADABLE";
@@ -47,6 +48,7 @@ export declare function reclaimRunSandboxes(cwd: string, runInput: string, hooks
  * also an alias (a run named `latest`) cannot reach another run's receipts.
  */
 export declare function reclaimPinnedRunSandboxes(cwd: string, runPaths: PreparedRunArtifactPaths, hooks?: ReclaimHooks): Promise<ReclaimResult>;
+type NoSandboxReason = "dry-run" | "no-sandbox";
 /**
  * Kill the sandboxes left by interrupted `humanish study check` probes. A probe journals under
  * .humanish/preflight/<probe-id>/ and removes the journal after a confirmed kill, so what is left

package/dist/run/reclaim.js

@@ -15,6 +15,7 @@ import { readRunJsonIfExists, resolveRunPath } from "./locate.js";
 import { RUN_BUNDLE_FILE } from "./bundle.js";
 import { RUN_STATUS_FILE } from "./status.js";
 import { isRecord } from "./type-guards.js";
+import { isRunOutcome } from "./bundle-shape.js";
 import { parseSandboxOwners, parseSandboxReceipts, SANDBOX_RECEIPTS_ARTIFACT, } from "./sandbox-receipts.js";
 import { sandboxOwnerTags, } from "./sandbox-creates.js";
 import { earlierOutcomes, GONE, RECLAIM_RECEIPT_ARTIFACT, RECLAIM_RESULT_SCHEMA, receiptWriter, rootState, searchTagSets, settledWithin, targetSet, } from "./reclaim-outcomes.js";
@@ -64,8 +65,9 @@ async function reclaimRun(cwd, runInput, locate, hooks) {
     }
     const runId = runIdOf(runPaths);
     // The signal handler passes the creates it stopped and decides from what they reported.
-    if (hooks.creates === undefined && (await recordedDryRun(runPaths)))
-        return { ...base, ok: true, state: "clean", runId, reason: "dry-run" };
+    const reason = hooks.creates === undefined ? await recordedNoSandbox(runPaths) : undefined;
+    if (reason !== undefined)
+        return { ...base, ok: true, state: "clean", runId, reason };
     const reclaimed = await reclaimRoot(runPaths, runId, hooks, warnings);
     if (reclaimed.kind === "module-unavailable")
         return {
@@ -93,29 +95,70 @@ async function reclaimRun(cwd, runInput, locate, hooks) {
     };
 }
 /**
- * Whether the run records that it was a dry run: run.json and status.json, each one present, say
- * `dry-run`. A run with neither record is not taken for one. A journal with any line in it, or an
- * earlier reclaim receipt that names a sandbox, means a create ran, so that run is reclaimed as a
- * live one whatever its records say.
+ * Why the run's own records say it created no sandbox. `dry-run`: run.json and status.json, each
+ * one present, say `dry-run`. `no-sandbox`: status.json, written at start, names this run and
+ * records `sandboxes: none`, which the route sets only when it has no way to create one (a
+ * scripted run against an app-url subject), and run.json agrees (scriptedAppUrlBundle). A status
+ * record alone can be stale or copied from another run, so it never decides on its own, and an
+ * empty journal alone never makes a run clean. A journal with any line in it, or an earlier
+ * reclaim receipt that names a sandbox, means a create ran, so that run is reclaimed as a live one
+ * whatever its records say.
  */
-async function recordedDryRun(runPaths) {
-    const modes = [];
-    for (const file of [RUN_BUNDLE_FILE, RUN_STATUS_FILE]) {
-        const record = await readRunJsonIfExists(runPaths, file);
-        if (isRecord(record))
-            modes.push(record.mode);
-    }
-    if (modes.length === 0 || modes.some((mode) => mode !== "dry-run"))
-        return false;
+async function recordedNoSandbox(runPaths) {
+    const bundle = await readRunJsonIfExists(runPaths, RUN_BUNDLE_FILE);
+    const status = await readRunJsonIfExists(runPaths, RUN_STATUS_FILE);
+    const records = [bundle, status].filter(isRecord);
+    const reason = records.length > 0 && records.every((record) => record.mode === "dry-run")
+        ? "dry-run"
+        : isRecord(status) &&
+            status.runId === runIdOf(runPaths) &&
+            status.sandboxes === "none" &&
+            scriptedAppUrlBundle(bundle, runIdOf(runPaths))
+            ? "no-sandbox"
+            : undefined;
+    if (reason === undefined)
+        return undefined;
     if (!(await containedPathAbsent(runPaths, RECLAIM_RECEIPT_ARTIFACT))) {
         const earlier = await readRunJsonIfExists(runPaths, RECLAIM_RECEIPT_ARTIFACT);
         if (!isRecord(earlier) || !Array.isArray(earlier.outcomes) || earlier.outcomes.length > 0)
-            return false;
+            return undefined;
     }
     if (await containedPathAbsent(runPaths, SANDBOX_RECEIPTS_ARTIFACT))
-        return true;
+        return reason;
     const journal = await readContainedRegularFile(runPaths, SANDBOX_RECEIPTS_ARTIFACT);
-    return journal !== null && journal.toString("utf8").trim() === "";
+    return journal !== null && journal.toString("utf8").trim() === "" ? reason : undefined;
+}
+/** The execution failure kinds that leave a sandbox or a provider's resources unconfirmed. */
+const CLEANUP_KINDS = new Set(["sandbox-cleanup", "provider-cleanup"]);
+/**
+ * run.json for `runId` agrees that its run could create no sandbox: the scripted route wrote it
+ * (each lifecycle event is a `scripted-lab.` one), its subject is not a provisioned clone (a clone
+ * records `subject`), it lists no provider resource and no desktop minutes, and its outcome marks
+ * no sandbox or provider cleanup unconfirmed. A run.json that is missing, unreadable or says
+ * otherwise does not agree.
+ */
+function scriptedAppUrlBundle(bundle, runId) {
+    if (!isRecord(bundle) || bundle.runId !== runId || bundle.subject !== undefined)
+        return false;
+    const { lifecycle, providerResources, cost, outcome } = bundle;
+    const scripted = Array.isArray(lifecycle) &&
+        lifecycle.length > 0 &&
+        lifecycle.every((entry) => isRecord(entry) &&
+            typeof entry.event === "string" &&
+            entry.event.startsWith("scripted-lab."));
+    if (!scripted)
+        return false;
+    if (providerResources !== undefined &&
+        !(Array.isArray(providerResources) && providerResources.length === 0))
+        return false;
+    if (cost !== undefined && !(isRecord(cost) && cost.desktopMinutes === null))
+        return false;
+    if (!isRunOutcome(outcome))
+        return false;
+    if (outcome.state !== "finished")
+        return true;
+    const { failures, warnings = [] } = outcome.execution;
+    return ![...failures, ...warnings].some((failure) => CLEANUP_KINDS.has(failure.kind));
 }
 /**
  * Kill the sandboxes left by interrupted `humanish study check` probes. A probe journals under

package/dist/run/results.d.ts

@@ -30,7 +30,7 @@ export interface RunResult {
     observer?: ObserverResult;
     warnings: string[];
     error?: {
-        code: "HUMANISH_STUDY_ANALYSIS_INVALID" | "HUMANISH_STUDY_ANALYSIS_UNSUPPORTED" | "HUMANISH_STUDY_TASKS_UNSUPPORTED" | "HUMANISH_STUDY_OPTION_UNSUPPORTED" | "HUMANISH_STUDY_V2_UNSUPPORTED" | "HUMANISH_STUDY_COMMS_UNSUPPORTED" | "HUMANISH_LIVE_RUN_UNIMPLEMENTED" | "HUMANISH_INVALID_CWD" | "HUMANISH_RUN_ID_IN_USE" | "HUMANISH_INVALID_PARTICIPANT_COUNT" | "HUMANISH_INVALID_PORT" | "HUMANISH_UNSUPPORTED_RERUN_FLAGS" | "HUMANISH_WATCH_OPTION_CONFLICT" | "HUMANISH_WATCH_SAFE_NOT_APPLICABLE" | "HUMANISH_RUN_OPTION_CONFLICT" | "HUMANISH_OBSERVE_OPTION_CONFLICT" | "HUMANISH_STUDY_SCORER_BAD_REF" | "HUMANISH_STUDY_SCORER_NOT_FOUND" | "HUMANISH_STUDY_SCORER_LOAD_FAILED" | "HUMANISH_STUDY_SCORER_NO_HOOKS" | "HUMANISH_STUDY_SCORER_UNSUPPORTED_BACKEND";
+        code: "HUMANISH_STUDY_ANALYSIS_INVALID" | "HUMANISH_STUDY_ANALYSIS_UNSUPPORTED" | "HUMANISH_STUDY_TASKS_UNSUPPORTED" | "HUMANISH_STUDY_OPTION_UNSUPPORTED" | "HUMANISH_STUDY_V2_UNSUPPORTED" | "HUMANISH_STUDY_INVALID" | "HUMANISH_STUDY_COMMS_UNSUPPORTED" | "HUMANISH_LIVE_RUN_UNIMPLEMENTED" | "HUMANISH_INVALID_CWD" | "HUMANISH_RUN_ID_IN_USE" | "HUMANISH_INVALID_PARTICIPANT_COUNT" | "HUMANISH_INVALID_PORT" | "HUMANISH_UNSUPPORTED_RERUN_FLAGS" | "HUMANISH_WATCH_OPTION_CONFLICT" | "HUMANISH_WATCH_SAFE_NOT_APPLICABLE" | "HUMANISH_RUN_OPTION_CONFLICT" | "HUMANISH_OBSERVE_OPTION_CONFLICT" | "HUMANISH_STUDY_SCORER_BAD_REF" | "HUMANISH_STUDY_SCORER_NOT_FOUND" | "HUMANISH_STUDY_SCORER_LOAD_FAILED" | "HUMANISH_STUDY_SCORER_NO_HOOKS" | "HUMANISH_STUDY_SCORER_UNSUPPORTED_BACKEND";
         message: string;
     };
 }

package/dist/run/run.d.ts

@@ -11,6 +11,8 @@ interface StartRunOptions {
     mintRunId: () => string;
     mode: "dry-run" | "live";
     study?: RunStudyProvenance | undefined;
+    /** `none` when the route creates no sandbox for this run; status.json records it for reclaim. */
+    sandboxes?: "none" | undefined;
     /** review.md for the published bundle. */
     renderReview: (bundle: RunBundle) => string;
     /** Used by `FinishedRun.renderObserver`; `render` is the `StudyDeps.renderObserver` seam. */
@@ -52,6 +54,12 @@ interface Run {
      * can never overwrite the final bundle. Routes that throttle snapshots own their timers.
      */
     writeSnapshot(bundle: RunBundle): Promise<void>;
+    /**
+     * A participant's session started: its actor began to act on the subject. FinishedRun's
+     * participantsRan reads this, so a session that throws before it returns a trace still counts,
+     * and a run that failed before any session (a refused E2B key) does not.
+     */
+    participantStarted(): void;
     /**
      * The one final publication: run.json with `outcome` set from `outcome`, then the status
      * outcome copied from it, then review.json, review.md, events.ndjson,
@@ -92,12 +100,14 @@ export declare class FinishedRun {
     readonly runId: string;
     /** The paths created by startRun and validated at the start of `finish`. */
     readonly paths: PreparedRunArtifactPaths;
-    constructor(key: typeof issueKey, runId: string, paths: PreparedRunArtifactPaths, observer: ObserverTarget | undefined, outcome: RecordedOutcome, recordFailure: (failure: ExecutionFailure) => Promise<RecordedOutcome>, interrupted: () => boolean);
+    constructor(key: typeof issueKey, runId: string, paths: PreparedRunArtifactPaths, observer: ObserverTarget | undefined, outcome: RecordedOutcome, recordFailure: (failure: ExecutionFailure) => Promise<RecordedOutcome>, interrupted: () => boolean, participantsRan: () => boolean);
     /**
      * A signal stopped this run's process: status.json and run.json record it `interrupted`. Read
      * when asked, since the signal can arrive after the bundle was published.
      */
     get interrupted(): boolean;
+    /** The route reported a participant's session started (Run.participantStarted). */
+    get participantsRan(): boolean;
     static isIssued(value: unknown): value is FinishedRun;
     /**
      * The run's ok and execution outcome as run.json records them: what the route passed to