humanish 0.107.0 → 0.109.0

package/dist/cli/commands/watch.js

@@ -1,68 +1,58 @@
 import { Command, Option } from "commander";
-import { renderObserver, serveObserver } from "../../observer/render.js";
+import { 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 { countOption } from "../renamed-options.js";
-import { applyEnvFileOption, collectRepeated, formatRunHuman, JSON_OPTION_DESCRIPTION, parseObserverPort, parsePositiveInteger, wantsJson, writeResult, } from "../io.js";
+import { runStudyCommand } from "./study-run.js";
+import { addRunOptions, studyOnlyFlags } from "./run-command.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("--count <count>", "With a lab, override a preview or computer-use lab's participant count. Without one, start a fresh synthetic run with this many participants; 4 when --run is omitted.")
-        // The older spelling of --count, hidden and noted on stderr (renamed-options.ts).
-        .addOption(new Option("--sims <count>").hideHelp())
-        .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."))
+        .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, parsed, command) {
-    const options = { ...parsed, count: countOption(io, parsed) };
-    const lab = options.lab ?? labArg;
-    if (options.lab !== undefined && labArg !== undefined) {
+async function handleWatch(io, named, parsed, command) {
+    const options = parsed;
+    const option = options.study;
+    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;
     }
@@ -71,26 +61,34 @@ async function handleWatch(io, labArg, parsed, command) {
         cwd: options.cwd,
         envFile: options.envFile,
         io,
-        // runLabCommand discovers keys for a live lab; a preview or a saved run needs none.
+        // runStudyCommand discovers keys for a live study; a preview run needs none.
         discoverKeys: false,
     }))) {
         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
-    // 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`.
+    // Exposure is only meaningful for a live computer-use study run (it serves the live desktop). A
+    // watch without a study starts a fresh synthetic run with no live desktop to 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",
@@ -98,7 +96,7 @@ async function handleWatch(io, labArg, parsed, command) {
         });
         return;
     }
-    const target = resolveWatchTarget(options, command);
+    const target = resolveWatchTarget(options);
     if ("code" in target) {
         refuseWatch(command, io, options.cwd, target);
         return;
@@ -109,7 +107,7 @@ async function handleWatch(io, labArg, parsed, 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)
@@ -131,62 +129,19 @@ 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) {
-    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.",
-        });
-        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.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 }),
-        },
-    });
+/** A study argument starts that study under watch. */
+async function watchStudy(io, command, study, options) {
+    // Forwarded wholesale, as `run` forwards its options, so a run flag reaches the run either way.
+    await runStudyCommand({ command, io, study, mode: "watch", options });
 }
-/** Without a lab, 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";
+/** Without a study, watch starts a fresh synthetic run of `--count` participants, 4 by default. */
+function resolveWatchTarget(options) {
     const participantCount = options.count === undefined ? undefined : parsePositiveInteger(options.count);
     const port = parseObserverPort(options.port);
     if (participantCount === null) {
-        return { code: "HUMANISH_INVALID_SIM_COUNT", message: "--count must be a positive integer." };
-    }
-    if (!runWasOmitted && participantCount !== undefined) {
-        return {
-            code: "HUMANISH_WATCH_OPTION_CONFLICT",
-            message: "Use either --run to watch existing evidence or --count to start a fresh run, not both.",
-        };
-    }
-    if (!runWasOmitted && options.runId !== undefined) {
         return {
-            code: "HUMANISH_WATCH_OPTION_CONFLICT",
-            message: "--run-id only applies to fresh watch runs; remove --run or remove --run-id.",
+            code: "HUMANISH_INVALID_PARTICIPANT_COUNT",
+            message: "--count must be a positive integer.",
         };
     }
     if (port === null) {
@@ -195,30 +150,25 @@ function resolveWatchTarget(options, command) {
             message: "--port must be an integer between 0 and 65535.",
         };
     }
-    return { requestedParticipantCount: participantCount ?? (runWasOmitted ? 4 : undefined), port };
+    return { requestedParticipantCount: participantCount ?? 4, port };
 }
