humanish 0.107.0 → 0.109.0

package/dist/cli/commands/{lab-format.js → study-format.js}

@@ -1,10 +1,28 @@
 import { formatCuaDiagnostics, formatCuaStopCause } from "../../routes/computer-use/diagnostics.js";
-export function formatConcurrentSharedWorldLabHuman(result) {
-    return ([
-        `humanish lab concurrent-shared-world ${result.ok ? (result.dryRun ? "dry-run" : "live") : "failed"}`,
-        ...(result.error ? [`${result.error.code}: ${result.error.message}`] : []),
+/** A run's first lines: the command that ran, whether it was a dry run, how it ended, and its route. */
+function runHeader(result, route) {
+    const kind = result.dryRun === true ? "dry run" : result.dryRun === false ? "live run" : "run";
+    return [
+        `humanish run ${result.studyId}: ${kind} ${result.ok ? "finished" : "failed"}`,
+        `route: ${route}`,
+    ];
+}
+/**
+ * A run's human output: its lines on stdout and, when it failed with an error, that error on
+ * stderr through formatCliError.
+ */
+function withError(error, lines) {
+    const stdout = `${lines.join("\n")}\n`;
+    return error === undefined ? stdout : { stdout, error };
+}
+/** A participant's status in words: a dry run's placeholder status says that nothing ran live. */
+function participantStatus(status) {
+    return status === "contract_proof_only" ? "dry run, nothing ran live" : status;
+}
+export function formatConcurrentSharedWorldStudyHuman(result) {
+    return withError(result.error, [
+        ...runHeader(result, "shared-world"),
         `run: ${result.runId}`,
-        `lab: ${result.labId}`,
         `actor: ${result.actor}`,
         `topology: ${result.topology}/${result.topologyMode} (${result.roleCount} persona${result.roleCount === 1 ? "" : "s"}, concurrency ${result.concurrency})`,
         ...(result.host ? [`host: ${result.host}`] : []),
@@ -16,7 +34,7 @@ export function formatConcurrentSharedWorldLabHuman(result) {
             : [
                 `overlap: ${result.overlapProven ? "proven" : "not observed"} (this run only; no scale or adoption claim)`,
             ]),
-        ...result.roles.map((participant) => `persona ${participant.id} (${participant.persona}): ${participant.status}${participant.session ? ` (${participant.session.completionReason})` : ""} ${participant.ok ? "ok" : "not-ok"}`),
+        ...result.roles.map((participant) => `persona ${participant.id} (${participant.persona}): ${participantStatus(participant.status)}${participant.session ? ` (${participant.session.completionReason})` : ""}${participant.ok ? "" : ", not ok"}`),
         ...(result.subjectSandbox
             ? [
                 `subject sandbox: ${result.subjectSandbox.sandboxId} killed=${result.subjectSandbox.killed ? "yes" : "no"}`,
@@ -27,14 +45,12 @@ export function formatConcurrentSharedWorldLabHuman(result) {
             ? []
             : [`opened: ${result.observer.opened ? "yes" : "no"}`]),
         ...result.warnings.map((warning) => `warning: ${warning}`),
-    ].join("\n") + "\n");
+    ]);
 }
-export function formatTerminalLabHuman(result) {
-    return ([
-        `humanish lab terminal ${result.ok ? (result.dryRun ? "dry-run" : "live") : "failed"}`,
-        ...(result.error ? [`${result.error.code}: ${result.error.message}`] : []),
+export function formatTerminalStudyHuman(result) {
+    return withError(result.error, [
+        ...runHeader(result, "terminal"),
         `run: ${result.runId}`,
-        `lab: ${result.labId}`,
         `actor: ${result.actor}`,
         `product: ${result.product}`,
         ...(result.observer?.observerPath ? [`observer: ${result.observer.observerPath}`] : []),
@@ -42,14 +58,12 @@ export function formatTerminalLabHuman(result) {
             ? []
             : [`opened: ${result.observer.opened ? "yes" : "no"}`]),
         ...result.warnings.map((warning) => `warning: ${warning}`),
-    ].join("\n") + "\n");
+    ]);
 }
-export function formatScriptedLabHuman(result) {
-    return ([
-        `humanish lab scripted ${result.ok ? (result.dryRun ? "dry-run" : "live") : "failed"}`,
-        ...(result.error ? [`${result.error.code}: ${result.error.message}`] : []),
+export function formatScriptedStudyHuman(result) {
+    return withError(result.error, [
+        ...runHeader(result, "scripted"),
         `run: ${result.runId}`,
-        `lab: ${result.labId}`,
         `actor: ${result.actor}`,
         `subject: ${result.appUrl}`,
         ...(result.scenario
@@ -63,14 +77,12 @@ export function formatScriptedLabHuman(result) {
             ? []
             : [`opened: ${result.observer.opened ? "yes" : "no"}`]),
         ...result.warnings.map((warning) => `warning: ${warning}`),
-    ].join("\n") + "\n");
+    ]);
 }
-export function formatCuaLabHuman(result) {
-    return ([
-        `humanish lab cua ${result.ok ? (result.dryRun ? "dry-run" : "live") : "failed"}`,
-        ...(result.error ? [`${result.error.code}: ${result.error.message}`] : []),
+export function formatCuaStudyHuman(result) {
+    return withError(result.error, [
+        ...runHeader(result, "computer-use"),
         `run: ${result.runId}`,
-        `lab: ${result.labId}`,
         `actor: ${result.actor}`,
         `subject: ${result.appUrl}`,
         ...(result.subject?.source === "clone"
@@ -83,11 +95,11 @@ export function formatCuaLabHuman(result) {
             : []),
         ...(result.diagnostics ? [`diagnostic: ${formatCuaDiagnostics(result.diagnostics)}`] : []),
         ...((result.lanes?.length ?? 0) > 1
-            ? result.lanes.map((participant) => `participant ${participant.id}: ${participant.status}${participant.session ? ` (${participant.session.completionReason})` : ""}${participant.diagnostics ? ` · ${formatCuaDiagnostics(participant.diagnostics)}` : ""}${participant.session ? ` · ${participant.session.reason}` : ""}`)
+            ? result.lanes.map((participant) => `participant ${participant.id}: ${participantStatus(participant.status)}${participant.session ? ` (${participant.session.completionReason})` : ""}${participant.diagnostics ? ` · ${formatCuaDiagnostics(participant.diagnostics)}` : ""}${participant.session ? ` · ${participant.session.reason}` : ""}`)
             : []),
         ...(result.session && (result.lanes?.length ?? 0) <= 1
             ? [
-                `session: ${result.session.status} (${result.session.completionReason})${result.session.stopCause ? ` · ${formatCuaStopCause(result.session.stopCause)}` : ""} · ${result.session.reason}`,
+                `session: ${participantStatus(result.session.status)} (${result.session.completionReason})${result.session.stopCause ? ` · ${formatCuaStopCause(result.session.stopCause)}` : ""} · ${result.session.reason}`,
                 `screenshots: ${result.session.screenshots}`,
             ]
             : []),
@@ -101,5 +113,5 @@ export function formatCuaLabHuman(result) {
             ? []
             : [`opened: ${result.observer.opened ? "yes" : "no"}`]),
         ...result.warnings.map((warning) => `warning: ${warning}`),
-    ].join("\n") + "\n");
+    ]);
 }

package/dist/cli/commands/{lab-route-computer-use.d.ts → study-route-computer-use.d.ts}

@@ -1,16 +1,16 @@
 import { Command } from "commander";
-import type { LabConfig } from "../../lab/types.js";
-import { type CliIo, type LabCommandOptions } from "../io.js";
-import type { RouteRun } from "./lab-route-run.js";
+import type { StudyConfig } from "../../study/types.js";
+import { type CliIo, type StudyCommandOptions } from "../io.js";
+import type { RouteRun } from "./study-route-run.js";
 interface ComputerUseRouteArgs {
     command: Command;
     io: CliIo;
-    config: LabConfig;
+    config: StudyConfig;
     mode: "run" | "watch";
-    options: LabCommandOptions;
+    options: StudyCommandOptions;
 }
 /**
- * The computer-use route's CLI setup: its settings, the watch and exposure plan, the runLab options
+ * The computer-use route's CLI setup: its settings, the watch and exposure plan, the runStudyWith options
  * with the live Observer hook, and how it presents the outcome or a run error. Undefined when
  * setup has already written its own result.
  */

package/dist/cli/commands/{lab-route-computer-use.js → study-route-computer-use.js}

@@ -1,19 +1,19 @@
 import { automaticAnalysisSucceeded } from "../../analysis/automatic-completion.js";
 import { Command } from "commander";
-import {} from "../../run-lab.js";
-import { resolveLabDryRun } from "../../lab/plan.js";
-import { CUA_ACTOR_LAB_SCHEMA } from "../../routes/computer-use/types.js";
+import {} from "../../run-study.js";
+import { resolveStudyDryRun } from "../../study/plan.js";
 import { serveObserver } from "../../observer/render.js";
 import { startExposedObserver, validateExposure } from "../../observer/exposure.js";
 import { ServeTunnelError } from "../../observer/tunnel.js";
 import { cliAnalysisOptions } from "./analysis-signals.js";
 import { onRunShutdown } from "./run-signals.js";
-import { parseLabCount, parseParticipantIds, parseObserverPort, wantsJson, writeResult, } from "../io.js";
+import { parseStudyCount, parseParticipantIds, parseObserverPort, wantsJson, writeResult, } from "../io.js";
 import { exposureRequestFromOptions, followObserver, planObserver, showObserver, staticObserverOpen, withObserverServer, } from "../observer-follow.js";
-import { formatCuaLabHuman } from "./lab-format.js";
-import { resolveRouteShouldOpen } from "./lab-route-open.js";
+import { formatCuaStudyHuman } from "./study-format.js";
+import { resolveRouteShouldOpen } from "./study-route-open.js";
+import { studyResultIdentity } from "../../run/study-result.js";
 /**
- * The computer-use route's CLI setup: its settings, the watch and exposure plan, the runLab options
+ * The computer-use route's CLI setup: its settings, the watch and exposure plan, the runStudyWith options
  * with the live Observer hook, and how it presents the outcome or a run error. Undefined when
  * setup has already written its own result.
  */
@@ -50,10 +50,9 @@ export function computerUseRouteRun(args) {
 }
 function refuseCua(args, dryRun, code, message) {
     const result = {
-        schema: CUA_ACTOR_LAB_SCHEMA,
+        ...studyResultIdentity("computer-use", args.config.id),
         ok: false,
         cwd: args.options.cwd,
-        labId: args.config.id,
         actor: args.config.actors[0]?.type ?? "",
         appUrl: "",
         dryRun,
@@ -61,7 +60,7 @@ function refuseCua(args, dryRun, code, message) {
         warnings: [],
         error: { code, message },
     };
-    writeResult(args.command, args.io, result, formatCuaLabHuman);
+    writeResult(args.command, args.io, result, formatCuaStudyHuman);
     args.io.setExitCode(2);
 }
 /** Parses the options, or writes the refusal and returns undefined. */
@@ -79,13 +78,13 @@ function resolveCuaSettings(args) {
         args.io.setExitCode(2);
         return undefined;
     }
-    const count = parseLabCount(args.options.count, args.config.actors[0]?.count ?? 1);
+    const count = parseStudyCount(args.options.count, args.config.actors[0]?.count ?? 1);
     if (count === null) {
         args.io.writeErr("error: --count must be a positive integer.\n");
         args.io.setExitCode(2);
         return undefined;
     }
-    const dryRun = resolveLabDryRun(args.config, args.options.dryRun, true) ?? true;
+    const dryRun = resolveStudyDryRun(args.config, args.options.dryRun, true) ?? true;
     const port = parseObserverPort(args.options.port ?? "0");
     const wantsFollow = args.mode === "watch" && !wantsMachine && args.options.detach !== true && dryRun !== true;
     if (port === null) {
@@ -97,7 +96,7 @@ function resolveCuaSettings(args) {
 /** Validates exposure and plans the finished-run Observer, or returns undefined after refusing. */
 function prepareCuaWatch(args, settings) {
     // Validate exposure up front (fail-closed matrix), before any run/spend. A live CUA watch is the
-    // one surface that serves runtime E2B stream URLs, so it MUST sit behind edge auth.
+    // one surface that serves runtime E2B stream URLs, so it must sit behind edge auth.
     const exposeValidation = validateExposure("watch", exposureRequestFromOptions(args.options), {
         dryRun: settings.dryRun,
         detach: args.options.detach === true,
@@ -123,7 +122,7 @@ function prepareCuaWatch(args, settings) {
         return undefined;
     return { exposure: exposeValidation.plan, finishedPlan };
 }
-/** The runLab options for this invocation, with the live Observer hook for a followed watch. */
+/** The runStudyWith options for this invocation, with the live Observer hook for a followed watch. */
 function cuaRunOptions(args, settings, prepared, live) {
     const { finishedPlan } = prepared;
     return {
@@ -141,7 +140,7 @@ function cuaRunOptions(args, settings, prepared, live) {
         dryRun: settings.dryRun,
         ...(settings.wantsFollow
             ? {
-                // Fires INSIDE runLab, before the actor loop and before sandbox creation, so a
+                // Fires inside runStudyWith, before the actor loop and before sandbox creation, so a
                 // tunnel-auth failure aborts before any spend and leaves no orphaned sandbox.
                 onObserverReady: (observer) => attachLiveObserver(args.io, settings, prepared.exposure, live, observer),
             }
@@ -214,7 +213,7 @@ async function attachLiveObserver(io, settings, exposure, live, observer) {
 async function reportCuaRun(args, prepared, result, live) {
     const { server, observer: attachedObserver } = live;
     const exposeRequested = prepared.exposure.exposed;
-    // Serving is NOT gated on result.ok: a timed_out, incomplete or failed run still comes up so the
+    // Serving is not gated on result.ok: a timed_out, incomplete or failed run still comes up so the
     // operator can inspect its evidence live (and, under --expose, from a phone).
     let output = result;
     if (server && attachedObserver) {
@@ -224,7 +223,7 @@ async function reportCuaRun(args, prepared, result, live) {
             observer: withObserverServer(attachedResult, server),
             warnings: [
                 ...result.warnings,
-                "Live CUA server is polling observer-data.json with no-store caching.",
+                "The live computer-use server polls observer-data.json with no-store caching.",
                 ...(exposeRequested
                     ? [
                         `Exposed live desktop stream URLs to an edge-authenticated remote viewer${live.tunnel ? ` via ${live.tunnel.url.replace(/\/$/, "")}` : ""}.`,
@@ -236,7 +235,7 @@ async function reportCuaRun(args, prepared, result, live) {
             ],
         };
     }
-    writeResult(args.command, args.io, output, formatCuaLabHuman);
+    writeResult(args.command, args.io, output, formatCuaStudyHuman);
     args.io.setExitCode(result.ok && automaticAnalysisSucceeded(result) ? 0 : 2);
     if (server && (result.observer?.ok || attachedObserver)) {
         const followResult = output.observer?.ok

package/dist/cli/commands/{lab-route-open.d.ts → study-route-open.d.ts}

@@ -1,10 +1,10 @@
 import { Command } from "commander";
-import type { CliIo, LabCommandOptions } from "../io.js";
+import type { CliIo, StudyCommandOptions } from "../io.js";
 import { type ObserverPlan } from "../observer-follow.js";
 /**
- * Default browser-open policy for a lab route's run. Mirrors the observe/watch gate:
+ * Default browser-open policy for a study route's run. Mirrors the observe/watch gate:
  * an explicit --open/--no-open wins; --json (machine mode) never auto-opens; otherwise a
- * lab-config `defaults.open` wins, and the final fallback opens only for an interactive
+ * study-file `defaults.open` wins, and the final fallback opens only for an interactive
  * `watch` on a real TTY. Extracted so every route's CLI setup shares one gate (and one test).
  */
 export declare function resolveRouteShouldOpen(args: {
@@ -21,7 +21,7 @@ export declare function watchFinishedPlan(args: {
     command: Command;
     io: CliIo;
     mode: "run" | "watch";
-    options: LabCommandOptions;
+    options: StudyCommandOptions;
 }, wantsMachine: boolean, shouldOpen: boolean): ObserverPlan | null | undefined;
 /** The route's static render opens only when nothing else will open the Observer. */
 export declare function observerOpen(mode: "run" | "watch", finishedPlan: ObserverPlan | undefined, shouldOpen: boolean): boolean;

package/dist/cli/commands/{lab-route-open.js → study-route-open.js}

@@ -1,9 +1,9 @@
 import { Command } from "commander";
 import { planObserver, staticObserverOpen } from "../observer-follow.js";
 /**
- * Default browser-open policy for a lab route's run. Mirrors the observe/watch gate:
+ * Default browser-open policy for a study route's run. Mirrors the observe/watch gate:
  * an explicit --open/--no-open wins; --json (machine mode) never auto-opens; otherwise a
- * lab-config `defaults.open` wins, and the final fallback opens only for an interactive
+ * study-file `defaults.open` wins, and the final fallback opens only for an interactive
  * `watch` on a real TTY. Extracted so every route's CLI setup shares one gate (and one test).
  */
 export function resolveRouteShouldOpen(args) {

package/dist/cli/commands/{lab-route-preview.d.ts → study-route-preview.d.ts}

@@ -1,17 +1,17 @@
 import { Command } from "commander";
-import type { LabConfig } from "../../lab/types.js";
-import { type CliIo, type LabCommandOptions } from "../io.js";
-import type { RouteRun } from "./lab-route-run.js";
+import type { StudyConfig } from "../../study/types.js";
+import { type CliIo, type StudyCommandOptions } from "../io.js";
+import type { RouteRun } from "./study-route-run.js";
 interface PreviewRouteArgs {
     command: Command;
     io: CliIo;
-    lab: string;
-    config: LabConfig;
+    study: string;
+    config: StudyConfig;
     mode: "run" | "watch";
-    options: LabCommandOptions;
+    options: StudyCommandOptions;
 }
 /**
- * The preview route's CLI setup: the participant count and Observer plan, its runLab options, and how it
+ * The preview route's CLI setup: the participant count and Observer plan, its runStudyWith options, and how it
  * presents the outcome. Undefined when setup has already written its own result.
  */
 export declare function previewRouteRun(args: PreviewRouteArgs): RouteRun | undefined;

package/dist/cli/commands/{lab-route-preview.js → study-route-preview.js}

@@ -1,20 +1,21 @@
 import { Command } from "commander";
-import { formatRunHuman, parseLabCount, writeResult, } from "../io.js";
+import { studyResultIdentity } from "../../run/study-result.js";
+import { formatRunHuman, parseStudyCount, writeResult, } from "../io.js";
 import { planObserver, showObserver, staticObserverOpen } from "../observer-follow.js";
 /**
- * The preview route's CLI setup: the participant count and Observer plan, its runLab options, and how it
+ * The preview route's CLI setup: the participant count and Observer plan, its runStudyWith options, and how it
  * presents the outcome. Undefined when setup has already written its own result.
  */
 export function previewRouteRun(args) {
-    const participantCount = parseLabCount(args.options.count, args.config.actors[0]?.count ?? 4);
+    const participantCount = parseStudyCount(args.options.count, args.config.actors[0]?.count ?? 4);
     if (participantCount === null) {
         const result = {
-            schema: "humanish.run-result.v1",
+            ...studyResultIdentity("preview", args.config.id),
             ok: false,
             cwd: args.options.cwd,
             warnings: [],
             error: {
-                code: "HUMANISH_INVALID_SIM_COUNT",
+                code: "HUMANISH_INVALID_PARTICIPANT_COUNT",
                 message: "--count must be a positive integer.",
             },
         };
@@ -23,7 +24,7 @@ export function previewRouteRun(args) {
         return undefined;
     }
     // `run` renders the Observer too, so `run` and `watch` write the same bundle and the first
-    // `export` of a run bundle finds observer/index.html (#597). A render failure is a warning on the
+    // `export` of a run bundle finds observer/index.html. A render failure is a warning on the
     // result, never a failed run. The preview renders through its finished run, so the page shown is
     // the run just written, never a directory swapped in under its id.
     const openOverride = args.options.open ?? args.config.defaults?.open;

package/dist/cli/commands/study-route-run.d.ts

@@ -0,0 +1,19 @@
+import { type InternalRunStudyOptions, type StudyOutcome } from "../../run-study.js";
+import type { StudyConfig } from "../../study/types.js";
+import type { LoadedAdapterScorer } from "./study-scorer.js";
+export interface RouteRun {
+    readonly options: InternalRunStudyOptions;
+    present(outcome: StudyOutcome): Promise<void>;
+    /** Handles an error runStudyWith threw, and rethrows any it does not handle. */
+    onRunError?(error: unknown): Promise<void>;
+}
+/**
+ * Plans the study with a route's options, then presents the refusal or the run. `beforeRun` runs
+ * only for a plan that will run: it loads the scorer, or writes its own refusal and returns
+ * undefined, so a refused study never imports the scorer's host code. `afterRun` runs once runStudyWith
+ * has returned or thrown, before presentation, which may hold its own signal handlers (watch's
+ * Observer and tunnel).
+ */
+export declare function runRoute(config: StudyConfig, run: RouteRun, beforeRun?: () => Promise<{
+    scorer?: LoadedAdapterScorer;
+} | undefined>, afterRun?: () => void): Promise<void>;

package/dist/cli/commands/{lab-route-run.js → study-route-run.js}

@@ -1,17 +1,17 @@
-// What a route's CLI setup hands the lab command: the runLab options it chose and how it presents
-// the outcome. runRoute plans the lab once and runs it between the two.
-import { prepareLab } from "../../run-lab.js";
+// What a route's CLI setup hands the run command: the runStudyWith options it chose and how it presents
+// the outcome. runRoute plans the study once and runs it between the two.
+import { prepareStudy } from "../../run-study.js";
 /**
- * Plans the lab with a route's options, then presents the refusal or the run. `beforeRun` runs
+ * Plans the study with a route's options, then presents the refusal or the run. `beforeRun` runs
  * only for a plan that will run: it loads the scorer, or writes its own refusal and returns
- * undefined, so a refused lab never imports the scorer's host code. `afterRun` runs once runLab
+ * undefined, so a refused study never imports the scorer's host code. `afterRun` runs once runStudyWith
  * has returned or thrown, before presentation, which may hold its own signal handlers (watch's
  * Observer and tunnel).
  */
 export async function runRoute(config, run, beforeRun = () => Promise.resolve({}), afterRun = () => undefined) {
     let outcome;
     try {
-        const prepared = await prepareLab(config, run.options);
+        const prepared = await prepareStudy(config, run.options);
         if (prepared.ok) {
             const ready = await beforeRun();
             if (ready === undefined)

package/dist/cli/commands/study-route-scripted.d.ts

@@ -0,0 +1,17 @@
+import { Command } from "commander";
+import type { StudyConfig } from "../../study/types.js";
+import { type CliIo, type StudyCommandOptions } from "../io.js";
+import type { RouteRun } from "./study-route-run.js";
+interface ScriptedRouteArgs {
+    command: Command;
+    io: CliIo;
+    config: StudyConfig;
+    mode: "run" | "watch";
+    options: StudyCommandOptions;
+}
+/**
+ * The scripted route's CLI setup: its open semantics and runStudyWith options, and how it presents the
+ * outcome. Undefined when watch-mode setup has already written its own result.
+ */
+export declare function scriptedRouteRun(args: ScriptedRouteArgs): RouteRun | undefined;
+export {};

package/dist/cli/commands/{lab-route-scripted.js → study-route-scripted.js}

@@ -3,10 +3,10 @@ import { Command } from "commander";
 import { cliAnalysisOptions } from "./analysis-signals.js";
 import { wantsJson, writeResult } from "../io.js";
 import { showObserver } from "../observer-follow.js";
-import { formatScriptedLabHuman } from "./lab-format.js";
-import { observerOpen, resolveRouteShouldOpen, watchFinishedPlan } from "./lab-route-open.js";
+import { formatScriptedStudyHuman } from "./study-format.js";
+import { observerOpen, resolveRouteShouldOpen, watchFinishedPlan } from "./study-route-open.js";
 /**
- * The scripted route's CLI setup: its open semantics and runLab options, and how it presents the
+ * The scripted route's CLI setup: its open semantics and runStudyWith options, and how it presents the
  * outcome. Undefined when watch-mode setup has already written its own result.
  */
 export function scriptedRouteRun(args) {
@@ -33,7 +33,7 @@ export function scriptedRouteRun(args) {
                 throw new Error(`Expected the scripted route, got ${outcome.route}.`);
             }
             const result = outcome.result;
-            writeResult(args.command, args.io, result, formatScriptedLabHuman);
+            writeResult(args.command, args.io, result, formatScriptedStudyHuman);
             args.io.setExitCode(result.ok && automaticAnalysisSucceeded(result) ? 0 : 2);
             // Watch mode serves the Observer the route rendered through its finished run.
             if (finishedPlan !== undefined && result.ok && result.observer !== undefined) {

package/dist/cli/commands/{lab-route-shared-world.d.ts → study-route-shared-world.d.ts}

@@ -1,13 +1,13 @@
 import { Command } from "commander";
-import type { LabConfig } from "../../lab/types.js";
-import { type CliIo, type LabCommandOptions } from "../io.js";
-import type { RouteRun } from "./lab-route-run.js";
+import type { StudyConfig } from "../../study/types.js";
+import { type CliIo, type StudyCommandOptions } from "../io.js";
+import type { RouteRun } from "./study-route-run.js";
 interface SharedWorldRouteArgs {
     command: Command;
     io: CliIo;
-    config: LabConfig;
+    config: StudyConfig;
     mode: "run" | "watch";
-    options: LabCommandOptions;
+    options: StudyCommandOptions;
 }
 /**
  * The shared-world route's CLI setup: dry run, open and follow semantics, the live Observer server

package/dist/cli/commands/{lab-route-shared-world.js → study-route-shared-world.js}

@@ -1,14 +1,15 @@
 import { automaticAnalysisSucceeded } from "../../analysis/automatic-completion.js";
 import { Command } from "commander";
-import { resolveLabDryRun } from "../../lab/plan.js";
+import { resolveStudyDryRun } from "../../study/plan.js";
 import { serveObserver } from "../../observer/render.js";
 import { redactText } from "../../evidence/redaction.js";
 import { cliAnalysisOptions } from "./analysis-signals.js";
 import { parseObserverPort, wantsJson, writeResult, } from "../io.js";
 import { followObserver, showObserver, staticObserverOpen, withObserverServer, } from "../observer-follow.js";
-import { formatConcurrentSharedWorldLabHuman } from "./lab-format.js";
-import { resolveRouteShouldOpen, watchFinishedPlan } from "./lab-route-open.js";
-import { rosterOf } from "../../lab/parse/actors.js";
+import { formatConcurrentSharedWorldStudyHuman } from "./study-format.js";
+import { resolveRouteShouldOpen, watchFinishedPlan } from "./study-route-open.js";
+import { rosterOf } from "../../study/parse/actors.js";
+import { studyResultIdentity } from "../../run/study-result.js";
 /**
  * The shared-world route's CLI setup: dry run, open and follow semantics, the live Observer server
  * the run attaches, and how it presents the outcome. Undefined when setup has already written its
@@ -16,7 +17,7 @@ import { rosterOf } from "../../lab/parse/actors.js";
  */
 export function sharedWorldRouteRun(args) {
     const wantsMachine = wantsJson(args.command);
-    const dryRun = resolveLabDryRun(args.config, args.options.dryRun, true) ?? true;
+    const dryRun = resolveStudyDryRun(args.config, args.options.dryRun, true) ?? true;
     const shouldOpen = resolveRouteShouldOpen({
         optionOpen: args.options.open,
         defaultsOpen: args.config.defaults?.open,
@@ -27,10 +28,9 @@ export function sharedWorldRouteRun(args) {
     const port = parseObserverPort(args.options.port ?? "0");
     const failConcurrent = (message, runId) => {
         const result = {
-            schema: "humanish.concurrent-shared-world-lab-result.v1",
+            ...studyResultIdentity("shared-world", args.config.id),
             ok: false,
             cwd: args.options.cwd,
-            labId: args.config.id,
             actor: args.config.actors[0]?.type ?? "",
             topology: "shared-world",
             topologyMode: "concurrent",
@@ -40,9 +40,9 @@ export function sharedWorldRouteRun(args) {
             runId: runId ?? args.options.runId ?? "not-created",
             roles: [],
             warnings: [],
-            error: { code: "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_FAILED", message },
+            error: { code: "HUMANISH_SHARED_WORLD_FAILED", message },
         };
-        writeResult(args.command, args.io, result, formatConcurrentSharedWorldLabHuman);
+        writeResult(args.command, args.io, result, formatConcurrentSharedWorldStudyHuman);
         args.io.setExitCode(2);
     };
     if (wantsFollow && port === null) {
@@ -116,7 +116,7 @@ export function sharedWorldRouteRun(args) {
                     ],
                 };
             }
-            writeResult(args.command, args.io, output, formatConcurrentSharedWorldLabHuman);
+            writeResult(args.command, args.io, output, formatConcurrentSharedWorldStudyHuman);
             args.io.setExitCode(result.ok && automaticAnalysisSucceeded(result) ? 0 : 2);
             if (server && output.observer?.ok) {
                 await followObserver(args.io, output.observer, server);

package/dist/cli/commands/study-route-terminal.d.ts

@@ -0,0 +1,17 @@
+import { Command } from "commander";
+import type { StudyConfig } from "../../study/types.js";
+import { type CliIo, type StudyCommandOptions } from "../io.js";
+import type { RouteRun } from "./study-route-run.js";
+interface TerminalRouteArgs {
+    command: Command;
+    io: CliIo;
+    config: StudyConfig;
+    mode: "run" | "watch";
+    options: StudyCommandOptions;
+}
+/**
+ * The terminal route's CLI setup: its open semantics and runStudyWith options, and how it presents the
+ * outcome. Undefined when watch-mode setup has already written its own result.
+ */
+export declare function terminalRouteRun(args: TerminalRouteArgs): RouteRun | undefined;
+export {};

package/dist/cli/commands/{lab-route-terminal.js → study-route-terminal.js}

@@ -3,10 +3,10 @@ import { Command } from "commander";
 import { cliAnalysisOptions } from "./analysis-signals.js";
 import { wantsJson, writeResult } from "../io.js";
 import { showObserver } from "../observer-follow.js";
-import { formatTerminalLabHuman } from "./lab-format.js";
-import { observerOpen, resolveRouteShouldOpen, watchFinishedPlan } from "./lab-route-open.js";
+import { formatTerminalStudyHuman } from "./study-format.js";
+import { observerOpen, resolveRouteShouldOpen, watchFinishedPlan } from "./study-route-open.js";
 /**
- * The terminal route's CLI setup: its open semantics and runLab options, and how it presents the
+ * The terminal route's CLI setup: its open semantics and runStudyWith options, and how it presents the
  * outcome. Undefined when watch-mode setup has already written its own result.
  */
 export function terminalRouteRun(args) {
@@ -33,7 +33,7 @@ export function terminalRouteRun(args) {
                 throw new Error(`Expected the terminal route, got ${outcome.route}.`);
             }
             const result = outcome.result;
-            writeResult(args.command, args.io, result, formatTerminalLabHuman);
+            writeResult(args.command, args.io, result, formatTerminalStudyHuman);
             args.io.setExitCode(result.ok && automaticAnalysisSucceeded(result) ? 0 : 2);
             if (finishedPlan !== undefined && result.ok && result.observer !== undefined) {
                 await showObserver({

package/dist/cli/commands/study-run.d.ts

@@ -0,0 +1,9 @@
+import { Command } from "commander";
+import { type CliIo, type StudyCommandOptions } from "../io.js";
+export declare function runStudyCommand(args: {
+    command: Command;
+    io: CliIo;
+    study: string;
+    mode: "run" | "watch";
+    options: StudyCommandOptions;
+}): Promise<void>;