humanish 0.108.0 → 0.109.1

package/dist/{lab → study}/preflight.js

@@ -4,24 +4,24 @@ import {} from "./types.js";
 import { runPublicPreviewPreflight, runSandboxLoopbackPreflight } from "./preflight-probes.js";
 import { digest, fail, finalize, STUDY_CHECK_SCHEMA } from "./preflight-result.js";
 import { routeOf } from "./plan.js";
-import { resolveLabManifest } from "./discover.js";
+import { resolveStudyManifest } from "./discover.js";
 import { rosterOf } from "./parse/actors.js";
 const DEFAULT_PREFLIGHT_TIMEOUT_MS = 30_000;
-export async function runLabPreflight(options) {
+export async function runStudyPreflight(options) {
     const cwd = path.resolve(options.cwd);
     const reachability = options.reachability ?? "metadata";
     const timeoutMs = options.timeoutMs ?? DEFAULT_PREFLIGHT_TIMEOUT_MS;
-    const resolved = await resolveLabManifest(cwd, options.lab);
+    const resolved = await resolveStudyManifest(cwd, options.study);
     if (!resolved.ok) {
         return {
             schema: STUDY_CHECK_SCHEMA,
             ok: false,
             cwd,
-            study: options.lab,
+            study: options.study,
             reachability,
             checks: [
                 {
-                    name: "lab manifest",
+                    name: "study file",
                     ok: false,
                     message: resolved.error.message,
                 },
@@ -36,8 +36,8 @@ export async function runLabPreflight(options) {
     const route = routeOf(resolved.config);
     const ctx = {
         cwd,
-        lab: options.lab,
-        labId: resolved.config.id,
+        study: options.study,
+        studyId: resolved.config.id,
         origin: resolved.origin,
         path: resolved.path,
         config: resolved.config,
@@ -47,7 +47,7 @@ export async function runLabPreflight(options) {
         env: options.env ?? process.env,
         hooks: options.hooks ?? {},
         checks: [
-            { name: "lab manifest", ok: true, message: `resolved ${resolved.origin} lab manifest` },
+            { name: "study file", ok: true, message: `resolved ${resolved.origin} study file` },
             { name: "route", ok: true, message: `selected the ${route} route` },
         ],
         targets: collectTargets(resolved.config),

package/dist/{lab → study}/requirements.d.ts

@@ -1,4 +1,4 @@
-import type { LabPlan, Requirement } from "./plan-types.js";
+import type { StudyPlan, Requirement } from "./plan-types.js";
 /** The `key` requirements whose value `env` lacks, OPENAI_API_KEY before E2B_API_KEY. */
 export declare function missingKeys(requirements: readonly Requirement[], env: Record<string, string | undefined>): string[];
 /** The subject env names the requirements list and `env` lacks, in declaration order. */
@@ -13,8 +13,8 @@ export declare function requiredSubjectEnv(requirements: readonly Requirement[])
 /**
  * The provider keys a live run of `plan` is known to read: its `key` and `key-one-of` names, its
  * subject env, the external catch's token variable, ANTHROPIC_API_KEY for a Claude Code
- * participant, and OPENAI_API_KEY when automatic analysis runs on OpenAI. `lab run` prints a
+ * participant, and OPENAI_API_KEY when automatic analysis runs on OpenAI. `run` prints a
  * key-source line for these only. Discovery still fills every key it finds: other readers, such as
  * a declared scorer's host code, are not in the plan.
  */
-export declare function keyNamesOf(plan: LabPlan): ReadonlySet<string>;
+export declare function keyNamesOf(plan: StudyPlan): ReadonlySet<string>;

package/dist/{lab → study}/requirements.js

@@ -30,7 +30,7 @@ export function requiredSubjectEnv(requirements) {
 /**
  * The provider keys a live run of `plan` is known to read: its `key` and `key-one-of` names, its
  * subject env, the external catch's token variable, ANTHROPIC_API_KEY for a Claude Code
- * participant, and OPENAI_API_KEY when automatic analysis runs on OpenAI. `lab run` prints a
+ * participant, and OPENAI_API_KEY when automatic analysis runs on OpenAI. `run` prints a
  * key-source line for these only. Discovery still fills every key it finds: other readers, such as
  * a declared scorer's host code, are not in the plan.
  */

package/dist/study/route-inputs.d.ts

@@ -0,0 +1,28 @@
+import type { InternalRunStudyOptions } from "../run-study.js";
+import type { RunScorerProvenance } from "../run/bundle.js";
+import { type AdapterScorerModule } from "./adapter-scorer-loader.js";
+import type { StudyDeps } from "./study-deps.js";
+import type { StudyEvent } from "./run-study-events.js";
+import type { ComputerUseRunInput } from "../routes/computer-use/types.js";
+import type { ScriptedRunInput } from "../routes/scripted/types.js";
+import type { SharedWorldRunInput } from "../routes/shared-world/types.js";
+import type { TerminalRunInput } from "../routes/terminal/types.js";
+export declare function computerUseInput(options: InternalRunStudyOptions, deps: StudyDeps, emit: StudyEmit | undefined): ComputerUseRunInput;
+export declare function scriptedInput(options: InternalRunStudyOptions, deps: StudyDeps, emit: StudyEmit | undefined): ScriptedRunInput;
+export declare function terminalInput(options: InternalRunStudyOptions, deps: StudyDeps, emit: StudyEmit | undefined): TerminalRunInput;
+export declare function sharedWorldInput(options: InternalRunStudyOptions, deps: StudyDeps, emit: StudyEmit | undefined): SharedWorldRunInput;
+/** A scorer the CLI loads after the route's local checks, and the provenance it stamps on the run. */
+export type LateScorer = Pick<InternalRunStudyOptions, "scorer" | "scorerProvenance">;
+/** Narrows RunStudyOptions.scorer to the context the route passes (adapter-scorer-loader.ts). */
+type NarrowScorer<S> = (scorer: AdapterScorerModule) => S;
+/**
+ * A route's input with a scorer loaded after admission, and the scorer's provenance, as if the
+ * caller had passed them up front. The rest of the input is the one the route's checks admitted.
+ */
+export declare function withLateScorer<S, I extends {
+    scorer?: S;
+    scorerProvenance?: RunScorerProvenance;
+}>(input: I, late: LateScorer | undefined, narrow: NarrowScorer<S>): I;
+/** Reports a StudyEvent to onEvent without waiting (normalizeRunStudyOptions builds it). */
+type StudyEmit = (event: StudyEvent) => void;
+export {};

package/dist/{lab → study}/route-inputs.js

@@ -1,4 +1,4 @@
-// What each route's run takes from runLab's options: the shared run settings, the typed options
+// What each route's run takes from runStudyWith's options: the shared run settings, the typed options
 // the route reads, the event emitter, the test seams and the declared scorer's provenance.
 import { browserRouteScorer, terminalRouteScorer, } from "./adapter-scorer-loader.js";
 export function computerUseInput(options, deps, emit) {

package/dist/{lab → study}/routing.d.ts

@@ -1,4 +1,4 @@
-import type { LabConfig } from "./types.js";
+import type { StudyConfig } from "./types.js";
 export declare const MAX_COMPUTER_USE_PARTICIPANTS = 16;
 export declare function actorResolvesToComputerUse(type: string | undefined): boolean;
 export declare function registeredComputerUseActors(): string[];
@@ -13,7 +13,7 @@ export declare function registeredTerminalActors(): string[];
  * a homogeneous `count`, else 1. The single source of truth shared by the parser, the engine,
  * and the pre-flight plan so the participant count is computed the same way everywhere.
  */
-export declare function computerUseParticipantCount(config: LabConfig): number;
+export declare function computerUseParticipantCount(config: StudyConfig): number;
 /**
  * A participant's id: its declared roster id, else `lane-NN` (independent participants) or `role-NN`
  * (shared-world participants) from its 0-based position. The parser's filled email recipients and
@@ -29,7 +29,7 @@ export declare function participantIdAt(index: number, declared: string | undefi
  * bare app-url fallback to the computer-use route so library-API configs with unknown actors still
  * hit its fail-closed ACTOR_UNSUPPORTED.)
  */
-export declare function isComputerUseComposition(config: LabConfig): boolean;
+export declare function isComputerUseComposition(config: StudyConfig): boolean;
 /**
  * True when this config routes to the shared-world route: a clone or local-tree subject
  * on a hosted desktop whose first actor resolves to a computer-use actor and that declares the
@@ -39,9 +39,9 @@ export declare function isComputerUseComposition(config: LabConfig): boolean;
  * clone/local-tree × e2b-desktop × computer-use composition without `topology: shared-world` stays per-lane-worlds
  * (the computer-use route); the topology declaration is the override switch.
  */
-export declare function isSharedWorldComposition(config: LabConfig): boolean;
+export declare function isSharedWorldComposition(config: StudyConfig): boolean;
 /** The getHost provisioned-subject shared-world shape (clone/local-tree served + exposed in-sandbox). */
-export declare function isProvisionedSharedWorldComposition(config: LabConfig): boolean;
+export declare function isProvisionedSharedWorldComposition(config: StudyConfig): boolean;
 /**
  * The external-public shared-world shape: a real public deployment used directly as
  * the shared plane: `source: app-url` + `topology: shared-world` + a computer-use actor on
@@ -51,7 +51,7 @@ export declare function isProvisionedSharedWorldComposition(config: LabConfig):
  * half-declared external-public config still routes here to get its precise fail-closed reason
  * rather than silently downgrading to the per-participant computer-use route).
  */
-export declare function isExternalPublicSharedWorldComposition(config: LabConfig): boolean;
+export declare function isExternalPublicSharedWorldComposition(config: StudyConfig): boolean;
 /**
  * Resolve a shared-world participant's entry URL from `serve.url` and its roster entry's `entry`
  * (a relative path or a same-origin absolute URL). Returns null when the result is not a
@@ -64,19 +64,19 @@ export declare function resolveEntryUrl(serveUrl: string, entry: string | undefi
  * absent; the parse layer enforces that pairing). Mirror of isComputerUseComposition; the single
  * source of truth for routeOf and the warning logic.
  */
-export declare function isScriptedBrowserComposition(config: LabConfig): boolean;
-export declare function isProvisionedScriptedBrowserComposition(config: LabConfig): boolean;
+export declare function isScriptedBrowserComposition(config: StudyConfig): boolean;
+export declare function isProvisionedScriptedBrowserComposition(config: StudyConfig): boolean;
 /**
  * True when this config routes to the terminal-product backend: a terminal-product subject whose
  * first actor resolves to a registered terminal actor (execution.target e2b-terminal or absent;
  * the parse layer enforces that pairing). Mirror of isComputerUseComposition/isScriptedBrowserComposition;
  * the single source of truth for routeOf and the warning logic.
  */
-export declare function isTerminalProductComposition(config: LabConfig): boolean;
-/** The five execution paths a lab can take. */
-export type LabRoute = "preview" | "computer-use" | "shared-world" | "terminal" | "scripted";
+export declare function isTerminalProductComposition(config: StudyConfig): boolean;
+/** The five execution paths a study can take. */
+export type StudyRoute = "preview" | "computer-use" | "shared-world" | "terminal" | "scripted";
 /**
  * The route a config takes. It never refuses: a config no route can run still gets the route
  * whose own checks refuse it with the most precise reason.
  */
-export declare function routeOf(config: LabConfig): LabRoute;
+export declare function routeOf(config: StudyConfig): StudyRoute;

package/dist/{lab/run-lab-events.d.ts → study/run-study-events.d.ts}

@@ -1,8 +1,8 @@
 import type { CuaParticipantPlan } from "../routes/computer-use/types.js";
 import type { SubjectPhaseEvent } from "../subject/steps.js";
-import type { InternalRunLabOptions } from "../run-lab.js";
-import type { LabRoute } from "./plan.js";
-import type { LabConfig } from "./types.js";
+import type { InternalRunStudyOptions } from "../run-study.js";
+import type { StudyRoute } from "./plan.js";
+import type { StudyConfig } from "./types.js";
 /** One participant, as the options' callbacks see it. */
 export interface ParticipantRef {
     readonly id: string;
@@ -19,12 +19,12 @@ export type SetupTarget = {
 };
 /**
  * What a run reports while it runs. `plan` comes from computer use only; the other routes run from
- * the lab plan but do not emit it. `subject-phase` comes from computer use (participant target)
+ * the study plan but do not emit it. `subject-phase` comes from computer use (participant target)
  * and shared world (subject target).
  */
-export type LabEvent = {
+export type StudyEvent = {
     type: "plan";
-    route: LabRoute;
+    route: StudyRoute;
     participants: readonly {
         id: string;
         persona: string;
@@ -50,12 +50,12 @@ export type LabEvent = {
  * analysis API key. A callback can hold any of them, and its warning is appended after the route
  * sanitized its own.
  */
-export declare function knownSecretValues(config: LabConfig, options: InternalRunLabOptions, forwardedEnv: Readonly<Record<string, string | undefined>> | undefined): string[];
+export declare function knownSecretValues(config: StudyConfig, options: InternalRunStudyOptions, forwardedEnv: Readonly<Record<string, string | undefined>> | undefined): string[];
 /**
  * The emitter the route hook bags call, or undefined without onEvent. It calls onEvent and never
  * waits for it: a throw or a rejected promise becomes a run warning, scrubbed of `secretValues`.
  */
-export declare function labEventEmitter(onEvent: ((event: LabEvent) => void | Promise<void>) | undefined, warnings: string[], secretValues: () => string[]): ((event: LabEvent) => void) | undefined;
+export declare function studyEventEmitter(onEvent: ((event: StudyEvent) => void | Promise<void>) | undefined, warnings: string[], secretValues: () => string[]): ((event: StudyEvent) => void) | undefined;
 /** The computer-use participant plan as a `plan` event: ids, personas, devices and digests. */
-export declare function planEvent(plan: CuaParticipantPlan): LabEvent;
-export declare function phaseEvent(event: SubjectPhaseEvent, target: SetupTarget): LabEvent;
+export declare function planEvent(plan: CuaParticipantPlan): StudyEvent;
+export declare function phaseEvent(event: SubjectPhaseEvent, target: SetupTarget): StudyEvent;

package/dist/{lab/run-lab-events.js → study/run-study-events.js}

@@ -1,5 +1,5 @@
-// What a run reports through RunLabOptions.onEvent, and how a callback failure becomes a run
-// warning. normalizeRunLabOptions (run-lab-options.ts) builds the emitter and hands it to the
+// What a run reports through RunStudyOptions.onEvent, and how a callback failure becomes a run
+// warning. normalizeRunStudyOptions (run-study-options.ts) builds the emitter and hands it to the
 // route hook bags it maps; the event values are built here.
 import { redactText, scrubLiterals, toErrorMessage } from "../evidence/redaction.js";
 /**
@@ -26,7 +26,7 @@ export function knownSecretValues(config, options, forwardedEnv) {
  * The emitter the route hook bags call, or undefined without onEvent. It calls onEvent and never
  * waits for it: a throw or a rejected promise becomes a run warning, scrubbed of `secretValues`.
  */
-export function labEventEmitter(onEvent, warnings, secretValues) {
+export function studyEventEmitter(onEvent, warnings, secretValues) {
     if (onEvent === undefined)
         return undefined;
     return (event) => {
@@ -43,7 +43,7 @@ export function labEventEmitter(onEvent, warnings, secretValues) {
             catch {
                 detail = "the thrown value has no message";
             }
-            warnings.push(`RunLabOptions.onEvent failed on ${type}: ${detail}`);
+            warnings.push(`RunStudyOptions.onEvent failed on ${type}: ${detail}`);
         };
         try {
             const returned = onEvent(event);

package/dist/{lab/run-lab-homes.d.ts → study/run-study-homes.d.ts}

@@ -1,11 +1,11 @@
 import type { CuaExecutor, CuaProvider } from "../actors/computer-use/loop.js";
 import type { E2BDesktopSandbox } from "../substrates/e2b/sdk.js";
 import type { AdapterScorerModule } from "./adapter-scorer-loader.js";
-import type { LabEvent, ParticipantRef, SetupTarget } from "./run-lab-events.js";
-import type { LabConfig } from "./types.js";
+import type { StudyEvent, ParticipantRef, SetupTarget } from "./run-study-events.js";
+import type { StudyConfig } from "./types.js";
 /** What `createProvider` receives for each participant. */
 export interface ProviderContext {
-    readonly config: LabConfig;
+    readonly config: StudyConfig;
     readonly participant: ParticipantRef;
     readonly executor: CuaExecutor;
 }
@@ -13,7 +13,7 @@ export type ProviderFactory = (ctx: ProviderContext) => Promise<CuaProvider>;
 /** The caller's executor for an in-process run, built once for the run's single participant. */
 export interface InProcessDriver {
     executor: (ctx: {
-        config: LabConfig;
+        config: StudyConfig;
         appUrl: string;
     }) => Promise<CuaExecutor>;
 }
@@ -26,7 +26,7 @@ interface StreamEventIds {
     recordId: string;
     streamId: string;
 }
-type StreamEventFields = (StreamEventIds & {
+export type StreamEvent = (StreamEventIds & {
     type: "ready";
     sandboxId: string;
     /** Runtime only: carries an auth key and must never be persisted. */
@@ -34,17 +34,8 @@ type StreamEventFields = (StreamEventIds & {
 }) | (StreamEventIds & {
     type: "ended";
 });
-export type StreamEvent = StreamEventFields & {
-    /**
-     * @deprecated Use `recordId`, which holds the same value. Reading it warns once per process; the
-     * next minor removes it.
-     */
-    readonly simId: string;
-};
-/** A stream event as the routes report it, with `simId` as a getter over `recordId`. */
-export declare function streamEvent(fields: StreamEventFields): StreamEvent;
 /** The options with a typed home, common to every route. */
-export interface RunLabHomes {
+export interface RunStudyHomes {
     /** Keys and subject env for the run. Defaults to process.env. */
     env?: Readonly<Record<string, string | undefined>>;
     /**
@@ -59,14 +50,14 @@ export interface RunLabHomes {
      * Passive. Never awaited; a throw or a rejected promise becomes a run warning. It observes and
      * changes no output: subject phases still go to stderr.
      */
-    onEvent?: (event: LabEvent) => void | Promise<void>;
+    onEvent?: (event: StudyEvent) => void | Promise<void>;
     /** Awaited after a participant's live stream starts, and again after its sandbox is gone. */
     onStream?: (event: StreamEvent) => Promise<void> | void;
     /** Cancels post-run analysis only. */
     analysisSignal?: AbortSignal;
 }
 /** Brain and in-process driving. An in-process executor needs a provider: it returns no frame. */
-export type RunLabDriving = {
+export type RunStudyDriving = {
     inProcess?: undefined;
     createProvider?: ProviderFactory;
 } | {

package/dist/study/run-study-homes.js

@@ -0,0 +1,3 @@
+// The public RunStudyOptions homes that every route reads: env, scorer, prepareDesktop, onEvent,
+// onStream and analysisSignal, and the brain and in-process driving computer use takes.
+export {};

package/dist/study/run-study-options.d.ts

@@ -0,0 +1,28 @@
+import type { InternalRunStudyOptions, StudyOutcome, RunStudyOptions } from "../run-study.js";
+import { type StudyRoute } from "./plan.js";
+import type { StudyConfig } from "./types.js";
+import { type StudyEvent } from "./run-study-events.js";
+type Refusal = {
+    ok: false;
+    code: "HUMANISH_STUDY_OPTION_UNSUPPORTED" | "HUMANISH_STUDY_V2_UNSUPPORTED";
+    message: string;
+};
+type Normalized = {
+    ok: true;
+    /** The options the route reads: onEvent removed, env copied. */
+    options: InternalRunStudyOptions;
+    /** Filled by onEvent failures while the run runs; runStudyWith appends them to the result. */
+    warnings: string[];
+    /** Calls onEvent and never waits for it, or undefined without onEvent. The routes report through it. */
+    emit: ((event: StudyEvent) => void) | undefined;
+};
+/** The refusal for a field a JavaScript caller passed that RunStudyOptions no longer has. */
+export declare function removedOptionRefusal(options: RunStudyOptions): Refusal | undefined;
+/**
+ * Refuse what the route cannot honor, copy env, and build the emitter onEvent receives through.
+ * Nothing here touches the filesystem, so a refusal leaves no run directory, receipt or sandbox.
+ */
+export declare function normalizeRunStudyOptions(config: StudyConfig, route: StudyRoute, options: InternalRunStudyOptions): Normalized | Refusal;
+/** A refusal in the route's own result envelope, before any run exists. */
+export declare function optionRefusalOutcome(config: StudyConfig, route: StudyRoute, options: RunStudyOptions, refusal: Refusal): StudyOutcome;
+export {};

package/dist/{lab/run-lab-options.js → study/run-study-options.js}

@@ -1,19 +1,19 @@
-// The typed homes on RunLabOptions. runLab calls normalizeRunLabOptions first: it refuses an option
+// The typed homes on RunStudyOptions. runStudyWith calls normalizeRunStudyOptions first: it refuses an option
 // the route cannot honor and otherwise passes the typed options to the route, with env copied and
-// onEvent turned into the emitter. The package's runLab refuses the removed bags
+// onEvent turned into the emitter. The package's runStudy refuses the removed bags
 // (removedOptionRefusal).
 import path from "node:path";
-import { isLocalBrowserLab } from "../substrates/local/runtime-config.js";
-import { resolveLabDryRun } from "./plan.js";
-import { knownSecretValues, labEventEmitter } from "./run-lab-events.js";
+import { isLocalBrowserStudy } from "../substrates/local/runtime-config.js";
+import { resolveStudyDryRun } from "./plan.js";
+import { knownSecretValues, studyEventEmitter } from "./run-study-events.js";
 import { rosterOf } from "./parse/actors.js";
 import { studyResultIdentity } from "../run/study-result.js";
 const unsupported = (option, route, reason) => ({
     ok: false,
     code: "HUMANISH_STUDY_OPTION_UNSUPPORTED",
-    message: `RunLabOptions.${option} is not supported on the ${route} route: ${reason}`,
+    message: `RunStudyOptions.${option} is not supported on the ${route} route: ${reason}`,
 });
-// Fields RunLabOptions no longer has, and where each one's job went.
+// Fields RunStudyOptions no longer has, and where each one's job went.
 const REMOVED_OPTIONS = {
     cuaHooks: "Use scorer, createProvider, inProcess, prepareDesktop, env, onEvent and onStream.",
     scriptedHooks: "Use prepareDesktop and env.",
@@ -21,9 +21,10 @@ const REMOVED_OPTIONS = {
     sharedWorldHooks: "Use scorer, prepareDesktop, env, onEvent and onStream.",
     automaticAnalysis: "Use onEvent (analysis-started, analysis-finished) and analysisSignal.",
     lab: "The humanish CLI sets it.",
+    study: "The humanish CLI sets it.",
     scorerProvenance: "The humanish CLI sets it.",
 };
-/** The refusal for a field a JavaScript caller passed that RunLabOptions no longer has. */
+/** The refusal for a field a JavaScript caller passed that RunStudyOptions no longer has. */
 export function removedOptionRefusal(options) {
     // rerun.laneIds, the older name of rerun.participantIds, would otherwise be ignored, so the rerun
     // would select every failed participant instead of the ones the caller named.
@@ -31,7 +32,7 @@ export function removedOptionRefusal(options) {
         return {
             ok: false,
             code: "HUMANISH_STUDY_OPTION_UNSUPPORTED",
-            message: 'RunLabOptions.rerun.laneIds was removed. Use rerun.participantIds. See docs/contracts/schemas.md, "Library options".',
+            message: '`rerun.laneIds` was removed in 0.107.0. Use `rerun.participantIds`. See docs/contracts/schemas.md, "Library options".',
         };
     const field = Object.keys(REMOVED_OPTIONS).find((key) => Reflect.get(options, key) !== undefined);
     if (field === undefined)
@@ -39,7 +40,7 @@ export function removedOptionRefusal(options) {
     return {
         ok: false,
         code: "HUMANISH_STUDY_OPTION_UNSUPPORTED",
-        message: `RunLabOptions.${field} was removed. ${REMOVED_OPTIONS[field]} See docs/contracts/schemas.md, "Library options".`,
+        message: `\`${field}\` was removed. ${REMOVED_OPTIONS[field]} See docs/contracts/schemas.md, "Library options".`,
     };
 }
 /** Why the route cannot honor an option it was given, or undefined when it can. */
@@ -52,7 +53,7 @@ function unsupportedOption(config, route, options) {
         return unsupported("scorer", route, "only computer use, shared world and terminal score runs.");
     if (createProvider !== undefined && route !== "computer-use")
         return unsupported("createProvider", route, route === "shared-world"
-            ? "shared-world participants run the lab's own brain."
+            ? "shared-world participants run the study's own brain."
             : "only computer use takes a caller brain.");
     if (route === "computer-use") {
         const source = config.subject.source;
@@ -61,7 +62,7 @@ function unsupportedOption(config, route, options) {
                 return unsupported("inProcess", route, "it drives an app-url or local-app subject.");
         }
         if (prepareDesktop !== undefined) {
-            if (isLocalBrowserLab(config))
+            if (isLocalBrowserStudy(config))
                 return unsupported("prepareDesktop", route, "a local VM study has no E2B desktop.");
             // An in-process run has no desktop to prepare.
             if (inProcess !== undefined || source === "local-app")
@@ -83,7 +84,7 @@ function unsupportedOption(config, route, options) {
  * Refuse what the route cannot honor, copy env, and build the emitter onEvent receives through.
  * Nothing here touches the filesystem, so a refusal leaves no run directory, receipt or sandbox.
  */
-export function normalizeRunLabOptions(config, route, options) {
+export function normalizeRunStudyOptions(config, route, options) {
     const refused = unsupportedOption(config, route, options);
     if (refused)
         return refused;
@@ -92,7 +93,7 @@ export function normalizeRunLabOptions(config, route, options) {
     // The route gets this copy, so it is the env a warning is scrubbed against, whatever the caller
     // does to its own object afterwards.
     const forwardedEnv = env === undefined ? undefined : { ...env };
-    const emit = labEventEmitter(onEvent, warnings, () => knownSecretValues(config, options, forwardedEnv));
+    const emit = studyEventEmitter(onEvent, warnings, () => knownSecretValues(config, options, forwardedEnv));
     // Every route reads its typed options directly, and onEvent reaches it as `emit`. unsupportedOption
     // already refused an option no route reads; the preview route reads no env.
     const normalized = { ...forwarded };
@@ -105,7 +106,7 @@ export function optionRefusalOutcome(config, route, options, refusal) {
     const cwd = path.resolve(options.cwd);
     const error = { code: refusal.code, message: refusal.message };
     const actor = config.actors[0]?.type ?? "";
-    const dryRun = resolveLabDryRun(config, options.dryRun, true) ?? true;
+    const dryRun = resolveStudyDryRun(config, options.dryRun, true) ?? true;
     const runId = options.runId ?? "not-created";
     const common = { ok: false, cwd, actor, dryRun, runId, warnings: [], error };
     switch (route) {

package/dist/{lab/lab-deps.d.ts → study/study-deps.d.ts}

@@ -9,8 +9,8 @@ import type { DetachedTimers } from "../substrates/detached.js";
 import type { E2BDesktopModule } from "../substrates/e2b/sdk.js";
 import type { LocalTreeArchive } from "../subject/local-tree-archive.js";
 import type { SubjectPhaseEvent } from "../subject/steps.js";
-import type { ParticipantRef } from "./run-lab-events.js";
-export interface LabDeps {
+import type { ParticipantRef } from "./run-study-events.js";
+export interface StudyDeps {
     /** Loads the E2B SDK. Defaults to loadE2BDesktopModule. */
     readonly desktopModule?: () => Promise<E2BDesktopModule>;
     /** Renders the Observer. Defaults to renderObserver. */

package/dist/{lab/lab-deps.js → study/study-deps.js}

@@ -1,4 +1,4 @@
-// Test seams: the implementations a test puts in place of the real ones. The internal runLab takes
-// them as its third argument and each route runner as `deps`; the package's runLab takes none.
+// Test seams: the implementations a test puts in place of the real ones. The internal runStudyWith takes
+// them as its third argument and each route runner as `deps`; the package's runStudy takes none.
 // Each field defaults to the real implementation.
 export {};

package/dist/{lab → study}/summary.d.ts

@@ -1,13 +1,13 @@
 import { type LocalRuntimeStatus } from "../substrates/local/runtime.js";
 import { type KeyResolutionDeps } from "../keys/key-resolution.js";
 export declare const STUDY_SUMMARY_SCHEMA = "humanish.study-summary.v1";
-export interface LabCaps {
+export interface StudyCaps {
     /** Per-participant blast-radius budget. */
     laneUsd?: number;
     /** Shared study budget across every participant. */
     studyUsd?: number;
 }
-export interface LabSummary {
+export interface StudySummary {
     runtime?: Pick<LocalRuntimeStatus, "ok" | "installed" | "message">;
     participantReadiness?: {
         ok: boolean;
@@ -35,11 +35,11 @@ export interface LabSummary {
      * The reasoning effort that will actually run, override or default, and `"per-lane"` when the
      * roster declares more than one, because a single value would be a lie about half the participants.
      *
-     * Shown because it was a silent constant: unreachable from a lab, so every run took the provider
+     * Shown because it was a silent constant: unreachable from a study, so every run took the provider
      * default. A study variable you cannot see is one nobody chose.
      */
     reasoningEffort?: string;
-    caps: LabCaps;
+    caps: StudyCaps;
     /**
      * Whether the configured route's required keys resolve. Dry runs require none. This checks key
      * presence, not local CLI authentication or provider validity. Undefined when not checked.
@@ -47,12 +47,12 @@ export interface LabSummary {
     keysReady?: boolean;
     missingKeys?: string[];
     /**
-     * The planner's refusal message when a live key check finds the lab will not plan, as
-     * `humanish lab run` would report it. `keysReady` is then unset: a refused plan lists no keys.
+     * The planner's refusal message when a live key check finds the study will not plan, as
+     * `humanish run` would report it. `keysReady` is then unset: a refused plan lists no keys.
      */
     planRefusal?: string;
 }
-export interface ReadLabSummaryOptions {
+export interface ReadStudySummaryOptions {
     /** Skip the key probe (it touches vendor stores); the screen then shows no keys line. */
     checkKeys?: boolean;
     env?: NodeJS.ProcessEnv;
@@ -60,7 +60,7 @@ export interface ReadLabSummaryOptions {
     keyDeps?: KeyResolutionDeps;
 }
 /**
- * Describe one lab. Returns null when the manifest cannot be resolved: the caller already knows
- * the lab exists from the listing, so this failing means the file changed underneath them.
+ * Describe one study. Returns null when the manifest cannot be resolved: the caller already knows
+ * the study exists from the listing, so this failing means the file changed underneath them.
  */
-export declare function readLabSummary(cwd: string, lab: string, options?: ReadLabSummaryOptions): Promise<LabSummary | null>;
+export declare function readStudySummary(cwd: string, study: string, options?: ReadStudySummaryOptions): Promise<StudySummary | null>;

package/dist/{lab → study}/summary.js

@@ -1,20 +1,20 @@
-import { isLocalBrowserLab } from "../substrates/local/runtime-config.js";
+import { isLocalBrowserStudy } from "../substrates/local/runtime-config.js";
 import { localRuntimeStatus } from "../substrates/local/runtime.js";
-// What a lab is, for the surface that has to describe it before you spend money.
+// What a study is, for the surface that has to describe it before you spend money.
 //
-// The run index and run detail answer questions about runs. This answers a question about the lab
+// The run index and run detail answer questions about runs. This answers a question about the study
 // itself (what it drives, who is in it, which model, and what it is allowed to spend), which is
 // what a stakeholder reads on the screen where they decide whether to press Start.
 //
 // Resolved analysis defaults are shown independently of declared participant caps. A cap that is not
 // declared is not "unlimited" and not "$0"; it is a line the screen does not draw.
-import { resolveLabDryRun } from "./plan.js";
+import { resolveStudyDryRun } from "./plan.js";
 import { routeOf } from "./plan.js";
 import { localCodexParticipantCheck, planCliRun } from "./doctor.js";
 import { requiredKeys, requiredSubjectEnv } from "./requirements.js";
 import { automaticAnalysisBudget } from "../analysis/automatic-config.js";
 import { DEFAULT_OPENAI_CU_MODEL, DEFAULT_OPENAI_CU_REASONING_EFFORT, } from "../actors/computer-use/openai-provider.js";
-import { inspectLabManifest } from "./discover.js";
+import { inspectStudyManifest } from "./discover.js";
 import { isComputerUseComposition } from "./routing.js";
 import { probeKeySources } from "../keys/key-resolution.js";
 import { receivingRequiredKey } from "../comms/setup.js";
@@ -35,7 +35,7 @@ function reasoningEffortOf(config) {
         return "per-lane";
     return resolved.size === 1 ? [...resolved][0] : fallback;
 }
-/** One short phrase for what the lab drives. */
+/** One short phrase for what the study drives. */
 function subjectOf(config) {
     const subject = config.subject;
     if (subject?.source === undefined)
@@ -76,11 +76,11 @@ function capsOf(config) {
     };
 }
 /**
- * Describe one lab. Returns null when the manifest cannot be resolved: the caller already knows
- * the lab exists from the listing, so this failing means the file changed underneath them.
+ * Describe one study. Returns null when the manifest cannot be resolved: the caller already knows
+ * the study exists from the listing, so this failing means the file changed underneath them.
  */
-export async function readLabSummary(cwd, lab, options = {}) {
-    const inspected = await inspectLabManifest(cwd, lab).catch(() => null);
+export async function readStudySummary(cwd, study, options = {}) {
+    const inspected = await inspectStudyManifest(cwd, study).catch(() => null);
     if (inspected === null || !inspected.ok || inspected.config === undefined)
         return null;
     const config = inspected.config;
@@ -88,8 +88,8 @@ export async function readLabSummary(cwd, lab, options = {}) {
     const route = routeOf(inspected.config);
     let keysReady;
     let missingKeys;
-    const dryRun = resolveLabDryRun(inspected.config, undefined, true) === true;
-    // A live key check reads the plan's requirements. A lab the planner refuses has none to check,
+    const dryRun = resolveStudyDryRun(inspected.config, undefined, true) === true;
+    // A live key check reads the plan's requirements. A study the planner refuses has none to check,
     // so the summary reports the refusal in place of its keys.
     const planned = options.checkKeys === true && !dryRun ? await planCliRun(inspected.config, cwd) : undefined;
     const planRefusal = planned?.ok === false ? planned.refusal.message : undefined;
@@ -129,7 +129,7 @@ export async function readLabSummary(cwd, lab, options = {}) {
     const analysis = automaticAnalysisBudget(inspected.config.review?.analysis, route);
     const subject = subjectOf(config);
     const participants = participantsOf(config);
-    const runtime = options.checkKeys === true && isLocalBrowserLab(inspected.config)
+    const runtime = options.checkKeys === true && isLocalBrowserStudy(inspected.config)
         ? await localRuntimeStatus({
             ...(options.env ? { env: options.env } : {}),
             media: inspected.config.execution?.desktop?.media !== undefined ||
@@ -137,7 +137,7 @@ export async function readLabSummary(cwd, lab, options = {}) {
         })
         : undefined;
     const participantReadiness = options.checkKeys === true &&
-        isLocalBrowserLab(inspected.config) &&
+        isLocalBrowserStudy(inspected.config) &&
         inspected.config.actors[0]?.type === "local-agent"
         ? await localCodexParticipantCheck({ env: options.env ?? process.env })
         : undefined;
@@ -160,7 +160,7 @@ export async function readLabSummary(cwd, lab, options = {}) {
                 communications: `Real email · ${inspected.config.comms.email.connection} · fresh inbox per participant · hosted processing · local review only`,
             }
             : {}),
-        studyId: String(config.id ?? lab),
+        studyId: String(config.id ?? study),
         ...(typeof config.title === "string" ? { title: config.title } : {}),
         ...(typeof config.description === "string" ? { description: config.description.trim() } : {}),
         ...(subject === undefined ? {} : { subject }),