humanish 0.106.1 → 0.108.0

package/dist/cli/commands/study.js

@@ -0,0 +1,182 @@
+import { formatAutomaticAnalysisBudget } from "../../analysis/automatic-config.js";
+import { resolve } from "node:path";
+import { Command, Option } from "commander";
+import { inspectLabManifest, listLabManifests } from "../../lab/discover.js";
+import { runLabPreflight, } from "../../lab/preflight.js";
+import { addRunOptions, handleRun } from "./run-command.js";
+import { deprecationMessage, warnAndQueue } from "../deprecations.js";
+import { applyEnvFileOption, CWD_OPTION_DESCRIPTION, ENV_FILE_OPTION_DESCRIPTION, JSON_OPTION_DESCRIPTION, parsePositiveInteger, writeResult, humanError, } from "../io.js";
+export function registerStudyCommands(parent, io) {
+    const study = parent
+        .command("study")
+        .description("List, show and check studies in humanish/studies/.");
+    listCommand(study.command("list"), io);
+    showCommand(study.command("show"), io);
+    checkCommand(study.command("check"), io);
+    // Removed in 0.109.0: the `lab` group stays one minor, hidden. Its list, inspect and preflight
+    // run as study list, show and check, and `lab run` runs as `run`, each after a warning.
+    const lab = parent
+        .command("lab", { hidden: true })
+        .description("Deprecated: use humanish study.");
+    listCommand(lab.command("list"), io, "humanish study list");
+    showCommand(lab.command("inspect"), io, "humanish study show <study>");
+    checkCommand(lab.command("preflight"), io, "humanish study check <study>");
+    addRunOptions(lab.command("run", { hidden: true }).argument("<study>", "Study id or .yaml path.")).action((name, options, command) => {
+        warnOldCommand(command, io, "humanish run <study>");
+        return handleRun(io, name, options, command);
+    });
+}
+/** The warning for a `lab` subcommand, naming its replacement. */
+function warnOldCommand(command, io, replacement) {
+    warnAndQueue(command, io, deprecationMessage(`humanish lab ${command.name()}`, replacement));
+}
+function listCommand(command, io, replacement) {
+    command
+        .description("List the studies in this project, committed and local.")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action((options, command) => {
+        if (replacement !== undefined)
+            warnOldCommand(command, io, replacement);
+        return handleStudyList(io, options, command);
+    });
+    if (replacement !== undefined)
+        command.description(`Deprecated: use ${replacement}.`);
+}
+function showCommand(command, io, replacement) {
+    command
+        .argument("<study>", "Study id or .yaml path.")
+        .description("Show a study's parsed file and its warnings without running it.")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action((name, options, command) => {
+        if (replacement !== undefined)
+            warnOldCommand(command, io, replacement);
+        return handleStudyShow(io, name, options, command);
+    });
+    if (replacement !== undefined)
+        command.description(`Deprecated: use ${replacement}.`);
+}
+function checkCommand(command, io, replacement) {
+    command
+        .argument("<study>", "Study id or .yaml path.")
+        .description("Check the study file and, with --reachability, its named endpoints. humanish doctor --study <study> checks this machine.")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
+        .addOption(new Option("--reachability <mode>", "Reachability mode.")
+        .choices(["metadata", "public-preview", "sandbox-loopback", "prepared-host"])
+        .default("metadata"))
+        .option("--timeout-ms <ms>", "Target reachability timeout.", String(30_000))
+        .option("--env-file <path>", ENV_FILE_OPTION_DESCRIPTION)
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action((name, options, command) => {
+        if (replacement !== undefined)
+            warnOldCommand(command, io, replacement);
+        return handleStudyCheck(io, name, options, command);
+    });
+    if (replacement !== undefined)
+        command.description(`Deprecated: use ${replacement}.`);
+}
+async function handleStudyList(io, options, command) {
+    const result = await listLabManifests(options.cwd);
+    writeResult(command, io, result, formatStudyListHuman);
+    io.setExitCode(0);
+}
+async function handleStudyShow(io, name, options, command) {
+    const result = await inspectLabManifest(options.cwd, name);
+    writeResult(command, io, result, formatStudyShowHuman);
+    io.setExitCode(result.ok ? 0 : 2);
+}
+async function handleStudyCheck(io, name, options, command) {
+    if (!(await applyEnvFileOption({
+        command,
+        cwd: options.cwd,
+        envFile: options.envFile,
+        io,
+    }))) {
+        return;
+    }
+    const timeoutMs = parsePositiveInteger(options.timeoutMs);
+    if (timeoutMs === null) {
+        const result = {
+            schema: "humanish.study-check.v1",
+            ok: false,
+            cwd: resolve(options.cwd),
+            study: name,
+            reachability: options.reachability,
+            checks: [{ name: "timeout", ok: false, message: "--timeout-ms must be a positive integer." }],
+            targets: [],
+            sandbox: { created: false },
+            spend: { e2bDesktop: false, model: false },
+            warnings: [],
+            error: {
+                code: "HUMANISH_STUDY_PREFLIGHT_INVALID_OPTION",
+                message: "--timeout-ms must be a positive integer.",
+            },
+        };
+        writeResult(command, io, result, formatStudyCheckHuman);
+        io.setExitCode(2);
+        return;
+    }
+    const result = await runLabPreflight({
+        cwd: options.cwd,
+        lab: name,
+        reachability: options.reachability,
+        timeoutMs,
+    });
+    writeResult(command, io, result, formatStudyCheckHuman);
+    io.setExitCode(result.ok ? 0 : 2);
+}
+function formatStudyListHuman(result) {
+    if (result.studies.length === 0) {
+        return ([
+            `No studies found in ${result.cwd}`,
+            "Create one under humanish/studies/*.yaml, or pass a .yaml path.",
+            ...result.warnings.map((warning) => `warning: ${warning}`),
+        ].join("\n") + "\n");
+    }
+    return ([
+        "humanish studies",
+        ...result.studies.map((lab) => `- ${lab.id} ${lab.source} ${lab.origin} ${lab.path}${lab.title ? ` (${lab.title})` : ""}${lab.error ? `\n  error: ${lab.error}` : ""}`),
+        ...result.warnings.map((warning) => `warning: ${warning}`),
+    ].join("\n") + "\n");
+}
+function formatStudyShowHuman(result) {
+    if (!result.ok || !result.config)
+        return humanError(result.error);
+    const config = result.config;
+    return ([
+        "humanish study",
+        `id: ${config.id}`,
+        `subject: ${config.subject.source}`,
+        ...(config.execution?.target ? [`execution: ${config.execution.target}`] : []),
+        `actors: ${config.actors.map((actor) => actor.type).join(", ")}`,
+        ...(config.title ? [`title: ${config.title}`] : []),
+        ...(config.description ? [`description: ${config.description}`] : []),
+        ...(result.path ? [`path: ${result.path}`] : []),
+        ...(result.origin ? [`origin: ${result.origin}`] : []),
+        ...(config.subject.repos?.length ? [`repos: ${config.subject.repos.join(", ")}`] : []),
+        ...(result.personas ?? []).map((persona) => `persona ${persona.id}: ${persona.brief ? `authored context (before runtime additions)\n${persona.brief.text}` : "unresolved; id only"}`),
+        ...result.warnings.map((warning) => `warning: ${warning}`),
+    ].join("\n") + "\n");
+}
+function formatStudyCheckHuman(result) {
+    const checkedTargets = result.targets.filter((target) => target.checked);
+    const reachableTargets = checkedTargets.filter((target) => target.reachable === true);
+    const blockedTargets = result.targets.filter((target) => target.status === "blocked");
+    const stdout = [
+        `humanish study check ${result.ok ? "passed" : "failed"}`,
+        `study: ${result.studyId ?? result.study}`,
+        ...(result.route ? [`route: ${result.route}`] : []),
+        `reachability: ${result.reachability}`,
+        `targets: ${checkedTargets.length ? `${reachableTargets.length}/${checkedTargets.length} reachable` : `${result.targets.length} declared, not checked`}`,
+        ...(blockedTargets.length ? [`blocked-targets: ${blockedTargets.length}`] : []),
+        `spend: ${result.spend.e2bDesktop ? "one e2b desktop, no model calls" : "none"}`,
+        ...(result.analysis ? [formatAutomaticAnalysisBudget(result.analysis)] : []),
+        ...(result.sandbox.created
+            ? [`sandbox: created=yes killed=${result.sandbox.killed === true ? "yes" : "no"}`]
+            : []),
+        ...result.checks.map((check) => `- ${check.ok ? "ok" : "fail"} ${check.name}: ${check.message}`),
+        ...result.warnings.map((warning) => `warning: ${warning}`),
+    ].join("\n") + "\n";
+    return result.error === undefined ? stdout : { stdout, error: result.error };
+}

