humanish 0.106.1 → 0.107.0

package/dist/lab/doctor.d.ts

@@ -1,21 +1,48 @@
 import { type LocalRuntimeStatus } from "../substrates/local/runtime.js";
 import type { LabConfig } from "./types.js";
-import type { LabRoute } from "./plan.js";
+import type { PlanResult } from "./plan-types.js";
 import type { DetectedLocalAgent } from "../actors/local-agent/cli.js";
+import type { ReasoningEffort } from "../actors/reasoning-effort.js";
 import type { DoctorResult } from "../cli/doctor.js";
+import { type CodexInstallation } from "../actors/codex/qualified-versions.js";
+import type { RefusedCodexExecutable } from "../actors/codex/restricted-executable.js";
 type Check = DoctorResult["checks"][number];
-/** Read-only Codex account readiness. An unadmitted CLI also reports the release it found. */
+/**
+ * Read-only Codex account readiness. An unadmitted CLI also reports the release it found, and an
+ * unavailable one the file humanish found and turned down.
+ */
 type CodexReadiness = {
     ready: boolean;
     errorCode: string | null;
     detectedCliVersion?: string;
+    refusedExecutable?: RefusedCodexExecutable;
+    /** Where the `codex` on `PATH` was installed, for the command that replaces it. */
+    installation?: CodexInstallation;
+    /** How the release's app-server schema differs from the fields humanish reads. */
+    protocolIncompatibilities?: readonly string[];
+    /** Schema values beyond the baseline, recorded by a launch that passed. */
+    protocolAdditions?: readonly string[];
 };
+/** What doctor's hosted Codex participant check found: a readiness result and what it admitted. */
+type HostedCodexReadiness = CodexReadiness & {
+    cliVersion?: string;
+    resolvedModel?: string;
+    authentication?: "chatgpt-account" | "api-key";
+};
+/**
+ * The hosted participant check: the operator-auth launch to an ephemeral thread, with no turn,
+ * using the lab's declared model and reasoning effort as a run would.
+ */
+declare function hostedCodexReadiness(env: NodeJS.ProcessEnv, actor: {
+    model?: string;
+    reasoningEffort?: ReasoningEffort;
+}): Promise<HostedCodexReadiness>;
 /** Shared read-only Codex account check for local participants in doctor and the TUI. */
 export declare function localCodexParticipantCheck(args: {
     env: NodeJS.ProcessEnv;
     readiness?: (env: NodeJS.ProcessEnv) => Promise<CodexReadiness>;
 }): Promise<Check>;
