humanish 0.110.4 → 0.111.1

package/dist/routes/terminal/session.js

@@ -61,6 +61,7 @@ export async function runLiveTerminalSession(args) {
         // This entry point is the live terminal route; its dry-run sibling is a separate function.
         mode: "live",
         study: plan.study,
+        warnings: plan.warnings,
         renderReview: renderTerminalReviewMarkdown,
         observer: { open: input.open === true, render: deps.renderObserver },
         now,
@@ -77,7 +78,7 @@ export async function runLiveTerminalSession(args) {
     });
     const e2bApiKey = env.E2B_API_KEY?.trim() ?? "";
     // The ledgers + capture buffers, mutated through the live lifecycle.
-    const recorder = createTerminalRecorder({ nowIso, sanitize, knownSecretValues });
+    const recorder = createTerminalRecorder({ nowIso, sanitize, knownSecretValues, verdictNonce });
     const { version, model, modelSource, reasoningEffort } = plan.runtime;
     const runtime = declaredRuntimeProvenance({
         ...(version === undefined ? {} : { version }),

package/dist/routes/terminal/token-usage.d.ts

@@ -1,4 +1,7 @@
 import type { ActorTokenUsage } from "../../actors/contract.js";
+/** The usage records in complete stdout lines, kept from output past the transcript cap so
+ *  parseTerminalTokenUsage can count them with the stored ones. */
+export declare function terminalUsageRecords(lines: string): string[];
 /**
  * Accumulate runtime-turn usage from a captured `codex exec --json` stream. A Codex turn may
  * include multiple provider requests; these records cannot establish per-request pricing tiers.

package/dist/routes/terminal/token-usage.js

@@ -19,6 +19,11 @@ const USAGE_RE = /"type"\s*:\s*"turn\.completed"\s*,\s*"usage"\s*:\s*(\{[^}\n]*\
 function num(value) {
     return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
 }
+/** The usage records in complete stdout lines, kept from output past the transcript cap so
+ *  parseTerminalTokenUsage can count them with the stored ones. */
+export function terminalUsageRecords(lines) {
+    return Array.from(lines.matchAll(USAGE_RE), (match) => match[0]);
+}
 /**
  * Accumulate runtime-turn usage from a captured `codex exec --json` stream. A Codex turn may
  * include multiple provider requests; these records cannot establish per-request pricing tiers.

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

@@ -53,7 +53,8 @@ export interface TerminalProductScoringContext {
     /**
      * The full normalized transcript of the in-sandbox agent session, scrubbed (literal known
      * values) then redacted (shape patterns) at the source, capped at MAX_TRANSCRIPT_BYTES, and
-     * byte-identical to the persisted terminal-transcript.txt artifact. The trace's transcriptTail
+     * byte-identical to the persisted terminal-transcript.txt artifact. A capped transcript ends
+     * with a `[humanish]` line giving the byte count that was not stored. The trace's transcriptTail
      * is a ~2KB projection of this; a scorer needs the whole session so a rubric can find
      * command-tier evidence anywhere in it.
      */
@@ -171,7 +172,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/routes/terminal/types.js

@@ -32,5 +32,6 @@ export const TEXT_ITEMS_BYTES = 128 * 1024;
 // The longest stdout line the participant reader holds while waiting for its newline.
 export const PENDING_LINE_CHARS = 1024 * 1024;
 // Hard cap on the retained event-stream + transcript size, so a runaway agent cannot balloon the
-// bundle. Redaction runs pre-truncation so a cut can never split a secret past the scrubber.
+// bundle. Redaction runs pre-truncation so a cut can never split a secret past the scrubber. Output
+// past the cap is still read for the verdict marker, token usage and the trace's agent text.
 export const MAX_TRANSCRIPT_BYTES = 512 * 1024;

package/dist/run/dry-run.js

@@ -67,6 +67,7 @@ async function runDryRunInScope(options, scope) {
         mintRunId: () => `dryrun-${createdAt.replace(/[:.]/g, "-")}-${randomUUID().slice(0, 8)}`,
         mode: options.dryRun ? "dry-run" : "live",
         study: options.study,
+        warnings: options.warnings,
         renderReview: renderReviewMarkdown,
         // The run starts at the time its id and source were stamped with.
         now: () => Date.parse(createdAt),

package/dist/run/results.d.ts

@@ -5,6 +5,8 @@ export declare const CLEANUP_SCHEMA = "humanish.cleanup-result.v1";
 export interface RunOptions {
     /** Which manifest produced this run. */
     study?: RunStudyProvenance;
+    /** Warnings about the study's own fields, recorded in the bundle as warn events. */
+    warnings?: readonly string[];
     cwd: string;
     dryRun?: boolean;
     runId?: string;
@@ -30,7 +32,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

@@ -22,6 +22,8 @@ interface StartRunOptions {
     };
     /** Clock for `createdAt` and the latest pointer. */
     now?: (() => number) | undefined;
+    /** Warnings about the study's own fields. Every bundle write records each as a warn event. */
+    warnings?: readonly string[] | undefined;
 }
 /** How a run ended as an execution, as run.json records it: the result's ok and execution outcome. */
 interface RecordedOutcome {

package/dist/run/run.js

@@ -5,7 +5,7 @@
 import { redactText } from "../evidence/redaction.js";
 import { buildObserverData } from "../observer/data.js";
 import { renderObserver } from "../observer/render.js";
-import { RUN_BUNDLE_FILE, PUBLIC_TARGET_CWD } from "./bundle.js";
+import { RUN_BUNDLE_FILE, PUBLIC_TARGET_CWD, } from "./bundle.js";
 import { judgeExecution, } from "./judge.js";
 import {} from "./results.js";
 import { createRunArtifactPaths, validatePreparedRunArtifactPaths, } from "./paths.js";
@@ -112,8 +112,20 @@ function observerTarget(options) {
         };
 }
 function runPublisher(args) {
-    const { options, runId, paths, runStatus, now, admit, participantsRan } = args;
+    const { options, runId, createdAt, paths, runStatus, now, admit, participantsRan } = args;
     const observer = observerTarget(options);
+    // The study's warnings join whatever events the route wrote, once, in every write.
+    const studyWarnings = (options.warnings ?? []).map((message, index) => ({
+        id: `event-study-warning-${String(index + 1).padStart(3, "0")}`,
+        at: createdAt,
+        level: "warn",
+        type: "study.warning",
+        message,
+    }));
+    const withStudyWarnings = (events) => [
+        ...events.filter((event) => !studyWarnings.some((warning) => warning.id === event.id)),
+        ...studyWarnings,
+    ];
     let pointerWritten = false;
     // The bundle of the last write asked for, and the outcome every later write carries once a
     // signal stopped the run, so no write after the interrupt can drop it.
@@ -145,6 +157,7 @@ function runPublisher(args) {
         const recorded = interrupted ?? outcome;
         const publicBundle = await withPublicSandboxIds(paths, {
             ...evidence,
+            events: withStudyWarnings(evidence.events),
             cwd: PUBLIC_TARGET_CWD,
             ...(recorded === undefined ? {} : { outcome: recorded }),
         });
@@ -271,6 +284,7 @@ export async function runScope(fn) {
         const publisher = runPublisher({
             options,
             runId,
+            createdAt,
             paths,
             runStatus,
             now,

package/dist/run/terminal-contract.d.ts

@@ -22,4 +22,14 @@ type ActorVerdict = "passed" | "blocked" | "failed";
  * divergent verdict logic would let the two routes disagree about what "passed" means.
  */
 export declare function extractLocalActorVerdict(transcript: string, verdictNonce: string): ActorVerdict | null;
+/**
+ * The same search over text that arrives in pieces and is not kept: the terminal route reads
+ * output past its transcript cap through this. Each piece is normalized and loses its whitespace
+ * as the whole transcript does above, and the end of the previous piece is carried so a marker
+ * split between pieces is found. The first marker wins, as above.
+ */
+export declare function createLocalActorVerdictScanner(verdictNonce: string): {
+    push(text: string): void;
+    verdict(): ActorVerdict | null;
+};
 export {};

package/dist/run/terminal-contract.js

@@ -27,6 +27,9 @@ export function normalizeLocalActorTranscript(transcript) {
         .replace(/\r/g, "\n")
         .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, "");
 }
+// The nonce is mandatory: a bare HUMANISH_ACTOR_VERDICT=<status> marker echoed by an actor (or
+// replayed from untrusted text) must never satisfy verdict extraction.
+const verdictPattern = (verdictNonce) => new RegExp(`HUMANISH_ACTOR_VERDICT=(passed|blocked|failed)HUMANISH_ACTOR_NONCE=${escapeRegExp(verdictNonce)}`, "i");
 /**
  * Extract the per-run verdict from a normalized transcript: the agent must print exactly
  * `HUMANISH_ACTOR_VERDICT=<status> HUMANISH_ACTOR_NONCE=<nonce>`, and the nonce is mandatory so a
@@ -35,13 +38,28 @@ export function normalizeLocalActorTranscript(transcript) {
  * divergent verdict logic would let the two routes disagree about what "passed" means.
  */
 export function extractLocalActorVerdict(transcript, verdictNonce) {
-    const compactTranscript = transcript.replace(/\s+/g, "");
-    // The per-run nonce is mandatory: a bare HUMANISH_ACTOR_VERDICT=<status>
-    // marker echoed by an actor (or replayed from untrusted text) must never
-    // satisfy verdict extraction.
-    const match = new RegExp(`HUMANISH_ACTOR_VERDICT=(passed|blocked|failed)HUMANISH_ACTOR_NONCE=${escapeRegExp(verdictNonce)}`, "i").exec(compactTranscript);
-    if (!match) {
-        return null;
-    }
-    return match[1]?.toLowerCase();
+    const match = verdictPattern(verdictNonce).exec(transcript.replace(/\s+/g, ""));
+    return match?.[1]?.toLowerCase() ?? null;
+}
+/**
+ * The same search over text that arrives in pieces and is not kept: the terminal route reads
+ * output past its transcript cap through this. Each piece is normalized and loses its whitespace
+ * as the whole transcript does above, and the end of the previous piece is carried so a marker
+ * split between pieces is found. The first marker wins, as above.
+ */
+export function createLocalActorVerdictScanner(verdictNonce) {
+    const pattern = verdictPattern(verdictNonce);
+    const carried = `HUMANISH_ACTOR_VERDICT=blockedHUMANISH_ACTOR_NONCE=${verdictNonce}`.length - 1;
+    let tail = "";
+    let found = null;
+    return {
+        push(text) {
+            if (found)
+                return;
+            const window = tail + normalizeLocalActorTranscript(text).replace(/\s+/g, "");
+            found = pattern.exec(window)?.[1]?.toLowerCase() ?? null;
+            tail = window.slice(-carried);
+        },
+        verdict: () => found,
+    };
 }

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)) {

package/dist/study/composition-rules.js

@@ -4,13 +4,22 @@
 // a library caller's config itself, under its route's error codes. The planners call the shared
 // checks in study/validation.ts and desktopCliProductReason below. The other subject rules here have
 // planner counterparts whose conditions and wording differ (clone serve and repo, local-tree
-// target, in-process fan-out, loopback targets, scripted scenario.ref).
+// target, in-process fan-out, loopback targets, scripted `scenario`).
 import { isLoopbackUrl } from "./parse/subject.js";
 import { REPO_SLUG_PATTERN } from "./parse/values.js";
 import { declaredTargets } from "./plan-participants.js";
 import { actorResolvesToComputerUse, actorResolvesToScriptedBrowser, actorResolvesToTerminal, computerUseParticipantCount, registeredComputerUseActors, registeredScriptedBrowserActors, registeredTerminalActors, isComputerUseComposition, } from "./routing.js";
 import { cloneTargetValidationReason, computerUseValidationReason, sharedWorldValidationReason, } from "./validation.js";
-import { actorOf, participantList, declaredParticipantCount, surfaceCount, modeOf, scenarioRefOf, declaresSharedWorld, } from "./study-fields.js";
+import { participantList, declaredParticipantCount } from "./study-fields.js";
+/**
+ * The count a scripted or terminal composition reads: its surfaces, or a participant count.
+ * parse/front.ts refuses `participants` on route: scripted and route: terminal, and `surfaces` off
+ * route: scripted, but a study can declare a route its composition does not take, and these rules
+ * run before parseStudy compares the two. migrate's view of a v2 file reaches them the same way.
+ */
+function participantOrSurfaceCount(config) {
+    return declaredParticipantCount(config) ?? config.surfaces?.length;
+}
 /** The first composition rule a config breaks, in the parser's order, or null. */
 export function compositionReason(config) {
     return (thisRepoValidationReason(config) ??
@@ -25,7 +34,7 @@ export function compositionReason(config) {
         (isComputerUseComposition(config) ? computerUseValidationReason(config) : null) ??
         // Whenever shared world is declared, not only when it routes, so a half-declared shared world
         // fails with a precise reason instead of running as independent participants.
-        (declaresSharedWorld(config) ? sharedWorldValidationReason(config) : null) ??
+        (config.route === "shared-world" ? sharedWorldValidationReason(config) : null) ??
         desktopCliValidationReason(config) ??
         terminalValidationReason(config) ??
         cloneActorValidationReason(config));
@@ -39,7 +48,7 @@ function thisRepoValidationReason(config) {
         if (config.execution?.target) {
             return "`execution.target` applies only to clone/app-url/local-app subjects; this-repo studies run locally.";
         }
-        if (modeOf(config) === "live") {
+        if (config.mode === "live") {
             return THIS_REPO_DRY_RUN_ONLY;
         }
     }
@@ -54,7 +63,7 @@ function thisRepoValidationReason(config) {
 // planComputerUseStudy refuses it with HUMANISH_COMPUTER_USE_LOCAL_APP_NO_EXECUTOR.
 function localAppValidationReason(config) {
     if (config.subject.source === "local-app") {
-        const type = actorOf(config)?.type ?? "";
+        const type = config.actor?.type ?? "";
         if (config.execution?.target !== undefined && config.execution.target !== "local") {
             return "A local-app subject drives a local dev server in this process, with no E2B desktop. Set `execution.target: local` or omit it. To run on a hosted desktop, use an app-url subject with `execution.target: e2b-desktop`.";
         }
@@ -62,7 +71,7 @@ function localAppValidationReason(config) {
             return `actor.type must be a registered computer-use actor for local-app subjects (one of: ${registeredComputerUseActors().join(", ")}); the caller's custom executor runs the computer-use loop. Got "${type}".`;
         }
         if (computerUseParticipantCount(config) > 1) {
-            return "Fan-out to more than one participant is not supported on the in-process/local-app route: fan-out provisions one independent E2B desktop per participant, which the in-process route deliberately skips. Set participants to 1 and drop participants (use an app-url or clone subject on execution.target: e2b-desktop for fan-out).";
+            return "Fan-out to more than one participant is not supported on the in-process/local-app route: fan-out provisions one independent E2B desktop per participant, which the in-process route deliberately skips. Remove `participants`, or set `participants: 1`. For fan-out, use an app-url or clone subject on execution.target: e2b-desktop.";
         }
         if (participantList(config) !== undefined) {
             return "`participants` (fan-out roster) is not supported on the in-process/local-app route: it provisions one E2B desktop per participant, which this route skips. Use an app-url or clone subject with execution.target: e2b-desktop.";
@@ -78,17 +87,17 @@ function localAppValidationReason(config) {
 // app; a computer-use actor drives a hosted desktop browser. Fail closed on mis-configs.
 function appUrlValidationReason(config) {
     if (config.subject.source === "app-url") {
-        const type = actorOf(config)?.type ?? "";
+        const type = config.actor?.type ?? "";
         if (actorResolvesToScriptedBrowser(type)) {
             // Scripted-browser route (all fail-closed, so claims match mechanism: a field that cannot act on
             // this route is rejected, never silently ignored).
             if (config.execution?.target !== undefined && config.execution.target !== "local") {
                 return "A scripted-browser actor on an app-url subject runs on this machine. Set `execution.target: local` or omit it. To run scripted steps on a hosted desktop, use a clone subject.";
             }
-            if (!scenarioRefOf(config)) {
+            if (!config.scenario) {
                 return "A scripted-browser study needs `scenario`: the actor runs the browser steps in that scenario file.";
             }
-            if ((surfaceCount(config) ?? 1) > 2) {
+            if ((participantOrSurfaceCount(config) ?? 1) > 2) {
                 return "A scripted-browser study takes `surfaces` 1 (desktop) or 2 (desktop and mobile). Higher counts are not supported yet.";
             }
             if (config.policies?.redactScreenshots === true) {
@@ -109,9 +118,8 @@ function appUrlValidationReason(config) {
                 return `actor.type must be a registered computer-use actor for app-url × e2b-desktop studies (one of: ${registeredComputerUseActors().join(", ")}); for local scripted execution use a registered scripted-browser actor (${registeredScriptedBrowserActors().join(", ")}). Got "${type}".`;
             }
             // Multi-participant fan-out is consumed on this route (`per-lane-worlds`; the shared cua
-            // cross-validation below enforces `lanes`/`count` XOR rules, the 16 cap, and the
-            // per-participant target gates, and the allowPublicTargets+N>1 rejection for ambiguous one-target
-            // fan-out).
+            // cross-validation below enforces the 16 cap, the per-participant target gates, and the
+            // allowPublicTargets+N>1 rejection for ambiguous one-target fan-out).
             // Loopback by default; an owner may declare a public/preview target via policies.
             const targets = [config.subject.appUrl ?? "", ...declaredTargets(config)];
             const unsafeTarget = targets.find((target) => !config.policies?.allowPublicTargets && !isLoopbackUrl(target));
@@ -124,8 +132,7 @@ function appUrlValidationReason(config) {
 }
 // Scripted-browser actors on any other subject: only a provisioned clone on e2b-desktop.
 function scriptedBrowserValidationReason(config) {
-    if (config.subject.source !== "app-url" &&
-        actorResolvesToScriptedBrowser(actorOf(config)?.type)) {
+    if (config.subject.source !== "app-url" && actorResolvesToScriptedBrowser(config.actor?.type)) {
         if (config.subject.source !== "clone") {
             return "scripted-browser actors require `subject.source: app-url` (a running app at a loopback URL) or `subject.source: clone` with `execution.target: e2b-desktop` (a provisioned synthetic subject).";
         }
@@ -142,16 +149,18 @@ function scriptedBrowserValidationReason(config) {
         if (!REPO_SLUG_PATTERN.test(repo)) {
             return `subject.repos[0] must be an owner/repo slug (got "${repo}").`;
         }
-        if (config.subject.topology !== undefined) {
+        // migrate converts a v2 file's `subject.topology: shared-world` to `route: shared-world`, and
+        // refuses it here with the v2 parser's message.
+        if (config.route === "shared-world") {
             return "A clone scripted-browser study does not support `subject.topology` yet: it runs one synthetic subject for its scripted actor. Remove `subject.topology`.";
         }
         if (config.subject.clone?.fanout !== undefined || config.subject.clone?.keep === true) {
             return "A clone scripted-browser study does not support `subject.clone.fanout` or `subject.clone.keep` yet: its subject is always one sandbox, removed after the run.";
         }
-        if (!scenarioRefOf(config)) {
+        if (!config.scenario) {
             return "A scripted-browser study needs `scenario`: the actor runs the browser steps in that scenario file.";
         }
-        if ((surfaceCount(config) ?? 1) > 2) {
+        if ((participantOrSurfaceCount(config) ?? 1) > 2) {
             return "A scripted-browser study takes `surfaces` 1 (desktop) or 2 (desktop and mobile). Higher counts are not supported yet.";
         }
         if (participantList(config) !== undefined) {
@@ -183,7 +192,7 @@ function scriptedBrowserValidationReason(config) {
 function cloneComputerUseValidationReason(config) {
     if (config.subject.source === "clone" &&
         config.execution?.target === "e2b-desktop" &&
-        actorResolvesToComputerUse(actorOf(config)?.type)) {
+        actorResolvesToComputerUse(config.actor?.type)) {
         if (!config.subject.serve) {
             return "A clone subject on the computer-use route needs `subject.serve` (start and url): humanish starts the app in the sandbox before the participant opens it.";
         }
@@ -195,8 +204,8 @@ function cloneComputerUseValidationReason(config) {
             return `subject.repos[0] must be an owner/repo slug (got "${repo}").`;
         }
         // Fan-out is consumed here: N participants each clone the same single repo into their own
-        // E2B desktop (`per-lane-worlds`). The shared cua cross-validation below enforces the
-        // `lanes`/`count` rules and the 16 cap; the single-repo rule above is unchanged.
+        // E2B desktop (`per-lane-worlds`). The shared cua cross-validation below enforces the 16 cap;
+        // the single-repo rule above is unchanged.
     }
     return null;
 }
@@ -210,8 +219,8 @@ function localTreeValidationReason(config) {
         if (config.execution?.target !== "e2b-desktop") {
             return "local-tree subjects require `execution.target: e2b-desktop`: the packed working tree is provisioned and served inside a hosted desktop sandbox; there is no local route for a local-tree subject.";
         }
-        if (!actorResolvesToComputerUse(actorOf(config)?.type)) {
-            return `actor.type must be a registered computer-use actor for local-tree subjects (one of: ${registeredComputerUseActors().join(", ")}); the actor drives the hosted desktop that serves the packed working tree. Got "${actorOf(config)?.type ?? ""}".`;
+        if (!actorResolvesToComputerUse(config.actor?.type)) {
+            return `actor.type must be a registered computer-use actor for local-tree subjects (one of: ${registeredComputerUseActors().join(", ")}); the actor drives the hosted desktop that serves the packed working tree. Got "${config.actor?.type ?? ""}".`;
         }
     }
     return null;
@@ -238,7 +247,7 @@ function desktopCliValidationReason(config) {
         if (config.execution?.target !== undefined && config.execution.target !== "e2b-desktop") {
             return "A desktop-cli subject runs on a hosted desktop. Set `execution.target: e2b-desktop` or omit it.";
         }
-        if (!actorResolvesToComputerUse(actorOf(config)?.type ?? "")) {
+        if (!actorResolvesToComputerUse(config.actor?.type ?? "")) {
             return "desktop-cli subjects need a registered computer-use actor: the participant reads the screen and types, which is what makes an interactive surface studiable at all.";
         }
         const install = config.subject.product.install;
@@ -255,14 +264,14 @@ function desktopCliValidationReason(config) {
 // fan-out lands.
 function terminalValidationReason(config) {
     if (config.subject.source === "terminal-product") {
-        const type = actorOf(config)?.type ?? "";
+        const type = config.actor?.type ?? "";
         if (config.execution?.target !== undefined && config.execution.target !== "e2b-terminal") {
             return "A terminal-product subject runs its agent in an E2B shell. Set `execution.target: e2b-terminal` or omit it; `local` and `e2b-desktop` are not supported.";
         }
         if (!actorResolvesToTerminal(type)) {
             return `actor.type must be a registered terminal actor for terminal-product subjects (one of: ${registeredTerminalActors().join(", ")}). Got "${type}".`;
         }
-        if ((declaredParticipantCount(config) ?? 1) > 1) {
+        if ((participantOrSurfaceCount(config) ?? 1) > 1) {
             return "Terminal fan-out to more than one participant is not supported yet; set participants to 1.";
         }
     }
@@ -271,7 +280,7 @@ function terminalValidationReason(config) {
         // mis-config: reject, never silently mishandle (mirrors app-url's e2b-desktop pairing rule).
         return "`execution.target: e2b-terminal` requires `subject.source: terminal-product` with a registered terminal actor.";
     }
-    else if (actorResolvesToTerminal(actorOf(config)?.type)) {
+    else if (actorResolvesToTerminal(config.actor?.type)) {
         // A registered terminal actor on a non-terminal-product subject: rejected, never ignored (the
         // terminal agent only studies a declared terminal-product from public surfaces).
         return "terminal actors require `subject.source: terminal-product` (a CLI/product the agent studies from public surfaces); other subjects are not supported on this route.";
@@ -283,7 +292,7 @@ function terminalValidationReason(config) {
 // Terminal actors were already refused above with their own message.
 function cloneActorValidationReason(config) {
     if (config.subject.source === "clone") {
-        const type = actorOf(config)?.type ?? "";
+        const type = config.actor?.type ?? "";
         if (!actorResolvesToComputerUse(type) && !actorResolvesToScriptedBrowser(type)) {
             return `clone subjects need a registered computer-use actor (one of: ${registeredComputerUseActors().join(", ")}) or scripted-browser actor (one of: ${registeredScriptedBrowserActors().join(", ")}); humanish clones and serves the app for that participant to drive. Got "${type}".`;
         }

package/dist/study/config.d.ts

@@ -1,22 +1,38 @@
-import { type StudyConfig, type StudyParseResult } from "./types.js";
-/** The message for a humanish.lab.v2 document, which the package and the CLI no longer run. */
-export declare const V2_UNSUPPORTED_MESSAGE = "This is a humanish.lab.v2 study, which humanish no longer reads. Convert its file with humanish migrate <path>.";
+import { type StudyConfig, type StudyParseFailure, type StudyParseResult } from "./types.js";
 /**
  * The package's study parser (src/index.ts) and the one discovery uses: a humanish.study.v3
  * document. It refuses a humanish.lab.v2 one with HUMANISH_STUDY_V2_UNSUPPORTED.
  */
 export declare function parseStudy(raw: unknown): StudyParseResult;
+interface StudyV3Options {
+    /**
+     * `report`, for `humanish migrate`: list the fields the route does not read in `inert`, in place
+     * of refusing the study for them. A shared world may then give `participants` as a count or
+     * leave it out, as a v2 file could (readStudyFront).
+     */
+    readonly inert?: "refuse" | "report";
+}
+type StudyV3ParseResult = {
+    ok: true;
+    config: StudyConfig;
+    warnings: string[];
+    inert?: string[];
+} | StudyParseFailure;
 /**
- * Validate a parsed YAML object, humanish.study.v3 or humanish.lab.v2, into a StudyConfig. Pure:
- * the caller owns file IO. Structural validation only. Fields the engine does not yet consume are
- * accepted but reported in `warnings` so `study show` never silently swallows a setting that does
- * nothing. The v2 parser's tests call it directly; migrate reads v2 files through migrate/v2.ts.
+ * Validate a humanish.study.v3 document into a StudyConfig. Pure: the caller owns file IO. Fields the
+ * route does not read refuse the study; migrate's report mode lists them in `inert` instead.
  */
-export declare function parseStudyDocument(raw: unknown): StudyParseResult;
+export declare function parseStudyV3(raw: Record<string, unknown>, options?: StudyV3Options): StudyV3ParseResult;
+/** Why runStudy refuses a config before anything runs. */
+interface ConfigRefusal {
+    readonly code: "HUMANISH_STUDY_V2_UNSUPPORTED" | "HUMANISH_STUDY_INVALID";
+    readonly message: string;
+}
 /**
- * The checks that read more than one section of a parsed config, and the defaults they fill:
- * shared-world `execution.concurrency`, `comms.email.recipients` and the local browser's defaults.
- * parseV2 runs them once every section has parsed. parse/study.ts runs them on its v2 view of a v3
- * study.
+ * Why runStudy refuses a config a library caller passes, or undefined: a humanish.lab.v2 config,
+ * one that still sets a StudyConfig field of humanish 0.110, one with no `actor` object, and one
+ * whose `route` is not the route its subject and actor take, with parseStudy's message. A planner
+ * reads only the v3 fields, so a budget left in `execution.caps` would otherwise run uncapped.
  */
-export declare function checkStudyConfig(config: StudyConfig): StudyParseResult;
+export declare function libraryConfigRefusal(config: StudyConfig): ConfigRefusal | undefined;
+export {};