humanish 0.110.4 → 0.111.0

package/CHANGELOG.md

@@ -8,6 +8,21 @@ The Unreleased section holds the full notes for the next version until it is tag
 
 ## Unreleased
 
+## 0.111.0: StudyConfig has the keys of a v3 study file (2026-10-05)
+
+humanish 0.111.0 is the first breaking release under the compatibility policy. It breaks library
+callers that read or build a `StudyConfig`, the type `parseStudy` returns and `runStudy` takes:
+the type now has the keys of a `humanish.study.v3` file, such as `actor`, `route`,
+`participants`, `caps` and `mode`, where it had `actors[0]`, `execution.caps` and
+`scenario.mode`. The release notes carry the migration table. `runStudy` refuses a config that
+still sets a 0.110 field with `HUMANISH_STUDY_V2_UNSUPPORTED`, so a budget left in
+`execution.caps` cannot run uncapped. Study files and CLI commands are unchanged, except two JSON
+outputs: `humanish study show --json` prints the v3 config, and `humanish study check --json`
+names a participant's target `participants[<i>].target`. The `--env-file` and `cleanup` aliases
+still work and are removed in 0.112.0, on or after 2026-11-03.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.111.0)
+
 ## 0.110.4: Scripted runs reclaim clean, review says interrupted, Chrome under a long TMPDIR (2026-10-05)
 
 humanish 0.110.4 fixes four findings of the 0.110.3 live smoke. `humanish reclaim --check` reports

package/CONTEXT.md

@@ -18,7 +18,7 @@ bundle and output fields keep older spellings; the second table maps them.
 | persona             | Who a participant is: traits, background, device. `humanish/personas/<id>.yaml`.                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `src/study/persona.ts`, `src/study/persona-resolve.ts`                                                                                                                                                                                                                                                                                                                                                      |
 | mission             | The free-form brief a model-driven participant receives: `actor.mission`. `actor.tasks[]` adds discrete tasks: each has a `goal` the participant sees and an optional `success` check it does not.                                                                                                                                                                                                                                                                                                                                    | `StudyActor` in `src/study/types.ts`                                                                                                                                                                                                                                                                                                                                                                        |
 | assignment          | What one participant was asked to do: the mission, a `participants` entry's `instruction` or the homogeneous `participants.instruction` (recorded as `focus`), and the tasks. Each stream records it as `streams[].assignment`.                                                                                                                                                                                                                                                                                                       | `participantAssignment` in `src/study/participant-assignment.ts`; `RunParticipantAssignment` in `src/run/streams.ts`                                                                                                                                                                                                                                                                                        |
-| scenario            | A scenario file, `humanish/scenarios/<id>.yaml` (`humanish.scenario.v1`): a goal and ordered steps with expectations. A scripted study names one in `scenario:`, and only the scripted route executes those steps. A v2 study file's `scenario` block held run settings (`mode`, `caps`, `ref`), which v3 moves to the top level. A model-driven participant follows its mission.                                                                                                                                                     | `StudyScenario` in `src/study/types.ts`; `src/routes/scripted/route.ts` resolves the scenario, and `executeBrowserPersonaStep` (`src/actors/scripted-browser/steps.ts`) runs each step                                                                                                                                                                                                                      |
+| scenario            | A scenario file, `humanish/scenarios/<id>.yaml` (`humanish.scenario.v1`): a goal and ordered steps with expectations. A scripted study names one in `scenario:`, and only the scripted route executes those steps. A v2 study file's `scenario` block held run settings (`mode`, `caps`, `ref`), which v3 moves to the top level. A model-driven participant follows its mission.                                                                                                                                                     | `scenario` in `StudyConfig` (`src/study/types.ts`); `src/routes/scripted/route.ts` resolves the scenario, and `executeBrowserPersonaStep` (`src/actors/scripted-browser/steps.ts`) runs each step                                                                                                                                                                                                           |
 | surface             | One browser viewport that a scripted run replays its journey on: `desktop` or `mobile`. A scripted study runs the desktop surface by default, and `surfaces: [desktop, mobile]` adds the mobile one. Each surface writes `actor-<surface>.json` and `traces/<surface>.json`.                                                                                                                                                                                                                                                          | `BrowserSurface` and `browserSurfaces` in `src/actors/scripted-browser/types.ts`; the plan's `surfaces` in `src/routes/scripted/plan.ts`                                                                                                                                                                                                                                                                    |
 | journey             | A scenario's `browser.steps` parsed into ordered steps with a goal and a start path. The scripted route replays it once on each surface, and each surface's session reports the first step that did not pass.                                                                                                                                                                                                                                                                                                                         | `BrowserPersonaJourney` in `src/actors/scripted-browser/types.ts`; `parseBrowserPersonaJourneyFromScenario` in `src/actors/scripted-browser/journey.ts`                                                                                                                                                                                                                                                     |
 | subject             | The product under study, declared by `subject.source`: `clone`, `app-url`, `local-tree`, `terminal-product`, `desktop-cli`, `local-app` or `this-repo`. `run.json` records its provenance under `subject`.                                                                                                                                                                                                                                                                                                                            | `StudySubject` in `src/study/types.ts`, parsed in `src/study/parse/subject.ts`                                                                                                                                                                                                                                                                                                                              |
