humanish 0.107.0 → 0.108.0

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

@@ -1,7 +1,7 @@
 import { loadAdapterScorer } from "../../lab/adapter-scorer-loader.js";
 /**
  * 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.
  */

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

@@ -0,0 +1,4 @@
+import type { Command } from "commander";
+import { type CliIo } from "../io.js";
+/** `humanish migrate`. */
+export declare function registerMigrateCommand(parent: Command, io: CliIo): void;

package/dist/cli/commands/migrate.js

@@ -0,0 +1,65 @@
+import { migrateStudies } from "../../study/migrate.js";
+import { CWD_OPTION_DESCRIPTION, JSON_OPTION_DESCRIPTION, wantsJson, writeResult, } from "../io.js";
+function formatValue(value) {
+    const text = JSON.stringify(value);
+    return text.length > 80 ? `${text.slice(0, 77)}...` : text;
+}
+/** Each file's source, destination, moved keys and dropped keys, printed before any write. */
+function formatMigratePlan(files) {
+    const lines = [];
+    for (const file of files) {
+        if (file.action === "skip") {
+            lines.push(`${file.source}: already humanish.study.v3, skipped`);
+            continue;
+        }
+        const where = file.action === "move" ? `-> ${file.destination}` : "(rewritten in place)";
+        lines.push(`${file.source} ${where} (route: ${file.route})`);
+        if (file.moved.length > 0)
+            lines.push(`  moved: ${file.moved.map((key) => `${key.from} -> ${key.to}`).join(", ")}`);
+        for (const key of file.dropped) {
+            lines.push(`  dropped ${key.path}: ${formatValue(key.value)} (the ${file.route} route never reads it)`);
+            if (key.comments)
+                lines.push(`    its comment: ${key.comments.replace(/\n/g, " ")}`);
+        }
+    }
+    return lines.length > 0 ? `${lines.join("\n")}\n` : "No study files to convert.\n";
+}
+function formatMigrateOutcome(result) {
+    if (result.error) {
+        const where = result.error.file ? ` ${result.error.file}` : "";
+        return `${result.error.code} (${result.error.phase})${where}: ${result.error.message}\n`;
+    }
+    const written = result.files.filter((file) => file.action !== "skip").length;
+    const files = written === 1 ? "1 study file" : `${written} study files`;
+    if (result.dryRun)
+        return `Dry run: nothing was written. ${files} would change.\n`;
+    return written === 0 ? "No v2 study files to convert.\n" : `Converted ${files}.\n`;
+}
+/** `humanish migrate`. */
+export function registerMigrateCommand(parent, io) {
+    parent
+        .command("migrate")
+        .description("Convert humanish.lab.v2 study files to humanish.study.v3. A file under a labs/ directory moves to the matching studies/ directory; any other file is rewritten in place. An original that a failure leaves out of place is kept as <name>.v2.bak. Pass the files to convert; without any, the six study directories are scanned. Every destination, moved key and dropped key is printed before anything is written. A file that changes during the run is kept and listed.")
+        .summary("Convert v2 study files to v3.")
+        // The paths are read from the command's arguments without a declared argument, so the root
+        // --help row stays `migrate [options]` and fits its column; this command's own help shows them.
+        .usage("[options] [path...]")
+        .allowExcessArguments(true)
+        .option("--dry-run", "Print what would change and write nothing.")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action(async (options, command) => {
+        const paths = command.args;
+        const json = wantsJson(command);
+        const result = await migrateStudies({
+            cwd: options.cwd,
+            paths,
+            dryRun: options.dryRun === true,
+            // The plan is printed before anything is written; with --json it goes to stderr, so stdout
+            // stays one JSON document.
+            onPlan: (files) => (json ? io.writeErr : io.writeOut)(formatMigratePlan(files)),
+        });
+        writeResult(command, io, result, formatMigrateOutcome);
+        io.setExitCode(result.ok ? 0 : 2);
+    });
+}

package/dist/cli/commands/observe.js

