humanish 0.107.0 → 0.109.0

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

@@ -10,23 +10,23 @@ import type { AutomaticAnalysisRefusal } from "../../analysis/job.js";
 import { type CuaDiagnostics } from "./diagnostics.js";
 import type { ActorCompletionReason, ActorStatus, ActorStopCause, ActorTokenUsage, ActorTraceItem } from "../../actors/contract.js";
 import { type CuaActorDescriptor } from "../../actors/registry.js";
-import type { LabDeps, PhaseParticipant } from "../../lab/lab-deps.js";
-import type { LabEvent, ParticipantRef } from "../../lab/run-lab-events.js";
-import type { InProcessDriver, ProviderFactory, RunLabHomes } from "../../lab/run-lab-homes.js";
-import { type BrowserScorer } from "../../lab/adapter-extension.js";
+import type { StudyDeps } from "../../study/study-deps.js";
+import type { StudyEvent, ParticipantRef } from "../../study/run-study-events.js";
+import type { InProcessDriver, ProviderFactory, RunStudyHomes } from "../../study/run-study-homes.js";
+import { type BrowserScorer } from "../../study/adapter-extension.js";
 import type { CuaActorSessionOptions } from "../../actors/computer-use/actor.js";
 import { type E2BDesktopModule } from "../../substrates/e2b/sdk.js";
 import { type DesktopResourceObservation } from "../../substrates/e2b/desktop-resources.js";
 import { type DetachedTimers } from "../../substrates/detached.js";
-import type { Brain, ComputerUsePlan, ComputerUseRunner, ResidualConfig } from "../../lab/plan-types.js";
-import { type LabCommsEmail, type LabConfig } from "../../lab/types.js";
+import type { Brain, ComputerUsePlan, ComputerUseRunner, ResidualConfig } from "../../study/plan-types.js";
+import { type StudyCommsEmail, type StudyConfig } from "../../study/types.js";
 import { type ObserverResult } from "../../observer/render.js";
 import { type BundleRun, type RunBundle, type RunRerunLineage, type RunScorerProvenance, type RunSubjectProvenance, type RunSubjectStateStepRecord } from "../../run/bundle.js";
 import { type RunDesktopGeometry } from "../../run/streams.js";
 import { type PreparedOutputRoot } from "../../run/contained-output.js";
-import type { ComputerUseParticipant, SharedWorldParticipant } from "../../lab/plan-participants.js";
+import type { ComputerUseParticipant, SharedWorldParticipant } from "../../study/plan-participants.js";
 import type { ResolvedParticipant } from "../../run/participant.js";
-export declare const CUA_ACTOR_LAB_SCHEMA = "humanish.cua-lab-result.v2";
+import { type StudyResultIdentity } from "../../run/study-result.js";
 export declare const CUA_FANOUT_STRATEGY: "per-lane-worlds";
 export declare const CUA_MAX_CONCURRENCY_ENV = "HUMANISH_CUA_MAX_CONCURRENCY";
 export declare const DEFAULT_APP_URL_SESSION_TIMEOUT_MS: number;
@@ -35,9 +35,9 @@ export declare const MIN_DERIVED_SESSION_TIMEOUT_MS: number;
  * What a computer-use run takes besides its plan and config. The count override and rerun go to
  * participant building with the config.
  */
-export type ComputerUseRunInput = Omit<RunCuaActorLabOptions, "config" | "dryRun" | "lab">;
+export type ComputerUseRunInput = Omit<RunCuaActorStudyOptions, "config" | "dryRun">;
 /**
- * What runLab's local VM study gives a computer-use run: the desktop each participant runs on, the
+ * What runStudyWith's local VM study gives a computer-use run: the desktop each participant runs on, the
  * reason automatic analysis must not run (the study's cleanup is unconfirmed), and the signal its
  * sessions abort on.
  */
@@ -47,17 +47,17 @@ export interface LocalVmInput {
     readonly analysisRefusal: () => AutomaticAnalysisRefusal | undefined;
     readonly signal?: AbortSignal;
 }