package/dist/cli/commands/tui.d.ts

@@ -5,7 +5,7 @@ import { type TuiModule } from "../../tui/contract.js";
 import { type CliIo } from "../io.js";
 /**
  * The pieces of the outside world the `tui` command touches. Injectable for the same reason
- * `keyDiscovery` is: the refusals ARE the behavior worth testing, and a test cannot make a real
+ * `keyDiscovery` is: the refusals are the behavior worth testing, and a test cannot make a real
  * TTY, an old Node, or a missing bundle appear.
  */
 export interface TuiRuntime {
@@ -21,12 +21,12 @@ export interface TuiRuntime {
 }
 export declare const defaultTuiRuntime: TuiRuntime;
 /**
- * The stakeholder surface (#455). Every other command is written so an agent can drive it; this one
- * is the opposite — it takes the screen and waits for a person.
+ * The stakeholder surface. Every other command is written so an agent can drive it; this one
+ * is the opposite: it takes the screen and waits for a person.
  *
  * That inversion is why it refuses rather than degrades. An agent that runs `humanish tui` with a
  * piped stdout has asked for something that cannot exist, and the useful answer is a structured
- * error naming the command that WOULD have answered the question. A TUI that quietly rendered
+ * error naming the command that would have answered the question. A TUI that quietly rendered
  * frames into a pipe would poison a transcript with escape codes and look like a hang.
  */
 export declare function registerTuiCommand(parent: Command, io: CliIo, runtime?: TuiRuntime): void;

package/dist/cli/commands/tui.js

@@ -19,7 +19,7 @@ import { readRunDetail } from "../../run/detail.js";
 import { launchRun, readLaunchLogTail } from "../../tui/launch.js";
 import { TUI_MIN_NODE_MAJOR, nodeSupportsTui, TUI_BUNDLE_URL, } from "../../tui/contract.js";
 import { detectAgentSession } from "../../actors/agent-session.js";
-import { applyEnvFileOption, CLI_VERSION, JSON_OPTION_DESCRIPTION, markInvocationEnvelopeWritten, wantsJson, } from "../io.js";
+import { applyEnvFileOption, CLI_VERSION, CWD_OPTION_DESCRIPTION, ENV_FILE_OPTION_DESCRIPTION, JSON_OPTION_DESCRIPTION, markInvocationEnvelopeWritten, wantsJson, } from "../io.js";
 export const defaultTuiRuntime = {
     checkComms: checkCommsConnection,
     promptSecret,
@@ -45,21 +45,21 @@ function refuseTui(command, io, refusal) {
     io.setExitCode(2);
 }
 /**
- * The stakeholder surface (#455). Every other command is written so an agent can drive it; this one
- * is the opposite — it takes the screen and waits for a person.
+ * The stakeholder surface. Every other command is written so an agent can drive it; this one
+ * is the opposite: it takes the screen and waits for a person.
  *
  * That inversion is why it refuses rather than degrades. An agent that runs `humanish tui` with a
  * piped stdout has asked for something that cannot exist, and the useful answer is a structured
- * error naming the command that WOULD have answered the question. A TUI that quietly rendered
+ * error naming the command that would have answered the question. A TUI that quietly rendered
  * frames into a pipe would poison a transcript with escape codes and look like a hang.
  */
 export function registerTuiCommand(parent, io, runtime = defaultTuiRuntime) {
     parent
         .command("tui")
-        .description("Open the interactive terminal surface for browsing labs and runs (humans only).")
-        .summary("Human terminal for labs and runs; refuses detected agent sessions and non-TTY input/output. Agents: humanish lab list --json, humanish lab inspect <lab> --json, humanish runs --json.")
-        .option("--cwd <path>", "Target project directory.", ".")
-        .option("--env-file <path>", "Load a local env file for this terminal session and its runs without printing values.")
+        .description("Browse studies and runs in an interactive terminal UI. It refuses detected agent sessions and non-TTY input or output; agents use humanish study list --json, humanish study show <study> --json and humanish runs --json.")
+        .summary("Browse studies and runs in a terminal UI for people.")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
+        .option("--env-file <path>", ENV_FILE_OPTION_DESCRIPTION)
         .option("--force", "Open it anyway in a session that looks like an agent's.")
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action((options, command) => handleTui(io, runtime, options, command));
@@ -70,7 +70,7 @@ async function handleTui(io, runtime, options, command) {
         refuseTui(command, io, refusal);
         return;
     }
-    // The Ink app ships as a pre-built bundle beside the compiled CLI and is loaded ONLY here, so
+    // The Ink app ships as a pre-built bundle beside the compiled CLI and is loaded only here, so
     // no agent-facing command pays its parse cost.
     const bundle = TUI_BUNDLE_URL;
     const loaded = await runtime.loadTui(bundle);
@@ -80,7 +80,7 @@ async function handleTui(io, runtime, options, command) {
             ok: false,
             error: {
                 code: "HUMANISH_TUI_BUNDLE_MISSING",
-                message: `The terminal surface bundle is missing at ${bundle.pathname}. In a checkout, run \`pnpm build\`; in an install, this package is incomplete — please report it.`,
+                message: `The terminal surface bundle is missing at ${bundle.pathname}. In a checkout, run \`pnpm build\`; an installed package always ships it, so please report this as a bug.`,
             },
         });
         return;
@@ -102,12 +102,12 @@ async function handleTui(io, runtime, options, command) {
 }
 /** The refusal for a session the surface cannot serve, or undefined when it may open. */
 function checkTuiSession(runtime, force) {
-    // An agent runner, even with a real terminal. `codex exec` allocates a PTY for the commands
-    // it runs, so the TTY check below passes and the surface used to open: a study watched an
-    // agent navigate the labs list and start a run it did not mean to start
-    // (humanish/labs/handed-a-human-surface.yaml). A TTY says a terminal exists, not that anyone is
-    // reading it. `--force` is the escape for the person who really is at this keyboard —
-    // capturing frames from inside an agent session is exactly that case.
+    // An agent runner, even with a real terminal. `codex exec` allocates a PTY for the commands it
+    // runs, so the TTY check below passes for an agent too, and an agent in the surface can start a
+    // run it did not mean to start (humanish/studies/handed-a-human-surface.yaml records one). A TTY
+    // says a terminal exists, not that anyone is reading it. `--force` is the escape for the person
+    // who really is at this keyboard, and capturing frames from inside an agent session is exactly
+    // that case.
     const agent = force ? undefined : detectAgentSession(runtime.env);
     if (agent !== undefined) {
         return {
@@ -117,8 +117,8 @@ function checkTuiSession(runtime, force) {
                 code: "HUMANISH_TUI_AGENT_SESSION",
                 message: `humanish tui is a surface for a person, and ${agent.marker} says this session belongs to ${agent.runner}. ` +
                     "It renders frames of escape codes into a transcript, and its keys can start runs. " +
-                    "`humanish runs --json` lists runs, `humanish lab list --json` lists the labs in this project, " +
-                    "and `humanish lab run <lab> --json` starts one. If you are a person at this keyboard, add --force.",
+                    "`humanish runs --json` lists runs, `humanish study list --json` lists the studies in this project, " +
+                    "and `humanish run <study> --json` starts one. If you are a person at this keyboard, add --force.",
             },
         };
     }
@@ -128,7 +128,7 @@ function checkTuiSession(runtime, force) {
             ok: false,
             error: {
                 code: "HUMANISH_TUI_REQUIRES_TTY",
-                message: "humanish tui needs an interactive terminal. For scripted or agent use, `humanish runs --json` lists the same runs and `humanish lab run --json` starts one.",
+                message: "humanish tui needs an interactive terminal. For scripted or agent use, `humanish runs --json` lists the same runs and `humanish run <lab> --json` starts one.",
             },
         };
     }
@@ -210,7 +210,7 @@ function tuiCapabilities(session) {
                 });
                 return session.connectionCheck;
             },
