humanish 0.108.0 → 0.109.0

package/dist/{lab → study}/plan-participants.js

@@ -1,4 +1,4 @@
-// Who takes part in a lab: one record per participant, built from the declared roster or a count.
+// Who takes part in a study: one record per participant, built from the declared roster or a count.
 // Computer-use and shared-world participants share the desktop fields; each kind adds its own.
 import { resolveParticipantDevice } from "./device-presets.js";
 import { isSharedWorldComposition, participantIdAt } from "./routing.js";
@@ -35,7 +35,7 @@ function desktopParticipant(config, entry, index, kind, focus) {
     };
 }
 /**
- * The participants of a computer-use lab: the declared roster, else `count` identical ones. A count
+ * The participants of a computer-use study: the declared roster, else `count` identical ones. A count
  * override (`--count`) applies only when no roster is declared.
  */
 export function computerUseParticipants(config, countOverride) {
@@ -52,7 +52,7 @@ export function computerUseParticipants(config, countOverride) {
         };
     });
 }
-/** The participants of a shared-world lab, one per roster entry, typed by the plane they share. */
+/** The participants of a shared-world study, one per roster entry, typed by the plane they share. */
 export function sharedWorldParticipants(config) {
     const roster = rosterOf(config.actors[0]) ?? [];
     const participantAt = (entry, index) => desktopParticipant(config, entry, index, "seat", entry.instruction);
@@ -73,7 +73,7 @@ export function sharedWorldParticipants(config) {
         })),
     };
 }