@@ -3,19 +3,21 @@ import { openTarget, renderObserver, serveObserver } from "../../observer/render
 import { SERVE_SCHEMA, serveObserverLibrary } from "../../observer/serve.js";
 import { startExposedObserver, validateExposure } from "../../observer/exposure.js";
 import { ServeTunnelError } from "../../observer/tunnel.js";
-import { collectRepeated, formatRunHuman, JSON_OPTION_DESCRIPTION, parseObserverPort, wantsJson, writeResult, } from "../io.js";
+import { deprecationMessage, warnAndQueue } from "../deprecations.js";
+import { collectRepeated, CWD_OPTION_DESCRIPTION, formatRunHuman, freePortOption, JSON_OPTION_DESCRIPTION, parseObserverPort, RUN_OPTION_DESCRIPTION, wantsJson, writeResult, } from "../io.js";
 import { exitCodeForSignal, formatObserverHuman, } from "../observer-follow.js";
 export function registerObserveCommand(parent, io) {
-    parent
+    addLibraryOptions(parent
         .command("observe")
-        .description("Follow a run's saved evidence in Observer over loopback http://127.0.0.1.")
-        .summary("Follow a run's saved evidence over loopback http.")
-        .option("--run <id>", "Run id or latest pointer.", "latest")
-        .option("--port <port>", "Loopback port to bind on 127.0.0.1. Defaults to an ephemeral port.", "0")
-        .option("--cwd <path>", "Target project directory.", ".")
-        .option("--open", "Open the observer in the default browser.")
+        .description("Open a saved run in the Observer, served on http://127.0.0.1; without --run, the latest. With --all, serve the run library, opening on --run when given.")
+        .summary("Open a saved run in the Observer.")
+        .option("--run <id>", RUN_OPTION_DESCRIPTION)
+        .option("--all", "Serve the whole run library, with optional tunnel-edge exposure.")
+        .addOption(freePortOption())
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
+        .option("--open", "Open the Observer in the default browser.")
         .option("--no-open", "Serve without opening a browser.")
-        .option("--json", JSON_OPTION_DESCRIPTION)
+        .option("--json", JSON_OPTION_DESCRIPTION))
         .addHelpText("after", [
         "",
         "Examples:",
@@ -23,62 +25,128 @@ export function registerObserveCommand(parent, io) {
         "  humanish observe --run latest",
         "  humanish observe --run <runId> --port 8732",
         "  humanish observe --no-open --json",
+        "  humanish observe --all",
+        "  humanish observe --all --expose --tunnel ngrok --oauth google --allow-email you@example.com",
+        "  humanish observe --all --safe --expose --tunnel ngrok",
+        "  humanish observe --all --expose --public-url https://observer.example.com",
         "",
-        "The server binds 127.0.0.1 only and exposes just the run's bundle directory.",
-        "It stays attached until Ctrl-C; file:// security policy and live refresh are why",
-        "loopback http is preferred over opening the index.html path directly.",
+        "The server binds 127.0.0.1 only. One run exposes just that run's bundle directory; --all",
+        "serves the run library. It stays attached until Ctrl-C; file:// security policy and live",
+        "refresh are why loopback http is preferred over opening the index.html path directly.",
+        "",
+        "--safe, --expose, --tunnel, --tunnel-domain, --oauth, --allow-email, --allow-domain and",
+        "--public-url need --all. Exposure only ever happens through an authenticated edge (ngrok",
+        "--oauth google, or an operator --public-url you secure) forwarding to the loopback port;",
+        "the server carries no in-process auth. Live desktop stream URLs are never served; remote",
+        "viewers see persisted evidence only. --safe composes with any exposure.",
     ].join("\n"))
-        .action(async (options, command) => {
-        const port = parseObserverPort(options.port);
-        if (port === null) {
-            const result = {
-                schema: "humanish.run-result.v1",
-                ok: false,
-                cwd: options.cwd,
-                warnings: [],
-                error: {
-                    code: "HUMANISH_INVALID_PORT",
-                    message: "--port must be an integer between 0 and 65535.",
-                },
-            };
-            writeResult(command, io, result, formatRunHuman);
-            io.setExitCode(2);
-            return;
-        }
-        const rendered = await renderObserver(options.cwd, options.run, { open: false });
-        if (!rendered.ok || !rendered.observerPath) {
-            writeResult(command, io, rendered, formatObserverHuman);
-            io.setExitCode(2);
-            return;
-        }
-        // Reuse the contained current-data projection, scoped to this run. A raw static
-        // server would miss runtime status and could replay stored iframe grants.
-        const wantsMachine = wantsJson(command);
-        const shouldOpen = options.open === false
-            ? false
-            : options.open === true
-                ? true
-                : !wantsMachine && process.stdout.isTTY === true;
-        const server = await serveObserver(rendered, { open: false, port, scope: "run" });
-        const openResult = shouldOpen
-            ? openTarget(server.url)
-            : { opened: false };
+        .action((options, command) => handleObserve(io, options, command));
+}
+/** The run library's flags, on `observe --all` and the hidden `serve` alias. */
+function addLibraryOptions(command) {
+    return command
+        .option("--safe", "Serve only runs whose verify shareSafety is share_ready; other runs are not served at all.")
+        .option("--expose", "Share the library beyond this machine. Requires --oauth or --public-url, or --safe.")
+        .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("--public-url <origin>", "Bring-your-own authed edge (e.g. https://observer.example.com). Requires --expose; never affects binding.");
+}
+/** The library flags set on a one-run observe, as typed on the command line. */
+function libraryOnlyFlags(options) {
+    return [
+        options.safe === true ? ["--safe"] : [],
+        options.expose === true ? ["--expose"] : [],
+        options.tunnel === undefined ? [] : ["--tunnel"],
+        options.tunnelDomain === undefined ? [] : ["--tunnel-domain"],
+        options.oauth === undefined ? [] : ["--oauth"],
+        (options.allowEmail?.length ?? 0) === 0 ? [] : ["--allow-email"],
+        (options.allowDomain?.length ?? 0) === 0 ? [] : ["--allow-domain"],
+        options.publicUrl === undefined ? [] : ["--public-url"],
+    ].flat();
+}
+function refuseObserve(command, io, cwd, error) {
+    const result = {
+        schema: "humanish.run-result.v1",
+        ok: false,
+        cwd,
+        warnings: [],
+        ...(error === undefined ? {} : { error }),
+    };
+    writeResult(command, io, result, formatRunHuman);
+    io.setExitCode(2);
+}
+/** `observe` shows one run (default latest); `observe --all` serves the run library. */
+async function handleObserve(io, options, command) {
+    if (options.all === true) {
+        await handleServe(io, options, command);
+        return;
+    }
+    const libraryOnly = libraryOnlyFlags(options);
+    if (libraryOnly.length > 0) {
+        refuseObserve(command, io, options.cwd, {
+            code: "HUMANISH_OBSERVE_OPTION_CONFLICT",
+            message: `${libraryOnly.join(", ")} ${libraryOnly.length === 1 ? "needs" : "need"} --all: humanish observe --all ${libraryOnly.join(" ")}.`,
+        });
+        return;
+    }
+    await observeRun(io, { ...options, run: options.run ?? "latest" }, command);
+}
+/** One run's Observer over loopback, until a signal stops it. */
+async function observeRun(io, options, command) {
+    const port = parseObserverPort(options.port);
+    if (port === null) {
         const result = {
-            ...rendered,
-            observerUrl: server.url,
-            serverUrl: server.url,
-            opened: openResult.opened,
-            ...(openResult.command ? { openCommand: openResult.command } : {}),
-            warnings: [
-                ...rendered.warnings,
-                "Observer is served read-only over loopback http on 127.0.0.1; only this run's bundle directory is exposed.",
-                ...(openResult.warning ? [openResult.warning] : []),
-            ],
+            schema: "humanish.run-result.v1",
+            ok: false,
+            cwd: options.cwd,
+            warnings: [],
+            error: {
+                code: "HUMANISH_INVALID_PORT",
+                message: "--port must be an integer between 0 and 65535.",
+            },
         };
-        writeResult(command, io, result, formatObserverHuman);
-        io.setExitCode(0);
-        await serveObserveUntilSignal(io, server, { json: wantsMachine });
-    });
+        writeResult(command, io, result, formatRunHuman);
+        io.setExitCode(2);
+        return;
+    }
+    const rendered = await renderObserver(options.cwd, options.run, { open: false });
+    if (!rendered.ok || !rendered.observerPath) {
+        writeResult(command, io, rendered, formatObserverHuman);
+        io.setExitCode(2);
+        return;
+    }
+    // Reuse the contained current-data projection, scoped to this run. A raw static
+    // server would miss runtime status and could replay stored iframe grants.
+    const wantsMachine = wantsJson(command);
+    const shouldOpen = options.open === false
+        ? false
+        : options.open === true
+            ? true
+            : !wantsMachine && process.stdout.isTTY === true;
+    const server = await serveObserver(rendered, { open: false, port, scope: "run" });
+    const openResult = shouldOpen
+        ? openTarget(server.url)
+        : { opened: false };
+    const result = {
+        ...rendered,
+        observerUrl: server.url,
+        serverUrl: server.url,
+        opened: openResult.opened,
+        ...(openResult.command ? { openCommand: openResult.command } : {}),
+        warnings: [
+            ...rendered.warnings,
+            "Observer is served read-only over loopback http on 127.0.0.1; only this run's bundle directory is exposed.",
+            ...(openResult.warning ? [openResult.warning] : []),
+        ],
+    };
+    writeResult(command, io, result, formatObserverHuman);
+    io.setExitCode(0);
+    await serveObserveUntilSignal(io, server, { json: wantsMachine });
 }
 async function serveObserveUntilSignal(io, server, options) {
     // Keep the JSON envelope on stdout clean: route attach/stop chatter to stderr
@@ -117,45 +185,19 @@ async function serveObserveUntilSignal(io, server, options) {
         }
     });
 }