-            labs: async () => (await listLabManifests(cwd)).labs.map((lab) => ({
+            labs: async () => (await listLabManifests(cwd)).studies.map((lab) => ({
                 title: lab.title ?? lab.id,
                 path: lab.path,
             })),
@@ -259,7 +259,7 @@ function tuiCapabilities(session) {
                 ? {
                     schema: TUI_ACTION_SCHEMA,
                     ok: true,
-                    message: `set up humanish here — ${result.changes.filter((change) => change.action !== "skip").length} files written`,
+                    message: `set up humanish here: ${result.changes.filter((change) => change.action !== "skip").length} files written`,
                 }
                 : {
                     schema: TUI_ACTION_SCHEMA,

package/dist/cli/commands/watch.js

@@ -3,63 +3,63 @@ import { renderObserver, serveObserver } from "../../observer/render.js";
 import { WATCH_SAFE_NOT_APPLICABLE_MESSAGE } from "../../observer/exposure.js";
 import { runDryRun } from "../../run/dry-run.js";
 import { runLabCommand } from "./lab-run.js";
-import { applyEnvFileOption, collectRepeated, formatRunHuman, JSON_OPTION_DESCRIPTION, parseObserverPort, parsePositiveInteger, wantsJson, writeResult, } from "../io.js";
+import { addRunOptions, studyOnlyFlags } from "./run-command.js";
+import { deprecationMessage, oldStudyOption, studyOptionValue, warnAndQueue, } from "../deprecations.js";
+import { applyEnvFileOption, collectRepeated, formatRunHuman, parseObserverPort, parsePositiveInteger, wantsJson, writeResult, } from "../io.js";
 import { followObserver, formatObserverHuman, watchExposeRequested } from "../observer-follow.js";
 export function registerWatchCommand(parent, io) {
-    parent
+    // A run's flags come from addRunOptions, the helper `run` uses, so the two cannot drift.
+    addRunOptions(parent
         .command("watch")
-        .argument("[lab]", "Optional lab id or .yaml path to run and observe.")
-        .description("Run synthetic participants, open the observer, and keep the shell attached.")
-        .summary("Run participants, open the observer, stay attached.")
-        .option("--lab <id-or-path>", "Explicit lab id or .yaml path.")
-        .option("--run <id>", "Watch an existing run id or latest pointer.")
-        .option("--dry-run", "Lab only: render contract evidence without live provider spend.")
-        .option("--sims <count>", "Start a fresh synthetic run with this many participants before rendering. Defaults to 4 when --run is omitted.")
-        .option("--count <count>", "Lab only: override the headed desktop participant count.")
-        .option("--scorer <path>", "Terminal/computer-use/shared-world labs only: repo-relative adopter scorer module (.mjs). Overrides review.scorer.ref. Executable code: review it as code.")
-        .option("--run-id <id>", "Explicit run id for deterministic fixture tests; refused when that run already exists.")
-        .option("--cwd <path>", "Target project directory.", ".")
-        .option("--env-file <path>", "Load a local env file for this watch without persisting values.")
-        .option("--open", "Open the observer in the default browser.")
-        .option("--no-open", "Render without opening a browser.")
-        .addOption(new Option("--follow", "Deprecated; human output follows by default.").hideHelp())
-        .option("--detach", "Render/open once and exit without attached watch server.")
-        .option("--port <port>", "Local observer server port when following.", "0")
-        .option("--expose", "CUA lab only: expose the live run through an authenticated edge so you can watch from a phone. Requires edge auth.")
+        .argument("[study]", "Study id or .yaml path to run and observe.")
+        .description("Run a study, open its Observer and keep the shell attached.")
+        .summary("Run a study and follow it in the Observer.")
+        .option("--study <id-or-path>", "Study id or .yaml path, in place of the argument.")
+        .addOption(oldStudyOption("id-or-path"))
+        // Removed in 0.109.0: watch --run stays one minor, hidden; observe --run shows a saved run.
+        .addOption(new Option("--run <id>", "Deprecated: use humanish observe --run <id>.").hideHelp()))
+        .option("--expose", "Computer-use studies only: share the live run through an authenticated tunnel, to watch from a phone. Requires --oauth or --public-url.")
         .addOption(new Option("--tunnel <provider>", "Spawn the external tunnel binary against the loopback port.").choices(["ngrok"]))
         .option("--tunnel-domain <domain>", "Reserved domain passed to ngrok as --url (e.g. observer.example.com). Requires --tunnel.")
         .addOption(new Option("--oauth <provider>", "Turn on ngrok edge OAuth. Requires --tunnel.").choices([
         "google",
     ]))
-        .option("--allow-email <addr>", "Edge OAuth allow rule: permit this email. Repeatable. Requires --oauth.", collectRepeated, [])
-        .option("--allow-domain <domain>", "Edge OAuth allow rule: permit this domain. Repeatable. Requires --oauth.", collectRepeated, [])
+        .option("--allow-email <addr>", "Edge OAuth allow rule: permit this email. Repeatable. Requires --oauth.", collectRepeated)
+        .option("--allow-domain <domain>", "Edge OAuth allow rule: permit this domain. Repeatable. Requires --oauth.", collectRepeated)
         .option("--public-url <origin>", "Bring-your-own authed edge (Cloudflare Access/Tailscale/manual). Binds loopback and trusts your edge. Requires --expose.")
-        .option("--safe", "Not applicable to watch: a live run is never share_ready, so --safe (a `serve` library filter) is rejected here. Restrict viewers with edge auth (--allow-email/--allow-domain).")
-        .option("--json", JSON_OPTION_DESCRIPTION)
+        // Hidden: watch rejects --safe with a pointer to the library filter and to edge auth, which
+        // a bare "unknown option" would lose.
+        .addOption(new Option("--safe").hideHelp())
         .addHelpText("after", [
         "",
+        "Without a study or --run, watch starts a synthetic run of 4 participants; --count changes it.",
+        "",
         "Happy path:",
         "  humanish watch",
         "  humanish watch first-run",
-        "  humanish watch --lab .humanish/labs/local.yaml",
         "",
-        "Watch a live CUA run from your phone (tunnel-edge auth):",
-        "  humanish watch my-cua-lab --expose --tunnel ngrok --oauth google --allow-email you@example.com",
+        "Watch a live computer-use run from your phone through an authenticated tunnel:",
+        "  humanish watch my-browser-study --expose --tunnel ngrok --oauth google --allow-email you@example.com",
         "",
         "Agent/CI path:",
         "  humanish watch --json --no-open",
         "",
-        "Existing evidence:",
-        "  humanish watch --run latest --detach",
+        "Saved runs:",
+        "  humanish observe --run latest",
     ].join("\n"))
-        .action((labArg, options, command) => handleWatch(io, labArg, options, command));
+        .action((named, options, command) => handleWatch(io, named, options, command));
 }
-async function handleWatch(io, labArg, options, command) {
-    const lab = options.lab ?? labArg;
-    if (options.lab !== undefined && labArg !== undefined) {
+async function handleWatch(io, named, parsed, command) {
+    const options = parsed;
+    if (options.run !== undefined) {
+        warnAndQueue(command, io, deprecationMessage("humanish watch --run", "humanish observe --run <id>"));
+    }
+    const option = studyOptionValue(command, io, options);
+    const study = option ?? named;
+    if (option !== undefined && named !== undefined) {
         refuseWatch(command, io, options.cwd, {
             code: "HUMANISH_WATCH_OPTION_CONFLICT",
-            message: "Use either positional lab or --lab, not both.",
+            message: "Use either a study argument or --study, not both.",
         });
         return;
     }
@@ -73,21 +73,29 @@ async function handleWatch(io, labArg, options, command) {
     }))) {
         return;
     }
-    if (lab) {
-        await watchLab(io, command, lab, options);
+    if (study) {
+        await watchStudy(io, command, study, options);
+        return;
+    }
+    const studyOnly = studyOnlyFlags(options);
+    if (studyOnly.length > 0) {
+        refuseWatch(command, io, options.cwd, {
+            code: "HUMANISH_WATCH_OPTION_CONFLICT",
+            message: `${studyOnly.join(", ")} ${studyOnly.length === 1 ? "needs" : "need"} a study: humanish watch <study>.`,
+        });
         return;
     }
-    // Exposure is only meaningful for a live CUA lab run (it serves the live desktop). The
+    // Exposure is only meaningful for a live computer-use study run (it serves the live desktop). The
     // non-lab watch path (existing evidence, or a fresh synthetic run) has no live desktop to
-    // stream, so exposure flags there are refused rather than silently ignored — use `serve`.
+    // stream, so exposure flags there are refused rather than silently ignored; use `observe --all`.
     if (watchExposeRequested(options)) {
         refuseWatch(command, io, options.cwd, {
             code: "HUMANISH_WATCH_OPTION_CONFLICT",
-            message: "--expose/--tunnel/--oauth apply only to a live CUA lab run; to expose finished evidence use `humanish serve --expose`.",
+            message: "--expose/--tunnel/--oauth apply only to a live computer-use run; to expose finished evidence use `humanish observe --all --expose`.",
         });
         return;
     }
-    // --safe is a `serve` library filter; watch shows one run and has nothing it could filter.
+    // --safe is an `observe --all` library filter; watch shows one run and has nothing to filter.
     if (options.safe === true) {
         refuseWatch(command, io, options.cwd, {
             code: "HUMANISH_WATCH_SAFE_NOT_APPLICABLE",
@@ -106,7 +114,7 @@ async function handleWatch(io, labArg, options, command) {
         : options.open === true
             ? true
             : !wantsMachine && process.stdout.isTTY === true;
-    const wantsFollow = !wantsMachine && options.detach !== true && options.follow !== false;
+    const wantsFollow = !wantsMachine && options.detach !== true;
     const staticOpen = wantsFollow ? false : shouldOpen;
     const rendered = await renderWatchEvidence(io, command, options, target.requestedParticipantCount, staticOpen);
     if (rendered === undefined)
@@ -128,57 +136,36 @@ function refuseWatch(command, io, cwd, refusal) {
     writeResult(command, io, result, formatRunHuman);
     io.setExitCode(2);
 }
-/** A lab argument starts that lab under watch; `--run` would name other evidence. */
-async function watchLab(io, command, lab, options) {
+/** A study argument starts that study under watch; `--run` would name other evidence. */
+async function watchStudy(io, command, study, options) {
     if (options.run !== undefined) {
         refuseWatch(command, io, options.cwd, {
             code: "HUMANISH_WATCH_OPTION_CONFLICT",
-            message: "Use either a lab to start evidence or --run to watch existing evidence, not both.",
+            message: "Use either a study to start evidence or --run to watch existing evidence, not both.",
         });
         return;
     }
-    await runLabCommand({
-        command,
-        io,
-        lab,
-        mode: "watch",
-        options: {
-            cwd: options.cwd,
-            ...(options.count === undefined ? {} : { count: options.count }),
-            ...(options.detach === undefined ? {} : { detach: options.detach }),
-            ...(options.dryRun === undefined ? {} : { dryRun: options.dryRun }),
-            ...(options.open === undefined ? {} : { open: options.open }),
-            port: options.port,
-            ...(options.runId === undefined ? {} : { runId: options.runId }),
-            ...(options.scorer === undefined ? {} : { scorer: options.scorer }),
-            ...(options.sims === undefined ? {} : { sims: options.sims }),
-            ...(options.expose === undefined ? {} : { expose: options.expose }),
-            ...(options.tunnel === undefined ? {} : { tunnel: options.tunnel }),
-            ...(options.tunnelDomain === undefined ? {} : { tunnelDomain: options.tunnelDomain }),
-            ...(options.oauth === undefined ? {} : { oauth: options.oauth }),
-            allowEmail: options.allowEmail,
-            allowDomain: options.allowDomain,
-            ...(options.publicUrl === undefined ? {} : { publicUrl: options.publicUrl }),
-            ...(options.safe === undefined ? {} : { safe: options.safe }),
-            ...(options.json === undefined ? {} : { json: options.json }),
-        },
-    });
+    // Forwarded wholesale, as `run` forwards its options, so a run flag reaches the lab either way.
+    await runLabCommand({ command, io, lab: study, mode: "watch", options });
 }
-/** Without a lab, watch shows existing evidence (`--run`) or a fresh synthetic run (`--sims`). */
+/** Without a study, watch shows existing evidence (`--run`) or a fresh synthetic run (`--count`). */
 function resolveWatchTarget(options, command) {
     const runOptionSource = typeof command.getOptionValueSource === "function"
         ? command.getOptionValueSource("run")
         : undefined;
     const runWasOmitted = runOptionSource === undefined || runOptionSource === "default";
-    const participantCount = options.sims === undefined ? undefined : parsePositiveInteger(options.sims);
+    const participantCount = options.count === undefined ? undefined : parsePositiveInteger(options.count);
     const port = parseObserverPort(options.port);
-    if (options.sims !== undefined && participantCount === null) {
-        return { code: "HUMANISH_INVALID_SIM_COUNT", message: "--sims must be a positive integer." };
+    if (participantCount === null) {
+        return {
+            code: "HUMANISH_INVALID_PARTICIPANT_COUNT",
+            message: "--count must be a positive integer.",
+        };
     }
-    if (!runWasOmitted && options.sims !== undefined) {
+    if (!runWasOmitted && participantCount !== undefined) {
         return {
             code: "HUMANISH_WATCH_OPTION_CONFLICT",
-            message: "Use either --run to watch existing evidence or --sims to start a fresh run, not both.",
+            message: "Use either --run to watch existing evidence or --count to start a fresh run, not both.",
         };
     }
     if (!runWasOmitted && options.runId !== undefined) {
@@ -203,7 +190,7 @@ async function renderWatchEvidence(io, command, options, requestedParticipantCou
         const runResult = await runDryRun({
             cwd: options.cwd,
             dryRun: true,
-            simCount: requestedParticipantCount,
+            participantCount: requestedParticipantCount,
             ...(options.runId === undefined ? {} : { runId: options.runId }),
             observer: { open: staticOpen },
         });

package/dist/cli/deprecations.d.ts

@@ -0,0 +1,18 @@
+import { Option, type Command } from "commander";
+import type { CliIo } from "./io.js";
+/** `<old> is deprecated and is removed in the next minor. Use <replacement>.` */
+export declare function deprecationMessage(old: string, replacement: string): string;
+/** Print `warning: <message>` on stderr, and queue the message for the command's JSON result. */
+export declare function warnAndQueue(command: Command, io: CliIo, message: string): void;
+/** `output` with the command's queued warnings at the front of its `warnings`. */
+export declare function withQueuedWarnings<T>(command: Command, output: T): T;
+/**
+ * The 0.107 spelling of `--study`, hidden for one minor. Commander refuses it together with
+ * `--study`. Read the value with studyOptionValue.
+ */
+export declare function oldStudyOption(valueName: string): Option;
+/** The `--study` value, or the `--lab` value with its deprecation warning. */
+export declare function studyOptionValue(command: Command, io: CliIo, options: {
+    study?: string | undefined;
+    lab?: string | undefined;
+}): string | undefined;

package/dist/cli/deprecations.js

@@ -0,0 +1,48 @@
+// A warning a command prints, such as a deprecated spelling or a study file 0.109 stops reading,
+// goes to stderr when it happens and into the `warnings` array of the command's JSON result, so a
+// caller that reads only stdout sees it too. writeResult adds the queued warnings.
+import { Option } from "commander";
+const queued = new WeakMap();
+/** `<old> is deprecated and is removed in the next minor. Use <replacement>.` */
+export function deprecationMessage(old, replacement) {
+    return `${old} is deprecated and is removed in the next minor. Use ${replacement}.`;
+}
+/** Print `warning: <message>` on stderr, and queue the message for the command's JSON result. */
+export function warnAndQueue(command, io, message) {
+    io.writeErr(`warning: ${message}\n`);
+    queued.set(command, [...(queued.get(command) ?? []), message]);
+}
+/** `output` with the command's queued warnings at the front of its `warnings`. */
+export function withQueuedWarnings(command, output) {
+    const messages = queued.get(command);
+    if (messages === undefined || output === null || typeof output !== "object")
+        return output;
+    if (Array.isArray(output))
+        return output;
+    const existing = output.warnings;
+    if (existing !== undefined && !Array.isArray(existing))
+        return output;
+    return { ...output, warnings: [...messages, ...(existing ?? [])] };
+}
+/**
+ * The 0.107 spelling of `--study`, hidden for one minor. Commander refuses it together with
+ * `--study`. Read the value with studyOptionValue.
+ */
+export function oldStudyOption(valueName) {
+    return new Option(`--lab <${valueName}>`).hideHelp().conflicts("study");
+}
+/** The `--study` value, or the `--lab` value with its deprecation warning. */
+export function studyOptionValue(command, io, options) {
+    if (options.lab === undefined)
+        return options.study;
+    const path = commandPath(command);
+    warnAndQueue(command, io, deprecationMessage(`humanish ${path} --lab`, `humanish ${path} --study <study>`));
+    return options.lab;
+}
+/** The command's words after `humanish`, such as `comms check`. */
+function commandPath(command) {
+    const words = [];
+    for (let at = command; at?.parent; at = at.parent)
+        words.unshift(at.name());
+    return words.join(" ");
+}