-interface LabSetupCheckArgs {
+export interface LabSetupCheckArgs {
     cwd: string;
     lab: string;
     env: NodeJS.ProcessEnv;
@@ -24,16 +51,24 @@ interface LabSetupCheckArgs {
     /** Internal read-only qualification seam; never a participant/model request. */
     localRuntimeReadiness?: () => Promise<LocalRuntimeStatus>;
     codexAnalysisReadiness?: (env: NodeJS.ProcessEnv) => Promise<CodexReadiness>;
+    /** The hosted Codex participant's operator handshake; tests replace it. */
+    codexParticipantReadiness?: typeof hostedCodexReadiness;
 }
-/** Setup checks only: no model turn, browser or desktop creation. CLI startup may use the network. */
+/**
+ * Setup checks only: no model turn, browser or desktop creation. CLI startup may use the network.
+ * `keys` are the keys a live run requires. `reads` are the provider keys the lab is known to read,
+ * required or not; it is undefined when that is unknown: the lab does not plan, or a declared
+ * scorer's host code may read any key.
+ */
 export declare function labSetupChecks(args: LabSetupCheckArgs): Promise<{
     desktop: boolean;
     keys: string[];
+    reads?: ReadonlySet<string>;
     checks: Check[];
 }>;
-/** Required participant provider keys, shared by doctor and the TUI. Optional analysis is separate. */
-export declare function labKeyRequirements(config: LabConfig, route: LabRoute, dryRun: boolean, keyPresent: (name: string) => boolean): {
-    desktop: boolean;
-    keys: string[];
-};
+/**
+ * The lab planned with no run options, so its own scenario mode decides dry or live. Doctor and the
+ * TUI read a live run's keys and subject env from this plan's requirements.
+ */
+export declare function planCliRun(config: LabConfig, cwd: string): Promise<PlanResult>;
 export {};

package/dist/lab/doctor.js

@@ -1,25 +1,107 @@
+import path from "node:path";
 import { isLocalBrowserLab } from "../substrates/local/runtime-config.js";
 import { localRuntimeStatus } from "../substrates/local/runtime.js";
+import { keyNamesOf, requiredKeys, requiredSubjectEnv } from "./requirements.js";
+import { protocolAdditionsWarning, protocolIncompatibilityMessage, } from "../actors/codex/protocol-compat.js";
 import { automaticAnalysisBudget } from "../analysis/automatic-config.js";
 import { externalCatchHealthy } from "../comms/sandbox-catch.js";
 import { receivingRequiredKey } from "../comms/setup.js";
-import { codexVersionRecovery } from "../actors/codex/qualified-versions.js";
-/** The account check doctor and the TUI share; the version probe runs only for an unadmitted CLI. */
+import { classifyCodexInstallation, codexInstallAdvice, codexVersionRecovery, } from "../actors/codex/qualified-versions.js";
+/** A ready row's message, with the schema values the launch recorded. */
+function readyMessage(message, readiness) {
+    const additions = protocolAdditionsWarning(readiness.cliVersion, readiness.protocolAdditions);
+    return additions === undefined ? message : `${message} ${additions}`;
+}
+/** npm's global prefix (`npm prefix -g`), or undefined when npm does not answer. */
+async function npmGlobalPrefix(env) {
+    const { execFile } = await import("node:child_process");
+    return new Promise((resolve) => {
+        execFile("npm", ["prefix", "-g"], { env, timeout: 5000 }, (error, stdout) => {
+            const prefix = String(stdout).trim();
+            resolve(error === null && path.isAbsolute(prefix) ? prefix : undefined);
+        });
+    });
+}
+/** Where the `codex` on `PATH` was installed; npm's prefix is read only when not project-local. */
+async function codexInstallation(env) {
+    const { foundCodexExecutable } = await import("../actors/codex/restricted-executable.js");
+    const found = await foundCodexExecutable(env).catch(() => undefined);
+    if (found === undefined)
+        return undefined;
+    const local = classifyCodexInstallation(found, undefined);
+    return local.kind === "project"
+        ? local
+        : classifyCodexInstallation(found, await npmGlobalPrefix(env));
+}
+/** The account check doctor and the TUI share: the isolated launch, with recovery details. */
 async function codexAccountReadiness(env) {
-    const readiness = await (await import("../analysis/restricted-codex.js")).checkRestrictedCodexAnalysisReadiness({ timeoutMs: 5000 }, { env });
-    if (readiness.errorCode !== "codex_unsupported_version")
-        return readiness;
+    const checked = await (await import("../analysis/restricted-codex.js")).checkRestrictedCodexAnalysisReadiness({ timeoutMs: 5000 }, { env });
+    return withCodexRecoveryDetails(env, checked);
+}
+/**
+ * The hosted participant check: the operator-auth launch to an ephemeral thread, with no turn,
+ * using the lab's declared model and reasoning effort as a run would.
+ */
+async function hostedCodexReadiness(env, actor) {
+    const { checkRestrictedCodexParticipantReadiness } = await import("../actors/codex/restricted-participant.js");
+    const checked = await checkRestrictedCodexParticipantReadiness({
+        session: { env },
+        ...(actor.model === undefined ? {} : { model: actor.model }),
+        ...(actor.reasoningEffort === undefined ? {} : { reasoningEffort: actor.reasoningEffort }),
+    });
+    return checked.ready
+        ? checked
+        : { ...checked, ...(await withCodexRecoveryDetails(env, checked)) };
+}
+/**
+ * Adds what the recovery line names to a failed check. An unadmitted CLI gets its release, an
+ * unavailable one the file humanish turned down, and both where the binary came from.
+ */
+async function withCodexRecoveryDetails(env, checked) {
+    if (checked.errorCode !== "codex_unavailable" &&
+        checked.errorCode !== "codex_unsupported_version" &&
+        checked.errorCode !== "codex_incompatible_release")
+        return checked;
+    const installation = await codexInstallation(env);
+    const readiness = installation === undefined ? checked : { ...checked, installation };
+    if (readiness.errorCode === "codex_unavailable") {
+        const { refusedCodexExecutable } = await import("../actors/codex/restricted-executable.js");
+        const refused = await refusedCodexExecutable(env).catch(() => undefined);
+        return refused === undefined ? readiness : { ...readiness, refusedExecutable: refused };
+    }
     const { detectRestrictedCodexCliVersion } = await import("../actors/codex/restricted-session.js");
     const detected = await detectRestrictedCodexCliVersion({ timeoutMs: 5000 }, { env }).catch(() => undefined);
     // An admitted release here means app-server reported a different one; name what --version says.
     const version = detected?.cliVersion ?? detected?.detectedVersion;
     return version === undefined ? readiness : { ...readiness, detectedCliVersion: version };
 }
-/** What to do about a Codex readiness failure; an unadmitted CLI gets its exact install command. */
+/**
+ * What to do about a Codex readiness failure, one line per code: an unadmitted CLI gets its exact
+ * install command, a missing login `codex login`, and an unavailable CLI the file humanish turned
+ * down and why. Other codes get `fallback`.
+ */
 function codexRecovery(readiness, fallback) {
-    return readiness.errorCode === "codex_unsupported_version"
-        ? codexVersionRecovery(readiness.detectedCliVersion)
-        : fallback;
+    switch (readiness.errorCode) {
+        case "codex_unsupported_version":
+            return codexVersionRecovery(readiness.detectedCliVersion, readiness.installation);
+        case "codex_incompatible_release":
+            return `${protocolIncompatibilityMessage(readiness.detectedCliVersion, readiness.protocolIncompatibilities ?? [])} ${codexInstallAdvice(readiness.installation)} Then sign in with a ChatGPT account (\`codex login\`).`;
+        case "codex_login_required":
+            return "Codex is installed but not signed in. Run `codex login` and sign in with a ChatGPT account.";
+        case "codex_unsupported_auth":
+            return "Codex is signed in without a ChatGPT account, for example with an API key. Run `codex logout`, then `codex login` with a ChatGPT account.";
+        case "codex_unavailable": {
+            const refused = readiness.refusedExecutable;
+            const found = refused === undefined
+                ? "humanish could not start the Codex CLI."
+                : refused.path === undefined
+                    ? `Codex is unavailable: ${refused.reason}.`
+                    : `humanish found \`${refused.path}\` and cannot run it: ${refused.reason}.`;
+            return `${found} ${codexInstallAdvice(readiness.installation)} Then sign in with a ChatGPT account (\`codex login\`).`;
+        }
+        default:
+            return fallback;
+    }
 }
 /** Shared read-only Codex account check for local participants in doctor and the TUI. */
 export async function localCodexParticipantCheck(args) {
@@ -28,11 +110,16 @@ export async function localCodexParticipantCheck(args) {
         name: "local participant authentication",
         ok: readiness.ready,
         message: readiness.ready
-            ? "Qualified Codex CLI and ChatGPT login are ready for restricted local browser participants. No E2B or model API key is required; inference is remote, and model access and account quota remain untested."
+            ? readyMessage("Qualified Codex CLI and ChatGPT login are ready for restricted local browser participants. No E2B or model API key is required; inference is remote, and model access and account quota remain untested.", readiness)
             : `Local Codex participant setup is unavailable (${readiness.errorCode}). ${codexRecovery(readiness, "Install the supported Codex CLI version and sign in with a ChatGPT account.")} No API fallback is used.`,
     };
 }
-/** Setup checks only: no model turn, browser or desktop creation. CLI startup may use the network. */
+/**
+ * Setup checks only: no model turn, browser or desktop creation. CLI startup may use the network.
+ * `keys` are the keys a live run requires. `reads` are the provider keys the lab is known to read,
+ * required or not; it is undefined when that is unknown: the lab does not plan, or a declared
+ * scorer's host code may read any key.
+ */
 export async function labSetupChecks(args) {
     const { resolveLabManifest } = await import("./discover.js");
     const { resolveLabDryRun, routeOf } = await import("./plan.js");
@@ -53,7 +140,7 @@ export async function labSetupChecks(args) {
         },
     ];
     if (dryRun)
-        return { desktop: false, keys: [], checks };
+        return { desktop: false, keys: [], reads: new Set(), checks };
     const unsupported = unsupportedCliRoute(config, route);
     if (unsupported)
         return {
@@ -61,7 +148,17 @@ export async function labSetupChecks(args) {
             keys: [],
             checks: [...checks, { name: "live route", ok: false, message: unsupported }],
         };
-    const { desktop, keys } = labKeyRequirements(config, route, false, args.keyPresent);
+    const planned = await planCliRun(config, args.cwd);
+    if (!planned.ok)
+        return {
+            desktop: false,
+            keys: [],
+            checks: [...checks, { name: "live route", ok: false, message: planned.refusal.message }],
+        };
+    const requirements = planned.planned.plan.requirements;
+    const keys = requiredKeys(requirements, args.keyPresent);
+    // This flag controls the hosted desktop SDK check as well as its API key.
+    const desktop = keys.includes("E2B_API_KEY");
     const local = isLocalBrowserLab(config);
     // One account check, shared by the local participant row and the Codex analysis row.
     let accountReadiness;
@@ -73,12 +170,15 @@ export async function labSetupChecks(args) {
     checks.push(...(await participantChecks(config, route, keys, local, args, checkAccount)));
     if (route === "scripted")
         checks.push(await scriptedBrowserCheck());
-    checks.push(...subjectEnvChecks(config, args));
+    checks.push(...subjectEnvChecks(requiredSubjectEnv(requirements), args));
     const analysis = automaticAnalysisBudget(config.review?.analysis, route);
     if (analysis)
         checks.push(await analysisCheck(analysis, args, checkAccount));
     checks.push(checkScope(analysis));
-    return { desktop, keys, checks };
+    const reads = config.review?.scorer === undefined
+        ? new Set([...keyNamesOf(planned.planned.plan), ...keys])
+        : undefined;
+    return { desktop, keys, ...(reads === undefined ? {} : { reads }), checks };
 }
 /** A local browser study's runtime and, with an external catch, its captured inbox. */
 async function localBrowserChecks(config, args) {
@@ -137,6 +237,10 @@ async function participantChecks(config, route, keys, local, args, checkAccount)
     const agent = args.agents.find((entry) => entry.id === choice);
     if (local)
         return [await localCodexParticipantCheck({ env: args.env, readiness: checkAccount })];
+    // A signed-in hosted Codex gets the operator handshake; its sign-in status alone does not show
+    // that the operator's config, release and model admit a launch.
+    if (choice === "codex" && agent?.authStatus === "authenticated")
+        return [await hostedCodexParticipantCheck(args, config.actors[0])];
     return [
         {
             name: "local participant authentication",
@@ -149,6 +253,24 @@ async function participantChecks(config, route, keys, local, args, checkAccount)
         },
     ];
 }
+/** The hosted Codex participant row: what the operator handshake admitted, or how to fix it. */
+async function hostedCodexParticipantCheck(args, actor) {
+    const declared = {
+        ...(actor?.model === undefined ? {} : { model: actor.model }),
+        ...(actor?.reasoningEffort === undefined ? {} : { reasoningEffort: actor.reasoningEffort }),
+    };
+    const readiness = await (args.codexParticipantReadiness ?? hostedCodexReadiness)(args.env, declared).catch(() => ({ ready: false, errorCode: "codex_unavailable" }));
+    const account = readiness.authentication === "api-key"
+        ? "an API key, which bills its usage to that key"
+        : "a ChatGPT account";
+    return {
+        name: "local participant authentication",
+        ok: readiness.ready,
+        message: readiness.ready
+            ? readyMessage(`Codex CLI ${readiness.cliVersion ?? "(unknown release)"} passed the operator handshake without a turn (initialize, config/read, account/read and an ephemeral thread/start): model ${readiness.resolvedModel ?? "(not reported)"} on ${account}. E2B supplies the desktop; no OpenAI API key is required for this participant.`, readiness)
+            : `Hosted Codex participant setup is unavailable (${readiness.errorCode}). ${codexRecovery(readiness, "Check `codex login status` and the operator's Codex configuration, then rerun doctor.")} No API fallback is used.`,
+    };
+}
 /** The local Chrome/Chromium the scripted-browser route drives. */
 async function scriptedBrowserCheck() {
     const { resolveBrowserCommand } = await import("../actors/scripted-browser/browser-command.js");
@@ -158,9 +280,9 @@ async function scriptedBrowserCheck() {
         message: "Scripted-browser uses local Chrome/Chromium and no participant model. Install Chrome/Chromium or set HUMANISH_BROWSER_COMMAND; a clone subject additionally needs E2B.",
     };
 }
-/** One row per declared subject env name: present or missing, never the value. */
-function subjectEnvChecks(config, args) {
-    return (config.subject.env ?? []).map((name) => ({
+/** One row per subject env name the plan requires: present or missing, never the value. */
+function subjectEnvChecks(names, args) {
+    return names.map((name) => ({
         name: `subject env ${name}`,
         ok: !!args.env[name]?.trim() || args.keyPresent(name),
         message: args.env[name]?.trim() || args.keyPresent(name)
@@ -168,7 +290,7 @@ function subjectEnvChecks(config, args) {
             : "missing declared subject environment variable; provide it with --env-file",
     }));
 }
-/** The post-run analysis: the Codex account, or the OpenAI key and the admission estimate limit. */
+/** The post-run analysis: the Codex account, or the OpenAI key and the analysis cost limit. */
 async function analysisCheck(analysis, args, checkAccount) {
     if (analysis.provider === "codex") {
         const readiness = await checkAccount();
@@ -181,7 +303,7 @@ async function analysisCheck(analysis, args, checkAccount) {
             name: "post-run analysis",
             ok: readiness.ready,
             message: readiness.ready
-                ? "Qualified Codex CLI and ChatGPT account login are ready for a separate restricted analyst. Analysis sends selected evidence to remote inference; model access and account allowance remain untested. Dollar cost and output-token ceilings are unavailable."
+                ? readyMessage("Qualified Codex CLI and ChatGPT account login are ready for a separate restricted analyst. Analysis sends selected evidence to remote inference; model access and account allowance remain untested. Dollar cost and output-token ceilings are unavailable.", readiness)
                 : `Codex account analysis is unavailable (${readiness.errorCode ?? "codex_unavailable"}). ${recovery} No API fallback is used; participant readiness is independent.`,
         };
     }
@@ -189,7 +311,7 @@ async function analysisCheck(analysis, args, checkAccount) {
         name: "post-run analysis",
         ok: true,
         message: args.keyPresent("OPENAI_API_KEY")
-            ? `OPENAI_API_KEY is present for the separate automatic analysis request; model access and quota are not tested. Its $${analysis.maxCostUsd} admission estimate limit may decline larger studies before dispatch; it is not a provider billing cap. Participant readiness is independent.`
+            ? `OPENAI_API_KEY is present for the separate automatic analysis request; model access and quota are not tested. The analysis is refused before it starts if its estimate is over $${analysis.maxCostUsd}; this is not a billing cap. Participant readiness is independent.`
             : "Will be skipped: OPENAI_API_KEY is missing. The participant may run, but there will be no automatic findings report. Add an OpenAI API key or set review.analysis: false deliberately.",
     };
 }
@@ -203,26 +325,12 @@ function checkScope(analysis) {
             : "Local setup only. Provider credentials are not validated, model access/quota and target reachability are untested, and no paid resources were created.",
     };
 }
-/** Required participant provider keys, shared by doctor and the TUI. Optional analysis is separate. */
-export function labKeyRequirements(config, route, dryRun, keyPresent) {
-    if (dryRun || unsupportedCliRoute(config, route))
-        return { desktop: false, keys: [] };
-    // This flag controls the hosted desktop SDK check as well as its API key.
-    const desktop = !isLocalBrowserLab(config) &&
-        (route === "computer-use" ||
-            route === "terminal" ||
-            route === "shared-world" ||
-            (route === "scripted" && config.subject.source === "clone"));
-    const keys = desktop ? ["E2B_API_KEY"] : [];
-    const openaiBrain = config.actors[0]?.type !== "local-agent";
-    if (route === "terminal")
-        keys.push(keyPresent("CODEX_API_KEY") ? "CODEX_API_KEY" : "OPENAI_API_KEY");
-    // Shared world's external-public plane reads the host's lobby code with the OpenAI API,
-    // whatever brain drives the participants (routes/shared-world/plan.ts).
-    else if ((route === "computer-use" && openaiBrain) ||
-        (route === "shared-world" && (openaiBrain || config.subject.source === "app-url")))
-        keys.push("OPENAI_API_KEY");
-    return { desktop, keys };
+/**
+ * The lab planned with no run options, so its own scenario mode decides dry or live. Doctor and the
+ * TUI read a live run's keys and subject env from this plan's requirements.
+ */
+export async function planCliRun(config, cwd) {
+    return (await import("./plan.js")).planLab(config, { cwd });
 }
 function unsupportedCliRoute(config, route) {
     if (config.subject.source === "local-app")

package/dist/lab/init-plan.js

@@ -3,6 +3,7 @@
 // here; runInit applies the plan.
 import path from "node:path";
 import { humanishScripts } from "./init-templates.js";
+import { isRecord } from "../run/type-guards.js";
 import { readTextIfExists } from "./init-paths.js";
 export async function planGitignore(projectRoot, cwd) {
     const relativePath = ".gitignore";
@@ -158,6 +159,3 @@ export async function planPackageJson(projectRoot, cwd) {
 function trimTrailingNewlines(text) {
     return text.replace(/\n+$/, "");
 }
-function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}

package/dist/lab/keys.js

@@ -92,7 +92,7 @@ const ACTOR = {
     type: true,
     count: true,
     lanes: PARTICIPANT_ENTRY,
-    // Roster groups are lanes with a count; the parser expands them into lanes.
+    // Roster groups are participants with a count; the parser expands them into `lanes[]`.
     roster: { ...PARTICIPANT_ENTRY, count: true },
     persona: true,
     mission: true,

package/dist/lab/lab-deps.d.ts

@@ -0,0 +1,85 @@
+import type { ScriptedBrowserSessionOptions, ScriptedBrowserSessionResult } from "../actors/scripted-browser/actor.js";
+import type { ScriptedBrowserLaunchArgs, ScriptedBrowserLike } from "../actors/scripted-browser/types.js";
+import type { CuaActorSessionOptions } from "../actors/computer-use/actor.js";
+import type { AutomaticAnalysisDeps, runAutomaticAnalysis } from "../analysis/automatic.js";
+import type { CuaLoopResult } from "../actors/computer-use/loop.js";
+import type { renderObserver } from "../observer/render.js";
+import type { TerminalCostProbe } from "../routes/terminal/types.js";
+import type { DetachedTimers } from "../substrates/detached.js";
+import type { E2BDesktopModule } from "../substrates/e2b/sdk.js";
+import type { LocalTreeArchive } from "../subject/local-tree-archive.js";
+import type { SubjectPhaseEvent } from "../subject/steps.js";
+/** The participant a computer-use subject phase belongs to, with the route's field names. */
+export interface PhaseParticipant {
+    readonly laneId: string;
+    readonly laneIndex: number;
+    readonly laneCount: number;
+}
+export interface LabDeps {
+    /** Loads the E2B SDK. Defaults to loadE2BDesktopModule. */
+    readonly desktopModule?: () => Promise<E2BDesktopModule>;
+    /** Renders the Observer. Defaults to renderObserver. */
+    readonly renderObserver?: typeof renderObserver;
+    /** The clock, in epoch milliseconds. Defaults to Date.now. */
+    readonly now?: () => number;
+    /** Clock and sleep for detached provisioning steps. */
+    readonly detachedTimers?: DetachedTimers;
+    /**
+     * Computer use and shared world: where subject-provisioning phases go in place of stderr. A
+     * computer-use phase names its participant; a shared-world plane's names none. onEvent still
+     * receives every phase.
+     */
+    readonly subjectPhaseSink?: (event: SubjectPhaseEvent, participant?: PhaseParticipant) => void;
+    /**
+     * Shared world: runs each seat's computer-use session in place of the actor's own. The planner
+     * reads whether it is set: a custom runner cannot enforce actors[0].maxOutputTokens.
+     */
+    readonly runSession?: (options: CuaActorSessionOptions) => Promise<CuaLoopResult>;
+    /**
+     * Shared world: packs a local-tree subject on the host. Defaults to createLocalTreeArchive and a
+     * read of the archive it writes. Called once per run, before the subject sandbox exists.
+     */
+    readonly packLocalTree?: (args: {
+        root: string;
+        extraExclude?: string[];
+        maxArchiveBytes?: number;
+    }) => Promise<{
+        archive: LocalTreeArchive;
+        buffer: ArrayBuffer;
+    }>;
+    /** Shared world: the background stateSeries prober's cadence in milliseconds. Defaults to 1000. */
+    readonly proberCadenceMs?: number;
+    /**
+     * Shared world, external-public plane: how long the host seat has to surface a /lobby/CODE URL
+     * before the run fails closed. Defaults to 120000, capped by execution.timeoutMs.
+     */
+    readonly handoffDeadlineMs?: number;
+    /**
+     * Shared world, external-public plane: reads a /lobby/CODE off a seat's screenshot. Defaults to
+     * the single-frame OpenAI read.
+     */
+    readonly readLobbyCodeFromFrame?: (frame: Buffer, apiKey: string) => Promise<string | undefined>;
+    /**
+     * Every route: post-run analysis in place of the real one. `run` replaces
+     * the real analysis runner, and `deps` (provider fetch, keys, clock) reach the analysis only,
+     * never a participant.
+     */
+    readonly analysis?: {
+        readonly run?: typeof runAutomaticAnalysis;
+        readonly deps?: AutomaticAnalysisDeps;
+    };
+    /** Scripted: runs one surface's session in place of the scripted-browser actor. */
+    readonly runScriptedSession?: (options: ScriptedBrowserSessionOptions) => Promise<ScriptedBrowserSessionResult>;
+    /**
+     * Scripted: launches the browser each session drives, so no browser binary is resolved. The
+     * planner reads whether it, or browserCommand, is set: a live run then needs no host browser.
+     */
+    readonly launchBrowser?: (args: ScriptedBrowserLaunchArgs) => Promise<ScriptedBrowserLike>;
+    /** Scripted: the browser binary to launch; operators use HUMANISH_BROWSER_COMMAND. */
+    readonly browserCommand?: string;
+    /**
+     * Terminal: known spend lines for the cost ledger. The planner reads whether it is set, since
+     * only a measured line can trip a positive maxUsd.
+     */
+    readonly costProbe?: TerminalCostProbe;
+}

package/dist/lab/lab-deps.js

@@ -0,0 +1,4 @@
+// Test seams: the implementations a test puts in place of the real ones. The internal runLab takes
+// them as its third argument and each route runner as `deps`; the package's runLab takes none.
+// Each field defaults to the real implementation.
+export {};

package/dist/lab/parse/actors.js

@@ -3,8 +3,9 @@ import { isReasoningEffort, reasoningEffortNames } from "../../actors/reasoning-
 import { isMaxOutputTokens } from "../../actors/output-token-limit.js";
 import { isHttpUrl } from "./subject.js";
 import { registeredComputerUseActors, registeredScriptedBrowserActors, registeredTerminalActors, } from "../routing.js";
-import { invalid, isRecord, posInt, str } from "./values.js";
-// A lane id interpolates into per-lane evidence paths (screenshots/<id>/, actors/<id>.json), so
+import { invalid, posInt, str } from "./values.js";
+import { isRecord } from "../../run/type-guards.js";
+// A participant id interpolates into its evidence paths (screenshots/<id>/, actors/<id>.json), so
 // it must be a public-safe path token, same shape as a lab id.
 export const PARTICIPANT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
 export const PARTICIPANT_ID_MAX_CHARS = 40;
@@ -138,7 +139,7 @@ function parseFocus(raw) {
     return Object.keys(focus).length > 0 ? focus : undefined;
 }
 /**
- * Parse `actors[index].roster` compact groups into concrete lanes. This is authoring sugar for
+ * Parse `actors[index].roster` compact groups into concrete `lanes[]` entries. This is authoring sugar for
  * "N users of M adapter-owned types across S surfaces"; the runtime receives only `lanes[]`.
  */
 function parseRosterGroups(raw, actorIndex) {
@@ -183,11 +184,11 @@ function parseRosterGroups(raw, actorIndex) {
 }
 /**
  * Parse `actors[index].lanes` into a fan-out roster (computer-use E2B route). Structural only:
- * each lane is `{ id?, actorType?, surface?, caseGroup?, persona?, device?, instruction?, target?,
+ * each entry is `{ id?, actorType?, surface?, caseGroup?, persona?, device?, instruction?, target?,
  * entry?, host?, reasoningEffort?, stopWhen?, dwell? }`.
- * Lane ids (when declared) must be public-safe path tokens and unique; lane grouping metadata
- * must be public-safe tokens; a lane device must be a known preset name. The
- * route-scoped cross-validation (lanes XOR count/laneFocus, device XOR raw resolution, cap 16)
+ * Participant ids (when declared) must be public-safe path tokens and unique; grouping metadata
+ * must be public-safe tokens; a device must be a known preset name. The
+ * route-scoped cross-validation (`lanes` XOR `count`/`laneFocus`, device XOR raw resolution, cap 16)
  * runs in parseLabConfig where the route is known.
  */
 function parseParticipantEntries(raw, actorIndex) {

package/dist/lab/parse/comms.js

@@ -1,4 +1,5 @@
-import { invalid, isRecord, posInt, str } from "./values.js";
+import { invalid, posInt, str } from "./values.js";
+import { isRecord } from "../../run/type-guards.js";
 // Fail-loud (never silently swallow a comms setting): a malformed `comms` block returns a parse
 // failure rather than being dropped.
 export function parseComms(raw) {
@@ -226,7 +227,7 @@ export function addressedRecipients(email) {
         ? []
         : [{ participantId: recipient.lane, address: recipient.address }]);
 }
-/** `comms.email.recipients`: which lane each captured address belongs to. */
+/** `comms.email.recipients`: which participant each captured address belongs to. */
 function parseRecipients(raw) {
     if (raw === undefined)
         return { ok: true, value: undefined };

package/dist/lab/parse/execution.js

@@ -1,7 +1,8 @@
 import { resolveAutomaticAnalysis } from "../../analysis/automatic-config.js";
 import { DEVICE_PRESET_NAMES, isDevicePresetName } from "../device-presets.js";
 import { isExactRuntimeVersion } from "../../routes/terminal/runtime.js";
-import { invalid, isRecord, nonNegNumber, posInt, str } from "./values.js";
+import { invalid, nonNegNumber, posInt, str } from "./values.js";
+import { isRecord } from "../../run/type-guards.js";
 export function parseExecution(raw) {
     if (raw === undefined) {
         return { ok: true, value: undefined };
@@ -32,7 +33,7 @@ export function parseExecution(raw) {
     }
     if (desktopResult.value)
         execution.desktop = desktopResult.value;
-    // Reuse the terminal lane's caps parser (same shape, not a fork) — a malformed budget is a hard
+    // Reuse the terminal route's caps parser (same shape, not a fork) — a malformed budget is a hard
     // error, never silently dropped (a cap that silently does nothing would be a safety lie).
     const capsResult = parseCaps(raw.caps);
     if (!capsResult.ok) {

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

@@ -2,7 +2,8 @@
 // the structural parse of `subject.state`, and subjectStateInvalidReason, the semantic check
 // parseLabConfig and the computer-use route share.
 import { containsSensitive } from "../../evidence/redaction.js";
-import { ENV_NAME_PATTERN, invalid, isRecord, posInt, str, strList } from "./values.js";
+import { ENV_NAME_PATTERN, invalid, posInt, str, strList } from "./values.js";
+import { isRecord } from "../../run/type-guards.js";
 /**
  * LITERAL non-secret subject env. Real apps need configuration before they will boot — a public base
  * URL, a transport selector, a feature flag — and none of that is secret. Routing it through

package/dist/lab/parse/subject.js

@@ -1,6 +1,7 @@
 import { normalizeExtraExcludeEntry } from "../../subject/local-tree-archive.js";
-import { ENV_NAME_PATTERN, invalid, isRecord, posInt, str, strList } from "./values.js";
+import { ENV_NAME_PATTERN, invalid, posInt, str, strList } from "./values.js";
 import { parseEnvValues, parseState, subjectStateInvalidReason } from "./subject-state.js";
+import { isRecord } from "../../run/type-guards.js";
 export function parseSubject(raw) {
     if (!isRecord(raw)) {
         return invalid("Lab `subject` is required and must be an object.");

package/dist/lab/parse/values.d.ts

@@ -2,7 +2,6 @@ import type { LabConfigParseFailure } from "../types.js";
 export declare const REPO_SLUG_PATTERN: RegExp;
 export declare const ENV_NAME_PATTERN: RegExp;
 export declare function invalid(message: string): LabConfigParseFailure;
-export declare function isRecord(value: unknown): value is Record<string, unknown>;
 export declare function str(value: unknown): string | undefined;
 export declare function optionalStr(key: string, value: unknown): Record<string, string>;
 export declare function strList(value: unknown): string[] | undefined;

package/dist/lab/parse/values.js

@@ -4,9 +4,6 @@ export const ENV_NAME_PATTERN = /^[A-Z][A-Z0-9_]*$/;
 export function invalid(message) {
     return { ok: false, error: { code: "HUMANISH_LAB_INVALID", message } };
 }
-export function isRecord(value) {
-    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
 export function str(value) {
     return typeof value === "string" && value.trim() ? value.trim() : undefined;
 }

package/dist/lab/persona-resolve.d.ts

@@ -13,7 +13,7 @@ export declare function resolveCommittedPersona(projectRoot: PreparedSelectedOut
     warnings: string[];
 }>;
 /**
- * Resolve every distinct persona id a run will use, once, before lane specs are built. Returning a
+ * Resolve every distinct persona id a run will use, once, before participant specs are built. Returning a
  * map keeps the plan builder PURE (it is exported npm surface and asserted pure by tests): the
  * async file reads happen here, and the composer only does a lookup.
  */
@@ -22,8 +22,8 @@ export declare function resolveCommittedPersonas(projectRoot: PreparedSelectedOu
     warnings: string[];
 }>;
 /**
- * Every persona id a lab config could put on a browser lane: the per-lane roster when one is
- * declared, otherwise the actor-level persona that every fan-out lane inherits.
+ * Every persona id a lab config could put on a browser participant: the roster when one is
+ * declared, otherwise the actor-level persona that every fan-out participant inherits.
  */
 export declare function labPersonaIds(config: {
     actors?: readonly Pick<LabActor, "persona" | "lanes">[];