humanish 0.107.0 → 0.109.0

package/dist/routes/computer-use/plan.js

@@ -4,18 +4,18 @@
 // values, spend-cap prices and the comms catch.
 import { resolveAutomaticAnalysis } from "../../analysis/automatic-config.js";
 import { actorRegistry, isCuaActorDescriptor, } from "../../actors/registry.js";
-import { isHttpUrl, isLoopbackUrl } from "../../lab/parse/subject.js";
-import { subjectStateInvalidReason } from "../../lab/parse/subject-state.js";
-import { brainOf, callerBrainOf, capsOf, desktopRequirements, planBase, provisionedSubject, } from "../../lab/plan-base.js";
-import { computerUseParticipants, declaredTargets } from "../../lab/plan-participants.js";
-import { MAX_CUA_LANES } from "../../lab/routing.js";
-import { cloneTargetValidationReason, cuaLaneValidationReason, desktopMediaValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, scenarioCapsValidationReason, taskProtocolValidationReason, } from "../../lab/validation.js";
-import { desktopCliProductReason } from "../../lab/composition-rules.js";
-import { isLocalBrowserLab } from "../../substrates/local/runtime-config.js";
+import { isHttpUrl, isLoopbackUrl } from "../../study/parse/subject.js";
+import { subjectStateInvalidReason } from "../../study/parse/subject-state.js";
+import { brainOf, callerBrainOf, capsOf, desktopRequirements, planBase, provisionedSubject, } from "../../study/plan-base.js";
+import { computerUseParticipants, declaredTargets } from "../../study/plan-participants.js";
+import { MAX_COMPUTER_USE_PARTICIPANTS } from "../../study/routing.js";
+import { cloneTargetValidationReason, computerUseValidationReason, desktopMediaValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, scenarioCapsValidationReason, taskProtocolValidationReason, } from "../../study/validation.js";
+import { desktopCliProductReason } from "../../study/composition-rules.js";
+import { isLocalBrowserStudy } from "../../substrates/local/runtime-config.js";
 import { boundedConcurrency, defaultSessionTimeoutMs, resolveParticipantSandboxMs, } from "./participant-runs.js";
 import { MAX_SANDBOX_MS } from "../../substrates/e2b/lifetime.js";
 import {} from "./types.js";
