humanish 0.107.0 → 0.109.0

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

@@ -1,27 +1,27 @@
 // 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";
 /**
- * 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
+ * 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
  * `subject.env` would force an adopter to carry a private env file just to reproduce a public study.
  *
- * These values ARE recorded in evidence (they are part of how the subject was configured), so a
+ * These values are recorded in evidence (they are part of how the subject was configured), so a
  * value that looks like a credential is refused here rather than committed to a public repo.
  */
 export function parseEnvValues(raw) {
     if (raw === undefined)
         return { ok: true };
     if (!isRecord(raw)) {
-        return invalid("`subject.envValues` must be a mapping of env var NAME to a literal non-secret value.");
+        return invalid("`subject.envValues` must map environment variable names to literal values that are not secret.");
     }
     const envValues = {};
     for (const [name, rawValue] of Object.entries(raw)) {
         if (!ENV_NAME_PATTERN.test(name)) {
-            return invalid(`subject.envValues keys must be env var NAMES like NEXT_PUBLIC_APP_URL (got "${name}").`);
+            return invalid(`subject.envValues keys must be environment variable names like NEXT_PUBLIC_APP_URL, and "${name}" is not one.`);
         }
         const value = typeof rawValue === "number" || typeof rawValue === "boolean"
             ? String(rawValue)
@@ -30,19 +30,19 @@ export function parseEnvValues(raw) {
             return invalid(`\`subject.envValues.${name}\` must be a string, number, or boolean.`);
         }
         // Reuse the redaction module's own detector rather than inventing a second opinion about what
-        // a secret looks like — the two must never disagree about the same string.
+        // a secret looks like; the two must never disagree about the same string.
         if (containsSensitive(value)) {
-            return invalid(`\`subject.envValues.${name}\` looks like a secret or a local path, and these values are committed with the lab and recorded in evidence. Declare the NAME in \`subject.env\` instead — those values come from the caller's environment and never persist.`);
+            return invalid(`\`subject.envValues.${name}\` looks like a secret or a local path, and envValues are committed with the study and recorded in evidence. List the name in \`subject.env\` instead: its value then comes from your environment and is never stored.`);
         }
         envValues[name] = value;
     }
     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 violate invariant 6.
+ * them) so subjectStateInvalidReason rejects them: a state declaration that silently does
+ * less than it says would claim more than its mechanism does.
  */
 export function parseState(raw) {
     if (raw === undefined) {
@@ -68,7 +68,7 @@ export function parseState(raw) {
     if (raw.external !== undefined) {
         const external = strList(raw.external);
         if (!external) {
-            return invalid("`subject.state.external` must be a non-empty list of env var NAMES when set.");
+            return invalid("`subject.state.external` must be a non-empty list of environment variable names when it is set.");
         }
         state.external = external;
     }
@@ -79,7 +79,7 @@ export function parseState(raw) {
         state.checkpoint = raw.checkpoint.map((probe) => ({
             name: typeof probe.name === "string" ? probe.name.trim() : "",
             command: typeof probe.command === "string" ? probe.command.trim() : "",
-            // Preserve the redact list verbatim (literal secret values may contain commas, so do NOT
+            // Preserve the redact list verbatim (literal secret values may contain commas, so do not
             // run it through the comma-splitting strList); subjectStateInvalidReason validates the shape.
             ...(probe.redact === undefined ? {} : { redact: probe.redact }),
         }));
@@ -87,7 +87,7 @@ export function parseState(raw) {
     return { ok: true, value: state };
 }
 // The step name interpolates into in-sandbox script/status/log paths (`subject-state-<name>`);
-// the strict shape is load-bearing, exactly like the repo slug.
+// so the shape is strict, exactly like the repo slug.
 const STATE_STEP_NAME_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
 const STATE_STEP_NAME_MAX_CHARS = 40;
 const STATE_STEP_WHENS = [
@@ -96,10 +96,10 @@ const STATE_STEP_WHENS = [
     "after-ready",
 ];
 /**
- * Semantic validation for `subject.state`, shared by parseLabConfig and the engine
- * (runCuaActorLab re-enforces it on configs that arrive through the library API). 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.
+ * defensively: library callers can hand the engine arbitrarily-shaped objects.
  */
 export function subjectStateInvalidReason(state, env) {
     const seed = state.seed;
@@ -140,11 +140,11 @@ export function subjectStateInvalidReason(state, env) {
     }
     if (external !== undefined) {
         if (!Array.isArray(external) || external.length === 0) {
-            return "`subject.state.external` must be a non-empty list of env var NAMES when set.";
+            return "`subject.state.external` must be a non-empty list of environment variable names when it is set.";
         }
         for (const name of external) {
             if (typeof name !== "string" || !ENV_NAME_PATTERN.test(name)) {
-                return "subject.state.external entries must be env var NAMES like DATABASE_URL; values come from the caller's environment and are never persisted.";
+                return "subject.state.external entries must be environment variable names like DATABASE_URL. Their values come from your environment and are never stored.";
             }
             if (!env?.includes(name)) {
                 return "subject.state.external names must also be declared in subject.env (the declaration must name a provisioned channel).";

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" &&
@@ -17,9 +17,9 @@ export function parseSubject(raw) {
         return invalid("`subject.source` must be one of: this-repo, clone, app-url, local-app, terminal-product, desktop-cli, local-tree.");
     }
     const subject = { source };
-    // topology is enum-validated everywhere; its SEMANTICS (shared-world requires clone × e2b-desktop
+    // topology is enum-validated everywhere; its semantics (shared-world requires clone × e2b-desktop
     // × a ≥2 roster) are enforced in the shared-world cross-validation below, and a set-but-unconsumed
-    // topology warns as inert off the shared-world route (invariant 6).
+    // topology warns as inert off the shared-world route.
     if (raw.topology !== undefined) {
         const topology = str(raw.topology);
         if (topology !== "per-lane-worlds" && topology !== "shared-world") {
@@ -27,12 +27,12 @@ export function parseSubject(raw) {
         }
         subject.topology = topology;
     }
-    // exposure is enum-validated everywhere; it is REQUIRED on the concurrent shared-world route (the
+    // exposure is enum-validated everywhere; it is required on the concurrent shared-world route (the
     // getHost synthetic-subject attestation) and warns inert elsewhere.
     if (raw.exposure !== undefined) {
         const exposure = str(raw.exposure);
         if (exposure !== "synthetic") {
-            return invalid("`subject.exposure` must be `synthetic` (the author attestation that the getHost-exposed subject is synthetic seeded data).");
+            return invalid("`subject.exposure` must be `synthetic`: your statement that the subject served on a public sandbox URL holds only synthetic seeded data.");
         }
         subject.exposure = exposure;
     }
@@ -57,51 +57,51 @@ export function parseSubject(raw) {
 }
 /** The first field set on a source it cannot act on, in the order parseSubject has always checked. */
 function misplacedFieldFailure(source, raw) {
-    // `product` is terminal-product-only; reject it elsewhere (invariant 6: a field that cannot act
-    // on this route is an honest parse error, not silently dropped).
+    // `product` is terminal-product-only; reject it elsewhere. A field that cannot act on this
+    // route is a parse error and is never silently dropped.
     if (source !== "terminal-product" && source !== "desktop-cli" && raw.product !== undefined) {
         return invalid("`subject.product` applies only to terminal-product and desktop-cli subjects (the CLI a participant studies from public surfaces).");
     }
-    // appUrl is app-url/local-app-only; a terminal-product subject drives PUBLIC surfaces, not a
-    // single loopback app — reject appUrl on it.
+    // appUrl is app-url/local-app-only; a terminal-product subject drives public surfaces instead of a
+    // single loopback app, so reject appUrl on it.
     if (source === "terminal-product" && raw.appUrl !== undefined) {
-        return invalid("`subject.appUrl` does not apply to terminal-product subjects — declare `subject.product.publicSurfaces` (the agent works from public surfaces, not one loopback app).");
+        return invalid("`subject.appUrl` does not apply to a terminal-product subject: its agent works from the product's public pages. List them in `subject.product.publicSurfaces` instead.");
     }
     // serve/env/state are shared between clone (cloned app) and local-tree (packed working
     // 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
+    // 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).");
     }
     // Rejected, never silently dropped, on app-url/local-app/this-repo/terminal-product subjects
-    // too (invariant 6: a field that cannot act on this route is an honest parse error).
+    // too: a field that cannot act on this route is a parse error.
     if (source !== "clone" && raw.repos !== undefined) {
         return invalid("`subject.repos` applies only to clone subjects (the owner/repo slugs to clone).");
     }
     if (source !== "clone" && raw.clone !== undefined) {
         return invalid("`subject.clone` applies only to clone subjects (clone depth/fanout/keep).");
     }
-    // localTree is local-tree-ONLY (pack/upload knobs for the packed working tree).
+    // localTree is local-tree-only (pack/upload knobs for the packed working tree).
     if (source !== "local-tree" && raw.localTree !== undefined) {
         return invalid("`subject.localTree` applies only to local-tree subjects (keep/exclude/maxArchiveBytes for packing the working tree).");
     }
-    // publicTarget is app-url-ONLY (the external-public shared-world ownership attestation). It is
-    // meaningless without a real public deployment as the plane — reject it elsewhere (invariant 6).
+    // publicTarget is app-url-only (the external-public shared-world ownership attestation). It is
+    // meaningless without a real public deployment as the plane, so reject it elsewhere.
     if (source !== "app-url" && raw.publicTarget !== undefined) {
         return invalid("`subject.publicTarget` applies only to app-url subjects on the external-public shared-world route (the operator's ownership attestation for a real public deployment used directly as the shared plane).");
     }
@@ -125,8 +125,8 @@ 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.
+    // serve is required here. Clone subjects get the same requirement from each route's checks in
+    // 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.");
     }
@@ -157,11 +157,11 @@ function parseServedApp(raw, subject) {
     if (raw.env !== undefined) {
         const env = strList(raw.env);
         if (!env || env.length === 0) {
-            return invalid("`subject.env` must be a non-empty list of env var NAMES when set.");
+            return invalid("`subject.env` must be a non-empty list of environment variable names when it is set.");
         }
         const badName = env.find((name) => !ENV_NAME_PATTERN.test(name));
         if (badName) {
-            return invalid(`subject.env entries must be env var NAMES like DATABASE_URL (got "${badName}"); values come from the caller's environment and are never persisted.`);
+            return invalid(`subject.env entries must be environment variable names like DATABASE_URL, and "${badName}" is not one. Their values come from your environment and are never stored.`);
         }
         subject.env = env;
     }
@@ -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) {
@@ -192,11 +192,11 @@ function parseAppSubject(raw, source, subject) {
     }
     // app-url: shape-only here; the loopback-vs-public-target gate is applied in the
     // cross-validation block below, where policies.allowPublicTargets is available.
-    // local-app: an in-process local dev server — ALWAYS loopback (no public-target option),
+    // local-app: an in-process local dev server, always loopback (no public-target option),
     // so the loopback wall is enforced right here at parse.
     if (source === "local-app") {
         if (!isLoopbackUrl(appUrl)) {
-            return invalid("`subject.appUrl` must be a loopback URL (127.0.0.1/localhost) on a local-app subject — it drives an already-running LOCAL dev server in-process; public targets are not supported on this route.");
+            return invalid("`subject.appUrl` must be a loopback URL (127.0.0.1 or localhost) on a local-app subject: humanish drives your running dev server from this process, so it cannot reach a public URL.");
         }
     }
     else if (!isHttpUrl(appUrl)) {
@@ -204,7 +204,7 @@ function parseAppSubject(raw, source, subject) {
     }
     subject.appUrl = appUrl;
     // publicTarget (external-public shared-world ownership attestation) is app-url-only. Shape it
-    // here; its REQUIRED-on-that-route semantics live in externalPublicSharedWorldValidationReason.
+    // here; its required-on-that-route semantics live in externalPublicSharedWorldValidationReason.
     if (source === "app-url" && raw.publicTarget !== undefined) {
         const publicTargetResult = parsePublicTarget(raw.publicTarget);
         if (!publicTargetResult.ok) {
@@ -226,22 +226,22 @@ function parseProductSubject(raw, subject) {
 // "example-operator/lobby-trivia" or a bare org name). Slash allowed for the owner/repo convention.
 export const PUBLIC_TARGET_OWNER_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_./-]*$/;
 /** Parse the external-public shared-world ownership attestation ({ owner, authorized: true }). The
- *  harness cannot verify ownership — this is author-trust, surfaced honestly in the evidence class. */
+ *  harness cannot verify ownership: this is author-trust, and the evidence class says so. */
 function parsePublicTarget(raw) {
     if (!isRecord(raw)) {
-        return invalid("`subject.publicTarget` must be an object ({ owner, authorized: true }) — the operator's ownership attestation for the external-public shared plane.");
+        return invalid("`subject.publicTarget` must be an object, `{ owner, authorized: true }`, declaring that you own or operate the public deployment.");
     }
     const owner = str(raw.owner);
     if (!owner || !PUBLIC_TARGET_OWNER_PATTERN.test(owner)) {
         return invalid("`subject.publicTarget.owner` must be a public-safe operator/repo label (e.g. owner/repo); it is recorded in evidence, so it must carry no secret.");
     }
     if (raw.authorized !== true) {
-        return invalid("`subject.publicTarget.authorized` must be true — you must attest you own/operate the public deployment used as the shared plane (author-trust; the harness cannot verify ownership).");
+        return invalid("`subject.publicTarget.authorized` must be true to declare that you own or operate the public deployment. humanish cannot check ownership, so the study states it.");
     }
     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 load-bearing 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)) {
@@ -263,7 +263,7 @@ function parseProduct(raw) {
         if (upload.startsWith("/") ||
             /^[A-Za-z]:/.test(upload) ||
             upload.split(/[\\/]/).includes("..")) {
-            return invalid("`subject.product.upload` must stay inside the project — no absolute paths and no `..` segments.");
+            return invalid("`subject.product.upload` must stay inside the project: use a relative path with no `..` segments.");
         }
     }
     const install = str(raw.install);
@@ -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.
@@ -330,7 +330,7 @@ function parseServe(raw) {
     }
     const url = str(raw.url);
     if (!url || !isLoopbackUrl(url)) {
-        return invalid("`subject.serve.url` must be a loopback http(s) URL (127.0.0.1 or localhost) — the app is served INSIDE the sandbox.");
+        return invalid("`subject.serve.url` must be a loopback http(s) URL (127.0.0.1 or localhost), because the app runs inside the sandbox.");
     }
     const serve = { start, url };
     const install = str(raw.install);
@@ -368,7 +368,7 @@ function parseClone(raw) {
 /**
  * Structural parse of `subject.localTree`, mirroring parseClone. Unlike parseClone (which
  * silently drops an out-of-range depth/fanout), an invalid exclude/maxArchiveBytes value is
- * REJECTED, never silently dropped: a caller who typed an empty exclude entry or a non-positive
+ * rejected, never silently dropped: a caller who typed an empty exclude entry or a non-positive
  * maxArchiveBytes almost certainly meant something, and the archive-size cap is a safety knob,
  * not a cosmetic default.
  */

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;
@@ -11,6 +11,6 @@ export declare function strList(value: unknown): string[] | undefined;
  */
 export declare function readPositiveInt(value: string | undefined, fallback: number): number;
 export declare function posInt(value: unknown): number | undefined;
-/** A non-negative finite number (0 allowed — caps default to 0 = no-spend). Accepts a numeric
+/** A non-negative finite number (0 allowed; caps default to 0 = no-spend). Accepts a numeric
  *  string too, since YAML scalars can arrive as strings. */
 export declare function nonNegNumber(value: unknown): number | undefined;

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

@@ -1,8 +1,8 @@
-// The slug interpolates into an in-sandbox shell command; the strict shape is load-bearing.
+// The slug interpolates into an in-sandbox shell command, so its shape is strict.
 export const REPO_SLUG_PATTERN = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
 export const ENV_NAME_PATTERN = /^[A-Z][A-Z0-9_]*$/;
 export function invalid(message) {
-    return { ok: false, error: { code: "HUMANISH_LAB_INVALID", message } };
+    return { ok: false, error: { code: "HUMANISH_STUDY_INVALID", message } };
 }
 export function str(value) {
     return typeof value === "string" && value.trim() ? value.trim() : undefined;
@@ -48,7 +48,7 @@ export function posInt(value) {
     }
     return undefined;
 }
-/** A non-negative finite number (0 allowed — caps default to 0 = no-spend). Accepts a numeric
+/** A non-negative finite number (0 allowed; caps default to 0 = no-spend). Accepts a numeric
  *  string too, since YAML scalars can arrive as strings. */
 export function nonNegNumber(value) {
     if (typeof value === "number" && Number.isFinite(value) && value >= 0) {

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

@@ -1,10 +1,10 @@
 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;
 /**
- * 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.
  */
@@ -14,7 +14,7 @@ export declare function resolveCommittedPersona(projectRoot: PreparedSelectedOut
 }>;
 /**
  * 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
+ * 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 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
- * 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 → study}/persona-resolve.js

@@ -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.
  */
@@ -66,7 +66,7 @@ export async function resolveCommittedPersona(projectRoot, personaId) {
 }
 /**
  * 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
+ * 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,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)
@@ -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 → study}/plan-base.d.ts

@@ -1,25 +1,25 @@
 import type { Brain, ComputerUsePlan, NonEmpty, PlannedAnalysis, ProvisionedSubject, Requirement } from "./plan-types.js";
-import type { LabConfig } from "./types.js";
+import type { StudyConfig } from "./types.js";
 export type Base = Omit<ComputerUsePlan, "route" | "actor" | "runner" | "concurrency" | "sessionBudgetMs" | "sandboxMs" | "caps" | "rerun">;
 export declare function isNonEmpty<T>(values: readonly T[]): values is NonEmpty<T>;
-export declare function capsOf(config: LabConfig): ComputerUsePlan["caps"];
-export declare function provisionedSubject(config: LabConfig): ProvisionedSubject | undefined;
+export declare function capsOf(config: StudyConfig): ComputerUsePlan["caps"];
+export declare function provisionedSubject(config: StudyConfig): ProvisionedSubject | undefined;
 /** Keys, env and local tools a live run checks right before it acquires anything. */
-export declare function desktopRequirements(config: LabConfig, args: {
+export declare function desktopRequirements(config: StudyConfig, args: {
     e2b: boolean;
     brain: Brain;
     localVm: boolean;
     externalCatch: boolean;
 }): Requirement[];
-export declare function brainOf(config: LabConfig, callerProvider: boolean): Brain;
+export declare function brainOf(config: StudyConfig, callerProvider: boolean): Brain;
 /** The brain of a run whose provider the library caller supplies. */
-export declare function callerBrainOf(config: LabConfig): Extract<Brain, {
+export declare function callerBrainOf(config: StudyConfig): Extract<Brain, {
     kind: "caller";
 }>;
 /** The model a participant's spend is priced at when its provider reports none. */
 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: {
+export declare function planBase(config: StudyConfig, input: {
     readonly dryRun: boolean;
     readonly analysis?: {
         readonly config?: PlannedAnalysis["config"] | undefined;

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

@@ -110,7 +110,7 @@ export function pricedModel(brain) {
 export function planBase(config, input) {
     const analysis = input.analysis?.config;
     return {
-        labId: config.id,
+        studyId: config.id,
         ...(config.title === undefined ? {} : { title: config.title }),
         residual: residualOf(config),
         dryRun: input.dryRun,

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

@@ -1,8 +1,8 @@
 import type { DwellWindow, StopWhen } from "../actors/stop-conditions.js";
 import type { ReasoningEffort } from "../actors/reasoning-effort.js";
 import { type DevicePreset } from "./device-presets.js";
-import type { LabTask } from "./tasks.js";
-import type { LabConfig } from "./types.js";
+import type { StudyTask } from "./tasks.js";
+import type { StudyConfig } from "./types.js";
 /** Who one participant is. Every route with participants carries this record. */
 export interface Participant {
     /** Declared roster id, else `lane-NN` (independent participants) or `role-NN` (shared-world participants). */
@@ -40,18 +40,18 @@ interface DesktopParticipant extends Participant {
 }
 /** Only independent computer-use participants consume a task protocol and their own target. */
 export interface ComputerUseParticipant extends DesktopParticipant {
-    readonly tasks?: readonly LabTask[];
+    readonly tasks?: readonly StudyTask[];
     /** 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,14 +68,14 @@ export type SharedWorldRoster = {
 /** One shared-world participant on either plane. */
 export type SharedWorldParticipant = ProvisionedParticipant | ExternalPublicParticipant;
 /**
- * The participants of a computer-use lab: the declared roster, else `count` identical ones. A count
+ * The participants of a computer-use study: the declared roster, else `count` identical ones. A count
  * override (`--count`) applies only when no roster is declared.
  */
-export declare function computerUseParticipants(config: LabConfig, countOverride?: number): ComputerUseParticipant[];
-/** The participants of a shared-world lab, one per roster entry, typed by the plane they share. */
-export declare function sharedWorldParticipants(config: LabConfig): SharedWorldRoster;
-/** The ids of the participants a computer-use or shared-world lab runs, in roster order. */
-export declare function declaredParticipantIds(config: LabConfig): string[];
+export declare function computerUseParticipants(config: StudyConfig, countOverride?: number): ComputerUseParticipant[];
+/** The participants of a shared-world study, one per roster entry, typed by the plane they share. */
+export declare function sharedWorldParticipants(config: StudyConfig): SharedWorldRoster;
+/** The ids of the participants a computer-use or shared-world study runs, in roster order. */
+export declare function declaredParticipantIds(config: StudyConfig): string[];
 /** The entry URLs roster entries declare in place of the subject URL (computer use, app-url). */
-export declare function declaredTargets(config: LabConfig): string[];
+export declare function declaredTargets(config: StudyConfig): string[];
 export {};

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

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