humanish 0.107.0 → 0.108.0

package/dist/lab/parse/subject-state.js

@@ -5,23 +5,23 @@ 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,9 +30,9 @@ 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;
     }
@@ -41,8 +41,8 @@ export function parseEnvValues(raw) {
 /**
  * Structural parse of `subject.state` into a candidate LabSubjectState. 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 = [
@@ -97,9 +97,9 @@ const STATE_STEP_WHENS = [
 ];
 /**
  * Semantic validation for `subject.state`, shared by parseLabConfig and the engine
- * (runCuaActorLab re-enforces it on configs that arrive through the library API). Returns
+ * (the route re-enforces it on configs that arrive through runLab). 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/parse/subject.js

@@ -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,15 +57,15 @@ 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 +
@@ -79,7 +79,7 @@ function misplacedFieldFailure(source, raw) {
     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).");
     }
-    // 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) {
@@ -89,19 +89,19 @@ function misplacedFieldFailure(source, raw) {
         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,7 +125,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
+    // serve is required here. Clone subjects get the same requirement from each route's checks in
     // parseLabConfig.
     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;
     }
@@ -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 lab 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 lab 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/parse/values.d.ts

@@ -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/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/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.
  */
@@ -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<{
@@ -30,8 +30,8 @@ export declare function labPersonaIds(config: {
 }): 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

@@ -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) {
@@ -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/plan-participants.d.ts

@@ -44,14 +44,14 @@ export interface ComputerUseParticipant extends DesktopParticipant {
     /** 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;

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

@@ -4,7 +4,7 @@ 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";
@@ -62,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;
@@ -194,7 +194,7 @@ export interface SharedWorldPlan extends PlanBase {
     readonly plane: SharedWorldPlane;
     /** At least 2. */
     readonly concurrency: number;
-    /** The declared seat session timeout; the route supplies its default. */
+    /** The declared participant session timeout; the route supplies its default. */
     readonly sessionTimeoutMs?: number;
     readonly brain: Extract<Brain, {
         kind: "openai" | "local-agent";
@@ -282,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

@@ -2,13 +2,7 @@ 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";
-/**
- * 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;
 /**

package/dist/lab/plan.js

@@ -1,6 +1,6 @@
 // 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.
+// execution.target, the first actor's registered run kind, subject.topology), never from a
+// declared kind. This is the only function that decides it.
 import { resolveAutomaticAnalysis } from "../analysis/automatic-config.js";
 import { callerDrivingOf, planComputerUseLab } from "../routes/computer-use/plan.js";
 import { injectedBrowser, planScriptedLab } from "../routes/scripted/plan.js";
@@ -9,40 +9,9 @@ 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";
-/**
- * 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
-    // independent participants.
-    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) {
@@ -66,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 {
@@ -102,7 +71,7 @@ export function planLab(config, options, deps = {}) {
     const result = planRoute(routeOf(config), lab, options, input, deps);
     if (!result.ok)
         return result;
-    // The manifest the CLI resolved (#455) enters the plan here and nowhere else; the routes read
+    // 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 } };