humanish 0.107.0 → 0.109.0

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

@@ -4,16 +4,16 @@ import type { ReasoningEffort } from "../actors/reasoning-effort.js";
 import type { BrowserSurface } from "../actors/scripted-browser/types.js";
 import type { ScriptedRefusal } from "../routes/scripted/plan.js";
 import type { TerminalRefusal } from "../routes/terminal/plan.js";
-import type { RunLabProvenance } from "../run/status.js";
+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?: RunLabProvenance;
+    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";
@@ -194,7 +194,7 @@ export interface SharedWorldPlan extends PlanBase {
     readonly plane: SharedWorldPlane;
     /** At least 2. */
     readonly concurrency: number;
-    /** The declared seat session timeout; the route supplies its default. */
+    /** The declared participant session timeout; the route supplies its default. */
     readonly sessionTimeoutMs?: number;
     readonly brain: Extract<Brain, {
         kind: "openai" | "local-agent";
@@ -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
@@ -282,12 +282,12 @@ export type RoutePlanResult<Plan, Refusal> = {
     readonly refusal: Refusal;
 };
 /** The error codes the preview route returns before a run starts. */
-export type PreviewRefusalCode = "HUMANISH_LAB_COMMS_UNSUPPORTED" | "HUMANISH_LAB_ANALYSIS_INVALID" | "HUMANISH_LAB_ANALYSIS_UNSUPPORTED" | "HUMANISH_LAB_TASKS_UNSUPPORTED" | "HUMANISH_INVALID_SIM_COUNT" | "HUMANISH_LIVE_RUN_UNIMPLEMENTED";
-/** Why planLab refused: the route's own code and message, as its runner returns them. */
+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 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/study/plan.js

@@ -0,0 +1,101 @@
+// 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, 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";
+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 resolveStudyDryRun(config, override, fallback) {
+    if (override !== undefined) {
+        return override;
+    }
+    if (config.scenario?.mode === "live") {
+        return false;
+    }
+    if (config.scenario?.mode === "dry-run") {
+        return true;
+    }
+    return fallback;
+}
+/**
+ * The preview route's refusals before a run starts, in its order: real email receiving, then
+ * analysis, then tasks. Each would otherwise be silently ignored by a synthetic run.
+ */
+function planPreview(config, options, input) {
+    const refuse = (code, message) => ({
+        ok: false,
+        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 study.");
+    const analysis = resolveAutomaticAnalysis(config.review?.analysis);
+    if (!analysis.ok)
+        return refuse("HUMANISH_STUDY_ANALYSIS_INVALID", analysis.message);
+    const unsupported = automaticAnalysisRouteReason(config);
+    if (unsupported)
+        return refuse("HUMANISH_STUDY_ANALYSIS_UNSUPPORTED", unsupported);
+    const tasksReason = taskProtocolValidationReason(config);
+    if (tasksReason)
+        return refuse("HUMANISH_STUDY_TASKS_UNSUPPORTED", tasksReason);
+    const participantCount = options.count ?? config.actors[0]?.count ?? 4;
+    if (!Number.isSafeInteger(participantCount) || participantCount < 1)
+        return refuse("HUMANISH_INVALID_PARTICIPANT_COUNT", "count must be a positive integer.");
+    if (!input.dryRun)
+        return refuse("HUMANISH_LIVE_RUN_UNIMPLEMENTED", THIS_REPO_DRY_RUN_ONLY);
+    return {
+        ok: true,
+        plan: {
+            ...planBase(config, { ...input, analysis }),
+            route: "preview",
+            dryRun: true,
+            participantCount,
+        },
+    };
+}
+/**
+ * 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 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.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, study, options, input, deps) {
+    switch (route) {
+        case "preview":
+            return planPreview(study, options, input);
+        case "computer-use":
+            return planComputerUseStudy(study, {
+                ...input,
+                hasRunSession: deps.runSession !== undefined,
+                driving: callerDrivingOf(options),
+                ...(options.count === undefined ? {} : { countOverride: options.count }),
+                ...(options.rerun === undefined ? {} : { rerun: options.rerun }),
+            });
+        case "shared-world":
+            return planSharedWorldStudy(study, {
+                ...input,
+                hasRunSession: deps.runSession !== undefined,
+            });
+        case "terminal":
+            return planTerminalStudy(study, { ...input, hasCostProbe: deps.costProbe !== undefined });
+        case "scripted":
+            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,13 +13,14 @@ 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;
 export async function runPublicPreviewPreflight(ctx) {
     const routeError = publicPreviewRouteError(ctx.config, ctx.route);
     if (routeError) {
-        return fail(ctx, "HUMANISH_LAB_PREFLIGHT_UNSUPPORTED_ROUTE", routeError, [
+        return fail(ctx, "HUMANISH_STUDY_PREFLIGHT_UNSUPPORTED_ROUTE", routeError, [
             { name: "route", ok: false, message: routeError },
         ]);
     }
@@ -28,12 +29,12 @@ export async function runPublicPreviewPreflight(ctx) {
         ? rosterTargets
         : ctx.targets.filter((target) => target.kind === "subject.appUrl");
     if (publicTargets.length === 0) {
-        return fail(ctx, "HUMANISH_LAB_PREFLIGHT_TARGET_POLICY", "public-preview preflight needs at least one declared app-url target.", [{ name: "targets", ok: false, message: "no app-url targets were declared" }]);
+        return fail(ctx, "HUMANISH_STUDY_PREFLIGHT_TARGET_POLICY", "public-preview preflight needs at least one declared app-url target.", [{ name: "targets", ok: false, message: "no app-url targets were declared" }]);
     }
     const loopbackTarget = publicTargets.find((target) => target.loopback);
     if (loopbackTarget) {
         blockTarget(loopbackTarget, "public-preview requires externally reachable non-loopback targets.");
-        return fail(ctx, "HUMANISH_LAB_PREFLIGHT_TARGET_POLICY", "public-preview reachability cannot prove loopback targets from a hosted desktop; use sandbox-loopback or a prepared public target.", [
+        return fail(ctx, "HUMANISH_STUDY_PREFLIGHT_TARGET_POLICY", "public-preview reachability cannot prove loopback targets from a hosted desktop; use sandbox-loopback or a prepared public target.", [
             {
                 name: "target policy",
                 ok: false,
@@ -43,7 +44,7 @@ export async function runPublicPreviewPreflight(ctx) {
     }
     const e2bApiKey = ctx.env.E2B_API_KEY?.trim();
     if (!e2bApiKey) {
-        return fail(ctx, "HUMANISH_LAB_PREFLIGHT_E2B_REQUIRED", "public-preview preflight creates one E2B desktop to probe target reachability; E2B_API_KEY is required.", [{ name: "e2b api key", ok: false, message: "missing E2B_API_KEY" }]);
+        return fail(ctx, "HUMANISH_STUDY_PREFLIGHT_E2B_REQUIRED", "public-preview preflight creates one E2B desktop to probe target reachability; E2B_API_KEY is required.", [{ name: "e2b api key", ok: false, message: "missing E2B_API_KEY" }]);
     }
     // Each target gets at most one readiness budget.
     const leaseMs = publicTargets.length * ctx.timeoutMs + PREFLIGHT_LEASE_BUFFER_MS;
@@ -63,7 +64,7 @@ export async function runPublicPreviewPreflight(ctx) {
     }
     const failed = publicTargets.find((target) => target.reachable === false);
     if (failed) {
-        return fail(ctx, "HUMANISH_LAB_PREFLIGHT_TARGET_UNREACHABLE", "one or more declared public-preview targets were not reachable from the hosted desktop.", [
+        return fail(ctx, "HUMANISH_STUDY_PREFLIGHT_TARGET_UNREACHABLE", "one or more declared public-preview targets were not reachable from the hosted desktop.", [
             {
                 name: "target reachability",
                 ok: false,
@@ -82,31 +83,31 @@ export async function runPublicPreviewPreflight(ctx) {
 export async function runSandboxLoopbackPreflight(ctx) {
     const routeError = sandboxLoopbackRouteError(ctx.config, ctx.route);
     if (routeError) {
-        return fail(ctx, "HUMANISH_LAB_PREFLIGHT_UNSUPPORTED_ROUTE", routeError, [
+        return fail(ctx, "HUMANISH_STUDY_PREFLIGHT_UNSUPPORTED_ROUTE", routeError, [
             { name: "route", ok: false, message: routeError },
         ]);
     }
     const missingEnv = (ctx.config.subject.env ?? []).filter((name) => !ctx.env[name]?.trim());
     if (missingEnv.length > 0) {
-        return fail(ctx, "HUMANISH_LAB_PREFLIGHT_ENV_MISSING", `sandbox-loopback preflight needs declared env values: ${missingEnv.join(", ")}`, [
+        return fail(ctx, "HUMANISH_STUDY_PREFLIGHT_ENV_MISSING", `sandbox-loopback preflight needs declared env values: ${missingEnv.join(", ")}`, [
             {
                 name: "subject env",
                 ok: false,
-                message: `${missingEnv.length} declared env var value(s) missing`,
+                message: `${plural(missingEnv.length, "declared env var value")} missing`,
             },
         ]);
     }
     const e2bApiKey = ctx.env.E2B_API_KEY?.trim();
     if (!e2bApiKey) {
-        return fail(ctx, "HUMANISH_LAB_PREFLIGHT_E2B_REQUIRED", "sandbox-loopback preflight creates one E2B desktop to clone, serve, and probe the subject; E2B_API_KEY is required.", [{ name: "e2b api key", ok: false, message: "missing E2B_API_KEY" }]);
+        return fail(ctx, "HUMANISH_STUDY_PREFLIGHT_E2B_REQUIRED", "sandbox-loopback preflight creates one E2B desktop to clone, serve, and probe the subject; E2B_API_KEY is required.", [{ name: "e2b api key", ok: false, message: "missing E2B_API_KEY" }]);
     }
     const repo = ctx.config.subject.repos?.[0];
     const serve = ctx.config.subject.serve;
     if (!repo || !serve) {
-        return fail(ctx, "HUMANISH_LAB_PREFLIGHT_UNSUPPORTED_ROUTE", "sandbox-loopback preflight requires one clone repo and subject.serve.", [{ name: "clone subject", ok: false, message: "missing repo or serve block" }]);
+        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,
@@ -216,7 +217,7 @@ async function withPreflightSandbox(ctx, args, callback) {
     if (failureMessage) {
         return {
             ok: false,
-            result: fail(ctx, "HUMANISH_LAB_PREFLIGHT_PROVISION_FAILED", failureMessage, [
+            result: fail(ctx, "HUMANISH_STUDY_PREFLIGHT_PROVISION_FAILED", failureMessage, [
                 { name: "sandbox preflight", ok: false, message: failureMessage },
             ]),
         };
@@ -224,7 +225,7 @@ async function withPreflightSandbox(ctx, args, callback) {
     if (ctx.sandbox.created && ctx.sandbox.killed !== true) {
         return {
             ok: false,
-            result: fail(ctx, "HUMANISH_LAB_PREFLIGHT_TEARDOWN_FAILED", "preflight sandbox was created but teardown could not be proven.", [{ name: "sandbox teardown", ok: false, message: "sandbox kill was not proven" }]),
+            result: fail(ctx, "HUMANISH_STUDY_PREFLIGHT_TEARDOWN_FAILED", "preflight sandbox was created but teardown could not be proven.", [{ name: "sandbox teardown", ok: false, message: "sandbox kill was not proven" }]),
         };
     }
     return { ok: true };
@@ -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,18 +2,19 @@
 // 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";
-export const LAB_PREFLIGHT_SCHEMA = "humanish.lab-preflight-result.v1";
+/** 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;
     const analysis = automaticAnalysisBudget(ctx.config.review?.analysis, ctx.route);
     return {
-        schema: LAB_PREFLIGHT_SCHEMA,
+        schema: STUDY_CHECK_SCHEMA,
         ...(analysis ? { analysis } : {}),
         ok: checks.every((check) => check.ok) &&
             ctx.targets.every((target) => target.status !== "failed" && target.status !== "blocked"),
         cwd: ctx.cwd,
-        lab: ctx.lab,
-        labId: ctx.labId,
+        study: ctx.study,
+        studyId: ctx.studyId,
         origin: ctx.origin,
         path: ctx.path,
         route: ctx.route,

package/dist/study/preflight.d.ts

@@ -0,0 +1,94 @@
+import type { AutomaticAnalysisBudget } from "../analysis/automatic-config.js";
+import type { E2BDesktopModule } from "../substrates/e2b/sdk.js";
+import { type StudyConfig } from "./types.js";
+import { STUDY_CHECK_SCHEMA } from "./preflight-result.js";
+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 StudyPreflightTarget {
+    label: string;
+    kind: "subject.appUrl" | "actors[0].lanes[].target" | "subject.serve.url" | "subject.product.publicSurface";
+    targetDigest: string;
+    originDigest?: string;
+    loopback: boolean;
+    checked: boolean;
+    reachable?: boolean;
+    status: "not_checked" | "passed" | "failed" | "blocked";
+    statusCode?: number;
+    errorCode?: "HUMANISH_PREFLIGHT_TARGET_BLOCKED" | "HUMANISH_PREFLIGHT_TARGET_UNREACHABLE";
+    message: string;
+}
+interface StudyPreflightSandbox {
+    created: boolean;
+    killed?: boolean;
+    /** The probe's server-side timeout, after which the provider kills it. */
+    timeoutMs?: number;
+    sandboxIdDigest?: string;
+    template?: string;
+}
+interface StudyPreflightSpend {
+    e2bDesktop: boolean;
+    model: false;
+}
+export interface StudyPreflightResult {
+    /** The separate budget for a future live run, never spend by preflight itself. */
+    analysis?: AutomaticAnalysisBudget;
+    schema: typeof STUDY_CHECK_SCHEMA;
+    ok: boolean;
+    cwd: string;
+    /** The study the caller asked for, as given. */
+    study: string;
+    /** The resolved study's `id`, once the file parses. */
+    studyId?: string;
+    origin?: string;
+    path?: string;
+    route?: StudyRoute;
+    reachability: StudyPreflightReachabilityMode;
+    checks: StudyPreflightCheck[];
+    targets: StudyPreflightTarget[];
+    sandbox: StudyPreflightSandbox;
+    spend: StudyPreflightSpend;
+    warnings: string[];
+    error?: {
+        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 StudyPreflightHooks {
+    loadDesktopModule?: () => Promise<E2BDesktopModule>;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+export interface RunStudyPreflightOptions {
+    cwd: string;
+    study: string;
+    reachability?: StudyPreflightReachabilityMode;
+    timeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+    hooks?: StudyPreflightHooks;
+}
+/** A preflight run's state; the probes in preflight-probes.ts read and extend it. */
+export interface PreflightContext {
+    cwd: string;
+    study: string;
+    studyId: string;
+    origin: string;
+    path: string;
+    config: StudyConfig;
+    route: StudyRoute;
+    reachability: StudyPreflightReachabilityMode;
+    timeoutMs: number;
+    env: NodeJS.ProcessEnv;
+    hooks: StudyPreflightHooks;
+    checks: StudyPreflightCheck[];
+    targets: StudyPreflightTarget[];
+    sandbox: StudyPreflightSandbox;
+    warnings: string[];
+}
+export declare function runStudyPreflight(options: RunStudyPreflightOptions): Promise<StudyPreflightResult>;
+export {};

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

@@ -2,26 +2,26 @@ import path from "node:path";
 import { isLoopbackUrl } from "./parse/subject.js";
 import {} from "./types.js";
 import { runPublicPreviewPreflight, runSandboxLoopbackPreflight } from "./preflight-probes.js";
-import { digest, fail, finalize, LAB_PREFLIGHT_SCHEMA } from "./preflight-result.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: LAB_PREFLIGHT_SCHEMA,
+            schema: STUDY_CHECK_SCHEMA,
             ok: false,
             cwd,
-            lab: 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),
@@ -60,7 +60,7 @@ export async function runLabPreflight(options) {
                 check: {
                     name: "reachability",
                     ok: true,
-                    message: "metadata-only; no network, sandbox, or model calls. Credentials, local login, dependencies and target reachability were not checked; use humanish doctor --lab <lab> for setup checks.",
+                    message: "metadata-only; no network, sandbox, or model calls. Credentials, local login, dependencies and target reachability were not checked; use humanish doctor --study <study> for setup checks.",
                 },
             });
         case "public-preview":
@@ -68,7 +68,7 @@ export async function runLabPreflight(options) {
         case "sandbox-loopback":
             return await runSandboxLoopbackPreflight(ctx);
         case "prepared-host":
-            return fail(ctx, "HUMANISH_LAB_PREFLIGHT_UNSUPPORTED_ROUTE", "prepared-host preflight requires a library adapter hook; the plain CLI can validate metadata only for this mode.", [
+            return fail(ctx, "HUMANISH_STUDY_PREFLIGHT_UNSUPPORTED_ROUTE", "prepared-host preflight requires a library adapter hook; the plain CLI can validate metadata only for this mode.", [
                 {
                     name: "prepared-host",
                     ok: false,