humanish 0.106.1 → 0.108.0

package/dist/lab/preflight.d.ts

@@ -1,8 +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 type { LabBackend } from "./plan.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";
@@ -39,15 +38,15 @@ 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;
-    /** The route's older name; `route` is the current one. */
-    backend?: LabBackend;
     route?: LabRoute;
     reachability: LabPreflightReachabilityMode;
     checks: LabPreflightCheck[];
@@ -56,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: [
                 {
@@ -48,7 +48,7 @@ export async function runLabPreflight(options) {
         hooks: options.hooks ?? {},
         checks: [
             { name: "lab manifest", ok: true, message: `resolved ${resolved.origin} lab manifest` },
-            { name: "backend", ok: true, message: `selected the ${route} route` },
+            { name: "route", ok: true, message: `selected the ${route} route` },
         ],
         targets: collectTargets(resolved.config),
         sandbox: { created: false },
@@ -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/requirements.d.ts

@@ -0,0 +1,20 @@
+import type { LabPlan, Requirement } from "./plan-types.js";
+/** The `key` requirements whose value `env` lacks, OPENAI_API_KEY before E2B_API_KEY. */
+export declare function missingKeys(requirements: readonly Requirement[], env: Record<string, string | undefined>): string[];
+/** The subject env names the requirements list and `env` lacks, in declaration order. */
+export declare function missingSubjectEnv(requirements: readonly Requirement[], env: Record<string, string | undefined>): string[];
+/**
+ * The provider keys the requirements name, in plan order. A `key-one-of` names the first of its
+ * keys that `isPresent` reports, else OPENAI_API_KEY.
+ */
+export declare function requiredKeys(requirements: readonly Requirement[], isPresent: (name: string) => boolean): string[];
+/** The subject env names the requirements list, in declaration order. */
+export declare function requiredSubjectEnv(requirements: readonly Requirement[]): string[];
+/**
+ * The provider keys a live run of `plan` is known to read: its `key` and `key-one-of` names, its
+ * subject env, the external catch's token variable, ANTHROPIC_API_KEY for a Claude Code
+ * participant, and OPENAI_API_KEY when automatic analysis runs on OpenAI. `lab run` prints a
+ * key-source line for these only. Discovery still fills every key it finds: other readers, such as
+ * a declared scorer's host code, are not in the plan.
+ */
+export declare function keyNamesOf(plan: LabPlan): ReadonlySet<string>;

package/dist/lab/requirements.js

@@ -0,0 +1,54 @@
+/** Provider keys in the order the routes name them in a refusal. */
+const KEY_ORDER = ["OPENAI_API_KEY", "E2B_API_KEY"];
+const present = (env, name) => (env[name]?.trim() ?? "") !== "";
+/** The `key` requirements whose value `env` lacks, OPENAI_API_KEY before E2B_API_KEY. */
+export function missingKeys(requirements, env) {
+    const required = new Set(requirements.flatMap((requirement) => (requirement.kind === "key" ? [requirement.name] : [])));
+    return KEY_ORDER.filter((name) => required.has(name) && !present(env, name));
+}
+/** The subject env names the requirements list and `env` lacks, in declaration order. */
+export function missingSubjectEnv(requirements, env) {
+    return requiredSubjectEnv(requirements).filter((name) => !present(env, name));
+}
+/**
+ * The provider keys the requirements name, in plan order. A `key-one-of` names the first of its
+ * keys that `isPresent` reports, else OPENAI_API_KEY.
+ */
+export function requiredKeys(requirements, isPresent) {
+    return requirements.flatMap((requirement) => {
+        if (requirement.kind === "key")
+            return [requirement.name];
+        if (requirement.kind === "key-one-of")
+            return [requirement.names.find(isPresent) ?? requirement.names[1]];
+        return [];
+    });
+}
+/** The subject env names the requirements list, in declaration order. */
+export function requiredSubjectEnv(requirements) {
+    return requirements.flatMap((requirement) => requirement.kind === "subject-env" ? requirement.names : []);
+}
+/**
+ * The provider keys a live run of `plan` is known to read: its `key` and `key-one-of` names, its
+ * subject env, the external catch's token variable, ANTHROPIC_API_KEY for a Claude Code
+ * participant, and OPENAI_API_KEY when automatic analysis runs on OpenAI. `lab run` prints a
+ * key-source line for these only. Discovery still fills every key it finds: other readers, such as
+ * a declared scorer's host code, are not in the plan.
+ */
+export function keyNamesOf(plan) {
+    const names = new Set();
+    for (const requirement of plan.requirements) {
+        if (requirement.kind === "key")
+            names.add(requirement.name);
+        if (requirement.kind === "key-one-of" || requirement.kind === "subject-env")
+            for (const name of requirement.names)
+                names.add(name);
+        if (requirement.kind === "local-agent" && requirement.agent === "claude")
+            names.add("ANTHROPIC_API_KEY");
+    }
+    const catchToken = plan.residual.comms?.email?.external?.authTokenEnv;
+    if (catchToken !== undefined)
+        names.add(catchToken);
+    if (plan.analysis !== undefined && plan.analysis.config.provider !== "codex")
+        names.add("OPENAI_API_KEY");
+    return names;
+}

package/dist/lab/route-inputs.d.ts

@@ -1,17 +1,28 @@
-import type { RunLabOptions } from "../run-lab.js";
+import type { InternalRunLabOptions } from "../run-lab.js";
+import type { RunScorerProvenance } from "../run/bundle.js";
+import { type AdapterScorerModule } from "./adapter-scorer-loader.js";
+import type { LabDeps } from "./lab-deps.js";
+import type { LabEvent } from "./run-lab-events.js";
 import type { ComputerUseRunInput } from "../routes/computer-use/types.js";
 import type { ScriptedRunInput } from "../routes/scripted/types.js";
 import type { SharedWorldRunInput } from "../routes/shared-world/types.js";
 import type { TerminalRunInput } from "../routes/terminal/types.js";
-export declare function computerUseInput(options: RunLabOptions): ComputerUseRunInput;
-export declare function scriptedInput(options: RunLabOptions): ScriptedRunInput;
-export declare function terminalInput(options: RunLabOptions): TerminalRunInput;
-export declare function sharedWorldInput(options: RunLabOptions): SharedWorldRunInput;
+export declare function computerUseInput(options: InternalRunLabOptions, deps: LabDeps, emit: LabEmit | undefined): ComputerUseRunInput;
+export declare function scriptedInput(options: InternalRunLabOptions, deps: LabDeps, emit: LabEmit | undefined): ScriptedRunInput;
+export declare function terminalInput(options: InternalRunLabOptions, deps: LabDeps, emit: LabEmit | undefined): TerminalRunInput;
+export declare function sharedWorldInput(options: InternalRunLabOptions, deps: LabDeps, emit: LabEmit | undefined): SharedWorldRunInput;
 /** A scorer the CLI loads after the route's local checks, and the provenance it stamps on the run. */
-export type LateScorer = Pick<RunLabOptions, "scorer" | "scorerProvenance">;
-/** The computer-use input with a scorer loaded after admission (see withLateScorer). */
-export declare function computerUseInputWithScorer(input: ComputerUseRunInput, late: LateScorer | undefined): ComputerUseRunInput;
-/** The shared-world input with a scorer loaded after admission (see withLateScorer). */
-export declare function sharedWorldInputWithScorer(input: SharedWorldRunInput, late: LateScorer | undefined): SharedWorldRunInput;
-/** The terminal input with a scorer loaded after admission. Terminal runs take no deriveArtifacts. */
-export declare function terminalInputWithScorer(input: TerminalRunInput, late: LateScorer | undefined): TerminalRunInput;
+export type LateScorer = Pick<InternalRunLabOptions, "scorer" | "scorerProvenance">;
+/** Narrows RunLabOptions.scorer to the context the route passes (adapter-scorer-loader.ts). */
+type NarrowScorer<S> = (scorer: AdapterScorerModule) => S;
+/**
+ * A route's input with a scorer loaded after admission, and the scorer's provenance, as if the
+ * caller had passed them up front. The rest of the input is the one the route's checks admitted.
+ */
+export declare function withLateScorer<S, I extends {
+    scorer?: S;
+    scorerProvenance?: RunScorerProvenance;
+}>(input: I, late: LateScorer | undefined, narrow: NarrowScorer<S>): I;
+/** Reports a LabEvent to onEvent without waiting (normalizeRunLabOptions builds it). */
+type LabEmit = (event: LabEvent) => void;
+export {};

package/dist/lab/route-inputs.js

@@ -1,95 +1,92 @@
-// What each route's run takes from runLab's options: the shared run settings, the route's own
-// hook bag, the automatic-analysis hooks and the declared scorer's provenance.
-import { HOOK_MEMBERS, withHookOverrides } from "./bag-overrides.js";
-import { scorerHooks } from "./run-lab-options.js";
-export function computerUseInput(options) {
+// What each route's run takes from runLab's options: the shared run settings, the typed options
+// the route reads, the event emitter, the test seams and the declared scorer's provenance.
+import { browserRouteScorer, terminalRouteScorer, } from "./adapter-scorer-loader.js";
+export function computerUseInput(options, deps, emit) {
     return {
         ...analysisOf(options),
         cwd: options.cwd,
-        // CLI --count overrides the homogeneous fan-out lane count (a declared roster's length wins).
+        // CLI --count overrides the homogeneous fan-out participant count (a declared roster's length wins).
         ...(options.count === undefined ? {} : { countOverride: options.count }),
         ...(options.open === undefined ? {} : { open: options.open }),
         ...(options.onObserverReady === undefined ? {} : { onObserverReady: options.onObserverReady }),
         ...(options.runId === undefined ? {} : { runId: options.runId }),
         ...(options.rerun === undefined ? {} : { rerun: options.rerun }),
-        ...(options.cuaHooks === undefined ? {} : { hooks: options.cuaHooks }),
-        ...scorerOf(options),
+        ...(options.env === undefined ? {} : { env: options.env }),
+        ...(options.prepareDesktop === undefined ? {} : { prepareDesktop: options.prepareDesktop }),
+        ...(options.createProvider === undefined ? {} : { createProvider: options.createProvider }),
+        ...(options.inProcess === undefined ? {} : { inProcess: options.inProcess }),
+        ...(options.localVm === undefined ? {} : { localVm: options.localVm }),
+        ...observersOf(options, emit),
+        deps,
+        ...scorerOf(options, browserRouteScorer),
     };
 }
-export function scriptedInput(options) {
+export function scriptedInput(options, deps, emit) {
     return {
         ...analysisOf(options),
+        ...(emit === undefined ? {} : { emit }),
         cwd: options.cwd,
         ...(options.open === undefined ? {} : { open: options.open }),
         ...(options.runId === undefined ? {} : { runId: options.runId }),
-        ...(options.scriptedHooks === undefined ? {} : { hooks: options.scriptedHooks }),
+        ...(options.env === undefined ? {} : { env: options.env }),
+        ...(options.prepareDesktop === undefined ? {} : { prepareDesktop: options.prepareDesktop }),
+        deps,
     };
 }
-export function terminalInput(options) {
+export function terminalInput(options, deps, emit) {
     return {
         ...analysisOf(options),
+        ...(emit === undefined ? {} : { emit }),
         cwd: options.cwd,
         ...(options.open === undefined ? {} : { open: options.open }),
         ...(options.runId === undefined ? {} : { runId: options.runId }),
-        ...(options.terminalHooks === undefined ? {} : { hooks: options.terminalHooks }),
-        ...scorerOf(options),
+        ...(options.env === undefined ? {} : { env: options.env }),
+        deps,
+        ...scorerOf(options, terminalRouteScorer),
     };
 }
-export function sharedWorldInput(options) {
+export function sharedWorldInput(options, deps, emit) {
     return {
         ...analysisOf(options),
         cwd: options.cwd,
         ...(options.open === undefined ? {} : { open: options.open }),
         ...(options.onObserverReady === undefined ? {} : { onObserverReady: options.onObserverReady }),
         ...(options.runId === undefined ? {} : { runId: options.runId }),
-        ...(options.sharedWorldHooks === undefined ? {} : { hooks: options.sharedWorldHooks }),
-        ...scorerOf(options),
+        ...(options.env === undefined ? {} : { env: options.env }),
+        ...(options.prepareDesktop === undefined ? {} : { prepareDesktop: options.prepareDesktop }),
+        ...observersOf(options, emit),
+        deps,
+        ...scorerOf(options, browserRouteScorer),
     };
 }
-/** The computer-use input with a scorer loaded after admission (see withLateScorer). */
-export function computerUseInputWithScorer(input, late) {
-    const hooks = late?.scorer === undefined ? undefined : scorerHooks(late.scorer);
-    return withLateScorer(input, HOOK_MEMBERS.cua, hooks, late);
-}
-/** The shared-world input with a scorer loaded after admission (see withLateScorer). */
-export function sharedWorldInputWithScorer(input, late) {
-    const hooks = late?.scorer === undefined ? undefined : scorerHooks(late.scorer);
-    return withLateScorer(input, HOOK_MEMBERS.sharedWorld, hooks, late);
-}
-/** The terminal input with a scorer loaded after admission. Terminal runs take no deriveArtifacts. */
-export function terminalInputWithScorer(input, late) {
-    const scorer = late?.scorer;
-    const hooks = scorer === undefined
-        ? undefined
-        : {
-            ...(scorer.score === undefined ? {} : { score: scorer.score }),
-            ...(scorer.deriveFeedback === undefined ? {} : { deriveFeedback: scorer.deriveFeedback }),
-        };
-    return withLateScorer(input, HOOK_MEMBERS.terminal, hooks, late);
-}
 /**
- * `input` with the scorer's hooks over its hook bag, as normalizeRunLabOptions maps a scorer the
- * caller passes up front, and the scorer's provenance. The bag is wrapped, never rebuilt, so the
- * members the route's checks already read stay the same objects.
+ * A route's input with a scorer loaded after admission, and the scorer's provenance, as if the
+ * caller had passed them up front. The rest of the input is the one the route's checks admitted.
  */
-function withLateScorer(input, declared, hooks, late) {
+export function withLateScorer(input, late, narrow) {
     if (late === undefined)
         return input;
     return {
         ...input,
-        ...(hooks === undefined
-            ? {}
-            : { hooks: withHookOverrides(input.hooks, declared, hooks) }),
+        ...(late.scorer === undefined ? {} : { scorer: narrow(late.scorer) }),
         ...(late.scorerProvenance === undefined ? {} : { scorerProvenance: late.scorerProvenance }),
     };
 }
+/** The caller's stream callback and the run's event emitter, for the routes that report them. */
+function observersOf(options, emit) {
+    return {
+        ...(options.onStream === undefined ? {} : { onStream: options.onStream }),
+        ...(emit === undefined ? {} : { emit }),
+    };
+}
 function analysisOf(options) {
-    return options.automaticAnalysis === undefined
-        ? {}
-        : { automaticAnalysis: options.automaticAnalysis };
+    return options.analysisSignal === undefined ? {} : { analysisSignal: options.analysisSignal };
 }
-function scorerOf(options) {
-    return options.scorerProvenance === undefined
-        ? {}
-        : { scorerProvenance: options.scorerProvenance };
+function scorerOf(options, narrow) {
+    return {
+        ...(options.scorer === undefined ? {} : { scorer: narrow(options.scorer) }),
+        ...(options.scorerProvenance === undefined
+            ? {}
+            : { scorerProvenance: options.scorerProvenance }),
+    };
 }

package/dist/lab/routing.d.ts

@@ -1,81 +1,82 @@
 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[];
 /**
- * The declared fan-out lane count on the computer-use route: a `lanes[]` roster's length, else
+ * The declared fan-out participant count on the computer-use route: a `lanes[]` roster's length, else
  * a homogeneous `count`, else 1. The single source of truth shared by the parser, the engine,
- * and the pre-flight plan so the lane count is computed ONE way everywhere.
+ * 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 lanes) 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
+ * A participant's id: its declared roster id, else `lane-NN` (independent participants) or `role-NN`
+ * (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 lane 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
- * on a hosted desktop whose first actor resolves to a computer-use actor AND that declares the
+ * 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.
+ * clone/local-tree × e2b-desktop × computer-use composition without `topology: shared-world` stays per-lane-worlds
+ * (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;
 /**
- * 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).
+ * 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
+ * half-declared external-public config still routes here to get its precise fail-closed reason
+ * rather than silently downgrading to the per-participant computer-use route).
  */
-export declare function resolveSeatUrl(serveUrl: string, entry: string | undefined): string | null;
+export declare function isExternalPublicSharedWorldComposition(config: LabConfig): boolean;
+/**
+ * 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 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;
-/** @deprecated Use `routeOf`. This goes in the next minor. */
-export declare function routesToComputerUse(config: LabConfig): boolean;
-/** @deprecated Use `routeOf`. This goes in the next minor. */
-export declare function routesToSharedWorld(config: LabConfig): boolean;
-/** @deprecated Use `routeOf`. This goes in the next minor. */
-export declare function routesToProvisionedSharedWorld(config: LabConfig): boolean;
-/** @deprecated Use `routeOf`. This goes in the next minor. */
-export declare function routesToExternalPublicSharedWorld(config: LabConfig): boolean;
+/** The five execution paths a lab can take. */
+export type LabRoute = "preview" | "computer-use" | "shared-world" | "terminal" | "scripted";
 /**
- * @deprecated Every shared-world study runs its participants at once since the sequential
- * shared-world route was removed. Use `routeOf`; this alias goes in the next minor.
+ * 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 routesToConcurrentSharedWorld(config: LabConfig): boolean;
-/** @deprecated Use `routeOf`. This goes in the next minor. */
-export declare function routesToScriptedBrowser(config: LabConfig): boolean;
-/** @deprecated Use `routeOf`. This goes in the next minor. */
-export declare function routesToTerminalProduct(config: LabConfig): boolean;
+export declare function routeOf(config: LabConfig): LabRoute;