humanish 0.17.0 → 0.18.0

package/dist/program.js

@@ -11,10 +11,12 @@ import { runInit } from "./init.js";
 import { inspectLabManifest, listLabManifests, resolveLabManifest } from "./labs.js";
 import { runLabPreflight } from "./lab-preflight.js";
 import { runLab, resolveLabDryRun, selectLabBackend } from "./lab-engine.js";
+import { CUA_ACTOR_LAB_SCHEMA } from "./cua-actor-lab.js";
 import { openTarget, renderObserver, serveObserver } from "./observer.js";
 import { serveObserverStatic } from "./observer-static.js";
-import { SERVE_SCHEMA, parsePublicOrigin, serveObserverLibrary } from "./observer-serve.js";
-import { ServeTunnelError, startNgrokTunnel } from "./serve-tunnel.js";
+import { SERVE_SCHEMA, serveObserverLibrary } from "./observer-serve.js";
+import { startExposedObserver, validateExposure } from "./serve-exposure.js";
+import { ServeTunnelError } from "./serve-tunnel.js";
 import { DEFAULT_OSS_REPOS, runOssLab } from "./oss-lab.js";
 import { cleanupOssMetaLabSandboxes, cleanupStaleOssMetaLabSandboxes, runOssMetaLab, startOssMetaLabLiveRefresh } from "./oss-meta-lab.js";
 import { cleanupRun, doctor, listRuns, readReview, runDryRun, verifyRun } from "./run.js";
