humanish 0.104.3 → 0.106.0

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

@@ -0,0 +1,74 @@
+import { Command } from "commander";
+import { formatRunHuman, parseLabCount, writeResult, } from "../io.js";
+import { planObserver, showObserver, staticObserverOpen } from "../observer-follow.js";
+/**
+ * The preview route's CLI setup: the sim count and Observer plan, its runLab options, and how it
+ * presents the outcome. Undefined when setup has already written its own result.
+ */
+export function previewRouteRun(args) {
+    const participantCount = parseLabCount(args.options.sims, args.config.actors[0]?.count ?? 4);
+    if (participantCount === null) {
+        const result = {
+            schema: "humanish.run-result.v1",
+            ok: false,
+            cwd: args.options.cwd,
+            warnings: [],
+            error: {
+                code: "HUMANISH_INVALID_SIM_COUNT",
+                message: "--sims must be a positive integer.",
+            },
+        };
+        writeResult(args.command, args.io, result, formatRunHuman);
+        args.io.setExitCode(2);
+        return undefined;
+    }
+    // `run` renders the Observer too, so `run` and `watch` write the same bundle and the first
+    // `export` of a run bundle finds observer/index.html (#597). A render failure is a warning on the
+    // result, never a failed run. The preview renders through its finished run, so the page shown is
+    // the run just written, never a directory swapped in under its id.
+    const openOverride = args.options.open ?? args.config.defaults?.open;
+    const plan = args.mode === "watch"
+        ? planObserver({
+            command: args.command,
+            cwd: args.options.cwd,
+            io: args.io,
+            port: args.options.port ?? "0",
+            ...(args.options.detach === undefined ? {} : { detach: args.options.detach }),
+            ...(openOverride === undefined ? {} : { open: openOverride }),
+        })
+        : undefined;
+    if (plan === null)
+        return undefined;
+    return {
+        options: {
+            cwd: args.options.cwd,
+            ...(args.labProvenance === undefined ? {} : { lab: args.labProvenance }),
+            count: participantCount,
+            ...(args.options.dryRun === undefined ? {} : { dryRun: args.options.dryRun }),
+            ...(args.options.runId === undefined ? {} : { runId: args.options.runId }),
+            open: plan === undefined ? false : staticObserverOpen(plan),
+        },
+        present: async (outcome) => {
+            if (outcome.route !== "preview") {
+                throw new Error(`Expected the preview route, got ${outcome.route}.`);
+            }
+            const runResult = outcome.result;
+            if (plan === undefined) {
+                writeResult(args.command, args.io, runResult, formatRunHuman);
+                args.io.setExitCode(runResult.ok ? 0 : 2);
+                return;
+            }
+            if (!runResult.ok || runResult.observer === undefined) {
+                writeResult(args.command, args.io, runResult, formatRunHuman);
+                args.io.setExitCode(2);
+                return;
+            }
+            await showObserver({
+                command: args.command,
+                io: args.io,
+                plan,
+                rendered: runResult.observer,
+            });
+        },
+    };
+}

package/dist/cli/commands/lab-route-run.d.ts

@@ -0,0 +1,17 @@
+import { type LabOutcome, type RunLabOptions } from "../../run-lab.js";
+import type { LabConfig } from "../../lab/types.js";
+import type { LoadedAdapterScorer } from "./lab-scorer.js";
+export interface RouteRun {
+    readonly options: RunLabOptions;
+    present(outcome: LabOutcome): Promise<void>;
+    /** Handles an error runLab threw, and rethrows any it does not handle. */
+    onRunError?(error: unknown): Promise<void>;
+}
+/**
+ * Plans the lab with a route's options, then presents the refusal or the run. `beforeRun` runs
+ * only for a plan that will run: it loads the scorer, or writes its own refusal and returns
+ * undefined, so a refused lab never imports the scorer's host code.
+ */
+export declare function runRoute(config: LabConfig, run: RouteRun, beforeRun?: () => Promise<{
+    scorer?: LoadedAdapterScorer;
+} | undefined>): Promise<void>;

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

