humanish 0.106.1 → 0.107.0

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

@@ -1,9 +1,10 @@
 import { automaticAnalysisBudget, formatAutomaticAnalysisBudget, } from "../../analysis/automatic-config.js";
 import { resolve } from "node:path";
 import { Command } from "commander";
-import { deriveStudyFacts } from "../telemetry.js";
+import { deriveRunFacts } from "../telemetry.js";
 import { resolveLabManifest } from "../../lab/discover.js";
-import { resolveLabDryRun } from "../../lab/plan.js";
+import { planLab, resolveLabDryRun } from "../../lab/plan.js";
+import { keyNamesOf } from "../../lab/requirements.js";
 import { routeOf } from "../../lab/plan.js";
 import { computerUseRouteRun } from "./lab-route-computer-use.js";
 import { runRoute } from "./lab-route-run.js";
@@ -12,8 +13,9 @@ import { sharedWorldRouteRun } from "./lab-route-shared-world.js";
 import { previewRouteRun } from "./lab-route-preview.js";
 import { terminalRouteRun } from "./lab-route-terminal.js";
 import { maybeLoadAdapterScorer } from "./lab-scorer.js";
-import { discoverCliKeys, formatRunHuman, noteStudyFacts, writeResult, } from "../io.js";
+import { discoverCliKeys, formatRunHuman, noteRunFacts, writeResult, } from "../io.js";
 import { watchExposeRequested } from "../observer-follow.js";
