humanish 0.106.0 → 0.107.0

package/dist/lab/adapter-extension.js

@@ -1,14 +1,51 @@
 import path from "node:path";
-import { isFeedbackIdempotencyKey } from "../run/feedback-shape.js";
+import { isRunAdapterScore } from "../run/bundle-shape.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.
+ */
+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;
+            },
+        },
+    });
+}
 /** 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. */
 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.`;
 }
-export async function applyBrowserAdapterHooks(args) {
-    const { hooks, context, bundle, sanitize, warnings, hookLabel, scorerProvenance } = args;
-    if (!hooks?.score && !hooks?.deriveFeedback && !hooks?.deriveArtifacts)
+export async function applyBrowserScorer(args) {
+    const { scorer, context, bundle, sanitize, warnings, scorerProvenance } = args;
+    if (!scorer?.score && !scorer?.deriveFeedback && !scorer?.deriveArtifacts)
         return { failures: [] };
     const declared = scorerProvenance !== undefined;
     // Record the loaded scorer's identity regardless of hook outcome (a throwing/invalid scorer was
@@ -19,78 +56,86 @@ export async function applyBrowserAdapterHooks(args) {
     // 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.
-    const scoringContext = {
+    const scoringContext = scorerContext({
         ...context,
         bundle: frozenBundleView(context.bundle),
-    };
+    });
     const scrubValue = (value) => {
         const encoded = JSON.stringify(value);
         return encoded === undefined ? value : JSON.parse(sanitize(encoded));
     };
     const failures = [];
-    if (hooks.score) {
+    if (scorer?.score) {
         try {
-            const score = await hooks.score(scoringContext);
+            const score = await scorer.score(scoringContext);
             const cleaned = scrubValue(score);
-            if (isAdapterScoreShape(cleaned)) {
+            if (isRunAdapterScore(cleaned)) {
                 bundle.adapterScore = cleaned;
                 const message = adapterScoreFailureMessage(bundle);
                 if (message !== undefined)
                     failures.push(message);
             }
             else {
-                warnings.push(`${hookLabel}.score returned a value that is not a well-formed humanish.adapter-score.v1 (non-empty namespace + status + numeric score + summary); dropped so the bundle stays verifiable.`);
+                warnings.push(`scorer.score returned a value that is not a well-formed humanish.adapter-score.v1 (non-empty namespace + status + numeric score + summary); dropped so the bundle stays verifiable.`);
                 if (declared)
                     failures.push(DECLARED_SCORER_MALFORMED);
             }
         }
         catch (error) {
             const detail = sanitize(error instanceof Error ? error.message : String(error));
-            warnings.push(`${hookLabel}.score threw (${detail}); dropped so the bundle stays verifiable.`);
+            warnings.push(`scorer.score threw (${detail}); dropped so the bundle stays verifiable.`);
             if (declared)
                 failures.push(declaredScorerThrew(detail));
         }
     }
-    if (hooks.deriveFeedback) {
+    if (scorer?.deriveFeedback) {
         try {
-            const candidates = await hooks.deriveFeedback(scoringContext);
+            const candidates = await scorer.deriveFeedback(scoringContext);
             const accepted = [];
             for (const candidate of Array.isArray(candidates) ? candidates : []) {
                 const cleaned = scrubValue(candidate);
-                if (isAdapterFeedbackCandidateShape(cleaned))
+                if (isAdapterFeedbackCandidate(cleaned))
                     accepted.push(cleaned);
                 else
-                    warnings.push(`${hookLabel}.deriveFeedback returned a candidate that is not a well-formed humanish.feedback-candidate.v1 (or its adapter block lacked a non-empty namespace + data record); dropped so the bundle stays verifiable.`);
+                    warnings.push(`scorer.deriveFeedback returned a candidate that is not a well-formed humanish.feedback-candidate.v1 (or its adapter block lacked a non-empty namespace + data record); dropped so the bundle stays verifiable.`);
             }
             if (accepted.length > 0) {
                 bundle.feedbackCandidates = [...bundle.feedbackCandidates, ...accepted];
             }
         }
         catch (error) {
-            warnings.push(`${hookLabel}.deriveFeedback threw (${sanitize(error instanceof Error ? error.message : String(error))}); dropped so the bundle stays verifiable.`);
+            warnings.push(`scorer.deriveFeedback threw (${sanitize(error instanceof Error ? error.message : String(error))}); dropped so the bundle stays verifiable.`);
         }
     }
-    if (hooks.deriveArtifacts) {
+    if (scorer?.deriveArtifacts) {
         try {
-            const artifacts = await hooks.deriveArtifacts(scoringContext);
+            const artifacts = await scorer.deriveArtifacts(scoringContext);
             const accepted = [];
             for (const artifact of Array.isArray(artifacts) ? artifacts : []) {
                 const cleaned = scrubValue(artifact);
                 if (isAdapterArtifactShape(cleaned))
                     accepted.push(cleaned);
                 else
-                    warnings.push(`${hookLabel}.deriveArtifacts returned an artifact that is not a well-formed humanish.adapter-artifact.v1 (non-empty namespace + label + local path + supported kind); dropped so the bundle stays verifiable.`);
+                    warnings.push(`scorer.deriveArtifacts returned an artifact that is not a well-formed humanish.adapter-artifact.v1 (non-empty namespace + label + local path + supported kind); dropped so the bundle stays verifiable.`);
             }
             if (accepted.length > 0) {
                 bundle.adapterArtifacts = [...(bundle.adapterArtifacts ?? []), ...accepted];
             }
         }
         catch (error) {
-            warnings.push(`${hookLabel}.deriveArtifacts threw (${sanitize(error instanceof Error ? error.message : String(error))}); dropped so the bundle stays verifiable.`);
+            warnings.push(`scorer.deriveArtifacts threw (${sanitize(error instanceof Error ? error.message : String(error))}); dropped so the bundle stays verifiable.`);
         }
     }
     return { failures };
 }
+/**
+ * A feedback candidate a scorer returned, accepted at the seam: the bundle's candidate shape with a
+ * non-empty summary. The browser and terminal seams both use it, so a candidate either seam drops
+ * never reaches a bundle.
+ */
+export function isAdapterFeedbackCandidate(value) {
+    return isRunFeedbackCandidate(value) && value.summary.trim().length > 0;
+}
 export function adapterScoreFailureMessage(bundle) {
     return bundle.adapterScore?.status === "fail"
         ? `Adapter scorer failed the run: ${bundle.adapterScore.summary}`
@@ -115,62 +160,6 @@ export function frozenBundleView(bundle) {
     freeze(clone);
     return clone;
 }
-function isAdapterScoreShape(value) {
-    return (typeof value === "object" &&
-        value !== null &&
-        !Array.isArray(value) &&
-        value.schema === "humanish.adapter-score.v1" &&
-        typeof value.namespace === "string" &&
-        value.namespace.trim().length > 0 &&
-        ["pass", "partial", "fail"].includes(value.status) &&
-        typeof value.score === "number" &&
-        Number.isFinite(value.score) &&
-        typeof value.summary === "string" &&
-        (value.data === undefined ||
-            (typeof value.data === "object" &&
-                value.data !== null &&
-                !Array.isArray(value.data))));
-}
-function isAdapterFeedbackCandidateShape(value) {
-    if (!isRecord(value))
-        return false;
-    const candidate = value;
-    if (candidate.schema !== "humanish.feedback-candidate.v1" ||
-        typeof candidate.id !== "string" ||
-        typeof candidate.run_id !== "string" ||
-        (candidate.stream_id !== undefined && typeof candidate.stream_id !== "string") ||
-        typeof candidate.adapter_id !== "string" ||
-        typeof candidate.scenario_id !== "string" ||
-        typeof candidate.persona_id !== "string" ||
-        !isFeedbackActor(candidate.actor) ||
-        !isFeedbackSubstrate(candidate.substrate) ||
-        !isFeedbackFailureOwner(candidate.failure_owner) ||
-        typeof candidate.summary !== "string" ||
-        candidate.summary.trim().length === 0 ||
-        typeof candidate.expected !== "string" ||
-        typeof candidate.actual !== "string" ||
-        !Array.isArray(candidate.evidence) ||
-        !candidate.evidence.every(isFeedbackEvidence) ||
-        !isRecord(candidate.redaction) ||
-        candidate.redaction.status !== "passed" ||
-        typeof candidate.redaction.notes !== "string" ||
-        !isFeedbackIdempotencyKey(candidate.idempotency_key) ||
-        !isFeedbackNextState(candidate.proposed_next_state) ||
-        !Array.isArray(candidate.acceptance_proof) ||
-        !candidate.acceptance_proof.every((item) => typeof item === "string")) {
-        return false;
-    }
-    if (candidate.adapter !== undefined) {
-        const adapter = candidate.adapter;
-        if (!isRecord(adapter) ||
-            typeof adapter.namespace !== "string" ||
-            adapter.namespace.trim().length === 0 ||
-            !isRecord(adapter.data)) {
-            return false;
-        }
-    }
-    return true;
-}
 function isAdapterArtifactShape(value) {
     if (!isRecord(value))
         return false;
@@ -186,9 +175,6 @@ function isAdapterArtifactShape(value) {
         typeof artifact.note === "string" &&
         artifact.note.trim().length > 0);
 }
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 function isSafeRelativeArtifactPath(value) {
     return (value.trim().length > 0 &&
         !path.isAbsolute(value) &&
@@ -204,50 +190,3 @@ function isAdapterArtifactKind(value) {
         value === "filesystem" ||
         value === "summary");
 }
-function isFeedbackActor(value) {
-    return (value === "codex-tui" ||
-        value === "codex-exec" ||
-        value === "codex-app-server" ||
-        value === "computer-use" ||
-        value === "synthetic-dry-run" ||
-        value === "unknown");
-}
-function isFeedbackSubstrate(value) {
-    return (value === "e2b-desktop" ||
-        value === "local-desktop" ||
-        value === "e2b-terminal" ||
-        value === "local-filesystem" ||
-        value === "codex-app-server" ||
-        value === "unknown");
-}
-function isFeedbackFailureOwner(value) {
-    return (value === "harness" ||
-        value === "target-app" ||
-        value === "actor" ||
-        value === "environment" ||
-        value === "unknown");
-}
-function isFeedbackNextState(value) {
-    return (value === "watch" ||
-        value === "adapter-hardening" ||
-        value === "target-app-setup" ||
-        value === "actor-auth" ||
-        value === "setup-quality-review" ||
-        value === "study-quality-review");
-}
-function isFeedbackEvidence(value) {
-    if (!isRecord(value))
-        return false;
-    return (typeof value.path === "string" &&
-        value.path.length > 0 &&
-        !path.isAbsolute(value.path) &&
-        !value.path.includes("://") &&
-        !value.path.includes("..") &&
-        (value.kind === "review" ||
-            value.kind === "state" ||
-            value.kind === "log" ||
-            value.kind === "trace" ||
-            value.kind === "screenshot" ||
-            value.kind === "filesystem") &&
-        typeof value.note === "string");
-}

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

@@ -3,20 +3,40 @@ 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
- *  narrows it at runtime (`"product" in ctx` ⇒ terminal; `"backend" in ctx` ⇒ browser). */
+ *  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.
+ *
+ * `C` is the context `score` and `deriveFeedback` read: `BrowserLabScoringContext` for a scorer
+ * written for computer use and shared world, `TerminalProductScoringContext` for one written for
+ * terminal runs, or the default union for one that narrows at runtime.
  */
-export interface AdapterScorerModule {
-    score?: (ctx: AdapterScoringContext) => RunAdapterScore | Promise<RunAdapterScore>;
-    deriveFeedback?: (ctx: AdapterScoringContext) => RunFeedbackCandidate[] | Promise<RunFeedbackCandidate[]>;
-    /** Browser-route only; inert on the terminal route (TerminalProductLabHooks carries no artifacts seam). */
+export interface AdapterScorerModule<C extends AdapterScoringContext = AdapterScoringContext> {
+    score?: (ctx: C) => RunAdapterScore | Promise<RunAdapterScore>;
+    deriveFeedback?: (ctx: C) => RunFeedbackCandidate[] | Promise<RunFeedbackCandidate[]>;
+    /** Browser-route only; inert on the terminal route, whose TerminalScorer has no artifacts seam. */
     deriveArtifacts?: (ctx: BrowserLabScoringContext) => RunAdapterArtifact[] | Promise<RunAdapterArtifact[]>;
 }
+/**
+ * A scorer written for computer use and shared world, as `RunLabOptions.scorer` takes it. Those
+ * routes pass the browser context; another route that calls it passes a context it was not written
+ * for. The call states the kind, so the module itself needs no cast.
+ */
+export declare function browserScorer(scorer: AdapterScorerModule<BrowserLabScoringContext>): AdapterScorerModule;
+/** A scorer written for terminal runs, as `RunLabOptions.scorer` takes it (see browserScorer). */
+export declare function terminalScorer(scorer: AdapterScorerModule<TerminalProductScoringContext>): AdapterScorerModule;
+/**
+ * The scorer as a computer-use or shared-world run calls it, with the browser context. The caller
+ * chose the context it wrote the scorer for; only the route knows which context it passes, so the
+ * narrowing is here. A terminal-typed scorer on a browser route reads fields the context lacks.
+ */
+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";
 export type AdapterScorerLoadResult = {
     ok: true;

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

@@ -19,6 +19,30 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { digestText, redactText } from "../evidence/redaction.js";
 import { prepareSelectedOutputDirectory, readContainedRegularFile, } from "../run/contained-output.js";
+/**
+ * A scorer written for computer use and shared world, as `RunLabOptions.scorer` takes it. Those
+ * routes pass the browser context; another route that calls it passes a context it was not written
+ * for. The call states the kind, so the module itself needs no cast.
+ */
+export function browserScorer(scorer) {
+    return scorer;
+}
+/** A scorer written for terminal runs, as `RunLabOptions.scorer` takes it (see browserScorer). */
+export function terminalScorer(scorer) {
+    return scorer;
+}
+/**
+ * The scorer as a computer-use or shared-world run calls it, with the browser context. The caller
+ * chose the context it wrote the scorer for; only the route knows which context it passes, so the
+ * narrowing is here. A terminal-typed scorer on a browser route reads fields the context lacks.
+ */
+export function browserRouteScorer(scorer) {
+    return scorer;
+}
+/** The scorer as a terminal run calls it, with the terminal context (see browserRouteScorer). */
+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. */
 const SCORER_CAPABLE_ROUTES = new Set([

package/dist/lab/composition-rules.d.ts

@@ -3,3 +3,5 @@ import type { LabConfig } from "./types.js";
 export declare function compositionReason(config: LabConfig): string | null;
 /** Why a this-repo lab cannot run live. The parser and the preview planner both refuse with it. */
 export declare const THIS_REPO_DRY_RUN_ONLY = "this-repo labs are dry-run only; use a clone or app-url subject for a live run.";
+/** A desktop-cli subject with no product to study. The computer-use planner checks this too. */
+export declare function desktopCliProductReason(config: LabConfig): string | null;

package/dist/lab/composition-rules.js

@@ -1,7 +1,10 @@
 // Which subject, target and actor compositions a lab may declare. Each rule returns the refusal
 // message for the first thing its composition gets wrong, or null. compositionReason runs them in
-// the parser's order; parseLabConfig calls it after the structural parse, and the planLab design
-// has library callers go through the same function.
+// the parser's order, and only parseLabConfig calls it. planLab does not: each route planner checks
+// a library caller's config itself, under its route's error codes. The planners call the shared
+// checks in lab/validation.ts and desktopCliProductReason below. The other subject rules here have
+// planner counterparts whose conditions and wording differ (clone serve and repo, local-tree
+// target, in-process fan-out, loopback targets, scripted scenario.ref).
 import { isLoopbackUrl } from "./parse/subject.js";
 import { REPO_SLUG_PATTERN } from "./parse/values.js";
 import { declaredTargets } from "./plan-participants.js";
@@ -18,10 +21,10 @@ export function compositionReason(config) {
         cloneTargetValidationReason(config) ??
         cloneComputerUseValidationReason(config) ??
         localTreeValidationReason(config) ??
-        // Independent computer-use lanes: the roster contract on every route that resolves to cua.
+        // Independent computer-use participants: the roster contract on every route that resolves to cua.
         (isComputerUseComposition(config) ? cuaLaneValidationReason(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 lanes.
+        // fails with a precise reason instead of running as independent participants.
         (config.subject.topology === "shared-world" ? sharedWorldValidationReason(config) : null) ??
         desktopCliValidationReason(config) ??
         terminalValidationReason(config) ??
@@ -42,12 +45,12 @@ function thisRepoValidationReason(config) {
     }
     return null;
 }
-// local-app route: an already-running LOCAL dev server driven IN-PROCESS via a custom
+// local-app route: an already-running local dev server driven in-process via a custom
 // CuaExecutor (no clone, no E2B desktop). Parse-validated fail-closed: a computer-use actor
-// only, execution.target local or absent (NEVER e2b-desktop — the whole point is to skip the
+// only, execution.target local or absent (never e2b-desktop, because the route exists to skip the
 // desktop), and no public-target policy (it is always loopback; the loopback shape was already
-// enforced in parseSubject). The actual "no buildExecutor hook supplied" case is inherently an
-// engine-time decision (the parser cannot know whether a library caller will pass hooks), so
+// 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.
 function localAppValidationReason(config) {
     if (config.subject.source === "local-app") {
@@ -70,7 +73,7 @@ function localAppValidationReason(config) {
     }
     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 lane
 // 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) {
@@ -105,9 +108,9 @@ function appUrlValidationReason(config) {
             if (!actorResolvesToComputerUse(type)) {
                 return `actors[0].type must be a registered computer-use actor for app-url × e2b-desktop labs (one of: ${registeredComputerUseActors().join(", ")}); for local scripted execution use a registered scripted-browser actor (${registeredScriptedBrowserActors().join(", ")}). Got "${type}".`;
             }
-            // Multi-lane fan-out is CONSUMED on this route (per-lane worlds; the shared cua-lane
-            // cross-validation below enforces lanes/count XOR rules, the 16 cap, and the
-            // lane-level target gates, and the allowPublicTargets+N>1 rejection for ambiguous one-target
+            // Multi-participant fan-out is consumed on this route (`per-lane-worlds`; the shared cua
+            // cross-validation below enforces `lanes`/`count` XOR rules, the 16 cap, and the
+            // per-participant target gates, and the allowPublicTargets+N>1 rejection for ambiguous one-target
             // fan-out).
             // Loopback by default; an owner may declare a public/preview target via policies.
             const targets = [config.subject.appUrl ?? "", ...declaredTargets(config)];
@@ -175,7 +178,7 @@ function scriptedBrowserValidationReason(config) {
     return null;
 }
 // clone × e2b-desktop disambiguates on the actor lane: a computer-use actor means the lab
-// clones AND serves the subject in-sandbox, then drives it. Scripted-browser actors were checked
+// clones and serves the subject in-sandbox, then drives it. Scripted-browser actors were checked
 // above.
 function cloneComputerUseValidationReason(config) {
     if (config.subject.source === "clone" &&
@@ -191,15 +194,15 @@ function cloneComputerUseValidationReason(config) {
         if (!REPO_SLUG_PATTERN.test(repo)) {
             return `subject.repos[0] must be an owner/repo slug (got "${repo}").`;
         }
-        // Fan-out is CONSUMED here: N lanes each clone the SAME single repo into their own E2B
-        // desktop (per-lane worlds). The shared cua-lane cross-validation below enforces the
-        // lanes/count rules and the 16 cap; the single-repo rule above is unchanged.
+        // Fan-out is consumed here: N participants each clone the same single repo into their own
+        // E2B desktop (`per-lane-worlds`). The shared cua cross-validation below enforces the
+        // `lanes`/`count` rules and the 16 cap; the single-repo rule above is unchanged.
     }
     return null;
 }
 // local-tree route: packs and uploads the operator's own working tree, then serves it exactly
 // like a computer-use clone subject. The scripted-browser route has no packed-working-tree
-// mode, so e2b-desktop + a computer-use actor are the ONLY combination this source supports.
+// mode, so e2b-desktop + a computer-use actor are the only combination this source supports.
 // `subject.serve` is already required at parse time (parseSubject); the repos/clone rejection
 // also already happened there (local-tree never carries git slugs).
 function localTreeValidationReason(config) {
@@ -215,17 +218,23 @@ function localTreeValidationReason(config) {
 }
 // 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, not the product: terminal-product sends an autonomous agent
+// 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
 // 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
 // "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."
+        : null;
+}
 function desktopCliValidationReason(config) {
-    if (config.subject.source === "desktop-cli") {
-        if (config.subject.product?.name === undefined) {
-            return "desktop-cli subjects need `subject.product.name` — the CLI the participant is being asked to use.";
-        }
+    const productReason = desktopCliProductReason(config);
+    if (productReason)
+        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.";
         }
@@ -239,11 +248,11 @@ function desktopCliValidationReason(config) {
     }
     return null;
 }
-// terminal-product route: a real autonomous agent studies a CLI/product from PUBLIC surfaces
+// 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), single
-// lane until fan-out lands.
+// (absent defaults to e2b-terminal — the only honest target for an in-sandbox agent), one
+// participant until fan-out lands.
 function terminalValidationReason(config) {
     if (config.subject.source === "terminal-product") {
         const type = config.actors[0]?.type ?? "";
@@ -258,7 +267,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
+        // 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).
         return "`execution.target: e2b-terminal` requires `subject.source: terminal-product` with a registered terminal actor.";
     }

package/dist/lab/config.js

@@ -1,59 +1,61 @@
-// humanish.lab.v2 — a lab is a COMPOSITION over code primitives, not a hardcoded kind.
+// humanish.lab.v2: a lab is a composition over code primitives. There is no hardcoded lab kind.
 //
-// HONEST SCOPE (read before trusting field names): the engine routes by
+// Scope (read before trusting field names): the engine routes by
 // subject.source × execution.target (disambiguated by the actor lane where both axes
 // collide) and consumes a deliberately small set of fields:
 //   subject.source/repos/appUrl/serve/env/state/clone.{depth,fanout,keep}, actors[0].count,
 //   execution.target + execution.desktop.codexAppServer, scenario.mode,
 //   policies.redactRepos, defaults.open.
 // On the computer-use routes (app-url × e2b-desktop, and clone × e2b-desktop with a
-// computer-use actor), `actors[0].type` IS load-bearing: it must resolve to a registered
+// computer-use actor), `actors[0].type` is load-bearing: it must resolve to a registered
 // computer-use actor, and that descriptor runs the session. Those routes also consume
 // actors[0].{mission,persona,laneFocus.instruction,model,reasoningEffort}, execution.timeoutMs,
 // execution.desktop.{browser,resolution,sandboxTimeoutMs}, and (clone)
 // subject.{serve,env,state,clone.depth}.
 // On the scripted-browser route (app-url × local-or-absent, or clone × e2b-desktop, with a
 // registered scripted-browser actor), `actors[0].type` is equally load-bearing, and the route
-// consumes scenario.ref (REQUIRED there — the committed scenario's browser steps ARE what the
+// consumes scenario.ref (required there, because the committed scenario's browser steps are what the
 // actor executes), actors[0].{persona,count}, and execution.timeoutMs. On the provisioned
 // clone slice it also consumes subject.{repos,serve,env,state,exposure,clone.depth} and
 // execution.desktop.template. actors[0].{mission,laneFocus,model} are inert on that route
 // because no model runs, and most execution.desktop.* fields remain forward-declared (device
 // presets belong to the cua route — scripted surfaces are the driver's own desktop/mobile
-// viewports where isMobile/DSF genuinely RENDER via playwright emulation).
-// On the other routes those fields remain FORWARD-DECLARED and NOT yet consumed —
+// viewports where isMobile/DSF genuinely render via playwright emulation).
+// On the other routes those fields remain forward-declared and are not yet consumed:
 // parseLabConfig emits a warning listing any such field that is set, so `lab inspect` shows
 // the truth.
 //
 // NOTE on actors[0].count: it now carries ROUTE-SPECIFIC meanings — synthetic route: simCount;
 // scripted-browser route: surface roster {1 = desktop, 2 = desktop + mobile}, default 1 (the
-// defaults-table single-lane row governs; count: 2 is the declared override); computer-use
-// E2B route: the HOMOGENEOUS fan-out lane count (N identical lanes, each its own E2B desktop),
-// capped at 16; the in-process/local-app cua route stays single lane (no E2B to fan out).
+// defaults-table single-participant row governs; count: 2 is the declared override); computer-use
+// E2B route: the homogeneous fan-out participant count (N identical participants, each its own E2B
+// desktop), capped at 16; the in-process/local-app cua route stays single-participant (no E2B to
+// fan out).
 //
 // NOTE on actors[0].lanes / actors[0].roster (computer-use E2B route, this slice): a
-// DIFFERENTIATED fan-out roster — each `{ id?, persona?, device?, instruction?, target? }` becomes one
-// independent E2B desktop (per-lane worlds, the default topology). `roster[]` is parser sugar for
+// differentiated fan-out roster: each `{ id?, persona?, device?, instruction?, target? }` becomes one
+// independent E2B desktop (`per-lane-worlds`, the default topology). `roster[]` is parser sugar for
 // repeated groups and is normalized into `lanes[]` before the engine sees it. `lanes|roster` XOR
-// `count` (declare a differentiated roster OR a homogeneous count, never both); `lanes|roster`
-// XOR `actors[0].laneFocus` (per-lane `instruction` is the roster's steer); `lanes[].device` XOR
-// raw `execution.desktop.resolution`. `execution.concurrency` bounds in-flight lanes (default: the
-// lane count, every lane at once; env HUMANISH_CUA_MAX_CONCURRENCY may only LOWER it — invariant
+// `count` (declare a differentiated roster or a homogeneous count, never both); `lanes|roster`
+// XOR `actors[0].laneFocus` (each entry's `instruction` is the roster's steer); `lanes[].device` XOR
+// raw `execution.desktop.resolution`. `execution.concurrency` bounds in-flight participants (default:
+// the participant count, all at once; env HUMANISH_CUA_MAX_CONCURRENCY may only lower it, per invariant
 // 3). On every non-cua route normalized `lanes` are inert (warned). subject.clone.fanout is
-// REJECTED on the cua route. `lanes[].target` is app-url × computer-use ONLY: an absolute browser
-// URL this lane opens instead of `subject.appUrl`; it is the generic setup-produced-target
+// rejected on the cua route. `lanes[].target` is app-url × computer-use only: an absolute browser
+// URL this participant opens instead of `subject.appUrl`; it is the generic setup-produced-target
 // handoff, not a service topology primitive.
 //
-// There is deliberately NO v1 compatibility: v1 had zero real users. Breaking schema changes
+// There is deliberately no v1 compatibility: v1 had zero real users. Breaking schema changes
 // bump the version honestly.
 import { isLocalBrowserLab, localBrowserDefaults, localBrowserUnsupportedReason, } from "../substrates/local/runtime-config.js";
+import { isRecord } from "../run/type-guards.js";
 import { compositionReason } from "./composition-rules.js";
 import { findUnknownLabKey } from "./keys.js";
 import { parseActors, rosterOf } from "./parse/actors.js";
 import { parseComms, recipientParticipantId } from "./parse/comms.js";
 import { parseDefaults, parseExecution, parsePersonas, parsePolicies, parseReview, parseScenario, } from "./parse/execution.js";
 import { parseSubject } from "./parse/subject.js";
-import { invalid, isRecord, optionalStr, str } from "./parse/values.js";
+import { invalid, optionalStr, str } from "./parse/values.js";
 import { isComputerUseComposition, isSharedWorldComposition } from "./routing.js";
 import { declaredParticipantIds } from "./plan-participants.js";
 import { ID_PATTERN, LAB_CONFIG_SCHEMA, } from "./types.js";
@@ -150,7 +152,7 @@ export function parseLabConfig(raw) {
         return invalid(scenarioCapsReason);
     // All-parallel default (#350): a multi-seat lab that does not declare execution.concurrency runs
     // every seat at once; the declared field is a cap the author chose, never a mode. Independent
-    // computer-use lanes resolve that default from the final seat count when they plan, after any
+    // computer-use participants resolve that default from the final participant count when they plan, after any
     // --count override, so the parser leaves it unset for them. A shared world's roster is fixed, so
     // its default is filled here for the envelopes and warnings that read the parsed config.
     {
@@ -161,12 +163,12 @@ export function parseLabConfig(raw) {
             config.execution = { ...config.execution, concurrency: participantCount };
         }
     }
-    // Email that just works (#351): the funnel's ONLY handoff to an actor is the per-lane inbox
-    // instruction, gated on recipients[]. Guessed lane names broke a field run — recipients copied
-    // from a single-lane example matched nothing, so every actor was left inbox-blind with zero
-    // signal. Omitted recipients are therefore FILLED (one deterministic address per lane); a
-    // recipient naming an unknown lane is a hard error listing the real lane ids; declared
-    // recipients covering zero lanes are a hard error (a guaranteed-dead funnel).
+    // Email that just works (#351): the funnel's only handoff to an actor is the per-participant
+    // inbox instruction, gated on recipients[]. Guessed participant ids broke a field run —
+    // recipients copied from a single-participant example matched nothing, so every actor was left inbox-blind with zero
+    // signal. Omitted recipients are therefore filled (one deterministic address per participant);
+    // a recipient naming an unknown participant is a hard error listing the real ids; declared
+    // recipients covering zero participants are a hard error (a guaranteed-dead funnel).
     const receivingReason = receivingEmailValidationReason(config);
     if (receivingReason)
         return invalid(receivingReason);

package/dist/lab/device-presets.d.ts

@@ -4,9 +4,9 @@ export interface DevicePreset {
     width: number;
     /** Requested device height, used for the hosted physical screen. */
     height: number;
-    /** Mobile identity; enables emulation only when the hosted lane explicitly opts in. */
+    /** Mobile identity; enables emulation only when the hosted participant explicitly opts in. */
     isMobile: boolean;
-    /** Requested DPR; applied on hosted mobile lanes only with opt-in CDP emulation. */
+    /** Requested DPR; applied on hosted mobile participants only with opt-in CDP emulation. */
     deviceScaleFactor: number;
 }
 /**