-/** Render the evidence to show; undefined when a fresh run failed and its result was written. */
+/** Render the fresh run; undefined when it failed and its result was written. */
 async function renderWatchEvidence(io, command, options, requestedParticipantCount, staticOpen) {
-    if (requestedParticipantCount !== undefined && requestedParticipantCount !== null) {
-        // A fresh run renders through its finished run, so the page shown is the run just
-        // written, never a directory swapped in under its id.
-        const runResult = await runDryRun({
-            cwd: options.cwd,
-            dryRun: true,
-            simCount: requestedParticipantCount,
-            ...(options.runId === undefined ? {} : { runId: options.runId }),
-            observer: { open: staticOpen },
-        });
-        if (!runResult.ok || runResult.observer === undefined) {
-            writeResult(command, io, runResult, formatRunHuman);
-            io.setExitCode(2);
-            return undefined;
-        }
-        return runResult.observer;
-    }
-    return renderObserver(options.cwd, options.run ?? "latest", {
-        open: staticOpen,
+    // A fresh run renders through its finished run, so the page shown is the run just written,
+    // never a directory swapped in under its id.
+    const runResult = await runDryRun({
+        cwd: options.cwd,
+        dryRun: true,
+        participantCount: requestedParticipantCount,
+        ...(options.runId === undefined ? {} : { runId: options.runId }),
+        observer: { open: staticOpen },
     });
+    if (!runResult.ok || runResult.observer === undefined) {
+        writeResult(command, io, runResult, formatRunHuman);
+        io.setExitCode(2);
+        return undefined;
+    }
+    return runResult.observer;
 }
 /** Write the result, then keep a live server attached when following. */
 async function reportWatch(io, command, rendered, serve) {

package/dist/cli/deprecations.d.ts

@@ -0,0 +1,6 @@
+import type { Command } from "commander";
+import type { CliIo } from "./io.js";
+/** 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;

package/dist/cli/deprecations.js

@@ -0,0 +1,18 @@
+const queued = new WeakMap();
+/** 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 ?? [])] };
+}

package/dist/cli/doctor.d.ts

@@ -1,7 +1,12 @@
 import { type KeyResolutionDeps } from "../keys/key-resolution.js";
 import { type DetectLocalAgentsOptions } from "../actors/local-agent/cli.js";
-import { type LabSetupCheckArgs } from "../lab/doctor.js";
+import { type StudySetupCheckArgs } from "../study/doctor.js";
 declare const DOCTOR_SCHEMA = "humanish.doctor-result.v1";
+/**
+ * A row's verdict, as the human output prints it. A "note" is advisory: it never fails the run, so
+ * its `ok` is true. "not_checked" goes with `checked: false`.
+ */
+type DoctorStatus = "ok" | "missing" | "not_checked" | "note";
 export interface DoctorResult {
     schema: typeof DOCTOR_SCHEMA;
     ok: boolean;
@@ -9,14 +14,15 @@ export interface DoctorResult {
     checks: Array<{
         name: string;
         ok: boolean;
+        status: DoctorStatus;
         message: string;
         /**
-         * ADDITIVE + OPTIONAL. `false` means the check never ran — the directory could not be read, so
+         * Additive + optional. `false` means the check never ran: the directory could not be read, so
          * there is nothing to report about it either way. Absent means it ran and `ok` is its verdict.
          *
-         * It exists because a failed check and an unrun one used to render identically, and the unrun
-         * rows carried the SUCCESS text: a participant read `missing package.json: package.json is
-         * present and safe to read` off a real screen (labs/tui-self-study.yaml).
+         * It exists so a failed check and an unrun one render differently. Without it an unrun row
+         * shows the success text, such as `missing package.json: package.json is present and safe to
+         * read` (labs/tui-self-study.yaml).
          */
         checked?: boolean;
     }>;
@@ -25,18 +31,22 @@ export interface DoctorResult {
  * Version 2.3.1 stopped holding a launched background command's event stream open. Version 2.3.2
  * also requires an e2b release whose background command handle supports sendStdin and closeStdin,
  * which the optional speech transport needs. On older releases the CLI could stay alive minutes
- * past a written result (#581, measured 2026-09-04 on 2.2.3: twelve minutes).
+ * past a written result (measured 2026-09-04 on 2.2.3: twelve minutes).
  */
 export declare const DESKTOP_SDK_FLOOR = "2.3.2";
 /** The advisory `doctor` attaches to an installed desktop SDK older than the floor, else undefined. */
 export declare function desktopSdkAdvisory(version: string | undefined): string | undefined;
+/** A row as a check writes it. Doctor derives `status`; an advisory row sets "note" itself. */
+export type DoctorCheckDraft = Omit<DoctorResult["checks"][number], "status"> & {
+    status?: "note";
+};
 export declare function doctor(cwdInput: string, options?: {
-    lab?: string;
+    study?: string;
     env?: NodeJS.ProcessEnv;
     localAgents?: DetectLocalAgentsOptions;
     /** Where the key probe looks for vendor stores; tests point it at a temp home. */
     keyDeps?: KeyResolutionDeps;
     /** The hosted Codex participant's operator handshake; tests replace it. */
-    codexParticipantReadiness?: LabSetupCheckArgs["codexParticipantReadiness"];
+    codexParticipantReadiness?: StudySetupCheckArgs["codexParticipantReadiness"];
 }): Promise<DoctorResult>;
 export {};