@@ -0,0 +1,31 @@
+// What a route's CLI setup hands the lab command: the runLab options it chose and how it presents
+// the outcome. runRoute plans the lab once and runs it between the two.
+import { prepareLab } from "../../run-lab.js";
+/**
+ * Plans the lab with a route's options, then presents the refusal or the run. `beforeRun` runs
+ * only for a plan that will run: it loads the scorer, or writes its own refusal and returns
+ * undefined, so a refused lab never imports the scorer's host code.
+ */
+export async function runRoute(config, run, beforeRun = () => Promise.resolve({})) {
+    let outcome;
+    try {
+        const prepared = await prepareLab(config, run.options);
+        if (prepared.ok) {
+            const ready = await beforeRun();
+            if (ready === undefined)
+                return;
+            const { scorer } = ready;
+            outcome = await prepared.run(scorer ? { scorer: scorer.hooks, scorerProvenance: scorer.provenance } : undefined);
+        }
+        else {
+            outcome = prepared.outcome;
+        }
+    }
+    catch (error) {
+        if (run.onRunError === undefined)
+            throw error;
+        await run.onRunError(error);
+        return;
+    }
+    await run.present(outcome);
+}

package/dist/cli/commands/lab-route-scripted.d.ts

@@ -0,0 +1,19 @@
+import { Command } from "commander";
+import type { RunLabProvenance } from "../../run/status.js";
+import type { LabConfig } from "../../lab/types.js";
+import { type CliIo, type LabCommandOptions } from "../io.js";
+import type { RouteRun } from "./lab-route-run.js";
+interface ScriptedRouteArgs {
+    command: Command;
+    io: CliIo;
+    config: LabConfig;
+    labProvenance?: RunLabProvenance;
+    mode: "run" | "watch";
+    options: LabCommandOptions;
+}
+/**
+ * The scripted route's CLI setup: its open semantics and runLab options, and how it presents the
+ * outcome. Undefined when watch-mode setup has already written its own result.
+ */
+export declare function scriptedRouteRun(args: ScriptedRouteArgs): RouteRun | undefined;
+export {};

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

@@ -0,0 +1,50 @@
+import { automaticAnalysisSucceeded } from "../../analysis/automatic-completion.js";
+import { Command } from "commander";
+import { cliAnalysisOptions } from "./analysis-signals.js";
+import { wantsJson, writeResult } from "../io.js";
+import { showObserver } from "../observer-follow.js";
+import { formatScriptedLabHuman } from "./lab-format.js";
+import { observerOpen, resolveRouteShouldOpen, watchFinishedPlan } from "./lab-route-open.js";
+/**
+ * The scripted route's CLI setup: its open semantics and runLab options, and how it presents the
+ * outcome. Undefined when watch-mode setup has already written its own result.
+ */
+export function scriptedRouteRun(args) {
+    const wantsMachine = wantsJson(args.command);
+    const shouldOpen = resolveRouteShouldOpen({
+        optionOpen: args.options.open,
+        defaultsOpen: args.config.defaults?.open,
+        mode: args.mode,
+        wantsMachine,
+    });
+    const finishedPlan = watchFinishedPlan(args, wantsMachine, shouldOpen);
+    if (finishedPlan === null)
+        return undefined;
+    return {
+        options: {
+            ...cliAnalysisOptions(args.io),
+            cwd: args.options.cwd,
+            ...(args.labProvenance === undefined ? {} : { lab: args.labProvenance }),
+            open: observerOpen(args.mode, finishedPlan, shouldOpen),
+            ...(args.options.dryRun === undefined ? {} : { dryRun: args.options.dryRun }),
+            ...(args.options.runId === undefined ? {} : { runId: args.options.runId }),
+        },
+        present: async (outcome) => {
+            if (outcome.route !== "scripted") {
+                throw new Error(`Expected the scripted route, got ${outcome.route}.`);
+            }
+            const result = outcome.result;
+            writeResult(args.command, args.io, result, formatScriptedLabHuman);
+            args.io.setExitCode(result.ok && automaticAnalysisSucceeded(result) ? 0 : 2);
+            // Watch mode serves the Observer the route rendered through its finished run.
+            if (finishedPlan !== undefined && result.ok && result.observer !== undefined) {
+                await showObserver({
+                    command: args.command,
+                    io: args.io,
+                    plan: finishedPlan,
+                    rendered: result.observer,
+                });
+            }
+        },
+    };
+}

