humanish 0.107.0 → 0.109.0

package/dist/routes/computer-use/participant-execution.js

@@ -132,12 +132,12 @@ export async function runCuaParticipant(spec, deps) {
 }
 /**
  * Run N>1 E2B participants with bounded concurrency, a pipeline gate (the first provisions
- * before the rest start), and session fail-fast on HARNESS errors only (queued participants
+ * before the rest start), and session fail-fast on harness errors only (queued participants
  * become `blocked` with a pinned reason + a fail-fast event; mission verdicts never trip it).
- * Each participant tears down ITS OWN sandbox by id; nothing here ever enumerates.
+ * Each participant tears down its own sandbox by id; nothing here ever enumerates.
  *
- * Exported for the #342 total-runner tests: the injectable runner lets a test make one participant
- * THROW (the exact class the guard exists for) without a live sandbox. Production always uses
+ * Exported for the total-runner tests: the injectable runner lets a test make one participant
+ * throw (the exact class the guard exists for) without a live sandbox. Production always uses
  * the default.
  */
 export async function runCuaParticipants(runs, deps, concurrency, runParticipant = runCuaParticipant) {
@@ -164,10 +164,10 @@ export async function runCuaParticipants(runs, deps, concurrency, runParticipant
         if (failFast.tripped) {
             return skippedOutcome(spec, `skipped: ${failFast.reason}`);
         }
-        // The participant runner is TOTAL (#342): every exit path returns a recorded outcome. Without this
+        // The participant runner is total: every exit path returns a recorded outcome. Without this
         // guard, one participant's late throw (e.g. its trace write hitting ENOSPC after its own sandbox was
         // already torn down) rejected the whole map while sibling workers kept launching sandboxes
-        // nobody would ever record — the run spent money and then reported nothing.
+        // nobody would ever record, so the run spent money and then reported nothing.
         let outcome;
         try {
             outcome = await runParticipant(spec, {
@@ -187,7 +187,7 @@ export async function runCuaParticipants(runs, deps, concurrency, runParticipant
             });
         }
         catch (error) {
-            // The first participant may have thrown before signaling the provisioning gate — release the followers as
+            // The first participant may have thrown before signaling the provisioning gate; release the followers as
             // blocked rather than leaving them awaiting a gate that will never settle.
             if (index === 0)
                 rejectGate?.();
@@ -247,7 +247,7 @@ export function toParticipantResult(spec, outcome, subject, dryRun) {
             ok: false,
             diagnostics: cuaParticipantDiagnostics({ dryRun, skipped: true }),
             skippedReason: outcome.skippedReason,
-            error: { code: "HUMANISH_CUA_LAB_FAILED", message: outcome.skippedReason },
+            error: { code: "HUMANISH_COMPUTER_USE_FAILED", message: outcome.skippedReason },
         };
     }
     const session = outcome.session;
@@ -299,7 +299,7 @@ export function toParticipantResult(spec, outcome, subject, dryRun) {
             ? {}
             : {
                 error: {
-                    code: outcome.failureCode ?? "HUMANISH_CUA_LAB_FAILED",
+                    code: outcome.failureCode ?? "HUMANISH_COMPUTER_USE_FAILED",
                     message: outcome.sessionError ??
                         (outcome.noEngagement
                             ? "Actor took no actions and produced no message (likely a blank/still-loading screen); not a credible goal_satisfied."
@@ -309,7 +309,7 @@ export function toParticipantResult(spec, outcome, subject, dryRun) {
                                     ? `Computer-use session ended with a harness error: ${session.reason}`
                                     : session?.status !== "passed"
                                         ? `Computer-use session ended with ${session?.status ?? "unknown"}: ${session?.reason ?? "no terminal reason"}`
-                                        : "Computer-use lab did not produce a terminal session."),
+                                        : "The computer-use run did not produce a terminal session."),
                 },
             }),
     };

package/dist/routes/computer-use/participant-model.d.ts

@@ -1,4 +1,5 @@
 import type { CuaExecutor, CuaLoopResult, CuaProvider } from "../../actors/computer-use/loop.js";
+import type { ActorConversation } from "../../actors/contract.js";
 import type { CuaActorSessionOptions } from "../../actors/computer-use/actor.js";
 import { startClaudeSession } from "../../actors/local-agent/claude-session.js";
 import { createRestrictedCodexParticipant, type ParticipantProviderCloseResult } from "../../actors/codex/restricted-participant.js";
@@ -29,6 +30,11 @@ export declare function closeParticipantModel(model: ParticipantModel, warnings:
 }>;
 /** Prices the finished session's tokens onto its trace, writes the trace, and warns on raw screenshots. */
 export declare function recordParticipantTrace(spec: DesktopParticipantRun, deps: ParticipantModelDeps, session: CuaLoopResult, warnings: string[]): Promise<void>;
+/**
+ * The run warning for a participant whose provider kept no conversation server-side, so humanish
+ * carried it on every request. It says why, and how many early turns became a text summary.
+ */
+export declare function explicitContextWarning(conversation: ActorConversation): string;
 /** The checks that keep a goal_satisfied session from counting as a pass, with their warnings. */
 export declare function judgeParticipantSession(session: CuaLoopResult | undefined, deps: ParticipantModelDeps, warnings: string[]): {
     noEngagement: boolean;

package/dist/routes/computer-use/participant-model.js

@@ -3,7 +3,7 @@
 // finished session. The desktop side stays with the participant runner.
 import { startClaudeSession } from "../../actors/local-agent/claude-session.js";
 import { createLocalAgentProvider } from "../../actors/local-agent/cli.js";
-import { pricedModel } from "../../lab/plan-base.js";
+import { pricedModel } from "../../study/plan-base.js";
 import { estimateActorCostForExecution, round6 } from "../../run/pricing.js";
 import { redactText } from "../../evidence/redaction.js";
 import { createRestrictedCodexParticipant, } from "../../actors/codex/restricted-participant.js";
@@ -49,12 +49,12 @@ export async function startParticipantModel(spec, deps, executor) {
         return { provider: codexParticipant.provider, codexParticipant };
     }
     if (localAgent === "claude") {
-        // One session for the whole run, like the codex thread above (#520). The one-shot
+        // One session for the whole run, like the codex thread above. The one-shot
         // provider (createLocalAgentProvider) spawned `claude -p` per turn, and every turn
         // started with no memory of the last. HUMANISH_LOCAL_AGENT_ONE_SHOT=1 keeps that path
-        // reachable as a MEASUREMENT switch: MemTrapBench (2026-08) reports memory frameworks
+        // reachable as a measurement switch: MemTrapBench (2026-08) reports memory frameworks
         // degrading agent performance by 10-40% on some tasks, so "remembers" has to be measured
-        // against "does not" on the same lab, not assumed. The trace records which one ran.
+        // against "does not" on the same study, not assumed. The trace records which one ran.
         const oneShot = env.HUMANISH_LOCAL_AGENT_ONE_SHOT !== undefined &&
             env.HUMANISH_LOCAL_AGENT_ONE_SHOT !== "" &&
             env.HUMANISH_LOCAL_AGENT_ONE_SHOT !== "0";
@@ -82,7 +82,7 @@ export async function startParticipantModel(spec, deps, executor) {
 /** The options the participant's session runs with: prompt, model settings, spend caps and callbacks. */
 export function participantSessionOptions(spec, deps, ready, provider, writeScreenshot) {
     const { executor, inbox } = ready;
-    // The FAIL-CLOSED spend cap (execution.caps.maxUsd) is wired into the loop as maxUsd + an
+    // The fail-closed spend cap (execution.caps.maxUsd) is wired into the loop as maxUsd + an
     // injected pure per-turn estimator keyed on the resolved model. Preflight already refused a
     // cap on an unpriced model, so the estimate is measurable whenever a cap is in force. The
     // model id here matches provider.version (openai-responses-cu resolves the default when unset).
@@ -95,7 +95,7 @@ export function participantSessionOptions(spec, deps, ready, provider, writeScre
         persona: spec.persona,
         timeoutMs: deps.timeoutMs,
         // The brain is either a keyed API client or a CLI the operator is already signed in to.
-        // Everything below this line — loop, executor, trace, affordances — is identical either
+        // Everything below this line (loop, executor, trace, affordances) is identical either
         // way, which is what makes a local-agent run comparable to an API one.
         ...(provider === undefined ? {} : { provider: provider }),
         openai: {
@@ -129,8 +129,8 @@ export function participantSessionOptions(spec, deps, ready, provider, writeScre
             : { stopWhen: spec.planned.limits.stopWhen }),
         ...(spec.planned.limits.dwell === undefined ? {} : { dwell: spec.planned.limits.dwell }),
         ...(spec.planned.tasks === undefined ? {} : { tasks: spec.planned.tasks }),
-        // The STUDY budget (#299): this participant notes its own running estimate on the shared
-        // ledger and stops when the RUN total crosses the cap — independent of the per-participant
+        // The study budget: this participant notes its own running estimate on the shared
+        // ledger and stops when the run total crosses the cap, independent of the per-participant
         // maxUsd above.
         ...(deps.runBudget === undefined
             ? {}
@@ -149,8 +149,8 @@ export function participantSessionOptions(spec, deps, ready, provider, writeScre
         ...(deps.onTrace === undefined
             ? {}
             : {
-                // Forwards the RUNNING usage as well: the participant runner is where both are known, and usage
-                // without it never reaches the flush — which is how the live cost stayed unknown.
+                // Forwards the running usage as well: the participant runner is where both are known, and usage
+                // without it never reaches the flush, which is how the live cost stayed unknown.
                 onTrace: (items, usage, metadata) => deps.onTrace?.(spec.planned.id, items, usage, metadata),
             }),
     };
@@ -207,27 +207,45 @@ export async function closeParticipantModel(model, warnings) {
 }
 /** Prices the finished session's tokens onto its trace, writes the trace, and warns on raw screenshots. */
 export async function recordParticipantTrace(spec, deps, session, warnings) {
-    // Per-participant model-token cost ESTIMATE, attached to the trace before it is persisted (the model
-    // id is authoritative here — provider.version). Kept at the lab boundary so the pure loop
+    // Per-participant model-token cost estimate, attached to the trace before it is persisted (the model
+    // id is authoritative here: provider.version). Kept at the study boundary so the pure loop
     // never depends on the operator rate table. estimateActorCost declares absent (null) for an
     // unknown rate / missing usage rather than guessing.
     session.trace.estimatedCost = estimateActorCostForExecution(session.trace.tokenUsage, session.trace.ids.model, session.trace.executionProfile);
     await writeContainedOutputFile(deps.artifactRoot, spec.traceArtifactPath, `${JSON.stringify(session.trace, null, 2)}\n`, "utf8");
+    const conversation = session.trace.conversation;
+    if (conversation?.mode === "explicit_context")
+        warnings.push(explicitContextWarning(conversation));
     if (session.trace.redaction.screenshots === "raw") {
-        warnings.push("Screenshots are full-fidelity (raw) for local use — the bundle stays in gitignored .humanish and nothing scans these pixels; review them before sharing anywhere. Set policies.redactScreenshots: true to blur a share-as-is bundle.");
+        warnings.push("Screenshots are unblurred for local use: the bundle stays in the gitignored .humanish/ folder and nothing scans these pixels, so review them before sharing. Set policies.redactScreenshots: true to blur screenshots in a bundle you plan to share.");
     }
 }
+/**
+ * The run warning for a participant whose provider kept no conversation server-side, so humanish
+ * carried it on every request. It says why, and how many early turns became a text summary.
+ */
+export function explicitContextWarning(conversation) {
+    const why = conversation.explicitReason === "zdr_rejection"
+        ? `The OpenAI organization rejected server-side conversation state (zero data retention)${conversation.switchedAtRequest === undefined
+            ? ""
+            : ` on request ${conversation.switchedAtRequest}`}`
+        : "zeroDataRetention is set";
+    const summarized = conversation.summarizedTurns === 0
+        ? ""
+        : ` To stay within its token budget it summarized the ${conversation.summarizedTurns} oldest turns as text and dropped their screenshots.`;
+    return `${why}, so humanish carried this participant's conversation itself (explicit_context).${summarized} The trace's conversation record has each request's carried context.`;
+}
 /** The checks that keep a goal_satisfied session from counting as a pass, with their warnings. */
 export function judgeParticipantSession(session, deps, warnings) {
     const noEngagement = session !== undefined && hollowCompletion(sessionEnding(session));
     if (noEngagement) {
-        warnings.push("Actor returned goal_satisfied with ZERO actions and ZERO messages — it likely saw a blank or still-loading screen and stopped without engaging. NOT counted as a pass. Check the screenshot; raise execution.timeoutMs or confirm the subject painted before the first turn.");
+        warnings.push("The participant returned goal_satisfied with no actions and no messages, so it likely saw a blank or loading screen and stopped. This does not count as a pass. Check the screenshot, and raise execution.timeoutMs or confirm the app had rendered before the first turn.");
     }
     const blockerReason = resolveSelfReportedBlocker(session);
     const selfReportedBlocker = blockerReason !== undefined;
     const reportedFriction = resolveSelfReportedFriction(session) !== undefined;
     if (selfReportedBlocker) {
-        warnings.push(`Actor returned goal_satisfied while its final message describes a blocker or asks for missing instructions — NOT counted as a pass: ${redactText(deps.scrubKnownValues(blockerReason))}`);
+        warnings.push(`The participant returned goal_satisfied, but its final message describes a blocker or asks for missing instructions, so this does not count as a pass: ${redactText(deps.scrubKnownValues(blockerReason))}`);
     }
     return { noEngagement, selfReportedBlocker, reportedFriction };
 }

package/dist/routes/computer-use/participant-prompt.d.ts

@@ -1,11 +1,11 @@
 import type { ActorPersonaRef } from "../../actors/contract.js";
-import type { DevicePreset } from "../../lab/device-presets.js";
-import { type ResolvedPersona } from "../../lab/persona.js";
-import { type LabTask } from "../../lab/tasks.js";
+import type { DevicePreset } from "../../study/device-presets.js";
+import { type ResolvedPersona } from "../../study/persona.js";
+import { type StudyTask } from "../../study/tasks.js";
 import type { DesktopParticipantRun } from "./types.js";
 export declare const DEFAULT_MISSION = "You are testing a web application. The browser is already open at the subject URL. Explore it, accomplish what the scenario asks, and stop when done.";
 /**
- * The participant's outcome as ONE fixed first line of its last message (#570, second half). The
+ * The participant's outcome as one fixed first line of its last message. The
  * free-text computer-use provider has no schema to fill; a fixed line is the next best thing, and
  * the loop reads it into the trace's declaredOutcome. Prompt-only control is weak in general, so
  * adherence is measured (declaredOutcome present or absent on the trace) and the regex over the
@@ -21,24 +21,24 @@ export declare function composeParticipantInstructions(args: {
     mission: string;
     persona?: string;
     instruction?: string;
-    /** The lab's declared protocol (#414). Only the participant-facing `goal` halves are rendered
+    /** The study's declared protocol. Only the participant-facing `goal` halves are rendered
      *  into the prompt; the `success` criteria never appear here. */
-    tasks?: readonly LabTask[];
+    tasks?: readonly StudyTask[];
     device: {
         name: string;
         preset: DevicePreset;
     };
-    /** The COMPILED persona for `args.persona`, when its committed file resolved (#381). Supplying it
-     *  makes the persona shape behavior — its traits become directives in the prompt and land in
-     *  traitsApplied — instead of appearing as a bare `Persona: <id>.` label. Absent (unsafe id,
-     *  no committed file, unparseable YAML) keeps the honest fallback: the bare line and an EMPTY
+    /** The compiled persona for `args.persona`, when its committed file resolved. Supplying it
+     *  makes the persona shape behavior: its traits become directives in the prompt and land in
+     *  traitsApplied, instead of appearing as a bare `Persona: <id>.` label. Absent (unsafe id,
+     *  no committed file, unparseable YAML) keeps the fallback: the bare line and an empty
      *  traitsApplied, never fabricated traits. Resolved by the caller so this stays pure. */
     resolvedPersona?: ResolvedPersona;
     /**
-     * desktop-cli (#495): the surface under study is a terminal window, not a page. Said plainly
-     * because a participant whose every prior world was a browser will look for one — and because a
+     * desktop-cli: the surface under study is a terminal window, not a page. Said plainly
+     * because a participant whose every prior world was a browser will look for one, and because a
      * capability nobody declares is one the recording cannot later be read against. It states that a
-     * terminal is open and NOT what to type in it: naming commands would answer the question the
+     * terminal is open and does not say what to type in it: naming commands would answer the question the
      * study is asking.
      */
     surface?: "desktop-cli";
@@ -46,8 +46,8 @@ export declare function composeParticipantInstructions(args: {
     instructions: string;
     persona: ActorPersonaRef;
 };
-/** Runtime-inject the persona inbox instruction into a participant's prompt (#297 slice B). The inbox URL is a
- *  runtime loopback/getHost address (not secret), so — mirroring the lobby-code runtime injection — this
+/** Runtime-inject the persona inbox instruction into a participant's prompt. The inbox URL is a
+ *  runtime loopback/getHost address (not secret), so, mirroring the lobby-code runtime injection, this
  *  augments only the instructions the model receives; the authored prompt + its digest are unchanged.
  *  Returns a new spec (never mutates). Shared by the CUA + concurrent shared-world routes. */
 export declare function withInboxMission(spec: DesktopParticipantRun, inboxUrl: string, address?: string, receiving?: boolean): DesktopParticipantRun;

package/dist/routes/computer-use/participant-prompt.js

@@ -3,11 +3,11 @@
 // the email inbox at run time. Shared by the computer-use and concurrent shared-world routes.
 import { recipientInboxUrl } from "../../comms/capture-surface.js";
 import { digestText } from "../../evidence/redaction.js";
-import { personaBrief, personaToDirectives, renderPersonaPromptSection, } from "../../lab/persona.js";
-import { renderTaskPrompt } from "../../lab/tasks.js";
+import { personaBrief, personaToDirectives, renderPersonaPromptSection, } from "../../study/persona.js";
+import { renderTaskPrompt } from "../../study/tasks.js";
 export const DEFAULT_MISSION = "You are testing a web application. The browser is already open at the subject URL. Explore it, accomplish what the scenario asks, and stop when done.";
 /**
- * The participant's outcome as ONE fixed first line of its last message (#570, second half). The
+ * The participant's outcome as one fixed first line of its last message. The
  * free-text computer-use provider has no schema to fill; a fixed line is the next best thing, and
  * the loop reads it into the trace's declaredOutcome. Prompt-only control is weak in general, so
  * adherence is measured (declaredOutcome present or absent on the trace) and the regex over the
@@ -26,12 +26,12 @@ export function composeParticipantInstructions(args) {
     const deviceLine = preset.isMobile
         ? `You are a mobile user on a ${name} device (${preset.width}x${preset.height} @${preset.deviceScaleFactor}x). Expect a mobile/touch layout.`
         : `You are a desktop user (${name}, ${preset.width}x${preset.height}).`;
-    // The protocol as the PARTICIPANT reads it: numbered goals, nothing else. The success criteria
-    // are the researcher's instrument and must never reach this prompt — a persona told how it will
-    // be measured optimizes for the measurement instead of using the product (src/lab/tasks.ts).
+    // The protocol as the participant reads it: numbered goals, nothing else. The success criteria
+    // are the researcher's instrument and must never reach this prompt: a persona told how it will
+    // be measured optimizes for the measurement instead of using the product (src/study/tasks.ts).
     const taskLines = renderTaskPrompt(args.tasks ?? []);
     // A resolved persona contributes its compiled directives (friction tolerance, skill bias,
-    // accessibility behavior, constraints) through the SAME persona.ts compiler the terminal route
+    // accessibility behavior, constraints) through the same persona.ts compiler the terminal route
     // uses, so one persona file means one behavior across every route.
     const personaLine = args.resolvedPersona
         ? renderPersonaPromptSection(args.resolvedPersona)
@@ -64,8 +64,8 @@ export function composeParticipantInstructions(args) {
         },
     };
 }
-/** Runtime-inject the persona inbox instruction into a participant's prompt (#297 slice B). The inbox URL is a
- *  runtime loopback/getHost address (not secret), so — mirroring the lobby-code runtime injection — this
+/** Runtime-inject the persona inbox instruction into a participant's prompt. The inbox URL is a
+ *  runtime loopback/getHost address (not secret), so, mirroring the lobby-code runtime injection, this
  *  augments only the instructions the model receives; the authored prompt + its digest are unchanged.
  *  Returns a new spec (never mutates). Shared by the CUA + concurrent shared-world routes. */
 export function withInboxMission(spec, inboxUrl, address, receiving = false) {

package/dist/routes/computer-use/participant-runs.d.ts

@@ -1,40 +1,40 @@
-import type { ComputerUsePlan } from "../../lab/plan-types.js";
-import { type LabConfig } from "../../lab/types.js";
-import { type ResolvedPersona } from "../../lab/persona.js";
+import type { ComputerUsePlan } from "../../study/plan-types.js";
+import { type StudyConfig } from "../../study/types.js";
+import { type ResolvedPersona } from "../../study/persona.js";
 import { type RunRerunLineage } from "../../run/bundle.js";
 import type { PreparedSelectedOutputDirectory } from "../../run/contained-output.js";
-import { type CuaActorLabErrorCode, type CuaParticipantPlan, type CuaParticipantPlanEntry, type DesktopParticipantRun } from "./types.js";
-export declare function defaultSessionTimeoutMs(config: LabConfig): number;
+import { type CuaActorStudyErrorCode, type CuaParticipantPlan, type CuaParticipantPlanEntry, type DesktopParticipantRun } from "./types.js";
+export declare function defaultSessionTimeoutMs(config: StudyConfig): number;
 /** Per-participant sandbox deadline (each one owns its own desktop). Mirrors the
  *  single-participant formula verbatim so N=1 stays byte-stable: explicit sandboxTimeoutMs, else session budget + (clone
  *  or local-tree: provision budget + Σ state-step budgets) + the server-side
  *  reclamation buffer. Local-tree shares the clone route's provisioning budget: it swaps a
  *  git clone for an upload+extract, but the shared install/build/state/start/probe pipeline
  *  costs the same wall-clock room either way. */
-export declare function resolveParticipantSandboxMs(config: LabConfig): number;
+export declare function resolveParticipantSandboxMs(config: StudyConfig): number;
 /**
- * The in-flight participant bound a lab declares. Defaults to the participant count — every
+ * The in-flight participant bound a study declares. Defaults to the participant count: every
  * declared participant runs at once, because a throttle nobody asked for silently turns "N actors
- * live" into waves (#350); total session count and spend are the same either way, only wall-clock
- * and simultaneity differ. A declared execution.concurrency is a CAP, clamped to [1, participants].
+ * live" into waves; total session count and spend are the same either way, only wall-clock
+ * and simultaneity differ. A declared execution.concurrency is a cap, clamped to [1, participants].
  * The planner records it; the route may only lower it from the environment.
  */
 export declare function boundedConcurrency(declared: number | undefined, participantCount: number): number;
 /**
- * Pure pre-flight plan resolver (runs in dry-run AND live). Returns the participant table, the
+ * Pure pre-flight plan resolver (runs in dry-run and live). Returns the participant table, the
  * effective concurrency, the wave count, the per-participant session budget, and the worst-case total
- * sandbox-minutes — BEFORE any sandbox or provider call. The same plan appears in dry-run,
+ * sandbox-minutes, before any sandbox or provider call. The same plan appears in dry-run,
  * marked $0 (dryRun: true).
  */
-export declare function resolveCuaParticipantPlan(config: LabConfig, opts?: {
+export declare function resolveCuaParticipantPlan(config: StudyConfig, opts?: {
     countOverride?: number;
     env?: Record<string, string | undefined>;
     dryRun?: boolean;
     personas?: Map<string, ResolvedPersona>;
 }): CuaParticipantPlan;
-/** Print the participant plan to stderr BEFORE any sandbox/provider call (public-safe: ids, devices,
- *  digests, and budgets only — no prompt text, no secrets). */
-export declare function emitPreflightPlan(participantPlan: CuaParticipantPlan, labId: string): void;
+/** Print the participant plan to stderr before any sandbox/provider call (public-safe: ids, devices,
+ *  digests, and budgets only; no prompt text, no secrets). */
+export declare function emitPreflightPlan(participantPlan: CuaParticipantPlan, studyId: string): void;
 export declare function formatParticipantPlanEntry(entry: CuaParticipantPlanEntry): string;
 /**
  * Compile the committed persona files the participants use, printing a warning for each one that
@@ -60,7 +60,7 @@ export declare function loadCuaParticipants(args: {
     rerunLineage?: RunRerunLineage;
 } | {
     ok: false;
-    code: CuaActorLabErrorCode;
+    code: CuaActorStudyErrorCode;
     message: string;
 }>;
 /** Scrub known secret values from each participant's declarative snapshot before any bundle uses it. */

package/dist/routes/computer-use/participant-runs.js

@@ -1,23 +1,24 @@
-// The participant runs a computer-use lab drives, built before anything is created: the sandbox
+// The participant runs a computer-use study drives, built before anything is created: the sandbox
 // and session budgets, the concurrency bound, each participant's prompt, bundle ids and artifact
 // paths, and the public plan printed before any sandbox or provider call. loadCuaParticipants
 // compiles the committed personas first and narrows a rerun to its selected participants.
-import { isLocalBrowserLab, LOCAL_BROWSER_LIFETIME_MS, } from "../../substrates/local/runtime-config.js";
+import { isLocalBrowserStudy, LOCAL_BROWSER_LIFETIME_MS, } from "../../substrates/local/runtime-config.js";
 import { DEFAULT_STATE_STEP_TIMEOUT_MS } from "../../subject/state.js";
-import { computerUseParticipants, } from "../../lab/plan-participants.js";
+import { computerUseParticipants, } from "../../study/plan-participants.js";
 import { resolveParticipant } from "../../run/participant.js";
-import {} from "../../lab/types.js";
-import { scrubPersonaBrief } from "../../lab/persona.js";
+import {} from "../../study/types.js";
+import { scrubPersonaBrief } from "../../study/persona.js";
 import { redactText } from "../../evidence/redaction.js";
 import {} from "../../run/bundle.js";
-import { participantAssignment } from "../../lab/participant-assignment.js";
-import { resolveCommittedPersonas } from "../../lab/persona-resolve.js";
+import { participantAssignment } from "../../study/participant-assignment.js";
+import { resolveCommittedPersonas } from "../../study/persona-resolve.js";
 import { CUA_FANOUT_STRATEGY, CUA_MAX_CONCURRENCY_ENV, DEFAULT_APP_URL_SESSION_TIMEOUT_MS, MIN_DERIVED_SESSION_TIMEOUT_MS, } from "./types.js";
 import { MAX_SANDBOX_MS, SANDBOX_TIMEOUT_BUFFER_MS, SUBJECT_PROVISION_BUDGET_MS, } from "../../substrates/e2b/lifetime.js";
-import { readPositiveInt } from "../../lab/parse/values.js";
+import { readPositiveInt } from "../../study/parse/values.js";
 import { digestUrl } from "./bundle-parts.js";
 import { composeParticipantInstructions, DEFAULT_MISSION } from "./participant-prompt.js";
 import { resolveCuaRerunSelection } from "./rerun-selection.js";
+import { plural } from "../../run/text.js";
 export function defaultSessionTimeoutMs(config) {
     const provisionedRoute = config.subject.source === "clone" || config.subject.source === "local-tree";
     if (!provisionedRoute)
@@ -33,7 +34,7 @@ export function defaultSessionTimeoutMs(config) {
  *  git clone for an upload+extract, but the shared install/build/state/start/probe pipeline
  *  costs the same wall-clock room either way. */
 export function resolveParticipantSandboxMs(config) {
-    if (isLocalBrowserLab(config))
+    if (isLocalBrowserStudy(config))
         return LOCAL_BROWSER_LIFETIME_MS;
     const timeoutMs = config.execution?.timeoutMs ?? defaultSessionTimeoutMs(config);
     const provisionedRoute = config.subject.source === "clone" || config.subject.source === "local-tree";
@@ -46,18 +47,18 @@ export function resolveParticipantSandboxMs(config) {
             SANDBOX_TIMEOUT_BUFFER_MS);
 }
 /**
- * The in-flight participant bound a lab declares. Defaults to the participant count — every
+ * The in-flight participant bound a study declares. Defaults to the participant count: every
  * declared participant runs at once, because a throttle nobody asked for silently turns "N actors
- * live" into waves (#350); total session count and spend are the same either way, only wall-clock
- * and simultaneity differ. A declared execution.concurrency is a CAP, clamped to [1, participants].
+ * live" into waves; total session count and spend are the same either way, only wall-clock
+ * and simultaneity differ. A declared execution.concurrency is a cap, clamped to [1, participants].
  * The planner records it; the route may only lower it from the environment.
  */
 export function boundedConcurrency(declared, participantCount) {
     return Math.max(1, declared === undefined ? participantCount : Math.min(Math.max(1, declared), participantCount));
 }
 /**
- * The planned bound, lowered by the env override. The override may only LOWER it (never raise
- * concurrent paid desktops — invariant 3), and a lowering is reported via envLoweredFrom so the
+ * The planned bound, lowered by the env override. The override may only lower it (never raise
+ * concurrent paid desktops), and a lowering is reported via envLoweredFrom so the
  * plan never silently disagrees with the manifest.
  */
 function envLoweredConcurrency(planned, participantCount, env) {
@@ -81,7 +82,7 @@ function plannedParticipantsOf(config, countOverride) {
         desktopCli: config.subject.source === "desktop-cli",
     };
 }
-/** Build the participant runs AND the public plan from the planned participants (pure). */
+/** Build the participant runs and the public plan from the planned participants (pure). */
 function participantRunsAndPlan(planned, opts = {}) {
     const env = opts.env ?? {};
     // Who each participant is (id, persona, focus, device, limits) comes from the plan; this adds
@@ -162,20 +163,20 @@ function participantRunsAndPlan(planned, opts = {}) {
     return { runs, participantPlan };
 }
 /**
- * Pure pre-flight plan resolver (runs in dry-run AND live). Returns the participant table, the
+ * Pure pre-flight plan resolver (runs in dry-run and live). Returns the participant table, the
  * effective concurrency, the wave count, the per-participant session budget, and the worst-case total
- * sandbox-minutes — BEFORE any sandbox or provider call. The same plan appears in dry-run,
+ * sandbox-minutes, before any sandbox or provider call. The same plan appears in dry-run,
  * marked $0 (dryRun: true).
  */
 export function resolveCuaParticipantPlan(config, opts = {}) {
     const { countOverride, ...rest } = opts;
     return participantRunsAndPlan(plannedParticipantsOf(config, countOverride), rest).participantPlan;
 }
-/** Print the participant plan to stderr BEFORE any sandbox/provider call (public-safe: ids, devices,
- *  digests, and budgets only — no prompt text, no secrets). */
-export function emitPreflightPlan(participantPlan, labId) {
+/** Print the participant plan to stderr before any sandbox/provider call (public-safe: ids, devices,
+ *  digests, and budgets only; no prompt text, no secrets). */
+export function emitPreflightPlan(participantPlan, studyId) {
     const lines = [];
-    lines.push(`humanish computer-use fan-out plan (${labId}): ${participantPlan.laneCount} participant(s), strategy ${participantPlan.strategy}, concurrency ${participantPlan.concurrency}${participantPlan.envLoweredConcurrencyFrom === undefined ? "" : ` (lowered from ${participantPlan.envLoweredConcurrencyFrom} by ${CUA_MAX_CONCURRENCY_ENV})`}, ${participantPlan.waves} wave(s).`);
+    lines.push(`humanish computer-use fan-out plan (${studyId}): ${plural(participantPlan.laneCount, "participant")}, strategy ${participantPlan.strategy}, concurrency ${participantPlan.concurrency}${participantPlan.envLoweredConcurrencyFrom === undefined ? "" : ` (lowered from ${participantPlan.envLoweredConcurrencyFrom} by ${CUA_MAX_CONCURRENCY_ENV})`}, ${plural(participantPlan.waves, "wave")}.`);
     lines.push(`  session budget ${Math.round(participantPlan.perLaneSessionBudgetMs / 1000)}s per participant; worst-case ~${participantPlan.worstCaseSandboxMinutes} sandbox-minutes total${participantPlan.dryRun ? " (dry-run: $0)" : ""}.`);
     for (const entry of participantPlan.lanes) {
         lines.push(`  - ${formatParticipantPlanEntry(entry)}`);
@@ -212,8 +213,8 @@ export async function compileParticipantPersonas(projectRoot, personaIds) {
 export async function loadCuaParticipants(args) {
     const { plan } = args;
     const { participants } = plan.runner;
-    // Compile any committed personas BEFORE planning, so the plan builder stays pure and each participant's
-    // prompt carries real behavioral directives rather than a bare `Persona: <id>.` label (#381).
+    // Compile any committed personas before planning, so the plan builder stays pure and each participant's
+    // prompt carries real behavioral directives rather than a bare `Persona: <id>.` label.
     const personas = await compileParticipantPersonas(args.projectRoot, participants.map((participant) => participant.personaId));
     const { runs: participantRuns, participantPlan } = participantRunsAndPlan({
         participants,
@@ -227,7 +228,7 @@ export async function loadCuaParticipants(args) {
         return { ok: true, participantRuns, participantPlan };
     const selected = await resolveCuaRerunSelection({
         cwd: args.cwd,
-        labId: plan.labId,
+        studyId: plan.studyId,
         sandboxMs: plan.sandboxMs,
         sourceRunId: rerun.sourceRunId,
         ...(rerun.participantIds === undefined ? {} : { participantIds: [...rerun.participantIds] }),
@@ -235,7 +236,7 @@ export async function loadCuaParticipants(args) {
         participantPlan,
     });
     if (!selected.ok) {
-        return { ok: false, code: "HUMANISH_CUA_LAB_RERUN_INVALID", message: selected.message };
+        return { ok: false, code: "HUMANISH_COMPUTER_USE_RERUN_INVALID", message: selected.message };
     }
     return {
         ok: true,

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

@@ -1,9 +1,9 @@
 import { type CuaActorDescriptor } from "../../actors/registry.js";
-import type { ComputerUsePlan, ComputerUseRunner, RoutePlanResult, RouteRefusal } from "../../lab/plan-types.js";
-import type { LabConfig, LabSubjectState } from "../../lab/types.js";
-import { type CuaActorLabErrorCode, type RunCuaActorLabOptions } from "./types.js";
-/** The error a computer-use lab returns before a run starts. */
-export interface ComputerUseRefusal extends RouteRefusal<"computer-use", CuaActorLabErrorCode> {
+import type { ComputerUsePlan, ComputerUseRunner, RoutePlanResult, RouteRefusal } from "../../study/plan-types.js";
+import type { StudyConfig, StudySubjectState } from "../../study/types.js";
+import { type CuaActorStudyErrorCode, type RunCuaActorStudyOptions } from "./types.js";
+/** The error a computer-use study returns before a run starts. */
+export interface ComputerUseRefusal extends RouteRefusal<"computer-use", CuaActorStudyErrorCode> {
     /**
      * Where the route returns it. "before-scope": analysis and tasks, returned before the run scope
      * with no automatic-analysis record. "in-scope": after the cwd checks. "after-personas": after
@@ -15,7 +15,7 @@ export interface ComputerUseRefusal extends RouteRefusal<"computer-use", CuaActo
     readonly actor?: string;
 }
 export type ComputerUsePlanResult = RoutePlanResult<ComputerUsePlan, ComputerUseRefusal>;
-/** 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 declare function cuaDescriptorOf(actor: string): CuaActorDescriptor;
 /** Which of the caller's driving homes, createProvider and inProcess, a run has. */
 export interface CallerDriving {
@@ -28,21 +28,21 @@ export declare function callerDrivingOf(options: {
     readonly createProvider?: unknown;
 }): CallerDriving;
 /** The state a planned run's provisioned subject declares. Other subjects declare none. */
-export declare function cuaDeclaredState(plan: ComputerUsePlan): LabSubjectState | undefined;
-/** The URL a refused lab's result names, from its declaration: a provisioned subject's serve URL. */
-export declare function declaredAppUrl(config: LabConfig): string;
+export declare function cuaDeclaredState(plan: ComputerUsePlan): StudySubjectState | undefined;
+/** The URL a refused study's result names, from its declaration: a provisioned subject's serve URL. */
+export declare function declaredAppUrl(config: StudyConfig): string;
 /** The URL a planned run's participants open: a provisioned subject's served URL, else its own. */
 export declare function plannedAppUrl(subject: ComputerUseRunner["subject"]): string;
 /**
- * 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 declare function planComputerUseLab(config: LabConfig, input: {
+export declare function planComputerUseStudy(config: StudyConfig, input: {
     readonly dryRun: boolean;
     /** Whether deps.runSession is set: a caller's session runner cannot enforce maxOutputTokens. */
     readonly hasRunSession?: boolean;
     /** Which of the caller's driving homes are set; neither when absent. */
     readonly driving?: CallerDriving;
     readonly countOverride?: number;
-    readonly rerun?: RunCuaActorLabOptions["rerun"];
+    readonly rerun?: RunCuaActorStudyOptions["rerun"];
 }): ComputerUsePlanResult;