humanish 0.106.1 → 0.108.0

package/dist/cli/commands/comms.js

@@ -1,19 +1,21 @@
 import { resolve } from "node:path";
 import { Command } from "commander";
 import { COMMS_PROVIDERS, saveCommsConnection } from "../../comms/connections.js";
+import { catchTokenRefusal } from "../../comms/external-evidence.js";
 import { readCommsSetup } from "../../comms/setup.js";
 import { checkCommsConnection, configureCommsLab } from "../../comms/setup.js";
 import { inspectCommsRecovery, recoverCommsReceiving } from "../../comms/receiving-recovery.js";
 import { resolveReceivingConnection } from "../../comms/receiving-runtime.js";
 import { resolveLabManifest } from "../../lab/discover.js";
+import { oldStudyOption, studyOptionValue } from "../deprecations.js";
 import { runCommsCatchHost } from "../../comms/catch-host.js";
 import { DEFAULT_SANDBOX_CATCH_PORT } from "../../comms/sandbox-catch.js";
-import { applyEnvFileOption, JSON_OPTION_DESCRIPTION, writeResult } from "../io.js";
+import { applyEnvFileOption, CWD_OPTION_DESCRIPTION, ENV_FILE_OPTION_DESCRIPTION, JSON_OPTION_DESCRIPTION, PORT_OPTION_DESCRIPTION, writeResult, messageOutput, } from "../io.js";
 export function registerCommsCommands(parent, io) {
     const comms = parent
         .command("comms")
         .description("Local email capture, real receiving connections, checks and cleanup recovery.")
-        .summary("Off-app comms surfaces.");
+        .summary("Catch the email an app sends, for email-gated flows.");
     comms
         .command("providers")
         .description("List installed communication provider capabilities. No network requests.")
@@ -21,61 +23,70 @@ export function registerCommsCommands(parent, io) {
         .action((_options, command) => handleCommsProviders(io, _options, command));
     const connections = comms
         .command("connections")
-        .description("Manage project-local non-secret connection profiles. A lab explicitly selects its receiving connection.");
+        .description("Manage project-local non-secret connection profiles. A study explicitly selects its receiving connection.");
     connections
         .command("list")
         .description("Show saved connections and local credential status; does not authenticate with a provider.")
-        .option("--cwd <path>", "Target project directory.", ".")
-        .option("--env-file <path>", "Load credentials for local status without printing values.")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
+        .option("--env-file <path>", ENV_FILE_OPTION_DESCRIPTION)
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action((options, command) => handleCommsList(io, options, command));
     connections
         .command("add")
         .argument("[name]", "Project connection name.", "agentmail")
-        .description("Save an AgentMail connection profile. Does not write a key, alter a lab or contact the provider.")
-        .option("--cwd <path>", "Target project directory.", ".")
+        .description("Save an AgentMail connection profile. Does not write a key, alter a study or contact the provider.")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--provider <id>", "Installed provider id.", "agentmail")
-        .option("--api-key-env <name>", "Environment variable NAME, never its value.", "AGENTMAIL_API_KEY")
+        .option("--api-key-env <name>", "The name of an environment variable, never its value.", "AGENTMAIL_API_KEY")
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action((name, options, command) => handleCommsAdd(io, name, options, command));
     comms
         .command("check")
         .description("Check connection and credential presence; --online authenticates without creating inboxes.")
-        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--connection <name>", "Saved connection name.", "agentmail")
-        .option("--lab <path>", "Check the connection selected by this exact lab.")
+        .option("--study <path>", "Check the connection this study selects.")
+        .addOption(oldStudyOption("path"))
         .option("--online", "Make a read-only provider authentication request.")
-        .option("--env-file <path>", "Load credentials without printing values.")
+        .option("--env-file <path>", ENV_FILE_OPTION_DESCRIPTION)
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action((options, command) => handleCommsCheck(io, options, command));
     comms
         .command("configure")
-        .description("Preview or save a local receiving-enabled copy of a supported lab. No provider requests.")
-        .requiredOption("--lab <path>", "Exact source lab path or handle.")
-        .option("--cwd <path>", "Target project directory.", ".")
+        .description("Preview or save a local receiving-enabled copy of a supported study. No provider requests.")
+        // Required, but checked in the action, so --lab still works for one minor.
+        .option("--study <path>", "Source study path or name. Required.")
+        .addOption(oldStudyOption("path"))
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--connection <name>", "Saved connection name.", "agentmail")
-        .option("--apply", "Save the local copy; original lab remains unchanged.")
+        .option("--apply", "Save the local copy; the source study stays unchanged.")
         .option("--plan-token <digest>", "Require the source and destination to match a previous preview.")
         .option("--json", JSON_OPTION_DESCRIPTION)
+        .hook("preAction", (command) => {
+        const options = command.opts();
+        // The message commander gives a missing required option.
+        if (options.study === undefined && options.lab === undefined)
+            command.error("error: required option '--study <path>' not specified");
+    })
         .action((options, command) => handleCommsConfigure(io, options, command));
     comms
         .command("recover")
         .description("Inspect interrupted email leases; --apply deletes only privately recorded resources owned by this project and account.")
-        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--run <id>", "One run to inspect or recover.")
         .option("--apply", "Recover the selected inactive run and verify mailbox deletion.")
-        .option("--env-file <path>", "Load credentials without printing values.")
+        .option("--env-file <path>", ENV_FILE_OPTION_DESCRIPTION)
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action((options, command) => handleCommsRecover(io, options, command));
     comms
         .command("catch")
-        .description("Run the email catch on this host so humanish can study an app it does not provision. Your app posts its email sends here; the persona opens /inbox; humanish drains GET /deliveries and writes digest-only evidence. Point your lab's comms.email.external.catchBaseUrl at this server.")
-        .summary("Run the adopter-hosted email catch.")
-        .option("--port <port>", "Port for capture + inbox (default 8025).", String(DEFAULT_SANDBOX_CATCH_PORT))
+        .description("Run the email catch on this host so humanish can study an app it does not provision. Your app posts its email sends here; the persona opens /inbox; humanish drains GET /deliveries and writes digest-only evidence. Point your study's comms.email.external.catchBaseUrl at this server.")
+        .summary("Run the email catch on this host.")
+        .option("--port <port>", PORT_OPTION_DESCRIPTION, String(DEFAULT_SANDBOX_CATCH_PORT))
         .option("--dir <path>", "Directory for the deliveries log and rendered inbox.", ".humanish/comms-catch")
-        .option("--token <value>", "Require this bearer token on GET /deliveries (recommended when reachable off-host).")
+        .option("--token <value>", "Require this bearer token, at least 16 characters, on GET /deliveries (recommended when reachable off-host).")
         .option("--smtp-port <port>", "Also capture SMTP mail on 127.0.0.1:<port>. Point your app's SMTP transport here.")
-        .option("--inbox-port <port>", "Also serve a READ-ONLY inbox listener on 0.0.0.0:<port>, so a persona on another machine can open /inbox. Without it the catch stays loopback-only.")
+        .option("--inbox-port <port>", "Also serve a read-only inbox listener on 0.0.0.0:<port>, so a persona on another machine can open /inbox. Without it the catch stays loopback-only.")
         .option("--recipient <address>", "Only render mail sent to this address (repeatable). Default: render whatever the app actually mailed.", (value, previous) => [...(previous ?? []), value])
         .action((options) => handleCommsCatch(io, options));
 }
@@ -101,25 +112,26 @@ async function handleCommsAdd(io, name, options, command) {
             ? await saveCommsConnection(resolve(options.cwd), name, options.apiKeyEnv)
             : { ok: false, message: "Only AgentMail connection setup is currently available." }),
     };