package/dist/cli/commands/lab-route-shared-world.d.ts

@@ -0,0 +1,20 @@
+import { Command } from "commander";
+import type { RunLabProvenance } from "../../run/status.js";
+import type { LabConfig } from "../../lab/types.js";
+import { type CliIo, type LabCommandOptions } from "../io.js";
+import type { RouteRun } from "./lab-route-run.js";
+interface SharedWorldRouteArgs {
+    command: Command;
+    io: CliIo;
+    config: LabConfig;
+    labProvenance?: RunLabProvenance;
+    mode: "run" | "watch";
+    options: LabCommandOptions;
+}
+/**
+ * The shared-world route's CLI setup: dry run, open and follow semantics, the live Observer server
+ * the run attaches, and how it presents the outcome. Undefined when setup has already written its
+ * own result.
+ */
+export declare function sharedWorldRouteRun(args: SharedWorldRouteArgs): RouteRun | undefined;
+export {};

package/dist/cli/commands/lab-route-shared-world.js

@@ -0,0 +1,135 @@
+import { automaticAnalysisSucceeded } from "../../analysis/automatic-completion.js";
+import { Command } from "commander";
+import { resolveLabDryRun } from "../../lab/plan.js";
+import { serveObserver } from "../../observer/render.js";
+import { redactText } from "../../evidence/redaction.js";
+import { cliAnalysisOptions } from "./analysis-signals.js";
+import { parseObserverPort, wantsJson, writeResult, } from "../io.js";
+import { followObserver, showObserver, staticObserverOpen, withObserverServer, } from "../observer-follow.js";
+import { formatConcurrentSharedWorldLabHuman } from "./lab-format.js";
+import { resolveRouteShouldOpen, watchFinishedPlan } from "./lab-route-open.js";
+import { rosterOf } from "../../lab/parse/actors.js";
+/**
+ * The shared-world route's CLI setup: dry run, open and follow semantics, the live Observer server
+ * the run attaches, and how it presents the outcome. Undefined when setup has already written its
+ * own result.
+ */
+export function sharedWorldRouteRun(args) {
+    const wantsMachine = wantsJson(args.command);
+    const dryRun = resolveLabDryRun(args.config, args.options.dryRun, true) ?? true;
+    const shouldOpen = resolveRouteShouldOpen({
+        optionOpen: args.options.open,
+        defaultsOpen: args.config.defaults?.open,
+        mode: args.mode,
+        wantsMachine,
+    });
+    const wantsFollow = args.mode === "watch" && !wantsMachine && args.options.detach !== true && dryRun !== true;
+    const port = parseObserverPort(args.options.port ?? "0");
+    const failConcurrent = (message, runId) => {
+        const result = {
+            schema: "humanish.concurrent-shared-world-lab-result.v1",
+            ok: false,
+            cwd: args.options.cwd,
+            labId: args.config.id,
+            actor: args.config.actors[0]?.type ?? "",
+            topology: "shared-world",
+            topologyMode: "concurrent",
+            roleCount: rosterOf(args.config.actors[0])?.length ?? 0,
+            concurrency: args.config.execution?.concurrency ?? 1,
+            dryRun,
+            runId: runId ?? args.options.runId ?? "not-created",
+            roles: [],
+            warnings: [],
+            error: { code: "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_FAILED", message },
+        };
+        writeResult(args.command, args.io, result, formatConcurrentSharedWorldLabHuman);
+        args.io.setExitCode(2);
+    };
+    if (wantsFollow && port === null) {
+        failConcurrent("--port must be an integer between 0 and 65535.");
+        return undefined;
+    }
+    // A watch that does not follow the live run shows the Observer the route rendered through its
+    // finished run once the run ends, never a re-render by run id.
+    const finishedPlan = wantsFollow ? undefined : watchFinishedPlan(args, wantsMachine, shouldOpen);
+    if (finishedPlan === null)
+        return undefined;
+    let server = null;
+    let attachedObserver = null;
+    // Set when the live Observer itself failed to start: an operator-side failure, reported as a
+    // structured result rather than an unexpected error.
+    let observerFailure;
+    return {
+        options: {
+            ...cliAnalysisOptions(args.io),
+            cwd: args.options.cwd,
+            ...(args.labProvenance === undefined ? {} : { lab: args.labProvenance }),
+            open: wantsFollow
+                ? false
+                : finishedPlan === undefined
+                    ? shouldOpen
+                    : staticObserverOpen(finishedPlan),
+            dryRun,
+            ...(wantsFollow
+                ? {
+                    onObserverReady: async (observer) => {
+                        attachedObserver = observer;
+                        try {
+                            server ??= await serveObserver(observer, { open: shouldOpen, port: port ?? 0 });
+                        }
+                        catch (error) {
+                            observerFailure = error;
+                            throw error;
+                        }
+                    },
+                }
+                : {}),
+            ...(args.options.runId === undefined ? {} : { runId: args.options.runId }),
+        },
+        onRunError: async (error) => {
+            await server?.close().catch((cleanupError) => {
+                args.io.writeErr(`watch cleanup failed: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}\n`);
+            });
+            server = null;
+            if (observerFailure !== undefined && error === observerFailure) {
+                const message = redactText(error instanceof Error ? error.message : String(error));
+                failConcurrent(`The live Observer could not start, so the run stopped before its participants: ${message}`, attachedObserver?.run);
+                return;
+            }
+            throw error;
+        },
+        present: async (outcome) => {
+            if (outcome.route !== "shared-world") {
+                throw new Error(`Expected the shared-world route, got ${outcome.route}.`);
+            }
+            const result = outcome.result;
+            let output = result;
+            if (server && attachedObserver) {
+                output = {
+                    ...result,
+                    observer: result.observer?.ok
+                        ? withObserverServer(result.observer, server)
+                        : withObserverServer(attachedObserver, server),
+                    warnings: [
+                        ...result.warnings,
+                        "Live concurrent shared-world server is polling observer-data.json with no-store caching.",
+                        ...(server.warning ? [server.warning] : []),
+                    ],
+                };
+            }
+            writeResult(args.command, args.io, output, formatConcurrentSharedWorldLabHuman);
+            args.io.setExitCode(result.ok && automaticAnalysisSucceeded(result) ? 0 : 2);
+            if (server && output.observer?.ok) {
+                await followObserver(args.io, output.observer, server);
+            }
+            else if (finishedPlan !== undefined && result.ok && result.observer !== undefined) {
+                await showObserver({
+                    command: args.command,
+                    io: args.io,
+                    plan: finishedPlan,
+                    rendered: result.observer,
+                });
+            }
+        },
+    };
+}