@@ -33,7 +33,7 @@ bundle and output fields keep older spellings; the second table maps them.
 | participant desktop | The desktop one computer-use or shared-world participant drives: a substrate plus the route's concerns, such as subject provisioning, comms and the participant's plan. It lives in the route, so `src/substrates/` holds only provider primitives ([ADR 0004](docs/decisions/0004-participant-desktops-stay-in-the-route.md)).                                                                                                                                                                                                       | `ParticipantDesktop` in `src/routes/computer-use/participant-desktop.ts`; `createE2BParticipantDesktop` in `src/routes/computer-use/e2b-desktop/desktop.ts`; the local VM's in `src/routes/computer-use/local-vm.ts`                                                                                                                                                                                        |
 | receipt             | A line in a run's `sandbox-receipts.ndjson` that records a sandbox's id, provider, the participant or subject it belongs to (`laneId`), and its time limit as soon as the sandbox is created, before any work runs in it. `humanish reclaim` kills sandboxes by these ids after an interrupted run.                                                                                                                                                                                                                                   | `SandboxReceipt` in `src/run/sandbox-receipts.ts`; `reclaimRunSandboxes` in `src/run/reclaim.ts`                                                                                                                                                                                                                                                                                                            |
 | owner tags          | The E2B metadata every sandbox humanish creates carries: `tool: humanish`, the run's `runId`, and `runKey`, a digest of the run directory's inode and creation time. The run journals them in an owner line before its first create. `humanish reclaim` lists sandboxes that match all three, which finds one whose id never reached a receipt.                                                                                                                                                                                       | `sandboxOwnerTags` in `src/run/sandbox-creates.ts`; `findE2BSandboxesByTags` in `src/substrates/e2b/sandbox.ts`                                                                                                                                                                                                                                                                                             |
-| topology            | Whether participants share one instance of the subject. `route: shared-world` gives one for all; every other route gives each participant its own (`per-lane-worlds`). `run.json` records it as `sharedWorld.topology`.                                                                                                                                                                                                                                                                                                               | `StudySubjectTopology` in `src/study/types.ts`                                                                                                                                                                                                                                                                                                                                                              |
+| topology            | Whether participants share one instance of the subject. `route: shared-world` gives one for all; every other route gives each participant its own (`per-lane-worlds`). `run.json` records it as `sharedWorld.topology`.                                                                                                                                                                                                                                                                                                               | `declaresSharedWorld` in `src/study/study-fields.ts`                                                                                                                                                                                                                                                                                                                                                        |
 | plane               | The one instance of the subject that a shared-world study's participants use together. A `provisioned` plane is a `clone` or `local-tree` subject that humanish serves in a sandbox, with a declared subject state. An `external-public` plane is a deployment already running at `subject.appUrl`, whose owner the study names in `subject.publicTarget.owner`. Each plane has at least two participants.                                                                                                                            | `SharedWorldPlane` in `src/study/plan-types.ts`; `src/routes/shared-world/`                                                                                                                                                                                                                                                                                                                                 |
 | stream              | One live or recorded view of a participant, such as a browser or a terminal, in `run.json` and the Observer.                                                                                                                                                                                                                                                                                                                                                                                                                          | `RunStream` in `src/run/streams.ts`                                                                                                                                                                                                                                                                                                                                                                         |
 | Observer            | The single-file review page built from `observer/observer-data.json` (`humanish.observer-data.v1`).                                                                                                                                                                                                                                                                                                                                                                                                                                   | `observer/` (the page), `src/observer/` (data, render, serve)                                                                                                                                                                                                                                                                                                                                               |

