humanish 0.107.0 → 0.109.0

package/dist/{lab → study}/warnings.js

@@ -13,13 +13,13 @@ const otherRoute = (routes) => !promptRoute(routes) && !routes.scripted;
 /** Rows for each actor, reported as `actors[<index>].<field>`, in this order per actor. */
 const ACTOR_ROWS = [
     // Shared-world-only fields on the roster: a participant's `entry` is inert anywhere else
-    // (invariant 6).
+    // (claims match mechanism).
     {
         field: "lanes[].entry",
         reason: "the per-participant loopback entry is a shared-world capability; needs subject.topology: shared-world",
         applies: (actor, routes) => Boolean(rosterOf(actor)?.some((entry) => entry.entry !== undefined)) && !routes.shared,
     },
-    // The host-seat marker acts only on the external-public shared-world route; inert elsewhere.
+    // The host marker acts only on the external-public shared-world route; inert elsewhere.
     {
         field: "lanes[].host",
         reason: "the designated host-participant marker; needs the external-public shared-world route: app-url × topology shared-world × allowPublicTargets",
@@ -35,7 +35,7 @@ const ACTOR_ROWS = [
     },
     {
         field: "lanes",
-        reason: "fan-out is a computer-use route capability; terminal fan-out is a later slice",
+        reason: "only the computer-use route runs more than one participant",
         applies: (actor, routes) => routes.terminal && Boolean(rosterOf(actor)),
     },
     {
@@ -69,7 +69,7 @@ const ACTOR_ROWS = [
     { field: "lanes", applies: (actor, routes) => otherRoute(routes) && Boolean(rosterOf(actor)) },
 ];
 const TERMINAL_ONLY = "needs subject.source: terminal-product + a registered terminal actor";
-const RESERVED = "reserved for a later slice; not yet consumed";
+const RESERVED = "reserved; no route reads it yet";
 /** Rows for the rest of the config, reported after the actor rows, in this order. */
 const CONFIG_ROWS = [
     // The computer-use routes consume (clone) subject.{serve,env,state,clone.depth}, and so does the
@@ -90,8 +90,9 @@ const CONFIG_ROWS = [
         field: "subject.state",
         applies: (config, routes) => Boolean(config.subject.state) && !routes.cua && !routes.scripted,
     },
-    // topology + checkpoint act only on the shared-world route (#164); a set-but-unconsumed value
-    // (incl. an explicit per-lane-worlds, which the cua route already is by mechanism) warns inert.
+    // topology + checkpoint act only on the shared-world route; a set-but-unconsumed value
+    // (incl. an explicit per-lane-worlds, which the computer-use route already is by mechanism) warns
+    // inert.
     {
         field: "subject.topology",
         reason: "drives behavior only on the shared-world route; needs subject.topology: shared-world + clone × e2b-desktop × a computer-use actor + a roster of ≥2 participants",
@@ -113,7 +114,7 @@ const CONFIG_ROWS = [
     // getHost-exposed plane) and on scripted clones; inert elsewhere.
     {
         field: "subject.exposure",
-        reason: "the synthetic-subject attestation for a getHost-exposed plane; needs shared-world or clone × e2b-desktop × scripted-browser",
+        reason: "the statement that a subject served on a public sandbox URL holds only synthetic data; needs shared-world or clone × e2b-desktop × scripted-browser",
         applies: (config, routes) => config.subject.exposure !== undefined &&
             !routes.shared &&
             !(routes.scripted && config.subject.source === "clone"),
@@ -121,10 +122,10 @@ const CONFIG_ROWS = [
     // comms.email drives the in-sandbox email/SMS catch, which needs a subject sandbox that humanish
     // provisions (clone or local-tree) so it holds a handle to host the catch. On an app-url /
     // operator-provided subject there is no such handle, so a declared comms block would silently
-    // collect nothing — a false green. Warn at parse time (fires on inspect + dry-run too).
+    // collect nothing, a false green. Warn at parse time (fires on inspect + dry-run too).
     {
         field: "comms.email",
-        reason: "the in-sandbox email/SMS catch needs a harness-provisioned subject to host it — subject.source: clone or local-tree; on an app-url or operator-provided subject humanish holds no sandbox handle. Declare `comms.email.external` to run the catch yourself: humanish then points the persona at your inbox, drains your catch, and writes the same evidence — see #328",
+        reason: "the email catch runs in a sandbox humanish provisions, which needs `subject.source: clone` or `local-tree`, and an app-url subject has none. To use email here, run the catch yourself with `humanish comms catch` and declare `comms.email.external`: humanish then points each persona at your inbox, reads your catch and records the same evidence",
         applies: (config) => config.comms?.email?.kind === "fake" &&
             config.comms.email.external === undefined &&
             config.subject.source !== "clone" &&
@@ -135,13 +136,13 @@ const CONFIG_ROWS = [
     // declared external one would silently collect nothing.
     {
         field: "comms.email.external",
-        reason: "this subject is harness-provisioned, so humanish hosts the catch itself and injects its URL; an adopter-hosted catch would receive nothing. Drop `external` here, or move the lab to an app-url/operator-provisioned subject",
+        reason: "this subject is harness-provisioned, so humanish hosts the catch itself and injects its URL; an adopter-hosted catch would receive nothing. Drop `external` here, or move the study to an app-url or operator-provisioned subject",
         applies: (config) => Boolean(config.comms?.email?.external) &&
             (config.subject.source === "clone" || config.subject.source === "local-tree"),
     },
-    // clone.keep is consumed on the cua route (honored on failure: the sandbox is left up to debug
-    // a failed install/boot; otherwise always killed). clone.fanout is rejected on the cua route
-    // (a hard parse error above), so it can never reach this warning list there.
+    // clone.keep is consumed on the computer-use route (honored on failure: the sandbox is left up to
+    // debug a failed install/boot; otherwise always killed). clone.fanout is rejected on the
+    // computer-use route (a hard parse error above), so it can never reach this warning list there.
     {
         field: "execution.timeoutMs",
         applies: (config, routes) => !routes.cua &&
@@ -153,23 +154,24 @@ const CONFIG_ROWS = [
         field: "execution.completionTimeoutMs",
         applies: (config) => config.execution?.completionTimeoutMs !== undefined,
     },
-    // execution.concurrency is consumed on the cua route (it bounds in-flight fan-out participants);
-    // inert (warned) everywhere else.
+    // execution.concurrency is consumed on the computer-use route (it bounds in-flight fan-out
+    // participants); inert (warned) everywhere else.
     {
         field: "execution.concurrency",
         applies: (config, routes) => config.execution?.concurrency !== undefined && !routes.cua,
     },
-    // execution.caps is consumed on the cua route (maxUsd is the fail-closed spend abort); inert
-    // (warned) everywhere else so a misplaced budget field is never trusted to cap a route it cannot.
+    // execution.caps is consumed on the computer-use route (maxUsd is the fail-closed spend abort);
+    // inert (warned) everywhere else so a misplaced budget field is never trusted to cap a route it
+    // cannot.
     {
         field: "execution.caps",
-        reason: "the fail-closed spend abort is a computer-use route capability; needs a computer-use actor on e2b-desktop",
+        reason: "only the computer-use route enforces it, with a computer-use actor on e2b-desktop",
         applies: (config, routes) => Boolean(config.execution?.caps) && !routes.cua,
     },
     // terminal-product consumes subject.product, scenario.caps, execution.{terminal,runtimeAuth}:
     // dry-run records the contract; live execution enforces caps and command-scoped auth. On every
     // other route they are inert and must warn so a
-    // misplaced safety/budget field is never trusted to do something it cannot (invariant 6).
+    // misplaced safety/budget field is never trusted to do something it cannot.
     {
         field: "subject.product",
         reason: "needs subject.source: terminal-product or desktop-cli with the matching actor",
@@ -229,9 +231,9 @@ const CONFIG_ROWS = [
         applies: (config, routes) => !routes.cua && config.execution?.desktop?.sandboxTimeoutMs !== undefined,
     },
     // execution.desktop.template (the custom E2B desktop image) is consumed only where a desktop is
-    // actually created via Sandbox.create — the e2b-desktop computer-use routes (cua/shared-world/
-    // concurrent). It is inert on every other route (incl. the in-process local-app cua route, which
-    // creates no desktop): warn so an unconsumed template is never silently ignored (invariant 6).
+    // actually created via Sandbox.create: the e2b-desktop computer-use routes (cua/shared-world/
+    // concurrent). It is inert on every other route (incl. the in-process local-app computer-use
+    // route, which creates no desktop): warn so an unconsumed template is never silently ignored.
     {
         field: "execution.desktop.template",
         reason: "the custom E2B desktop image is consumed only on execution.target: e2b-desktop computer-use routes that create a desktop; needs a computer-use actor on e2b-desktop",
@@ -251,8 +253,8 @@ const CONFIG_ROWS = [
         applies: (config, routes) => Boolean(config.scenario?.ref) && !routes.scripted,
     },
     { field: "scenario.inline", applies: (config) => Boolean(config.scenario?.inline) },
-    // review.{scoring,milestones,vocabulary} stay forward-declared (reserved for #319) on every route.
-    // review.scorer (#316) is consumed (loaded + wired, or fail-closed at load) on every scorer-capable
+    // review.{scoring,milestones,vocabulary} stay forward-declared on every route.
+    // review.scorer is consumed (loaded + wired, or fail-closed at load) on every scorer-capable
     // route, so it does not warn there; on the scripted-browser route the actor carries no scorer seam,
     // so a declared scorer is flagged inert (the run also fails closed at load).
     {
@@ -297,9 +299,11 @@ function rowLabel(row, prefix = "") {
         ? `${prefix}${row.field}`
         : `${prefix}${row.field} (${row.reason})`;
 }
-// Report fields that are present but not yet consumed by the engine, so a user never trusts a
-// setting that silently does nothing. Keeps the schema forward-correct and honest.
-export function forwardDeclaredWarnings(config) {
+/**
+ * The fields a config sets that its route does not read, each as `field` or `field (reason)`. A v2
+ * file gets them as one warning; a v3 study is refused for any of them.
+ */
+export function inertFieldLabels(config) {
     const routes = routesOf(config);
     const inert = [];
     for (const [index, actor] of config.actors.entries()) {
@@ -310,14 +314,38 @@ export function forwardDeclaredWarnings(config) {
     for (const row of CONFIG_ROWS)
         if (row.applies(config, routes))
             inert.push(rowLabel(row));
+    return inert;
+}
+/**
+ * The same fields as `inertFieldLabels`, as paths without their reasons, such as
+ * `actors[0].lanes[].entry` or `execution.timeoutMs`. `humanish migrate` drops each one.
+ */
+export function inertFieldPaths(config) {
+    const routes = routesOf(config);
+    const paths = [];
+    for (const [index, actor] of config.actors.entries()) {
+        for (const row of ACTOR_ROWS)
+            if (row.applies(actor, routes))
+                paths.push(`actors[${index}].${row.field}`);
+    }
+    for (const row of CONFIG_ROWS)
+        if (row.applies(config, routes))
+            paths.push(row.field);
+    return paths;
+}
+// Report fields that are present but not yet consumed by the engine, so a user never trusts a
+// setting that silently does nothing.
+export function forwardDeclaredWarnings(config) {
+    const routes = routesOf(config);
+    const inert = inertFieldLabels(config);
     const warnings = inert.length === 0
         ? []
         : [
-            `Forward-declared fields are set but not yet consumed by the engine (planned for a later slice): ${inert.join(", ")}.`,
+            `These fields are set, but no route reads them yet, so they have no effect: ${inert.join(", ")}.`,
         ];
-    // A declared cap below the seat count is legal but loud: the roster promises N live actors and
-    // the cap delivers waves of M. Say so up front (inspect + dry-run + run) — a green run in waves
-    // is otherwise indistinguishable from the all-live run the author meant (#350).
+    // A declared cap below the participant count is legal but loud: the roster promises N live actors
+    // and the cap delivers waves of M. Say so up front (inspect + dry-run + run): a green run in
+    // waves is otherwise indistinguishable from the all-live run the author meant.
     {
         const participantCount = rosterOf(config.actors[0])?.length ?? config.actors[0]?.count ?? 1;
         const cap = config.execution?.concurrency;
@@ -325,14 +353,14 @@ export function forwardDeclaredWarnings(config) {
             warnings.push(`execution.concurrency ${cap} caps a ${participantCount}-participant roster: participants run in waves of ${cap}, never all live at once. Remove execution.concurrency (the default runs all ${participantCount} participants simultaneously) or set it to ${participantCount}; declare a lower cap only to bound simultaneous paid desktops.`);
         }
     }
-    // Partial email coverage is legal but loud (#351): a participant without an addressed recipient never
-    // hears an inbox exists, so an email-gated flow on that seat dead-ends by construction.
+    // Partial email coverage is legal but loud: a participant without an addressed recipient never
+    // hears an inbox exists, so an email-gated flow on that participant dead-ends by construction.
     if (routes.cua && config.comms?.email?.recipients) {
         const participantIds = declaredParticipantIds(config);
         const covered = new Set(addressedRecipients(config.comms.email).map((recipient) => recipient.participantId));
         const uncovered = participantIds.filter((id) => !covered.has(id));
         if (covered.size > 0 && uncovered.length > 0 && participantIds.length > 1) {
-            warnings.push(`comms.email covers ${covered.size} of ${participantIds.length} participants; the uncovered participant(s) get no inbox and are never told one exists: ${uncovered.join(", ")}. Add addressed recipients for them if their flows need email.`);
+            warnings.push(`comms.email covers ${covered.size} of ${participantIds.length} participants. These get no inbox and are never told one exists: ${uncovered.join(", ")}. Add a recipient with an address for each one whose flow needs email.`);
         }
     }
     return warnings;

package/dist/subject/clone.d.ts

@@ -1,15 +1,15 @@
-import type { LabSubjectServe, LabSubjectState } from "../lab/types.js";
+import type { StudySubjectServe, StudySubjectState } from "../study/types.js";
 import type { RunSubjectStateStepRecord } from "../run/bundle.js";
 import { type DetachedTimers } from "../substrates/detached.js";
 import { type Shell } from "../substrates/shell.js";
 import { type SubjectPhaseEvent } from "./steps.js";
-/** The longest provisionCloneSubject can take with the lab's budgets: the clone, then serving. */
-export declare function cloneProvisioningBudgetMs(serve: LabSubjectServe, state: LabSubjectState | undefined): number;
+/** The longest provisionCloneSubject can take with the study's budgets: the clone, then serving. */
+export declare function cloneProvisioningBudgetMs(serve: StudySubjectServe, state: StudySubjectState | undefined): number;
 /**
  * Provision a clone subject inside the sandbox: clone, then the shared serve pipeline (install,
  * state before-build, build, state before-start, start, readiness probe, state after-ready).
  * Returns the latest subject HEAD after successful provisioning. Throws (with a capped log tail
- * for the caller to redact) on any failing step; the lab persists that as a failed-evidence
+ * for the caller to redact) on any failing step; the route persists that as a failed-evidence
  * bundle.
  *
  * Auth: when GITHUB_TOKEN is among the declared subject env names, the clone authenticates via an
@@ -20,12 +20,12 @@ export declare function cloneProvisioningBudgetMs(serve: LabSubjectServe, state:
 export declare function provisionCloneSubject(shell: Shell, args: {
     repo: string;
     depth: number;
-    serve: LabSubjectServe;
+    serve: StudySubjectServe;
     /** Declared subject state (seed steps; external declaration is provenance-only). */
-    state?: LabSubjectState;
+    state?: StudySubjectState;
     hasGithubToken: boolean;
     requestTimeoutMs: number;
-    /** Literal scrubber for known provisioned values, applied to log tails PRE-truncation. */
+    /** Literal scrubber for known provisioned values, applied to log tails pre-truncation. */
     scrub: (text: string) => string;
     /** Called the moment the cloned commit resolves, so provenance survives later failures. */
     onCommit?: (commit: string) => void;

package/dist/subject/clone.js

@@ -3,7 +3,7 @@ import { detachedTimersOf, runDetachedStep } from "../substrates/detached.js";
 import { runOrThrow } from "../substrates/shell.js";
 import { runSubjectServePipeline, serveProvisioningBudgetMs } from "./serve.js";
 import { SOURCE_TIMEOUT_MS, emitPhaseCompleted, emitPhaseStarted, SUBJECT_DIR, } from "./steps.js";
-/** The longest provisionCloneSubject can take with the lab's budgets: the clone, then serving. */
+/** The longest provisionCloneSubject can take with the study's budgets: the clone, then serving. */
 export function cloneProvisioningBudgetMs(serve, state) {
     return SOURCE_TIMEOUT_MS + serveProvisioningBudgetMs(serve, state);
 }
@@ -11,7 +11,7 @@ export function cloneProvisioningBudgetMs(serve, state) {
  * Provision a clone subject inside the sandbox: clone, then the shared serve pipeline (install,
  * state before-build, build, state before-start, start, readiness probe, state after-ready).
  * Returns the latest subject HEAD after successful provisioning. Throws (with a capped log tail
- * for the caller to redact) on any failing step; the lab persists that as a failed-evidence
+ * for the caller to redact) on any failing step; the route persists that as a failed-evidence
  * bundle.
  *
  * Auth: when GITHUB_TOKEN is among the declared subject env names, the clone authenticates via an

package/dist/subject/desktop-cli.d.ts

@@ -1,7 +1,7 @@
 import type { Shell } from "../substrates/shell.js";
 import { type SubjectPhaseEvent } from "./steps.js";
 /**
- * Prepare a CLI study's runtime and, only when declared, its product (#495, #515).
+ * Prepare a CLI study's runtime and, only when declared, its product.
  *
  * The install runs unkeyed and before the session starts, for the same reason the clone route
  * provisions its subject first: what is being studied begins when the participant looks at the

package/dist/subject/desktop-cli.js

@@ -4,7 +4,7 @@ import { NODE_BOOTSTRAP_COMMAND, NODE_BOOTSTRAP_TIMEOUT_MS } from "./node-bootst
 import { runDetachedStep } from "../substrates/detached.js";
 import { emitPhaseCompleted, emitPhaseStarted, INSTALL_TIMEOUT_MS, } from "./steps.js";
 /**
- * Prepare a CLI study's runtime and, only when declared, its product (#495, #515).
+ * Prepare a CLI study's runtime and, only when declared, its product.
  *
  * The install runs unkeyed and before the session starts, for the same reason the clone route
  * provisions its subject first: what is being studied begins when the participant looks at the
@@ -44,7 +44,7 @@ export async function provisionDesktopCli(shell, args) {
     if (!result.ok) {
         // Fail closed: a participant handed a desktop where the product is not installed would produce
         // a transcript about a missing command, and that finding belongs to the harness, not the tool.
-        // The tail rides along, scrubbed before truncation like every other provisioning failure — a
+        // The tail rides along, scrubbed before truncation like every other provisioning failure. A
         // bare "install failed" is unactionable to whoever wrote the command.
         throw new Error(args.scrub(`desktop-cli install failed for "${args.product}" (${result.timedOut ? "timed out" : `exit ${result.exitCode ?? "?"}`}): ${failureTail(args.scrub(result.logTail))}`));
     }

package/dist/subject/local-tree-archive.d.ts

@@ -76,7 +76,7 @@ export declare function createLocalTreeArchive(root: string, options?: CreateLoc
  * produces (no leading "./", no trailing "/"). Absolute paths and glob syntax
  * are rejected instead of silently ignored: an exclude the author believed in but
  * that never matches anything is a leak vector, so unusable shapes fail
- * closed at the packing boundary (and, for lab manifests, already at parse
- * time in src/lab/parse/subject.ts).
+ * closed at the packing boundary (and, for study manifests, already at parse
+ * time in src/study/parse/subject.ts).
  */
 export declare function normalizeExtraExcludeEntry(entry: string): string;

package/dist/subject/local-tree-archive.js

@@ -8,7 +8,7 @@
 // that cannot happen: enumerateLocalTree() builds one entries array, and both
 // the hash and the tar file list are derived from that same array.
 //
-// See docs/goals/local-tree-subject/goal.md ("Packing design") for the full
+// See docs/history/goals/local-tree-subject/goal.md ("Packing design") for the full
 // contract implemented here. Node builtins only, no npm dependencies.
 import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
@@ -111,7 +111,7 @@ export function createLocalTreeArchive(root, options = {}) {
     if (entries.length === 0) {
         throw new Error(`Local tree root "${path.basename(resolvedRoot)}" produced zero packable entries after the always-on denylist` +
             (extraExclude.length > 0 ? " and extraExclude" : "") +
-            "; local-tree packing requires at least one non-denylisted file or symlink. (Paths in this message are basenames only; the packed root is the lab resolution cwd.)");
+            "; local-tree packing requires at least one non-denylisted file or symlink. (Paths in this message are basenames only; the packed root is the study's working directory.)");
     }
     // Check the cap from enumerated sizes before reading/hashing file bytes, so
     // an oversized tree fails closed without the cost of hashing all of it.
@@ -292,8 +292,8 @@ function isDenylistedSegment(relPath) {
  * produces (no leading "./", no trailing "/"). Absolute paths and glob syntax
  * are rejected instead of silently ignored: an exclude the author believed in but
  * that never matches anything is a leak vector, so unusable shapes fail
- * closed at the packing boundary (and, for lab manifests, already at parse
- * time in src/lab/parse/subject.ts).
+ * closed at the packing boundary (and, for study manifests, already at parse
+ * time in src/study/parse/subject.ts).
  */
 export function normalizeExtraExcludeEntry(entry) {
     const trimmed = entry.trim();

package/dist/subject/local-tree.d.ts

@@ -1,4 +1,4 @@
-import type { LabSubjectServe, LabSubjectState } from "../lab/types.js";
+import type { StudySubjectServe, StudySubjectState } from "../study/types.js";
 import type { RunSubjectStateStepRecord } from "../run/bundle.js";
 import { type DetachedTimers } from "../substrates/detached.js";
 import type { Shell } from "../substrates/shell.js";
@@ -14,11 +14,11 @@ import { type SubjectPhaseEvent } from "./steps.js";
 export declare function provisionLocalTreeSubject(shell: Shell, args: {
     /** The once-per-run packed archive bytes (shared byte-identically across every participant). */
     archiveBuffer: ArrayBuffer;
-    serve: LabSubjectServe;
+    serve: StudySubjectServe;
     /** Declared subject state (seed steps; external declaration is provenance-only). */
-    state?: LabSubjectState;
+    state?: StudySubjectState;
     requestTimeoutMs: number;
-    /** Literal scrubber for known provisioned values, applied to log tails PRE-truncation. */
+    /** Literal scrubber for known provisioned values, applied to log tails pre-truncation. */
     scrub: (text: string) => string;
     /** Called the moment each state step finishes, success or failure. */
     onStateStep?: (record: RunSubjectStateStepRecord) => void;

package/dist/subject/node-bootstrap.js

@@ -54,7 +54,7 @@ export const NODE_BOOTSTRAP_COMMAND = [
     "for executable in node npm npx; do",
     `  sudo -n ln -sfn "$node_target/bin/$executable" "/usr/local/bin/$executable"`,
     "done",
-    // Keep global product executables on the existing ordinary/sudo `PATH` (#679). The new
+    // Keep global product executables on the existing ordinary/sudo `PATH`. The new
     // versioned distribution is the only config we modify; no user/global npmrc or profile.
     `sudo -n "$node_target/bin/node" -e '${NODE_NPM_PREFIX_SCRIPT}' "$node_target/lib/node_modules/npm/npmrc"`,
     "hash -r",

package/dist/subject/runtime.js

@@ -1,17 +1,16 @@
-// Provide the runtime a subject's serve pipeline needs, instead of failing at exit 127 (#371).
+// Provide the runtime a subject's serve pipeline needs, instead of failing at exit 127.
 //
-// The stock E2B `desktop` template ships python3 and curl but no Node. That fact has now been
-// rediscovered three times: the in-sandbox comms catch was rewritten from node to python3 in 0.29.0
-// for exactly this reason, the terminal route bootstraps Node explicitly, and the computer-use
-// clone/local-tree route did neither — so any lab whose `serve.install` runs npm or pnpm died with
-// `pnpm: command not found` after a sandbox had been created and paid for.
+// The stock E2B `desktop` template ships python3 and curl but no Node. So the in-sandbox comms
+// catch runs on python3, the terminal route bootstraps Node explicitly, and this module provides
+// Node for the computer-use clone/local-tree route. Without it, any study whose `serve.install`
+// runs npm or pnpm dies with `pnpm: command not found` after its sandbox is created and paid for.
 //
-// It failed invisibly up front: `lab inspect` was clean, the plan printed normally, the sandbox
-// provisioned, and the first signal was a shell exit code attributed to "subject install failed".
+// That failure is invisible up front: `study show` is clean, the plan prints normally, the sandbox
+// provisions, and the first signal is a shell exit code attributed to "subject install failed".
 // Nobody can debug that from the outside.
 //
-// The harness provides the runtime instead of warning about it. An adopter writing a lab for a Node app should not have to
-// know which binaries the template happens to carry — that is the harness's job, and the terminal
+// The harness provides the runtime instead of warning about it. An adopter writing a study for a Node app should not have to
+// know which binaries the template happens to carry. That is the harness's job, and the terminal
 // route already treats it that way. Detection is conservative and the bootstrap is skipped whenever
 // a runtime is already present, so a custom template that ships Node pays nothing.
 /** Package managers and runtimes whose absence on the stock template breaks a serve pipeline. */

package/dist/subject/serve.d.ts

@@ -1,4 +1,4 @@
-import type { LabSubjectServe, LabSubjectState } from "../lab/types.js";
+import type { StudySubjectServe, StudySubjectState } from "../study/types.js";
 import type { RunSubjectStateStepRecord } from "../run/bundle.js";
 import { type DetachedTimers } from "../substrates/detached.js";
 import type { Shell } from "../substrates/shell.js";
@@ -8,7 +8,7 @@ import { type SubjectPhaseEvent } from "./steps.js";
  * with their one retry, the package-manager step, every seed step, the build and the readiness
  * wait. Detached-step polling adds seconds on top.
  */
-export declare function serveProvisioningBudgetMs(serve: LabSubjectServe, state: LabSubjectState | undefined): number;
+export declare function serveProvisioningBudgetMs(serve: StudySubjectServe, state: StudySubjectState | undefined): number;
 /**
  * The provisioning pipeline the clone and local-tree routes share once SUBJECT_DIR is populated
  * (by git clone, or by upload and extract): install, state before-build, build, state
@@ -21,11 +21,11 @@ export declare function serveProvisioningBudgetMs(serve: LabSubjectServe, state:
  * eats the session budget.
  */
 export declare function runSubjectServePipeline(shell: Shell, args: {
-    serve: LabSubjectServe;
+    serve: StudySubjectServe;
     /** Declared subject state (seed steps; external declaration is provenance-only). */
-    state?: LabSubjectState;
+    state?: StudySubjectState;
     requestTimeoutMs: number;
-    /** Literal scrubber for known provisioned values, applied to log tails PRE-truncation. */
+    /** Literal scrubber for known provisioned values, applied to log tails pre-truncation. */
     scrub: (text: string) => string;
     /** Called the moment each state step finishes, success or failure. */
     onStateStep?: (record: RunSubjectStateStepRecord) => void;

package/dist/subject/serve.js

@@ -8,7 +8,7 @@ import { emitPhaseCompleted, emitPhaseStarted, INSTALL_TIMEOUT_MS, isoNow, SUBJE
 const BUILD_TIMEOUT_MS = 10 * 60_000;
 const DEFAULT_READY_TIMEOUT_MS = 180_000;
 /**
- * Run a provisioning step and, when it fails with an exit code, run it once more (#602): a
+ * Run a provisioning step and, when it fails with an exit code, run it once more: a
  * transient network error inside `npm install` is the common case. A timeout is not retried: its
  * budget is already spent, and a second wait would double it. The retry runs under its own step
  * name so both logs stay.
@@ -121,7 +121,7 @@ export async function runSubjectServePipeline(shell, args) {
     await refresh();
 }
 /**
- * Provide the runtime the pipeline needs before running it (#371). The stock desktop template
+ * Provide the runtime the pipeline needs before running it. The stock desktop template
  * ships python3 and curl but no Node. Probe first, so a template that ships its own Node pays
  * nothing.
  */
@@ -187,7 +187,7 @@ async function installSubject(step, command) {
             ? "subject install failed twice"
             : "subject install failed");
     if (!install.ok) {
-        // Lead with the line a person can act on; npm's own trace follows it (#602).
+        // Lead with the line a person can act on; npm's own trace follows it.
         const headline = install.timedOut
             ? `subject install timed out after ${step.serve.installTimeoutMs ?? INSTALL_TIMEOUT_MS}ms`
             : install.attempts === 2

package/dist/subject/state.d.ts

@@ -1,4 +1,4 @@
-import type { LabStateStepWhen, LabSubjectState } from "../lab/types.js";
+import type { StudyStateStepWhen, StudySubjectState } from "../study/types.js";
 import type { RunSubjectStateStepRecord } from "../run/bundle.js";
 import { type DetachedTimers } from "../substrates/detached.js";
 import type { Shell } from "../substrates/shell.js";
@@ -11,10 +11,10 @@ export declare function commandDigestOf(command: string): string;
  * `subject-state-<name>` so a step can never collide with a serve step. Each step's record goes
  * to `onStateStep` as it finishes; the first failure throws with its scrubbed log tail.
  */
-export declare function runStateSteps(shell: Shell, when: LabStateStepWhen, args: {
-    state?: LabSubjectState;
+export declare function runStateSteps(shell: Shell, when: StudyStateStepWhen, args: {
+    state?: StudySubjectState;
     requestTimeoutMs: number;
-    /** Literal scrubber for known provisioned values, applied to log tails PRE-truncation. */
+    /** Literal scrubber for known provisioned values, applied to log tails pre-truncation. */
     scrub: (text: string) => string;
     onStateStep?: (record: RunSubjectStateStepRecord) => void;
     onPhase?: (event: SubjectPhaseEvent) => void;

package/dist/subject/state.js

@@ -39,7 +39,7 @@ export async function runStateSteps(shell, when, args) {
         args.onStateStep?.({
             name: step.name,
             when,
-            // Digest only (sha256-16): the command text never persists: the lab YAML in the
+            // Digest only (sha256-16): the command text never persists: the study YAML in the
             // consumer's repo is the plaintext source of truth.
             commandDigest: commandDigestOf(step.command),
             ok: result.ok,

package/dist/subject/steps.d.ts

@@ -25,13 +25,13 @@ export declare function emitPhaseStarted(onPhase: ((event: SubjectPhaseEvent) =>
 /** Emit the matching phase-completed event: always carries ok and durationMs (>= 0). */
 export declare function emitPhaseCompleted(onPhase: ((event: SubjectPhaseEvent) => void) | undefined, now: () => number, startedAt: number, phase: string, ok: boolean, message: string): void;
 /** Default phase-boundary sink (stderr): one line per event, prefixed with the participant id
- *  only when laneCount > 1. Single-participant emission is unconditional: total single-participant silence for the
- *  whole clone/install/build/ready boot is the bug this event stream exists to close.
- *  Overridable via LabDeps.subjectPhaseSink so deterministic tests capture instead of writing to
+ *  only when the run has more than one participant. A single participant still gets every line:
+ *  a silent clone, install, build and ready boot is the bug this event stream exists to close.
+ *  Overridable via StudyDeps.subjectPhaseSink so deterministic tests capture instead of writing to
  *  the real stderr. */
-export declare function defaultSubjectPhaseSink(event: SubjectPhaseEvent, ctx: {
-    laneId: string;
-    laneCount: number;
+export declare function defaultSubjectPhaseSink(event: SubjectPhaseEvent, participant: {
+    readonly id: string;
+    readonly count: number;
 }): void;
 /** The shared-world subject's phase line: one shared plane, so no participant prefix. */
 export declare function defaultSharedWorldPhaseSink(event: SubjectPhaseEvent): void;

package/dist/subject/steps.js

@@ -23,13 +23,13 @@ export function emitPhaseCompleted(onPhase, now, startedAt, phase, ok, message)
     });
 }
 /** Default phase-boundary sink (stderr): one line per event, prefixed with the participant id
- *  only when laneCount > 1. Single-participant emission is unconditional: total single-participant silence for the
- *  whole clone/install/build/ready boot is the bug this event stream exists to close.
- *  Overridable via LabDeps.subjectPhaseSink so deterministic tests capture instead of writing to
+ *  only when the run has more than one participant. A single participant still gets every line:
+ *  a silent clone, install, build and ready boot is the bug this event stream exists to close.
+ *  Overridable via StudyDeps.subjectPhaseSink so deterministic tests capture instead of writing to
  *  the real stderr. */
-export function defaultSubjectPhaseSink(event, ctx) {
+export function defaultSubjectPhaseSink(event, participant) {
     const durationSuffix = event.durationMs === undefined ? "" : ` (${event.durationMs}ms)`;
-    const prefix = ctx.laneCount > 1 ? `humanish computer-use [${ctx.laneId}]` : "humanish computer-use";
+    const prefix = participant.count > 1 ? `humanish computer-use [${participant.id}]` : "humanish computer-use";
     process.stderr.write(`${prefix}: ${event.message}${durationSuffix}\n`);
 }
 /** The shared-world subject's phase line: one shared plane, so no participant prefix. */

package/dist/substrates/command-failure.d.ts

@@ -1,13 +1,13 @@
 /**
  * True when `error` is (structurally) the @e2b/desktop CommandExitError: a
- * non-zero substrate command exit that the real Sandbox surfaces as a THROW.
+ * non-zero substrate command exit that the real Sandbox surfaces as a throw.
  * Matches either the SDK class name (`name === "CommandExitError"`) or any object
  * carrying a numeric `exitCode` (the same field `commandFailureInfo` reads, so a
  * structural fake is covered without importing the SDK class).
  *
- * Deliberately conservative — it is the RECOVERABILITY predicate the CUA loop uses
+ * Deliberately conservative: it is the recoverability predicate the CUA loop uses
  * to skip a single failed desktop action instead of ending the whole run: it must
- * NOT match a deadline/abort control-flow signal (those subclass Error without a
+ * not match a deadline/abort control-flow signal (those subclass Error without a
  * name override or an exitCode) or a generic Error with no exit signal, so only a
  * genuine substrate-command failure is treated as recoverable.
  */

package/dist/substrates/command-failure.js

@@ -12,14 +12,14 @@
 import { tailOf } from "./shell.js";
 /**
  * True when `error` is (structurally) the @e2b/desktop CommandExitError: a
- * non-zero substrate command exit that the real Sandbox surfaces as a THROW.
+ * non-zero substrate command exit that the real Sandbox surfaces as a throw.
  * Matches either the SDK class name (`name === "CommandExitError"`) or any object
  * carrying a numeric `exitCode` (the same field `commandFailureInfo` reads, so a
  * structural fake is covered without importing the SDK class).
  *
- * Deliberately conservative — it is the RECOVERABILITY predicate the CUA loop uses
+ * Deliberately conservative: it is the recoverability predicate the CUA loop uses
  * to skip a single failed desktop action instead of ending the whole run: it must
- * NOT match a deadline/abort control-flow signal (those subclass Error without a
+ * not match a deadline/abort control-flow signal (those subclass Error without a
  * name override or an exitCode) or a generic Error with no exit signal, so only a
  * genuine substrate-command failure is treated as recoverable.
  */

package/dist/substrates/desktop-session.js

@@ -1,4 +1,4 @@
-import { CuaExecutorError } from "../actors/computer-use/executor-error.js";
+import { ComputerUseExecutorError } from "../actors/computer-use/executor-error.js";
 /**
  * Wrap an already-acquired resource. The adapter supplies release authority as a closure;
  * this layer never reconstructs it from a saved ID or enumerates provider resources.
@@ -12,7 +12,7 @@ export function ownDesktopAllocation(options) {
     let closing;
     const assertOpen = () => {
         if (closing !== undefined)
-            throw new CuaExecutorError("executor_closed", "not_dispatched");
+            throw new ComputerUseExecutorError("executor_closed", "not_dispatched");
     };
     const close = (policy = {}) => {
         // Install the promise before invoking release: concurrent/reentrant callers share it.