package/dist/cli/commands/lab-route-terminal.d.ts

@@ -0,0 +1,19 @@
+import { Command } from "commander";
+import type { RunLabProvenance } from "../../run/status.js";
+import type { LabConfig } from "../../lab/types.js";
+import { type CliIo, type LabCommandOptions } from "../io.js";
+import type { RouteRun } from "./lab-route-run.js";
+interface TerminalRouteArgs {
+    command: Command;
+    io: CliIo;
+    config: LabConfig;
+    labProvenance?: RunLabProvenance;
+    mode: "run" | "watch";
+    options: LabCommandOptions;
+}
+/**
+ * The terminal route's CLI setup: its open semantics and runLab options, and how it presents the
+ * outcome. Undefined when watch-mode setup has already written its own result.
+ */
+export declare function terminalRouteRun(args: TerminalRouteArgs): RouteRun | undefined;
+export {};

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

@@ -0,0 +1,49 @@
+import { automaticAnalysisSucceeded } from "../../analysis/automatic-completion.js";
+import { Command } from "commander";
+import { cliAnalysisOptions } from "./analysis-signals.js";
+import { wantsJson, writeResult } from "../io.js";
+import { showObserver } from "../observer-follow.js";
+import { formatTerminalLabHuman } from "./lab-format.js";
+import { observerOpen, resolveRouteShouldOpen, watchFinishedPlan } from "./lab-route-open.js";
+/**
+ * The terminal route's CLI setup: its open semantics and runLab options, and how it presents the
+ * outcome. Undefined when watch-mode setup has already written its own result.
+ */
+export function terminalRouteRun(args) {
+    const wantsMachine = wantsJson(args.command);
+    const shouldOpen = resolveRouteShouldOpen({
+        optionOpen: args.options.open,
+        defaultsOpen: args.config.defaults?.open,
+        mode: args.mode,
+        wantsMachine,
+    });
+    const finishedPlan = watchFinishedPlan(args, wantsMachine, shouldOpen);
+    if (finishedPlan === null)
+        return undefined;
+    return {
+        options: {
+            ...cliAnalysisOptions(args.io),
+            cwd: args.options.cwd,
+            ...(args.labProvenance === undefined ? {} : { lab: args.labProvenance }),
+            open: observerOpen(args.mode, finishedPlan, shouldOpen),
+            ...(args.options.dryRun === undefined ? {} : { dryRun: args.options.dryRun }),
+            ...(args.options.runId === undefined ? {} : { runId: args.options.runId }),
+        },
+        present: async (outcome) => {
+            if (outcome.route !== "terminal") {
+                throw new Error(`Expected the terminal route, got ${outcome.route}.`);
+            }
+            const result = outcome.result;
+            writeResult(args.command, args.io, result, formatTerminalLabHuman);
+            args.io.setExitCode(result.ok && automaticAnalysisSucceeded(result) ? 0 : 2);
+            if (finishedPlan !== undefined && result.ok && result.observer !== undefined) {
+                await showObserver({
+                    command: args.command,
+                    io: args.io,
+                    plan: finishedPlan,
+                    rendered: result.observer,
+                });
+            }
+        },
+    };
+}

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