+import { beginRunSignalPhase } from "./run-signals.js";
 import { WATCH_SAFE_NOT_APPLICABLE_MESSAGE } from "../../observer/exposure.js";
 export async function runLabCommand(args) {
     const resolved = await resolveLabManifest(args.options.cwd, args.lab);
@@ -35,7 +37,7 @@ export async function runLabCommand(args) {
     const lab = { id: config.id, path: resolved.path, origin: resolved.origin };
     // Named here, once, for every route: a preview or terminal result carries no labId, so the
     // starter lab `first-run` went unnamed in telemetry while the computer-use ones were named.
-    noteStudyFacts(args.command, deriveStudyFacts({ labId: config.id }));
+    noteRunFacts(args.command, deriveRunFacts({ labId: config.id }));
     const route = routeOf(config);
     if (route !== "computer-use" && labRerunFlagsRequested(args.options)) {
         writeUnsupportedRerunFlagsResult(args, route);
@@ -76,52 +78,81 @@ export async function runLabCommand(args) {
         return;
     }
     // Only a live run reads provider keys, so a dry run looks none up: no `gh auth token`, no e2b
-    // login, overlay or key store. This comes after the option refusals above, which read no key,
-    // and before the route's CLI setup and prepareLab, which do.
+    // login, overlay or key store. A live run fills every key it finds and prints a line only for
+    // the keys its plan reads. This comes after the option refusals above, which read no key, and
+    // before the route's CLI setup and prepareLab, which do.
     if (resolveLabDryRun(config, args.options.dryRun, true) === false) {
-        await discoverCliKeys({ io: args.io, cwd: args.options.cwd });
+        const announced = announcedKeyNames(config, args.options);
+        await discoverCliKeys({
+            io: args.io,
+            cwd: args.options.cwd,
+            ...(announced === undefined ? {} : { announced }),
+        });
     }
     // The route's CLI setup refuses bad options, runLab's plan refuses bad labs, and the route's local
     // checks (keys, runtime auth, subject env, the local agent, caps) refuse this machine, all before
     // the scorer loads, so none imports the scorer's host code. The scripted route's checks and the
     // run-id claim still come after it; the scripted route takes no scorer.
-    const run = routeRunFor(route, { ...args, config, labProvenance: lab });
-    if (run === undefined)
+    const routeRun = routeRunFor(route, { ...args, config });
+    if (routeRun === undefined)
         return;
-    // #316: 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 () => {
-        const scorerLoad = await maybeLoadAdapterScorer({
-            cwd: args.options.cwd,
-            config,
-            route,
-            flag: args.options.scorer,
-        });
-        if (!scorerLoad.ok) {
-            const result = {
-                schema: "humanish.run-result.v1",
-                ok: false,
-                cwd: resolve(args.options.cwd),
-                warnings: [],
-                error: scorerLoad.error,
-            };
-            writeResult(args.command, args.io, result, formatRunHuman);
-            args.io.setExitCode(2);
-            return undefined;
-        }
-        const scorer = scorerLoad.scorer;
-        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`);
-        }
-        const analysisBudget = automaticAnalysisBudget(config.review?.analysis, route);
-        if (analysisBudget && resolveLabDryRun(config, args.options.dryRun, true) === false) {
-            args.io.writeErr(`${formatAutomaticAnalysisBudget(analysisBudget)}\n`);
-        }
-        return scorer === undefined ? {} : { scorer };
-    });
+    // Every route's runLab options carry the lab's provenance, from here only.
+    const run = { ...routeRun, options: { ...routeRun.options, lab } };
+    // 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
+        // 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 () => {
+            const scorerLoad = await maybeLoadAdapterScorer({
+                cwd: args.options.cwd,
+                config,
+                route,
+                flag: args.options.scorer,
+            });
+            if (!scorerLoad.ok) {
+                const result = {
+                    schema: "humanish.run-result.v1",
+                    ok: false,
+                    cwd: resolve(args.options.cwd),
+                    warnings: [],
+                    error: scorerLoad.error,
+                };
+                writeResult(args.command, args.io, result, formatRunHuman);
+                args.io.setExitCode(2);
+                return undefined;
+            }
+            const scorer = scorerLoad.scorer;
+            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`);
+            }
+            const analysisBudget = automaticAnalysisBudget(config.review?.analysis, route);
+            if (analysisBudget && resolveLabDryRun(config, args.options.dryRun, true) === false) {
+                args.io.writeErr(`${formatAutomaticAnalysisBudget(analysisBudget)}\n`);
+            }
+            return scorer === undefined ? {} : { scorer };
+        }, 
+        // The run is over before presentation, which may own shutdown itself (watch's Observer).
+        // A shutdown already begun keeps its handlers and finishes through its cleanups.
+        signals.release);
+    }
+    finally {
+        signals.release();
+    }
+}
+/**
+ * The filled keys a live run prints a line for: the ones its plan reads. Count and rerun options
+ * change who runs, not which keys. Undefined, so every fill is printed, when a scorer is declared,
+ * since its host code may read any key, and when the lab does not plan.
+ */
+function announcedKeyNames(config, options) {
+    if (options.scorer !== undefined || config.review?.scorer !== undefined)
+        return undefined;
+    const planned = planLab(config, { cwd: options.cwd, dryRun: false });
+    return planned.ok ? keyNamesOf(planned.planned.plan) : undefined;
 }
 /** The route's CLI setup. Undefined when the setup has already written its own result. */
 function routeRunFor(route, args) {
@@ -142,7 +173,7 @@ function routeRunFor(route, args) {
     }
 }
 function labRerunFlagsRequested(options) {
-    return options.rerunFailedFrom !== undefined || options.lanes !== undefined;
+    return options.rerunFailedFrom !== undefined || options.participants !== undefined;
 }
 function writeUnsupportedRerunFlagsResult(args, route) {
     const result = {
@@ -152,7 +183,7 @@ function writeUnsupportedRerunFlagsResult(args, route) {
         warnings: [],
         error: {
             code: "HUMANISH_UNSUPPORTED_RERUN_FLAGS",
-            message: `--rerun-failed-from/--lanes apply only to computer-use fan-out labs; this lab resolved to the ${route} route.`,
+            message: `--rerun-failed-from/--participants apply only to computer-use fan-out labs; this lab resolved to the ${route} route.`,
         },
     };
     writeResult(args.command, args.io, result, formatRunHuman);

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

@@ -1,4 +1,3 @@
-import type { RunLabProvenance } from "../../run/status.js";
 import { type AdapterScorerModule } from "../../lab/adapter-scorer-loader.js";
 import type { LabRoute } from "../../lab/plan.js";
 import type { RunScorerProvenance } from "../../run/bundle.js";
@@ -18,7 +17,6 @@ export interface LoadedAdapterScorer {
 export declare function maybeLoadAdapterScorer(args: {
     cwd: string;
     config: LabConfig;
-    labProvenance?: RunLabProvenance;
     route: LabRoute;
     flag: string | undefined;
 }): Promise<{

package/dist/cli/commands/lab.js

@@ -4,6 +4,7 @@ import { Command, Option } from "commander";
 import { inspectLabManifest, listLabManifests } from "../../lab/discover.js";
 import { runLabPreflight, } from "../../lab/preflight.js";
 import { runLabCommand } from "./lab-run.js";
+import { countOption, participantsOption } from "../renamed-options.js";
 import { applyEnvFileOption, JSON_OPTION_DESCRIPTION, parsePositiveInteger, writeResult, } from "../io.js";
 export function registerLabCommands(parent, io) {
     const lab = parent
@@ -45,10 +46,13 @@ export function registerLabCommands(parent, io) {
         .option("--no-open", "Render without opening a browser.")
         .option("--detach", "Render/open once and exit without attached watch server.")
         .option("--port <port>", "Local observer server port when following.", "0")
-        .option("--sims <count>", "Override the synthetic or headed desktop participant count.")
-        .option("--count <count>", "Computer-use only: override the headed desktop participant count.")
+        .option("--count <count>", "Override the participant count of a preview or computer-use lab.")
+        // The older spelling of --count, hidden and noted on stderr (renamed-options.ts).
+        .addOption(new Option("--sims <count>").hideHelp())
         .option("--rerun-failed-from <run>", "CUA fan-out only: create a new run for failed participants from a prior run.")
-        .option("--lanes <participant-ids>", "CUA rerun only: comma-separated participant ids to rerun from the source run.")
+        .option("--participants <ids>", "CUA rerun only: comma-separated participant ids from the source run. Ids are the lab's declared actors[0].lanes[].id, or lane-01, lane-02, … by position.")
+        // The older spelling of --participants, hidden and noted on stderr (renamed-options.ts).
+        .addOption(new Option("--lanes <participant-ids>").hideHelp())
         .option("--run-id <id>", "Explicit lab run id; refused when that run already exists.")
         .option("--cwd <path>", "Target project directory.", ".")
         .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.")
@@ -57,7 +61,7 @@ export function registerLabCommands(parent, io) {
         "",
         "Examples:",
         "  humanish lab run first-run",
-        "  humanish lab run fanout-demo --rerun-failed-from latest --lanes lane-02,lane-04",
+        "  humanish lab run fanout-demo --rerun-failed-from latest --participants lane-02,lane-04",
         "  humanish lab run my-terminal-lab --scorer scorers/product.mjs",
         "  humanish lab run .humanish/labs/private-dogfood.yaml --env-file .humanish/local/provider.env",
         "",
@@ -118,6 +122,8 @@ async function handleLabPreflight(io, labName, options, command) {
     io.setExitCode(result.ok ? 0 : 2);
 }
 async function handleLabRun(io, labName, options, command) {
+    const count = countOption(io, options);
+    const participants = participantsOption(io, options);
     if (!(await applyEnvFileOption({
         command,
         cwd: options.cwd,
@@ -133,7 +139,7 @@ async function handleLabRun(io, labName, options, command) {
         io,
         lab: labName,
         mode: "run",
-        options,
+        options: { ...options, count, participants },
     });
 }
 function formatLabListHuman(result) {
@@ -177,7 +183,7 @@ function formatLabPreflightHuman(result) {
     return ([
         `humanish lab preflight ${result.ok ? "passed" : "failed"}`,
         `lab: ${result.labId ?? result.lab}`,
-        ...(result.backend ? [`backend: ${result.backend}`] : []),
+        ...(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}`] : []),

package/dist/cli/commands/observe.js

@@ -292,6 +292,7 @@ async function reportServe(io, command, options, server, plan, edge) {
             : {}),
         runsListed: server.runsListed,
         ...(server.shareReadyCount !== undefined ? { shareReadyCount: server.shareReadyCount } : {}),
+        ...(server.hiddenRuns !== undefined ? { hiddenRuns: server.hiddenRuns } : {}),
         ...(server.entryRunId ? { entryRunId: server.entryRunId } : {}),
         opened: openResult.opened,
         ...(openResult.command ? { openCommand: openResult.command } : {}),
@@ -309,6 +310,26 @@ async function reportServe(io, command, options, server, plan, edge) {
         },
     }, { json: wantsMachine });
 }
+/**
+ * The runs --safe left out, grouped by grade and reasons, and how to share one. A run held back
+ * only for raw screenshots can be exported as a copy with blurred screenshots; the read-results
+ * docs name that step.
+ */
+function hiddenRunLines(groups) {
+    const total = groups.reduce((sum, group) => sum + group.runs, 0);
+    if (total === 0)
+        return [];
+    const runs = (count) => `${count} run${count === 1 ? "" : "s"}`;
+    const lines = [`hidden: ${runs(total)} not share_ready`];
+    for (const group of groups) {
+        const reasons = group.reasons.length > 0 ? ` (${group.reasons.join(", ")})` : "";
+        lines.push(`  ${runs(group.runs)} ${group.status}${reasons}`);
+    }
+    if (groups.some((group) => group.reasons.join(",") === "RAW_SCREENSHOTS"))
+        lines.push("share: a run held back only for RAW_SCREENSHOTS can be copied with blurred screenshots: `humanish export --run <id> --format bundle --redact-screenshots --out <dir>`, then `humanish serve --safe --cwd <dir>`");
+    lines.push("why: `humanish verify --run <id>` explains each reason");
+    return lines;
+}
 function formatServeHuman(result) {
     if (!result.ok) {
         return ([
@@ -323,6 +344,7 @@ function formatServeHuman(result) {
         `mode: ${result.mode}${modeSuffix}`,
         `library: ${result.url ?? ""}`,
         `runs: ${result.runsListed}`,
+        ...hiddenRunLines(result.hiddenRuns ?? []),
     ];
     if (result.publicUrl) {
         lines.push(`public: ${result.publicUrl}`);

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

@@ -0,0 +1,30 @@
+import { type ReclaimHooks } from "../../run/reclaim.js";
+import type { RunInterruptSignal } from "../../run/status.js";
+import type { CliIo } from "../io.js";
+interface RunSignalTarget {
+    on(event: RunInterruptSignal, listener: () => void): unknown;
+    removeListener(event: RunInterruptSignal, listener: () => void): unknown;
+}
+/** Seams for tests; the CLI passes none. */
+export interface RunSignalOptions {
+    signalTarget?: RunSignalTarget;
+    exit?: (code: number) => void;
+    reclaim?: ReclaimHooks;
+    deadlineMs?: number;
+}
+/**
+ * Register work a committed shutdown finishes before it exits, such as closing watch's Observer
+ * server and tunnel. It runs within the same deadline as reclaim. The returned function removes it.
+ */
+export declare function onRunShutdown(cleanup: () => Promise<void>): () => void;
+/**
+ * Install the run's signal handling. `end` removes it. `release` removes it unless a shutdown has
+ * begun, which keeps its handlers so a second signal still exits at once.
+ */
+export declare function beginRunSignalPhase(io: Pick<CliIo, "writeErr">, options?: RunSignalOptions): {
+    end(): void;
+    release(): void;
+};
+/** Analysis is starting, and its own cancel handlers take the signals from here. */
+export declare function handOverRunSignals(): void;
+export {};

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

@@ -0,0 +1,146 @@
+// The run command's signal handling outside post-run analysis. The first interrupt, terminate or
+// hangup signal marks each unfinished run in this process interrupted, kills the E2B sandboxes
+// its create-time receipts name, runs the registered shutdown cleanups (watch's Observer server
+// and tunnel) and exits 128+n, all within one deadline; a second signal exits at once. Routes
+// take no abort signal, so the bundle is not finished, but the record ends at once and no
+// journaled sandbox waits for its timeout. Analysis has its own cancel handlers
+// (analysis-signals.ts) and takes over when it starts.
+import path from "node:path";
+import { activeRuns } from "../../run/active-runs.js";
+import { LATEST_RUN_ALIAS } from "../../run/locate.js";
+import { reclaimPinnedRunSandboxes, } from "../../run/reclaim.js";
+import { SANDBOX_RECEIPTS_ARTIFACT } from "../../run/sandbox-receipts.js";
+import { exitCodeForSignal } from "../observer-follow.js";
+/** How long the handler waits for interrupt, reclaim and cleanups before it exits anyway. */
+const INTERRUPT_RECLAIM_DEADLINE_MS = 10_000;
+/** Each kill's own request timeout, inside the deadline. */
+const KILL_REQUEST_TIMEOUT_MS = 8_000;
+const SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
+let current;
+const shutdownCleanups = new Set();
+/**
+ * Register work a committed shutdown finishes before it exits, such as closing watch's Observer
+ * server and tunnel. It runs within the same deadline as reclaim. The returned function removes it.
+ */
+export function onRunShutdown(cleanup) {
+    shutdownCleanups.add(cleanup);
+    return () => {
+        shutdownCleanups.delete(cleanup);
+    };
+}
+/**
+ * Install the run's signal handling. `end` removes it. `release` removes it unless a shutdown has
+ * begun, which keeps its handlers so a second signal still exits at once.
+ */
+export function beginRunSignalPhase(io, options = {}) {
+    const target = options.signalTarget ?? process;
+    const exit = options.exit ??
+        ((code) => {
+            process.exit(code);
+        });
+    const handlers = new Map();
+    let stopping = false;
+    const end = () => {
+        for (const [signal, handler] of handlers)
+            target.removeListener(signal, handler);
+        handlers.clear();
+        if (current?.end === end)
+            current = undefined;
+    };
+    const release = () => {
+        if (!stopping)
+            end();
+    };
+    const onSignal = (signal) => {
+        if (stopping) {
+            exit(exitCodeForSignal(signal));
+            return;
+        }
+        stopping = true;
+        void stopActiveRuns(io, signal, options)
+            .catch(() => undefined)
+            .finally(() => exit(exitCodeForSignal(signal)));
+    };
+    current?.end();
+    for (const signal of SIGNALS) {
+        const handler = () => onSignal(signal);
+        handlers.set(signal, handler);
+        target.on(signal, handler);
+    }
+    current = { end, release };
+    return { end, release };
+}
+/** Analysis is starting, and its own cancel handlers take the signals from here. */
+export function handOverRunSignals() {
+    current?.release();
+}
+/**
+ * Interrupt, reclaim and the registered cleanups all run inside one deadline that starts before
+ * the first status write is awaited, so a stalled write or kill still ends in a bounded exit.
+ */
+async function stopActiveRuns(io, signal, options) {
+    const deadlineMs = options.deadlineMs ?? INTERRUPT_RECLAIM_DEADLINE_MS;
+    const runs = activeRuns();
+    // Absent: still pending at the deadline. Null: the run had finished, so there is nothing to say.
+    const reports = new Map();
+    const work = Promise.all([
+        ...runs.map(async (run) => {
+            // False when the run had already finished: its route released what it held.
+            if (!(await run.status.interrupt(signal))) {
+                reports.set(run, null);
+                return;
+            }
+            const reclaimed = await reclaimPinnedRunSandboxes(run.cwd, run.paths, {
+                requestTimeoutMs: KILL_REQUEST_TIMEOUT_MS,
+                ...options.reclaim,
+            }).catch(() => undefined);
+            reports.set(run, reclaimSummary(run, reclaimed));
+        }),
+        ...[...shutdownCleanups].map((cleanup) => cleanup().catch(() => undefined)),
+    ]);
+    const finished = await withDeadline(work, deadlineMs);
+    for (const run of runs) {
+        const report = reports.get(run);
+        if (report === null)
+            continue;
+        const text = report ??
+            (finished === "deadline"
+                ? `stopping did not finish within ${deadlineMs / 1000} s; ${recovery(run)}.`
+                : `reclaim failed; ${recovery(run)}.`);
+        try {
+            io.writeErr(`humanish: ${signal}: run ${run.runId} marked interrupted; ${text}\n`);
+        }
+        catch {
+            // A hung-up terminal cannot take the line; the status record and reclaim receipt hold it.
+        }
+    }
+}
+function withDeadline(work, ms) {
+    let timer;
+    const deadline = new Promise((resolve) => {
+        timer = setTimeout(() => resolve("deadline"), ms);
+    });
+    return Promise.race([work, deadline]).finally(() => clearTimeout(timer));
+}
+/**
+ * How to finish what the handler could not. A run whose id is the alias `latest` cannot be named
+ * to reclaim, which would resolve the newest run instead, so it gets its receipts path.
+ */
+function recovery(run) {
+    return run.runId === LATEST_RUN_ALIAS
+        ? `its id is \`${LATEST_RUN_ALIAS}\`, which \`humanish reclaim --run\` reads as the newest run, so kill the ids in ${path.join(run.paths.relativeRunRoot, SANDBOX_RECEIPTS_ARTIFACT)} by hand`
+        : `run \`humanish reclaim --run ${run.runId}\``;
+}
+function reclaimSummary(run, reclaimed) {
+    if (reclaimed === undefined)
+        return `reclaim failed; ${recovery(run)}.`;
+    if (reclaimed.error !== undefined)
+        return reclaimed.error.message;
+    if (reclaimed.outcomes.length === 0)
+        return "no sandbox receipts to reclaim.";
+    const counts = new Map();
+    for (const outcome of reclaimed.outcomes)
+        counts.set(outcome.state, (counts.get(outcome.state) ?? 0) + 1);
+    const tally = [...counts].map(([state, count]) => `${count} ${state}`).join(", ");
+    return reclaimed.ok ? `sandboxes: ${tally}.` : `sandboxes: ${tally}; ${recovery(run)} to retry.`;
+}

package/dist/cli/commands/runs.js

@@ -6,6 +6,7 @@ import { runDryRun } from "../../run/dry-run.js";
 import { verifyRun } from "../../verify/verify.js";
 import { reclaimPreflightSandboxes, reclaimRunSandboxes, } from "../../run/reclaim.js";
 import { runLabCommand } from "./lab-run.js";
+import { countOption } from "../renamed-options.js";
 import { applyEnvFileOption, formatRunHuman, JSON_OPTION_DESCRIPTION, parsePositiveInteger, writeResult, } from "../io.js";
 const SCRIPTED_BROWSER_DOCS_URL = "https://humanish.dev/docs/lab-manifests#scripted-browser-scenarios";
 export function registerRunCommand(parent, io) {
@@ -24,7 +25,9 @@ export function registerRunCommand(parent, io) {
         .option("--no-open", "Render without opening a browser.")
         .option("--detach", "Render/open once and exit without an attached watch server.")
         .option("--port <port>", "Local observer server port when following.", "0")
-        .option("--sims <count>", "Simulation count. A dry run accepts any positive count.")
+        .option("--count <count>", "Override the participant count of a preview or computer-use lab, or of the synthetic run without a lab.")
+        // The older spelling of --count, hidden and noted on stderr (renamed-options.ts).
+        .addOption(new Option("--sims <count>").hideHelp())
         // Agents with an older installed skill still send --app-url. Accepting it hidden lets the
         // refusal name the replacement; commander's bare unknown-option error names nothing. Delete
         // after 0.106.x.
@@ -34,6 +37,7 @@ export function registerRunCommand(parent, io) {
         .option("--run-id <id>", "Explicit run id for deterministic fixture tests; refused when that run already exists.")
         .option("--json", JSON_OPTION_DESCRIPTION)
         .action(async (lab, options, command) => {
+        const count = countOption(io, options);
         if (options.appUrl !== undefined) {
             const result = {
                 schema: "humanish.run-result.v1",
@@ -67,12 +71,12 @@ export function registerRunCommand(parent, io) {
                 mode: "run",
                 // Forwarded wholesale, exactly as `lab run` does. Cherry-picking a subset here is what
                 // made the two commands disagree in the first place.
-                options: options,
+                options: { ...options, count },
             });
             return;
         }
-        const participantCount = options.sims === undefined ? undefined : parsePositiveInteger(options.sims);
-        if (options.sims !== undefined && participantCount === null) {
+        const participantCount = count === undefined ? undefined : parsePositiveInteger(count);
+        if (participantCount === null) {
             const result = {
                 schema: "humanish.run-result.v1",
                 ok: false,
@@ -80,7 +84,7 @@ export function registerRunCommand(parent, io) {
                 warnings: [],
                 error: {
                     code: "HUMANISH_INVALID_SIM_COUNT",
-                    message: "--sims must be a positive integer.",
+                    message: "--count must be a positive integer.",
                 },
             };
             writeResult(command, io, result, formatRunHuman);
@@ -91,9 +95,7 @@ export function registerRunCommand(parent, io) {
             cwd: options.cwd,
             ...(options.dryRun === undefined ? {} : { dryRun: options.dryRun }),
             ...(options.runId === undefined ? {} : { runId: options.runId }),
-            ...(participantCount === undefined || participantCount === null
-                ? {}
-                : { simCount: participantCount }),
+            ...(participantCount === undefined ? {} : { simCount: participantCount }),
             // Rendered the way `watch` renders it, so a bundle is the same bundle whichever command
             // produced it (#597). A render failure is a warning on the result.
             observer: { open: false },

package/dist/cli/commands/watch.js

@@ -3,6 +3,7 @@ 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 { countOption } from "../renamed-options.js";
 import { applyEnvFileOption, collectRepeated, formatRunHuman, JSON_OPTION_DESCRIPTION, parseObserverPort, parsePositiveInteger, wantsJson, writeResult, } from "../io.js";
 import { followObserver, formatObserverHuman, watchExposeRequested } from "../observer-follow.js";
 export function registerWatchCommand(parent, io) {
@@ -14,8 +15,9 @@ export function registerWatchCommand(parent, io) {
         .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("--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.", ".")
@@ -54,7 +56,8 @@ export function registerWatchCommand(parent, io) {
     ].join("\n"))
         .action((labArg, options, command) => handleWatch(io, labArg, options, command));
 }
-async function handleWatch(io, labArg, 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) {
         refuseWatch(command, io, options.cwd, {
@@ -151,7 +154,6 @@ async function watchLab(io, command, lab, options) {
             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 }),
@@ -164,21 +166,21 @@ async function watchLab(io, command, lab, options) {
         },
     });
 }
-/** Without a lab, watch shows existing evidence (`--run`) or a fresh synthetic run (`--sims`). */
+/** 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";
-    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_SIM_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) {

package/dist/cli/doctor.d.ts

@@ -1,5 +1,6 @@
 import { type KeyResolutionDeps } from "../keys/key-resolution.js";
 import { type DetectLocalAgentsOptions } from "../actors/local-agent/cli.js";
+import { type LabSetupCheckArgs } from "../lab/doctor.js";
 declare const DOCTOR_SCHEMA = "humanish.doctor-result.v1";
 export interface DoctorResult {
     schema: typeof DOCTOR_SCHEMA;
@@ -35,5 +36,7 @@ export declare function doctor(cwdInput: string, options?: {
     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"];
 }): Promise<DoctorResult>;
 export {};