-/** The ids of the participants a computer-use or shared-world lab runs, in roster order. */
+/** The ids of the participants a computer-use or shared-world study runs, in roster order. */
 export function declaredParticipantIds(config) {
     const actor = config.actors[0];
     const roster = rosterOf(actor);

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

@@ -8,12 +8,12 @@ import type { RunStudyProvenance } from "../run/study-provenance.js";
 import type { ComputerUseRefusal } from "../routes/computer-use/plan.js";
 import type { SharedWorldRefusal } from "../routes/shared-world/plan.js";
 import type { ComputerUseParticipant, ExternalPublicParticipant, ProvisionedParticipant } from "./plan-participants.js";
-import type { LabConfig, LabExecutionTerminal, LabRuntimeAuth, LabScenarioCaps, LabSubjectProduct, LabSubjectServe, LabSubjectState, LabSubjectStateCheckpoint } from "./types.js";
+import type { StudyConfig, StudyExecutionTerminal, StudyRuntimeAuth, StudyScenarioCaps, StudySubjectProduct, StudySubjectServe, StudySubjectState, StudySubjectStateCheckpoint } from "./types.js";
 export type NonEmpty<T> = readonly [T, ...T[]];
 type AtLeastTwo<T> = readonly [T, T, ...T[]];
 /**
  * Something a route checks right before acquisition. Preflight refuses on, and doctor and the TUI
- * report, the keys and subject env listed here, through src/lab/requirements.ts.
+ * report, the keys and subject env listed here, through src/study/requirements.ts.
  */
 export type Requirement = {
     readonly kind: "key";
@@ -48,21 +48,21 @@ export type Requirement = {
  * VM study read it before a plan exists. Shared world, terminal and scripted still read some config
  * fields at run time.
  */
-export type ResidualConfig = Pick<LabConfig, "comms" | "policies" | "personas" | "defaults" | "review"> & {
-    readonly execution?: Pick<NonNullable<LabConfig["execution"]>, "desktop" | "target">;
-    readonly subject: Pick<LabConfig["subject"], "clone" | "localTree" | "repos" | "envValues">;
+export type ResidualConfig = Pick<StudyConfig, "comms" | "policies" | "personas" | "defaults" | "review"> & {
+    readonly execution?: Pick<NonNullable<StudyConfig["execution"]>, "desktop" | "target">;
+    readonly subject: Pick<StudyConfig["subject"], "clone" | "localTree" | "repos" | "envValues">;
 };
 export interface PlannedAnalysis {
     readonly config: AnalysisConfig;
-    /** "default" when the lab declared no review.analysis. */
+    /** "default" when the study declared no review.analysis. */
     readonly trigger: "default" | "explicit";
     readonly preferLargerOutput: boolean;
 }
 interface PlanBase {
-    readonly labId: string;
-    /** The lab's declared title, which bundles record. */
+    readonly studyId: string;
+    /** The study's declared title, which bundles record. */
     readonly title?: string;
-    readonly lab?: RunStudyProvenance;
+    readonly study?: RunStudyProvenance;
     /** A frozen copy owned by the plan. */
     readonly residual: Readonly<ResidualConfig>;
     readonly dryRun: boolean;
@@ -83,7 +83,7 @@ interface PreviewPlan extends PlanBase {
 }
 /**
  * The model driving a desktop participant. `caller` is the library caller's createProvider.
- * `declaredModel` is actors[0].model as the lab wrote it, absent when undeclared: the providers
+ * `declaredModel` is actors[0].model as the study wrote it, absent when undeclared: the providers
  * take it as written, and spend is priced at it, else the default (pricedModel). An openai
  * brain's `model` is the one its provider runs, with that default applied.
  */
@@ -102,14 +102,14 @@ export type Brain = {
 export type ProvisionedSubject = {
     readonly kind: "clone";
     readonly repo: string;
-    readonly serve: LabSubjectServe;
+    readonly serve: StudySubjectServe;
     readonly env: readonly string[];
-    readonly state?: LabSubjectState;
+    readonly state?: StudySubjectState;
 } | {
     readonly kind: "local-tree";
-    readonly serve: LabSubjectServe;
+    readonly serve: StudySubjectServe;
     readonly env: readonly string[];
-    readonly state?: LabSubjectState;
+    readonly state?: StudySubjectState;
 };
 export interface AppUrlSubject {
     readonly kind: "app-url";
@@ -131,7 +131,7 @@ export type ComputerUseRunner = {
     readonly participants: NonEmpty<ComputerUseParticipant>;
     readonly subject: AppUrlSubject | ProvisionedSubject | {
         readonly kind: "desktop-cli";
-        readonly product: LabSubjectProduct;
+        readonly product: StudySubjectProduct;
         /** As on AppUrlSubject: a library config's declared `subject.serve.url`. */
         readonly serveUrl?: string;
     };
@@ -172,8 +172,8 @@ export interface ComputerUsePlan extends PlanBase {
         readonly participantIds?: readonly string[];
     };
 }
-type CheckpointedState = LabSubjectState & {
-    readonly checkpoint: NonEmpty<LabSubjectStateCheckpoint>;
+type CheckpointedState = StudySubjectState & {
+    readonly checkpoint: NonEmpty<StudySubjectStateCheckpoint>;
 };
 export type SharedWorldPlane = {
     readonly kind: "provisioned";
@@ -208,7 +208,7 @@ export type TerminalPlan = PlanBase & {
     readonly route: "terminal";
     /** The registered terminal actor that runs. */
     readonly actor: string;
-    readonly product: LabSubjectProduct & {
+    readonly product: StudySubjectProduct & {
         readonly publicSurfaces: NonEmpty<string>;
     };
     /** The declared persona and mission; the route supplies its defaults. */
@@ -218,21 +218,21 @@ export type TerminalPlan = PlanBase & {
         readonly version?: string;
         /** Passed to Codex as `--model` on every run, so the bundle can name and price it. */
         readonly model: string;
-        /** `declared` by the lab's actor, or humanish's participant default. */
+        /** `declared` by the study's actor, or humanish's participant default. */
         readonly modelSource: "declared" | "humanish_default";
         readonly reasoningEffort?: ReasoningEffort;
-        readonly auth?: LabRuntimeAuth;
+        readonly auth?: StudyRuntimeAuth;
     };
     /** The declared egress routing allowlist; without one the sandbox egress is unrestricted. */
     readonly egressAllow?: readonly string[];
     /** The declared operator stdin posture; the route defaults to "disabled". */
-    readonly stdin?: NonNullable<LabExecutionTerminal["stdin"]>;
+    readonly stdin?: NonNullable<StudyExecutionTerminal["stdin"]>;
 } & ({
     readonly dryRun: true;
-    readonly caps?: LabScenarioCaps;
+    readonly caps?: StudyScenarioCaps;
 } | {
     readonly dryRun: false;
-    readonly caps: LabScenarioCaps & {
+    readonly caps: StudyScenarioCaps & {
         readonly maxUsd: number;
         readonly maxMinutes: number;
     };
@@ -259,9 +259,9 @@ export interface ScriptedPlan extends PlanBase {
     readonly personaId?: string;
     readonly sessionTimeoutMs?: number;
 }
-export type LabPlan = PreviewPlan | ComputerUsePlan | SharedWorldPlan | TerminalPlan | ScriptedPlan;
-interface PlannedLab {
-    readonly plan: LabPlan;
+export type StudyPlan = PreviewPlan | ComputerUsePlan | SharedWorldPlan | TerminalPlan | ScriptedPlan;
+interface PlannedStudy {
+    readonly plan: StudyPlan;
 }
 /**
  * The error a route returns before a run starts: the route, its error code and a message. Each
@@ -283,11 +283,11 @@ export type RoutePlanResult<Plan, Refusal> = {
 };
 /** The error codes the preview route returns before a run starts. */
 export type PreviewRefusalCode = "HUMANISH_STUDY_COMMS_UNSUPPORTED" | "HUMANISH_STUDY_ANALYSIS_INVALID" | "HUMANISH_STUDY_ANALYSIS_UNSUPPORTED" | "HUMANISH_STUDY_TASKS_UNSUPPORTED" | "HUMANISH_INVALID_PARTICIPANT_COUNT" | "HUMANISH_LIVE_RUN_UNIMPLEMENTED";
-/** Why planLab refused: the route's own code and message, as its runner returns them. */
+/** Why planStudy refused: the route's own code and message, as its runner returns them. */
 export type PlanRefusal = RouteRefusal<"preview", PreviewRefusalCode> | TerminalRefusal | ScriptedRefusal | ComputerUseRefusal | SharedWorldRefusal;
 export type PlanResult = {
     readonly ok: true;
-    readonly planned: PlannedLab;
+    readonly planned: PlannedStudy;
 } | {
     readonly ok: false;
     readonly refusal: PlanRefusal;

package/dist/{lab → study}/plan-types.js

@@ -1,5 +1,5 @@
-// The LabPlan union: what planLab decides about a lab before anything runs. Each route has its own
+// The StudyPlan union: what planStudy decides about a study before anything runs. Each route has its own
 // variant, and each supported subject and substrate pairing is its own case, so a combination the
 // routes refuse cannot be written down. Numeric bounds, unique ids, safe URLs and "exactly one
-// host" stay checks in planLab.
+// host" stay checks in planStudy.
 export {};

package/dist/study/plan.d.ts

@@ -0,0 +1,13 @@
+import type { InternalRunStudyOptions } from "../run-study.js";
+import type { StudyDeps } from "./study-deps.js";
+import type { PlanResult } from "./plan-types.js";
+import type { StudyConfig } from "./types.js";
+export { routeOf, type StudyRoute } from "./routing.js";
+/** Resolve dry-run: explicit override wins, else the scenario mode, else the given fallback. */
+export declare function resolveStudyDryRun(config: StudyConfig, override: boolean | undefined, fallback: boolean | undefined): boolean | undefined;
+/**
+ * The plan a study runs under, built without reading files, env or the network. Each route's planner
+ * makes every refusal that route makes, in the route's order and with its codes and messages; the
+ * route's exported runner calls the same planner.
+ */
+export declare function planStudy(config: StudyConfig, options: InternalRunStudyOptions, deps?: StudyDeps): PlanResult;

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

@@ -1,11 +1,11 @@
-// The route decision. A lab's route follows from its composition (subject.source,
+// The route decision. A study's route follows from its composition (subject.source,
 // execution.target, the first actor's registered run kind, subject.topology), never from a
 // declared kind. This is the only function that decides it.
 import { resolveAutomaticAnalysis } from "../analysis/automatic-config.js";
-import { callerDrivingOf, planComputerUseLab } from "../routes/computer-use/plan.js";
-import { injectedBrowser, planScriptedLab } from "../routes/scripted/plan.js";
-import { planSharedWorldLab } from "../routes/shared-world/plan.js";
-import { planTerminalLab } from "../routes/terminal/plan.js";
+import { callerDrivingOf, planComputerUseStudy } from "../routes/computer-use/plan.js";
+import { injectedBrowser, planScriptedStudy } from "../routes/scripted/plan.js";
+import { planSharedWorldStudy } from "../routes/shared-world/plan.js";
+import { planTerminalStudy } from "../routes/terminal/plan.js";
 import { localBrowserDefaults } from "../substrates/local/runtime-config.js";
 import { THIS_REPO_DRY_RUN_ONLY } from "./composition-rules.js";
 import { planBase } from "./plan-base.js";
@@ -13,7 +13,7 @@ import { routeOf } from "./routing.js";
 import { automaticAnalysisRouteReason, taskProtocolValidationReason } from "./validation.js";
 export { routeOf } from "./routing.js";
 /** Resolve dry-run: explicit override wins, else the scenario mode, else the given fallback. */
-export function resolveLabDryRun(config, override, fallback) {
+export function resolveStudyDryRun(config, override, fallback) {
     if (override !== undefined) {
         return override;
     }
@@ -35,7 +35,7 @@ function planPreview(config, options, input) {
         refusal: { route: "preview", code, message },
     });
     if (String(config.comms?.email?.kind) === "real")
-        return refuse("HUMANISH_STUDY_COMMS_UNSUPPORTED", "Real email receiving is unsupported on the preview route. Use a supported hosted computer-use lab.");
+        return refuse("HUMANISH_STUDY_COMMS_UNSUPPORTED", "Real email receiving is unsupported on the preview route. Use a supported hosted computer-use study.");
     const analysis = resolveAutomaticAnalysis(config.review?.analysis);
     if (!analysis.ok)
         return refuse("HUMANISH_STUDY_ANALYSIS_INVALID", analysis.message);
@@ -61,27 +61,27 @@ function planPreview(config, options, input) {
     };
 }
 /**
- * The plan a lab runs under, built without reading files, env or the network. Each route's planner
+ * The plan a study runs under, built without reading files, env or the network. Each route's planner
  * makes every refusal that route makes, in the route's order and with its codes and messages; the
  * route's exported runner calls the same planner.
  */
-export function planLab(config, options, deps = {}) {
-    const lab = localBrowserDefaults(config);
-    const input = { dryRun: resolveLabDryRun(lab, options.dryRun, true) ?? true };
-    const result = planRoute(routeOf(config), lab, options, input, deps);
+export function planStudy(config, options, deps = {}) {
+    const study = localBrowserDefaults(config);
+    const input = { dryRun: resolveStudyDryRun(study, options.dryRun, true) ?? true };
+    const result = planRoute(routeOf(config), study, options, input, deps);
     if (!result.ok)
         return result;
     // The manifest the CLI resolved enters the plan here and nowhere else; the routes read
-    // plan.lab for the run's status record and bundle.
-    const plan = options.lab === undefined ? result.plan : { ...result.plan, lab: options.lab };
+    // plan.study for the run's status record and bundle.
+    const plan = options.study === undefined ? result.plan : { ...result.plan, study: options.study };
     return { ok: true, planned: { plan } };
 }
-function planRoute(route, lab, options, input, deps) {
+function planRoute(route, study, options, input, deps) {
     switch (route) {
         case "preview":
-            return planPreview(lab, options, input);
+            return planPreview(study, options, input);
         case "computer-use":
-            return planComputerUseLab(lab, {
+            return planComputerUseStudy(study, {
                 ...input,
                 hasRunSession: deps.runSession !== undefined,
                 driving: callerDrivingOf(options),
@@ -89,13 +89,13 @@ function planRoute(route, lab, options, input, deps) {
                 ...(options.rerun === undefined ? {} : { rerun: options.rerun }),
             });
         case "shared-world":
-            return planSharedWorldLab(lab, {
+            return planSharedWorldStudy(study, {
                 ...input,
                 hasRunSession: deps.runSession !== undefined,
             });
         case "terminal":
-            return planTerminalLab(lab, { ...input, hasCostProbe: deps.costProbe !== undefined });
+            return planTerminalStudy(study, { ...input, hasCostProbe: deps.costProbe !== undefined });
         case "scripted":
-            return planScriptedLab(lab, { ...input, injectedBrowser: injectedBrowser(deps) });
+            return planScriptedStudy(study, { ...input, injectedBrowser: injectedBrowser(deps) });
     }
 }

package/dist/study/preflight-probes.d.ts

@@ -0,0 +1,3 @@
+import type { StudyPreflightResult, PreflightContext } from "./preflight.js";
+export declare function runPublicPreviewPreflight(ctx: PreflightContext): Promise<StudyPreflightResult>;
+export declare function runSandboxLoopbackPreflight(ctx: PreflightContext): Promise<StudyPreflightResult>;

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

@@ -1,9 +1,9 @@
-// The two reachability probes `humanish lab preflight` can run: public-preview checks a public
+// The two reachability probes `humanish study check` can run: public-preview checks a public
 // target from an E2B desktop, and sandbox-loopback serves a clone subject inside one. Each leases one
 // sandbox, journals it for `humanish reclaim --preflight`, and tears it down. preflight.ts resolves
-// the lab and dispatches here.
+// the study and dispatches here.
 import { cloneProvisioningBudgetMs, provisionCloneSubject } from "../subject/clone.js";
-import { CUA_ACTOR_LAB_PROVIDER_METADATA } from "../routes/computer-use/e2b-desktop/prepare.js";
+import { CUA_ACTOR_STUDY_PROVIDER_METADATA } from "../routes/computer-use/e2b-desktop/prepare.js";
 import { MAX_SANDBOX_MS } from "../substrates/e2b/lifetime.js";
 import { abandonPreflightJournal, discardPreflightJournal, openPreflightJournal, } from "../run/preflight-receipts.js";
 import { probeUrl } from "../substrates/detached.js";
@@ -13,6 +13,7 @@ import { e2bShell } from "../substrates/e2b/shell.js";
 import { redactText } from "../evidence/redaction.js";
 import { digest, fail, finalize } from "./preflight-result.js";
 import { rosterOf } from "./parse/actors.js";
+import { plural } from "../run/text.js";
 const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
 // Room on the probe's lease for desktop boot and teardown around the work it does.
 const PREFLIGHT_LEASE_BUFFER_MS = 5 * 60_000;
@@ -92,7 +93,7 @@ export async function runSandboxLoopbackPreflight(ctx) {
             {
                 name: "subject env",
                 ok: false,
-                message: `${missingEnv.length} declared env var value(s) missing`,
+                message: `${plural(missingEnv.length, "declared env var value")} missing`,
             },
         ]);
     }
@@ -106,7 +107,7 @@ export async function runSandboxLoopbackPreflight(ctx) {
         return fail(ctx, "HUMANISH_STUDY_PREFLIGHT_UNSUPPORTED_ROUTE", "sandbox-loopback preflight requires one clone repo and subject.serve.", [{ name: "clone subject", ok: false, message: "missing repo or serve block" }]);
     }
     let subjectCommitDigest;
-    // The longest the clone and serve steps can take with the lab's own budgets, so the probe is
+    // The longest the clone and serve steps can take with the study's own budgets, so the probe is
     // never cut off where the run's provisioning would still be allowed to finish.
     const leaseMs = cloneProvisioningBudgetMs(serve, ctx.config.subject.state) + PREFLIGHT_LEASE_BUFFER_MS;
     const probe = await withPreflightSandbox(ctx, { e2bApiKey, leaseMs }, async (shell) => {
@@ -167,7 +168,7 @@ async function withPreflightSandbox(ctx, args, callback) {
                 timeoutMs,
                 lifecycle: { onTimeout: "kill" },
                 metadata: {
-                    ...CUA_ACTOR_LAB_PROVIDER_METADATA,
+                    ...CUA_ACTOR_STUDY_PROVIDER_METADATA,
                     mode: "lab-preflight",
                     labId: ctx.config.id,
                     reachability: ctx.reachability,
@@ -282,7 +283,7 @@ function publicPreviewRouteError(config, route) {
     if (route !== "computer-use" ||
         config.subject.source !== "app-url" ||
         config.execution?.target !== "e2b-desktop") {
-        return "public-preview preflight supports app-url × e2b-desktop computer-use labs.";
+        return "public-preview preflight supports app-url × e2b-desktop computer-use studies.";
     }
     if (config.policies?.allowPublicTargets !== true) {
         return "public-preview preflight requires policies.allowPublicTargets: true so the owner explicitly declares the public/preview target.";
@@ -293,7 +294,7 @@ function sandboxLoopbackRouteError(config, route) {
     if (route !== "computer-use" ||
         config.subject.source !== "clone" ||
         config.execution?.target !== "e2b-desktop") {
-        return "sandbox-loopback preflight supports clone × e2b-desktop computer-use labs. (local-tree labs are not preflightable yet: see the local-tree goal doc's out-of-scope list; a dry run of the lab is the current no-spend check.)";
+        return "sandbox-loopback preflight supports clone × e2b-desktop computer-use studies. Local-tree studies cannot be preflighted yet; a dry run of the study is the current no-spend check.";
     }
     if (!config.subject.serve) {
         return "sandbox-loopback preflight requires subject.serve.";

package/dist/study/preflight-result.d.ts

@@ -0,0 +1,8 @@
+import type { StudyPreflightCheck, StudyPreflightResult, PreflightContext } from "./preflight.js";
+/** The schema of `study check` results: whether a study is ready to run on this machine. */
+export declare const STUDY_CHECK_SCHEMA = "humanish.study-check.v1";
+export declare function finalize(ctx: PreflightContext, args?: {
+    check?: StudyPreflightCheck;
+}): StudyPreflightResult;
+export declare function fail(ctx: PreflightContext, code: NonNullable<StudyPreflightResult["error"]>["code"], message: string, checks: StudyPreflightCheck[]): StudyPreflightResult;
+export declare function digest(value: string): string;

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

@@ -2,7 +2,7 @@
 // preflight-probes.ts both finish through these, so they live below both.
 import { automaticAnalysisBudget } from "../analysis/automatic-config.js";
 import { digestText } from "../evidence/redaction.js";
-/** The schema of `lab preflight` results: whether a study is ready to run on this machine. */
+/** The schema of `study check` results: whether a study is ready to run on this machine. */
 export const STUDY_CHECK_SCHEMA = "humanish.study-check.v1";
 export function finalize(ctx, args) {
     const checks = args?.check ? [...ctx.checks, args.check] : ctx.checks;
@@ -13,8 +13,8 @@ export function finalize(ctx, args) {
         ok: checks.every((check) => check.ok) &&
             ctx.targets.every((target) => target.status !== "failed" && target.status !== "blocked"),
         cwd: ctx.cwd,
-        study: ctx.lab,
-        studyId: ctx.labId,
+        study: ctx.study,
+        studyId: ctx.studyId,
         origin: ctx.origin,
         path: ctx.path,
         route: ctx.route,

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

@@ -1,16 +1,16 @@
 import type { AutomaticAnalysisBudget } from "../analysis/automatic-config.js";
 import type { E2BDesktopModule } from "../substrates/e2b/sdk.js";
-import { type LabConfig } from "./types.js";
+import { type StudyConfig } from "./types.js";
 import { STUDY_CHECK_SCHEMA } from "./preflight-result.js";
-import { type LabRoute } from "./plan.js";
-import { type LabResolveFailure } from "./discover.js";
-export type LabPreflightReachabilityMode = "metadata" | "public-preview" | "sandbox-loopback" | "prepared-host";
-export interface LabPreflightCheck {
+import { type StudyRoute } from "./plan.js";
+import { type StudyResolveFailure } from "./discover.js";
+export type StudyPreflightReachabilityMode = "metadata" | "public-preview" | "sandbox-loopback" | "prepared-host";
+export interface StudyPreflightCheck {
     name: string;
     ok: boolean;
     message: string;
 }
-export interface LabPreflightTarget {
+export interface StudyPreflightTarget {
     label: string;
     kind: "subject.appUrl" | "actors[0].lanes[].target" | "subject.serve.url" | "subject.product.publicSurface";
     targetDigest: string;
@@ -23,7 +23,7 @@ export interface LabPreflightTarget {
     errorCode?: "HUMANISH_PREFLIGHT_TARGET_BLOCKED" | "HUMANISH_PREFLIGHT_TARGET_UNREACHABLE";
     message: string;
 }
-interface LabPreflightSandbox {
+interface StudyPreflightSandbox {
     created: boolean;
     killed?: boolean;
     /** The probe's server-side timeout, after which the provider kills it. */
@@ -31,11 +31,11 @@ interface LabPreflightSandbox {
     sandboxIdDigest?: string;
     template?: string;
 }
-interface LabPreflightSpend {
+interface StudyPreflightSpend {
     e2bDesktop: boolean;
     model: false;
 }
-export interface LabPreflightResult {
+export interface StudyPreflightResult {
     /** The separate budget for a future live run, never spend by preflight itself. */
     analysis?: AutomaticAnalysisBudget;
     schema: typeof STUDY_CHECK_SCHEMA;
@@ -47,48 +47,48 @@ export interface LabPreflightResult {
     studyId?: string;
     origin?: string;
     path?: string;
-    route?: LabRoute;
-    reachability: LabPreflightReachabilityMode;
-    checks: LabPreflightCheck[];
-    targets: LabPreflightTarget[];
-    sandbox: LabPreflightSandbox;
-    spend: LabPreflightSpend;
+    route?: StudyRoute;
+    reachability: StudyPreflightReachabilityMode;
+    checks: StudyPreflightCheck[];
+    targets: StudyPreflightTarget[];
+    sandbox: StudyPreflightSandbox;
+    spend: StudyPreflightSpend;
     warnings: string[];
     error?: {
-        code: LabResolveFailure["error"]["code"] | "HUMANISH_STUDY_PREFLIGHT_INVALID_OPTION" | "HUMANISH_STUDY_PREFLIGHT_UNSUPPORTED_ROUTE" | "HUMANISH_STUDY_PREFLIGHT_TARGET_POLICY" | "HUMANISH_STUDY_PREFLIGHT_ENV_MISSING" | "HUMANISH_STUDY_PREFLIGHT_E2B_REQUIRED" | "HUMANISH_STUDY_PREFLIGHT_TARGET_UNREACHABLE" | "HUMANISH_STUDY_PREFLIGHT_PROVISION_FAILED" | "HUMANISH_STUDY_PREFLIGHT_TEARDOWN_FAILED";
+        code: StudyResolveFailure["error"]["code"] | "HUMANISH_STUDY_PREFLIGHT_INVALID_OPTION" | "HUMANISH_STUDY_PREFLIGHT_UNSUPPORTED_ROUTE" | "HUMANISH_STUDY_PREFLIGHT_TARGET_POLICY" | "HUMANISH_STUDY_PREFLIGHT_ENV_MISSING" | "HUMANISH_STUDY_PREFLIGHT_E2B_REQUIRED" | "HUMANISH_STUDY_PREFLIGHT_TARGET_UNREACHABLE" | "HUMANISH_STUDY_PREFLIGHT_PROVISION_FAILED" | "HUMANISH_STUDY_PREFLIGHT_TEARDOWN_FAILED";
         message: string;
     };
 }
-interface LabPreflightHooks {
+interface StudyPreflightHooks {
     loadDesktopModule?: () => Promise<E2BDesktopModule>;
     now?: () => number;
     sleep?: (ms: number) => Promise<void>;
 }
-export interface RunLabPreflightOptions {
+export interface RunStudyPreflightOptions {
     cwd: string;
-    lab: string;
-    reachability?: LabPreflightReachabilityMode;
+    study: string;
+    reachability?: StudyPreflightReachabilityMode;
     timeoutMs?: number;
     env?: NodeJS.ProcessEnv;
-    hooks?: LabPreflightHooks;
+    hooks?: StudyPreflightHooks;
 }
 /** A preflight run's state; the probes in preflight-probes.ts read and extend it. */
 export interface PreflightContext {
     cwd: string;
-    lab: string;
-    labId: string;
+    study: string;
+    studyId: string;
     origin: string;
     path: string;
-    config: LabConfig;
-    route: LabRoute;
-    reachability: LabPreflightReachabilityMode;
+    config: StudyConfig;
+    route: StudyRoute;
+    reachability: StudyPreflightReachabilityMode;
     timeoutMs: number;
     env: NodeJS.ProcessEnv;
-    hooks: LabPreflightHooks;
-    checks: LabPreflightCheck[];
-    targets: LabPreflightTarget[];
-    sandbox: LabPreflightSandbox;
+    hooks: StudyPreflightHooks;
+    checks: StudyPreflightCheck[];
+    targets: StudyPreflightTarget[];
+    sandbox: StudyPreflightSandbox;
     warnings: string[];
 }
-export declare function runLabPreflight(options: RunLabPreflightOptions): Promise<LabPreflightResult>;
+export declare function runStudyPreflight(options: RunStudyPreflightOptions): Promise<StudyPreflightResult>;
 export {};

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