@@ -0,0 +1,9 @@
+import { Command } from "commander";
+import { type CliIo, type LabCommandOptions } from "../io.js";
+export declare function runLabCommand(args: {
+    command: Command;
+    io: CliIo;
+    lab: string;
+    mode: "run" | "watch";
+    options: LabCommandOptions;
+}): Promise<void>;

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

@@ -0,0 +1,166 @@
+import { automaticAnalysisBudget, formatAutomaticAnalysisBudget, } from "../../analysis/automatic-config.js";
+import { resolve } from "node:path";
+import { Command } from "commander";
+import { deriveStudyFacts } from "../telemetry.js";
+import { resolveLabManifest } from "../../lab/discover.js";
+import { resolveLabDryRun } from "../../lab/plan.js";
+import { routeOf } from "../../lab/plan.js";
+import { computerUseRouteRun } from "./lab-route-computer-use.js";
+import { runRoute } from "./lab-route-run.js";
+import { scriptedRouteRun } from "./lab-route-scripted.js";
+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 { watchExposeRequested } from "../observer-follow.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);
+    if (!resolved.ok) {
+        writeResult(args.command, args.io, resolved, formatLabResolveFailureHuman);
+        args.io.setExitCode(2);
+        return;
+    }
+    // Surface forward-declared-field + .yml warnings on run/watch too, not only on inspect.
+    // Otherwise a setting that does nothing is silently swallowed on the path users actually run.
+    for (const warning of resolved.warnings) {
+        args.io.writeErr(`warning: ${warning}\n`);
+    }
+    const config = resolved.config;
+    // The run's identity (#455): which manifest, where it lives, and whether it is committed, a
+    // local overlay, or an explicit path. Resolved once here — the only place that knows all three —
+    // and carried into the run's status record and bundle so the filesystem can answer "which lab
+    // produced this run" without the old `persona.source = "lab:<id>"` string convention.
+    const lab = { id: config.id, path: resolved.path, origin: resolved.origin };
+    // 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 }));
+    const route = routeOf(config);
+    if (route !== "computer-use" && labRerunFlagsRequested(args.options)) {
+        writeUnsupportedRerunFlagsResult(args, route);
+        return;
+    }
+    // Exposure serves a live desktop, which only the computer-use route produces. Refuse it on any
+    // other route rather than silently ignoring it.
+    if (route !== "computer-use" && watchExposeRequested(args.options)) {
+        const result = {
+            schema: "humanish.run-result.v1",
+            ok: false,
+            cwd: resolve(args.options.cwd),
+            warnings: [],
+            error: {
+                code: "HUMANISH_WATCH_OPTION_CONFLICT",
+                message: `--expose/--tunnel/--oauth stream a live desktop and apply only to computer-use labs; this lab resolved to the ${route} route.`,
+            },
+        };
+        writeResult(args.command, args.io, result, formatRunHuman);
+        args.io.setExitCode(2);
+        return;
+    }
+    // A live run is never share_ready, so watch --safe admits nothing. The computer-use route
+    // refuses it through validateExposure; refuse it here for the others.
+    if (route !== "computer-use" && args.options.safe === true) {
+        const result = {
+            schema: "humanish.run-result.v1",
+            ok: false,
+            cwd: resolve(args.options.cwd),
+            warnings: [],
+            error: {
+                code: "HUMANISH_WATCH_SAFE_NOT_APPLICABLE",
+                message: WATCH_SAFE_NOT_APPLICABLE_MESSAGE,
+            },
+        };
+        writeResult(args.command, args.io, result, formatRunHuman);
+        args.io.setExitCode(2);
+        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.
+    if (resolveLabDryRun(config, args.options.dryRun, true) === false) {
+        await discoverCliKeys({ io: args.io, cwd: args.options.cwd });
+    }
+    // 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)
+        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 };
+    });
+}
+/** The route's CLI setup. Undefined when the setup has already written its own result. */
+function routeRunFor(route, args) {
+    switch (route) {
+        case "preview":
+            return previewRouteRun(args);
+        case "computer-use":
+            return computerUseRouteRun(args);
+        case "scripted":
+            return scriptedRouteRun(args);
+        case "terminal":
+            return terminalRouteRun(args);
+        case "shared-world":
+            return sharedWorldRouteRun(args);
+        default:
+            // Compile-time exhaustiveness: a future route must be handled here, not silently no-op.
+            throw new Error(`Unhandled lab route: ${String(route)}`);
+    }
+}
+function labRerunFlagsRequested(options) {
+    return options.rerunFailedFrom !== undefined || options.lanes !== undefined;
+}
+function writeUnsupportedRerunFlagsResult(args, route) {
+    const result = {
+        schema: "humanish.run-result.v1",
+        ok: false,
+        cwd: resolve(args.options.cwd),
+        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.`,
+        },
+    };
+    writeResult(args.command, args.io, result, formatRunHuman);
+    args.io.setExitCode(2);
+}
+function formatLabResolveFailureHuman(result) {
+    return ([
+        `${result.error.code}: ${result.error.message}`,
+        ...result.warnings.map((warning) => `warning: ${warning}`),
+    ].join("\n") + "\n");
+}

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

@@ -0,0 +1,30 @@
+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";
+import type { LabConfig } from "../../lab/types.js";
+import type { RunResult } from "../../run/results.js";
+/** A CONFIG-DECLARED scorer that resolved + loaded fail-closed, ready to thread into a backend. */
+export interface LoadedAdapterScorer {
+    hooks: AdapterScorerModule;
+    provenance: RunScorerProvenance;
+}
+/**
+ * Resolve `review.scorer.ref` (or the `--scorer` override) to a loaded adopter scorer, fail-closed
+ * (typed error) PRE-SPEND. Precedence: CLI `--scorer` overrides the manifest; `source` records which
+ * 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.
+ */
+export declare function maybeLoadAdapterScorer(args: {
+    cwd: string;
+    config: LabConfig;
+    labProvenance?: RunLabProvenance;
+    route: LabRoute;
+    flag: string | undefined;
+}): Promise<{
+    ok: true;
+    scorer?: LoadedAdapterScorer;
+} | {
+    ok: false;
+    error: NonNullable<RunResult["error"]>;
+}>;

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

@@ -0,0 +1,17 @@
+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
+ * 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.
+ */
+export async function maybeLoadAdapterScorer(args) {
+    const ref = args.flag ?? args.config.review?.scorer?.ref;
+    if (ref === undefined)
+        return { ok: true };
+    const source = args.flag !== undefined ? "cli-flag" : "manifest";
+    const loaded = await loadAdapterScorer({ cwd: args.cwd, ref, route: args.route, source });
+    if (!loaded.ok)
+        return { ok: false, error: loaded.error };
+    return { ok: true, scorer: { hooks: loaded.hooks, provenance: loaded.provenance } };
+}

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

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+import { type CliIo } from "../io.js";
+export declare function registerLabCommands(parent: Command, io: CliIo): void;