-export interface RunCuaActorLabOptions {
+export interface RunCuaActorStudyOptions {
     /** Cancels post-run analysis only. */
     analysisSignal?: AbortSignal;
     cwd: string;
-    config: LabConfig;
+    config: StudyConfig;
     /** Resolved upstream (scenario.mode + CLI override); defaults safe (dry-run). */
     dryRun: boolean;
     open?: boolean;
     runId?: string;
     /** CLI `--count` override for the homogeneous fan-out participant count (ignored when a `lanes`
-     *  roster is declared — a roster's length is authoritative). */
+     *  roster is declared; a roster's length is authoritative). */
     countOverride?: number;
     /** Explicitly create a new run containing failed or selected participants from a prior fan-out run. */
     rerun?: {
@@ -67,30 +67,30 @@ export interface RunCuaActorLabOptions {
     /** Keys and subject env for the run. Defaults to process.env. */
     env?: Readonly<Record<string, string | undefined>>;
     /** E2B only. Runs on each participant's desktop after it exists and before provisioning. */
-    prepareDesktop?: NonNullable<RunLabHomes["prepareDesktop"]>;
-    /** runLab's local VM study, for an app-url lab on the local target. */
+    prepareDesktop?: NonNullable<RunStudyHomes["prepareDesktop"]>;
+    /** runStudyWith's local VM study, for an app-url study on the local target. */
     localVm?: LocalVmInput;
     onObserverReady?: (observer: ObserverResult & {
         ok: true;
     }) => Promise<void> | void;
     /** Awaited after a participant's live stream starts, and again after its sandbox is gone. */
-    onStream?: NonNullable<RunLabHomes["onStream"]>;
-    /** The caller's brain for each participant, in place of the lab's own. */
+    onStream?: NonNullable<RunStudyHomes["onStream"]>;
+    /** The caller's brain for each participant, in place of the study's own. */
     createProvider?: ProviderFactory;
     /** Drives an app-url or local-app subject in this process, with no desktop. Needs createProvider. */
     inProcess?: InProcessDriver;
-    /** Reports the plan and subject phases to onEvent; built by normalizeRunLabOptions. */
-    emit?: (event: LabEvent) => void;
+    /** Reports the plan and subject phases to onEvent; built by normalizeRunStudyOptions. */
+    emit?: (event: StudyEvent) => void;
     /** Test seams. */
-    deps?: LabDeps;
-    /** Scores the assembled evidence: `RunLabOptions.scorer`, or the scorer the CLI loads. */
+    deps?: StudyDeps;
+    /** Scores the assembled evidence: `RunStudyOptions.scorer`, or the scorer the CLI loads. */
     scorer?: BrowserScorer;
-    /** Present only when the scorer was CONFIG-DECLARED and loaded by the CLI (#316);
+    /** Present only when the scorer was config-declared and loaded by the CLI;
      *  core-stamped onto the bundle as evidence. Absent for library callers. */
     scorerProvenance?: RunScorerProvenance;
 }
 /** A participant's row in the pre-flight plan: identity + the device/persona it will drive. The prompt
- *  text never leaks — only a sha256-16 digest of the composed instructions. */
+ *  text never leaks: only a sha256-16 digest of the composed instructions. */
 export interface CuaParticipantPlanEntry {
     id: string;
     actorType?: string;
@@ -103,8 +103,8 @@ export interface CuaParticipantPlanEntry {
     /** Requested E2B/X screen resolution. This is not the measured browser CSS viewport. */
     resolution: [number, number];
     instructionDigest: string;
-    /** The declared reasoning effort for this participant, when the lab declared one. The plan line is what
-     *  you read BEFORE spending money, so a declared per-participant difference has to be visible there. */
+    /** The declared reasoning effort for this participant, when the study declared one. The plan line is what
+     *  you read before spending money, so a declared per-participant difference has to be visible there. */
     reasoningEffort?: string;
     maxOutputTokens?: number;
     /** Present only when a participant overrides subject.appUrl; digest avoids leaking preview hosts in plan logs. */
@@ -115,23 +115,23 @@ export interface CuaParticipantPlanEntry {
 export interface CuaParticipantPlan {
     strategy: typeof CUA_FANOUT_STRATEGY;
     laneCount: number;
-    /** Effective in-flight bound (defaults to laneCount — all seats live; a declared
-     *  execution.concurrency is a cap; the env override may only LOWER it). */
+    /** Effective in-flight bound (defaults to laneCount, all participants live; a declared
+     *  execution.concurrency is a cap; the env override may only lower it). */
     concurrency: number;
-    /** Present when the env override lowered the bound below the config's value — recorded so the
+    /** Present when the env override lowered the bound below the config's value, recorded so the
      *  plan never silently disagrees with the manifest. */
     envLoweredConcurrencyFrom?: number;
     /** ceil(laneCount / concurrency). */
     waves: number;
     /** Per-participant session wall-clock budget (execution.timeoutMs); there is no run-level wall clock. */
     perLaneSessionBudgetMs: number;
-    /** Worst-case TOTAL sandbox-minutes across all participants (each one's full sandbox deadline). */
+    /** Worst-case total sandbox-minutes across all participants (each one's full sandbox deadline). */
     worstCaseSandboxMinutes: number;
     /** True for a dry-run plan (no spend); the same table appears live. */
     dryRun: boolean;
     lanes: CuaParticipantPlanEntry[];
 }
-/** One participant's outcome in the result projection. ALWAYS present in `result.lanes` (length
+/** One participant's outcome in the result projection. Always present in `result.lanes` (length
  *  1 at N=1). A `blocked` participant is one the pipeline-gate / fail-fast skipped before it ran. */
 export interface CuaParticipantResult {
     id: string;
@@ -164,7 +164,7 @@ export interface CuaParticipantResult {
     /** Set when the participant was skipped (pinned reason string). */
     skippedReason?: string;
     error?: {
-        code: CuaActorLabErrorCode;
+        code: CuaActorStudyErrorCode;
         message: string;
     };
 }
@@ -183,8 +183,8 @@ export interface CuaParticipantSummary {
     concurrency: number;
     waves: number;
 }
-export type CuaActorLabErrorCode = "HUMANISH_LAB_ANALYSIS_INVALID" | "HUMANISH_LAB_TASKS_UNSUPPORTED" | "HUMANISH_LAB_OPTION_UNSUPPORTED" | "HUMANISH_CUA_LAB_FAILED" | "HUMANISH_CUA_LAB_KEYS_MISSING" | "HUMANISH_CUA_LAB_AGENT_MISSING" | "HUMANISH_CUA_LAB_AGENT_SIGNIN_REQUIRED" | "HUMANISH_CUA_LAB_SUBJECT_ENV_MISSING" | "HUMANISH_CUA_LAB_ACTOR_UNSUPPORTED" | "HUMANISH_CUA_LAB_SUBJECT_INVALID" | "HUMANISH_CUA_LAB_SUBJECT_UNSAFE" | "HUMANISH_CUA_LAB_EXECUTOR_NO_PROVIDER" | "HUMANISH_CUA_LAB_LOCAL_APP_NO_EXECUTOR" | "HUMANISH_CUA_LAB_LOCAL_DESKTOP_MISSING" | "HUMANISH_CUA_LAB_FANOUT_INVALID" | "HUMANISH_CUA_LAB_RERUN_INVALID" | "HUMANISH_CUA_LAB_DEVICE_GEOMETRY" | "HUMANISH_RUN_ID_IN_USE" | "HUMANISH_CUA_LAB_UNPRICED_CAP" | "HUMANISH_CUA_LAB_COMMS_CATCH_UNREACHABLE" | "HUMANISH_CUA_LAB_COMMS_TOKEN_INVALID" | "HUMANISH_WATCH_ALLOW_REQUIRES_OAUTH" | "HUMANISH_WATCH_OAUTH_REQUIRES_TUNNEL" | "HUMANISH_WATCH_OPTION_CONFLICT" | "HUMANISH_WATCH_TUNNEL_REQUIRES_EXPOSE" | "HUMANISH_WATCH_EXPOSE_REQUIRES_EDGE_AUTH" | "HUMANISH_WATCH_EXPOSE_REQUIRES_LIVE_FOLLOW" | "HUMANISH_WATCH_SAFE_NOT_APPLICABLE" | "HUMANISH_SERVE_TUNNEL_NOT_FOUND" | "HUMANISH_SERVE_TUNNEL_START_FAILED";
-/** Subject provenance projection (invariant 5): what the actor actually drove. */
+export type CuaActorStudyErrorCode = "HUMANISH_STUDY_ANALYSIS_INVALID" | "HUMANISH_STUDY_TASKS_UNSUPPORTED" | "HUMANISH_STUDY_OPTION_UNSUPPORTED" | "HUMANISH_STUDY_V2_UNSUPPORTED" | "HUMANISH_COMPUTER_USE_FAILED" | "HUMANISH_COMPUTER_USE_KEYS_MISSING" | "HUMANISH_COMPUTER_USE_AGENT_MISSING" | "HUMANISH_COMPUTER_USE_AGENT_SIGNIN_REQUIRED" | "HUMANISH_COMPUTER_USE_SUBJECT_ENV_MISSING" | "HUMANISH_COMPUTER_USE_ACTOR_UNSUPPORTED" | "HUMANISH_COMPUTER_USE_SUBJECT_INVALID" | "HUMANISH_COMPUTER_USE_SUBJECT_UNSAFE" | "HUMANISH_COMPUTER_USE_EXECUTOR_NO_PROVIDER" | "HUMANISH_COMPUTER_USE_LOCAL_APP_NO_EXECUTOR" | "HUMANISH_COMPUTER_USE_LOCAL_DESKTOP_MISSING" | "HUMANISH_COMPUTER_USE_FANOUT_INVALID" | "HUMANISH_COMPUTER_USE_RERUN_INVALID" | "HUMANISH_COMPUTER_USE_DEVICE_GEOMETRY" | "HUMANISH_RUN_ID_IN_USE" | "HUMANISH_COMPUTER_USE_UNPRICED_CAP" | "HUMANISH_COMPUTER_USE_COMMS_CATCH_UNREACHABLE" | "HUMANISH_COMPUTER_USE_COMMS_TOKEN_INVALID" | "HUMANISH_WATCH_ALLOW_REQUIRES_OAUTH" | "HUMANISH_WATCH_OAUTH_REQUIRES_TUNNEL" | "HUMANISH_WATCH_OPTION_CONFLICT" | "HUMANISH_WATCH_TUNNEL_REQUIRES_EXPOSE" | "HUMANISH_WATCH_EXPOSE_REQUIRES_EDGE_AUTH" | "HUMANISH_WATCH_EXPOSE_REQUIRES_LIVE_FOLLOW" | "HUMANISH_WATCH_SAFE_NOT_APPLICABLE" | "HUMANISH_SERVE_TUNNEL_NOT_FOUND" | "HUMANISH_SERVE_TUNNEL_START_FAILED";
+/** Subject provenance projection: what the actor actually drove. */
 export interface CuaSubjectProjection {
     source: "app-url" | "clone" | "local-tree";
     /** Clone-route only: the (possibly redacted) owner/repo slug. */
@@ -198,9 +198,9 @@ export interface CuaSubjectProjection {
     /** Local-tree-route only: host-side porcelain status at pack time (true when the working
      *  tree had uncommitted changes). Absent when the packed root was not a git work tree. */
     dirty?: boolean;
-    /** Declared env NAMES provisioned for the subject (values never surface anywhere). */
+    /** Declared env names provisioned for the subject (values never surface anywhere). */
     envNames?: string[];
-    /** The subject's state story (seeded digests / UNPINNED external / declared-not-run /
+    /** The subject's state story (seeded digests / unpinned external / declared-not-run /
      *  undeclared): the same block the run bundle records. */
     state: RunSubjectProvenance["state"];
 }
@@ -221,13 +221,11 @@ export type CuaSubjectProvenanceArg = {
     envNames: string[];
     state: RunSubjectProvenance["state"];
 };
-export interface CuaActorLabResult extends AutomaticAnalysisResult {
-    schema: typeof CUA_ACTOR_LAB_SCHEMA;
+export interface CuaActorStudyResult extends AutomaticAnalysisResult, StudyResultIdentity<"computer-use"> {
     /** True when the Observer verified the bundle, all live participants passed credibility checks
      * (or this is a dry-run), and no declared adapter/scorer verdict failed. */
     ok: boolean;
     cwd: string;
-    labId: string;
     /** The registry-resolved actor id that ran (or would run) the session. */
     actor: string;
     appUrl: string;
@@ -244,16 +242,16 @@ export interface CuaActorLabResult extends AutomaticAnalysisResult {
     sandbox?: {
         sandboxId: string;
         killed: boolean;
-        /** The stream URL itself (carries an auth key) is runtime-only and is deliberately NOT
-         * surfaced on the result — the sandbox is already dead by the time the result exists. */
+        /** The stream URL itself (carries an auth key) is runtime-only and is deliberately not
+         * surfaced on the result; the sandbox is already dead by the time the result exists. */
         streamUrlPresent: boolean;
     };
-    /** Subject provenance (invariant 5): what the actor actually drove. At N>1 this is the
+    /** Subject provenance: what the actor actually drove. At N>1 this is the
      *  unanimity-gated aggregate (top-level `commit` only when every participant resolved the same one). */
     subject?: CuaSubjectProjection;
     /** The pre-flight participant plan (present once participants resolve; absent on early validation errors). */
     plan?: CuaParticipantPlan;
-    /** Per-participant results — ALWAYS present once participants resolve (length 1 at N=1). */
+    /** Per-participant results, always present once participants resolve (length 1 at N=1). */
     lanes?: CuaParticipantResult[];
     /** Aggregate participant counts. */
     laneSummary?: CuaParticipantSummary;
@@ -263,7 +261,7 @@ export interface CuaActorLabResult extends AutomaticAnalysisResult {
     diagnostics?: CuaDiagnostics;
     warnings: string[];
     error?: {
-        code: CuaActorLabErrorCode;
+        code: CuaActorStudyErrorCode;
         message: string;
     };
 }
@@ -293,8 +291,8 @@ export interface ParticipantRunsAndPlan {
     participantPlan: CuaParticipantPlan;
 }
 /**
- * The STUDY's shared spend ledger (#299): one counter across every participant. Each one notes its
- * own latest running MODEL-spend estimate (monotone per participant — an estimate can only grow)
+ * The study's shared spend ledger: one counter across every participant. Each one notes its
+ * own latest running model-spend estimate (monotone per participant: an estimate can only grow)
  * and reads back the run total; the loop stops the participant the moment the total crosses the study budget.
  * Estimated model spend only: desktop-minutes ride the cost summary, not this ledger.
  */
@@ -308,8 +306,8 @@ export interface CuaRunBudget {
  * The subject as a participant's desktop meets it. A computer-use participant gets the plan's
  * subject: a clone or local tree is provisioned in its own sandbox with the declared env, a
  * desktop-cli product is set up there, and an app-url or local-app subject is only opened. A
- * shared-world seat gets `shared-app`: it opens the one app the plane serves, with no subject env
- * names forwarded, no GitHub token and no provisioning in its sandbox.
+ * shared-world participant gets `shared-app`: it opens the one app the plane serves, with no
+ * subject env names forwarded, no GitHub token and no provisioning in its sandbox.
  */
 export type ParticipantSubject = ComputerUseRunner["subject"] | {
     readonly kind: "shared-app";
@@ -324,7 +322,7 @@ export declare function participantServeUrl(subject: ParticipantSubject): string
 export interface E2BDesktopDeps {
     /** The plan's residual config: comms, policies, the desktop and target, and subject leftovers. */
     residual: Readonly<ResidualConfig>;
-    labId: string;
+    studyId: string;
     appUrl: string;
     /** What the participant's desktop does with the subject before the participant starts. */
     subject: ParticipantSubject;
@@ -337,32 +335,32 @@ export interface E2BDesktopDeps {
     sandboxMs: number;
     participantCount: number;
     artifactRoot: PreparedOutputRoot;
-    /** The lab's resolution directory: relative paths in the config (a camera .y4m) resolve here. */
-    labCwd: string;
+    /** The study's resolution directory: relative paths in the config (a camera .y4m) resolve here. */
+    studyCwd: string;
     scrubKnownValues: (text: string) => string;
     receiving?: CommsReceivingRun;
-    /** Adopter-hosted comms plane (#380): present on the app-url route when comms.email.external is
+    /** Adopter-hosted comms plane: present on the app-url route when comms.email.external is
      *  declared. Carries the parsed comms block (recipients drive the per-participant inbox instruction)
      *  and the inbox URL the persona opens. The drain runs once at run level, not per participant. */
     externalComms?: {
-        email: LabCommsEmail;
+        email: StudyCommsEmail;
         inboxUrl: string;
     };
-    /** Injected clock (ms). Used to measure the host-side E2B desktop create->teardown span so the
+    /** Injected clock (ms). It measures the host-side E2B desktop create->teardown span so the
      *  desktop-minute cost estimate is deterministic in tests. Defaults to Date.now. */
     now: () => number;
     /** Loads the E2B SDK for the participant's desktop. Defaults to loadE2BDesktopModule. */
     desktopModule?: () => Promise<E2BDesktopModule>;
     /** The caller's prepareDesktop, called with the participant as its target. */
-    prepareDesktop?: NonNullable<RunLabHomes["prepareDesktop"]>;
+    prepareDesktop?: NonNullable<RunStudyHomes["prepareDesktop"]>;
     /** Clock and sleep for detached provisioning steps. */
     detachedTimers?: DetachedTimers;
     /** Receives each live stream's ready and ended: the Observer's tracker, then the caller's onStream. */
-    onStream: NonNullable<RunLabHomes["onStream"]>;
+    onStream: NonNullable<RunStudyHomes["onStream"]>;
     /** Reports a subject phase to the phase sink (stderr by default) and to onEvent. */
-    reportSubjectPhase: (event: SubjectPhaseEvent, participant: PhaseParticipant) => void;
+    reportSubjectPhase: (event: SubjectPhaseEvent, participant: ParticipantRef) => void;
     /**
-     * How a PARSEABLE requested-vs-verified screen mismatch is treated. Default ("fail-closed"):
+     * How a parseable requested-vs-verified screen mismatch is treated. Default ("fail-closed"):
      * the participant's device claim is falsified, so it fails with DEVICE_GEOMETRY (the
      * single-participant/fan-out contract). "record-evidence" (the concurrent shared-world route):
      * requested and verified stay recorded as separate facts plus an explicit warning, and the
@@ -386,22 +384,22 @@ export interface ParticipantModelDeps {
     redactScreenshots: boolean;
     scrubKnownValues: (text: string) => string;
     /** The study's shared spend ledger, present exactly when execution.caps.maxTotalUsd is set on a
-     *  live run (#299). Preflight already refused the cap on an unpriced model. */
+     *  live run. Preflight already refused the cap on an unpriced model. */
     runBudget?: CuaRunBudget;
     /**
-     * RUNTIME-ONLY observed-URL callback (#164 handoff crux): threaded into the participant's session so the
-     * orchestrator watches this seat's live location.href mid-run. Never persisted (see
-     * CuaLoopOptions.onObservedUrl). The concurrent shared-world barrier passes a host-seat latch here
+     * runtime-only observed-URL callback (the shared-world handoff): threaded into the participant's session so the
+     * orchestrator watches this participant's live location.href mid-run. Never persisted (see
+     * CuaLoopOptions.onObservedUrl). The concurrent shared-world barrier passes a host latch here
      * to extract a /lobby/CODE; on ordinary routes it is undefined (no-op).
      */
     onObservedUrl?: (url: string | undefined) => void;
-    /** RUNTIME-ONLY per-turn narration callback; see CuaLoopOptions.onMessage. The concurrent
-     * shared-world barrier passes a host-seat message scanner here to latch the lobby code. */
+    /** runtime-only per-turn narration callback; see CuaLoopOptions.onMessage. The concurrent
+     * shared-world barrier passes a host message scanner here to latch the lobby code. */
     onMessage?: (text: string) => void;
-    /** RUNTIME-ONLY per-turn raw-frame callback; see CuaLoopOptions.onScreenshot. The concurrent
-     * shared-world barrier passes a host-seat vision reader here to latch the lobby code off-screen. */
+    /** runtime-only per-turn raw-frame callback; see CuaLoopOptions.onScreenshot. The concurrent
+     * shared-world barrier passes a host vision reader here to latch the lobby code off-screen. */
     onScreenshot?: (frame: Buffer) => void;
-    /** Per-turn trace snapshot from a participant's loop (#441), keyed by participant. The live path
+    /** Per-turn trace snapshot from a participant's loop, keyed by participant. The live path
      * wires the incremental in-progress flush here so the attached Observer's timeline grows mid-run. */
     onTrace?: (participantId: string, items: readonly ActorTraceItem[], usage?: ActorTokenUsage, metadata?: CuaLiveMetadata) => void;
 }
@@ -438,8 +436,8 @@ export interface ParticipantRunOutcome {
      *  the session's evidence does not show. An execution failure, scrubbed, like the cleanup one. */
     providerPolicyError?: string;
     sandboxId?: string;
-    /** Host-side E2B desktop create->teardown span (ms). An APPROXIMATION of E2B's server-side
-     *  billed lifetime (server-side kill-on-timeout can extend it) — so the derived dollar figure is
+    /** Host-side E2B desktop create->teardown span (ms). An approximation of E2B's server-side
+     *  billed lifetime (server-side kill-on-timeout can extend it), so the derived dollar figure is
      *  doubly an estimate. Absent on the in-process route (no sandbox) and on dry-run. */
     desktopDurationMs?: number;
     desktopResources?: DesktopResourceObservation;
@@ -463,22 +461,22 @@ export interface ParticipantRunOutcome {
     skippedReason?: string;
     noEngagement: boolean;
     selfReportedBlocker: boolean;
-    /** The inclusive friction read (#453): blocker-shaped narration incl. self-resolved arcs.
+    /** The inclusive friction read: blocker-shaped narration incl. self-resolved arcs.
      *  Feeds the participants tally and feedback candidates; never the participant verdict. Optional so
      *  external outcome constructors (shared-world, test fakes) stay valid; absent counts as false. */
     reportedFriction?: boolean;
     harnessError: boolean;
-    failureCode?: CuaActorLabErrorCode;
+    failureCode?: CuaActorStudyErrorCode;
     /** Relative run-dir path of the digest-only comms-thread evidence artifact this participant wrote
-     *  (humanish.comms-thread.v1), when a comms lab captured mail into its in-sandbox catch. Registered
-     *  in the participant's stream artifacts. Absent when no comms lab ran or nothing was captured. */
+     *  (humanish.comms-thread.v1), when a comms study captured mail into its in-sandbox catch. Registered
+     *  in the participant's stream artifacts. Absent when no comms study ran or nothing was captured. */
     commsArtifactPath?: string;
 }
 /** What buildCuaFanoutBundle projects into a fan-out run bundle. */
 export interface CuaFanoutBundleArgs {
     /** The run's verdict, from the judge. */
     verdict: Verdict;
-    /** The run this bundle belongs to; the bundle head reads its id, mode, start and lab. */
+    /** The run this bundle belongs to; the bundle head reads its id, mode, start and study. */
     run: BundleRun;
     specs: DesktopParticipantRun[];
     outcomes?: ParticipantRunOutcome[];

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

@@ -2,33 +2,33 @@ import {} from "./participant-desktop.js";
 import {} from "../../analysis/automatic-completion.js";
 import {} from "./diagnostics.js";
 import {} from "../../actors/registry.js";
-import {} from "../../lab/adapter-extension.js";
+import {} from "../../study/adapter-extension.js";
 import {} from "../../substrates/e2b/sdk.js";
 import {} from "../../substrates/e2b/desktop-resources.js";
 import {} from "../../substrates/detached.js";
-import {} from "../../lab/types.js";
+import {} from "../../study/types.js";
 import {} from "../../observer/render.js";
 import {} from "../../run/bundle.js";
 import {} from "../../run/streams.js";
 import {} from "../../run/contained-output.js";
-export const CUA_ACTOR_LAB_SCHEMA = "humanish.cua-lab-result.v2";
-// The only fan-out topology this slice ships: N participants = N independent E2B desktop
-// sandboxes, each its own world (clone/serve + subject.state per participant). Shared-world is layer 7 (#164).
+import {} from "../../run/study-result.js";
+// The fan-out topology of this route: N participants = N independent E2B desktop sandboxes,
+// each its own world (clone/serve + subject.state per participant). Shared-world has its own route.
 export const CUA_FANOUT_STRATEGY = "per-lane-worlds";
-// Env override that may only LOWER the effective concurrency (never raise concurrent paid
-// desktops — invariant 3). Read names-only into a local; the value never persists.
+// Env override that may only lower the effective concurrency (never raise concurrent paid
+// desktops). Read names-only into a local; the value never persists.
 export const CUA_MAX_CONCURRENCY_ENV = "HUMANISH_CUA_MAX_CONCURRENCY";
-// The DEFAULT session budget, sized so a study can FINISH (docs/principles/three-roles.md: a
-// session ends because the participant is done, not because a timer fired — the time-box is a
+// The default session budget, sized so a study can finish (docs/principles/three-roles.md: a
+// session ends because the participant is done, not because a timer fired; the time-box is a
 // session-level cap a researcher sets generously; spend protection is the dollar caps' job).
 // The old 300s default ended real signup studies mid-flow: observed studies run 16-40 turns at
-// ~5-6s per turn BEFORE any email wait, so five minutes was the biggest single source of
+// ~5-6s per turn before any email wait, so five minutes was the biggest single source of
 // budget_reached endings that read as participant failures.
 //
 // App-url and in-process routes default to 30 minutes. Provisioned routes (clone/local-tree)
 // default to whatever the 1-hour sandbox cap leaves after provisioning, declared state seeding,
-// and the teardown buffer — 20 minutes on a stateless clone — floored at the old five minutes so
-// a state-heavy lab still gets a session at all. An EXPLICIT execution.timeoutMs is never
+// and the teardown buffer (20 minutes on a stateless clone), floored at the old five minutes so
+// a state-heavy study still gets a session at all. An explicit execution.timeoutMs is never
 // adjusted: when it cannot be provisioned, the plan-time cap refusal shows the arithmetic.
 export const DEFAULT_APP_URL_SESSION_TIMEOUT_MS = 30 * 60_000;
 export const MIN_DERIVED_SESSION_TIMEOUT_MS = 5 * 60_000;

package/dist/routes/preview.d.ts

@@ -1,13 +1,19 @@
-import type { AdmittedPlan, RunLabOptions } from "../run-lab.js";
-import type { LabPlan, PlanRefusal } from "../lab/plan-types.js";
+import type { AdmittedPlan, RunStudyOptions } from "../run-study.js";
+import type { StudyPlan, PlanRefusal } from "../study/plan-types.js";
 import type { RunResult } from "../run/results.js";
-type PreviewPlan = Extract<LabPlan, {
+import { type StudyResultIdentity } from "../run/study-result.js";
+type PreviewPlan = Extract<StudyPlan, {
     readonly route: "preview";
 }>;
+/**
+ * The preview route's result when a study runs: the synthetic run's result, named as a study
+ * result. `humanish run` with no study returns the plain `RunResult`.
+ */
+export type PreviewStudyResult = Omit<RunResult, "schema"> & StudyResultIdentity<"preview">;
 /** A refused preview's result. */
-export declare function previewLabRefusal(cwd: string, refusal: Extract<PlanRefusal, {
+export declare function previewStudyRefusal(cwd: string, studyId: string, refusal: Extract<PlanRefusal, {
     readonly route: "preview";
-}>): RunResult;
-/** runLab's step for a preview plan: it has no local checks and takes no scorer, so it returns its run. */
-export declare function admitPreviewPlan(plan: PreviewPlan, input: Pick<RunLabOptions, "cwd" | "runId" | "open">): AdmittedPlan<"preview">;
+}>): PreviewStudyResult;
+/** runStudyWith's step for a preview plan: it has no local checks and takes no scorer, so it returns its run. */
+export declare function admitPreviewPlan(plan: PreviewPlan, input: Pick<RunStudyOptions, "cwd" | "runId" | "open">): AdmittedPlan<"preview">;
 export {};

package/dist/routes/preview.js

@@ -1,34 +1,38 @@
-// The preview route: a lab whose subject is this repo runs the synthetic dry run. planLab decides
+// The preview route: a study whose subject is this repo runs the synthetic dry run. planStudy decides
 // the sim count and refuses what a synthetic run would ignore; runPreviewPlan does the rest.
+import { studyResultIdentity } from "../run/study-result.js";
 import { runDryRun } from "../run/dry-run.js";
 import path from "node:path";
 /** A refused preview's result. */
-export function previewLabRefusal(cwd, refusal) {
+export function previewStudyRefusal(cwd, studyId, refusal) {
     return {
-        schema: "humanish.run-result.v1",
+        ...studyResultIdentity("preview", studyId),
         ok: false,
         cwd: path.resolve(cwd),
         warnings: [],
         error: { code: refusal.code, message: refusal.message },
     };
 }
-/** runLab's step for a preview plan: it has no local checks and takes no scorer, so it returns its run. */
+/** runStudyWith's step for a preview plan: it has no local checks and takes no scorer, so it returns its run. */
 export function admitPreviewPlan(plan, input) {
     return {
         ok: true,
         run: async () => ({
             route: "preview",
-            result: await runPreviewPlan(plan, input),
+            result: {
+                ...(await runPreviewPlan(plan, input)),
+                ...studyResultIdentity("preview", plan.studyId),
+            },
         }),
     };
 }
 /** Run a preview plan: the synthetic dry run with the planned sim count. */
 function runPreviewPlan(plan, input) {
     return runDryRun({
-        ...(plan.lab === undefined ? {} : { lab: plan.lab }),
+        ...(plan.study === undefined ? {} : { study: plan.study }),
         cwd: input.cwd,
         dryRun: true,
-        simCount: plan.participantCount,
+        participantCount: plan.participantCount,
         ...(input.runId === undefined ? {} : { runId: input.runId }),
         ...(input.open === undefined ? {} : { observer: { open: input.open } }),
     });

package/dist/routes/scripted/bundle.d.ts

@@ -3,9 +3,9 @@ import type { ScriptedBrowserSessionResult } from "../../actors/scripted-browser
 import type { BrowserPersonaJourney, BrowserSurface } from "../../actors/scripted-browser/types.js";
 import type { DesktopResourceObservation } from "../../substrates/e2b/desktop-resources.js";
 import { type ReviewSummary, type RunBundle, type RunSubjectProvenance, type BundleRun } from "../../run/bundle.js";
-/** What the scripted lab's bundle is built from. */
+/** What the scripted study's bundle is built from. */
 interface ScriptedBundleArgs {
-    /** The run this bundle belongs to; the bundle head reads its id, mode, start and lab. */
+    /** The run this bundle belongs to; the bundle head reads its id, mode, start and study. */
     run: BundleRun;
     actorId: string;
     appUrl: string;
@@ -13,8 +13,8 @@ interface ScriptedBundleArgs {
     dryRun: boolean;
     hostDigest?: string;
     journey: BrowserPersonaJourney;
-    labId: string;
-    labTitle?: string;
+    studyId: string;
+    studyTitle?: string;
     persona: ActorPersonaRef;
     scenarioSource: string;
     scenarioSourceDigest: string;
@@ -34,11 +34,11 @@ interface ScriptedBundleArgs {
     verdict: ReviewSummary["verdict"];
 }
 /**
- * Project the scripted lab run into a humanish.run-bundle.v1 (no schema change — a new
- * producer only). The load-bearing line is `stream.actor = result.trace`: the provider-neutral
+ * Project the scripted run into a humanish.run-bundle.v1 (no schema change: a new
+ * producer only). The key line is `stream.actor = result.trace`: the provider-neutral
  * ActorTrace seam the Observer renders and verifyRun's engagement check reads. Exported for
  * the bundle-builder tests.
  */
-export declare function buildScriptedLabBundle(args: ScriptedBundleArgs): RunBundle;
+export declare function buildScriptedStudyBundle(args: ScriptedBundleArgs): RunBundle;
 export declare function renderScriptedReviewMarkdown(bundle: RunBundle): string;
 export {};