humanish 0.107.0 → 0.108.0

package/dist/cli/commands/comms.js

@@ -7,14 +7,15 @@ 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.")
@@ -22,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, 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));
 }
@@ -102,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),
@@ -128,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) {
@@ -165,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 {
@@ -174,7 +195,7 @@ 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);
     }
 }

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.js

@@ -2,7 +2,6 @@ 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";
@@ -12,6 +11,7 @@ import { parseLabCount, parseParticipantIds, parseObserverPort, wantsJson, write
 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
@@ -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,
@@ -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,
@@ -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 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),
             }
@@ -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(/\/$/, "")}` : ""}.`,

package/dist/cli/commands/lab-route-preview.js

@@ -1,4 +1,5 @@
 import { Command } from "commander";
+import { studyResultIdentity } from "../../run/study-result.js";
 import { formatRunHuman, parseLabCount, writeResult, } from "../io.js";
 import { planObserver, showObserver, staticObserverOpen } from "../observer-follow.js";
 /**
@@ -9,12 +10,12 @@ export function previewRouteRun(args) {
     const participantCount = parseLabCount(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/lab-route-shared-world.js

@@ -9,6 +9,7 @@ import { followObserver, showObserver, staticObserverOpen, withObserverServer, }
 import { formatConcurrentSharedWorldLabHuman } from "./lab-format.js";
 import { resolveRouteShouldOpen, watchFinishedPlan } from "./lab-route-open.js";
 import { rosterOf } from "../../lab/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
@@ -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,7 +40,7 @@ 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);
         args.io.setExitCode(2);

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

@@ -3,6 +3,7 @@ import { resolve } from "node:path";
 import { Command } from "commander";
 import { deriveRunFacts } from "../telemetry.js";
 import { resolveLabManifest } from "../../lab/discover.js";
+import { warnAndQueue } from "../deprecations.js";
 import { planLab, resolveLabDryRun } from "../../lab/plan.js";
 import { keyNamesOf } from "../../lab/requirements.js";
 import { routeOf } from "../../lab/plan.js";
@@ -26,12 +27,12 @@ export async function runLabCommand(args) {
     }
     // Surface forward-declared-field + .yml warnings on run/watch too, not only on inspect.
     // Otherwise a setting that does nothing is silently swallowed on the path users actually run.
-    for (const warning of resolved.warnings) {
-        args.io.writeErr(`warning: ${warning}\n`);
-    }
+    // Each also goes into the JSON result's warnings[], so a --json caller sees it.
+    for (const warning of resolved.warnings)
+        warnAndQueue(args.command, args.io, warning);
     const config = resolved.config;
-    // The run's identity (#455): which manifest, where it lives, and whether it is committed, a
-    // local overlay, or an explicit path. Resolved once here — the only place that knows all three —
+    // The run's identity: which manifest, where it lives, and whether it is committed, a
+    // local overlay, or an explicit path. Resolved once here (the only place that knows all three)
     // and carried into the run's status record and bundle so the filesystem can answer "which lab
     // produced this run" without the old `persona.source = "lab:<id>"` string convention.
     const lab = { id: config.id, path: resolved.path, origin: resolved.origin };
@@ -101,7 +102,7 @@ export async function runLabCommand(args) {
     // From here a signal marks the run interrupted and reclaims its sandboxes (run-signals.ts).
     const signals = beginRunSignalPhase(args.io);
     try {
-        // #316: resolve + load a config-declared/CLI-flagged adopter scorer FAIL-CLOSED, before any
+        // Resolve + load a config-declared/CLI-flagged adopter scorer fail-closed, before any
         // spend, and only for a plan that will run. A declared gate that cannot load (bad ref, not
         // found, load failure, no hooks, unsupported route) aborts with exit 2 rather than green-passing.
         await runRoute(config, run, async () => {
@@ -127,7 +128,7 @@ export async function runLabCommand(args) {
             if (scorer) {
                 // Cross-repo guardrail: `humanish lab run` now import()s host JS named in the manifest.
                 // Surface it so the invoker (who may not be the manifest author) knows executable code ran.
-                args.io.writeErr(`warning: review scorer ${scorer.provenance.ref} (${scorer.provenance.source}) is executable host code loaded and run in-process — review it as code, not config.\n`);
+                args.io.writeErr(`warning: review scorer ${scorer.provenance.ref} (${scorer.provenance.source}) is code that humanish loaded and ran in this process. Review it as you would any code you run.\n`);
             }
             const analysisBudget = automaticAnalysisBudget(config.review?.analysis, route);
             if (analysisBudget && resolveLabDryRun(config, args.options.dryRun, true) === false) {
@@ -190,8 +191,6 @@ function writeUnsupportedRerunFlagsResult(args, route) {
     args.io.setExitCode(2);
 }
 function formatLabResolveFailureHuman(result) {
-    return ([
-        `${result.error.code}: ${result.error.message}`,
-        ...result.warnings.map((warning) => `warning: ${warning}`),
-    ].join("\n") + "\n");
+    const warnings = result.warnings.map((warning) => `warning: ${warning}\n`).join("");
+    return { ...(warnings ? { stdout: warnings } : {}), error: result.error };
 }

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

@@ -3,14 +3,14 @@ import type { LabRoute } from "../../lab/plan.js";
 import type { RunScorerProvenance } from "../../run/bundle.js";
 import type { LabConfig } from "../../lab/types.js";
 import type { RunResult } from "../../run/results.js";
-/** A CONFIG-DECLARED scorer that resolved + loaded fail-closed, ready to thread into a backend. */
+/** A config-declared scorer that resolved + loaded fail-closed, ready to thread into a backend. */
 export interface LoadedAdapterScorer {
     hooks: AdapterScorerModule;
     provenance: RunScorerProvenance;
 }
 /**
  * Resolve `review.scorer.ref` (or the `--scorer` override) to a loaded adopter scorer, fail-closed
- * (typed error) PRE-SPEND. Precedence: CLI `--scorer` overrides the manifest; `source` records which
+ * (typed error) pre-spend. Precedence: CLI `--scorer` overrides the manifest; `source` records which
  * won. No scorer declared → `{ ok: true }` with no scorer. A declared scorer on an unsupported
  * backend, or a bad/unreadable/broken ref, → `{ ok: false }` so the caller aborts with exit 2.
  */