humanish 0.107.0 → 0.109.0

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

@@ -1,47 +1,49 @@
-// The computer-use lab backend: a subject (an app-url the caller provisioned, or a repo the
-// lab clones AND serves in-sandbox) driven by a REGISTRY-RESOLVED computer-use actor inside a
-// hosted E2B desktop. This is the path that makes `actors[].type` load-bearing — the
-// descriptor returned by the registry runs the session; the lab provisions the desktop and
+// The computer-use route: a subject (an app-url the caller provisioned, or a repo the
+// humanish clones and serves in the sandbox) driven by a registry-resolved computer-use actor inside a
+// hosted E2B desktop. On this path `actors[].type` selects the actor: the
+// descriptor returned by the registry runs the session; the route provisions the desktop and
 // subject, composes the prompt from config, persists the evidence bundle, and tears down.
 //
 // Substrate notes:
 // - The desktop is created via the shared loader in src/substrates/e2b/sdk.ts with
 //   kill-on-timeout lifecycle, so a dead host process can never orphan a sandbox past its
 //   server-side deadline.
-// - Env placement follows the doctrine (docs/principles/invariants-and-defaults.md): the
-//   ACTOR's key never enters the sandbox (the model drives from outside via the provider API);
-//   the SUBJECT's declared env NAMES are provisioned in on the clone route — values come from
+// - Env placement follows the placement rule (docs/principles/invariants-and-defaults.md): the
+//   actor's key never enters the sandbox (the model drives from outside via the provider API);
+//   the subject's declared env names are provisioned in on the clone route; values come from
 //   the caller's environment and are never logged or persisted.
 // - The live stream URL is runtime-only (carries an auth key) and is never persisted into run
-//   artifacts — only its presence is recorded.
+//   artifacts; only its presence is recorded.
 // - Evidence redaction is mode-aware (docs/principles/invariants-and-defaults.md, the
-//   capture-vs-publish rule): screenshots persist RAW (full fidelity) by default into gitignored
+//   capture-vs-publish rule): screenshots persist raw (full fidelity) by default into gitignored
 //   .humanish/; `policies.redactScreenshots: true` opts into blur-at-capture for a share-as-is
-//   bundle. Length-only typed text and text redaction of reasoning/messages are UNCONDITIONAL;
-//   harness errors are redacted at THIS boundary; the bundle's `stream.actor` carries the
+//   bundle. Length-only typed text and text redaction of reasoning/messages are unconditional;
+//   harness errors are redacted at this boundary; the bundle's `stream.actor` carries the
 //   conformant humanish.actor-trace.v1 projection, whose `redaction.screenshots` records the
-//   run's actual mode ("raw" | "blurred" | "n/a") — every label downstream derives from it.
+//   run's actual mode ("raw" | "blurred" | "n/a"), and every label downstream derives from it.
 import { withTransientCommsSecrets } from "../../run/transient-comms-secrets.js";
 import path from "node:path";
 import { completeAutomaticAnalysis } from "../../analysis/automatic-completion.js";
 import { runScope } from "../../run/run.js";
 import { resolveAutomaticAnalysis } from "../../analysis/automatic-config.js";
-import { browserRouteScorer } from "../../lab/adapter-scorer-loader.js";
-import { withLateScorer } from "../../lab/route-inputs.js";
-import { callerDrivingOf, planComputerUseLab } from "./plan.js";
+import { browserRouteScorer } from "../../study/adapter-scorer-loader.js";
+import { withLateScorer } from "../../study/route-inputs.js";
+import { callerDrivingOf, planComputerUseStudy } from "./plan.js";
 import { finishCuaRun } from "./result.js";