@@ -487,6 +489,14 @@ function registerWatchCommand(parent, io) {
         .addOption(new Option("--follow", "Deprecated; human output follows by default.").hideHelp())
         .option("--detach", "Render/open once and exit without attached watch server.")
         .option("--port <port>", "Local observer server port when following.", "0")
+        .option("--expose", "CUA lab only: expose the live run through an authenticated edge so you can watch from a phone. Requires edge auth.")
+        .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 (Cloudflare Access/Tailscale/manual). Binds loopback and trusts your edge. Requires --expose.")
+        .option("--safe", "Not applicable to watch: a live run is never share_ready, so --safe (a `serve` library filter) is rejected here. Restrict viewers with edge auth (--allow-email/--allow-domain).")
         .option("--json", JSON_OPTION_DESCRIPTION)
         .addHelpText("after", [
         "",
@@ -495,6 +505,9 @@ function registerWatchCommand(parent, io) {
         "  humanish watch first-run",
         "  humanish watch --lab .humanish/labs/local.yaml",
         "",
+        "Watch a live CUA run from your phone (tunnel-edge auth):",
+        "  humanish watch my-cua-lab --expose --tunnel ngrok --oauth google --allow-email you@example.com",
+        "",
         "Agent/CI path:",
         "  humanish watch --json --no-open",
         "",
@@ -561,11 +574,38 @@ function registerWatchCommand(parent, io) {
                     repo: options.repo,
                     ...(options.repos === undefined ? {} : { repos: options.repos }),
                     ...(options.runId === undefined ? {} : { runId: options.runId }),
-                    ...(options.sims === undefined ? {} : { sims: options.sims })
+                    ...(options.sims === undefined ? {} : { sims: options.sims }),
+                    ...(options.expose === undefined ? {} : { expose: options.expose }),
+                    ...(options.tunnel === undefined ? {} : { tunnel: options.tunnel }),
+                    ...(options.tunnelDomain === undefined ? {} : { tunnelDomain: options.tunnelDomain }),
+                    ...(options.oauth === undefined ? {} : { oauth: options.oauth }),
+                    allowEmail: options.allowEmail,
+                    allowDomain: options.allowDomain,
+                    ...(options.publicUrl === undefined ? {} : { publicUrl: options.publicUrl }),
+                    ...(options.safe === undefined ? {} : { safe: options.safe }),
+                    ...(options.json === undefined ? {} : { json: options.json })
                 }
             });
             return;
         }
+        // Exposure is only meaningful for a live CUA lab run (it serves the live desktop). The
+        // non-lab watch path (existing evidence, or a fresh synthetic run) has no live desktop to
+        // stream, so exposure flags there are refused rather than silently ignored — use `serve`.
+        if (watchExposeRequested(options)) {
+            const result = {
+                schema: "humanish.run-result.v1",
+                ok: false,
+                cwd: options.cwd,
+                warnings: [],
+                error: {
+                    code: "HUMANISH_WATCH_OPTION_CONFLICT",
+                    message: "--expose/--tunnel/--oauth apply only to a live CUA lab run; to expose finished evidence use `humanish serve --expose`."
+                }
+            };
+            writeResult(command, io, result, formatRunHuman);
+            io.setExitCode(2);
+            return;
+        }
         const runOptionSource = typeof command.getOptionValueSource === "function"
             ? command.getOptionValueSource("run")
             : undefined;
@@ -794,18 +834,19 @@ async function serveObserveUntilSignal(io, server, options) {
 function registerServeCommand(parent, io) {
     parent
         .command("serve")
-        .description("Serve the local run library over loopback http, with optional capability-link exposure.")
-        .summary("Serve the run library; optional capability-link exposure.")
+        .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: enables the capability-link auth gate on every request and prints the secret link once. Requires --tunnel or --public-url.")
-        .addOption(new Option("--auth <mode>", "Auth mode under --expose: capability link, or none (requires --safe).").choices(["link", "none"]).default("link"))
-        .option("--ttl <minutes>", "Capability session lifetime in minutes under --expose.", "720")
-        .addOption(new Option("--tunnel <provider>", "Spawn the OPTIONAL external tunnel binary against the loopback port.").choices(["ngrok"]))
-        .option("--tunnel-domain <domain>", "Reserved domain passed to ngrok as --url (e.g. observer.example.dev). Requires --tunnel.")
-        .option("--public-url <origin>", "Declared public origin when you run your own tunnel/proxy (e.g. https://observer.example.dev). Requires --expose; never affects binding.")
+        .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.")
         .option("--open", "Open the library in the default browser.")
         .option("--no-open", "Serve without opening a browser.")
         .option("--json", JSON_OPTION_DESCRIPTION)
@@ -813,17 +854,18 @@ function registerServeCommand(parent, io) {
         "",
         "Happy path:",
         "  humanish serve",
-        "  humanish serve --expose --tunnel ngrok --tunnel-domain observer.example.dev",
-        "  humanish serve --safe --expose --auth none --tunnel ngrok",
+        "  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 a tunnel",
-        "forwarding to the loopback port. The capability link is minted fresh per process:",
-        "Ctrl-C revokes the link and every session. Live desktop stream URLs are never",
-        "served in any mode; remote viewers see persisted evidence (screenshots, events).",
-        "--safe composes with the capability link for defense in depth."
+        "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. humanish 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(async (options, command) => {
         const wantsMachine = wantsJson(command);
@@ -847,57 +889,29 @@ function registerServeCommand(parent, io) {
             fail("HUMANISH_INVALID_PORT", "--port must be an integer between 0 and 65535.");
             return;
         }
-        const ttlMinutes = /^\d+$/.test(options.ttl) ? Number.parseInt(options.ttl, 10) : null;
-        if (ttlMinutes === null || ttlMinutes < 1 || ttlMinutes > 10_080) {
-            fail("HUMANISH_SERVE_INVALID_TTL", "--ttl must be an integer between 1 and 10080 (minutes).");
-            return;
-        }
-        const authExplicit = command.getOptionValueSource("auth") === "cli";
-        const ttlExplicit = command.getOptionValueSource("ttl") === "cli";
-        if (authExplicit && options.expose !== true) {
-            fail("HUMANISH_SERVE_OPTION_CONFLICT", "--auth only applies with --expose.");
-            return;
-        }
-        if (ttlExplicit && options.expose !== true) {
-            fail("HUMANISH_SERVE_OPTION_CONFLICT", "--ttl only applies with --expose.");
-            return;
-        }
-        if (options.auth === "none" && options.safe !== true) {
-            fail("HUMANISH_SERVE_OPEN_REQUIRES_SAFE", "--auth none serves without a secret; that is publishing, so it requires --safe (share_ready runs only).");
-            return;
-        }
-        if (options.tunnel && options.expose !== true) {
-            fail("HUMANISH_SERVE_TUNNEL_REQUIRES_EXPOSE", "--tunnel exposes the library; declare that intent with --expose.");
-            return;
-        }
-        if (options.publicUrl !== undefined && options.expose !== true) {
-            fail("HUMANISH_SERVE_OPTION_CONFLICT", "--public-url only applies with --expose.");
-            return;
-        }
-        if (options.tunnelDomain !== undefined && !options.tunnel) {
-            fail("HUMANISH_SERVE_OPTION_CONFLICT", "--tunnel-domain requires --tunnel.");
-            return;
-        }
-        if (options.tunnel && options.publicUrl !== undefined) {
-            fail("HUMANISH_SERVE_OPTION_CONFLICT", "Use either --tunnel or --public-url as the public origin, not both.");
-            return;
-        }
-        if (options.expose === true && !options.tunnel && options.publicUrl === undefined) {
-            fail("HUMANISH_SERVE_EXPOSE_REQUIRES_ORIGIN", "--expose needs a declared public origin: pass --tunnel ngrok or --public-url <origin>. The Host allowlist stays strict in every mode.");
-            return;
-        }
-        const declaredOrigin = options.publicUrl !== undefined ? parsePublicOrigin(options.publicUrl) : null;
-        if (options.publicUrl !== undefined && !declaredOrigin) {
-            fail("HUMANISH_SERVE_OPTION_CONFLICT", "--public-url must be an http(s) origin like https://observer.example.dev.");
+        // Fail-closed exposure matrix (shared validator; tunnel-edge auth only). All guards run before
+        // any bind/spawn.
+        const exposeValidation = validateExposure("serve", {
+            expose: options.expose === true,
+            ...(options.tunnel === undefined ? {} : { tunnel: options.tunnel }),
+            ...(options.tunnelDomain === undefined ? {} : { tunnelDomain: options.tunnelDomain }),
+            ...(options.oauth === undefined ? {} : { oauth: options.oauth }),
+            allowEmails: options.allowEmail,
+            allowDomains: options.allowDomain,
+            ...(options.publicUrl === undefined ? {} : { publicUrl: options.publicUrl }),
+            safe: options.safe === true
+        });
+        if (!exposeValidation.ok) {
+            fail(exposeValidation.error.code, exposeValidation.error.message);
             return;
         }
+        const plan = exposeValidation.plan;
         const started = await serveObserverLibrary(options.cwd, {
             port,
             safe: options.safe === true,
-            expose: options.expose === true,
-            authMode: options.auth,
-            ttlMinutes,
-            ...(declaredOrigin ? { publicOrigin: declaredOrigin.origin } : {}),
+            expose: plan.exposed,
+            edgeAuthed: plan.edgeAuthed,
+            ...(plan.publicOrigin ? { publicOrigin: plan.publicOrigin.origin } : {}),
             ...(options.run ? { entryRunId: options.run } : {})
         });
         if (!started.ok) {
@@ -906,12 +920,14 @@ function registerServeCommand(parent, io) {
         }
         const server = started.server;
         let tunnel;
-        if (options.tunnel) {
+        let publicUrl;
+        const warnings = [];
+        if (plan.exposed) {
             try {
-                tunnel = await startNgrokTunnel({
-                    port: server.port,
-                    ...(options.tunnelDomain ? { domain: options.tunnelDomain } : {})
-                });
+                const exposeResult = await startExposedObserver(server, plan);
+                tunnel = exposeResult.tunnel;
+                publicUrl = exposeResult.publicUrl;
+                warnings.push(...exposeResult.warnings);
             }
             catch (error) {
                 await server.close();
@@ -923,38 +939,26 @@ function registerServeCommand(parent, io) {
                 }
                 return;
             }
-            // Declares the tunnel's https origin: extends the Host allowlist and
-            // marks minted cookies Secure (every ngrok tunnel is https).
-            server.addPublicOrigin(tunnel.url);
         }
-        const publicUrl = tunnel ? tunnel.url.replace(/\/$/, "") : declaredOrigin?.origin;
-        const capabilityUrl = server.capabilityToken
-            ? `${server.url.replace(/\/$/, "")}/_humanish/auth/${server.capabilityToken}`
-            : undefined;
-        const publicCapabilityUrl = server.capabilityToken && publicUrl
-            ? `${publicUrl}/_humanish/auth/${server.capabilityToken}`
-            : undefined;
-        const warnings = [];
-        if (server.mode === "capability-link" && options.safe !== true) {
-            warnings.push(`capability link grants read access to all ${server.runsListed} local runs, including any not verified share_ready (local_only raw screenshots, blocked bundles); anyone holding the link can view them until this process exits; restart rotates the link; add --safe to restrict to share_ready`);
+        if (server.mode === "exposed" && options.safe !== true) {
+            warnings.push(`edge-authed exposure grants read access to all ${server.runsListed} local runs, including any not verified share_ready (local_only raw screenshots, blocked bundles); anyone who clears the edge auth can view them; add --safe to restrict to share_ready`);
         }
-        if (server.mode === "capability-link" && options.safe === true) {
-            warnings.push(`capability link grants read access to ${server.shareReadyCount ?? 0} share_ready runs; non-share_ready runs are absent even to link holders`);
+        if (server.mode === "exposed" && options.safe === true) {
+            warnings.push(`edge-authed exposure grants read access to ${server.shareReadyCount ?? 0} share_ready runs; non-share_ready runs are absent even behind the edge`);
         }
         if (server.mode === "share-safe-open") {
-            warnings.push(`serving ${server.shareReadyCount ?? 0} share_ready runs to anyone who can reach ${publicUrl}; non-share_ready runs are absent and their URLs 404`);
+            warnings.push(`serving ${server.shareReadyCount ?? 0} share_ready runs to anyone who can reach ${publicUrl ?? server.url}; non-share_ready runs are absent and their URLs 404`);
         }
-        warnings.push("live desktop stream URLs are never served; remote viewers see persisted evidence (screenshots, events, terminal tails) only");
-        // Auto-open is suppressed under --expose so the capability token is not
-        // placed into a local opener process's argv (readable via `ps`) without
-        // the operator asking — the exposure target is a remote device anyway.
-        // Explicit --open still honors intent and opens the capability URL.
+        warnings.push("live desktop stream URLs are never served here; remote viewers see persisted evidence (screenshots, events, terminal tails) only");
+        // 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
+        // intent and opens the loopback library.
         const shouldOpen = options.open === false
             ? false
             : options.open === true
                 ? true
-                : !wantsMachine && process.stdout.isTTY === true && options.expose !== true;
-        const openResult = shouldOpen ? openTarget(capabilityUrl ?? server.url) : { opened: false };
+                : !wantsMachine && process.stdout.isTTY === true && plan.exposed !== true;
+        const openResult = shouldOpen ? openTarget(server.url) : { opened: false };
         if (openResult.warning) {
             warnings.push(openResult.warning);
         }
@@ -967,11 +971,9 @@ function registerServeCommand(parent, io) {
             host: "127.0.0.1",
             port: server.port,
             url: server.url,
-            ...(capabilityUrl ? { capabilityUrl } : {}),
             ...(publicUrl ? { publicUrl } : {}),
-            ...(publicCapabilityUrl ? { publicCapabilityUrl } : {}),
             ...(tunnel ? { tunnel: { provider: "ngrok", url: tunnel.url } } : {}),
-            ...(server.mode === "capability-link" ? { ttlMinutes } : {}),
+            ...(plan.oauth ? { oauth: { provider: plan.oauth.provider, allowEmails: plan.oauth.allowEmails, allowDomains: plan.oauth.allowDomains } } : {}),
             runsListed: server.runsListed,
             ...(server.shareReadyCount !== undefined ? { shareReadyCount: server.shareReadyCount } : {}),
             ...(server.entryRunId ? { entryRunId: server.entryRunId } : {}),
@@ -1007,20 +1009,16 @@ function formatServeHuman(result) {
         `library: ${result.url ?? ""}`,
         `runs: ${result.runsListed}`
     ];
-    if (result.capabilityUrl) {
-        lines.push("SECRET LINK (anyone holding it can read the library until Ctrl-C):");
-        lines.push(`  ${result.capabilityUrl}`);
-        if (result.publicCapabilityUrl) {
-            lines.push(`  ${result.publicCapabilityUrl}`);
-        }
-        lines.push("revocation: Ctrl-C revokes the link and all sessions; restarting mints a new link");
-    }
-    else if (result.publicUrl) {
+    if (result.publicUrl) {
         lines.push(`public: ${result.publicUrl}`);
     }
     if (result.tunnel) {
         lines.push(`tunnel: ${result.tunnel.provider} ${result.tunnel.url}`);
     }
+    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)"}`);
+    }
     if (result.entryRunId) {
         lines.push(`entry: ${result.entryRunId}`);
     }
@@ -1493,6 +1491,23 @@ async function runLabCommand(args) {
         writeUnsupportedRerunFlagsResult(args, backend);
         return;
     }
+    // Exposure serves a live desktop, which only the computer-use backend produces. Refuse it on any
+    // other backend rather than silently ignoring it.
+    if (backend !== "cua" && 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 ${backend}.`
+            }
+        };
+        writeResult(args.command, args.io, result, formatRunHuman);
+        args.io.setExitCode(2);
+        return;
+    }
     switch (backend) {
         case "synthetic":
             await runSyntheticBackend({ ...args, config });
@@ -1621,30 +1636,162 @@ async function runCuaBackend(args) {
         args.io.setExitCode(2);
         return;
     }
-    const outcome = await runLab(args.config, {
-        cwd: args.options.cwd,
-        // Watch mode opens the served Observer below instead of the static render.
-        open: args.mode === "watch" ? false : shouldOpen,
-        count,
-        ...(args.options.dryRun === undefined ? {} : { dryRun: args.options.dryRun }),
-        ...(args.options.runId === undefined ? {} : { runId: args.options.runId }),
-        ...(args.options.rerunFailedFrom === undefined
-            ? {}
-            : {
-                rerun: {
-                    sourceRunId: args.options.rerunFailedFrom,
-                    ...(laneIds.length === 0 ? {} : { laneIds })
-                }
-            })
+    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;
+    const failCua = (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);
+    };
+    if (port === null) {
+        failCua("HUMANISH_WATCH_OPTION_CONFLICT", "--port must be an integer between 0 and 65535.");
+        return;
+    }
+    // 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,
+        detach: args.options.detach === true,
+        json: wantsMachine
     });
+    if (!exposeValidation.ok) {
+        failCua(exposeValidation.error.code, exposeValidation.error.message);
+        return;
+    }
+    const plan = exposeValidation.plan;
+    const exposeRequested = plan.exposed;
+    let server = null;
+    let attachedObserver = null;
+    let tunnel;
+    let exposeWarnings = [];
+    let exposePublicTarget;
+    let outcome;
+    try {
+        outcome = await runLab(args.config, {
+            cwd: args.options.cwd,
+            // Watch mode opens the served Observer below (or prints the phone target under --expose)
+            // instead of the static render — preserved byte-for-byte from the pre-0.18 open policy so a
+            // non-follow watch (dry-run/--json) does not double-open. Run mode keeps the static open.
+            open: args.mode === "watch" ? false : shouldOpen,
+            count,
+            dryRun,
+            ...(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: async (observer) => {
+                        attachedObserver = observer;
+                        if (!server) {
+                            server = await serveObserver(observer, {
+                                open: shouldOpen && !exposeRequested,
+                                port,
+                                exposed: exposeRequested
+                            });
+                        }
+                        if (exposeRequested) {
+                            const activeServer = server;
+                            const exposeResult = await startExposedObserver(activeServer, plan);
+                            if (exposeResult.tunnel) {
+                                tunnel = exposeResult.tunnel;
+                            }
+                            exposeWarnings = exposeResult.warnings;
+                            const phoneTarget = exposeResult.publicUrl ?? activeServer.url;
+                            exposePublicTarget = phoneTarget;
+                            args.io.writeOut(`watch: exposed live desktop at ${phoneTarget} (edge-authed; open it on your phone)\n`);
+                            for (const warning of exposeResult.warnings) {
+                                args.io.writeErr(`warning: ${warning}\n`);
+                            }
+                        }
+                    }
+                }
+                : {}),
+            ...(args.options.runId === undefined ? {} : { runId: args.options.runId }),
+            ...(args.options.rerunFailedFrom === undefined
+                ? {}
+                : {
+                    rerun: {
+                        sourceRunId: args.options.rerunFailedFrom,
+                        ...(laneIds.length === 0 ? {} : { laneIds })
+                    }
+                })
+        });
+    }
+    catch (error) {
+        // Tear down the loopback server and any tunnel started inside onObserverReady before rethrowing
+        // (or surfacing a structured tunnel-startup failure). The sandbox is created AFTER
+        // onObserverReady returns, so a tunnel failure here cannot orphan one.
+        const earlyServer = server;
+        await earlyServer?.close().catch((cleanupError) => {
+            args.io.writeErr(`watch cleanup failed: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}\n`);
+        });
+        server = null;
+        if (tunnel) {
+            await tunnel.close().catch(() => undefined);
+            tunnel = undefined;
+        }
+        if (error instanceof ServeTunnelError) {
+            failCua(error.code, error.message);
+            return;
+        }
+        throw error;
+    }
     if (outcome.backend !== "cua") {
         throw new Error(`Expected cua backend, got ${outcome.backend}.`);
     }
     const result = outcome.result;
-    writeResult(args.command, args.io, result, formatCuaLabHuman);
+    // Serving is NOT gated on result.ok: a timed_out/failed run still comes up so the operator can
+    // inspect its evidence live (and, under --expose, from a phone). budget_reached now makes a
+    // productive open-ended watch result.ok true.
+    let output = result;
+    if (server && attachedObserver) {
+        const activeServer = server;
+        const attachedResult = result.observer?.ok ? result.observer : attachedObserver;
+        output = {
+            ...result,
+            observer: withObserverServer(attachedResult, activeServer),
+            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${tunnel ? ` via ${tunnel.url.replace(/\/$/, "")}` : ""}.`,
+                        `this live run's raw, unverified evidence (screenshots, events) is viewable by anyone who clears the edge auth at ${exposePublicTarget ?? activeServer.url}; only the run being watched is served, not your other runs`
+                    ]
+                    : []),
+                ...exposeWarnings,
+                ...(activeServer.warning ? [activeServer.warning] : [])
+            ]
+        };
+    }
+    writeResult(args.command, args.io, output, formatCuaLabHuman);
     args.io.setExitCode(result.ok ? 0 : 2);
-    // Watch mode serves the freshly rendered Observer (and opens it unless told not to).
-    if (args.mode === "watch" && result.ok && !wantsMachine) {
+    if (server && (result.observer?.ok || attachedObserver)) {
+        const activeServer = server;
+        const followResult = output.observer?.ok ? output.observer : withObserverServer(attachedObserver, activeServer);
+        await followObserver(args.io, followResult, activeServer, {
+            onStop: async () => {
+                if (tunnel) {
+                    await tunnel.close();
+                    return ["closed ngrok tunnel"];
+                }
+                return [];
+            }
+        });
+    }
+    else if (args.mode === "watch" && result.ok && !wantsMachine) {
+        // Non-follow / dry-run watch keeps today's fallback: render the finished bundle and follow it.
         await renderAndMaybeFollowObserver({
             command: args.command,
             cwd: args.options.cwd,
@@ -2541,6 +2688,31 @@ function formatOssMetaLabCleanupHuman(result) {
 function collectRepeated(value, previous) {
     return [...previous, value];
 }
+// True when any tunnel-edge exposure flag is present (not --safe, which is an orthogonal filter).
+// Used to refuse exposure on the non-lab watch path and on non-CUA backends, where there is no live
+// desktop to stream.
+function watchExposeRequested(o) {
+    return o.expose === true
+        || o.tunnel !== undefined
+        || o.tunnelDomain !== undefined
+        || o.oauth !== undefined
+        || (o.allowEmail?.length ?? 0) > 0
+        || (o.allowDomain?.length ?? 0) > 0
+        || o.publicUrl !== undefined;
+}
+// Map LabCommandOptions onto the shared exposure validator input.
+function exposureRequestFromOptions(options) {
+    return {
+        expose: options.expose === true,
+        ...(options.tunnel === undefined ? {} : { tunnel: options.tunnel }),
+        ...(options.tunnelDomain === undefined ? {} : { tunnelDomain: options.tunnelDomain }),
+        ...(options.oauth === undefined ? {} : { oauth: options.oauth }),
+        allowEmails: options.allowEmail ?? [],
+        allowDomains: options.allowDomain ?? [],
+        ...(options.publicUrl === undefined ? {} : { publicUrl: options.publicUrl }),
+        safe: options.safe === true
+    };
+}
 function formatInitHuman(result) {
     const title = result.ok
         ? `humanish init ${result.mode}`