humanish 0.105.0 → 0.106.0

package/dist/cli/commands/feedback.js

@@ -0,0 +1,138 @@
+import { Command } from "commander";
+import { draftFeedback, listFeedback, renderIssueMarkdown, renderIssueUrl, verifyFeedback, } from "../../feedback/feedback.js";
+import { candidateOption, JSON_OPTION_DESCRIPTION, wantsJson, writeResult, } from "../io.js";
+export function registerFeedbackCommands(parent, io) {
+    const feedback = parent
+        .command("feedback")
+        .description("Create public-safe feedback drafts without GitHub API mutation.")
+        .summary("Create public-safe feedback drafts, no GitHub API.");
+    feedback
+        .command("list")
+        .description("List recorded feedback candidates and any saved draft.")
+        .addHelpText("after", "\nWith no candidates, feedback draft and feedback issue can generate a run-summary follow-up. Public drafting still requires share_ready verification.\n")
+        .option("--run <id>", "Run id or latest pointer.", "latest")
+        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action((options, command) => handleFeedbackList(io, options, command));
+    feedback
+        .command("draft")
+        .description("Generate a public-safe feedback draft from verified evidence.")
+        .option("--run <id>", "Run id or latest pointer.", "latest")
+        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--analysis <id>", "Independent analysis version; use with --finding.")
+        .option("--finding <id>", "Finding within --analysis, separate from participant candidates.")
+        .option("--candidate <id>", "Which finding to draft (ids from `feedback list`); default: the first.")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action((options, command) => handleFeedbackDraft(io, options, command));
+    feedback
+        .command("verify")
+        .description("Verify the feedback draft for public issue eligibility.")
+        .option("--run <id>", "Run id or latest pointer.", "latest")
+        .option("--cwd <path>", "Target project directory.", ".")
+        .option("--analysis <id>", "Independent analysis version; use with --finding.")
+        .option("--finding <id>", "Finding within --analysis, separate from participant candidates.")
+        .option("--candidate <id>", "Which finding to verify (ids from `feedback list`); default: the first.")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action((options, command) => handleFeedbackVerify(io, options, command));
+    feedback
+        .command("issue")
+        .description("Print Markdown for a public GitHub issue. Does not mutate GitHub.")
+        .option("--run <id>", "Run id or latest pointer.", "latest")
+        .option("--cwd <path>", "Target project directory.", ".")
+        .requiredOption("--repo <owner/repo>", "Repository slug used in rendered filing instructions.")
+        .option("--format <format>", "Output format.", "markdown")
+        .option("--analysis <id>", "Independent analysis version; use with --finding.")
+        .option("--finding <id>", "Finding within --analysis, separate from participant candidates.")
+        .option("--candidate <id>", "Which finding to file (ids from `feedback list`); default: the first.")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action((options, command) => handleFeedbackIssue(io, options, command));
+    feedback
+        .command("issue-url")
+        .description("Print a prefilled public issue URL. Does not mutate GitHub.")
+        .option("--run <id>", "Run id or latest pointer.", "latest")
+        .option("--cwd <path>", "Target project directory.", ".")
+        .requiredOption("--repo <owner/repo>", "Repository slug used in the generated URL.")
+        .option("--analysis <id>", "Independent analysis version; use with --finding.")
+        .option("--finding <id>", "Finding within --analysis, separate from participant candidates.")
+        .option("--candidate <id>", "Which finding to link (ids from `feedback list`); default: the first.")
+        .option("--json", JSON_OPTION_DESCRIPTION)
+        .action((options, command) => handleFeedbackIssueUrl(io, options, command));
+}
+async function handleFeedbackList(io, options, command) {
+    const result = await listFeedback(options.cwd, options.run);
+    writeResult(command, io, result, formatFeedbackHuman);
+    io.setExitCode(result.ok ? 0 : 2);
+}
+async function handleFeedbackDraft(io, options, command) {
+    const result = await draftFeedback(options.cwd, options.run, candidateOption(options));
+    writeResult(command, io, result, formatFeedbackHuman);
+    io.setExitCode(result.ok ? 0 : 2);
+}
+async function handleFeedbackVerify(io, options, command) {
+    const result = await verifyFeedback(options.cwd, options.run, candidateOption(options));
+    writeResult(command, io, result, formatFeedbackHuman);
+    io.setExitCode(result.ok ? 0 : 2);
+}
+async function handleFeedbackIssue(io, options, command) {
+    const result = await renderIssueMarkdown(options.cwd, options.run, options.repo, candidateOption(options));
+    if (wantsJson(command)) {
+        io.writeOut(`${JSON.stringify(result, null, 2)}\n`);
+    }
+    else if (options.format !== "markdown") {
+        io.writeErr("Only --format markdown is supported.\n");
+        io.setExitCode(2);
+        return;
+    }
+    else if (result.ok && result.issueMarkdown) {
+        io.writeOut(result.issueMarkdown);
+    }
+    else {
+        io.writeErr(formatFeedbackHuman(result));
+    }
+    io.setExitCode(result.ok ? 0 : 2);
+}
+async function handleFeedbackIssueUrl(io, options, command) {
+    const result = await renderIssueUrl(options.cwd, options.run, options.repo, candidateOption(options));
+    if (wantsJson(command)) {
+        io.writeOut(`${JSON.stringify(result, null, 2)}\n`);
+    }
+    else if (result.ok && result.issueUrl) {
+        io.writeOut(`${result.issueUrl}\n`);
+    }
+    else {
+        io.writeErr(formatFeedbackHuman(result));
+    }
+    io.setExitCode(result.ok ? 0 : 2);
+}
+function formatFeedbackHuman(result) {
+    if (!result.ok) {
+        return `${result.error?.code}: ${result.error?.message}\n`;
+    }
+    const candidates = result.candidates ?? [];
+    const noCandidates = result.candidates !== undefined && candidates.length === 0;
+    return ([
+        noCandidates && result.draft === undefined
+            ? "humanish feedback: no recorded candidates"
+            : "humanish feedback ready",
+        `run: ${result.run}`,
+        ...(result.draftPath ? [`draft: ${result.draftPath}`] : []),
+        ...(result.issuePath ? [`issue: ${result.issuePath}`] : []),
+        ...(result.draft?.source_candidate_id
+            ? [`candidate: ${result.draft.source_candidate_id}`]
+            : []),
+        ...(noCandidates
+            ? [
+                "candidates: none recorded",
+                "With no candidates, feedback draft and feedback issue can generate a run-summary follow-up after share_ready verification.",
+                ...(result.draft ? [`summary: ${result.draft.summary}`] : []),
+            ]
+            : []),
+        // Every finding the run produced, so the second and third are one flag away (#609).
+        ...(candidates.length > 1 || (candidates.length === 1 && result.draft === undefined)
+            ? [
+                `candidates (${candidates.length}; choose one with --candidate <id>):`,
+                ...candidates.map((item) => `- ${item.id} [${item.failure_owner}] ${item.persona_id}: ${item.summary}`),
+            ]
+            : []),
+    ].join("\n") + "\n");
+}

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