package/dist/actors/local-agent/claude-session.js

@@ -1,6 +1,6 @@
 // One Claude Code process as the computer-use brain, instead of a fresh `claude -p` per turn.
 //
-// Why: `actors[].localAgent: codex` already runs through a persistent app-server thread,
+// Why: `actor.localAgent: codex` already runs through a persistent app-server thread,
 // so the participant remembers what it tried. `claude` spawned `claude -p` per turn, so every
 // turn started cold. Measured on the same study with the same credentials (n=1 each): one-shot,
 // 188 actions over 90 turns and never finished; a thread that remembers, 21 actions over 8 turns

package/dist/actors/local-agent/cli.js

@@ -3,7 +3,7 @@
 // mapping and JSON reading the two Claude Code paths share, and the one-shot Claude Code provider.
 //
 // A developer trying humanish often already has a coding agent signed in (Codex on a ChatGPT plan,
-// Claude Code on a Max plan), so `actors[0].type: local-agent` lets that agent decide the next
+// Claude Code on a Max plan), so `actor.type: local-agent` lets that agent decide the next
 // action instead of a provider API key. Codex runs as a restricted app-server participant
 // (actors/codex/restricted-participant.ts) and Claude Code as one session for the whole run
 // (claude-session.ts). The one-shot provider below spawns `claude -p` per turn, with no memory of

package/dist/actors/scripted-browser/actor.d.ts

