humanish 0.106.1 → 0.108.0

package/dist/lab/persona-resolve.d.ts

@@ -4,7 +4,7 @@ import type { LabActor } from "./types.js";
 /** Title-case an id for the fallback display name (`skeptical-power-user` -> `Skeptical Power User`). */
 export declare function personaTitleFromId(personaId: string): string;
 /**
- * Resolve ONE persona from `humanish/personas/`, then the ignored `.humanish/local/personas/`.
+ * Resolve one persona from `humanish/personas/`, then the ignored `.humanish/local/personas/`.
  * Returns `null` with a warning when the id is unsafe or no file exists. Invalid rich backgrounds
  * reject the study before execution.
  */
@@ -13,8 +13,8 @@ export declare function resolveCommittedPersona(projectRoot: PreparedSelectedOut
     warnings: string[];
 }>;
 /**
- * Resolve every distinct persona id a run will use, once, before lane specs are built. Returning a
- * map keeps the plan builder PURE (it is exported npm surface and asserted pure by tests): the
+ * Resolve every distinct persona id a run will use, once, before participant specs are built. Returning a
+ * map keeps the plan builder pure (it is exported npm surface and asserted pure by tests): the
  * async file reads happen here, and the composer only does a lookup.
  */
 export declare function resolveCommittedPersonas(projectRoot: PreparedSelectedOutputDirectory, personaIds: readonly (string | undefined)[]): Promise<{
@@ -22,16 +22,16 @@ export declare function resolveCommittedPersonas(projectRoot: PreparedSelectedOu
     warnings: string[];
 }>;
 /**
- * Every persona id a lab config could put on a browser lane: the per-lane roster when one is
- * declared, otherwise the actor-level persona that every fan-out lane inherits.
+ * Every persona id a lab config could put on a browser participant: the roster when one is
+ * declared, otherwise the actor-level persona that every fan-out participant inherits.
  */
 export declare function labPersonaIds(config: {
     actors?: readonly Pick<LabActor, "persona" | "lanes">[];
 }): string[];
 /**
  * Same resolution from a plain cwd, for the labs that carry a directory string rather than an
- * already-prepared root. Realpath-then-prepare mirrors the cua lab so a symlinked cwd still reads
- * personas from the physical project.
+ * already-prepared root. Realpath-then-prepare mirrors the computer-use route so a symlinked cwd
+ * still reads personas from the physical project.
  */
 export declare function resolveCommittedPersonasForCwd(cwd: string, personaIds: readonly (string | undefined)[]): Promise<{
     personas: Map<string, ResolvedPersona>;

package/dist/lab/persona-resolve.js

@@ -6,7 +6,7 @@ import { prepareSelectedOutputDirectory, readContainedRegularFile, } from "../ru
 import { digestText, redactText } from "../evidence/redaction.js";
 import { realpath } from "node:fs/promises";
 import { rosterOf } from "./parse/actors.js";
-/** Persona ids are file-name segments, never paths: the same grammar the terminal lane enforces. */
+/** Persona ids are file-name segments, never paths: the same grammar the terminal route enforces. */
 const PERSONA_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
 /** Title-case an id for the fallback display name (`skeptical-power-user` -> `Skeptical Power User`). */
 export function personaTitleFromId(personaId) {
@@ -22,7 +22,7 @@ const PERSONA_DIRECTORIES = [
     path.posix.join(".humanish", "local", "personas"),
 ];
 /**
- * Resolve ONE persona from `humanish/personas/`, then the ignored `.humanish/local/personas/`.
+ * Resolve one persona from `humanish/personas/`, then the ignored `.humanish/local/personas/`.
  * Returns `null` with a warning when the id is unsafe or no file exists. Invalid rich backgrounds
  * reject the study before execution.
  */
@@ -65,8 +65,8 @@ export async function resolveCommittedPersona(projectRoot, personaId) {
     };
 }
 /**
- * Resolve every distinct persona id a run will use, once, before lane specs are built. Returning a
- * map keeps the plan builder PURE (it is exported npm surface and asserted pure by tests): the
+ * Resolve every distinct persona id a run will use, once, before participant specs are built. Returning a
+ * map keeps the plan builder pure (it is exported npm surface and asserted pure by tests): the
  * async file reads happen here, and the composer only does a lookup.
  */
 export async function resolveCommittedPersonas(projectRoot, personaIds) {
@@ -81,8 +81,8 @@ export async function resolveCommittedPersonas(projectRoot, personaIds) {
     return { personas, warnings };
 }
 /**
- * Every persona id a lab config could put on a browser lane: the per-lane roster when one is
- * declared, otherwise the actor-level persona that every fan-out lane inherits.
+ * Every persona id a lab config could put on a browser participant: the roster when one is
+ * declared, otherwise the actor-level persona that every fan-out participant inherits.
  */
 export function labPersonaIds(config) {
     const ids = [];
@@ -98,8 +98,8 @@ export function labPersonaIds(config) {
 }
 /**
  * Same resolution from a plain cwd, for the labs that carry a directory string rather than an
- * already-prepared root. Realpath-then-prepare mirrors the cua lab so a symlinked cwd still reads
- * personas from the physical project.
+ * already-prepared root. Realpath-then-prepare mirrors the computer-use route so a symlinked cwd
+ * still reads personas from the physical project.
  */
 export async function resolveCommittedPersonasForCwd(cwd, personaIds) {
     try {

package/dist/lab/persona.js

@@ -1,4 +1,5 @@
 import { digestText, redactText } from "../evidence/redaction.js";
+import { isRecord } from "../run/type-guards.js";
 export const PERSONA_BACKGROUND_MAX_BYTES = 32 * 1024;
 const PERSONA_COMPILER_VERSION = 2;
 export class PersonaConfigError extends Error {
@@ -18,9 +19,6 @@ const PERSONA_FIELDS = new Set([
     "constraints",
 ]);
 const TRAIT_FIELDS = new Set(["patience", "technical_confidence", "accessibility_needs"]);
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 function cleanText(value) {
     return value
         .replace(/\r\n?/g, "\n")

package/dist/lab/plan-base.d.ts

@@ -1,4 +1,3 @@
-import type { RunLabProvenance } from "../run/status.js";
 import type { Brain, ComputerUsePlan, NonEmpty, PlannedAnalysis, ProvisionedSubject, Requirement } from "./plan-types.js";
 import type { LabConfig } from "./types.js";
 export type Base = Omit<ComputerUsePlan, "route" | "actor" | "runner" | "concurrency" | "sessionBudgetMs" | "sandboxMs" | "caps" | "rerun">;
@@ -22,7 +21,6 @@ export declare function pricedModel(brain: Brain): string;
 /** The fields every plan shares, from a config whose analysis already resolved. */
 export declare function planBase(config: LabConfig, input: {
     readonly dryRun: boolean;
-    readonly lab?: RunLabProvenance;
     readonly analysis?: {
         readonly config?: PlannedAnalysis["config"] | undefined;
         readonly preferLargerOutput?: boolean | undefined;

package/dist/lab/plan-base.js

@@ -1,10 +1,13 @@
 // What every route planner shares: the plan fields common to all routes, the frozen residual config,
 // and the requirement and subject helpers.
 import { DEFAULT_OPENAI_CU_MODEL } from "../actors/computer-use/openai-provider.js";
-function deepFreeze(value) {
-    if (typeof value === "object" && value !== null) {
+// A YAML alias can make a parsed record contain itself (an inline persona that names its own
+// anchor), and structuredClone keeps the cycle, so each object is frozen once.
+function deepFreeze(value, frozen = new WeakSet()) {
+    if (typeof value === "object" && value !== null && !frozen.has(value)) {
+        frozen.add(value);
         for (const child of Object.values(value))
-            deepFreeze(child);
+            deepFreeze(child, frozen);
         Object.freeze(value);
     }
     return value;
@@ -109,7 +112,6 @@ export function planBase(config, input) {
     return {
         labId: config.id,
         ...(config.title === undefined ? {} : { title: config.title }),
-        ...(input.lab === undefined ? {} : { lab: input.lab }),
         residual: residualOf(config),
         dryRun: input.dryRun,
         ...(analysis === undefined

package/dist/lab/plan-participants.d.ts

@@ -5,7 +5,7 @@ import type { LabTask } from "./tasks.js";
 import type { LabConfig } from "./types.js";
 /** Who one participant is. Every route with participants carries this record. */
 export interface Participant {
-    /** Declared roster id, else `lane-NN` (independent lanes) or `role-NN` (shared-world seats). */
+    /** Declared roster id, else `lane-NN` (independent participants) or `role-NN` (shared-world participants). */
     readonly id: string;
     /** 0-based position in the roster. Bundle `sim-NNN` and `stream-NNN` ids derive from it. */
     readonly index: number;
@@ -30,7 +30,7 @@ interface DesktopParticipant extends Participant {
         readonly preset: DevicePreset;
         readonly resolution: [number, number];
     };
-    /** Lane value, else actor value, else absent (the provider default is recorded in the trace). */
+    /** The `lanes[]` entry's value, else actor value, else absent (the provider default is recorded in the trace). */
     readonly limits: {
         readonly stopWhen?: StopWhen;
         readonly dwell?: DwellWindow;
@@ -38,20 +38,20 @@ interface DesktopParticipant extends Participant {
         readonly maxOutputTokens?: number;
     };
 }
-/** Only independent computer-use lanes consume a task protocol and a per-lane target. */
+/** Only independent computer-use participants consume a task protocol and their own target. */
 export interface ComputerUseParticipant extends DesktopParticipant {
     readonly tasks?: readonly LabTask[];
-    /** app-url fan-out only: this lane's own entry URL; absent means the subject URL. */
+    /** app-url fan-out only: this participant's own entry URL; absent means the subject URL. */
     readonly targetUrl?: string;
 }
-/** A seat on a provisioned plane: an optional same-origin path under `serve.url`. */
+/** A participant on a provisioned plane: an optional same-origin path under `serve.url`. */
 export interface ProvisionedParticipant extends DesktopParticipant {
     readonly entry?: string;
     readonly host?: never;
     readonly tasks?: never;
     readonly targetUrl?: never;
 }
-/** A seat on an external public plane: exactly one seat hosts the shared session. */
+/** A participant on an external public plane: exactly one participant hosts the shared session. */
 export interface ExternalPublicParticipant extends DesktopParticipant {
     readonly host: boolean;
     readonly entry?: never;
@@ -68,7 +68,7 @@ export type SharedWorldRoster = {
 /** One shared-world participant on either plane. */
 export type SharedWorldParticipant = ProvisionedParticipant | ExternalPublicParticipant;
 /**
- * The lanes of a computer-use lab: the declared roster, else `count` identical lanes. A count
+ * The participants of a computer-use lab: the declared roster, else `count` identical ones. A count
  * override (`--count`) applies only when no roster is declared.
  */
 export declare function computerUseParticipants(config: LabConfig, countOverride?: number): ComputerUseParticipant[];

package/dist/lab/plan-participants.js

@@ -1,5 +1,5 @@
 // Who takes part in a lab: one record per participant, built from the declared roster or a count.
-// Computer-use lanes and shared-world seats share the desktop fields; each kind adds its own.
+// 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";
 import { focusOf, rosterOf } from "./parse/actors.js";
@@ -35,7 +35,7 @@ function desktopParticipant(config, entry, index, kind, focus) {
     };
 }
 /**
- * The lanes of a computer-use lab: the declared roster, else `count` identical lanes. A count
+ * The participants of a computer-use lab: the declared roster, else `count` identical ones. A count
  * override (`--count`) applies only when no roster is declared.
  */
 export function computerUseParticipants(config, countOverride) {

package/dist/lab/plan-types.d.ts

@@ -4,14 +4,17 @@ 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";
 export type NonEmpty<T> = readonly [T, ...T[]];
 type AtLeastTwo<T> = readonly [T, T, ...T[]];
-/** Something a route checks right before acquisition. Doctor, the TUI and preflight list the same set. */
+/**
+ * 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.
+ */
 export type Requirement = {
     readonly kind: "key";
     readonly name: "OPENAI_API_KEY" | "E2B_API_KEY";
@@ -39,7 +42,12 @@ export type Requirement = {
     readonly kind: "external-catch";
     readonly url: string;
 };
-/** Config fields no plan field decides. Routes read nothing else from the config. */
+/**
+ * Config fields no plan field decides. After admission, computer use reads the config only to pass
+ * it to the caller's createProvider and inProcess executor; its planner, refusal envelopes and local
+ * 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">;
@@ -54,7 +62,7 @@ interface PlanBase {
     readonly labId: string;
     /** The lab's declared title, which bundles record. */
     readonly title?: string;
-    readonly lab?: RunLabProvenance;
+    readonly lab?: RunStudyProvenance;
     /** A frozen copy owned by the plan. */
     readonly residual: Readonly<ResidualConfig>;
     readonly dryRun: boolean;
@@ -74,7 +82,7 @@ interface PreviewPlan extends PlanBase {
     readonly participantCount: number;
 }
 /**
- * The model driving a desktop participant. `caller` is the library caller's buildProvider.
+ * 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
  * 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.
@@ -107,6 +115,11 @@ export interface AppUrlSubject {
     readonly kind: "app-url";
     readonly appUrl: string;
     readonly publicTargets: boolean;
+    /**
+     * A `subject.serve.url` declared on this subject, which the parser refuses and only a library
+     * config can carry. Participants map links to it back to their own app.
+     */
+    readonly serveUrl?: string;
 }
 /**
  * Supported subject and desktop pairings. The local VM also takes public targets: the route runs
@@ -119,6 +132,8 @@ export type ComputerUseRunner = {
     readonly subject: AppUrlSubject | ProvisionedSubject | {
         readonly kind: "desktop-cli";
         readonly product: LabSubjectProduct;
+        /** As on AppUrlSubject: a library config's declared `subject.serve.url`. */
+        readonly serveUrl?: string;
     };
 } | {
     readonly desktop: "local-vm";
@@ -179,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";
@@ -201,7 +216,10 @@ export type TerminalPlan = PlanBase & {
     readonly mission?: string;
     readonly runtime: {
         readonly version?: string;
-        readonly model?: 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. */
+        readonly modelSource: "declared" | "humanish_default";
         readonly reasoningEffort?: ReasoningEffort;
         readonly auth?: LabRuntimeAuth;
     };
@@ -264,7 +282,7 @@ 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";
+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. */
 export type PlanRefusal = RouteRefusal<"preview", PreviewRefusalCode> | TerminalRefusal | ScriptedRefusal | ComputerUseRefusal | SharedWorldRefusal;
 export type PlanResult = {

package/dist/lab/plan.d.ts

@@ -1,22 +1,8 @@
-import type { RunLabOptions } from "../run-lab.js";
+import type { InternalRunLabOptions } from "../run-lab.js";
+import type { LabDeps } from "./lab-deps.js";
 import type { PlanResult } from "./plan-types.js";
 import type { LabConfig } from "./types.js";
-/** The five execution paths a lab can take. */
-export type LabRoute = "preview" | "computer-use" | "shared-world" | "terminal" | "scripted";
-/** A route's older name, kept in `LabOutcome.backend` and the preflight result's `backend`. */
-export type LabBackend = "synthetic" | "cua" | "scripted" | "terminal" | "concurrent-shared-world";
-/** The backend name older callers and wire fields use for a route. */
-export declare function backendOf(route: LabRoute): LabBackend;
-/**
- * The backend a config runs on: `routeOf`, under its older name.
- * @deprecated Use `routeOf`, and `backendOf` for the older backend name. This goes in the next minor.
- */
-export declare function selectLabBackend(config: LabConfig): LabBackend;
-/**
- * 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 { routeOf, type LabRoute } from "./routing.js";
 /** Resolve dry-run: explicit override wins, else the scenario mode, else the given fallback. */
 export declare function resolveLabDryRun(config: LabConfig, override: boolean | undefined, fallback: boolean | undefined): boolean | undefined;
 /**
@@ -24,4 +10,4 @@ export declare function resolveLabDryRun(config: LabConfig, override: boolean |
  * 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 planLab(config: LabConfig, options: RunLabOptions): PlanResult;
+export declare function planLab(config: LabConfig, options: InternalRunLabOptions, deps?: LabDeps): PlanResult;

package/dist/lab/plan.js

@@ -1,67 +1,17 @@
 // The route decision. A lab's route follows from its composition (subject.source,
-// execution.target, the first actor's registered lane, subject.topology), never from a declared
-// kind. This is the only function that decides it; backendOf maps its answer to the older
-// backend names.
+// 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 { planComputerUseLab } from "../routes/computer-use/plan.js";
-import { planScriptedLab } from "../routes/scripted/plan.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 { localBrowserDefaults } from "../substrates/local/runtime-config.js";
 import { THIS_REPO_DRY_RUN_ONLY } from "./composition-rules.js";
 import { planBase } from "./plan-base.js";
-import { isComputerUseComposition, isScriptedBrowserComposition, isSharedWorldComposition, isTerminalProductComposition, } from "./routing.js";
+import { routeOf } from "./routing.js";
 import { automaticAnalysisRouteReason, taskProtocolValidationReason } from "./validation.js";
-const BACKENDS = {
-    preview: "synthetic",
-    "computer-use": "cua",
-    "shared-world": "concurrent-shared-world",
-    terminal: "terminal",
-    scripted: "scripted",
-};
-/** The backend name older callers and wire fields use for a route. */
-export function backendOf(route) {
-    return BACKENDS[route];
-}
-/**
- * The backend a config runs on: `routeOf`, under its older name.
- * @deprecated Use `routeOf`, and `backendOf` for the older backend name. This goes in the next minor.
- */
-export function selectLabBackend(config) {
-    return backendOf(routeOf(config));
-}
-/**
- * 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 function routeOf(config) {
-    const source = config.subject.source;
-    // A scripted-browser actor on a loopback app or a provisioned clone replays committed steps.
-    if (isScriptedBrowserComposition(config))
-        return "scripted";
-    // A terminal-product subject goes to the terminal route even with an unregistered actor, so that
-    // route refuses the actor instead of another route running something else.
-    if (isTerminalProductComposition(config) || source === "terminal-product")
-        return "terminal";
-    // Checked before computer use: the same composition without the topology declaration runs as
-    // independent lanes.
-    if (isSharedWorldComposition(config))
-        return "shared-world";
-    // A CLI studied at a desktop is a computer-use study whose subject is a terminal window.
-    if (source === "desktop-cli")
-        return "computer-use";
-    // Every other app-url, clone, local-app or local-tree config goes to computer use, including
-    // ones with an unknown actor: that route refuses the actor, where the preview route would run
-    // no participant at all.
-    if (isComputerUseComposition(config) ||
-        source === "app-url" ||
-        source === "clone" ||
-        source === "local-app" ||
-        source === "local-tree")
-        return "computer-use";
-    // this-repo runs the synthetic preview.
-    return "preview";
-}
+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) {
     if (override !== undefined) {
@@ -85,19 +35,19 @@ function planPreview(config, options, input) {
         refusal: { route: "preview", code, message },
     });
     if (String(config.comms?.email?.kind) === "real")
-        return refuse("HUMANISH_LAB_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 lab.");
     const analysis = resolveAutomaticAnalysis(config.review?.analysis);
     if (!analysis.ok)
-        return refuse("HUMANISH_LAB_ANALYSIS_INVALID", analysis.message);
+        return refuse("HUMANISH_STUDY_ANALYSIS_INVALID", analysis.message);
     const unsupported = automaticAnalysisRouteReason(config);
     if (unsupported)
-        return refuse("HUMANISH_LAB_ANALYSIS_UNSUPPORTED", unsupported);
+        return refuse("HUMANISH_STUDY_ANALYSIS_UNSUPPORTED", unsupported);
     const tasksReason = taskProtocolValidationReason(config);
     if (tasksReason)
-        return refuse("HUMANISH_LAB_TASKS_UNSUPPORTED", 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_SIM_COUNT", "count must be a positive integer.");
+        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 {
@@ -115,42 +65,37 @@ function planPreview(config, options, input) {
  * 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) {
+export function planLab(config, options, deps = {}) {
     const lab = localBrowserDefaults(config);
-    const input = {
-        dryRun: resolveLabDryRun(lab, options.dryRun, true) ?? true,
-        ...(options.lab === undefined ? {} : { lab: options.lab }),
-    };
-    const result = planRoute(routeOf(config), lab, options, input);
+    const input = { dryRun: resolveLabDryRun(lab, options.dryRun, true) ?? true };
+    const result = planRoute(routeOf(config), lab, options, input, deps);
     if (!result.ok)
         return result;
-    return { ok: true, planned: { plan: result.plan } };
+    // 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 };
+    return { ok: true, planned: { plan } };
 }
-function planRoute(route, lab, options, input) {
+function planRoute(route, lab, options, input, deps) {
     switch (route) {
         case "preview":
             return planPreview(lab, options, input);
         case "computer-use":
             return planComputerUseLab(lab, {
                 ...input,
-                ...(options.cuaHooks === undefined ? {} : { hooks: options.cuaHooks }),
+                hasRunSession: deps.runSession !== undefined,
+                driving: callerDrivingOf(options),
                 ...(options.count === undefined ? {} : { countOverride: options.count }),
                 ...(options.rerun === undefined ? {} : { rerun: options.rerun }),
             });
         case "shared-world":
             return planSharedWorldLab(lab, {
                 ...input,
-                ...(options.sharedWorldHooks === undefined ? {} : { hooks: options.sharedWorldHooks }),
+                hasRunSession: deps.runSession !== undefined,
             });
         case "terminal":
-            return planTerminalLab(lab, {
-                ...input,
-                ...(options.terminalHooks === undefined ? {} : { hooks: options.terminalHooks }),
-            });
+            return planTerminalLab(lab, { ...input, hasCostProbe: deps.costProbe !== undefined });
         case "scripted":
-            return planScriptedLab(lab, {
-                ...input,
-                ...(options.scriptedHooks === undefined ? {} : { hooks: options.scriptedHooks }),
-            });
+            return planScriptedLab(lab, { ...input, injectedBrowser: injectedBrowser(deps) });
     }
 }

package/dist/lab/preflight-probes.js

@@ -19,7 +19,7 @@ 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 +28,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 +43,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 +63,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,13 +82,13 @@ 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,
@@ -98,12 +98,12 @@ export async function runSandboxLoopbackPreflight(ctx) {
     }
     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
@@ -216,7 +216,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 +224,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 };

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

@@ -1,5 +1,6 @@
 import type { LabPreflightCheck, LabPreflightResult, PreflightContext } from "./preflight.js";
-export declare const LAB_PREFLIGHT_SCHEMA = "humanish.lab-preflight-result.v1";
+/** The schema of `lab preflight` 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?: LabPreflightCheck;
 }): LabPreflightResult;

package/dist/lab/preflight-result.js

@@ -1,23 +1,22 @@
 // The preflight result a run returns, built from its context. preflight.ts and the probes in
 // preflight-probes.ts both finish through these, so they live below both.
-import { backendOf } from "./plan.js";
 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 `lab preflight` 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.lab,
+        studyId: ctx.labId,
         origin: ctx.origin,
         path: ctx.path,
-        backend: backendOf(ctx.route),
         route: ctx.route,
         reachability: ctx.reachability,
         checks,