-/** The registered descriptor for a planned actor id; planComputerUseLab checked the registry. */
+/** The registered descriptor for a planned actor id; planComputerUseStudy checked the registry. */
 export function cuaDescriptorOf(actor) {
     const descriptor = actorRegistry[actor];
     if (!descriptor || !isCuaActorDescriptor(descriptor))
@@ -52,7 +52,7 @@ export function cuaDeclaredState(plan) {
     const { subject } = plan.runner;
     return subject.kind === "clone" || subject.kind === "local-tree" ? subject.state : undefined;
 }
-/** The URL a refused lab's result names, from its declaration: a provisioned subject's serve URL. */
+/** The URL a refused study's result names, from its declaration: a provisioned subject's serve URL. */
 export function declaredAppUrl(config) {
     const { subject } = config;
     const provisioned = subject.source === "clone" || subject.source === "local-tree";
@@ -65,15 +65,15 @@ export function plannedAppUrl(subject) {
     return "appUrl" in subject ? subject.appUrl : "";
 }
 const invalid = (message) => ({
-    code: "HUMANISH_CUA_LAB_SUBJECT_INVALID",
+    code: "HUMANISH_COMPUTER_USE_SUBJECT_INVALID",
     message,
 });
 /**
- * The first reason a computer-use lab cannot start, checked before any sandbox, key or provider
+ * The first reason a computer-use study cannot start, checked before any sandbox, key or provider
  * is touched. The parser enforces most of these too; the engine repeats them for library callers
  * that hand it a config directly. The groups run in this order, and each returns its first reason.
  */
-function cuaLabRejection(config, hasRunSession, driving, subjectRoute) {
+function cuaStudyRejection(config, hasRunSession, driving, subjectRoute) {
     return (unsupportedDeclarationReason(config, hasRunSession, driving, subjectRoute) ??
         subjectStructureReason(config, subjectRoute) ??
         entryTargetReason(config, subjectRoute) ??
@@ -110,17 +110,17 @@ function subjectStructureReason(config, subjectRoute) {
     if (cloneRoute &&
         (!serve || !subjectRepo || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(subjectRepo)))
         return invalid(!serve
-            ? "clone subjects on the computer-use route require `subject.serve` (start + url) — the lab serves the app in-sandbox."
+            ? "A clone subject on the computer-use route needs `subject.serve` (start and url): humanish starts the app in the sandbox before the participant opens it."
             : `subject.repos[0] must be an owner/repo slug (got "${subjectRepo ?? ""}").`);
-    // A library caller that skips parseLabConfig gets the same fail-closed shape the parser
+    // A library caller that skips parseStudy gets the same fail-closed shape the parser
     // enforces, naming which requirement is missing.
     if (localTreeRoute && (!serve || config.execution?.target !== "e2b-desktop"))
         return invalid(!serve
-            ? "local-tree subjects on the computer-use route require `subject.serve` (start + url): the lab packs and serves the working tree in-sandbox."
+            ? "local-tree subjects on the computer-use route require `subject.serve` (start + url): humanish packs and serves the working tree in the sandbox."
             : "local-tree subjects require `execution.target: e2b-desktop`: the packed working tree is provisioned and served inside a hosted desktop sandbox.");
     if (config.subject.state) {
         const stateReason = !provisionedRoute
-            ? "`subject.state` applies only to clone subjects or local-tree subjects (the lab seeds the state it serves)."
+            ? "`subject.state` applies only to clone subjects or local-tree subjects (humanish seeds the state it serves)."
             : subjectStateInvalidReason(config.subject.state, config.subject.env);
         if (stateReason)
             return invalid(stateReason);
@@ -146,7 +146,7 @@ function entryTargetReason(config, subjectRoute) {
     if (entryTargetSafe)
         return undefined;
     return {
-        code: "HUMANISH_CUA_LAB_SUBJECT_UNSAFE",
+        code: "HUMANISH_COMPUTER_USE_SUBJECT_UNSAFE",
         message: provisionedRoute || localAppSubject || !allowPublicTargets
             ? "subject.appUrl and any actors[0].lanes[].target entries must be loopback (127.0.0.1 or localhost) unless policies.allowPublicTargets is set for an app-url subject."
             : "subject.appUrl and actors[0].lanes[].target entries must be valid http(s) URLs.",
@@ -158,14 +158,14 @@ function driverReason(driving, { localAppSubject, inProcessRoute }) {
     // and would fail closed against an executor that returns no screenshot.
     if (driving.inProcess && !driving.createProvider)
         return {
-            code: "HUMANISH_CUA_LAB_EXECUTOR_NO_PROVIDER",
-            message: "RunLabOptions.inProcess requires RunLabOptions.createProvider — a state-driven executor returns no screenshot, so it must be paired with a NON-vision provider (the default OpenAI computer-use provider is vision-based and would fail closed).",
+            code: "HUMANISH_COMPUTER_USE_EXECUTOR_NO_PROVIDER",
+            message: "RunLabOptions.inProcess needs RunLabOptions.createProvider: an in-process executor returns no screenshot, so it needs a provider that does not read images. The default OpenAI computer-use provider reads screenshots and would stop the session.",
         };
     // There is no built-in in-process driver for a local app.
     if (localAppSubject && !inProcessRoute)
         return {
-            code: "HUMANISH_CUA_LAB_LOCAL_APP_NO_EXECUTOR",
-            message: "subject.source: local-app has no built-in driver. Supply one through runLab(config, { inProcess: { executor }, createProvider }); a state-driven executor needs a non-vision provider.",
+            code: "HUMANISH_COMPUTER_USE_LOCAL_APP_NO_EXECUTOR",
+            message: "subject.source: local-app has no built-in driver. Supply one through runStudy(config, { inProcess: { executor }, createProvider }); a state-driven executor needs a non-vision provider.",
         };
     return undefined;
 }
@@ -173,10 +173,10 @@ function driverReason(driving, { localAppSubject, inProcessRoute }) {
 function rosterShapeReason(config) {
     // `lanes` XOR `count`/`laneFocus`, device XOR raw resolution, cap, unique ids,
     // allowPublicTargets with more than one participant, clone.fanout.
-    const fanoutReason = cuaLaneValidationReason(config);
+    const fanoutReason = computerUseValidationReason(config);
     if (fanoutReason)
-        return { code: "HUMANISH_CUA_LAB_FANOUT_INVALID", message: fanoutReason };
-    // The sandbox deadline is derived from the session budget, so a lab can ask for a session that
+        return { code: "HUMANISH_COMPUTER_USE_FANOUT_INVALID", message: fanoutReason };
+    // The sandbox deadline is derived from the session budget, so a study can ask for a session that
     // cannot legally be provisioned. Show the arithmetic: the provider's own error names a limit
     // but not which knob produced it.
     const derivedSandboxMs = resolveParticipantSandboxMs(config);
@@ -192,10 +192,10 @@ function rerunPlan({ sourceRunId, participantIds, }) {
     return { sourceRunId, ...(participantIds === undefined ? {} : { participantIds }) };
 }
 /**
- * Plan a computer-use lab. It is called for any config handed to the computer-use runner, not only
+ * Plan a computer-use study. It is called for any config handed to the computer-use runner, not only
  * one routeOf sends here, so a config for another route gets this route's refusal.
  */
-export function planComputerUseLab(config, input) {
+export function planComputerUseStudy(config, input) {
     const hasRunSession = input.hasRunSession === true;
     const driving = input.driving ?? { inProcess: false, createProvider: false };
     const refuse = (stage, code, message, actor) => ({
@@ -210,40 +210,40 @@ export function planComputerUseLab(config, input) {
     });
     const analysis = resolveAutomaticAnalysis(config.review?.analysis);
     if (!analysis.ok)
-        return refuse("before-scope", "HUMANISH_LAB_ANALYSIS_INVALID", analysis.message);
+        return refuse("before-scope", "HUMANISH_STUDY_ANALYSIS_INVALID", analysis.message);
     const tasksReason = taskProtocolValidationReason(config, true);
     if (tasksReason)
-        return refuse("before-scope", "HUMANISH_LAB_TASKS_UNSUPPORTED", tasksReason);
+        return refuse("before-scope", "HUMANISH_STUDY_TASKS_UNSUPPORTED", tasksReason);
     // The parser checks the actor too; a library caller skips the parser.
     const actorType = config.actors[0]?.type ?? "";
     const descriptor = actorRegistry[actorType];
     if (!descriptor || !isCuaActorDescriptor(descriptor))
-        return refuse("in-scope", "HUMANISH_CUA_LAB_ACTOR_UNSUPPORTED", `actors[0].type "${actorType}" is not a registered computer-use actor.`);
+        return refuse("in-scope", "HUMANISH_COMPUTER_USE_ACTOR_UNSUPPORTED", `actors[0].type "${actorType}" is not a registered computer-use actor.`);
     const actor = descriptor.id;
-    const rejection = cuaLabRejection(config, hasRunSession, driving, declaredSubjectRoute(config, driving));
+    const rejection = cuaStudyRejection(config, hasRunSession, driving, declaredSubjectRoute(config, driving));
     if (rejection)
         return refuse("in-scope", rejection.code, rejection.message, actor);
-    // A shared world runs every seat against one app; this route would run them as separate participants.
-    // It comes after the rules above, so a shared-world config that breaks one of them, which runLab
-    // sends here, still gets that rule's message.
+    // A shared world runs every participant against one app; this route would run them as separate
+    // participants. It comes after the rules above, so a shared-world config that breaks one of them,
+    // which runStudyWith sends here, still gets that rule's message.
     if (config.subject.topology === "shared-world")
-        return refuse("in-scope", "HUMANISH_CUA_LAB_SUBJECT_INVALID", "subject.topology: shared-world labs run every participant against one shared app on the shared-world route; runCuaActorLab runs independent participants. Run the lab with runLab or runConcurrentSharedWorld.", actor);
+        return refuse("in-scope", "HUMANISH_COMPUTER_USE_SUBJECT_INVALID", "subject.topology: shared-world studies run every participant against one shared app on the shared-world route; this route runs independent participants. Run the study with runStudy or runConcurrentSharedWorld.", actor);
     // The in-process route drives subject.appUrl on this machine and creates no desktop, so it would
-    // skip the subject a clone, local-tree or desktop-cli lab declares.
+    // skip the subject a clone, local-tree or desktop-cli study declares.
     const source = config.subject.source;
     if (driving.inProcess &&
         (source === "clone" || source === "local-tree" || source === "desktop-cli"))
-        return refuse("in-scope", "HUMANISH_CUA_LAB_SUBJECT_INVALID", `RunLabOptions.inProcess drives subject.appUrl in this process, and a ${source} subject needs the hosted desktop the in-process route never creates. Use an app-url or local-app subject with inProcess, or remove inProcess to run on a hosted desktop.`, actor);
+        return refuse("in-scope", "HUMANISH_COMPUTER_USE_SUBJECT_INVALID", `RunLabOptions.inProcess drives subject.appUrl in this process, and a ${source} subject needs the hosted desktop the in-process route never creates. Use an app-url or local-app subject with inProcess, or remove inProcess to run on a hosted desktop.`, actor);
     // The parser's rule; without a product the desktop study fails later.
     const productReason = desktopCliProductReason(config);
     if (productReason)
-        return refuse("in-scope", "HUMANISH_CUA_LAB_SUBJECT_INVALID", productReason, actor);
+        return refuse("in-scope", "HUMANISH_COMPUTER_USE_SUBJECT_INVALID", productReason, actor);
     const participants = computerUseParticipants(config, input.countOverride);
-    if (participants.length > MAX_CUA_LANES)
-        return refuse("after-personas", "HUMANISH_CUA_LAB_FANOUT_INVALID", `Computer-use fan-out is capped at ${MAX_CUA_LANES} participants (resolved ${participants.length}); N concurrent paid desktops is real spend.`, actor);
+    if (participants.length > MAX_COMPUTER_USE_PARTICIPANTS)
+        return refuse("after-personas", "HUMANISH_COMPUTER_USE_FANOUT_INVALID", `Computer-use fan-out is capped at ${MAX_COMPUTER_USE_PARTICIPANTS} participants (resolved ${participants.length}); N concurrent paid desktops is real spend.`, actor);
     const [first, ...rest] = participants;
     if (driving.inProcess && rest.length > 0)
-        return refuse("after-personas", "HUMANISH_CUA_LAB_FANOUT_INVALID", "Fan-out to more than one participant is not supported on the in-process route (RunLabOptions.inProcess): fan-out provisions one independent E2B desktop per participant, which the in-process route deliberately skips. Run a single in-process participant, or fan out on the E2B route.", actor);
+        return refuse("after-personas", "HUMANISH_COMPUTER_USE_FANOUT_INVALID", "Fan-out to more than one participant is not supported on the in-process route (RunLabOptions.inProcess): fan-out provisions one independent E2B desktop per participant, which the in-process route deliberately skips. Run a single in-process participant, or fan out on the E2B route.", actor);
     if (first === undefined)
         throw new Error("computerUseParticipants returned no participant");
     const appUrl = config.subject.appUrl ?? "";
@@ -267,7 +267,7 @@ export function planComputerUseLab(config, input) {
             participants: [first],
             subject: source === "local-app" ? { kind: "local-app", appUrl } : appUrlSubject,
         }
-        : isLocalBrowserLab(config)
+        : isLocalBrowserStudy(config)
             ? { desktop: "local-vm", brain, participants: [first, ...rest], subject: appUrlSubject }
             : { desktop: "e2b-desktop", brain, participants: [first, ...rest], subject: hosted };
     const declared = config.execution?.concurrency;

package/dist/routes/computer-use/preflight.d.ts

@@ -1,6 +1,6 @@
-import type { Brain, ComputerUsePlan } from "../../lab/plan-types.js";
-import type { LabCommsExternal } from "../../lab/types.js";
-import type { CuaActorLabErrorCode } from "./types.js";
+import type { Brain, ComputerUsePlan } from "../../study/plan-types.js";
+import type { StudyCommsExternal } from "../../study/types.js";
+import type { CuaActorStudyErrorCode } from "./types.js";
 /**
  * The first reason a live computer-use run cannot start on this machine: missing keys, a missing
  * or signed-out local agent, missing subject env, a spend cap with no price, or an unreachable
@@ -14,8 +14,8 @@ export declare function liveCuaRejection(args: {
     env: Record<string, string | undefined>;
     /** The plan's requirements: which keys and subject env names this run needs. */
     requirements: ComputerUsePlan["requirements"];
-    externalCommsConfig: LabCommsExternal | undefined;
+    externalCommsConfig: StudyCommsExternal | undefined;
 }): Promise<{
-    code: CuaActorLabErrorCode;
+    code: CuaActorStudyErrorCode;
     message: string;
 } | undefined>;

package/dist/routes/computer-use/preflight.js

@@ -1,17 +1,17 @@
-import { pricedModel } from "../../lab/plan-base.js";
-import { missingKeys, missingSubjectEnv } from "../../lab/requirements.js";
+import { pricedModel } from "../../study/plan-base.js";
+import { missingKeys, missingSubjectEnv } from "../../study/requirements.js";
 import { detectLocalAgents } from "../../actors/local-agent/cli.js";
 import { localAgentRefusal } from "../../actors/local-agent/readiness.js";
 import { describeMissingKeys } from "../../keys/key-resolution.js";
 import { catchTokenOf, catchTokenRefusal } from "../../comms/external-evidence.js";
 import { externalCatchHealthy } from "../../comms/sandbox-catch.js";
-import { MODEL_RATES } from "../../run/pricing.js";
+import { MODEL_RATES, unpricedCapMessage } from "../../run/pricing.js";
 /** The computer-use code for each local-agent refusal; shared-world keeps the same kinds. */
 const LOCAL_AGENT_REFUSAL_CODES = {
-    "agent-missing": "HUMANISH_CUA_LAB_AGENT_MISSING",
-    "signin-required": "HUMANISH_CUA_LAB_AGENT_SIGNIN_REQUIRED",
-    unsupported: "HUMANISH_CUA_LAB_ACTOR_UNSUPPORTED",
-    "unpriced-cap": "HUMANISH_CUA_LAB_UNPRICED_CAP",
+    "agent-missing": "HUMANISH_COMPUTER_USE_AGENT_MISSING",
+    "signin-required": "HUMANISH_COMPUTER_USE_AGENT_SIGNIN_REQUIRED",
+    unsupported: "HUMANISH_COMPUTER_USE_ACTOR_UNSUPPORTED",
+    "unpriced-cap": "HUMANISH_COMPUTER_USE_UNPRICED_CAP",
 };
 /**
  * The first reason a live computer-use run cannot start on this machine: missing keys, a missing
@@ -27,7 +27,7 @@ export async function liveCuaRejection(args) {
     const missing = missingKeys(requirements, env);
     if (missing.length > 0) {
         // The moment someone new actually hits the wall. If a signed-in coding agent is sitting
-        // right there, say so HERE rather than making them go and find an API key — that detour is
+        // right there, say so here rather than making them go and find an API key; that detour is
         // where most people trying humanish stop.
         const suggestion = missing.includes("OPENAI_API_KEY")
             ? await (async () => {
@@ -35,17 +35,17 @@ export async function liveCuaRejection(args) {
                 return ready.length === 0
                     ? ""
                     : ` ${ready.map((agent) => agent.label).join(" and ")} reports authenticated on this machine` +
-                        ` — set actors[0].type: local-agent to use ${ready.length === 1 ? "it" : "one"} instead of a key.`;
+                        `. Set actors[0].type: local-agent to use ${ready.length === 1 ? "it" : "one"} instead of a key.`;
             })()
             : "";
         return {
-            code: "HUMANISH_CUA_LAB_KEYS_MISSING",
-            message: `Live computer-use labs need ${missing.join(" and ")} in the environment (values are never persisted). ${describeMissingKeys(missing, env)}${suggestion}`,
+            code: "HUMANISH_COMPUTER_USE_KEYS_MISSING",
+            message: `Live computer-use studies need ${missing.join(" and ")} in the environment (values are never persisted). ${describeMissingKeys(missing, env)}${suggestion}`,
         };
     }
-    // A caller's createProvider makes the brain `caller`, so only the lab's own local agent is checked.
+    // A caller's createProvider makes the brain `caller`, so only the study's own local agent is checked.
     if (localAgent) {
-        // Refuse HERE, before a sandbox exists. "codex is not installed" discovered after the
+        // Refuse here, before a sandbox exists. "codex is not installed" discovered after the
         // machine is paid for is the same information delivered at the worst possible moment.
         const refusal = await localAgentRefusal({ agent: localAgent, env, caps });
         if (refusal)
@@ -54,38 +54,38 @@ export async function liveCuaRejection(args) {
     const unsetSubjectEnv = missingSubjectEnv(requirements, env);
     if (unsetSubjectEnv.length > 0) {
         return {
-            code: "HUMANISH_CUA_LAB_SUBJECT_ENV_MISSING",
+            code: "HUMANISH_COMPUTER_USE_SUBJECT_ENV_MISSING",
             message: `subject.env declares ${unsetSubjectEnv.join(", ")} but the environment does not provide ${unsetSubjectEnv.length === 1 ? "it" : "them"} (pass via --env-file; values are never persisted).`,
         };
     }
-    // FAIL-CLOSED CAP TENSION (discipline #3): a maxUsd cap needs a MEASURABLE per-turn estimate.
+    // Fail-closed cap: a maxUsd cap needs a measurable per-turn estimate.
     // If the operator set execution.caps.maxUsd but src/run/pricing.ts has no rate for the resolved
-    // model, the loop could not enforce the cap — and silently running uncapped would break the
-    // runaway-retry protection. Refuse at PREFLIGHT (before any sandbox/spend) rather than run
-    // uncapped: an unenforceable cap is more dangerous than none. The operator adds a rate to
-    // src/run/pricing.ts (the honest place) or removes the cap.
+    // model, the loop could not enforce the cap, and silently running uncapped would break the
+    // runaway-retry protection. Refuse at preflight (before any sandbox/spend) rather than run
+    // uncapped: an unenforceable cap is more dangerous than none. The operator picks a priced model
+    // or removes the cap; a source checkout can also add a rate to src/run/pricing.ts.
     if (caps.maxUsd !== undefined || caps.maxTotalUsd !== undefined) {
         const model = pricedModel(brain);
         const capModelId = model.trim().toLowerCase();
         if (!MODEL_RATES[capModelId]) {
             return {
-                code: "HUMANISH_CUA_LAB_UNPRICED_CAP",
-                message: `execution.caps declares a spend cap (maxUsd/maxTotalUsd) but src/run/pricing.ts has no rate for model "${model}"; add a rate or remove the cap — an unenforceable cap is refused rather than run uncapped.`,
+                code: "HUMANISH_COMPUTER_USE_UNPRICED_CAP",
+                message: unpricedCapMessage(model),
             };
         }
     }
-    // Adopter-hosted comms catch (#380): fail closed BEFORE any sandbox is created — a comms lab
+    // Adopter-hosted comms catch: fail closed before any sandbox is created, because a comms study
     // whose catch is unreachable collects nothing while every participant still spends. The probe asserts
-    // OUR service marker in /health, so an adopter's proxy answering 200 for everything cannot
+    // humanish's own service marker in /health, so an adopter's proxy answering 200 for everything cannot
     // pass for a catch.
     const tokenRefusal = externalCommsConfig === undefined
         ? undefined
         : catchTokenRefusal(catchTokenOf(externalCommsConfig, env));
     if (tokenRefusal !== undefined)
-        return { code: "HUMANISH_CUA_LAB_COMMS_TOKEN_INVALID", message: tokenRefusal };
+        return { code: "HUMANISH_COMPUTER_USE_COMMS_TOKEN_INVALID", message: tokenRefusal };
     if (externalCommsConfig && !(await externalCatchHealthy(externalCommsConfig))) {
         return {
-            code: "HUMANISH_CUA_LAB_COMMS_CATCH_UNREACHABLE",
+            code: "HUMANISH_COMPUTER_USE_COMMS_CATCH_UNREACHABLE",
             message: "The external comms catch or inbox is unreachable or incompatible (GET /health must identify humanish-comms-catch and advertise recipient-inbox-v1). Update humanish on the catch host and restart it with `humanish comms catch` on that host, or drop comms.email to run without the inbox funnel.",
         };
     }

package/dist/routes/computer-use/rerun-selection.d.ts

@@ -2,7 +2,7 @@ import { type RunRerunLineage } from "../../run/bundle.js";
 import type { CuaParticipantPlan, DesktopParticipantRun } from "./types.js";
 export declare function resolveCuaRerunSelection(args: {
     cwd: string;
-    labId: string;
+    studyId: string;
     sandboxMs: number;
     sourceRunId: string;
     participantIds?: string[];

package/dist/routes/computer-use/rerun-selection.js

@@ -3,6 +3,7 @@
 import {} from "../../run/bundle.js";
 import { loadRunBundle } from "../../run/locate.js";
 import {} from "../../run/streams.js";
+import { plural } from "../../run/text.js";
 export async function resolveCuaRerunSelection(args) {
     const source = await loadRunBundle(args.cwd, args.sourceRunId);
     if (!source) {
@@ -36,14 +37,14 @@ export async function resolveCuaRerunSelection(args) {
     if (selectedIds.length === 0) {
         return {
             ok: false,
-            message: `source run ${bundle.runId} has no failed, blocked, timed-out, or hollow participants to rerun.`,
+            message: `source run ${bundle.runId} has no participant to rerun: none failed, was blocked, timed out or ended without engaging.`,
         };
     }
     const missingPrior = selectedIds.filter((id) => !priorById.has(id));
     if (missingPrior.length > 0) {
         return {
             ok: false,
-            message: `selected participant id(s) were not present in source run ${bundle.runId}: ${missingPrior.join(", ")}`,
+            message: `${plural(missingPrior.length, "selected participant id")} ${missingPrior.length === 1 ? "was" : "were"} not present in source run ${bundle.runId}: ${missingPrior.join(", ")}`,
         };
     }
     const specsById = new Map(args.participantRuns.map((spec) => [spec.planned.id, spec]));
@@ -51,7 +52,7 @@ export async function resolveCuaRerunSelection(args) {
     if (missingCurrent.length > 0) {
         return {
             ok: false,
-            message: `selected participant id(s) are not present in the current lab config ${args.labId}: ${missingCurrent.join(", ")}`,
+            message: `${plural(missingCurrent.length, "selected participant id")} ${missingCurrent.length === 1 ? "is" : "are"} not present in the current study file ${args.studyId}: ${missingCurrent.join(", ")}`,
         };
     }
     const selectedSpecs = selectedIds.map((id) => specsById.get(id));

package/dist/routes/computer-use/result.d.ts

@@ -1,7 +1,7 @@
-import type { runLabParticipants } from "./live-phase.js";
+import type { runStudyParticipants } from "./live-phase.js";
 import type { CuaFinishFacts, CuaRunSetup } from "./setup.js";
-import { type CuaActorLabResult } from "./types.js";
+import { type CuaActorStudyResult } from "./types.js";
 /** Builds and publishes the final bundle, runs the adapter hooks, renders the Observer and returns the result. */
-export declare function finishCuaRun(setup: CuaRunSetup, finish: CuaFinishFacts, ran: Extract<Awaited<ReturnType<typeof runLabParticipants>>, {
+export declare function finishCuaRun(setup: CuaRunSetup, finish: CuaFinishFacts, ran: Extract<Awaited<ReturnType<typeof runStudyParticipants>>, {
     ok: true;
-}>): Promise<CuaActorLabResult>;
+}>): Promise<CuaActorStudyResult>;

package/dist/routes/computer-use/result.js

@@ -1,4 +1,4 @@
-import { adapterScoreFailureMessage, applyBrowserScorer } from "../../lab/adapter-extension.js";
+import { adapterScoreFailureMessage, applyBrowserScorer } from "../../study/adapter-extension.js";
 import { redactText } from "../../evidence/redaction.js";
 import { round6 } from "../../run/pricing.js";
 import { foldScorerFailures, judgeExecution, OUTCOME_POLICIES, participantHarnessFailed, resultOk, } from "../../run/judge.js";
@@ -7,8 +7,10 @@ import { summarizeCuaDiagnostics } from "./diagnostics.js";
 import { toParticipantResult } from "./participant-execution.js";
 import { buildCuaRunBundle, judgeComputerUseRun } from "./bundle.js";
 import { aggregateCuaSubject, projectParticipantSubjects, subjectProvenanceArg, } from "./subject-projection.js";
-import { CUA_ACTOR_LAB_SCHEMA, CUA_FANOUT_STRATEGY, participantSubjectEnv, } from "./types.js";
+import { CUA_FANOUT_STRATEGY, participantSubjectEnv, } from "./types.js";
 import { plannedAppUrl } from "./plan.js";
+import { studyResultIdentity } from "../../run/study-result.js";
+import { plural } from "../../run/text.js";
 /** Aggregate participant counts for the result projection. */
 function buildParticipantSummary(outcomes, participantCount, participantPlan, dryRun) {
     if (dryRun || !outcomes) {
@@ -51,12 +53,12 @@ function buildParticipantSummary(outcomes, participantCount, participantPlan, dr
     };
 }
 /**
- * The computer-use lab result for a finished run. The run passes only when the Observer rendered,
+ * The computer-use study result for a finished run. The run passes only when the Observer rendered,
  * every participant passed (dry-run participants pass as contracts), and no adapter score or declared scorer
  * verdict failed; otherwise the error names the first reason.
  */
-function cuaLabResult(args) {
-    const { labId, cwd, runId, appUrl, dryRun, participantRuns, outcomes, subjects, aggregateSubject, participantPlan, rerunLineage, bundle, observer, receivingWarnings, aggregateWarnings, adapterWarnings, } = args;
+function cuaStudyResult(args) {
+    const { studyId, cwd, runId, appUrl, dryRun, participantRuns, outcomes, subjects, aggregateSubject, participantPlan, rerunLineage, bundle, observer, receivingWarnings, aggregateWarnings, adapterWarnings, } = args;
     const participantCount = participantRuns.length;
     // Participant-level pass: dry-run participants are contract-ok; live ones need a passed,
     // engaged session.
@@ -83,19 +85,19 @@ function cuaLabResult(args) {
         if (ok)
             return undefined;
         if (adapterFailure !== undefined) {
-            return { code: "HUMANISH_CUA_LAB_FAILED", message: adapterFailure };
+            return { code: "HUMANISH_COMPUTER_USE_FAILED", message: adapterFailure };
         }
         if (participantCount === 1) {
             const outcome = firstOutcome;
             return {
-                code: outcome?.failureCode ?? "HUMANISH_CUA_LAB_FAILED",
+                code: outcome?.failureCode ?? "HUMANISH_COMPUTER_USE_FAILED",
                 message: outcome?.sessionError ??
                     outcome?.providerCleanupError ??
                     outcome?.providerPolicyError ??
                     (outcome?.noEngagement
                         ? "Actor took no actions and produced no message (likely a blank/still-loading screen); not a credible goal_satisfied."
                         : // The participant result (toParticipantResult) named this refusal; the N=1 envelope fell through to
-                            // "did not produce a terminal session", which is false — it produced one and refused it.
+                            // "did not produce a terminal session", which is false: it produced one and refused it.
                             outcome?.selfReportedBlocker
                                 ? "Actor reported goal_satisfied while its final message described a blocker or asked for missing instructions; not a credible pass."
                                 : observer.ok
@@ -103,25 +105,24 @@ function cuaLabResult(args) {
                                         ? `Computer-use session ended with a harness error: ${outcome.session.reason}`
                                         : outcome?.session?.status !== "passed"
                                             ? `Computer-use session ended with ${outcome?.session?.status ?? "unknown"}: ${outcome?.session?.reason ?? "no terminal reason"}`
-                                            : "Computer-use lab did not produce a terminal session."
-                                    : (observer.error?.message ?? "Observer failed for the computer-use lab run.")),
+                                            : "The computer-use run did not produce a terminal session."
+                                    : (observer.error?.message ?? "Observer failed for the computer-use run.")),
             };
         }
         const failing = (outcomes ?? []).find((outcome) => !participantOk(outcome));
-        const geometryFailure = (outcomes ?? []).find((outcome) => outcome.failureCode === "HUMANISH_CUA_LAB_DEVICE_GEOMETRY");
-        const code = geometryFailure?.failureCode ?? "HUMANISH_CUA_LAB_FAILED";
+        const geometryFailure = (outcomes ?? []).find((outcome) => outcome.failureCode === "HUMANISH_COMPUTER_USE_DEVICE_GEOMETRY");
+        const code = geometryFailure?.failureCode ?? "HUMANISH_COMPUTER_USE_FAILED";
         return {
             code,
             message: observer.ok
-                ? `Fan-out run failed: ${summary.passed}/${participantCount} participant(s) passed (${summary.skipped} skipped, ${summary.harnessErrors} harness error(s), ${summary.hollow} hollow)${failing?.sessionError !== undefined ? `; first failure: ${failing.sessionError}` : failing === undefined && args.execution.failures[0] !== undefined ? `; ${args.execution.failures[0].message}` : ""}.`
+                ? `Fan-out run failed: ${summary.passed}/${plural(participantCount, "participant")} passed (${summary.skipped} skipped, ${plural(summary.harnessErrors, "harness error")}, ${summary.hollow} without engagement)${failing?.sessionError !== undefined ? `; first failure: ${failing.sessionError}` : failing === undefined && args.execution.failures[0] !== undefined ? `; ${args.execution.failures[0].message}` : ""}.`
                 : (observer.error?.message ?? "Observer failed for the computer-use fan-out run."),
         };
     })();
     return {
-        schema: CUA_ACTOR_LAB_SCHEMA,
+        ...studyResultIdentity("computer-use", studyId),
         ok,
         cwd,
-        labId,
         actor: args.actorId,
         appUrl,
         dryRun,
@@ -198,7 +199,7 @@ function computerUseExecutionFailures(outcomes, observer, runId) {
             : [
                 {
                     kind: "evidence",
-                    message: observer.error?.message ?? "Observer failed for the computer-use lab run.",
+                    message: observer.error?.message ?? "Observer failed for the computer-use run.",
                 },
             ]),
     ];
@@ -214,7 +215,7 @@ function participantCapWarning(caps, participantCount) {
         return undefined;
     if (caps.maxTotalUsd !== undefined)
         return undefined;
-    return `execution.caps.maxUsd ($${capUsd}) is a PER-PARTICIPANT cap; ${participantCount} participants may spend up to ${participantCount} × $${capUsd} (~$${round6(capUsd * participantCount)} total) before any participant aborts. Set execution.caps.maxTotalUsd for a shared study budget.`;
+    return `execution.caps.maxUsd ($${capUsd}) caps each participant, so ${participantCount} participants may spend up to ${participantCount} × $${capUsd} (about $${round6(capUsd * participantCount)}) before any of them stops. Set execution.caps.maxTotalUsd for one budget across the study.`;
 }
 /** Builds and publishes the final bundle, runs the adapter hooks, renders the Observer and returns the result. */
 export async function finishCuaRun(setup, finish, ran) {
@@ -227,7 +228,7 @@ export async function finishCuaRun(setup, finish, ran) {
     const { runId } = run;
     const participantCount = participantRuns.length;
     const { outcomes, failFastReason, receiving, receivingWarnings, externalCommsWarnings } = ran;
-    // Per-participant subject projections (invariant 5).
+    // Per-participant subject projections.
     const subjects = projectParticipantSubjects({ ...subjectArgs, outcomes, dryRun });
     const aggregate = aggregateCuaSubject({ subjects, outcomes, participantCount, dryRun });
     const aggregateSubject = aggregate.subject;
@@ -256,7 +257,7 @@ export async function finishCuaRun(setup, finish, ran) {
         context: {
             bundle,
             runDir: run.paths.physicalRunRoot,
-            labId: plan.labId,
+            studyId: plan.studyId,
             runId,
             actor: descriptor.id,
             route: "computer-use",
@@ -275,8 +276,8 @@ export async function finishCuaRun(setup, finish, ran) {
     const observer = await finished.renderObserver();
     streams.attachFinal(observer);
     const execution = judgeExecution(computerUseExecutionFailures(outcomes, observer, runId), OUTCOME_POLICIES["computer-use"]);
-    const result = cuaLabResult({
-        labId: plan.labId,
+    const result = cuaStudyResult({
+        studyId: plan.studyId,
         cwd,
         runId,
         actorId: descriptor.id,

package/dist/routes/computer-use/route.d.ts

@@ -1,27 +1,28 @@
-import type { ComputerUsePlan } from "../../lab/plan-types.js";
-import type { AdmittedPlan } from "../../run-lab.js";
-import type { LabConfig } from "../../lab/types.js";
+import type { ComputerUsePlan } from "../../study/plan-types.js";
+import type { AdmittedPlan } from "../../run-study.js";
+import type { StudyConfig } from "../../study/types.js";
 import { type ComputerUseRefusal } from "./plan.js";
-import { type ComputerUseRunInput, type CuaActorLabResult, type RunCuaActorLabOptions } from "./types.js";
+import { type ComputerUseRunInput, type CuaActorStudyResult, type RunCuaActorStudyOptions } from "./types.js";
 /**
- * The library entry for a computer-use lab. It plans the config with planComputerUseLab and runs
+ * Plans and runs a computer-use study in one call. It is not exported from src/index.ts; tests call
+ * it. It plans the config with planComputerUseStudy and runs
  * the plan with runComputerUsePlan, whose run scope and withTransientCommsSecrets wrapper cover the
  * run and its analysis.
  */
-export declare function runCuaActorLab(options: RunCuaActorLabOptions): Promise<CuaActorLabResult>;
+export declare function runCuaActorStudy(options: RunCuaActorStudyOptions): Promise<CuaActorStudyResult>;
 /**
- * A refused computer-use lab's result, at the refusal's stage: a before-scope refusal has its own
+ * A refused computer-use study's result, at the refusal's stage: a before-scope refusal has its own
  * envelope and no analysis record; the others come after the cwd checks, and the participant cap after
  * the personas are read.
  */
-export declare function computerUseLabRefusal(options: RunCuaActorLabOptions, refusal: ComputerUseRefusal): Promise<CuaActorLabResult>;
+export declare function computerUseStudyRefusal(options: RunCuaActorStudyOptions, refusal: ComputerUseRefusal): Promise<CuaActorStudyResult>;
 /**
- * runLab's step for a computer-use plan. It runs the plan's local checks (admitCuaRun: the
+ * runStudyWith's step for a computer-use plan. It runs the plan's local checks (admitCuaRun: the
  * participants, the preflight plan, the keys, the local agent, subject env and caps, and the
  * local-tree archive) before any run scope opens, so the CLI can present their refusal before it
  * loads a declared scorer, and returns the run that continues from them with that scorer.
  */
-export declare function admitComputerUsePlan(plan: ComputerUsePlan, input: ComputerUseRunInput, config: LabConfig): Promise<AdmittedPlan<"computer-use">>;
+export declare function admitComputerUsePlan(plan: ComputerUsePlan, input: ComputerUseRunInput, config: StudyConfig): Promise<AdmittedPlan<"computer-use">>;
 /**
  * Run a computer-use plan: its local checks, then the run. The run scope in runAdmittedCuaRun
  * finalizes any status record the run opened, on every exit, so a test or library caller does not
@@ -29,4 +30,4 @@ export declare function admitComputerUsePlan(plan: ComputerUsePlan, input: Compu
  * ENOTEMPTY). Participants, the brain, the subject, the caps and the residual config come from the
  * plan. `config` is what the caller's createProvider and inProcess executor receive.
  */
-export declare function runComputerUsePlan(plan: ComputerUsePlan, input: ComputerUseRunInput, config: LabConfig): Promise<CuaActorLabResult>;
+export declare function runComputerUsePlan(plan: ComputerUsePlan, input: ComputerUseRunInput, config: StudyConfig): Promise<CuaActorStudyResult>;