+// Removed in 0.109.0: `serve` stays one minor as a hidden alias of `observe --all`.
 export function registerServeCommand(parent, io) {
-    parent
-        .command("serve")
-        .description("Serve the local run library over loopback http, with optional tunnel-edge authenticated exposure.")
-        .summary("Serve the run library; optional tunnel-edge exposure.")
-        .option("--cwd <path>", "Target project directory.", ".")
-        .option("--port <port>", "Loopback port to bind on 127.0.0.1. Defaults to an ephemeral port.", "0")
-        .option("--run <id>", "Land on this run id (or latest) instead of the library index.")
-        .option("--safe", "Serve only runs whose verify shareSafety is share_ready; everything else is absent (fail-closed).")
-        .option("--expose", "Declare exposure intent. Requires edge auth (--oauth or --public-url) OR --safe.")
-        .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("--public-url <origin>", "Bring-your-own authed edge (e.g. https://observer.example.com). Requires --expose; never affects binding.")
+    addLibraryOptions(parent
+        .command("serve", { hidden: true })
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
+        .addOption(freePortOption())
+        .option("--run <id>", RUN_OPTION_DESCRIPTION)
         .option("--open", "Open the library in the default browser.")
         .option("--no-open", "Serve without opening a browser.")
-        .option("--json", JSON_OPTION_DESCRIPTION)
-        .addHelpText("after", [
-        "",
-        "Happy path:",
-        "  humanish serve",
-        "  humanish serve --expose --tunnel ngrok --oauth google --allow-email you@example.com",
-        "  humanish serve --safe --expose --tunnel ngrok",
-        "  humanish serve --expose --public-url https://observer.example.com",
-        "",
-        "Agent/CI path:",
-        "  humanish serve --json --no-open",
-        "",
-        "The server always binds 127.0.0.1; exposure only ever happens through an authenticated",
-        "edge (ngrok --oauth google, or an operator --public-url you secure) forwarding to the",
-        "loopback port. The server carries no in-process auth; the gate lives at the edge. Live",
-        "desktop stream URLs are never served here; remote viewers see persisted evidence only.",
-        "--safe composes with any exposure for defense in depth.",
-    ].join("\n"))
-        .action((options, command) => handleServe(io, options, command));
+        .option("--json", JSON_OPTION_DESCRIPTION)).action((options, command) => {
+        warnAndQueue(command, io, deprecationMessage("humanish serve", "humanish observe --all"));
+        return handleServe(io, options, command);
+    });
 }
 async function handleServe(io, options, command) {
     const fail = (code, message) => refuseServe(command, io, options, code, message);
@@ -171,8 +213,8 @@ async function handleServe(io, options, command) {
         ...(options.tunnel === undefined ? {} : { tunnel: options.tunnel }),
         ...(options.tunnelDomain === undefined ? {} : { tunnelDomain: options.tunnelDomain }),
         ...(options.oauth === undefined ? {} : { oauth: options.oauth }),
-        allowEmails: options.allowEmail,
-        allowDomains: options.allowDomain,
+        allowEmails: options.allowEmail ?? [],
+        allowDomains: options.allowDomain ?? [],
         ...(options.publicUrl === undefined ? {} : { publicUrl: options.publicUrl }),
         safe: options.safe === true,
     });