-    writeResult(command, io, result, (value) => `${value.message}\n`);
+    writeResult(command, io, result, messageOutput);
     io.setExitCode(result.ok ? 0 : 2);
 }
 async function handleCommsCheck(io, options, command) {
     if (!(await applyEnvFileOption({ command, cwd: options.cwd, envFile: options.envFile, io })))
         return;
     let connection = options.connection;
-    if (options.lab) {
-        const lab = await resolveLabManifest(options.cwd, options.lab);
-        if (!lab.ok || lab.config.comms?.email?.kind !== "real") {
+    const study = studyOptionValue(command, io, options);
+    if (study) {
+        const resolved = await resolveLabManifest(options.cwd, study);
+        if (!resolved.ok || resolved.config.comms?.email?.kind !== "real") {
             const result = {
                 ok: false,
-                message: "This lab does not select a real email connection.",
+                message: "This study does not select a real email connection.",
             };
-            writeResult(command, io, result, (value) => `${value.message}\n`);
+            writeResult(command, io, result, messageOutput);
             io.setExitCode(2);
             return;
         }
-        connection = lab.config.comms.email.connection;
+        connection = resolved.config.comms.email.connection;
     }
     const result = await checkCommsConnection({
         cwd: resolve(options.cwd),
@@ -127,12 +139,22 @@ async function handleCommsCheck(io, options, command) {
         env: process.env,
         online: options.online === true,
     });
-    writeResult(command, io, result, (value) => `${value.message}\n`);
+    writeResult(command, io, result, messageOutput);
     io.setExitCode(result.ok ? 0 : 2);
 }
 async function handleCommsConfigure(io, options, command) {
-    const result = await configureCommsLab({ ...options, cwd: resolve(options.cwd) });
-    writeResult(command, io, result, (value) => `${value.message}\n`);
+    const study = studyOptionValue(command, io, options);
+    // The preAction hook refuses a call without either option.
+    if (study === undefined)
+        return;
+    const result = await configureCommsLab({
+        cwd: resolve(options.cwd),
+        lab: study,
+        connection: options.connection,
+        ...(options.apply === undefined ? {} : { apply: options.apply }),
+        ...(options.planToken === undefined ? {} : { planToken: options.planToken }),
+    });
+    writeResult(command, io, result, messageOutput);
     io.setExitCode(result.ok ? 0 : 2);
 }
 async function handleCommsRecover(io, options, command) {
@@ -164,7 +186,7 @@ async function handleCommsRecover(io, options, command) {
                 adapter,
             })),
         };
-        writeResult(command, io, result, (value) => `${value.message}\n`);
+        writeResult(command, io, result, messageOutput);
         io.setExitCode(result.ok ? 0 : 2);
     }
     catch {
@@ -173,11 +195,17 @@ async function handleCommsRecover(io, options, command) {
             ok: false,
             message: "Recovery could not complete. Select one recorded run with --run, check its connection, and retry. No unrecorded resources are eligible.",
         };
-        writeResult(command, io, result, (value) => `${value.message}\n`);
+        writeResult(command, io, result, messageOutput);
         io.setExitCode(2);
     }
 }
 async function handleCommsCatch(io, options) {
+    const tokenRefusal = catchTokenRefusal(options.token);
+    if (tokenRefusal !== undefined) {
+        io.writeErr(`--token: ${tokenRefusal} The token guards GET /deliveries, and runs scrub it from their warnings.\n`);
+        io.setExitCode(2);
+        return;
+    }
     const port = Number.parseInt(options.port, 10);
     if (!Number.isInteger(port) || port <= 0 || port > 65_534) {
         io.writeErr("--port must be an integer between 1 and 65534.\n");

package/dist/cli/commands/feedback.js

@@ -1,24 +1,24 @@
 import { Command } from "commander";
 import { draftFeedback, listFeedback, renderIssueMarkdown, renderIssueUrl, verifyFeedback, } from "../../feedback/feedback.js";
-import { candidateOption, JSON_OPTION_DESCRIPTION, wantsJson, writeResult, } from "../io.js";
+import { candidateOption, CWD_OPTION_DESCRIPTION, JSON_OPTION_DESCRIPTION, RUN_OPTION_DESCRIPTION, wantsJson, writeResult, humanError, writeHuman, } from "../io.js";
 export function registerFeedbackCommands(parent, io) {
     const feedback = parent
         .command("feedback")
-        .description("Create public-safe feedback drafts without GitHub API mutation.")
-        .summary("Create public-safe feedback drafts, no GitHub API.");
+        .description("Draft public-safe feedback issues from a run. humanish never calls the GitHub API.")
+        .summary("Draft public-safe feedback issues from a run.");
     feedback
         .command("list")
         .description("List recorded feedback candidates and any saved draft.")
-        .addHelpText("after", "\nWith no candidates, feedback draft and feedback issue can generate a run-summary follow-up. Public drafting still requires share_ready verification.\n")
-        .option("--run <id>", "Run id or latest pointer.", "latest")
-        .option("--cwd <path>", "Target project directory.", ".")
+        .addHelpText("after", "\nWith no candidates, feedback draft and feedback issue write a run-summary follow-up for a live run that verifies share_ready. A dry run gets no draft.\n")
+        .option("--run <id>", RUN_OPTION_DESCRIPTION, "latest")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action((options, command) => handleFeedbackList(io, options, command));
     feedback
         .command("draft")
         .description("Generate a public-safe feedback draft from verified evidence.")
-        .option("--run <id>", "Run id or latest pointer.", "latest")
-        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--run <id>", RUN_OPTION_DESCRIPTION, "latest")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--analysis <id>", "Independent analysis version; use with --finding.")
         .option("--finding <id>", "Finding within --analysis, separate from participant candidates.")
         .option("--candidate <id>", "Which finding to draft (ids from `feedback list`); default: the first.")
@@ -27,8 +27,8 @@ export function registerFeedbackCommands(parent, io) {
     feedback
         .command("verify")
         .description("Verify the feedback draft for public issue eligibility.")
-        .option("--run <id>", "Run id or latest pointer.", "latest")
-        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--run <id>", RUN_OPTION_DESCRIPTION, "latest")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .option("--analysis <id>", "Independent analysis version; use with --finding.")
         .option("--finding <id>", "Finding within --analysis, separate from participant candidates.")
         .option("--candidate <id>", "Which finding to verify (ids from `feedback list`); default: the first.")
@@ -37,8 +37,8 @@ export function registerFeedbackCommands(parent, io) {
     feedback
         .command("issue")
         .description("Print Markdown for a public GitHub issue. Does not mutate GitHub.")
-        .option("--run <id>", "Run id or latest pointer.", "latest")
-        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--run <id>", RUN_OPTION_DESCRIPTION, "latest")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .requiredOption("--repo <owner/repo>", "Repository slug used in rendered filing instructions.")
         .option("--format <format>", "Output format.", "markdown")
         .option("--analysis <id>", "Independent analysis version; use with --finding.")
@@ -49,8 +49,8 @@ export function registerFeedbackCommands(parent, io) {
     feedback
         .command("issue-url")
         .description("Print a prefilled public issue URL. Does not mutate GitHub.")
-        .option("--run <id>", "Run id or latest pointer.", "latest")
-        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--run <id>", RUN_OPTION_DESCRIPTION, "latest")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
         .requiredOption("--repo <owner/repo>", "Repository slug used in the generated URL.")
         .option("--analysis <id>", "Independent analysis version; use with --finding.")
         .option("--finding <id>", "Finding within --analysis, separate from participant candidates.")
@@ -87,7 +87,7 @@ async function handleFeedbackIssue(io, options, command) {
         io.writeOut(result.issueMarkdown);
     }
     else {
-        io.writeErr(formatFeedbackHuman(result));
+        writeHuman(command, io, formatFeedbackHuman(result));
     }
     io.setExitCode(result.ok ? 0 : 2);
 }
@@ -100,14 +100,13 @@ async function handleFeedbackIssueUrl(io, options, command) {
         io.writeOut(`${result.issueUrl}\n`);
     }
     else {
-        io.writeErr(formatFeedbackHuman(result));
+        writeHuman(command, io, formatFeedbackHuman(result));
     }
     io.setExitCode(result.ok ? 0 : 2);
 }
 function formatFeedbackHuman(result) {
-    if (!result.ok) {
-        return `${result.error?.code}: ${result.error?.message}\n`;
-    }
+    if (!result.ok)
+        return humanError(result.error);
     const candidates = result.candidates ?? [];
     const noCandidates = result.candidates !== undefined && candidates.length === 0;
     return ([
@@ -123,11 +122,11 @@ function formatFeedbackHuman(result) {
         ...(noCandidates
             ? [
                 "candidates: none recorded",
-                "With no candidates, feedback draft and feedback issue can generate a run-summary follow-up after share_ready verification.",
+                "With no candidates, feedback draft and feedback issue write a run-summary follow-up for a live run that verifies share_ready.",
                 ...(result.draft ? [`summary: ${result.draft.summary}`] : []),
             ]
             : []),
-        // Every finding the run produced, so the second and third are one flag away (#609).
+        // Every finding the run produced, so the second and third are one flag away.
         ...(candidates.length > 1 || (candidates.length === 1 && result.draft === undefined)
             ? [
                 `candidates (${candidates.length}; choose one with --candidate <id>):`,

package/dist/cli/commands/lab-format.d.ts

@@ -1,8 +1,9 @@
+import type { HumanOutput } from "../io.js";
 import type { CuaActorLabResult } from "../../routes/computer-use/types.js";
 import type { ScriptedBrowserLabResult } from "../../routes/scripted/types.js";
 import type { TerminalProductLabResult } from "../../routes/terminal/types.js";
 import type { ConcurrentSharedWorldLabResult } from "../../routes/shared-world/types.js";
-export declare function formatConcurrentSharedWorldLabHuman(result: ConcurrentSharedWorldLabResult): string;
-export declare function formatTerminalLabHuman(result: TerminalProductLabResult): string;
-export declare function formatScriptedLabHuman(result: ScriptedBrowserLabResult): string;
-export declare function formatCuaLabHuman(result: CuaActorLabResult): string;
+export declare function formatConcurrentSharedWorldLabHuman(result: ConcurrentSharedWorldLabResult): HumanOutput;
+export declare function formatTerminalLabHuman(result: TerminalProductLabResult): HumanOutput;
+export declare function formatScriptedLabHuman(result: ScriptedBrowserLabResult): HumanOutput;
+export declare function formatCuaLabHuman(result: CuaActorLabResult): HumanOutput;

package/dist/cli/commands/lab-format.js

@@ -1,10 +1,28 @@
 import { formatCuaDiagnostics, formatCuaStopCause } from "../../routes/computer-use/diagnostics.js";
+/** A lab 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 formatConcurrentSharedWorldLabHuman(result) {
-    return ([
-        `humanish lab concurrent-shared-world ${result.ok ? (result.dryRun ? "dry-run" : "live") : "failed"}`,
-        ...(result.error ? [`${result.error.code}: ${result.error.message}`] : []),
+    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}`] : []),
+    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}`] : []),
+    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}`] : []),
+    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

@@ -1,5 +1,4 @@
 import { Command } from "commander";
-import type { RunLabProvenance } from "../../run/status.js";
 import type { LabConfig } from "../../lab/types.js";
 import { type CliIo, type LabCommandOptions } from "../io.js";
 import type { RouteRun } from "./lab-route-run.js";
@@ -7,7 +6,6 @@ interface ComputerUseRouteArgs {
     command: Command;
     io: CliIo;
     config: LabConfig;
-    labProvenance?: RunLabProvenance;
     mode: "run" | "watch";
     options: LabCommandOptions;
 }

package/dist/cli/commands/lab-route-computer-use.js

@@ -2,15 +2,16 @@ import { automaticAnalysisSucceeded } from "../../analysis/automatic-completion.
 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 { 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 { exposureRequestFromOptions, followObserver, planObserver, showObserver, staticObserverOpen, withObserverServer, } from "../observer-follow.js";
 import { formatCuaLabHuman } from "./lab-format.js";
 import { resolveRouteShouldOpen } from "./lab-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
  * with the live Observer hook, and how it presents the outcome or a run error. Undefined when
@@ -29,6 +30,7 @@ export function computerUseRouteRun(args) {
         tunnel: undefined,
         exposeWarnings: [],
         publicTarget: undefined,
+        releaseShutdown: undefined,
     };
     return {
         options: cuaRunOptions(args, settings, prepared, live),
@@ -37,16 +39,20 @@ export function computerUseRouteRun(args) {
             if (outcome.route !== "computer-use") {
                 throw new Error(`Expected the computer-use route, got ${outcome.route}.`);
             }
-            await reportCuaRun(args, prepared, outcome.result, live);
+            try {
+                await reportCuaRun(args, prepared, outcome.result, live);
+            }
+            finally {
+                live.releaseShutdown?.();
+            }
         },
     };
 }
 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,
@@ -66,15 +72,15 @@ function resolveCuaSettings(args) {
         mode: args.mode,
         wantsMachine,
     });
-    const participantIds = parseParticipantIds(args.options.lanes);
+    const participantIds = parseParticipantIds(args.options.participants);
     if (participantIds.length > 0 && !args.options.rerunFailedFrom) {
-        args.io.writeErr("error: --lanes requires --rerun-failed-from.\n");
+        args.io.writeErr("error: --participants requires --rerun-failed-from.\n");
         args.io.setExitCode(2);
         return undefined;
     }
-    const count = parseLabCount(args.options.count ?? args.options.sims, args.config.actors[0]?.count ?? 1);
+    const count = parseLabCount(args.options.count, args.config.actors[0]?.count ?? 1);
     if (count === null) {
-        args.io.writeErr("error: --count/--sims must be a positive integer.\n");
+        args.io.writeErr("error: --count must be a positive integer.\n");
         args.io.setExitCode(2);
         return undefined;
     }
@@ -90,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,
@@ -122,7 +128,6 @@ function cuaRunOptions(args, settings, prepared, live) {
     return {
         ...cliAnalysisOptions(args.io),
         cwd: args.options.cwd,
-        ...(args.labProvenance === undefined ? {} : { lab: args.labProvenance }),
         // A followed watch opens the served Observer (or prints the phone target under --expose), so
         // its static render never opens. A non-follow watch opens what its plan says, once. Run mode
         // keeps the static open.
@@ -135,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 runLab, 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),
             }
@@ -153,20 +158,24 @@ function cuaRunOptions(args, settings, prepared, live) {
             }),
     };
 }
+/** Closes the loopback server and any tunnel the watch attached. Safe to call twice. */
+async function closeLiveAttachment(io, live) {
+    const { server, tunnel } = live;
+    live.server = null;
+    live.tunnel = undefined;
+    await server?.close().catch((cleanupError) => {
+        io.writeErr(`watch cleanup failed: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}\n`);
+    });
+    await tunnel?.close().catch(() => undefined);
+}
 /**
  * Tears down the loopback server and any tunnel started inside onObserverReady, then reports a
  * tunnel startup failure or rethrows. The sandbox is created after onObserverReady returns, so a
  * tunnel failure cannot orphan one.
  */
 async function closeLiveAfterRunError(args, settings, live, error) {
-    await live.server?.close().catch((cleanupError) => {
-        args.io.writeErr(`watch cleanup failed: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}\n`);
-    });
-    live.server = null;
-    if (live.tunnel) {
-        await live.tunnel.close().catch(() => undefined);
-        live.tunnel = undefined;
-    }
+    await closeLiveAttachment(args.io, live);
+    live.releaseShutdown?.();
     if (error instanceof ServeTunnelError) {
         refuseCua(args, settings.dryRun, error.code, error.message);
         return;
@@ -182,6 +191,8 @@ async function attachLiveObserver(io, settings, exposure, live, observer) {
             port: settings.port,
             exposed: exposure.exposed,
         });
+        // A signal that stops the run closes the server and any tunnel before the process exits.
+        live.releaseShutdown ??= onRunShutdown(() => closeLiveAttachment(io, live));
     }
     if (exposure.exposed) {
         const activeServer = live.server;
@@ -202,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) {
@@ -212,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(/\/$/, "")}` : ""}.`,

package/dist/cli/commands/lab-route-preview.d.ts

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