humanish 0.107.0 → 0.108.0

package/dist/lab/adapter-extension.d.ts

@@ -39,7 +39,7 @@ type BrowserScoringFacts = Omit<BrowserLabScoringContext, "backend" | "laneCount
 /** The scorer functions a computer-use or shared-world run calls: `RunLabOptions.scorer`. */
 export interface BrowserScorer {
     /**
-     * Browser-route extension seam (#165): a thin adapter may score the assembled
+     * Browser-route extension seam: a thin adapter may score the assembled
      * browser/shared-world evidence without forking core. The score is stored as
      * namespaced `bundle.adapterScore`; product-specific component detail belongs
      * in `data`, not in core enums or review text.
@@ -64,9 +64,9 @@ export interface ScorerOutcome {
     /** Why the scorer failed the run, in order; empty when it did not. */
     failures: string[];
 }
-/** A DECLARED scorer that returned a malformed value never rendered a verdict. */
+/** A declared scorer that returned a malformed value never rendered a verdict. */
 export declare const DECLARED_SCORER_MALFORMED = "Declared product scorer returned a malformed value instead of a verdict; a declared gate that cannot render a pass is recorded as a fail, never a silent pass.";
-/** A DECLARED scorer that threw never rendered a verdict. `detail` is already sanitized. */
+/** A declared scorer that threw never rendered a verdict. `detail` is already sanitized. */
 export declare function declaredScorerThrew(detail: string): string;
 export declare function applyBrowserScorer(args: {
     scorer: BrowserScorer | undefined;
@@ -74,9 +74,9 @@ export declare function applyBrowserScorer(args: {
     bundle: RunBundle;
     sanitize: (text: string) => string;
     warnings: string[];
-    /** Present only when the scorer was CONFIG-DECLARED (#316); core-stamped onto the bundle as
+    /** Present only when the scorer was config-declared; core-stamped onto the bundle as
      *  evidence of which out-of-tree module was loaded. Absent for library callers. Its presence also
-     *  makes a THROWING or MALFORMED scorer a failure — a declared gate that cannot render a pass is
+     *  makes a throwing or malformed scorer a failure: a declared gate that cannot render a pass is
      *  a fail, never a silent green. */
     scorerProvenance?: RunScorerProvenance;
 }): Promise<ScorerOutcome>;
@@ -88,10 +88,10 @@ export declare function applyBrowserScorer(args: {
 export declare function isAdapterFeedbackCandidate(value: unknown): value is RunFeedbackCandidate;
 export declare function adapterScoreFailureMessage(bundle: RunBundle): string | undefined;
 /**
- * Deep-freeze a structured clone so a loaded scorer sees a READ-ONLY bundle: it cannot mutate
+ * Deep-freeze a structured clone so a loaded scorer sees a read-only bundle: it cannot mutate
  * noSpend/cost/review in place to launder a verdict (which would defeat the costProbe-not-loadable
  * guarantee). A tamper attempt throws in the scorer's strict-mode ESM and is caught as a hook failure.
- * Legitimate read-only scoring is unaffected. The seam always stamps the REAL bundle, never this view.
+ * Legitimate read-only scoring is unaffected. The seam always stamps the real bundle, never this view.
  */
 export declare function frozenBundleView(bundle: RunBundle): RunBundle;
 export {};

package/dist/lab/adapter-extension.js

@@ -1,45 +1,22 @@
 import path from "node:path";
 import { isRunAdapterScore } from "../run/bundle-shape.js";
+import { withDeprecatedFields } from "./deprecated-fields.js";
 import { isRunFeedbackCandidate } from "../run/feedback-shape.js";
 import { isRecord } from "../run/type-guards.js";
 const OLDER_BACKEND = {
     "computer-use": "cua",
     "shared-world": "concurrent-shared-world",
 };
-const warnedFields = new Set();
-function warnOlderField(name, replacement) {
-    if (warnedFields.has(name))
-        return;
-    warnedFields.add(name);
-    process.emitWarning(`BrowserLabScoringContext.${name} is deprecated and is removed in the next minor. Use ${replacement}.`, { type: "DeprecationWarning", code: "HUMANISH_SCORING_CONTEXT_FIELD_DEPRECATED" });
-}
-/**
- * The scorer's context: the facts, plus the older `backend` and `laneCount` as getters that warn
- * once when a scorer reads them. They are not enumerable, so a spread, `Object.assign`,
- * `JSON.stringify` or `structuredClone` of the context skips them and warns about no field the
- * code never named. `"backend" in ctx` still finds them. Core never reads them.
- */
+/** The scorer's context: the facts, plus the older `backend` and `laneCount` (deprecated-fields.ts). */
 function scorerContext(facts) {
-    return Object.defineProperties({ ...facts }, {
-        backend: {
-            enumerable: false,
-            get: () => {
-                warnOlderField("backend", "route");
-                return OLDER_BACKEND[facts.route];
-            },
-        },
-        laneCount: {
-            enumerable: false,
-            get: () => {
-                warnOlderField("laneCount", "participantCount");
-                return facts.participantCount;
-            },
-        },
+    return withDeprecatedFields({ ...facts }, { name: "BrowserLabScoringContext", code: "HUMANISH_SCORING_CONTEXT_FIELD_DEPRECATED" }, {
+        backend: { replacement: "route", read: () => OLDER_BACKEND[facts.route] },
+        laneCount: { replacement: "participantCount", read: () => facts.participantCount },
     });
 }
-/** A DECLARED scorer that returned a malformed value never rendered a verdict. */
+/** A declared scorer that returned a malformed value never rendered a verdict. */
 export const DECLARED_SCORER_MALFORMED = "Declared product scorer returned a malformed value instead of a verdict; a declared gate that cannot render a pass is recorded as a fail, never a silent pass.";
-/** A DECLARED scorer that threw never rendered a verdict. `detail` is already sanitized. */
+/** A declared scorer that threw never rendered a verdict. `detail` is already sanitized. */
 export function declaredScorerThrew(detail) {
     return `Declared product scorer threw before returning a verdict (${detail}); a crashed declared gate is recorded as a fail, never a silent pass.`;
 }
@@ -49,13 +26,13 @@ export async function applyBrowserScorer(args) {
         return { failures: [] };
     const declared = scorerProvenance !== undefined;
     // Record the loaded scorer's identity regardless of hook outcome (a throwing/invalid scorer was
-    // still loaded and attempted). A VALID status:"fail" is a failure (library + declared, the
-    // pre-#316 (#165) path); a DECLARED scorer that THROWS or returns MALFORMED is one too (below).
+    // still loaded and attempted). A valid status:"fail" is a failure (library + declared, the
+    // original path); a declared scorer that throws or returns a malformed value is one too (below).
     if (scorerProvenance)
         bundle.scorerProvenance = scorerProvenance;
-    // The scorer sees a READ-ONLY view of the bundle: it cannot mutate noSpend/cost/review in place to
+    // The scorer sees a read-only view of the bundle: it cannot mutate noSpend/cost/review in place to
     // launder a verdict (a tamper attempt throws in the scorer's strict-mode ESM and is caught below as
-    // a hook failure). The seam still stamps the REAL bundle.
+    // a hook failure). The seam still stamps the real bundle.
     const scoringContext = scorerContext({
         ...context,
         bundle: frozenBundleView(context.bundle),
@@ -142,10 +119,10 @@ export function adapterScoreFailureMessage(bundle) {
         : undefined;
 }
 /**
- * Deep-freeze a structured clone so a loaded scorer sees a READ-ONLY bundle: it cannot mutate
+ * Deep-freeze a structured clone so a loaded scorer sees a read-only bundle: it cannot mutate
  * noSpend/cost/review in place to launder a verdict (which would defeat the costProbe-not-loadable
  * guarantee). A tamper attempt throws in the scorer's strict-mode ESM and is caught as a hook failure.
- * Legitimate read-only scoring is unaffected. The seam always stamps the REAL bundle, never this view.
+ * Legitimate read-only scoring is unaffected. The seam always stamps the real bundle, never this view.
  */
 export function frozenBundleView(bundle) {
     const clone = structuredClone(bundle);

package/dist/lab/adapter-scorer-loader.d.ts

@@ -2,14 +2,14 @@ import type { BrowserLabScoringContext } from "./adapter-extension.js";
 import type { TerminalProductScoringContext } from "../routes/terminal/types.js";
 import type { LabRoute } from "./plan.js";
 import type { RunAdapterArtifact, RunAdapterScore, RunFeedbackCandidate, RunScorerProvenance } from "../run/bundle.js";
-/** The read-model context a loaded scorer sees — the terminal or browser scoring context. The module
+/** The read-model context a loaded scorer sees: the terminal or browser scoring context. The module
  *  narrows it at runtime (`"product" in ctx` ⇒ terminal; `"route" in ctx` ⇒ browser). */
 export type AdapterScoringContext = TerminalProductScoringContext | BrowserLabScoringContext;
 /**
- * The adopter-facing scorer module contract (#316). Export any subset of these from a `.mjs` (or a
- * `.js`/`.cjs` whose package.json type matches) — named exports OR a single default object. The
- * loader wires ONLY these three; an exported `executor`/`env`/`provisionSubject`/`costProbe` is never
- * picked up (the whitelist is the scope guard). A module exporting NONE of them is a hard load error.
+ * The adopter-facing scorer module contract. Export any subset of these from a `.mjs` (or a
+ * `.js`/`.cjs` whose package.json type matches): named exports or a single default object. The
+ * loader wires only these three; an exported `executor`/`env`/`provisionSubject`/`costProbe` is never
+ * picked up (the whitelist is the scope guard). A module exporting none of them is a hard load error.
  *
  * `C` is the context `score` and `deriveFeedback` read: `BrowserLabScoringContext` for a scorer
  * written for computer use and shared world, `TerminalProductScoringContext` for one written for
@@ -37,7 +37,7 @@ export declare function terminalScorer(scorer: AdapterScorerModule<TerminalProdu
 export declare function browserRouteScorer(scorer: AdapterScorerModule): AdapterScorerModule<BrowserLabScoringContext>;
 /** The scorer as a terminal run calls it, with the terminal context (see browserRouteScorer). */
 export declare function terminalRouteScorer(scorer: AdapterScorerModule): AdapterScorerModule<TerminalProductScoringContext>;
-type AdapterScorerLoadErrorCode = "HUMANISH_LAB_SCORER_BAD_REF" | "HUMANISH_LAB_SCORER_NOT_FOUND" | "HUMANISH_LAB_SCORER_LOAD_FAILED" | "HUMANISH_LAB_SCORER_NO_HOOKS" | "HUMANISH_LAB_SCORER_UNSUPPORTED_BACKEND";
+type AdapterScorerLoadErrorCode = "HUMANISH_STUDY_SCORER_BAD_REF" | "HUMANISH_STUDY_SCORER_NOT_FOUND" | "HUMANISH_STUDY_SCORER_LOAD_FAILED" | "HUMANISH_STUDY_SCORER_NO_HOOKS" | "HUMANISH_STUDY_SCORER_UNSUPPORTED_BACKEND";
 export type AdapterScorerLoadResult = {
     ok: true;
     hooks: AdapterScorerModule;
@@ -52,7 +52,7 @@ export type AdapterScorerLoadResult = {
 /**
  * Resolve + load a config-declared scorer module. Resolution clones scenario.ref exactly
  * (prepareSelectedOutputDirectory → cwd-clamp → readContainedRegularFile), then `import()`s the
- * entry file in a BROAD try/catch. The digest is over the readContainedRegularFile ENTRY bytes.
+ * entry file in a broad try/catch. The digest is over the readContainedRegularFile entry bytes.
  */
 export declare function loadAdapterScorer(args: {
     cwd: string;

package/dist/lab/adapter-scorer-loader.js

@@ -1,18 +1,18 @@
-// #316 — CLI-loadable adopter scorer. Resolve `review.scorer.ref` / `--scorer` to an out-of-tree
-// scorer module, load it fail-closed (typed error + exit 2, PRE-SPEND), and pick off ONLY the
+// CLI-loadable adopter scorer. Resolve `review.scorer.ref` / `--scorer` to an out-of-tree
+// scorer module, load it fail-closed (typed error + exit 2, before any spend), and pick off only the
 // whitelisted read-model hooks {score, deriveFeedback, deriveArtifacts}. `costProbe` is deliberately
-// NOT loadable — an injected provider cost line overwrites the core-measured one and can forge a
+// not loadable: an injected provider cost line overwrites the core-measured one and can forge a
 // satisfied no-spend proof, so it stays library-only.
 //
-// TRUST MODEL (stated plainly, no overclaims): the party who writes `review.scorer.ref` is the party
-// who runs `humanish lab run` in their own checkout — identical trust to humanish.lab.yml or a
-// package.json script. #316 adds ZERO new execution capability; it relocates WHERE the reference is
-// declared. Containment is ENTRY-FILE-ONLY: `readContainedRegularFile` blocks abs/`..`/symlink/
+// Trust model: the party who writes `review.scorer.ref` is the party
+// who runs `humanish lab run` in their own checkout: identical trust to humanish.lab.yml or a
+// package.json script. The loader adds no new execution capability; it relocates where the reference is
+// declared. Containment is entry-file-only: `readContainedRegularFile` blocks abs/`..`/symlink/
 // hardlink/realpath-escape/TOCTOU on the entry module, but `import()` then executes the transitive
 // graph + npm deps with no clamp, and `import()` runs top-level module code before any whitelist
-// check. The whitelist bounds the WIRED HOOK SURFACE, not arbitrary import-time code; the
+// check. The whitelist bounds the wired hook surface and does not cover import-time code; the
 // trusted-in-process boundary is the actual safety carrier. The seam's output re-scrub is a
-// best-effort denylist, NOT containment. `review.scorer.ref` entries are executable code — review a
+// best-effort denylist that provides no containment. `review.scorer.ref` entries are executable code, so review a
 // PR that adds one as code, not config.
 import { realpath } from "node:fs/promises";
 import path from "node:path";
@@ -43,20 +43,20 @@ export function browserRouteScorer(scorer) {
 export function terminalRouteScorer(scorer) {
     return scorer;
 }
-/** The routes whose hooks bag can carry the loaded scorer. A declared scorer on ANY other route
- *  (scripted or preview) aborts at load — a gate that cannot run must never green-pass. */
+/** The routes that can run the loaded scorer. A declared scorer on any other route
+ *  (scripted or preview) aborts at load: a gate that cannot run must never green-pass. */
 const SCORER_CAPABLE_ROUTES = new Set([
     "terminal",
     "computer-use",
     "shared-world",
 ]);
-/** `.mjs` is required-canonical; `.js`/`.cjs` accepted but the module system is the adopter repo's
- *  package.json `type`. `.ts` is rejected — the compiled `dist/` CLI ships no TypeScript loader. */
+/** `.mjs` is the recommended extension; `.js`/`.cjs` accepted but the module system is the adopter repo's
+ *  package.json `type`. `.ts` is rejected: the compiled `dist/` CLI ships no TypeScript loader. */
 const SCORER_EXTENSIONS = new Set([".mjs", ".js", ".cjs"]);
 /**
  * Resolve + load a config-declared scorer module. Resolution clones scenario.ref exactly
  * (prepareSelectedOutputDirectory → cwd-clamp → readContainedRegularFile), then `import()`s the
- * entry file in a BROAD try/catch. The digest is over the readContainedRegularFile ENTRY bytes.
+ * entry file in a broad try/catch. The digest is over the readContainedRegularFile entry bytes.
  */
 export async function loadAdapterScorer(args) {
     const { route, source } = args;
@@ -64,25 +64,25 @@ export async function loadAdapterScorer(args) {
         ok: false,
         error: { code, message },
     });
-    // A declared gate that cannot run on this route must ABORT (never silently green-pass).
+    // A declared gate that cannot run on this route must abort (never silently green-pass).
     if (!SCORER_CAPABLE_ROUTES.has(route)) {
-        return fail("HUMANISH_LAB_SCORER_UNSUPPORTED_BACKEND", `review.scorer.ref is declared but this lab resolves to the ${route} route, which has no adopter-scorer seam. A declared scorer that cannot run must fail closed rather than pass silently — declare it on a terminal, computer-use or shared-world lab.`);
+        return fail("HUMANISH_STUDY_SCORER_UNSUPPORTED_BACKEND", `review.scorer.ref is set, but this study runs on the ${route} route, which cannot run a scorer. The run stops here so the scorer is not silently skipped. Use it with a terminal, computer-use or shared-world study, or remove review.scorer.ref.`);
     }
     const trimmed = args.ref.trim();
     if (!trimmed) {
-        return fail("HUMANISH_LAB_SCORER_BAD_REF", "review.scorer.ref must be a non-empty repo-relative path ending in .mjs (recommended), .js, or .cjs.");
+        return fail("HUMANISH_STUDY_SCORER_BAD_REF", "review.scorer.ref must be a non-empty repo-relative path ending in .mjs (recommended), .js, or .cjs.");
     }
-    // Provenance is recorded repo-relative — an absolute ref (even one that happens to land inside cwd)
+    // Provenance is recorded repo-relative: an absolute ref (even one that happens to land inside cwd)
     // is rejected up front rather than silently rewritten to its in-tree relative form.
     if (path.isAbsolute(trimmed)) {
-        return fail("HUMANISH_LAB_SCORER_BAD_REF", `review.scorer.ref "${trimmed}" must be a repo-relative path, not absolute — provenance is recorded repo-relative.`);
+        return fail("HUMANISH_STUDY_SCORER_BAD_REF", `review.scorer.ref "${trimmed}" must be a path relative to the project, not an absolute path, because the run records it relative to the project.`);
     }
     const ext = path.extname(trimmed).toLowerCase();
     if (ext === ".ts") {
-        return fail("HUMANISH_LAB_SCORER_BAD_REF", `review.scorer.ref "${trimmed}" ends in .ts, but the shipped CLI runs compiled JS with no TypeScript loader. Precompile to .mjs (recommended) or .js/.cjs.`);
+        return fail("HUMANISH_STUDY_SCORER_BAD_REF", `review.scorer.ref "${trimmed}" ends in .ts, but the shipped CLI runs compiled JS with no TypeScript loader. Precompile to .mjs (recommended) or .js/.cjs.`);
     }
     if (!SCORER_EXTENSIONS.has(ext)) {
-        return fail("HUMANISH_LAB_SCORER_BAD_REF", `review.scorer.ref "${trimmed}" must be a repo-relative PATH ending in .mjs (recommended), .js, or .cjs — an id-style ref is not supported.`);
+        return fail("HUMANISH_STUDY_SCORER_BAD_REF", `review.scorer.ref "${trimmed}" must be a path relative to the project ending in .mjs (recommended), .js or .cjs.`);
     }
     // Root token: realpath(cwd) → prepareSelectedOutputDirectory(dirname, cwd). Mirrors scenario.ref.
     const physicalCwd = await realpath(path.resolve(args.cwd));
@@ -91,18 +91,18 @@ export async function loadAdapterScorer(args) {
     const absolutePath = path.resolve(root.physicalPath, trimmed);
     const relative = path.relative(root.physicalPath, absolutePath);
     if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
-        return fail("HUMANISH_LAB_SCORER_BAD_REF", `review.scorer.ref "${trimmed}" must stay inside the target cwd — provenance is recorded repo-relative and an escaping/absolute path (a cwd parent, node_modules above cwd, an absolute path) cannot be.`);
+        return fail("HUMANISH_STUDY_SCORER_BAD_REF", `review.scorer.ref "${trimmed}" must stay inside the project directory, because the run records it relative to the project; a path into a parent directory cannot be recorded that way.`);
     }
     const relPosix = relative.split(path.sep).join("/");
-    // Fail-closed containment gate on the ENTRY file only: rejects symlink, nlink>1, realpath-escape,
+    // Fail-closed containment gate on the entry file only: rejects symlink, nlink>1, realpath-escape,
     // TOCTOU. Its returned bytes are the digest input.
     const bytes = await readContainedRegularFile(root, relPosix);
     if (!bytes) {
-        return fail("HUMANISH_LAB_SCORER_NOT_FOUND", `review.scorer.ref "${trimmed}" could not be read as a contained regular file (${relPosix}). A scorer must be a regular file inside the target cwd — no symlink, no hardlink, no realpath escape.`);
+        return fail("HUMANISH_STUDY_SCORER_NOT_FOUND", `review.scorer.ref "${trimmed}" could not be read as a regular file inside the project (${relPosix}). Use a plain file there: not a symlink or a hard link, and not a path that resolves outside the project.`);
     }
     const digest = digestText(bytes.toString("utf8"));
-    // Import the entry module in a BROAD try/catch (ERR_MODULE_NOT_FOUND / SyntaxError / ERR_REQUIRE_ESM
-    // / top-level throw). import() executes the transitive graph — the cwd clamp guards only the ENTRY
+    // Import the entry module in a broad try/catch (ERR_MODULE_NOT_FOUND / SyntaxError / ERR_REQUIRE_ESM
+    // / top-level throw). import() executes the transitive graph, and the cwd clamp guards only the entry
     // file; out-of-tree/transitive code is acceptable only because of the trust boundary above.
     let mod;
     try {
@@ -114,12 +114,12 @@ export async function loadAdapterScorer(args) {
         const hint = /ERR_REQUIRE_ESM|import statement outside a module|Cannot use import statement|Unexpected (?:token|identifier)|SyntaxError/i.test(detail)
             ? ' Use a .mjs entry file, or set "type": "module" in the nearest package.json.'
             : "";
-        return fail("HUMANISH_LAB_SCORER_LOAD_FAILED", `review.scorer.ref "${trimmed}" failed to load: ${redactText(detail)}.${hint}`);
+        return fail("HUMANISH_STUDY_SCORER_LOAD_FAILED", `review.scorer.ref "${trimmed}" failed to load: ${redactText(detail)}.${hint}`);
     }
-    // mod.default ?? mod, then pick off ONLY the whitelist. An exported executor/env/costProbe is never
-    // wired — the whitelist is the scope guard. `exports` records the hooks ACTUALLY WIRED for this
+    // mod.default ?? mod, then pick off only the whitelist. An exported executor/env/costProbe is never
+    // wired; the whitelist is the scope guard. `exports` records the hooks actually wired for this
     // backend: deriveArtifacts is browser-only, so on the terminal route it is neither wired nor
-    // recorded (a scorer that exported ONLY deriveArtifacts there wires nothing and fails closed below,
+    // recorded (a scorer that exported only deriveArtifacts there wires nothing and fails closed below,
     // never a silent no-op).
     const picked = (mod.default ?? mod);
     const terminalRoute = route === "terminal";
@@ -139,9 +139,9 @@ export async function loadAdapterScorer(args) {
     }
     if (exports.length === 0) {
         const artifactsOnly = terminalRoute && typeof picked.deriveArtifacts === "function";
-        return fail("HUMANISH_LAB_SCORER_NO_HOOKS", artifactsOnly
+        return fail("HUMANISH_STUDY_SCORER_NO_HOOKS", artifactsOnly
             ? `review.scorer.ref "${trimmed}" exported only deriveArtifacts, which is browser-only and inert on the terminal route. Export score and/or deriveFeedback for a terminal-product scorer.`
-            : `review.scorer.ref "${trimmed}" loaded but exported none of the adopter-scorer hooks (score, deriveFeedback, deriveArtifacts). Export at least one (named, or on a single default object). costProbe is intentionally NOT loadable.`);
+            : `review.scorer.ref "${trimmed}" loaded but exports none of score, deriveFeedback or deriveArtifacts. Export at least one, as a named export or on a default object. costProbe cannot be loaded from a scorer file.`);
     }
     const provenance = {
         schema: "humanish.scorer-provenance.v1",

package/dist/lab/composition-rules.js

@@ -8,8 +8,8 @@
 import { isLoopbackUrl } from "./parse/subject.js";
 import { REPO_SLUG_PATTERN } from "./parse/values.js";
 import { declaredTargets } from "./plan-participants.js";
-import { actorResolvesToComputerUse, actorResolvesToScriptedBrowser, actorResolvesToTerminal, cuaLaneCount, registeredComputerUseActors, registeredScriptedBrowserActors, registeredTerminalActors, isComputerUseComposition, } from "./routing.js";
-import { cloneTargetValidationReason, cuaLaneValidationReason, sharedWorldValidationReason, } from "./validation.js";
+import { actorResolvesToComputerUse, actorResolvesToScriptedBrowser, actorResolvesToTerminal, computerUseParticipantCount, registeredComputerUseActors, registeredScriptedBrowserActors, registeredTerminalActors, isComputerUseComposition, } from "./routing.js";
+import { cloneTargetValidationReason, computerUseValidationReason, sharedWorldValidationReason, } from "./validation.js";
 import { rosterOf } from "./parse/actors.js";
 /** The first composition rule a config breaks, in the parser's order, or null. */
 export function compositionReason(config) {
@@ -22,7 +22,7 @@ export function compositionReason(config) {
         cloneComputerUseValidationReason(config) ??
         localTreeValidationReason(config) ??
         // Independent computer-use participants: the roster contract on every route that resolves to cua.
-        (isComputerUseComposition(config) ? cuaLaneValidationReason(config) : null) ??
+        (isComputerUseComposition(config) ? computerUseValidationReason(config) : null) ??
         // Whenever shared world is declared, not only when it routes, so a half-declared shared world
         // fails with a precise reason instead of running as independent participants.
         (config.subject.topology === "shared-world" ? sharedWorldValidationReason(config) : null) ??
@@ -32,7 +32,7 @@ export function compositionReason(config) {
 }
 /** Why a this-repo lab cannot run live. The parser and the preview planner both refuse with it. */
 export const THIS_REPO_DRY_RUN_ONLY = "this-repo labs are dry-run only; use a clone or app-url subject for a live run.";
-// this-repo subjects run locally and dry-run only — there is no live execution target for the
+// this-repo subjects run locally and dry-run only: there is no live execution target for the
 // host repo (clone/app-url provide that). Reject the mis-configs rather than silently mishandle.
 function thisRepoValidationReason(config) {
     if (config.subject.source === "this-repo") {
@@ -51,51 +51,51 @@ function thisRepoValidationReason(config) {
 // desktop), and no public-target policy (it is always loopback; the loopback shape was already
 // enforced in parseSubject). The actual "no inProcess executor supplied" case is inherently an
 // engine-time decision (the parser cannot know whether a library caller will pass one), so
-// it fails closed in runCuaActorLab with HUMANISH_CUA_LAB_LOCAL_APP_NO_EXECUTOR.
+// it fails closed in runCuaActorLab with HUMANISH_COMPUTER_USE_LOCAL_APP_NO_EXECUTOR.
 function localAppValidationReason(config) {
     if (config.subject.source === "local-app") {
         const type = config.actors[0]?.type ?? "";
         if (config.execution?.target !== undefined && config.execution.target !== "local") {
-            return "local-app subjects drive an in-process LOCAL dev server with NO E2B desktop — set `execution.target: local` or omit it (absent means local); `e2b-desktop` is rejected (use an app-url subject for the hosted-desktop route).";
+            return "A local-app subject drives a local dev server in this process, with no E2B desktop. Set `execution.target: local` or omit it. To run on a hosted desktop, use an app-url subject with `execution.target: e2b-desktop`.";
         }
         if (!actorResolvesToComputerUse(type)) {
             return `actors[0].type must be a registered computer-use actor for local-app subjects (one of: ${registeredComputerUseActors().join(", ")}); the caller's custom executor runs the computer-use loop. Got "${type}".`;
         }
-        if (cuaLaneCount(config) > 1) {
+        if (computerUseParticipantCount(config) > 1) {
             return "Fan-out to more than one participant is not supported on the in-process/local-app route: fan-out provisions one independent E2B desktop per participant, which the in-process route deliberately skips. Set actors[0].count to 1 and drop actors[0].lanes (use an app-url or clone subject on execution.target: e2b-desktop for fan-out).";
         }
         if (rosterOf(config.actors[0]) !== undefined) {
             return "`actors[0].lanes` (fan-out roster) is not supported on the in-process/local-app route: it provisions one E2B desktop per participant, which this route skips. Use an app-url or clone subject with execution.target: e2b-desktop.";
         }
         if (config.policies?.allowPublicTargets === true) {
-            return "`policies.allowPublicTargets` is not supported on the local-app route — a local-app subject is always a loopback dev server; there is no public target to allow.";
+            return "`policies.allowPublicTargets` does not apply to a local-app subject: it is always a loopback dev server, so there is no public target to allow. Remove the setting.";
         }
     }
     return null;
 }
-// app-url routes: the actor type is a real dispatch key (registry-resolved). The actor lane
+// app-url routes: the actor type is a real dispatch key (registry-resolved). The actor's run kind
 // picks the substrate: a scripted-browser actor runs locally against the declared loopback
 // app; a computer-use actor drives a hosted desktop browser. Fail closed on mis-configs.
 function appUrlValidationReason(config) {
     if (config.subject.source === "app-url") {
         const type = config.actors[0]?.type ?? "";
         if (actorResolvesToScriptedBrowser(type)) {
-            // Scripted-browser route (all fail-closed: invariant 6 — a field that cannot act on
+            // Scripted-browser route (all fail-closed, so claims match mechanism: a field that cannot act on
             // this route is rejected, never silently ignored).
             if (config.execution?.target !== undefined && config.execution.target !== "local") {
-                return "scripted-browser actors run on the operator's machine — set `execution.target: local` or omit it (absent means local); in-sandbox scripted execution is a later slice.";
+                return "A scripted-browser actor on an app-url subject runs on this machine. Set `execution.target: local` or omit it. To run scripted steps on a hosted desktop, use a clone subject.";
             }
             if (!config.scenario?.ref) {
-                return "scripted-browser labs require `scenario.ref` — the committed scenario's browser steps are what this actor executes.";
+                return "A scripted-browser study needs `scenario.ref`: the actor runs the browser steps in that scenario file.";
             }
             if ((config.actors[0]?.count ?? 1) > 2) {
-                return "scripted-browser labs support actors[0].count of 1 (desktop surface) or 2 (desktop + mobile); larger fan-out is a later slice.";
+                return "A scripted-browser study takes `actors[0].count` 1 (desktop) or 2 (desktop and mobile). Higher counts are not supported yet.";
             }
             if (config.policies?.redactScreenshots === true) {
-                return "`policies.redactScreenshots: true` is not implemented on the scripted-browser route yet — screenshots persist raw in gitignored .humanish; a silently ignored redaction policy would be a safety lie, so it is rejected.";
+                return "`policies.redactScreenshots: true` is not supported on the scripted-browser route yet, so its screenshots would be stored unredacted in .humanish/. Remove the setting, or use a computer-use actor, which blurs screenshots as it takes them.";
             }
             if (config.policies?.allowPublicTargets === true) {
-                return "`policies.allowPublicTargets` is not supported on the scripted-browser route — the scripted step driver enforces loopback at every navigation; public targets on this route are a later slice.";
+                return "`policies.allowPublicTargets` is not supported on the scripted-browser route: the step driver allows only loopback URLs at every navigation. Remove the setting, or drive the public URL with a computer-use actor.";
             }
             if (!isLoopbackUrl(config.subject.appUrl ?? "")) {
                 return "`subject.appUrl` must be a loopback URL (127.0.0.1/localhost) on the scripted-browser route.";
@@ -116,7 +116,7 @@ function appUrlValidationReason(config) {
             const targets = [config.subject.appUrl ?? "", ...declaredTargets(config)];
             const unsafeTarget = targets.find((target) => !config.policies?.allowPublicTargets && !isLoopbackUrl(target));
             if (unsafeTarget !== undefined) {
-                return "`subject.appUrl` and `actors[0].lanes[].target` must be loopback URLs (127.0.0.1/localhost) unless `policies.allowPublicTargets: true` is set — set it to drive deployed/preview URLs you own.";
+                return "`subject.appUrl` and `actors[0].lanes[].target` must be loopback URLs (127.0.0.1 or localhost). To drive a deployed or preview URL you own, set `policies.allowPublicTargets: true`.";
             }
         }
     }
@@ -130,10 +130,10 @@ function scriptedBrowserValidationReason(config) {
             return "scripted-browser actors require `subject.source: app-url` (a running app at a loopback URL) or `subject.source: clone` with `execution.target: e2b-desktop` (a provisioned synthetic subject).";
         }
         if (config.execution?.target !== "e2b-desktop") {
-            return "clone subjects with scripted-browser actors require `execution.target: e2b-desktop` — the lab provisions the clone in E2B, exposes it with getHost, then drives deterministic browser steps.";
+            return "A clone subject with a scripted-browser actor needs `execution.target: e2b-desktop`: humanish builds the clone in an E2B sandbox, opens it at a public sandbox URL and runs the scenario's browser steps against it.";
         }
         if (!config.subject.serve) {
-            return "clone subjects with scripted-browser actors require `subject.serve` (start + url) — the lab serves the app in-sandbox before the scripted browser drives it.";
+            return "A clone subject with a scripted-browser actor needs `subject.serve` (start and url): humanish starts the app in the sandbox before the browser steps run.";
         }
         if ((config.subject.repos?.length ?? 0) !== 1) {
             return "clone scripted-browser labs require exactly one repo in subject.repos.";
@@ -143,41 +143,41 @@ function scriptedBrowserValidationReason(config) {
             return `subject.repos[0] must be an owner/repo slug (got "${repo}").`;
         }
         if (config.subject.topology !== undefined) {
-            return "clone scripted-browser labs do not support `subject.topology` yet — this slice provisions one synthetic subject and one deterministic scripted actor roster, not a shared-world run.";
+            return "A clone scripted-browser study does not support `subject.topology` yet: it runs one synthetic subject for its scripted actor. Remove `subject.topology`.";
         }
         if (config.subject.clone?.fanout !== undefined || config.subject.clone?.keep === true) {
-            return "clone scripted-browser labs do not support `subject.clone.fanout` or `subject.clone.keep` yet — the provisioned subject is always a single disposable E2B sandbox.";
+            return "A clone scripted-browser study does not support `subject.clone.fanout` or `subject.clone.keep` yet: its subject is always one sandbox, removed after the run.";
         }
         if (!config.scenario?.ref) {
-            return "scripted-browser labs require `scenario.ref` — the committed scenario's browser steps are what this actor executes.";
+            return "A scripted-browser study needs `scenario.ref`: the actor runs the browser steps in that scenario file.";
         }
         if ((config.actors[0]?.count ?? 1) > 2) {
-            return "scripted-browser labs support actors[0].count of 1 (desktop surface) or 2 (desktop + mobile); larger fan-out is a later slice.";
+            return "A scripted-browser study takes `actors[0].count` 1 (desktop) or 2 (desktop and mobile). Higher counts are not supported yet.";
         }
         if (rosterOf(config.actors[0]) !== undefined) {
-            return "`actors[0].lanes` is not supported on the scripted-browser route yet — use actors[0].count for the deterministic surface roster.";
+            return "`actors[0].lanes` is not supported on the scripted-browser route yet. Use `actors[0].count` to choose the desktop and mobile surfaces.";
         }
         if (config.policies?.redactScreenshots === true) {
-            return "`policies.redactScreenshots: true` is not implemented on the scripted-browser route yet — screenshots persist raw in gitignored .humanish; a silently ignored redaction policy would be a safety lie, so it is rejected.";
+            return "`policies.redactScreenshots: true` is not supported on the scripted-browser route yet, so its screenshots would be stored unredacted in .humanish/. Remove the setting, or use a computer-use actor, which blurs screenshots as it takes them.";
         }
         if (config.policies?.allowPublicTargets === true) {
-            return "`policies.allowPublicTargets` is not supported on the clone scripted-browser route — the only external host is the harness-minted getHost URL for a provisioned synthetic subject.";
+            return "`policies.allowPublicTargets` does not apply to a clone scripted-browser study: its only public URL is the sandbox URL humanish opens for its synthetic subject. Remove the setting.";
         }
         if (config.subject.exposure !== "synthetic") {
-            return "clone scripted-browser labs require `subject.exposure: synthetic` — the subject is exposed on an internet-reachable getHost URL for the run, so the author must attest it is synthetic seeded data.";
+            return "A clone scripted-browser study needs `subject.exposure: synthetic`. The subject is reachable from the internet at a public sandbox URL during the run, so the study must declare that its data is synthetic.";
         }
         if (!config.subject.state?.seed ||
             config.subject.state.seed.length === 0 ||
             (config.subject.state.external?.length ?? 0) > 0) {
-            return "clone scripted-browser labs require `subject.state.seed` and do not allow `subject.state.external` — getHost-exposed subjects must be synthetic seeded data, not external/unpinned state.";
+            return "A clone scripted-browser study needs `subject.state.seed` and cannot use `subject.state.external`: a subject at a public sandbox URL may hold only seeded synthetic data.";
         }
         if (!config.subject.serve.start.includes("0.0.0.0")) {
-            return "clone scripted-browser labs require `subject.serve.start` to bind all interfaces (e.g. `-H 0.0.0.0` / `--host 0.0.0.0` / `HOST=0.0.0.0`) — getHost only routes to a 0.0.0.0-bound port; the readiness probe stays loopback.";
+            return "A clone scripted-browser study needs `subject.serve.start` to listen on all interfaces (for example `-H 0.0.0.0`, `--host 0.0.0.0` or `HOST=0.0.0.0`): the public sandbox URL reaches only a port bound to 0.0.0.0. The readiness probe still uses loopback.";
         }
     }
     return null;
 }
-// clone × e2b-desktop disambiguates on the actor lane: a computer-use actor means the lab
+// clone × e2b-desktop disambiguates on the actor's run kind: a computer-use actor means the study
 // clones and serves the subject in-sandbox, then drives it. Scripted-browser actors were checked
 // above.
 function cloneComputerUseValidationReason(config) {
@@ -185,7 +185,7 @@ function cloneComputerUseValidationReason(config) {
         config.execution?.target === "e2b-desktop" &&
         actorResolvesToComputerUse(config.actors[0]?.type)) {
         if (!config.subject.serve) {
-            return "clone subjects on the computer-use route require `subject.serve` (start + url) — the lab serves the app in-sandbox before the actor drives it.";
+            return "A clone subject on the computer-use route needs `subject.serve` (start and url): humanish starts the app in the sandbox before the participant opens it.";
         }
         if ((config.subject.repos?.length ?? 0) !== 1) {
             return "computer-use clone labs serve one repo; declare exactly one repo in subject.repos.";
@@ -216,18 +216,18 @@ function localTreeValidationReason(config) {
     }
     return null;
 }
-// desktop-cli route: a computer-use participant studies a CLI/TUI the way a person does — at a
+// desktop-cli route: a computer-use participant studies a CLI/TUI the way a person does: at a
 // desktop, in a terminal window, by looking at it. The sibling of terminal-product, and the
 // distinction is the population: terminal-product sends an autonomous agent
-// through a pipe with stdin disabled, which is the honest way to study what an agent meets and
+// through a pipe with stdin disabled, which matches what an agent meets and
 // structurally cannot study an interactive surface. This route sends someone who can see it.
 //
-// Fail-closed on the pairing (invariant 6): a hosted desktop and a computer-use actor, because
+// Fail-closed on the pairing: a hosted desktop and a computer-use actor, because
 // "watch a person use a terminal" is not something the other substrates can do.
 /** A desktop-cli subject with no product to study. The computer-use planner checks this too. */
 export function desktopCliProductReason(config) {
     return config.subject.source === "desktop-cli" && config.subject.product?.name === undefined
-        ? "desktop-cli subjects need `subject.product.name` — the CLI the participant is being asked to use."
+        ? "A desktop-cli subject needs `subject.product.name`: the CLI the participant is asked to use."
         : null;
 }
 function desktopCliValidationReason(config) {
@@ -236,7 +236,7 @@ function desktopCliValidationReason(config) {
         return productReason;
     if (config.subject.source === "desktop-cli" && config.subject.product !== undefined) {
         if (config.execution?.target !== undefined && config.execution.target !== "e2b-desktop") {
-            return "desktop-cli subjects are studied at a hosted desktop — set `execution.target: e2b-desktop` or omit it.";
+            return "A desktop-cli subject runs on a hosted desktop. Set `execution.target: e2b-desktop` or omit it.";
         }
         if (!actorResolvesToComputerUse(config.actors[0]?.type ?? "")) {
             return "desktop-cli subjects need a registered computer-use actor: the participant reads the screen and types, which is what makes an interactive surface studiable at all.";
@@ -248,16 +248,16 @@ function desktopCliValidationReason(config) {
     }
     return null;
 }
-// terminal-product route: a real autonomous agent studies a CLI/product from public surfaces
-// inside an E2B shell. Fail-closed (invariant 6 — a field that cannot act on this route is an
-// honest parse error): a registered terminal actor only, execution.target e2b-terminal or absent
-// (absent defaults to e2b-terminal — the only honest target for an in-sandbox agent), one
-// participant until fan-out lands.
+// terminal-product route: a real autonomous agent studies a CLI/product from public surfaces inside
+// an E2B shell. Fail-closed (claims match mechanism: a field that cannot act on this route is a
+// parse error): a registered terminal actor only, execution.target e2b-terminal or absent (absent
+// defaults to e2b-terminal, the only target where an in-sandbox agent runs), one participant until
+// fan-out lands.
 function terminalValidationReason(config) {
     if (config.subject.source === "terminal-product") {
         const type = config.actors[0]?.type ?? "";
         if (config.execution?.target !== undefined && config.execution.target !== "e2b-terminal") {
-            return "terminal-product subjects run the agent inside an E2B shell — set `execution.target: e2b-terminal` or omit it (absent means e2b-terminal); `local`/`e2b-desktop` are rejected.";
+            return "A terminal-product subject runs its agent in an E2B shell. Set `execution.target: e2b-terminal` or omit it; `local` and `e2b-desktop` are not supported.";
         }
         if (!actorResolvesToTerminal(type)) {
             return `actors[0].type must be a registered terminal actor for terminal-product subjects (one of: ${registeredTerminalActors().join(", ")}). Got "${type}".`;
@@ -268,7 +268,7 @@ function terminalValidationReason(config) {
     }
     else if (config.execution?.target === "e2b-terminal") {
         // e2b-terminal is the terminal-product substrate only. Any other source declaring it is a
-        // mis-config — reject, never silently mishandle (mirrors app-url's e2b-desktop pairing rule).
+        // mis-config: reject, never silently mishandle (mirrors app-url's e2b-desktop pairing rule).
         return "`execution.target: e2b-terminal` requires `subject.source: terminal-product` with a registered terminal actor.";
     }
     else if (actorResolvesToTerminal(config.actors[0]?.type)) {