humanish 0.107.0 → 0.108.0

package/dist/lab/preflight-probes.js

@@ -19,7 +19,7 @@ const PREFLIGHT_LEASE_BUFFER_MS = 5 * 60_000;
 export async function runPublicPreviewPreflight(ctx) {
     const routeError = publicPreviewRouteError(ctx.config, ctx.route);
     if (routeError) {
-        return fail(ctx, "HUMANISH_LAB_PREFLIGHT_UNSUPPORTED_ROUTE", routeError, [
+        return fail(ctx, "HUMANISH_STUDY_PREFLIGHT_UNSUPPORTED_ROUTE", routeError, [
             { name: "route", ok: false, message: routeError },
         ]);
     }
@@ -28,12 +28,12 @@ export async function runPublicPreviewPreflight(ctx) {
         ? rosterTargets
         : ctx.targets.filter((target) => target.kind === "subject.appUrl");
     if (publicTargets.length === 0) {
-        return fail(ctx, "HUMANISH_LAB_PREFLIGHT_TARGET_POLICY", "public-preview preflight needs at least one declared app-url target.", [{ name: "targets", ok: false, message: "no app-url targets were declared" }]);
+        return fail(ctx, "HUMANISH_STUDY_PREFLIGHT_TARGET_POLICY", "public-preview preflight needs at least one declared app-url target.", [{ name: "targets", ok: false, message: "no app-url targets were declared" }]);
     }
     const loopbackTarget = publicTargets.find((target) => target.loopback);
     if (loopbackTarget) {
         blockTarget(loopbackTarget, "public-preview requires externally reachable non-loopback targets.");
-        return fail(ctx, "HUMANISH_LAB_PREFLIGHT_TARGET_POLICY", "public-preview reachability cannot prove loopback targets from a hosted desktop; use sandbox-loopback or a prepared public target.", [
+        return fail(ctx, "HUMANISH_STUDY_PREFLIGHT_TARGET_POLICY", "public-preview reachability cannot prove loopback targets from a hosted desktop; use sandbox-loopback or a prepared public target.", [
             {
                 name: "target policy",
                 ok: false,
@@ -43,7 +43,7 @@ export async function runPublicPreviewPreflight(ctx) {
     }
     const e2bApiKey = ctx.env.E2B_API_KEY?.trim();
     if (!e2bApiKey) {
-        return fail(ctx, "HUMANISH_LAB_PREFLIGHT_E2B_REQUIRED", "public-preview preflight creates one E2B desktop to probe target reachability; E2B_API_KEY is required.", [{ name: "e2b api key", ok: false, message: "missing E2B_API_KEY" }]);
+        return fail(ctx, "HUMANISH_STUDY_PREFLIGHT_E2B_REQUIRED", "public-preview preflight creates one E2B desktop to probe target reachability; E2B_API_KEY is required.", [{ name: "e2b api key", ok: false, message: "missing E2B_API_KEY" }]);
     }
     // Each target gets at most one readiness budget.
     const leaseMs = publicTargets.length * ctx.timeoutMs + PREFLIGHT_LEASE_BUFFER_MS;
@@ -63,7 +63,7 @@ export async function runPublicPreviewPreflight(ctx) {
     }
     const failed = publicTargets.find((target) => target.reachable === false);
     if (failed) {
-        return fail(ctx, "HUMANISH_LAB_PREFLIGHT_TARGET_UNREACHABLE", "one or more declared public-preview targets were not reachable from the hosted desktop.", [
+        return fail(ctx, "HUMANISH_STUDY_PREFLIGHT_TARGET_UNREACHABLE", "one or more declared public-preview targets were not reachable from the hosted desktop.", [
             {
                 name: "target reachability",
                 ok: false,
@@ -82,13 +82,13 @@ export async function runPublicPreviewPreflight(ctx) {
 export async function runSandboxLoopbackPreflight(ctx) {
     const routeError = sandboxLoopbackRouteError(ctx.config, ctx.route);
     if (routeError) {
-        return fail(ctx, "HUMANISH_LAB_PREFLIGHT_UNSUPPORTED_ROUTE", routeError, [
+        return fail(ctx, "HUMANISH_STUDY_PREFLIGHT_UNSUPPORTED_ROUTE", routeError, [
             { name: "route", ok: false, message: routeError },
         ]);
     }
     const missingEnv = (ctx.config.subject.env ?? []).filter((name) => !ctx.env[name]?.trim());
     if (missingEnv.length > 0) {
-        return fail(ctx, "HUMANISH_LAB_PREFLIGHT_ENV_MISSING", `sandbox-loopback preflight needs declared env values: ${missingEnv.join(", ")}`, [
+        return fail(ctx, "HUMANISH_STUDY_PREFLIGHT_ENV_MISSING", `sandbox-loopback preflight needs declared env values: ${missingEnv.join(", ")}`, [
             {
                 name: "subject env",
                 ok: false,
@@ -98,12 +98,12 @@ export async function runSandboxLoopbackPreflight(ctx) {
     }
     const e2bApiKey = ctx.env.E2B_API_KEY?.trim();
     if (!e2bApiKey) {
-        return fail(ctx, "HUMANISH_LAB_PREFLIGHT_E2B_REQUIRED", "sandbox-loopback preflight creates one E2B desktop to clone, serve, and probe the subject; E2B_API_KEY is required.", [{ name: "e2b api key", ok: false, message: "missing E2B_API_KEY" }]);
+        return fail(ctx, "HUMANISH_STUDY_PREFLIGHT_E2B_REQUIRED", "sandbox-loopback preflight creates one E2B desktop to clone, serve, and probe the subject; E2B_API_KEY is required.", [{ name: "e2b api key", ok: false, message: "missing E2B_API_KEY" }]);
     }
     const repo = ctx.config.subject.repos?.[0];
     const serve = ctx.config.subject.serve;
     if (!repo || !serve) {
-        return fail(ctx, "HUMANISH_LAB_PREFLIGHT_UNSUPPORTED_ROUTE", "sandbox-loopback preflight requires one clone repo and subject.serve.", [{ name: "clone subject", ok: false, message: "missing repo or serve block" }]);
+        return fail(ctx, "HUMANISH_STUDY_PREFLIGHT_UNSUPPORTED_ROUTE", "sandbox-loopback preflight requires one clone repo and subject.serve.", [{ name: "clone subject", ok: false, message: "missing repo or serve block" }]);
     }
     let subjectCommitDigest;
     // The longest the clone and serve steps can take with the lab's own budgets, so the probe is
@@ -216,7 +216,7 @@ async function withPreflightSandbox(ctx, args, callback) {
     if (failureMessage) {
         return {
             ok: false,
-            result: fail(ctx, "HUMANISH_LAB_PREFLIGHT_PROVISION_FAILED", failureMessage, [
+            result: fail(ctx, "HUMANISH_STUDY_PREFLIGHT_PROVISION_FAILED", failureMessage, [
                 { name: "sandbox preflight", ok: false, message: failureMessage },
             ]),
         };
@@ -224,7 +224,7 @@ async function withPreflightSandbox(ctx, args, callback) {
     if (ctx.sandbox.created && ctx.sandbox.killed !== true) {
         return {
             ok: false,
-            result: fail(ctx, "HUMANISH_LAB_PREFLIGHT_TEARDOWN_FAILED", "preflight sandbox was created but teardown could not be proven.", [{ name: "sandbox teardown", ok: false, message: "sandbox kill was not proven" }]),
+            result: fail(ctx, "HUMANISH_STUDY_PREFLIGHT_TEARDOWN_FAILED", "preflight sandbox was created but teardown could not be proven.", [{ name: "sandbox teardown", ok: false, message: "sandbox kill was not proven" }]),
         };
     }
     return { ok: true };

package/dist/lab/preflight-result.d.ts

@@ -1,5 +1,6 @@
 import type { LabPreflightCheck, LabPreflightResult, PreflightContext } from "./preflight.js";
-export declare const LAB_PREFLIGHT_SCHEMA = "humanish.lab-preflight-result.v1";
+/** The schema of `lab preflight` results: whether a study is ready to run on this machine. */
+export declare const STUDY_CHECK_SCHEMA = "humanish.study-check.v1";
 export declare function finalize(ctx: PreflightContext, args?: {
     check?: LabPreflightCheck;
 }): LabPreflightResult;

package/dist/lab/preflight-result.js

@@ -2,18 +2,19 @@
 // preflight-probes.ts both finish through these, so they live below both.
 import { automaticAnalysisBudget } from "../analysis/automatic-config.js";
 import { digestText } from "../evidence/redaction.js";
-export const LAB_PREFLIGHT_SCHEMA = "humanish.lab-preflight-result.v1";
+/** The schema of `lab preflight` results: whether a study is ready to run on this machine. */
+export const STUDY_CHECK_SCHEMA = "humanish.study-check.v1";
 export function finalize(ctx, args) {
     const checks = args?.check ? [...ctx.checks, args.check] : ctx.checks;
     const analysis = automaticAnalysisBudget(ctx.config.review?.analysis, ctx.route);
     return {
-        schema: LAB_PREFLIGHT_SCHEMA,
+        schema: STUDY_CHECK_SCHEMA,
         ...(analysis ? { analysis } : {}),
         ok: checks.every((check) => check.ok) &&
             ctx.targets.every((target) => target.status !== "failed" && target.status !== "blocked"),
         cwd: ctx.cwd,
-        lab: ctx.lab,
-        labId: ctx.labId,
+        study: ctx.lab,
+        studyId: ctx.labId,
         origin: ctx.origin,
         path: ctx.path,
         route: ctx.route,

package/dist/lab/preflight.d.ts

@@ -1,7 +1,7 @@
 import type { AutomaticAnalysisBudget } from "../analysis/automatic-config.js";
 import type { E2BDesktopModule } from "../substrates/e2b/sdk.js";
 import { type LabConfig } from "./types.js";
-import { LAB_PREFLIGHT_SCHEMA } from "./preflight-result.js";
+import { STUDY_CHECK_SCHEMA } from "./preflight-result.js";
 import { type LabRoute } from "./plan.js";
 import { type LabResolveFailure } from "./discover.js";
 export type LabPreflightReachabilityMode = "metadata" | "public-preview" | "sandbox-loopback" | "prepared-host";
@@ -38,11 +38,13 @@ interface LabPreflightSpend {
 export interface LabPreflightResult {
     /** The separate budget for a future live run, never spend by preflight itself. */
     analysis?: AutomaticAnalysisBudget;
-    schema: typeof LAB_PREFLIGHT_SCHEMA;
+    schema: typeof STUDY_CHECK_SCHEMA;
     ok: boolean;
     cwd: string;
-    lab: string;
-    labId?: string;
+    /** The study the caller asked for, as given. */
+    study: string;
+    /** The resolved study's `id`, once the file parses. */
+    studyId?: string;
     origin?: string;
     path?: string;
     route?: LabRoute;
@@ -53,7 +55,7 @@ export interface LabPreflightResult {
     spend: LabPreflightSpend;
     warnings: string[];
     error?: {
-        code: LabResolveFailure["error"]["code"] | "HUMANISH_LAB_PREFLIGHT_INVALID_OPTION" | "HUMANISH_LAB_PREFLIGHT_UNSUPPORTED_ROUTE" | "HUMANISH_LAB_PREFLIGHT_TARGET_POLICY" | "HUMANISH_LAB_PREFLIGHT_ENV_MISSING" | "HUMANISH_LAB_PREFLIGHT_E2B_REQUIRED" | "HUMANISH_LAB_PREFLIGHT_TARGET_UNREACHABLE" | "HUMANISH_LAB_PREFLIGHT_PROVISION_FAILED" | "HUMANISH_LAB_PREFLIGHT_TEARDOWN_FAILED";
+        code: LabResolveFailure["error"]["code"] | "HUMANISH_STUDY_PREFLIGHT_INVALID_OPTION" | "HUMANISH_STUDY_PREFLIGHT_UNSUPPORTED_ROUTE" | "HUMANISH_STUDY_PREFLIGHT_TARGET_POLICY" | "HUMANISH_STUDY_PREFLIGHT_ENV_MISSING" | "HUMANISH_STUDY_PREFLIGHT_E2B_REQUIRED" | "HUMANISH_STUDY_PREFLIGHT_TARGET_UNREACHABLE" | "HUMANISH_STUDY_PREFLIGHT_PROVISION_FAILED" | "HUMANISH_STUDY_PREFLIGHT_TEARDOWN_FAILED";
         message: string;
     };
 }

package/dist/lab/preflight.js

@@ -2,7 +2,7 @@ import path from "node:path";
 import { isLoopbackUrl } from "./parse/subject.js";
 import {} from "./types.js";
 import { runPublicPreviewPreflight, runSandboxLoopbackPreflight } from "./preflight-probes.js";
-import { digest, fail, finalize, LAB_PREFLIGHT_SCHEMA } from "./preflight-result.js";
+import { digest, fail, finalize, STUDY_CHECK_SCHEMA } from "./preflight-result.js";
 import { routeOf } from "./plan.js";
 import { resolveLabManifest } from "./discover.js";
 import { rosterOf } from "./parse/actors.js";
@@ -14,10 +14,10 @@ export async function runLabPreflight(options) {
     const resolved = await resolveLabManifest(cwd, options.lab);
     if (!resolved.ok) {
         return {
-            schema: LAB_PREFLIGHT_SCHEMA,
+            schema: STUDY_CHECK_SCHEMA,
             ok: false,
             cwd,
-            lab: options.lab,
+            study: options.lab,
             reachability,
             checks: [
                 {
@@ -60,7 +60,7 @@ export async function runLabPreflight(options) {
                 check: {
                     name: "reachability",
                     ok: true,
-                    message: "metadata-only; no network, sandbox, or model calls. Credentials, local login, dependencies and target reachability were not checked; use humanish doctor --lab <lab> for setup checks.",
+                    message: "metadata-only; no network, sandbox, or model calls. Credentials, local login, dependencies and target reachability were not checked; use humanish doctor --study <study> for setup checks.",
                 },
             });
         case "public-preview":
@@ -68,7 +68,7 @@ export async function runLabPreflight(options) {
         case "sandbox-loopback":
             return await runSandboxLoopbackPreflight(ctx);
         case "prepared-host":
-            return fail(ctx, "HUMANISH_LAB_PREFLIGHT_UNSUPPORTED_ROUTE", "prepared-host preflight requires a library adapter hook; the plain CLI can validate metadata only for this mode.", [
+            return fail(ctx, "HUMANISH_STUDY_PREFLIGHT_UNSUPPORTED_ROUTE", "prepared-host preflight requires a library adapter hook; the plain CLI can validate metadata only for this mode.", [
                 {
                     name: "prepared-host",
                     ok: false,

package/dist/lab/routing.d.ts

@@ -1,10 +1,10 @@
 import type { LabConfig } from "./types.js";
-export declare const MAX_CUA_LANES = 16;
+export declare const MAX_COMPUTER_USE_PARTICIPANTS = 16;
 export declare function actorResolvesToComputerUse(type: string | undefined): boolean;
 export declare function registeredComputerUseActors(): string[];
 export declare function actorResolvesToScriptedBrowser(type: string | undefined): boolean;
 export declare function registeredScriptedBrowserActors(): string[];
-/** True when `type` resolves to a registered terminal actor (the "terminal" lane). Exported so
+/** True when `type` resolves to a registered terminal actor (the "terminal" run kind). Exported so
  *  the engine + tests can resolve the dispatch the same way the parser does. */
 export declare function actorResolvesToTerminal(type: string | undefined): boolean;
 export declare function registeredTerminalActors(): string[];
@@ -13,64 +13,70 @@ export declare function registeredTerminalActors(): string[];
  * a homogeneous `count`, else 1. The single source of truth shared by the parser, the engine,
  * and the pre-flight plan so the participant count is computed the same way everywhere.
  */
-export declare function cuaLaneCount(config: LabConfig): number;
+export declare function computerUseParticipantCount(config: LabConfig): number;
 /**
  * A participant's id: its declared roster id, else `lane-NN` (independent participants) or `role-NN`
- * (shared-world seats) from its 0-based position. The parser's filled email recipients and the
- * routes that name participants both call this, so a filled recipient names a participant that
+ * (shared-world participants) from its 0-based position. The parser's filled email recipients and
+ * the routes that name participants both call this, so a filled recipient names a participant that
  * runs.
  */
 export declare function participantIdAt(index: number, declared: string | undefined, kind: "lane" | "seat"): string;
 /**
- * True when this config routes to the computer-use backend: an app-url subject whose first
- * actor resolves to a registered computer-use actor, or a clone subject on a hosted desktop
- * whose first actor does. Single source of truth — routeOf and the warning logic
- * both use it. (The app-url branch used to be unconditionally true; it narrowed when the
- * scripted-browser route arrived. Behavior-preserving for every parse-valid config —
- * routeOf keeps a bare app-url fallback to the cua backend so library-API configs
- * with unknown actors still hit its fail-closed ACTOR_UNSUPPORTED.)
+ * True when this config routes to the computer-use backend: an app-url subject whose first actor
+ * resolves to a registered computer-use actor, or a clone subject on a hosted desktop whose first
+ * actor does. Single source of truth: routeOf and the warning logic both use it. (The app-url
+ * branch also checks the first actor, so a scripted-browser actor routes elsewhere. routeOf keeps a
+ * bare app-url fallback to the computer-use route so library-API configs with unknown actors still
+ * hit its fail-closed ACTOR_UNSUPPORTED.)
  */
 export declare function isComputerUseComposition(config: LabConfig): boolean;
 /**
- * True when this config routes to the SHARED-WORLD backend (#164): a clone or local-tree subject
+ * True when this config routes to the shared-world route: a clone or local-tree subject
  * on a hosted desktop whose first actor resolves to a computer-use actor and that declares the
  * `shared-world` topology. Mirror of isComputerUseComposition; the single source of truth shared by
- * routeOf (which checks it before the cua route) and the warning logic. Every
+ * routeOf (which checks it before the computer-use route) and the warning logic. Every
  * shared-world study runs its participants at once (`execution.concurrency` >= 2). The same
  * clone/local-tree × e2b-desktop × computer-use composition without `topology: shared-world` stays per-lane-worlds
- * (the cua route) — the topology declaration is the override switch.
+ * (the computer-use route); the topology declaration is the override switch.
  */
 export declare function isSharedWorldComposition(config: LabConfig): boolean;
 /** The getHost provisioned-subject shared-world shape (clone/local-tree served + exposed in-sandbox). */
 export declare function isProvisionedSharedWorldComposition(config: LabConfig): boolean;
 /**
- * The external-public shared-world shape (#164 phase 2): a real public deployment used directly as
- * the shared plane — `source: app-url` + `topology: shared-world` + a computer-use actor on
+ * The external-public shared-world shape: a real public deployment used directly as
+ * the shared plane: `source: app-url` + `topology: shared-world` + a computer-use actor on
  * e2b-desktop + `policies.allowPublicTargets: true`. No getHost, no clone, no subject sandbox, no
  * seed. The operator-ownership attestation `subject.publicTarget` is required (validated in
- * externalPublicSharedWorldValidationReason, not here — this predicate is the router only, so a
+ * externalPublicSharedWorldValidationReason, not here; this predicate is the router only, so a
  * half-declared external-public config still routes here to get its precise fail-closed reason
- * rather than silently downgrading to the per-participant cua route).
+ * rather than silently downgrading to the per-participant computer-use route).
  */
 export declare function isExternalPublicSharedWorldComposition(config: LabConfig): boolean;
 /**
- * Resolve a shared-world seat's entry URL from `serve.url` + a role's `entry` (relative path or
- * same-origin absolute URL). Returns null when the combination is not a same-origin loopback URL
- * (the load-bearing public-safety boundary — a seat only ever drives the in-sandbox app).
+ * Resolve a shared-world participant's entry URL from `serve.url` and its roster entry's `entry`
+ * (a relative path or a same-origin absolute URL). Returns null when the result is not a
+ * same-origin loopback URL, so a participant only ever drives the in-sandbox app.
  */
-export declare function resolveSeatUrl(serveUrl: string, entry: string | undefined): string | null;
+export declare function resolveEntryUrl(serveUrl: string, entry: string | undefined): string | null;
 /**
  * True when this config routes to the scripted-browser backend: an app-url subject whose
  * first actor resolves to a registered scripted-browser actor (execution.target local or
- * absent — the parse layer enforces that pairing). Mirror of isComputerUseComposition; the single
+ * absent; the parse layer enforces that pairing). Mirror of isComputerUseComposition; the single
  * source of truth for routeOf and the warning logic.
  */
 export declare function isScriptedBrowserComposition(config: LabConfig): boolean;
 export declare function isProvisionedScriptedBrowserComposition(config: LabConfig): boolean;
 /**
  * True when this config routes to the terminal-product backend: a terminal-product subject whose
- * first actor resolves to a registered terminal actor (execution.target e2b-terminal or absent —
+ * first actor resolves to a registered terminal actor (execution.target e2b-terminal or absent;
  * the parse layer enforces that pairing). Mirror of isComputerUseComposition/isScriptedBrowserComposition;
  * the single source of truth for routeOf and the warning logic.
  */
 export declare function isTerminalProductComposition(config: LabConfig): boolean;
+/** 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;

package/dist/lab/routing.js

@@ -1,8 +1,8 @@
 import { actorRegistry } from "../actors/registry.js";
 import { isLoopbackUrl } from "./parse/subject.js";
-// Hard cap on fan-out participants (per the ratified design). No HUMANISH_MAX_LANES escape above this
-// until a reference panel demands it — N concurrent paid desktops is real money.
-export const MAX_CUA_LANES = 16;
+// Hard cap on computer-use participants. No setting raises it: each participant is a paid desktop,
+// and they all run at once.
+export const MAX_COMPUTER_USE_PARTICIPANTS = 16;
 // Run kinds whose evidence is the participant's screenshots. An actor that declares it produces none
 // cannot run on them: a code-only actor would claim a GUI flow it only reached through a shell.
 const SCREENSHOT_RUN_KINDS = new Set([
@@ -36,7 +36,7 @@ export function actorResolvesToScriptedBrowser(type) {
 export function registeredScriptedBrowserActors() {
     return registeredActorsOn("scripted-browser");
 }
-/** True when `type` resolves to a registered terminal actor (the "terminal" lane). Exported so
+/** True when `type` resolves to a registered terminal actor (the "terminal" run kind). Exported so
  *  the engine + tests can resolve the dispatch the same way the parser does. */
 export function actorResolvesToTerminal(type) {
     return actorResolvesTo(type, "terminal");
@@ -49,7 +49,7 @@ export function registeredTerminalActors() {
  * a homogeneous `count`, else 1. The single source of truth shared by the parser, the engine,
  * and the pre-flight plan so the participant count is computed the same way everywhere.
  */
-export function cuaLaneCount(config) {
+export function computerUseParticipantCount(config) {
     const actor = config.actors[0];
     if (actor?.lanes !== undefined) {
         return actor.lanes.length;
@@ -58,29 +58,28 @@ export function cuaLaneCount(config) {
 }
 /**
  * A participant's id: its declared roster id, else `lane-NN` (independent participants) or `role-NN`
- * (shared-world seats) from its 0-based position. The parser's filled email recipients and the
- * routes that name participants both call this, so a filled recipient names a participant that
+ * (shared-world participants) from its 0-based position. The parser's filled email recipients and
+ * the routes that name participants both call this, so a filled recipient names a participant that
  * runs.
  */
 export function participantIdAt(index, declared, kind) {
     return declared ?? `${kind === "seat" ? "role" : "lane"}-${String(index + 1).padStart(2, "0")}`;
 }
 /**
- * True when this config routes to the computer-use backend: an app-url subject whose first
- * actor resolves to a registered computer-use actor, or a clone subject on a hosted desktop
- * whose first actor does. Single source of truth — routeOf and the warning logic
- * both use it. (The app-url branch used to be unconditionally true; it narrowed when the
- * scripted-browser route arrived. Behavior-preserving for every parse-valid config —
- * routeOf keeps a bare app-url fallback to the cua backend so library-API configs
- * with unknown actors still hit its fail-closed ACTOR_UNSUPPORTED.)
+ * True when this config routes to the computer-use backend: an app-url subject whose first actor
+ * resolves to a registered computer-use actor, or a clone subject on a hosted desktop whose first
+ * actor does. Single source of truth: routeOf and the warning logic both use it. (The app-url
+ * branch also checks the first actor, so a scripted-browser actor routes elsewhere. routeOf keeps a
+ * bare app-url fallback to the computer-use route so library-API configs with unknown actors still
+ * hit its fail-closed ACTOR_UNSUPPORTED.)
  */
 export function isComputerUseComposition(config) {
     // local-app drives the cua loop in-process (a custom executor + a non-vision provider), so it
-    // routes to the cua backend exactly like an app-url subject with a computer-use actor.
+    // routes to the computer-use route exactly like an app-url subject with a computer-use actor.
     if (config.subject.source === "app-url" || config.subject.source === "local-app") {
         return actorResolvesToComputerUse(config.actors[0]?.type);
     }
-    // desktop-cli hands the participant a terminal instead of a served page (#495), but it is the
+    // desktop-cli hands the participant a terminal instead of a served page, but it is the
     // same route: same desktop, same actor, same prompt fields. Leaving it out of this predicate told
     // adopters their mission and persona were inert on the one route whose whole point is that a
     // person reads a screen.
@@ -95,13 +94,13 @@ export function isComputerUseComposition(config) {
         actorResolvesToComputerUse(config.actors[0]?.type));
 }
 /**
- * True when this config routes to the SHARED-WORLD backend (#164): a clone or local-tree subject
+ * True when this config routes to the shared-world route: a clone or local-tree subject
  * on a hosted desktop whose first actor resolves to a computer-use actor and that declares the
  * `shared-world` topology. Mirror of isComputerUseComposition; the single source of truth shared by
- * routeOf (which checks it before the cua route) and the warning logic. Every
+ * routeOf (which checks it before the computer-use route) and the warning logic. Every
  * shared-world study runs its participants at once (`execution.concurrency` >= 2). The same
  * clone/local-tree × e2b-desktop × computer-use composition without `topology: shared-world` stays per-lane-worlds
- * (the cua route) — the topology declaration is the override switch.
+ * (the computer-use route); the topology declaration is the override switch.
  */
 export function isSharedWorldComposition(config) {
     return (isProvisionedSharedWorldComposition(config) || isExternalPublicSharedWorldComposition(config));
@@ -114,13 +113,13 @@ export function isProvisionedSharedWorldComposition(config) {
         actorResolvesToComputerUse(config.actors[0]?.type));
 }
 /**
- * The external-public shared-world shape (#164 phase 2): a real public deployment used directly as
- * the shared plane — `source: app-url` + `topology: shared-world` + a computer-use actor on
+ * The external-public shared-world shape: a real public deployment used directly as
+ * the shared plane: `source: app-url` + `topology: shared-world` + a computer-use actor on
  * e2b-desktop + `policies.allowPublicTargets: true`. No getHost, no clone, no subject sandbox, no
  * seed. The operator-ownership attestation `subject.publicTarget` is required (validated in
- * externalPublicSharedWorldValidationReason, not here — this predicate is the router only, so a
+ * externalPublicSharedWorldValidationReason, not here; this predicate is the router only, so a
  * half-declared external-public config still routes here to get its precise fail-closed reason
- * rather than silently downgrading to the per-participant cua route).
+ * rather than silently downgrading to the per-participant computer-use route).
  */
 export function isExternalPublicSharedWorldComposition(config) {
     return (config.subject.source === "app-url" &&
@@ -130,11 +129,11 @@ export function isExternalPublicSharedWorldComposition(config) {
         config.policies?.allowPublicTargets === true);
 }
 /**
- * Resolve a shared-world seat's entry URL from `serve.url` + a role's `entry` (relative path or
- * same-origin absolute URL). Returns null when the combination is not a same-origin loopback URL
- * (the load-bearing public-safety boundary — a seat only ever drives the in-sandbox app).
+ * Resolve a shared-world participant's entry URL from `serve.url` and its roster entry's `entry`
+ * (a relative path or a same-origin absolute URL). Returns null when the result is not a
+ * same-origin loopback URL, so a participant only ever drives the in-sandbox app.
  */
-export function resolveSeatUrl(serveUrl, entry) {
+export function resolveEntryUrl(serveUrl, entry) {
     if (entry === undefined || entry === "") {
         return isLoopbackUrl(serveUrl) ? serveUrl : null;
     }
@@ -156,7 +155,7 @@ export function resolveSeatUrl(serveUrl, entry) {
 /**
  * True when this config routes to the scripted-browser backend: an app-url subject whose
  * first actor resolves to a registered scripted-browser actor (execution.target local or
- * absent — the parse layer enforces that pairing). Mirror of isComputerUseComposition; the single
+ * absent; the parse layer enforces that pairing). Mirror of isComputerUseComposition; the single
  * source of truth for routeOf and the warning logic.
  */
 export function isScriptedBrowserComposition(config) {
@@ -172,10 +171,42 @@ export function isProvisionedScriptedBrowserComposition(config) {
 }
 /**
  * True when this config routes to the terminal-product backend: a terminal-product subject whose
- * first actor resolves to a registered terminal actor (execution.target e2b-terminal or absent —
+ * first actor resolves to a registered terminal actor (execution.target e2b-terminal or absent;
  * the parse layer enforces that pairing). Mirror of isComputerUseComposition/isScriptedBrowserComposition;
  * the single source of truth for routeOf and the warning logic.
  */
 export function isTerminalProductComposition(config) {
     return (config.subject.source === "terminal-product" && actorResolvesToTerminal(config.actors[0]?.type));
 }
+/**
+ * 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";
+}

package/dist/lab/run-lab-events.d.ts

@@ -1,5 +1,4 @@
 import type { CuaParticipantPlan } from "../routes/computer-use/types.js";
-import type { PhaseParticipant } from "./lab-deps.js";
 import type { SubjectPhaseEvent } from "../subject/steps.js";
 import type { InternalRunLabOptions } from "../run-lab.js";
 import type { LabRoute } from "./plan.js";
@@ -59,6 +58,4 @@ export declare function knownSecretValues(config: LabConfig, options: InternalRu
 export declare function labEventEmitter(onEvent: ((event: LabEvent) => void | Promise<void>) | undefined, warnings: string[], secretValues: () => string[]): ((event: LabEvent) => void) | undefined;
 /** The computer-use participant plan as a `plan` event: ids, personas, devices and digests. */
 export declare function planEvent(plan: CuaParticipantPlan): LabEvent;
-/** A participant as the route reports a phase for it, renamed to the event's field names. */
-export declare const participantOf: (participant: PhaseParticipant) => ParticipantRef;
 export declare function phaseEvent(event: SubjectPhaseEvent, target: SetupTarget): LabEvent;

package/dist/lab/run-lab-events.js

@@ -68,12 +68,6 @@ export function planEvent(plan) {
         })),
     };
 }
-/** A participant as the route reports a phase for it, renamed to the event's field names. */
-export const participantOf = (participant) => ({
-    id: participant.laneId,
-    index: participant.laneIndex,
-    count: participant.laneCount,
-});
 export function phaseEvent(event, target) {
     return {
         type: "subject-phase",

package/dist/lab/run-lab-homes.d.ts

@@ -17,21 +17,32 @@ export interface InProcessDriver {
         appUrl: string;
     }) => Promise<CuaExecutor>;
 }
-export type StreamEvent = 
-/** Runtime only: `url` carries an auth key and must never be persisted. */
-{
-    type: "ready";
+interface StreamEventIds {
     participantId: string;
-    sandboxId: string;
-    simId: string;
+    /**
+     * The id of this participant's entry in run.json `simulations[]` (`sim-001`), which
+     * `streams[].simId` also holds.
+     */
+    recordId: string;
     streamId: string;
+}
+type StreamEventFields = (StreamEventIds & {
+    type: "ready";
+    sandboxId: string;
+    /** Runtime only: carries an auth key and must never be persisted. */
     url: string;
-} | {
+}) | (StreamEventIds & {
     type: "ended";
-    participantId: string;
-    simId: string;
-    streamId: string;
+});
+export type StreamEvent = StreamEventFields & {
+    /**
+     * @deprecated Use `recordId`, which holds the same value. Reading it warns once per process; the
+     * next minor removes it.
+     */
+    readonly simId: string;
 };
+/** A stream event as the routes report it, with `simId` as a getter over `recordId`. */
+export declare function streamEvent(fields: StreamEventFields): StreamEvent;
 /** The options with a typed home, common to every route. */
 export interface RunLabHomes {
     /** Keys and subject env for the run. Defaults to process.env. */
@@ -62,3 +73,4 @@ export type RunLabDriving = {
     inProcess: InProcessDriver;
     createProvider: ProviderFactory;
 };
+export {};

package/dist/lab/run-lab-homes.js

@@ -1,3 +1,7 @@
 // The public RunLabOptions homes that every route reads: env, scorer, prepareDesktop, onEvent,
 // onStream and analysisSignal, and the brain and in-process driving computer use takes.
-export {};
+import { withDeprecatedFields } from "./deprecated-fields.js";
+/** A stream event as the routes report it, with `simId` as a getter over `recordId`. */
+export function streamEvent(fields) {
+    return withDeprecatedFields({ ...fields }, { name: "StreamEvent", code: "HUMANISH_STREAM_EVENT_FIELD_DEPRECATED" }, { simId: { replacement: "recordId", read: () => fields.recordId } });
+}

package/dist/lab/run-lab-options.d.ts

@@ -4,7 +4,7 @@ import type { LabConfig } from "./types.js";
 import { type LabEvent } from "./run-lab-events.js";
 type Refusal = {
     ok: false;
-    code: "HUMANISH_LAB_OPTION_UNSUPPORTED";
+    code: "HUMANISH_STUDY_OPTION_UNSUPPORTED";
     message: string;
 };
 type Normalized = {