-import { runLabParticipants } from "./live-phase.js";
-import { admitCuaRun, refuseCuaLab, startCuaRun } from "./setup.js";
-import { CUA_ACTOR_LAB_SCHEMA, } from "./types.js";
+import { runStudyParticipants } from "./live-phase.js";
+import { admitCuaRun, refuseCuaStudy, startCuaRun } from "./setup.js";
+import {} from "./types.js";
+import { studyResultIdentity } from "../../run/study-result.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 async function runCuaActorLab(options) {
+export async function runCuaActorStudy(options) {
     const { config, dryRun, ...input } = options;
-    // planComputerUseLab makes every configuration refusal, in the order this route always has.
-    const planned = planComputerUseLab(config, {
+    // planComputerUseStudy makes every configuration refusal, in the order this route always has.
+    const planned = planComputerUseStudy(config, {
         dryRun,
         hasRunSession: input.deps?.runSession !== undefined,
         driving: callerDrivingOf(input),
@@ -50,21 +52,20 @@ export async function runCuaActorLab(options) {
     });
     if (planned.ok)
         return runComputerUsePlan(planned.plan, input, config);
-    return computerUseLabRefusal(options, planned.refusal);
+    return computerUseStudyRefusal(options, planned.refusal);
 }
 /**
- * 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 async function computerUseLabRefusal(options, refusal) {
+export async function computerUseStudyRefusal(options, refusal) {
     const { config, dryRun } = options;
     if (refusal.stage === "before-scope")
         return {
-            schema: CUA_ACTOR_LAB_SCHEMA,
+            ...studyResultIdentity("computer-use", config.id),
             ok: false,
             cwd: path.resolve(options.cwd),
-            labId: config.id,
             actor: config.actors[0]?.type ?? "",
             dryRun,
             runId: options.runId ?? "not-created",
@@ -75,10 +76,10 @@ export async function computerUseLabRefusal(options, refusal) {
         };
     // The other refusals come after the cwd checks, and the participant cap after the personas are read.
     const analysis = resolveAutomaticAnalysis(config.review?.analysis);
-    return completeAutomaticAnalysis(await refuseCuaLab(options, refusal), undefined, analysis.ok ? analysis.config : undefined, options, { trigger: config.review?.analysis === undefined ? "default" : "explicit" });
+    return completeAutomaticAnalysis(await refuseCuaStudy(options, refusal), undefined, analysis.ok ? analysis.config : undefined, options, { trigger: config.review?.analysis === undefined ? "default" : "explicit" });
 }
 /**
- * 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.
@@ -140,7 +141,7 @@ async function runPlanInScope(plan, input, admitted, scope) {
     const prepared = await startCuaRun(plan, input, admitted, scope);
     if (!prepared.ok)
         return prepared.result;
-    const ran = await runLabParticipants(prepared.setup, prepared.participants);
+    const ran = await runStudyParticipants(prepared.setup, prepared.participants);
     if (!ran.ok)
         return ran.result;
     return finishCuaRun(prepared.setup, prepared.finish, ran);

package/dist/routes/computer-use/self-report.d.ts

@@ -1,21 +1,21 @@
 import type { CuaLoopResult } from "../../actors/computer-use/loop.js";
 import { type SessionEnding } from "../../run/judge.js";
 /**
- * A goal_satisfied participant counts as a self-reported blocker ONLY when its final narrative contradicts
- * the goal AND the run's own stop predicate did NOT fire. A matched stopWhen is independent,
- * structured completion evidence, so it overrides a text scan of the free-form narrative — which can
- * otherwise trip on the subject app's OWN quoted copy (e.g. a relayed "cannot be undone" banner).
- * Resolved-arc segments never block the verdict (#453). Returns the offending reason, or undefined
+ * A goal_satisfied participant counts as a self-reported blocker only when its final narrative contradicts
+ * the goal and the run's own stop predicate did not fire. A matched stopWhen is independent,
+ * structured completion evidence, so it overrides a text scan of the free-form narrative, which can
+ * otherwise trip on the subject app's own quoted copy (e.g. a relayed "cannot be undone" banner).
+ * Resolved-arc segments never block the verdict. Returns the offending reason, or undefined
  * when the participant is a clean pass. Exported for testing.
  */
 export declare function resolveSelfReportedBlocker(session: CuaLoopResult | undefined): string | undefined;
 /** A session's ending, reduced to what the judge's engagement and blocker rules read. */
 export declare function sessionEnding(session: CuaLoopResult): SessionEnding;
 /**
- * Friction is independent of how a completed session ended (#657). Read the participant's
+ * Friction is independent of how a completed session ended. Read the participant's
  * redacted messages, including earlier reports, rather than the harness-owned reason that
  * stopWhen/dwell writes. Reasoning, observations, and notices are not participant reports.
- * Resolved arcs still count (#453); quoted copy and negated reports still do not. This read
+ * Resolved arcs still count; quoted copy and negated reports still do not. This read
  * never changes the verdict. Exported for testing.
  */
 export declare function resolveSelfReportedFriction(session: CuaLoopResult | undefined): string | undefined;

package/dist/routes/computer-use/self-report.js

@@ -1,12 +1,12 @@
 import { selfReportedBlocker } from "../../run/judge.js";
-// "can't" followed by a PERCEPTION verb describes what the screen showed, not an inability to
+// "can't" followed by a perception verb describes what the screen showed, not an inability to
 // proceed: "the canvas truncates it so you can't even read the whole thing", "I can't tell from
 // the screen whether the rename is persisted", "so I could not read its full description". Five
 // of five completed live runs on 2026-09-01 (two on drawDB, three on the planted benchmark app)
 // were refused as "not a credible pass" on exactly these sentences, every one a defect report
-// written AFTER the participant reached the goal. The more precisely a participant describes a
-// display defect, the more likely the scan was to refuse the run — the incentive inversion #453
-// fixed for resolved arcs, back in a new shape. "could not complete", "could not connect",
+// written after the participant reached the goal. The more precisely a participant describes a
+// display defect, the more likely the scan was to refuse the run: the incentive inversion the
+// resolved-arc rule fixed, back in a new shape. "could not complete", "could not connect",
 // "unable to get focus" still count: those name an inability to act.
 const PERCEPTION_AFTER_MODAL = /\b(can'?t|cannot|could ?not|couldn'?t|unable to|wasn'?t able to)\s+(even\s+|quite\s+|really\s+|fully\s+)?(read|see|tell|view|make out|verify|confirm|be sure|be certain|judge|know)\b/g;
 function hasBlockerLanguage(text) {
@@ -15,17 +15,17 @@ function hasBlockerLanguage(text) {
         /\berror[:.]/.test(text) ||
         /what would you like me to do|please tell me|need (the )?(task|credentials|instructions)/.test(text));
 }
-/** The friction scan (inclusive): does the narrative report ANY blocker-shaped language,
+/** The friction scan (inclusive): does the narrative report any blocker-shaped language,
  *  resolved or not? Feeds the participants `reportedFriction` tally and feedback candidates. */
-// Report-shaped language: what a participant writes when it finished AND has something to say.
+// Report-shaped language: what a participant writes when it finished and has something to say.
 // Every one of the day's eleven drawDB reports (2026-09-01) opened a section "What confused me"
 // or "Accessibility defects:"; none contained a blocker word, so none became a feedback candidate
 // and a participant that had just replicated a keyboard-accessibility defect three times drafted "Live
-// study completed without a participant-reported finding". Friction is the INCLUSIVE scan; a
+// study completed without a participant-reported finding". Friction is the inclusive scan; a
 // false positive here adds a candidate a person then reads, which is the cheap direction.
 const REPORTED_DEFECT_LANGUAGE = /\b(defects?|bugs?|accessibilit(y|ies)|inaccessible|not (keyboard|screen.?reader)[- ]?accessible|confus(ed|ing)|hesitat(ed|ion)|unexpected(ly)?|unclear|hard to (find|tell|see|read|reach)|no (visible )?focus|overlap(ped|ping|s)?|truncat(ed|es|ion)|cut off|did nothing|nothing happened|no effect)\b/;
-// The friction scan's own negations (#614). "Nothing was confusing", "no defects", "not unclear"
-// are what a participant writes when it has NOTHING to report, and until 2026-09-03 each of them
+// The friction scan's own negations. "Nothing was confusing", "no defects", "not unclear"
+// are what a participant writes when it has nothing to report, and until 2026-09-03 each of them
 // counted as reported friction and became a feedback candidate whose "actual" was a sentence
 // reporting no problem. Only the report-shaped adjectives are negatable here: "no visible focus",
 // "not keyboard-accessible" and "did nothing" are defects and stay.
@@ -80,25 +80,25 @@ function interimMessageReportsFriction(message) {
     });
 }
 /** The verdict scan (strict): like the friction scan, but resolved-arc segments are stripped
- *  first — failure narration the participant itself reports as overcome is friction on the
- *  road, not a blocker at the destination (#453). */
+ *  first: failure narration the participant itself reports as overcome counts as friction and
+ *  never as a blocker. */
 function completionReasonBlocksVerdict(reason) {
-    // Perception phrases are stripped for the VERDICT only: "I could not read the full description"
+    // Perception phrases are stripped for the verdict only: "I could not read the full description"
     // is friction worth a tally count and a feedback candidate (the friction scan above keeps it),
     // and it is not a reason to refuse the pass.
     return hasBlockerLanguage(stripResolvedArcSegments(stripQuotedSpans(stripNegatedNonBlockerPhrases(reason.toLowerCase()))).replace(PERCEPTION_AFTER_MODAL, ""));
 }
 // A failure segment counts as a resolved arc when the recovery is self-reported either in the
-// SAME segment ("the import failed but then went through") or — the common report shape — in the
-// immediately FOLLOWING segment as a retry/alternative that succeeded ("my first import failed
+// same segment ("the import failed but then went through") or, in the common report shape, in the
+// immediately following segment as a retry/alternative that succeeded ("my first import failed
 // with a parser error. A simpler SQL import succeeded."). The lookahead demands the retry flavor
 // on purpose: unrelated praise ("Separately, the search box worked") must never launder an
 // unresolved failure. "Login failed so I gave up" has no recovery anywhere and stays a blocker.
-// (#453 — the run-1 false negative: a defect report after demonstrated success failed the participant,
+// (Without this, a defect report after demonstrated success failed the participant:
 // an incentive inversion against exactly the participant behavior a study wants most.)
 const RESOLUTION_TERMS = /\b(succeed(?:ed|s)?|success(?:ful|fully)?|worked|works around|then worked|now works?|resolved|fixed|recovered|got it working|went through)\b/;
 const RETRY_RESOLUTION = /\b(simpler|simplified|retry(?:ing)?|retried|second (?:attempt|try)|another (?:attempt|try|approach)|different (?:approach|way|route)|instead|then|eventually|after that)\b[^.!?\n]{0,80}\b(succeed(?:ed|s)?|success(?:ful|fully)?|worked|went through|completed|passed)\b/;
-/** Drop sentence/bullet segments whose failure language is part of a self-reported RESOLVED arc. */
+/** Drop sentence/bullet segments whose failure language is part of a self-reported resolved arc. */
 function stripResolvedArcSegments(text) {
     const segments = text.split(/(?<=[.!?])\s+|\n+/);
     return segments
@@ -112,20 +112,20 @@ function stripResolvedArcSegments(text) {
     })
         .join(" ");
 }
-// Negations that DESCRIBE a defect rather than deny one. Kept out of every clause drop below.
+// Negations that describe a defect rather than deny one. Kept out of every clause drop below.
 const DEFECT_SHAPED_NEGATION = /\bno\s+(?:visible\s+)?focus\b|\bno\s+(?:keyboard|screen.?reader)[- ]?(?:access|path|route|way|alternative|equivalent)|\bnot\s+(?:keyboard|screen.?reader)[- ]?accessible\b|\bno\s+(?:effect|feedback|response)\b|\b(?:did|does)\s+nothing\b|\bnothing\s+happened\b/;
 function stripNegatedNonBlockerPhrases(text) {
     return (text
-        // FIRST, before the narrower rules eat the "no blockers" and leave "encountered ... error"
+        // First, before the narrower rules eat the "no blockers" and leave "encountered ... error"
         // behind: "I encountered no blockers or unclear error output." refused a clean passing run on
         // 2026-09-01. A verb of encounter followed by "no" negates the whole clause, so drop the clause.
-        // ... unless the clause names a DEFECT: "the delete control had no visible focus" is a
-        // finding, and the verb it happens to use must not decide whether it counts (#622).
+        // ... unless the clause names a defect: "the delete control had no visible focus" is a
+        // finding, and the verb it happens to use must not decide whether it counts.
         .replace(/\b(?:encountered|hit|saw|found|met|had|got|ran into)\s+no\s+[^.!?\n]*/g, (clause) => (DEFECT_SHAPED_NEGATION.test(clause) ? clause : " "))
         .replace(/\bno\s+(?:real\s+|remaining\s+|actual\s+)?(?:blocker|blockers|blocking issue|blocking issues|error|errors|failure|failures)\s+(?:was\s+|were\s+)?(?:encountered|observed|found|hit|seen|reported|detected)\b/g, "")
         .replace(/\bwithout\s+(?:a\s+|any\s+)?(?:real\s+|remaining\s+|actual\s+)?(?:blocker|blockers|blocking issue|blocking issues|error|errors|failure|failures)\b/g, "")
         .replace(/\bnot\s+(?:blocked|a blocker|an error|failed)\b/g, "")
-        // "No functional failures blocked me" downgraded a clean passing run to a lab failure on
+        // "No functional failures blocked me" downgraded a clean passing run to a run failure on
         // 2026-09-01. The adjective list above is closed (real|remaining|actual), so an ordinary
         // qualifier like "functional" slipped through and the trailing verb "blocked" tripped the
         // scan. Allow up to two intervening words, and cover the verb form directly.
@@ -134,9 +134,9 @@ function stripNegatedNonBlockerPhrases(text) {
 }
 /**
  * Remove double-quoted spans and markdown blockquote lines before the blocker scan, so a persona
- * that faithfully QUOTES the subject app's own copy (e.g. a banner reading "cannot be undone") is
- * not misread as the actor reporting its OWN blocker. Only double quotes (straight and smart) and
- * `>` blockquotes are stripped — never single quotes, which would mangle contractions like `can't`.
+ * that faithfully quotes the subject app's own copy (e.g. a banner reading "cannot be undone") is
+ * not misread as the actor reporting its own blocker. Only double quotes (straight and smart) and
+ * `>` blockquotes are stripped, never single quotes, which would mangle contractions like `can't`.
  */
 function stripQuotedSpans(text) {
     return text
@@ -148,15 +148,15 @@ function traceHasStopWhenMatch(session) {
     return session.trace.items.some((item) => item.kind === "notice" &&
         item.status === "matched" &&
         // A dwell window that ended the session (then: stop) is the same class of harness-owned,
-        // structured completion as a matched stopWhen (#510).
+        // structured completion as a matched stopWhen.
         (item.title.startsWith("stopWhen matched") || item.title === "dwell window complete"));
 }
 /**
- * A goal_satisfied participant counts as a self-reported blocker ONLY when its final narrative contradicts
- * the goal AND the run's own stop predicate did NOT fire. A matched stopWhen is independent,
- * structured completion evidence, so it overrides a text scan of the free-form narrative — which can
- * otherwise trip on the subject app's OWN quoted copy (e.g. a relayed "cannot be undone" banner).
- * Resolved-arc segments never block the verdict (#453). Returns the offending reason, or undefined
+ * A goal_satisfied participant counts as a self-reported blocker only when its final narrative contradicts
+ * the goal and the run's own stop predicate did not fire. A matched stopWhen is independent,
+ * structured completion evidence, so it overrides a text scan of the free-form narrative, which can
+ * otherwise trip on the subject app's own quoted copy (e.g. a relayed "cannot be undone" banner).
+ * Resolved-arc segments never block the verdict. Returns the offending reason, or undefined
  * when the participant is a clean pass. Exported for testing.
  */
 export function resolveSelfReportedBlocker(session) {
@@ -187,10 +187,10 @@ export function sessionEnding(session) {
     };
 }
 /**
- * Friction is independent of how a completed session ended (#657). Read the participant's
+ * Friction is independent of how a completed session ended. Read the participant's
  * redacted messages, including earlier reports, rather than the harness-owned reason that
  * stopWhen/dwell writes. Reasoning, observations, and notices are not participant reports.
- * Resolved arcs still count (#453); quoted copy and negated reports still do not. This read
+ * Resolved arcs still count; quoted copy and negated reports still do not. This read
  * never changes the verdict. Exported for testing.
  */
 export function resolveSelfReportedFriction(session) {

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

@@ -1,26 +1,26 @@
 import { type RunScope } from "../../run/run.js";
 import type { CuaActorDescriptor } from "../../actors/registry.js";
-import type { LabCommsEmail, LabCommsExternal, LabConfig } from "../../lab/types.js";
+import type { StudyCommsEmail, StudyCommsExternal, StudyConfig } from "../../study/types.js";
 import { type RunRerunLineage } from "../../run/bundle.js";
 import { type LocalTreeArchive } from "../../subject/local-tree-archive.js";
 import { type ComputerUseRefusal } from "./plan.js";
-import type { ComputerUsePlan } from "../../lab/plan-types.js";
+import type { ComputerUsePlan } from "../../study/plan-types.js";
 import { trackRuntimeStreams, type LiveTraceFlush } from "./live-flush.js";
 import { type CuaRunBundleBase } from "./bundle.js";
 import { projectParticipantSubjects } from "./subject-projection.js";
-import { type CuaActorLabErrorCode, type CuaActorLabResult, type CuaParticipantDeps, type CuaParticipantPlan, type DesktopParticipantRun, type CuaSubjectProjection, type CuaSubjectProvenanceArg, type ComputerUseRunInput, type RunCuaActorLabOptions } from "./types.js";
+import { type CuaActorStudyErrorCode, type CuaActorStudyResult, type CuaParticipantDeps, type CuaParticipantPlan, type DesktopParticipantRun, type CuaSubjectProjection, type CuaSubjectProvenanceArg, type ComputerUseRunInput, type RunCuaActorStudyOptions } from "./types.js";
 /**
  * The envelope of a refusal the plan left for after the cwd checks. The participant cap and
  * in-process fan-out refusals come after the committed personas are read, so a persona-file error still wins.
  */
-export declare function refuseCuaLab(options: RunCuaActorLabOptions, refusal: ComputerUseRefusal): Promise<CuaActorLabResult>;
+export declare function refuseCuaStudy(options: RunCuaActorStudyOptions, refusal: ComputerUseRefusal): Promise<CuaActorStudyResult>;
 export type AdmittedCuaRun = Extract<Awaited<ReturnType<typeof admitCuaRun>>, {
     ok: true;
 }>["admitted"];
 type StartedRun = Extract<Awaited<ReturnType<RunScope["startRun"]>>, {
     ok: true;
 }>["run"];
-/** What runLabParticipants and finishCuaRun both read. */
+/** What runStudyParticipants and finishCuaRun both read. */
 export interface CuaRunSetup {
     plan: ComputerUsePlan;
     input: ComputerUseRunInput;
@@ -34,22 +34,22 @@ export interface CuaRunSetup {
     scrubKnownValues: (text: string) => string;
     bundleBase: CuaRunBundleBase;
 }
-/** What only runLabParticipants reads. */
+/** What only runStudyParticipants reads. */
 export interface CuaParticipantsSetup {
     env: Record<string, string | undefined>;
     /** The array scrubKnownValues reads at each call. Email receiving appends the values it
      *  provisions before the participants run. */
     knownSecretValues: string[];
     deps: Omit<CuaParticipantDeps, "signalProvisioned">;
-    /** Filled by runLabParticipants on a live run; deps.onTrace reads it. */
+    /** Filled by runStudyParticipants on a live run; deps.onTrace reads it. */
     liveTrace: {
         flush?: LiveTraceFlush["flush"];
         stop?: LiveTraceFlush["stop"];
     };
     /** The operator-hosted inbox on the app-url route, when declared. */
     externalComms: {
-        config: LabCommsExternal;
-        email: LabCommsEmail;
+        config: StudyCommsExternal;
+        email: StudyCommsEmail;
     } | undefined;
     /** The subjects of the in-progress bundle, written before any participant starts. */
     inProgress: {
@@ -58,7 +58,7 @@ export interface CuaParticipantsSetup {
         provenance: CuaSubjectProvenanceArg | undefined;
     };
     /** The refusal envelope, for a run that stops before its bundle. */
-    fail: (code: CuaActorLabErrorCode, message: string, actorLabel?: string) => CuaActorLabResult;
+    fail: (code: CuaActorStudyErrorCode, message: string, actorLabel?: string) => CuaActorStudyResult;
 }
 /** What only finishCuaRun reads besides the participants' outcomes. */
 export interface CuaFinishFacts {
@@ -68,7 +68,7 @@ export interface CuaFinishFacts {
 }
 type PreparedCuaRun = {
     ok: false;
-    result: CuaActorLabResult;
+    result: CuaActorStudyResult;
 } | {
     ok: true;
     setup: CuaRunSetup;
@@ -78,21 +78,21 @@ type PreparedCuaRun = {
 /**
  * Everything before the run starts: the physical project, the route, the participant plan and
  * preflight, the key and subject-env scrubber, the live checks that need no sandbox, and the
- * local-tree archive. These read files, env and the network, which planLab does not. Returns the
+ * local-tree archive. These read files, env and the network, which planStudy does not. Returns the
  * refusal, or what startCuaRun reads.
  */
-export declare function admitCuaRun(plan: ComputerUsePlan, input: ComputerUseRunInput, config: LabConfig): Promise<{
+export declare function admitCuaRun(plan: ComputerUsePlan, input: ComputerUseRunInput, config: StudyConfig): Promise<{
     ok: false;
-    result: CuaActorLabResult;
+    result: CuaActorStudyResult;
 } | {
     ok: true;
     admitted: {
-        config: LabConfig;
+        config: StudyConfig;
         dryRun: boolean;
         cwd: string;
-        seams: import("../../lab/lab-deps.js").LabDeps;
+        seams: import("../../study/study-deps.js").StudyDeps;
         streams: {
-            onStream: NonNullable<import("../../lab/run-lab-homes.js").RunLabHomes["onStream"]>;
+            onStream: NonNullable<import("../../study/run-study-homes.js").RunStudyHomes["onStream"]>;
             showIn: (observer: import("../../index.js").ObserverResult & {
                 ok: true;
             }) => void;
@@ -100,15 +100,15 @@ export declare function admitCuaRun(plan: ComputerUsePlan, input: ComputerUseRun
         };
         env: Record<string, string | undefined>;
         appUrl: string;
-        fail: (code: CuaActorLabErrorCode, message: string, actorLabel?: string) => CuaActorLabResult;
-        refuse: (code: CuaActorLabErrorCode, message: string, actorLabel?: string | undefined) => {
+        fail: (code: CuaActorStudyErrorCode, message: string, actorLabel?: string) => CuaActorStudyResult;
+        refuse: (code: CuaActorStudyErrorCode, message: string, actorLabel?: string | undefined) => {
             ok: false;
-            result: CuaActorLabResult;
+            result: CuaActorStudyResult;
         };
         descriptor: CuaActorDescriptor;
-        runSession: (options: import("../../actors/computer-use/actor.js").CuaActorSessionOptions) => Promise<import("../../index.js").CuaLoopResult>;
-        externalCommsConfig: LabCommsExternal | undefined;
-        externalCommsEmail: LabCommsEmail | undefined;
+        runSession: (options: import("../../actors/computer-use/actor.js").CuaActorSessionOptions) => Promise<import("../../index.js").ComputerUseLoopResult>;
+        externalCommsConfig: StudyCommsExternal | undefined;
+        externalCommsEmail: StudyCommsEmail | undefined;
         participantRuns: DesktopParticipantRun[];
         participantPlan: CuaParticipantPlan;
         rerunLineage: RunRerunLineage | undefined;

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

@@ -17,13 +17,14 @@ import { e2bRequestTimeoutMs } from "../../substrates/e2b/lifetime.js";
 import { liveCuaRejection } from "./preflight.js";
 import { cuaDescriptorOf, declaredAppUrl, plannedAppUrl } from "./plan.js";
 import { trackRuntimeStreams } from "./live-flush.js";
-import { participantOf, phaseEvent, planEvent } from "../../lab/run-lab-events.js";
+import { phaseEvent, planEvent } from "../../study/run-study-events.js";
 import { defaultSubjectPhaseSink } from "../../subject/steps.js";
 import {} from "./bundle.js";
 import { packRunLocalTree } from "./local-tree-pack.js";
 import { projectParticipantSubjects, subjectProvenanceArg } from "./subject-projection.js";
-import { CUA_ACTOR_LAB_SCHEMA, participantSubjectEnv, } from "./types.js";
-import { labPersonaIds } from "../../lab/persona-resolve.js";
+import { participantSubjectEnv, } from "./types.js";
+import { studyPersonaIds } from "../../study/persona-resolve.js";
+import { studyResultIdentity } from "../../run/study-result.js";
 /** The physical project, bound before any caller hook runs. */
 async function bindProject(cwd) {
     // Capture the physical project before reading or invoking any caller hook. A supported
@@ -36,17 +37,16 @@ async function bindProject(cwd) {
  * The envelope of a refusal the plan left for after the cwd checks. The participant cap and
  * in-process fan-out refusals come after the committed personas are read, so a persona-file error still wins.
  */
-export async function refuseCuaLab(options, refusal) {
+export async function refuseCuaStudy(options, refusal) {
     const { config, dryRun } = options;
     const projectRoot = await bindProject(options.cwd);
     // The committed personas are read before the refusal returns, so a persona-file error wins.
     if (refusal.stage === "after-personas")
-        await compileParticipantPersonas(projectRoot, labPersonaIds(config));
+        await compileParticipantPersonas(projectRoot, studyPersonaIds(config));
     return {
-        schema: CUA_ACTOR_LAB_SCHEMA,
+        ...studyResultIdentity("computer-use", config.id),
         ok: false,
         cwd: projectRoot.physicalPath,
-        labId: config.id,
         actor: refusal.actor ?? config.actors[0]?.type ?? "",
         appUrl: declaredAppUrl(config),
         dryRun,
@@ -59,7 +59,7 @@ export async function refuseCuaLab(options, refusal) {
 /**
  * Everything before the run starts: the physical project, the route, the participant plan and
  * preflight, the key and subject-env scrubber, the live checks that need no sandbox, and the
- * local-tree archive. These read files, env and the network, which planLab does not. Returns the
+ * local-tree archive. These read files, env and the network, which planStudy does not. Returns the
  * refusal, or what startCuaRun reads.
  */
 export async function admitCuaRun(plan, input, config) {
@@ -74,10 +74,9 @@ export async function admitCuaRun(plan, input, config) {
     const appUrl = plannedAppUrl(subject);
     const subjectEnvNames = [...participantSubjectEnv(subject)];
     const fail = (code, message, actorLabel) => ({
-        schema: CUA_ACTOR_LAB_SCHEMA,
+        ...studyResultIdentity("computer-use", plan.studyId),
         ok: false,
         cwd,
-        labId: plan.labId,
         actor: actorLabel ?? plan.actor,
         appUrl,
         dryRun,
@@ -90,13 +89,13 @@ export async function admitCuaRun(plan, input, config) {
         ok: false,
         result: fail(...args),
     });
-    // runLab's local VM study supplies a local-target app-url lab's desktop; a direct route call or
-    // an in-process executor on the same lab has none. It reads the declared source, as the planner
+    // runStudyWith's local VM study supplies a local-target app-url study's desktop; a direct route call or
+    // an in-process executor on the same study has none. It reads the declared source, as the planner
     // did: a library config the parser never saw can plan to an app-url subject from another source.
     if (config.subject.source === "app-url" &&
         config.execution?.target === "local" &&
         input.localVm === undefined)
-        return refuse("HUMANISH_CUA_LAB_LOCAL_DESKTOP_MISSING", "An app-url lab with execution.target: local needs a local desktop. runLab starts one; a direct route call or an in-process executor does not.");
+        return refuse("HUMANISH_COMPUTER_USE_LOCAL_DESKTOP_MISSING", "An app-url study with execution.target: local needs a local desktop. runStudy starts one; a direct route call or an in-process executor does not.");
     const descriptor = cuaDescriptorOf(plan.actor);
     const baseRunSession = seams.runSession ?? descriptor.runSession;
     // A local VM study's sessions abort on its signal.
@@ -104,11 +103,11 @@ export async function admitCuaRun(plan, input, config) {
     const runSession = localVmSignal === undefined
         ? baseRunSession
         : (options) => baseRunSession({ ...options, signal: localVmSignal });
-    // Adopter-hosted comms plane on the app-url route (#380): humanish provisions no subject here,
-    // so it cannot host a catch — the OPERATOR runs one, and humanish still does every other part
+    // Adopter-hosted comms plane on the app-url route: humanish provisions no subject here,
+    // so it cannot host a catch. The operator runs one, and humanish still does every other part
     // of the funnel: tells each persona its address and inbox URL, drains the catch over HTTP after
     // the participants, and writes the same digest-only evidence. Declaring `external` previously did
-    // nothing on this route (and, per #387, on every other) while its docs said otherwise.
+    // nothing on this route (or on any other) while its docs said otherwise.
     const comms = plan.residual.comms;
     const externalCommsConfig = subject.kind !== "clone" && subject.kind !== "local-tree" && !inProcess
         ? comms?.email?.external
@@ -120,11 +119,11 @@ export async function admitCuaRun(plan, input, config) {
     }
     const { participantRuns, participantPlan, rerunLineage } = participants;
     const participantCount = participantRuns.length;
-    // Pre-flight plan: BEFORE any sandbox or provider call (dry-run AND live). onEvent gets it for
+    // Pre-flight plan: before any sandbox or provider call (dry-run and live). onEvent gets it for
     // every N; the stderr table prints for fan-out (N>1) so single-participant runs stay as quiet as they
     // always were.
     if (participantCount > 1) {
-        emitPreflightPlan(participantPlan, plan.labId);
+        emitPreflightPlan(participantPlan, plan.studyId);
     }
     input.emit?.(planEvent(participantPlan));
     await assertPreparedSelectedOutputDirectory(projectRoot);
@@ -141,7 +140,7 @@ export async function admitCuaRun(plan, input, config) {
     sanitizeParticipantRuns(participantRuns, scrubKnownValues);
     const redactRepoLabel = plan.residual.policies?.redactRepos ?? subjectEnvNames.includes("GITHUB_TOKEN");
     const publicRepo = subject.kind === "clone" ? (redactRepoLabel ? "repo-01" : subject.repo) : undefined;
-    // Key-gating is route-aware: the in-process route uses the caller's OWN model + executor, and
+    // Key-gating is route-aware: the in-process route uses the caller's own model + executor, and
     // the local-agent route uses a CLI the operator has already signed in to.
     if (!dryRun && !inProcess) {
         const rejection = await liveCuaRejection({
@@ -154,8 +153,8 @@ export async function admitCuaRun(plan, input, config) {
         if (rejection)
             return refuse(rejection.code, rejection.message, descriptor.id);
     }
-    // Pack the working tree ONCE per run, on the host, BEFORE any sandbox or provider call: every
-    // fan-out participant below uploads this SAME archive, so one archiveSha256 describes every
+    // Pack the working tree once per run, on the host, before any sandbox or provider call: every
+    // fan-out participant below uploads this same archive, so one archiveSha256 describes every
     // participant's digest. Dry-run packs nothing (no fs side effects; the contract bundle carries no
     // archiveSha256). A packing failure fails the run closed here, before any sandbox is
     // created and before the run directory exists.
@@ -168,7 +167,7 @@ export async function admitCuaRun(plan, input, config) {
             localTreeArchiveBuffer = packed.buffer;
         }
         catch (error) {
-            return refuse("HUMANISH_CUA_LAB_SUBJECT_INVALID", `local-tree packing failed: ${redactText(scrubKnownValues(toErrorMessage(error)))}`, descriptor.id);
+            return refuse("HUMANISH_COMPUTER_USE_SUBJECT_INVALID", `local-tree packing failed: ${redactText(scrubKnownValues(toErrorMessage(error)))}`, descriptor.id);
         }
     }
     return {
@@ -206,14 +205,14 @@ export async function startCuaRun(plan, input, admitted, scope) {
     const { dryRun, cwd, seams, descriptor, participantRuns, participantPlan, publicRepo } = admitted;
     const { appUrl } = admitted;
     // The run's status record exists from here on, so anything watching the runs directory can
-    // tell which lab this is and that it is alive. The fail-closed returns below leave it finished
+    // tell which study this is and that it is alive. The fail-closed returns below leave it finished
     // with no outcome when the scope closes; a crash leaves it stale, which reads as interrupted.
     const started = await scope.startRun({
         cwd,
         runId: input.runId,
         mintRunId: makeCuaRunId,
         mode: dryRun ? "dry-run" : "live",
-        lab: plan.lab,
+        study: plan.study,
         renderReview: renderCuaReviewMarkdown,
         observer: { open: input.open === true, render: seams.renderObserver },
     });
@@ -229,7 +228,7 @@ export async function startCuaRun(plan, input, admitted, scope) {
         humanishSource: "present",
         packageName: "humanish",
     });
-    // Live-trace flush seam (#441): runLabParticipants fills it when a live run has an in-progress bundle
+    // Live-trace flush seam: runStudyParticipants fills it when a live run has an in-progress bundle
     // to grow; participants call it through deps.onTrace. It exists before deps so deps can reference it as
     // a stable indirection.
     const liveTrace = {};
@@ -316,7 +315,7 @@ function cuaParticipantDeps(plan, input, admitted, run) {
         onTrace: (participantId, items, usage, metadata) => liveTrace.flush?.(participantId, items, usage, metadata),
         ...callerDriving(input, config),
         residual: plan.residual,
-        labId: plan.labId,
+        studyId: plan.studyId,
         caps: plan.caps,
         appUrl,
         brain: plan.runner.brain,
@@ -330,11 +329,11 @@ function cuaParticipantDeps(plan, input, admitted, run) {
         timeoutMs,
         participantCount,
         artifactRoot: runPaths,
-        labCwd: input.cwd,
+        studyCwd: input.cwd,
         redactScreenshots,
         scrubKnownValues,
         runSession,
-        // The study-level ledger exists once per RUN, shared by every participant (#299). Dry runs never
+        // The study-level ledger exists once per run, shared by every participant. Dry runs never
         // spend, so they carry none.
         ...(dryRun || plan.caps.maxTotalUsd === undefined
             ? {}
@@ -374,7 +373,7 @@ function subjectPhaseReporter(input) {
     const sink = input.deps?.subjectPhaseSink ?? defaultSubjectPhaseSink;
     return (event, participant) => {
         sink(event, participant);
-        input.emit?.(phaseEvent(event, { kind: "participant", participant: participantOf(participant) }));
+        input.emit?.(phaseEvent(event, { kind: "participant", participant }));
     };
 }
 function makeCuaRunId() {