@@ -0,0 +1,8 @@
+import type { CuaActorLabResult } from "../../routes/computer-use/types.js";
+import type { ScriptedBrowserLabResult } from "../../routes/scripted/types.js";
+import type { TerminalProductLabResult } from "../../routes/terminal/types.js";
+import type { ConcurrentSharedWorldLabResult } from "../../routes/shared-world/types.js";
+export declare function formatConcurrentSharedWorldLabHuman(result: ConcurrentSharedWorldLabResult): string;
+export declare function formatTerminalLabHuman(result: TerminalProductLabResult): string;
+export declare function formatScriptedLabHuman(result: ScriptedBrowserLabResult): string;
+export declare function formatCuaLabHuman(result: CuaActorLabResult): string;

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

@@ -0,0 +1,105 @@
+import { formatCuaDiagnostics, formatCuaStopCause } from "../../routes/computer-use/diagnostics.js";
+export function formatConcurrentSharedWorldLabHuman(result) {
+    return ([
+        `humanish lab concurrent-shared-world ${result.ok ? (result.dryRun ? "dry-run" : "live") : "failed"}`,
+        ...(result.error ? [`${result.error.code}: ${result.error.message}`] : []),
+        `run: ${result.runId}`,
+        `lab: ${result.labId}`,
+        `actor: ${result.actor}`,
+        `topology: ${result.topology}/${result.topologyMode} (${result.roleCount} persona${result.roleCount === 1 ? "" : "s"}, concurrency ${result.concurrency})`,
+        ...(result.host ? [`host: ${result.host}`] : []),
+        ...(result.subject?.commit
+            ? [`plane: ${result.subject.repo}@${result.subject.commit.slice(0, 12)}`]
+            : []),
+        ...(result.overlapProven === undefined
+            ? []
+            : [
+                `overlap: ${result.overlapProven ? "proven" : "not observed"} (this run only; no scale or adoption claim)`,
+            ]),
+        ...result.roles.map((participant) => `persona ${participant.id} (${participant.persona}): ${participant.status}${participant.session ? ` (${participant.session.completionReason})` : ""} ${participant.ok ? "ok" : "not-ok"}`),
+        ...(result.subjectSandbox
+            ? [
+                `subject sandbox: ${result.subjectSandbox.sandboxId} killed=${result.subjectSandbox.killed ? "yes" : "no"}`,
+            ]
+            : []),
+        ...(result.observer?.observerPath ? [`observer: ${result.observer.observerPath}`] : []),
+        ...(result.observer?.opened === undefined
+            ? []
+            : [`opened: ${result.observer.opened ? "yes" : "no"}`]),
+        ...result.warnings.map((warning) => `warning: ${warning}`),
+    ].join("\n") + "\n");
+}
+export function formatTerminalLabHuman(result) {
+    return ([
+        `humanish lab terminal ${result.ok ? (result.dryRun ? "dry-run" : "live") : "failed"}`,
+        ...(result.error ? [`${result.error.code}: ${result.error.message}`] : []),
+        `run: ${result.runId}`,
+        `lab: ${result.labId}`,
+        `actor: ${result.actor}`,
+        `product: ${result.product}`,
+        ...(result.observer?.observerPath ? [`observer: ${result.observer.observerPath}`] : []),
+        ...(result.observer?.opened === undefined
+            ? []
+            : [`opened: ${result.observer.opened ? "yes" : "no"}`]),
+        ...result.warnings.map((warning) => `warning: ${warning}`),
+    ].join("\n") + "\n");
+}
+export function formatScriptedLabHuman(result) {
+    return ([
+        `humanish lab scripted ${result.ok ? (result.dryRun ? "dry-run" : "live") : "failed"}`,
+        ...(result.error ? [`${result.error.code}: ${result.error.message}`] : []),
+        `run: ${result.runId}`,
+        `lab: ${result.labId}`,
+        `actor: ${result.actor}`,
+        `subject: ${result.appUrl}`,
+        ...(result.scenario
+            ? [
+                `scenario: ${result.scenario.id} @ ${result.scenario.sourceDigest.slice(0, 12)} (${result.scenario.source}, ${result.scenario.steps} step${result.scenario.steps === 1 ? "" : "s"})`,
+            ]
+            : []),
+        ...result.sessions.map((session) => `session ${session.surface}: ${session.status} (${session.completionReason}) · ${session.reason} [${session.screenshots} screenshot${session.screenshots === 1 ? "" : "s"}]`),
+        ...(result.observer?.observerPath ? [`observer: ${result.observer.observerPath}`] : []),
+        ...(result.observer?.opened === undefined
+            ? []
+            : [`opened: ${result.observer.opened ? "yes" : "no"}`]),
+        ...result.warnings.map((warning) => `warning: ${warning}`),
+    ].join("\n") + "\n");
+}
+export function formatCuaLabHuman(result) {
+    return ([
+        `humanish lab cua ${result.ok ? (result.dryRun ? "dry-run" : "live") : "failed"}`,
+        ...(result.error ? [`${result.error.code}: ${result.error.message}`] : []),
+        `run: ${result.runId}`,
+        `lab: ${result.labId}`,
+        `actor: ${result.actor}`,
+        `subject: ${result.appUrl}`,
+        ...(result.subject?.source === "clone"
+            ? [
+                `repo: ${result.subject.repo}${result.subject.commit ? `@${result.subject.commit.slice(0, 12)}` : ""}${result.subject.envNames && result.subject.envNames.length > 0 ? ` env=[${result.subject.envNames.join(", ")}]` : ""}`,
+            ]
+            : []),
+        ...(result.rerun
+            ? [`rerun: ${result.rerun.selectedLaneIds.join(", ")} from ${result.rerun.sourceRunId}`]
+            : []),
+        ...(result.diagnostics ? [`diagnostic: ${formatCuaDiagnostics(result.diagnostics)}`] : []),
+        ...((result.lanes?.length ?? 0) > 1
+            ? result.lanes.map((participant) => `participant ${participant.id}: ${participant.status}${participant.session ? ` (${participant.session.completionReason})` : ""}${participant.diagnostics ? ` · ${formatCuaDiagnostics(participant.diagnostics)}` : ""}${participant.session ? ` · ${participant.session.reason}` : ""}`)
+            : []),
+        ...(result.session && (result.lanes?.length ?? 0) <= 1
+            ? [
+                `session: ${result.session.status} (${result.session.completionReason})${result.session.stopCause ? ` · ${formatCuaStopCause(result.session.stopCause)}` : ""} · ${result.session.reason}`,
+                `screenshots: ${result.session.screenshots}`,
+            ]
+            : []),
+        ...(result.sandbox
+            ? [
+                `sandbox: ${result.sandbox.sandboxId} stream=${result.sandbox.streamUrlPresent ? "connected" : "missing"} killed=${result.sandbox.killed ? "yes" : "no"}`,
+            ]
+            : []),
+        ...(result.observer?.observerPath ? [`observer: ${result.observer.observerPath}`] : []),
+        ...(result.observer?.opened === undefined
+            ? []
+            : [`opened: ${result.observer.opened ? "yes" : "no"}`]),
+        ...result.warnings.map((warning) => `warning: ${warning}`),
+    ].join("\n") + "\n");
+}