@@ -257,7 +299,7 @@ async function reportServe(io, command, options, server, plan, edge) {
         ...serveExposureWarnings(server, options.safe === true, publicUrl),
     ];
     // Auto-open is suppressed under --expose so the public URL is not shoved into a local opener's
-    // argv unasked — the exposure target is a remote device anyway. Explicit --open still honors
+    // argv unasked; the exposure target is a remote device anyway. Explicit --open still honors
     // intent and opens the loopback library.
     const shouldOpen = options.open === false
         ? false
@@ -326,21 +368,18 @@ function hiddenRunLines(groups) {
         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("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 observe --all --safe --cwd <dir>`");
     lines.push("why: `humanish verify --run <id>` explains each reason");
     return lines;
 }
 function formatServeHuman(result) {
     if (!result.ok) {
-        return ([
-            "humanish serve failed",
-            ...(result.error ? [`error: ${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 };
     }
     const modeSuffix = result.safe ? " (share_ready only)" : "";
     const lines = [
-        "humanish serve",
+        "humanish observe --all",
         `mode: ${result.mode}${modeSuffix}`,
         `library: ${result.url ?? ""}`,
         `runs: ${result.runsListed}`,
@@ -354,7 +393,7 @@ function formatServeHuman(result) {
     }
     if (result.oauth) {
         const rules = [...result.oauth.allowEmails, ...result.oauth.allowDomains];
-        lines.push(`edge auth: ${result.oauth.provider} oauth${rules.length > 0 ? ` (allow: ${rules.join(", ")})` : " (no allow rule — any Google account)"}`);
+        lines.push(`edge auth: ${result.oauth.provider} oauth${rules.length > 0 ? ` (allow: ${rules.join(", ")})` : " (no allow rule: any Google account can sign in)"}`);
     }
     if (result.entryRunId) {
         lines.push(`entry: ${result.entryRunId}`);

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

@@ -0,0 +1,10 @@
+import type { Command } from "commander";
+import { type CliIo, type LabCommandOptions as RunOptions } from "../io.js";
+/** The parsed flags of `run`, `watch` and the `lab run` alias. */
+export type { RunOptions };
+/** The flags a run takes, whichever command starts it. */
+export declare function addRunOptions(command: Command): Command;
+/** The flags that only a study file can use, as typed on the command line, when they are set. */
+export declare function studyOnlyFlags(options: RunOptions): string[];
+/** `humanish run [study]`: the named study, or the synthetic preview when no study is given. */
+export declare function handleRun(io: CliIo, named: string | undefined, options: RunOptions, command: Command): Promise<void>;

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

@@ -0,0 +1,85 @@
+import { runDryRun } from "../../run/dry-run.js";
+import { runLabCommand } from "./lab-run.js";
+import { applyEnvFileOption, CWD_OPTION_DESCRIPTION, ENV_FILE_OPTION_DESCRIPTION, formatRunHuman, freePortOption, JSON_OPTION_DESCRIPTION, parsePositiveInteger, writeResult, } from "../io.js";
+/** The flags a run takes, whichever command starts it. */
+export function addRunOptions(command) {
+    return command
+        .option("--dry-run", "Do a dry run: a synthetic run with no browser, keys or provider spend.")
+        .option("--open", "Open the Observer in the default browser.")
+        .option("--no-open", "Render without opening a browser.")
+        .option("--detach", "Render/open once and exit without an attached watch server.")
+        .addOption(freePortOption())
+        .option("--count <count>", "Override the participant count of a preview or computer-use study, or of the synthetic run without a study.")
+        .option("--rerun-failed-from <run>", "Computer-use studies only: start a new run for the failed participants of a prior run.")
+        .option("--participants <ids>", "With --rerun-failed-from: comma-separated ids of the participants to rerun. The study's participants decide who takes part; ids are their id, or lane-01, lane-02, … by position.")
+        .option("--scorer <path>", "Score with this .mjs module, a path inside the repo, in place of review.scorer.ref. It runs as code, so review it first. Terminal, computer-use and shared-world studies only.")
+        .option("--cwd <path>", CWD_OPTION_DESCRIPTION, ".")
+        .option("--env-file <path>", ENV_FILE_OPTION_DESCRIPTION)
+        .option("--run-id <id>", "Explicit run id for deterministic fixture tests; refused when that run already exists.")
+        .option("--json", JSON_OPTION_DESCRIPTION);
+}
+/** The flags that only a study file can use, as typed on the command line, when they are set. */
+export function studyOnlyFlags(options) {
+    return [
+        options.scorer === undefined ? [] : ["--scorer"],
+        options.rerunFailedFrom === undefined ? [] : ["--rerun-failed-from"],
+        options.participants === undefined ? [] : ["--participants"],
+    ].flat();
+}
+function refuseRun(command, io, cwd, error) {
+    const result = {
+        schema: "humanish.run-result.v1",
+        ok: false,
+        cwd,
+        warnings: [],
+        ...(error === undefined ? {} : { error }),
+    };
+    writeResult(command, io, result, formatRunHuman);
+    io.setExitCode(2);
+}
+/** `humanish run [study]`: the named study, or the synthetic preview when no study is given. */
+export async function handleRun(io, named, options, command) {
+    // An empty argument, as from a script passing an unset variable, is the synthetic run.
+    const study = named === "" ? undefined : named;
+    const studyOnly = studyOnlyFlags(options);
+    if (study === undefined && studyOnly.length > 0) {
+        refuseRun(command, io, options.cwd, {
+            code: "HUMANISH_RUN_OPTION_CONFLICT",
+            message: `${studyOnly.join(", ")} ${studyOnly.length === 1 ? "needs" : "need"} a study: humanish run <study>.`,
+        });
+        return;
+    }
+    const loaded = await applyEnvFileOption({
+        command,
+        cwd: options.cwd,
+        envFile: options.envFile,
+        io,
+        // runLabCommand discovers keys for a live lab; the lab-less preview needs none.
+        discoverKeys: false,
+    });
+    if (!loaded)
+        return;
+    if (study !== undefined) {
+        await runLabCommand({ command, io, lab: study, mode: "run", options });
+        return;
+    }
+    const participantCount = options.count === undefined ? undefined : parsePositiveInteger(options.count);
+    if (participantCount === null) {
+        refuseRun(command, io, options.cwd, {
+            code: "HUMANISH_INVALID_PARTICIPANT_COUNT",
+            message: "--count must be a positive integer.",
+        });
+        return;
+    }
+    const result = await runDryRun({
+        cwd: options.cwd,
+        ...(options.dryRun === undefined ? {} : { dryRun: options.dryRun }),
+        ...(options.runId === undefined ? {} : { runId: options.runId }),
+        ...(participantCount === undefined ? {} : { participantCount }),
+        // Rendered the way `watch` renders it, so a bundle is the same bundle whichever command
+        // produced it. A render failure is a warning on the result.
+        observer: { open: false },
+    });
+    writeResult(command, io, result, formatRunHuman);
+    io.setExitCode(result.ok ? 0 : 2);
+}