humanish 0.108.0 → 0.109.1

package/dist/{lab → study}/init-templates.js

@@ -1,8 +1,9 @@
+import { DEFAULT_ANALYSIS_MAX_COST_USD } from "../analysis/automatic-config.js";
 export const DEFAULT_LOCAL_BROWSER_STARTER = {
     appUrl: "http://127.0.0.1:3000",
     mission: "Use the app's primary flow. Explain anything confusing and stop when the task is complete or you are stuck.",
 };
-function localBrowserLab(starter = DEFAULT_LOCAL_BROWSER_STARTER) {
+function localBrowserStudy(starter = DEFAULT_LOCAL_BROWSER_STARTER) {
     return {
         path: "humanish/studies/local-browser.yaml",
         plane: "source",
@@ -34,19 +35,23 @@ defaults:
     };
 }
 /**
- * The flagship live lab. A ChatGPT-account Codex participant has no API-dollar price, so preflight
+ * The flagship live study. A ChatGPT-account Codex participant has no API-dollar price, so preflight
  * refuses a dollar cap on it (HUMANISH_COMPUTER_USE_UNPRICED_CAP); that variant is bounded by the
  * session timeout instead of a cap it could never enforce.
  */
-function tryLiveLab(actor, localAgent = "codex") {
+function tryLiveStudy(actor, localAgent = "codex") {
     const account = actor === "local-agent";
     const needs = account
         ? `  Needs E2B_API_KEY and the coding agent signed in on this machine. Cost: one small task, a few
   E2B desktop minutes and the agent's account usage. humanish cannot put a dollar cap on account
-  usage, so the ten-minute session limit below bounds the run.`
+  usage, so the ten-minute session limit below bounds the run. When OPENAI_API_KEY is set, the
+  analysis after the run bills it: humanish refuses that request before it starts if its estimate
+  is over $${DEFAULT_ANALYSIS_MAX_COST_USD}. Set review.analysis: false to skip it.`
         : `  Needs E2B_API_KEY and OPENAI_API_KEY. Cost: one small task with a $2 cap on estimated model
   spend. The run stops before its next model request once the estimate passes $2, so the last
-  request can go slightly over, and hosted desktop time is billed separately.`;
+  request can go slightly over, and hosted desktop time is billed separately. The analysis after
+  the run bills the same key outside that cap: humanish refuses it before it starts if its
+  estimate is over $${DEFAULT_ANALYSIS_MAX_COST_USD}. Set review.analysis: false to skip it.`;
     const participant = account
         ? `# Your machine has a coding agent signed in, so this study uses it: no provider API key, only
 # E2B. To use a provider key instead, swap to \`type: openai-computer-use\` and add caps.maxUsd.
@@ -229,8 +234,8 @@ defaults:
   open: true
 `,
     },
-    tryLiveLab("openai-computer-use"),
-    localBrowserLab(),
+    tryLiveStudy("openai-computer-use"),
+    localBrowserStudy(),
     {
         path: "humanish/studies/cua-browser.yaml",
         plane: "source",
@@ -401,16 +406,16 @@ export const humanishScripts = {
     "humanish:verify": "humanish verify",
 };
 /**
- * The starter files, with the live lab written for the brain this machine can use.
+ * The starter files, with the live study written for the brain this machine can use.
  *
- * `local-agent` is not a variant of the lab so much as a different participant: on a machine with
+ * `local-agent` is not a variant of the study so much as a different participant: on a machine with
  * a signed-in Codex and no provider key, the study runs with the operator's own agent and needs
  * only E2B. Writing the other one there would hand someone homework instead of a first run.
  */
 export function starterFilesFor(actor, localBrowser = DEFAULT_LOCAL_BROWSER_STARTER, localAgent) {
     return starterFiles.map((file) => file.path === "humanish/studies/local-browser.yaml"
-        ? localBrowserLab(localBrowser)
+        ? localBrowserStudy(localBrowser)
         : file.path === "humanish/studies/try-live.yaml"
-            ? tryLiveLab(actor, localAgent)
+            ? tryLiveStudy(actor, localAgent)
             : file);
 }

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

@@ -5,7 +5,7 @@ export interface InitOptions {
     yes?: boolean;
     /** Injected so a test can decide what credentials this machine appears to have. */
     env?: NodeJS.ProcessEnv;
-    /** Configure the starter local-browser lab without making the operator edit YAML. */
+    /** Configure the starter local-browser study without making the operator edit YAML. */
     localBrowser?: {
         appUrl: string;
         mission?: string;

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

@@ -8,7 +8,7 @@ import { assertPreparedSelectedOutputDirectory, prepareContainedOutputDirectory,
 import { validateCwd } from "../run/project.js";
 import { pathExists, readTextIfExists, validateInitProjectPaths } from "./init-paths.js";
 import { planGitignore, planPackageJson } from "./init-plan.js";
-import { otherStudyFiles, STUDY_DIRECTORIES, studyFileStem } from "../study/files.js";
+import { otherStudyFiles, STUDY_DIRECTORIES, studyFileStem } from "./files.js";
 const INIT_RESPONSE_SCHEMA = "humanish.init-result.v1";
 export async function runInit(options) {
     const requestedCwd = path.resolve(options.cwd);
@@ -38,7 +38,7 @@ export async function runInit(options) {
         return failed(initialPathCheck);
     }
     await planAgentsFile(preparedProjectRoot, cwd, plan);
-    // The starter live lab is written for the brain this machine can actually use. Shipping it as
+    // The starter live study is written for the brain this machine can actually use. Shipping it as
     // openai-computer-use on a machine with no provider key but a signed-in Codex would hand someone
     // a file that asks for a credential they were just told they do not need.
     const machine = await firstRunEnvironment(options.env ?? process.env, requestedCwd);
@@ -149,8 +149,11 @@ async function planStarterFiles(preparedProjectRoot, cwd, files, localBrowserReq
                 target: file.plane,
                 reason: `${others.join(", ")} already uses the name ${stem}`,
             });
+            // humanish no longer reads a labs/ file, but migrate needs its name free to move it.
             const legacy = others.some((other) => other.split(path.sep).includes("labs"));
-            plan.warnings.push(`Skipped ${file.path}: ${others.join(", ")} already uses the name ${stem}, and a second file with that name would make \`run ${stem}\` fail.${legacy ? " Run humanish migrate to move it to a studies/ directory." : ""}`);
+            plan.warnings.push(legacy
+                ? `Skipped ${file.path}: ${others.join(", ")} already uses the name ${stem}. Move it to a studies/ directory; humanish migrate converts and moves a v2 file.`
+                : `Skipped ${file.path}: ${others.join(", ")} already uses the name ${stem}, and a second file with that name would make \`run ${stem}\` fail.`);
         }
         else if (existing === null) {
             plan.changes.push({
@@ -268,7 +271,7 @@ function validateLocalBrowserStarter(input) {
     return { ok: true, value };
 }
 /**
- * What this machine can run, for the starter lab and the next steps. Local CLI status is
+ * What this machine can run, for the starter study and the next steps. Local CLI status is
  * classified without returning its output or reading its credential file. Provider keys go
  * through the same discovery chain as every other command (process env, the project overlay,
  * `e2b auth login`, the `humanish keys set` store) and only their presence is read, never a value.

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

@@ -1,4 +1,4 @@
-/** The first key in `raw` that LAB_KEYS does not list, as an error message; undefined if none. */
-export declare function findUnknownLabKey(raw: unknown): string | undefined;
+/** The first key in `raw` that V2_KEYS does not list, as an error message; undefined if none. */
+export declare function findUnknownV2Key(raw: unknown): string | undefined;
 /** The first key in a humanish.study.v3 document that the format does not have; undefined if none. */
 export declare function findUnknownStudyKey(raw: unknown): string | undefined;

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

@@ -1,4 +1,4 @@
-// Every mapping key parseLabConfig reads, by path. A key that is not listed fails the lab as
+// Every mapping key parseStudy reads, by path. A key that is not listed fails the study as
 // unknown, so a typo stops the run instead of being dropped. `true` marks a leaf: its parser
 // checks the value (scalars, lists, and mappings that check their own keys). Each level satisfies
 // the parsed type's keys, so a field added to a Lab* interface must be added here too.
@@ -166,7 +166,7 @@ const EMAIL = {
     allowedOrigins: true,
     recipients: { lane: true, address: true },
 };
-const LAB_KEYS = {
+const V2_KEYS = {
     schema: true,
     id: true,
     title: true,
@@ -225,14 +225,14 @@ const STUDY_KEYS = {
     caps: CAPS,
     execution: without(EXECUTION, "caps"),
     scenario: true,
-    policies: LAB_KEYS.policies,
-    review: LAB_KEYS.review,
-    defaults: LAB_KEYS.defaults,
-    comms: LAB_KEYS.comms,
+    policies: V2_KEYS.policies,
+    review: V2_KEYS.review,
+    defaults: V2_KEYS.defaults,
+    comms: V2_KEYS.comms,
 };
-/** The first key in `raw` that LAB_KEYS does not list, as an error message; undefined if none. */
-export function findUnknownLabKey(raw) {
-    return walk(raw, LAB_KEYS, "", "lab");
+/** The first key in `raw` that V2_KEYS does not list, as an error message; undefined if none. */
+export function findUnknownV2Key(raw) {
+    return walk(raw, V2_KEYS, "", "study");
 }
 /** The first key in a humanish.study.v3 document that the format does not have; undefined if none. */
 export function findUnknownStudyKey(raw) {
@@ -270,7 +270,7 @@ function unknownKeysMessage(path, unknown, known, noun) {
         const suggestion = closest(key, known);
         return suggestion ? `${key} (did you mean \`${suggestion}\`?)` : key;
     });
-    return `Unknown ${noun} field(s)${path ? ` in \`${path}\`` : ""}: ${named.join(", ")}. Known fields: ${known.join(", ")}.`;
+    return `Unknown ${noun} ${unknown.length === 1 ? "field" : "fields"}${path ? ` in \`${path}\`` : ""}: ${named.join(", ")}. Known fields: ${known.join(", ")}.`;
 }
 // The known key within edit distance 2, or one that differs only in case.
 function closest(key, known) {

package/dist/study/migrate.d.ts

@@ -1,4 +1,4 @@
-import type { StudyRoute } from "../lab/parse/study-v3.js";
+import type { StudyRoute } from "./routing.js";
 import { type DroppedKey, type MovedKey } from "./convert.js";
 /** The schema of `humanish migrate --json`. */
 declare const MIGRATE_SCHEMA = "humanish.migrate-result.v1";
@@ -21,6 +21,8 @@ export interface MigrateResult {
     readonly files: readonly MigrateFile[];
     /** Files left behind after a clean-up step found them changed: sources, backups or temp files. */
     readonly unresolved?: readonly string[];
+    /** The labs/ directories the moves emptied and migrate removed, or with `--dry-run` would remove. */
+    readonly removedDirectories?: readonly string[];
     readonly error?: {
         readonly code: "HUMANISH_MIGRATE_REFUSED" | "HUMANISH_MIGRATE_FAILED";
         readonly phase: "plan" | "stage" | "commit" | "clean-up";
@@ -34,8 +36,11 @@ export interface MigrateOptions {
     /** Files to convert. Without any, the six study directories are scanned. */
     readonly paths?: readonly string[];
     readonly dryRun?: boolean;
-    /** Called with the plan before anything is written, so a caller can print every destination. */
-    readonly onPlan?: (files: readonly MigrateFile[]) => void;
+    /**
+     * Called with the plan before anything is written, so a caller can print every destination and
+     * each labs/ directory the moves empty, which migrate then removes.
+     */
+    readonly onPlan?: (files: readonly MigrateFile[], emptied: readonly string[]) => void;
     /** Replaces `fs.link`. Tests use it to stand in for a filesystem without hard links. */
     readonly link?: (from: string, to: string) => Promise<void>;
     /** Called between stage and commit, and between commit and clean-up. Tests change files there. */

package/dist/study/migrate.js

@@ -8,6 +8,8 @@
 //    name, so no file this run did not write is ever overwritten. A failure undoes the commits.
 // 4. Clean up: delete each moved source and each rewrite's original, once checked (owned-files.ts).
 //    A file that changed since the plan is kept and listed; a rewrite's original as <name>.v2.bak.
+//    Then a labs/ directory whose every entry moved is removed with a plain rmdir, which fails, and
+//    keeps the directory, when anything else is in it by then.
 import { randomUUID } from "node:crypto";
 import { link, lstat, readdir, readFile, realpath, rename, rmdir } from "node:fs/promises";
 import path from "node:path";
@@ -317,6 +319,46 @@ async function undoCommits(root, writes, linkFile) {
     }
     return unrestored;
 }
+// Each labs/ directory whose every entry, a dotfile or a subdirectory included, is a file this run
+// moves out. Only these are removed after the move.
+async function emptiedRetiredDirectories(root, writes) {
+    const moving = new Map();
+    for (const write of writes) {
+        if (write.file.action !== "move")
+            continue;
+        const directory = path.dirname(write.sourcePath);
+        const relative = path.relative(root, directory);
+        const retired = STUDY_DIRECTORIES.some((entry) => entry.family === "labs" && entry.relativeDir === relative);
+        if (!retired)
+            continue;
+        const entry = moving.get(directory) ?? { write, names: new Set() };
+        entry.names.add(path.basename(write.sourcePath));
+        moving.set(directory, entry);
+    }
+    const emptied = [];
+    for (const [directory, { write, names }] of moving) {
+        const entries = await readdir(directory).catch(() => undefined);
+        if (entries !== undefined && entries.every((name) => names.has(name)))
+            emptied.push(write);
+    }
+    return emptied;
+}
+// Remove each emptied labs/ directory, if it is still the one the plan read. rmdir is not
+// recursive, so a file that appeared in it since the plan keeps it. Returns the removed paths.
+async function removeEmptiedDirectories(root, emptied) {
+    const removed = [];
+    for (const write of emptied) {
+        try {
+            await assertDirectory(write.sourceDirectory, root);
+            await rmdir(path.dirname(write.sourcePath));
+            removed.push(path.relative(root, path.dirname(write.sourcePath)));
+        }
+        catch {
+            // Not empty, or not the directory the plan read: it stays.
+        }
+    }
+    return removed;
+}
 // Delete each moved source and each rewrite's original, but only once the v3 file is in place as
 // written, and only if the old file is still the one the plan read (removeChecked). Anything kept
 // is listed; a rewrite's original is kept as <name>.v2.bak.
@@ -356,9 +398,17 @@ export async function migrateStudies(options) {
     const linkFile = options.link ?? link;
     try {
         ({ files, writes } = await planWrites(root, options));
-        options.onPlan?.(files);
-        if (options.dryRun === true || writes.length === 0)
-            return { ...base, ok: true, files };
+        const emptied = await emptiedRetiredDirectories(root, writes);
+        const emptiedPaths = emptied.map((write) => path.relative(root, path.dirname(write.sourcePath)));
+        options.onPlan?.(files, emptiedPaths);
+        if (options.dryRun === true || writes.length === 0) {
+            return {
+                ...base,
+                ok: true,
+                files,
+                ...(emptiedPaths.length === 0 ? {} : { removedDirectories: emptiedPaths }),
+            };
+        }
         try {
             await stage(root, writes, created);
             options.onPhase?.("stage");
@@ -386,7 +436,13 @@ export async function migrateStudies(options) {
                 },
             };
         }
-        return { ...base, ok: true, files };
+        const removed = await removeEmptiedDirectories(root, emptied);
+        return {
+            ...base,
+            ok: true,
+            files,
+            ...(removed.length === 0 ? {} : { removedDirectories: removed }),
+        };
     }
     catch (error) {
         const failure = error instanceof MigrateError

package/dist/{lab → study}/parse/actors.d.ts

@@ -1,14 +1,14 @@
-import type { LabActor, LabParticipantEntry, LabParticipantFocus, LabConfigParseFailure } from "../types.js";
+import type { StudyActor, StudyParticipantEntry, StudyParticipantFocus, StudyParseFailure } from "../types.js";
 export declare const PARTICIPANT_ID_PATTERN: RegExp;
 export declare const PARTICIPANT_ID_MAX_CHARS = 40;
 /** The participant entries an actor declares, after roster groups expand into them. The manifest
  *  spells them `actors[].lanes`. Undefined when the actor declares none. */
-export declare function rosterOf<Entry = LabParticipantEntry>(actor: {
+export declare function rosterOf<Entry = StudyParticipantEntry>(actor: {
     readonly lanes?: readonly Entry[];
 } | undefined): readonly Entry[] | undefined;
 /** An actor's per-participant focus on the app-url route. The manifest spells it `laneFocus`. */
-export declare function focusOf(actor: Pick<LabActor, "laneFocus"> | undefined): LabParticipantFocus | undefined;
+export declare function focusOf(actor: Pick<StudyActor, "laneFocus"> | undefined): StudyParticipantFocus | undefined;
 export declare function parseActors(raw: unknown): {
     ok: true;
-    value: LabActor[];
-} | LabConfigParseFailure;
+    value: StudyActor[];
+} | StudyParseFailure;

package/dist/{lab → study}/parse/actors.js

@@ -6,7 +6,7 @@ import { registeredComputerUseActors, registeredScriptedBrowserActors, registere
 import { invalid, posInt, str } from "./values.js";
 import { isRecord } from "../../run/type-guards.js";
 // A participant id interpolates into its evidence paths (screenshots/<id>/, actors/<id>.json), so
-// it must be a public-safe path token, same shape as a lab id.
+// it must be a public-safe path token, same shape as a study id.
 export const PARTICIPANT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
 export const PARTICIPANT_ID_MAX_CHARS = 40;
 const METADATA_MAX_CHARS = 80;
@@ -19,7 +19,7 @@ export function rosterOf(actor) {
 export function focusOf(actor) {
     return actor?.laneFocus;
 }
-// Actor ids humanish no longer registers. Rejecting them at parse keeps a lab that names one
+// Actor ids humanish no longer registers. Rejecting them at parse keeps a study that names one
 // from running on a route that ignores actors[0].type, such as a this-repo dry run.
 const REMOVED_ACTOR_TYPES = new Set(["pi-agent-core", "claude-agent-sdk"]);
 // Only actors of a run kind a route dispatches. codex-app-server is registered but declares only
@@ -33,7 +33,7 @@ function routableActorTypes() {
 }
 export function parseActors(raw) {
     if (!Array.isArray(raw) || raw.length === 0) {
-        return invalid("Lab `actors` must be a non-empty array.");
+        return invalid("`actors` must be a non-empty array.");
     }
     // Multi-actor fan-out is not wired yet (only actors[0] is consumed). Fail closed rather than
     // silently ignore actors[1..]; multi-actor support lands in a later slice.
@@ -50,7 +50,7 @@ export function parseActors(raw) {
             return invalid(`actors[${index}].type is required.`);
         }
         if (REMOVED_ACTOR_TYPES.has(type)) {
-            return invalid(`actors[${index}].type "${type}" is no longer a humanish actor. Use an actor a lab route runs (one of: ${routableActorTypes().join(", ")}). To drive a study with a signed-in Claude Code, use type: local-agent with localAgent: claude.`);
+            return invalid(`actors[${index}].type "${type}" is no longer a humanish actor. Use an actor a study route runs (one of: ${routableActorTypes().join(", ")}). To drive a study with a signed-in Claude Code, use type: local-agent with localAgent: claude.`);
         }
         const actor = { type };
         const count = posInt(entry.count);
@@ -189,7 +189,7 @@ function parseRosterGroups(raw, actorIndex) {
  * Participant ids (when declared) must be public-safe path tokens and unique; grouping metadata
  * must be public-safe tokens; a device must be a known preset name. The
  * route-scoped cross-validation (`lanes` XOR `count`/`laneFocus`, device XOR raw resolution, cap 16)
- * runs in parseLabConfig where the route is known.
+ * runs in parseStudy where the route is known.
  */
 function parseParticipantEntries(raw, actorIndex) {
     if (raw === undefined) {

package/dist/study/parse/comms.d.ts

@@ -0,0 +1,12 @@
+import type { StudyComms, StudyCommsEmail, StudyCommsRecipient, StudyParseFailure } from "../types.js";
+export declare function parseComms(raw: unknown): {
+    ok: true;
+    value: StudyComms | undefined;
+} | StudyParseFailure;
+/** The participant a declared inbox recipient belongs to. The manifest spells it `lane`. */
+export declare function recipientParticipantId(recipient: StudyCommsRecipient): string;
+/** The declared recipients that name an address, in declaration order, by participant id. */
+export declare function addressedRecipients(email: Pick<StudyCommsEmail, "recipients">): {
+    participantId: string;
+    address: string;
+}[];

package/dist/study/parse/execution.d.ts

@@ -0,0 +1,19 @@
+import type { StudyParseFailure, StudyDefaults, StudyExecution, StudyPolicies, StudyReview, StudyScenario } from "../types.js";
+export declare function parseExecution(raw: unknown): {
+    ok: true;
+    value: StudyExecution | undefined;
+} | StudyParseFailure;
+export declare function parsePersonas(raw: unknown): Record<string, unknown>[] | undefined;
+export declare function parseScenario(raw: unknown): {
+    ok: true;
+    value: StudyScenario | undefined;
+} | StudyParseFailure;
+export declare function parsePolicies(raw: unknown): {
+    ok: true;
+    value: StudyPolicies | undefined;
+} | StudyParseFailure;
+export declare function parseReview(raw: unknown): {
+    ok: true;
+    value: StudyReview | undefined;
+} | StudyParseFailure;
+export declare function parseDefaults(raw: unknown): StudyDefaults | undefined;

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

@@ -1,7 +1,5 @@
-import { type LabConfigParseFailure } from "../types.js";
-declare const ROUTES: readonly ["preview", "computer-use", "shared-world", "terminal", "scripted"];
-/** A route a study declares. */
-export type StudyRoute = (typeof ROUTES)[number];
+import type { StudyRoute } from "../routing.js";
+import { type StudyParseFailure } from "../types.js";
 export interface StudyDocument {
     readonly route: StudyRoute;
     /** The same document in the humanish.lab.v2 spelling. */
@@ -12,7 +10,7 @@ export interface StudyDocument {
 type Parsed<T> = {
     ok: true;
     value: T;
-} | LabConfigParseFailure;
+} | StudyParseFailure;
 /** Rewrite a humanish.study.v3 document into humanish.lab.v2, or refuse it. */
 export declare function studyToV2(raw: Record<string, unknown>): Parsed<StudyDocument>;
 /**

package/dist/{lab → study}/parse/study-v3.js

@@ -1,10 +1,10 @@
 // humanish.study.v3, the study format. A study declares its route, one `actor`, its `participants`
 // and one `caps` block. studyToV2 rewrites a v3 document into the v2 spelling, so both formats run
-// through one parser and parse into the same LabConfig. parseLabConfig then checks the declared
+// through one parser and parse into the same StudyConfig. parseStudy then checks the declared
 // route against the one the config takes, and refuses any field that route does not read.
 import { isRecord } from "../../run/type-guards.js";
 import { findUnknownStudyKey } from "../keys.js";
-import { LAB_CONFIG_SCHEMA } from "../types.js";
+import { V2_SCHEMA } from "../types.js";
 import { PARTICIPANT_ID_MAX_CHARS, PARTICIPANT_ID_PATTERN } from "./actors.js";
 import { invalid, posInt } from "./values.js";
 // The values `route:` takes: every route routeOf can return.
@@ -81,7 +81,7 @@ export function studyToV2(raw) {
         ? withKey(raw.execution, "caps", caps)
         : raw.execution;
     const subject = route === "shared-world" ? withKey(raw.subject, "topology", "shared-world") : raw.subject;
-    const v2 = { schema: LAB_CONFIG_SCHEMA };
+    const v2 = { schema: V2_SCHEMA };
     const fields = [
         ["id", raw.id],
         ["title", raw.title],

package/dist/{lab → study}/parse/subject-state.d.ts

@@ -1,4 +1,4 @@
-import type { LabConfigParseFailure, LabSubjectState } from "../types.js";
+import type { StudyParseFailure, StudySubjectState } from "../types.js";
 /**
  * Literal non-secret subject env. Real apps need configuration before they will boot: a public base
  * URL, a transport selector, a feature flag, and none of that is secret. Routing it through
@@ -10,21 +10,21 @@ import type { LabConfigParseFailure, LabSubjectState } from "../types.js";
 export declare function parseEnvValues(raw: unknown): {
     ok: true;
     value?: Record<string, string>;
-} | LabConfigParseFailure;
+} | StudyParseFailure;
 /**
- * Structural parse of `subject.state` into a candidate LabSubjectState. Deliberately keeps
+ * Structural parse of `subject.state` into a candidate StudySubjectState. Deliberately keeps
  * unrecognized `when`/`timeoutMs` values in the candidate (instead of silently dropping
  * them) so subjectStateInvalidReason rejects them: a state declaration that silently does
  * less than it says would claim more than its mechanism does.
  */
 export declare function parseState(raw: unknown): {
     ok: true;
-    value: LabSubjectState | undefined;
-} | LabConfigParseFailure;
+    value: StudySubjectState | undefined;
+} | StudyParseFailure;
 /**
- * Semantic validation for `subject.state`, shared by parseLabConfig and the engine
- * (the route re-enforces it on configs that arrive through runLab). Returns
+ * Semantic validation for `subject.state`, shared by parseStudy and the engine
+ * (the route re-enforces it on configs that arrive through runStudyWith). Returns
  * the failure message, or null when the declaration is valid. Reads the candidate
  * defensively: library callers can hand the engine arbitrarily-shaped objects.
  */
-export declare function subjectStateInvalidReason(state: LabSubjectState, env: readonly string[] | undefined): string | null;
+export declare function subjectStateInvalidReason(state: StudySubjectState, env: readonly string[] | undefined): string | null;

package/dist/{lab → study}/parse/subject-state.js

@@ -1,6 +1,6 @@
 // The state and env channels of a served subject (clone or local-tree): `subject.envValues`,
 // the structural parse of `subject.state`, and subjectStateInvalidReason, the semantic check
-// parseLabConfig and the computer-use route share.
+// parseStudy and the computer-use route share.
 import { containsSensitive } from "../../evidence/redaction.js";
 import { ENV_NAME_PATTERN, invalid, posInt, str, strList } from "./values.js";
 import { isRecord } from "../../run/type-guards.js";
@@ -39,7 +39,7 @@ export function parseEnvValues(raw) {
     return { ok: true, value: envValues };
 }
 /**
- * Structural parse of `subject.state` into a candidate LabSubjectState. Deliberately keeps
+ * Structural parse of `subject.state` into a candidate StudySubjectState. Deliberately keeps
  * unrecognized `when`/`timeoutMs` values in the candidate (instead of silently dropping
  * them) so subjectStateInvalidReason rejects them: a state declaration that silently does
  * less than it says would claim more than its mechanism does.
@@ -96,8 +96,8 @@ const STATE_STEP_WHENS = [
     "after-ready",
 ];
 /**
- * Semantic validation for `subject.state`, shared by parseLabConfig and the engine
- * (the route re-enforces it on configs that arrive through runLab). Returns
+ * Semantic validation for `subject.state`, shared by parseStudy and the engine
+ * (the route re-enforces it on configs that arrive through runStudyWith). Returns
  * the failure message, or null when the declaration is valid. Reads the candidate
  * defensively: library callers can hand the engine arbitrarily-shaped objects.
  */

package/dist/{lab → study}/parse/subject.d.ts

@@ -1,8 +1,8 @@
-import type { LabConfigParseFailure, LabSubject } from "../types.js";
+import type { StudyParseFailure, StudySubject } from "../types.js";
 export declare function parseSubject(raw: unknown): {
     ok: true;
-    value: LabSubject;
-} | LabConfigParseFailure;
+    value: StudySubject;
+} | StudyParseFailure;
 export declare const PUBLIC_TARGET_OWNER_PATTERN: RegExp;
 export declare function isLoopbackUrl(value: string): boolean;
 /** A well-formed http(s) URL (any host). Shape gate before the loopback/public-target policy. */

package/dist/{lab → study}/parse/subject.js

@@ -4,7 +4,7 @@ import { parseEnvValues, parseState, subjectStateInvalidReason } from "./subject
 import { isRecord } from "../../run/type-guards.js";
 export function parseSubject(raw) {
     if (!isRecord(raw)) {
-        return invalid("Lab `subject` is required and must be an object.");
+        return invalid("`subject` is required and must be an object.");
     }
     const source = str(raw.source);
     if (source !== "this-repo" &&
@@ -71,19 +71,19 @@ function misplacedFieldFailure(source, raw) {
     // tree): both routes serve a subject in-sandbox with the same install/build/start/url +
     // env-name + seed/external/checkpoint shapes.
     if (source !== "clone" && source !== "local-tree" && raw.serve !== undefined) {
-        return invalid("`subject.serve` applies only to clone subjects or local-tree subjects (the lab serves the cloned/packed app in-sandbox).");
+        return invalid("`subject.serve` applies only to clone subjects or local-tree subjects (humanish serves the cloned or packed app in the sandbox).");
     }
     if (source !== "clone" && source !== "local-tree" && raw.env !== undefined) {
         return invalid("`subject.env` applies only to clone subjects or local-tree subjects (the served app's environment channel).");
     }
     if (source !== "clone" && source !== "local-tree" && raw.state !== undefined) {
-        return invalid("`subject.state` applies only to clone subjects or local-tree subjects (the lab seeds the state it serves).");
+        return invalid("`subject.state` applies only to clone subjects or local-tree subjects (humanish seeds the state it serves).");
     }
     // repos/clone are clone-only (a fresh-clone subject's git inputs). local-tree packs the
     // resolution cwd itself, so it has no repo slug to clone and gets its own precise reasons
     // rather than falling through to the generic clone-only message below.
     if (source === "local-tree" && raw.repos !== undefined) {
-        return invalid("`subject.repos` does not apply to local-tree subjects. The local-tree route packs the lab resolution cwd itself; there is no owner/repo slug to clone.");
+        return invalid("`subject.repos` does not apply to local-tree subjects. The local-tree route packs the study's working directory itself; there is no owner/repo slug to clone.");
     }
     if (source === "local-tree" && raw.clone !== undefined) {
         return invalid("`subject.clone` does not apply to local-tree subjects. Declare `subject.localTree` instead (keep/exclude/maxArchiveBytes).");
@@ -126,7 +126,7 @@ function parseCloneSubject(raw, subject) {
 function parseLocalTreeSubject(raw, subject) {
     // A local-tree subject exists to be packed and served; there is no other way to boot it, so
     // serve is required here. Clone subjects get the same requirement from each route's checks in
-    // parseLabConfig.
+    // parseStudy.
     if (raw.serve === undefined) {
         return invalid("`subject.serve` is required when source is local-tree: a local-tree subject exists to be packed and served, so declare install/build/start/url exactly like the clone route.");
     }
@@ -175,7 +175,7 @@ function parseServedApp(raw, subject) {
         return stateResult;
     }
     if (stateResult.value) {
-        // Semantic validation is shared with the engine (runCuaActorLab re-enforces it for
+        // Semantic validation is shared with the engine (runCuaActorStudy re-enforces it for
         // configs that arrive through the library API without the parser).
         const reason = subjectStateInvalidReason(stateResult.value, subject.env);
         if (reason) {
@@ -241,7 +241,7 @@ function parsePublicTarget(raw) {
     return { ok: true, value: { owner, authorized: true } };
 }
 // The product name interpolates into evidence labels and the composed prompt; the public-safe
-// token shape is the same strict constraint as a lab id.
+// token shape is the same strict constraint as a study id.
 const PRODUCT_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
 function parseProduct(raw) {
     if (!isRecord(raw)) {
@@ -289,7 +289,7 @@ function parseProduct(raw) {
         },
     };
 }
-// Public-safe stance: a computer-use actor's entry URL is always an app the lab owner runs on
+// Public-safe stance: a computer-use actor's entry URL is always an app the study owner runs on
 // loopback (inside the sandbox), never an arbitrary public site. (The constraint binds the
 // entry point; a navigation watchdog for mid-session escapes is a later slice.) Exported so
 // the engine re-enforces the same boundary on configs that arrive through the library API.

package/dist/{lab → study}/parse/values.d.ts

@@ -1,7 +1,7 @@
-import type { LabConfigParseFailure } from "../types.js";
+import type { StudyParseFailure } from "../types.js";
 export declare const REPO_SLUG_PATTERN: RegExp;
 export declare const ENV_NAME_PATTERN: RegExp;
-export declare function invalid(message: string): LabConfigParseFailure;
+export declare function invalid(message: string): StudyParseFailure;
 export declare function str(value: unknown): string | undefined;
 export declare function optionalStr(key: string, value: unknown): Record<string, string>;
 export declare function strList(value: unknown): string[] | undefined;

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

@@ -1,6 +1,6 @@
 import { type ResolvedPersona } from "./persona.js";
 import { type PreparedSelectedOutputDirectory } from "../run/contained-output.js";
-import type { LabActor } from "./types.js";
+import type { StudyActor } 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;
 /**
@@ -22,11 +22,11 @@ export declare function resolveCommittedPersonas(projectRoot: PreparedSelectedOu
     warnings: string[];
 }>;
 /**
- * Every persona id a lab config could put on a browser participant: the roster when one is
+ * Every persona id a study 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">[];
+export declare function studyPersonaIds(config: {
+    actors?: readonly Pick<StudyActor, "persona" | "lanes">[];
 }): string[];
 /**
  * Same resolution from a plain cwd, for the labs that carry a directory string rather than an

package/dist/{lab → study}/persona-resolve.js

@@ -81,10 +81,10 @@ export async function resolveCommittedPersonas(projectRoot, personaIds) {
     return { personas, warnings };
 }
 /**
- * Every persona id a lab config could put on a browser participant: the roster when one is
+ * Every persona id a study 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) {
+export function studyPersonaIds(config) {
     const ids = [];
     for (const actor of config.actors ?? []) {
         if (actor.persona)