package/dist/cli/commands/lab-route-computer-use.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 ComputerUseRouteArgs {
+    command: Command;
+    io: CliIo;
+    config: LabConfig;
+    labProvenance?: RunLabProvenance;
+    mode: "run" | "watch";
+    options: LabCommandOptions;
+}
+/**
+ * The computer-use route's CLI setup: its settings, the watch and exposure plan, the runLab options
+ * with the live Observer hook, and how it presents the outcome or a run error. Undefined when
+ * setup has already written its own result.
+ */
+export declare function computerUseRouteRun(args: ComputerUseRouteArgs): RouteRun | undefined;
+export {};

package/dist/cli/commands/lab-route-computer-use.js

@@ -0,0 +1,251 @@
+import { automaticAnalysisSucceeded } from "../../analysis/automatic-completion.js";
+import { Command } from "commander";
+import {} from "../../run-lab.js";
+import { resolveLabDryRun } from "../../lab/plan.js";
+import { CUA_ACTOR_LAB_SCHEMA } from "../../routes/computer-use/types.js";
+import { serveObserver } from "../../observer/render.js";
+import { startExposedObserver, validateExposure } from "../../observer/exposure.js";
+import { ServeTunnelError } from "../../observer/tunnel.js";
+import { cliAnalysisOptions } from "./analysis-signals.js";
+import { parseLabCount, parseParticipantIds, parseObserverPort, wantsJson, writeResult, } from "../io.js";
+import { exposureRequestFromOptions, followObserver, planObserver, showObserver, staticObserverOpen, withObserverServer, } from "../observer-follow.js";
+import { formatCuaLabHuman } from "./lab-format.js";
+import { resolveRouteShouldOpen } from "./lab-route-open.js";
+/**
+ * The computer-use route's CLI setup: its settings, the watch and exposure plan, the runLab options
+ * with the live Observer hook, and how it presents the outcome or a run error. Undefined when
+ * setup has already written its own result.
+ */
+export function computerUseRouteRun(args) {
+    const settings = resolveCuaSettings(args);
+    if (settings === undefined)
+        return undefined;
+    const prepared = prepareCuaWatch(args, settings);
+    if (prepared === undefined)
+        return undefined;
+    const live = {
+        server: null,
+        observer: null,
+        tunnel: undefined,
+        exposeWarnings: [],
+        publicTarget: undefined,
+    };
+    return {
+        options: cuaRunOptions(args, settings, prepared, live),
+        onRunError: (error) => closeLiveAfterRunError(args, settings, live, error),
+        present: async (outcome) => {
+            if (outcome.route !== "computer-use") {
+                throw new Error(`Expected the computer-use route, got ${outcome.route}.`);
+            }
+            await reportCuaRun(args, prepared, outcome.result, live);
+        },
+    };
+}
+function refuseCua(args, dryRun, code, message) {
+    const result = {
+        schema: CUA_ACTOR_LAB_SCHEMA,
+        ok: false,
+        cwd: args.options.cwd,
+        labId: args.config.id,
+        actor: args.config.actors[0]?.type ?? "",
+        appUrl: "",
+        dryRun,
+        runId: args.options.runId ?? "not-created",
+        warnings: [],
+        error: { code, message },
+    };
+    writeResult(args.command, args.io, result, formatCuaLabHuman);
+    args.io.setExitCode(2);
+}
+/** Parses the options, or writes the refusal and returns undefined. */
+function resolveCuaSettings(args) {
+    const wantsMachine = wantsJson(args.command);
+    const shouldOpen = resolveRouteShouldOpen({
+        optionOpen: args.options.open,
+        defaultsOpen: args.config.defaults?.open,
+        mode: args.mode,
+        wantsMachine,
+    });
+    const participantIds = parseParticipantIds(args.options.lanes);
+    if (participantIds.length > 0 && !args.options.rerunFailedFrom) {
+        args.io.writeErr("error: --lanes requires --rerun-failed-from.\n");
+        args.io.setExitCode(2);
+        return undefined;
+    }
+    const count = parseLabCount(args.options.count ?? args.options.sims, args.config.actors[0]?.count ?? 1);
+    if (count === null) {
+        args.io.writeErr("error: --count/--sims must be a positive integer.\n");
+        args.io.setExitCode(2);
+        return undefined;
+    }
+    const dryRun = resolveLabDryRun(args.config, args.options.dryRun, true) ?? true;
+    const port = parseObserverPort(args.options.port ?? "0");
+    const wantsFollow = args.mode === "watch" && !wantsMachine && args.options.detach !== true && dryRun !== true;
+    if (port === null) {
+        refuseCua(args, dryRun, "HUMANISH_WATCH_OPTION_CONFLICT", "--port must be an integer between 0 and 65535.");
+        return undefined;
+    }
+    return { wantsMachine, shouldOpen, participantIds, count, dryRun, port, wantsFollow };
+}
+/** Validates exposure and plans the finished-run Observer, or returns undefined after refusing. */
+function prepareCuaWatch(args, settings) {
+    // Validate exposure up front (fail-closed matrix), before any run/spend. A live CUA watch is the
+    // one surface that serves runtime E2B stream URLs, so it MUST sit behind edge auth.
+    const exposeValidation = validateExposure("watch", exposureRequestFromOptions(args.options), {
+        dryRun: settings.dryRun,
+        detach: args.options.detach === true,
+        json: settings.wantsMachine,
+    });
+    if (!exposeValidation.ok) {
+        refuseCua(args, settings.dryRun, exposeValidation.error.code, exposeValidation.error.message);
+        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 = args.mode === "watch" && !settings.wantsMachine && !settings.wantsFollow
+        ? planObserver({
+            command: args.command,
+            cwd: args.options.cwd,
+            io: args.io,
+            port: args.options.port ?? "0",
+            open: settings.shouldOpen,
+            ...(args.options.detach === undefined ? {} : { detach: args.options.detach }),
+        })
+        : undefined;
+    if (finishedPlan === null)
+        return undefined;
+    return { exposure: exposeValidation.plan, finishedPlan };
+}
+/** The runLab options for this invocation, with the live Observer hook for a followed watch. */
+function cuaRunOptions(args, settings, prepared, live) {
+    const { finishedPlan } = prepared;
+    return {
+        ...cliAnalysisOptions(args.io),
+        cwd: args.options.cwd,
+        ...(args.labProvenance === undefined ? {} : { lab: args.labProvenance }),
+        // A followed watch opens the served Observer (or prints the phone target under --expose), so
+        // its static render never opens. A non-follow watch opens what its plan says, once. Run mode
+        // keeps the static open.
+        open: args.mode === "watch"
+            ? finishedPlan === undefined
+                ? false
+                : staticObserverOpen(finishedPlan)
+            : settings.shouldOpen,
+        count: settings.count,
+        dryRun: settings.dryRun,
+        ...(settings.wantsFollow
+            ? {
+                // Fires INSIDE runLab, before the actor loop and before sandbox creation, so a
+                // tunnel-auth failure aborts before any spend and leaves no orphaned sandbox.
+                onObserverReady: (observer) => attachLiveObserver(args.io, settings, prepared.exposure, live, observer),
+            }
+            : {}),
+        ...(args.options.runId === undefined ? {} : { runId: args.options.runId }),
+        ...(args.options.rerunFailedFrom === undefined
+            ? {}
+            : {
+                rerun: {
+                    sourceRunId: args.options.rerunFailedFrom,
+                    ...(settings.participantIds.length === 0
+                        ? {}
+                        : { participantIds: settings.participantIds }),
+                },
+            }),
+    };
+}
+/**
+ * Tears down the loopback server and any tunnel started inside onObserverReady, then reports a
+ * tunnel startup failure or rethrows. The sandbox is created after onObserverReady returns, so a
+ * tunnel failure cannot orphan one.
+ */
+async function closeLiveAfterRunError(args, settings, live, error) {
+    await live.server?.close().catch((cleanupError) => {
+        args.io.writeErr(`watch cleanup failed: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}\n`);
+    });
+    live.server = null;
+    if (live.tunnel) {
+        await live.tunnel.close().catch(() => undefined);
+        live.tunnel = undefined;
+    }
+    if (error instanceof ServeTunnelError) {
+        refuseCua(args, settings.dryRun, error.code, error.message);
+        return;
+    }
+    throw error;
+}
+/** Serves the live Observer and, under --expose, puts the planned edge in front of it. */
+async function attachLiveObserver(io, settings, exposure, live, observer) {
+    live.observer = observer;
+    if (!live.server) {
+        live.server = await serveObserver(observer, {
+            open: settings.shouldOpen && !exposure.exposed,
+            port: settings.port,
+            exposed: exposure.exposed,
+        });
+    }
+    if (exposure.exposed) {
+        const activeServer = live.server;
+        const exposeResult = await startExposedObserver(activeServer, exposure);
+        if (exposeResult.tunnel) {
+            live.tunnel = exposeResult.tunnel;
+        }
+        live.exposeWarnings = exposeResult.warnings;
+        const phoneTarget = exposeResult.publicUrl ?? activeServer.url;
+        live.publicTarget = phoneTarget;
+        io.writeOut(`watch: exposed live desktop at ${phoneTarget} (edge-authed; open it on your phone)\n`);
+        for (const warning of exposeResult.warnings) {
+            io.writeErr(`warning: ${warning}\n`);
+        }
+    }
+}
+/** Writes the result, then follows the live server or shows the finished run's Observer. */
+async function reportCuaRun(args, prepared, result, live) {
+    const { server, observer: attachedObserver } = live;
+    const exposeRequested = prepared.exposure.exposed;
+    // Serving is NOT gated on result.ok: a timed_out, incomplete or failed run still comes up so the
+    // operator can inspect its evidence live (and, under --expose, from a phone).
+    let output = result;
+    if (server && attachedObserver) {
+        const attachedResult = result.observer?.ok ? result.observer : attachedObserver;
+        output = {
+            ...result,
+            observer: withObserverServer(attachedResult, server),
+            warnings: [
+                ...result.warnings,
+                "Live CUA server is polling observer-data.json with no-store caching.",
+                ...(exposeRequested
+                    ? [
+                        `Exposed live desktop stream URLs to an edge-authenticated remote viewer${live.tunnel ? ` via ${live.tunnel.url.replace(/\/$/, "")}` : ""}.`,
+                        `this live run's raw, unverified evidence (screenshots, events) is viewable by anyone who clears the edge auth at ${live.publicTarget ?? server.url}; only the run being watched is served, not your other runs`,
+                    ]
+                    : []),
+                ...live.exposeWarnings,
+                ...(server.warning ? [server.warning] : []),
+            ],
+        };
+    }
+    writeResult(args.command, args.io, output, formatCuaLabHuman);
+    args.io.setExitCode(result.ok && automaticAnalysisSucceeded(result) ? 0 : 2);
+    if (server && (result.observer?.ok || attachedObserver)) {
+        const followResult = output.observer?.ok
+            ? output.observer
+            : withObserverServer(attachedObserver, server);
+        await followObserver(args.io, followResult, server, {
+            onStop: async () => {
+                if (live.tunnel) {
+                    await live.tunnel.close();
+                    return ["closed ngrok tunnel"];
+                }
+                return [];
+            },
+        });
+    }
+    else if (prepared.finishedPlan !== undefined && result.ok && result.observer !== undefined) {
+        await showObserver({
+            command: args.command,
+            io: args.io,
+            plan: prepared.finishedPlan,
+            rendered: result.observer,
+        });
+    }
+}

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

@@ -0,0 +1,27 @@
+import { Command } from "commander";
+import type { CliIo, LabCommandOptions } from "../io.js";
+import { type ObserverPlan } from "../observer-follow.js";
+/**
+ * Default browser-open policy for a lab route's run. Mirrors the observe/watch gate:
+ * an explicit --open/--no-open wins; --json (machine mode) never auto-opens; otherwise a
+ * lab-config `defaults.open` wins, and the final fallback opens only for an interactive
+ * `watch` on a real TTY. Extracted so every route's CLI setup shares one gate (and one test).
+ */
+export declare function resolveRouteShouldOpen(args: {
+    optionOpen: boolean | undefined;
+    defaultsOpen: boolean | undefined;
+    mode: string;
+    wantsMachine: boolean;
+}): boolean;
+/**
+ * The Observer plan of a watch that shows the route's final render: undefined outside watch or in
+ * machine mode, null after an invalid --port was reported.
+ */
+export declare function watchFinishedPlan(args: {
+    command: Command;
+    io: CliIo;
+    mode: "run" | "watch";
+    options: LabCommandOptions;
+}, wantsMachine: boolean, shouldOpen: boolean): ObserverPlan | null | undefined;
+/** The route's static render opens only when nothing else will open the Observer. */
+export declare function observerOpen(mode: "run" | "watch", finishedPlan: ObserverPlan | undefined, shouldOpen: boolean): boolean;

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

@@ -0,0 +1,37 @@
+import { Command } from "commander";
+import { planObserver, staticObserverOpen } from "../observer-follow.js";
+/**
+ * Default browser-open policy for a lab route's run. Mirrors the observe/watch gate:
+ * an explicit --open/--no-open wins; --json (machine mode) never auto-opens; otherwise a
+ * lab-config `defaults.open` wins, and the final fallback opens only for an interactive
+ * `watch` on a real TTY. Extracted so every route's CLI setup shares one gate (and one test).
+ */
+export function resolveRouteShouldOpen(args) {
+    if (args.optionOpen === false)
+        return false;
+    if (args.wantsMachine)
+        return args.optionOpen === true;
+    return (args.optionOpen ?? args.defaultsOpen ?? (process.stdout.isTTY === true && args.mode === "watch"));
+}
+/**
+ * The Observer plan of a watch that shows the route's final render: undefined outside watch or in
+ * machine mode, null after an invalid --port was reported.
+ */
+export function watchFinishedPlan(args, wantsMachine, shouldOpen) {
+    if (args.mode !== "watch" || wantsMachine)
+        return undefined;
+    return planObserver({
+        command: args.command,
+        cwd: args.options.cwd,
+        io: args.io,
+        port: args.options.port ?? "0",
+        open: shouldOpen,
+        ...(args.options.detach === undefined ? {} : { detach: args.options.detach }),
+    });
+}
+/** The route's static render opens only when nothing else will open the Observer. */
+export function observerOpen(mode, finishedPlan, shouldOpen) {
+    if (mode === "run")
+        return shouldOpen;
+    return finishedPlan === undefined ? false : staticObserverOpen(finishedPlan);
+}

package/dist/cli/commands/lab-route-preview.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 PreviewRouteArgs {
+    command: Command;
+    io: CliIo;
+    lab: string;
+    config: LabConfig;
+    labProvenance?: RunLabProvenance;
+    mode: "run" | "watch";
+    options: LabCommandOptions;
+}
+/**
+ * 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 declare function previewRouteRun(args: PreviewRouteArgs): RouteRun | undefined;
+export {};