@@ -8,11 +8,11 @@ export interface ScriptedBrowserSessionOptions {
     evidenceAppUrl?: string;
     /** Defaults to loopback. Provisioned subjects drive a private URL but persist redacted labels. */
     urlPolicy?: ScriptedBrowserEvidenceUrlPolicy;
-    /** Parsed + validated by the backend (scenario.ref is consumed there, fail-closed). */
+    /** Parsed + validated by the backend (`scenario` is consumed there, fail-closed). */
     journey: BrowserPersonaJourney;
     /** One session per surface. */
     surface: BrowserSurface;
-    /** id = actors[0].persona ?? "scripted-journey"; promptDigest = journey.sourceDigest prefix
+    /** id = actor.persona ?? "scripted-journey"; promptDigest = journey.sourceDigest prefix
      *  (the step manifest is the "prompt"; no model prompt exists on this route). */
     persona: ActorPersonaRef;
     /** Journey wall-clock budget in ms; the route passes execution.timeoutMs or 300_000. */

package/dist/cli/commands/study.js

@@ -4,7 +4,7 @@ import { Command, Option } from "commander";
 import { inspectStudyManifest, listStudyManifests } from "../../study/discover.js";
 import { runStudyPreflight, } from "../../study/preflight.js";
 import { applyEnvFileOption, CWD_OPTION_DESCRIPTION, DOTENV_OPTION_DESCRIPTION, dotenvPathOf, envFileAliasOption, JSON_OPTION_DESCRIPTION, parsePositiveInteger, writeResult, humanError, } from "../io.js";
-import { actorsOf } from "../../study/study-fields.js";
+import { actorOf } from "../../study/study-fields.js";
 export function registerStudyCommands(parent, io) {
     const study = parent
         .command("study")
@@ -115,9 +115,7 @@ function formatStudyShowHuman(result) {
         `id: ${config.id}`,
         `subject: ${config.subject.source}`,
         ...(config.execution?.target ? [`execution: ${config.execution.target}`] : []),
-        `actors: ${actorsOf(config)
-            .map((actor) => actor.type)
-            .join(", ")}`,
+        `actor: ${actorOf(config)?.type ?? ""}`,
         ...(config.title ? [`title: ${config.title}`] : []),
         ...(config.description ? [`description: ${config.description}`] : []),
         ...(result.path ? [`path: ${result.path}`] : []),

package/dist/routes/computer-use/participant-model.js

@@ -84,7 +84,7 @@ export async function startParticipantModel(spec, deps, executor) {
 /** The options the participant's session runs with: prompt, model settings, spend caps and callbacks. */
 export function participantSessionOptions(spec, deps, ready, provider, writeScreenshot) {
     const { executor, inbox } = ready;
-    // The fail-closed spend cap (execution.caps.maxUsd) is wired into the loop as maxUsd + an
+    // The fail-closed spend cap (caps.maxUsd) is wired into the loop as maxUsd + an
     // injected pure per-turn estimator keyed on the resolved model. Preflight already refused a
     // cap on an unpriced model, so the estimate is measurable whenever a cap is in force. The
     // model id here matches provider.version (openai-responses-cu resolves the default when unset).

package/dist/routes/computer-use/plan.js

@@ -10,7 +10,7 @@ import { subjectStateInvalidReason } from "../../study/parse/subject-state.js";
 import { brainOf, callerBrainOf, planCaps, desktopRequirements, planBase, provisionedSubject, } from "../../study/plan-base.js";
 import { computerUseParticipants, declaredTargets } from "../../study/plan-participants.js";
 import { MAX_COMPUTER_USE_PARTICIPANTS } from "../../study/routing.js";
-import { cloneTargetValidationReason, computerUseValidationReason, desktopMediaValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, scenarioCapsValidationReason, taskProtocolValidationReason, } from "../../study/validation.js";
+import { cloneTargetValidationReason, computerUseValidationReason, desktopMediaValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, taskProtocolValidationReason, } from "../../study/validation.js";
 import { desktopCliProductReason } from "../../study/composition-rules.js";
 import { isLocalBrowserStudy } from "../../substrates/local/runtime-config.js";
 import { boundedConcurrency, defaultSessionTimeoutMs, resolveParticipantSandboxMs, } from "./participant-runs.js";
@@ -84,9 +84,7 @@ function cuaStudyRejection(config, hasRunSession, driving, subjectRoute) {
 }
 /** A declaration this route cannot honor, for any subject or with the caller's own driver. */
 function unsupportedDeclarationReason(config, hasRunSession, driving, { inProcessRoute }) {
-    const reason = desktopMediaValidationReason(config) ||
-        outputTokenLimitValidationReason(config) ||
-        scenarioCapsValidationReason(config);
+    const reason = desktopMediaValidationReason(config) || outputTokenLimitValidationReason(config);
     if (reason)
         return invalid(reason);
     if (actorOf(config)?.maxOutputTokens !== undefined &&
@@ -177,7 +175,7 @@ function driverReason(driving, { localAppSubject, inProcessRoute }) {
 }
 /** The participant roster, then the sandbox deadline its session budget derives. */
 function rosterShapeReason(config) {
-    // `lanes` XOR `count`/`laneFocus`, device XOR raw resolution, cap, unique ids,
+    // Device XOR raw resolution, cap, unique ids,
     // allowPublicTargets with more than one participant, clone.fanout.
     const fanoutReason = computerUseValidationReason(config);
     if (fanoutReason)
@@ -293,7 +291,7 @@ export function planComputerUseStudy(config, input) {
             concurrency: boundedConcurrency(declared, n),
             sessionBudgetMs: config.execution?.timeoutMs ?? defaultSessionTimeoutMs(config),
             sandboxMs: resolveParticipantSandboxMs(config),
-            caps: planCaps(config, "computer-use"),
+            caps: planCaps(config),
             ...(input.rerun === undefined ? {} : { rerun: rerunPlan(input.rerun) }),
             requirements: base.dryRun || runner.desktop === "in-process"
                 ? []

package/dist/routes/computer-use/preflight.js

@@ -59,7 +59,7 @@ export async function liveCuaRejection(args) {
         };
     }
     // Fail-closed cap: a maxUsd cap needs a measurable per-turn estimate.
-    // If the operator set execution.caps.maxUsd but src/run/pricing.ts has no rate for the resolved
+    // If the operator set caps.maxUsd but src/run/pricing.ts has no rate for the resolved
     // model, the loop could not enforce the cap, and silently running uncapped would break the
     // runaway-retry protection. Refuse at preflight (before any sandbox/spend) rather than run
     // uncapped: an unenforceable cap is more dangerous than none. The operator picks a priced model

package/dist/routes/computer-use/result.js

@@ -193,7 +193,7 @@ function computerUseExecutionFailures(outcomes, runId) {
     ];
 }
 /**
- * execution.caps.maxUsd is enforced inside each participant's loop independently, so an
+ * caps.maxUsd is enforced inside each participant's loop independently, so an
  * N-participant fan-out can spend up to N × maxUsd before any participant aborts, while the run cost summary reports the larger
  * aggregate. The warning names that ceiling, unless the study declared a shared maxTotalUsd budget.
  */

package/dist/routes/computer-use/route.js

@@ -1,6 +1,6 @@
 // The computer-use route: a subject (an app-url the caller provisioned, or a repo the
 // humanish clones and serves in the sandbox) driven by a registry-resolved computer-use actor inside a
-// hosted E2B desktop. On this path `actors[].type` selects the actor: the
+// hosted E2B desktop. On this path `actor.type` selects the actor: the
 // descriptor returned by the registry runs the session; the route provisions the desktop and
 // subject, composes the prompt from config, persists the evidence bundle, and tears down.
 //

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

@@ -52,8 +52,8 @@ export interface ComputerUseRunInput {
     cwd: string;
     open?: boolean;
     runId?: string;
-    /** CLI `--count` override for the homogeneous fan-out participant count (ignored when a `lanes`
-     *  roster is declared; a roster's length is authoritative). */
+    /** CLI `--count` override for the homogeneous fan-out participant count (ignored when a `participants`
+     *  list is declared; a roster's length is authoritative). */
     countOverride?: number;
     /** Explicitly create a new run containing failed or selected participants from a prior fan-out run. */
     rerun?: {
@@ -182,7 +182,7 @@ export interface CuaParticipantSummary {
     concurrency: number;
     waves: number;
 }
-export type CuaActorStudyErrorCode = "HUMANISH_STUDY_ANALYSIS_INVALID" | "HUMANISH_STUDY_TASKS_UNSUPPORTED" | "HUMANISH_STUDY_OPTION_UNSUPPORTED" | "HUMANISH_STUDY_V2_UNSUPPORTED" | "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_FANOUT_INVALID" | "HUMANISH_COMPUTER_USE_RERUN_INVALID" | "HUMANISH_COMPUTER_USE_DEVICE_GEOMETRY" | "HUMANISH_RUN_ID_IN_USE" | "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 type CuaActorStudyErrorCode = "HUMANISH_STUDY_ANALYSIS_INVALID" | "HUMANISH_STUDY_TASKS_UNSUPPORTED" | "HUMANISH_STUDY_OPTION_UNSUPPORTED" | "HUMANISH_STUDY_V2_UNSUPPORTED" | "HUMANISH_STUDY_INVALID" | "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_FANOUT_INVALID" | "HUMANISH_COMPUTER_USE_RERUN_INVALID" | "HUMANISH_COMPUTER_USE_DEVICE_GEOMETRY" | "HUMANISH_RUN_ID_IN_USE" | "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";
@@ -385,7 +385,7 @@ export interface ParticipantModelDeps {
     artifactRoot: PreparedOutputRoot;
     redactScreenshots: boolean;
     scrubKnownValues: (text: string) => string;
-    /** The study's shared spend ledger, present exactly when execution.caps.maxTotalUsd is set on a
+    /** The study's shared spend ledger, present exactly when caps.maxTotalUsd is set on a
      *  live run. Preflight already refused the cap on an unpriced model. */
     runBudget?: CuaRunBudget;
     /**

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.
 //

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/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

@@ -200,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

@@ -10,7 +10,7 @@ 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, 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. */
@@ -54,7 +54,6 @@ 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));
@@ -62,7 +61,7 @@ export function planSharedWorldStudy(config, input) {
         return refuse(invalid, invalidReason, actor);
     if (actorOf(config)?.maxOutputTokens !== undefined && input.hasRunSession === true)
         return refuse(invalid, "maxOutputTokens cannot be enforced by a custom runSession.", actor);
-    const caps = capsOf(config, "shared-world");
+    const caps = capsOf(config);
     if (!input.dryRun && (caps?.maxUsd !== undefined || caps?.maxTotalUsd !== undefined)) {
         const model = (actorOf(config)?.model ?? DEFAULT_OPENAI_CU_MODEL).trim().toLowerCase();
         if (!MODEL_RATES[model])
@@ -107,7 +106,7 @@ export function planSharedWorldStudy(config, input) {
                 ? {}
                 : { sessionTimeoutMs: config.execution.timeoutMs }),
             brain,
-            caps: planCaps(config, "shared-world"),
+            caps: planCaps(config),
             requirements: base.dryRun
                 ? []
                 : [

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

@@ -84,7 +84,7 @@ export function planTerminalStudy(config, input) {
         ...(egressAllow === undefined ? {} : { egressAllow }),
         ...(stdin === undefined ? {} : { stdin }),
     };
-    const caps = capsOf(config, "terminal");
+    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

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/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-study.d.ts

@@ -3,7 +3,7 @@ import { type LateScorer } from "./study/route-inputs.js";
 import { type StudyRoute } from "./study/plan.js";
 import type { StudyDeps } from "./study/study-deps.js";
 import type { RunStudyDriving, RunStudyHomes } from "./study/run-study-homes.js";
-import { type StudyConfig } from "./study/types.js";
+import type { StudyConfig } from "./study/types.js";
 import type { ObserverResult } from "./observer/render.js";
 import { type CuaActorStudyResult } from "./routes/computer-use/types.js";
 import { type PreviewStudyResult } from "./routes/preview.js";
@@ -20,8 +20,10 @@ import type { RunStudyProvenance } from "./run/study-provenance.js";
 export declare function runStudyWith(config: StudyConfig, options: InternalRunStudyOptions, deps?: StudyDeps): Promise<StudyOutcome>;
 /**
  * The package's study runner (`src/index.ts`): runStudyWith with the public options only. A
- * JavaScript caller that passes a field RunStudyOptions no longer has, or a humanish.lab.v2 config,
- * is refused in the route's own result envelope before anything runs.
+ * config that skipped parseStudy is checked first (libraryConfigRefusal): a humanish.lab.v2 config
+ * or one with a humanish 0.110 field, no `actor`, or a `route` the config does not take. That, or a
+ * field RunStudyOptions no longer has, is refused in the route's own result envelope before
+ * anything runs.
  */
 export declare function runStudy(config: StudyConfig, options: RunStudyOptions): Promise<StudyOutcome>;
 /** A study planned once: the route's refusal, or the run of its plan. */

package/dist/run-study.js

@@ -7,8 +7,7 @@
 import { computerUseInput, scriptedInput, sharedWorldInput, terminalInput, } from "./study/route-inputs.js";
 import { planStudy, resolveStudyDryRun, routeOf } from "./study/plan.js";
 import { normalizeRunStudyOptions, optionRefusalOutcome, removedOptionRefusal, } from "./study/run-study-options.js";
-import { V2_SCHEMA } from "./study/types.js";
-import { V2_UNSUPPORTED_MESSAGE } from "./study/config.js";
+import { libraryConfigRefusal } from "./study/config.js";
 import { admitComputerUsePlan, computerUseStudyRefusal } from "./routes/computer-use/route.js";
 import {} from "./routes/computer-use/types.js";
 import { admitPreviewPlan, previewStudyRefusal, } from "./routes/preview.js";
@@ -32,17 +31,14 @@ export async function runStudyWith(config, options, deps = {}) {
 }
 /**
  * The package's study runner (`src/index.ts`): runStudyWith with the public options only. A
- * JavaScript caller that passes a field RunStudyOptions no longer has, or a humanish.lab.v2 config,
- * is refused in the route's own result envelope before anything runs.
+ * config that skipped parseStudy is checked first (libraryConfigRefusal): a humanish.lab.v2 config
+ * or one with a humanish 0.110 field, no `actor`, or a `route` the config does not take. That, or a
+ * field RunStudyOptions no longer has, is refused in the route's own result envelope before
+ * anything runs.
  */
 export async function runStudy(config, options) {
-    const refusal = config.schema === V2_SCHEMA
-        ? {
-            ok: false,
-            code: "HUMANISH_STUDY_V2_UNSUPPORTED",
-            message: V2_UNSUPPORTED_MESSAGE,
-        }
-        : removedOptionRefusal(options);
+    const rejected = libraryConfigRefusal(config);
+    const refusal = rejected === undefined ? removedOptionRefusal(options) : { ok: false, ...rejected };
     if (refusal === undefined)
         return runStudyWith(config, options);
     const study = localBrowserDefaults(config);

package/dist/study/adapter-scorer-loader.d.ts

@@ -50,7 +50,7 @@ export type AdapterScorerLoadResult = {
     };
 };
 /**
- * Resolve + load a config-declared scorer module. Resolution clones scenario.ref exactly
+ * Resolve + load a config-declared scorer module. Resolution clones the scripted `scenario` resolution exactly
  * (prepareSelectedOutputDirectory → cwd-clamp → readContainedRegularFile), then `import()`s the
  * entry file in a broad try/catch. The digest is over the readContainedRegularFile entry bytes.
  */

package/dist/study/adapter-scorer-loader.js

@@ -54,7 +54,7 @@ const SCORER_CAPABLE_ROUTES = new Set([
  *  package.json `type`. `.ts` is rejected: the compiled `dist/` CLI ships no TypeScript loader. */
 const SCORER_EXTENSIONS = new Set([".mjs", ".js", ".cjs"]);
 /**
- * Resolve + load a config-declared scorer module. Resolution clones scenario.ref exactly
+ * Resolve + load a config-declared scorer module. Resolution clones the scripted `scenario` resolution exactly
  * (prepareSelectedOutputDirectory → cwd-clamp → readContainedRegularFile), then `import()`s the
  * entry file in a broad try/catch. The digest is over the readContainedRegularFile entry bytes.
  */
@@ -84,10 +84,10 @@ export async function loadAdapterScorer(args) {
     if (!SCORER_EXTENSIONS.has(ext)) {
         return fail("HUMANISH_STUDY_SCORER_BAD_REF", `review.scorer.ref "${trimmed}" must be a path relative to the project ending in .mjs (recommended), .js or .cjs.`);
     }
-    // Root token: realpath(cwd) → prepareSelectedOutputDirectory(dirname, cwd). Mirrors scenario.ref.
+    // Root token: realpath(cwd) → prepareSelectedOutputDirectory(dirname, cwd). Mirrors the scripted `scenario`.
     const physicalCwd = await realpath(path.resolve(args.cwd));
     const root = await prepareSelectedOutputDirectory(path.dirname(physicalCwd), physicalCwd);
-    // Clamp verbatim from the scripted scenario.ref branch: resolve → relative → reject escape/absolute.
+    // Clamp verbatim from the scripted `scenario` branch: resolve → relative → reject escape/absolute.
     const absolutePath = path.resolve(root.physicalPath, trimmed);
     const relative = path.relative(root.physicalPath, absolutePath);
     if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {