humanish 0.16.0 → 0.18.0

package/dist/serve-exposure.js

@@ -0,0 +1,129 @@
+// Shared fail-closed exposure validation + tunnel orchestration for BOTH `serve` (a library of
+// finished runs) and `watch` (one live run). Exposure auth is TUNNEL-EDGE only: humanish carries no
+// in-process auth. Exposure is admitted only behind edge auth (ngrok --oauth google, or an operator
+// --public-url they secure) OR, for serve, behind --safe (share_ready runs only). A live watch run
+// is never share_ready (raw, unverified screenshots), so watch --expose ALWAYS requires edge auth.
+//
+// This module is pure with respect to the fail-closed matrix (validateExposure) and thin over the
+// tunnel launcher (startExposedObserver), so the CLI just maps flags in and results out.
+import { parsePublicOrigin } from "./serve-http.js";
+import { startNgrokTunnel } from "./serve-tunnel.js";
+function code(surface, suffix) {
+    return `HUMANISH_${surface.toUpperCase()}_${suffix}`;
+}
+export function validateExposure(surface, request, live) {
+    const fail = (suffix, message) => ({
+        ok: false,
+        error: { code: code(surface, suffix), message }
+    });
+    // Structural guards (both surfaces), in the fail-closed order documented in the matrix. These run
+    // before any bind/spawn so a mis-configured exposure aborts before sandbox/provider spend.
+    if ((request.allowEmails.length > 0 || request.allowDomains.length > 0) && !request.oauth) {
+        return fail("ALLOW_REQUIRES_OAUTH", "--allow-email/--allow-domain configure the ngrok edge OAuth allow-list; they require --oauth google.");
+    }
+    if (request.oauth && !request.tunnel) {
+        return fail("OAUTH_REQUIRES_TUNNEL", "--oauth turns on edge OAuth on the ngrok tunnel; it requires --tunnel ngrok (a --public-url operator brings their own edge auth).");
+    }
+    if (request.tunnel && request.publicUrl !== undefined) {
+        return fail("OPTION_CONFLICT", "Use either --tunnel or --public-url as the public origin, not both.");
+    }
+    if (request.tunnelDomain !== undefined && !request.tunnel) {
+        return fail("OPTION_CONFLICT", "--tunnel-domain requires --tunnel.");
+    }
+    const publicOrigin = request.publicUrl !== undefined ? parsePublicOrigin(request.publicUrl) : null;
+    if (request.publicUrl !== undefined && !publicOrigin) {
+        return fail("OPTION_CONFLICT", "--public-url must be an http(s) origin like https://observer.example.com.");
+    }
+    if (!request.expose) {
+        // Exposure flags without --expose are refused (no silent wide-open). --safe is orthogonal and
+        // stays valid without --expose (a loopback share_ready filter).
+        if (request.tunnel) {
+            return fail("TUNNEL_REQUIRES_EXPOSE", "--tunnel exposes the surface; declare that intent with --expose.");
+        }
+        if (request.publicUrl !== undefined) {
+            return fail("OPTION_CONFLICT", "--public-url only applies with --expose.");
+        }
+        return {
+            ok: true,
+            plan: { exposed: false, edgeAuthed: false, mode: "loopback", safe: request.safe, warnings: [] }
+        };
+    }
+    const oauth = request.oauth
+        ? { provider: "google", allowEmails: request.allowEmails, allowDomains: request.allowDomains }
+        : undefined;
+    const edgeAuthed = Boolean(request.oauth) || Boolean(publicOrigin);
+    const warnings = [];
+    if (surface === "watch") {
+        // A live, in-progress run is never share_ready (raw screenshots, unverified), so --safe would
+        // admit nothing and expose nothing: watch --expose ALWAYS requires edge auth, and the live-follow
+        // preconditions are checked first so `--dry-run`/`--detach`/`--json` fail with the clearer reason.
+        if (live && (live.dryRun || live.detach || live.json)) {
+            return fail("EXPOSE_REQUIRES_LIVE_FOLLOW", "watch --expose streams a live desktop over an attached follow channel; it cannot combine with --dry-run, --detach, or --json.");
+        }
+        // --safe is a share_ready LIBRARY filter for `serve`; watch streams a single live run that is
+        // never share_ready, so --safe would silently do nothing here. Reject it rather than ignore it.
+        if (request.safe) {
+            return fail("SAFE_NOT_APPLICABLE", "watch streams a single live run that is never share_ready; --safe (a share_ready library filter) applies to `serve`, not `watch`. Restrict viewers with edge auth: --allow-email / --allow-domain.");
+        }
+        if (!edgeAuthed) {
+            return fail("EXPOSE_REQUIRES_EDGE_AUTH", "watch --expose serves a live run that is never share_ready, so --safe cannot gate it; require edge auth: --tunnel ngrok --oauth google, or an operator-secured --public-url.");
+        }
+    }
+    else {
+        // serve: --expose must ALWAYS resolve to a reachable public origin (a tunnel or a --public-url),
+        // even under --safe. Without one the exposed server is an unreachable loopback no-op, so fail
+        // closed before the origin-less bind. When an origin IS present, keep the edge-auth-OR-safe gate.
+        if (!request.tunnel && !publicOrigin) {
+            return fail("EXPOSE_REQUIRES_ORIGIN", "--expose needs a declared public origin: pass --tunnel ngrok or --public-url <origin>.");
+        }
+        if (!edgeAuthed && !request.safe) {
+            return fail("EXPOSE_REQUIRES_EDGE_AUTH_OR_SAFE", "--expose opens a public URL to local run bundles; require edge auth (--oauth google with --tunnel, or a --public-url you secure) OR --safe (share_ready runs only).");
+        }
+    }
+    if (request.oauth && request.allowEmails.length === 0 && request.allowDomains.length === 0) {
+        warnings.push("ngrok --oauth google with NO --allow-email/--allow-domain lets ANY Google account that reaches the URL in; add at least one allow rule to restrict who can watch.");
+    }
+    const mode = edgeAuthed ? "exposed" : "share-safe-open";
+    return {
+        ok: true,
+        plan: {
+            exposed: true,
+            edgeAuthed,
+            mode,
+            safe: request.safe,
+            ...(request.tunnel ? { tunnel: request.tunnel } : {}),
+            ...(request.tunnelDomain ? { tunnelDomain: request.tunnelDomain } : {}),
+            ...(oauth ? { oauth } : {}),
+            ...(publicOrigin ? { publicOrigin } : {}),
+            warnings
+        }
+    };
+}
+// Orchestrate the edge in front of an already-bound loopback server: spawn the ngrok tunnel (with
+// oauth/allow args) or declare the operator's --public-url, then extend the server's Host allowlist.
+// May throw a ServeTunnelError (ngrok missing/failed); callers close the loopback server on throw.
+export async function startExposedObserver(server, plan, deps = {}) {
+    const warnings = [...plan.warnings];
+    if (plan.tunnel === "ngrok") {
+        const startTunnel = deps.startTunnel ?? startNgrokTunnel;
+        const tunnel = await startTunnel({
+            port: server.port,
+            ...(plan.tunnelDomain ? { domain: plan.tunnelDomain } : {}),
+            ...(plan.oauth
+                ? {
+                    oauthProvider: plan.oauth.provider,
+                    oauthAllowEmails: plan.oauth.allowEmails,
+                    oauthAllowDomains: plan.oauth.allowDomains
+                }
+                : {})
+        });
+        server.addPublicOrigin(tunnel.url);
+        return { tunnel, publicUrl: tunnel.url.replace(/\/$/, ""), warnings };
+    }
+    if (plan.publicOrigin) {
+        server.addPublicOrigin(plan.publicOrigin.origin);
+        return { publicUrl: plan.publicOrigin.origin, warnings };
+    }
+    return { warnings };
+}
+//# sourceMappingURL=serve-exposure.js.map

package/dist/serve-exposure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve-exposure.js","sourceRoot":"","sources":["../src/serve-exposure.ts"],"names":[],"mappings":"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"}

package/dist/serve-http.d.ts

@@ -0,0 +1,8 @@
+export type ServeMode = "loopback" | "exposed" | "share-safe-open";
+export declare function buildServeSecurityHeaders(): Record<string, string>;
+export declare function hostAllowed(hostHeader: string | undefined, allowlist: ReadonlySet<string>): boolean;
+export declare function parsePublicOrigin(value: string): {
+    origin: string;
+    host: string;
+    scheme: "http" | "https";
+} | null;

package/dist/serve-http.js

@@ -0,0 +1,37 @@
+// Shared HTTP hardening primitives for the serve surfaces. Extracted here so BOTH the live
+// Observer server (src/observer.ts, exposed mode) and the run-library server
+// (src/observer-serve.ts) can enforce the identical Host allowlist + security-header posture
+// without a module cycle. This file imports nothing from the serve modules.
+export function buildServeSecurityHeaders() {
+    return {
+        "cache-control": "no-store",
+        "referrer-policy": "no-referrer",
+        "x-content-type-options": "nosniff",
+        "x-frame-options": "DENY",
+        "x-robots-tag": "noindex, nofollow"
+    };
+}
+export function hostAllowed(hostHeader, allowlist) {
+    return typeof hostHeader === "string" && allowlist.has(hostHeader.trim().toLowerCase());
+}
+export function parsePublicOrigin(value) {
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        return null;
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        return null;
+    }
+    if ((parsed.pathname !== "/" && parsed.pathname !== "") || parsed.search || parsed.hash || !parsed.host) {
+        return null;
+    }
+    return {
+        origin: parsed.origin,
+        host: parsed.host.toLowerCase(),
+        scheme: parsed.protocol === "https:" ? "https" : "http"
+    };
+}
+//# sourceMappingURL=serve-http.js.map

package/dist/serve-http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve-http.js","sourceRoot":"","sources":["../src/serve-http.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,6EAA6E;AAC7E,6FAA6F;AAC7F,4EAA4E;AAS5E,MAAM,UAAU,yBAAyB;IACvC,OAAO;QACL,eAAe,EAAE,UAAU;QAC3B,iBAAiB,EAAE,aAAa;QAChC,wBAAwB,EAAE,SAAS;QACnC,iBAAiB,EAAE,MAAM;QACzB,cAAc,EAAE,mBAAmB;KACpC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,UAA8B,EAAE,SAA8B;IACxF,OAAO,OAAO,UAAU,KAAK,QAAQ,IAAI,SAAS,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;AAC1F,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,KAAa;IAC7C,IAAI,MAAW,CAAC;IAChB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAChE,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,QAAQ,KAAK,GAAG,IAAI,MAAM,CAAC,QAAQ,KAAK,EAAE,CAAC,IAAI,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QACxG,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO;QACL,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE;QAC/B,MAAM,EAAE,MAAM,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM;KACxD,CAAC;AACJ,CAAC"}

package/dist/serve-tunnel.d.ts

@@ -0,0 +1,20 @@
+import { spawn } from "node:child_process";
+export type ServeTunnelErrorCode = "HUMANISH_SERVE_TUNNEL_NOT_FOUND" | "HUMANISH_SERVE_TUNNEL_START_FAILED";
+export declare class ServeTunnelError extends Error {
+    readonly code: ServeTunnelErrorCode;
+    constructor(code: ServeTunnelErrorCode, message: string);
+}
+export interface ServeTunnel {
+    url: string;
+    close(): Promise<void>;
+}
+export interface StartNgrokTunnelOptions {
+    port: number;
+    domain?: string;
+    oauthProvider?: "google";
+    oauthAllowEmails?: string[];
+    oauthAllowDomains?: string[];
+    timeoutMs?: number;
+    spawnImpl?: typeof spawn;
+}
+export declare function startNgrokTunnel(options: StartNgrokTunnelOptions): Promise<ServeTunnel>;

package/dist/serve-tunnel.js

@@ -0,0 +1,113 @@
+import { spawn } from "node:child_process";
+export class ServeTunnelError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "ServeTunnelError";
+        this.code = code;
+    }
+}
+export async function startNgrokTunnel(options) {
+    const spawnImpl = options.spawnImpl ?? spawn;
+    const timeoutMs = options.timeoutMs ?? 15_000;
+    const oauthArgs = options.oauthProvider
+        ? [
+            "--oauth",
+            options.oauthProvider,
+            ...(options.oauthAllowEmails ?? []).flatMap((email) => ["--oauth-allow-email", email]),
+            ...(options.oauthAllowDomains ?? []).flatMap((domain) => ["--oauth-allow-domain", domain])
+        ]
+        : [];
+    const args = [
+        "http",
+        "--log",
+        "stdout",
+        "--log-format",
+        "json",
+        ...(options.domain ? ["--url", options.domain] : []),
+        ...oauthArgs,
+        String(options.port)
+    ];
+    const child = spawnImpl("ngrok", args, { stdio: ["ignore", "pipe", "ignore"] });
+    const url = await new Promise((resolve, reject) => {
+        let settled = false;
+        let buffered = "";
+        const settle = (outcome) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timer);
+            if ("url" in outcome) {
+                resolve(outcome.url);
+            }
+            else {
+                killChild(child);
+                reject(outcome.error);
+            }
+        };
+        const timer = setTimeout(() => {
+            settle({
+                error: new ServeTunnelError("HUMANISH_SERVE_TUNNEL_START_FAILED", `ngrok did not report a started tunnel within ${timeoutMs}ms.`)
+            });
+        }, timeoutMs);
+        child.once("error", (error) => {
+            settle({
+                error: error.code === "ENOENT"
+                    ? new ServeTunnelError("HUMANISH_SERVE_TUNNEL_NOT_FOUND", "ngrok binary not found on PATH. Install ngrok, or run your own tunnel and pass --public-url <origin>.")
+                    : new ServeTunnelError("HUMANISH_SERVE_TUNNEL_START_FAILED", `ngrok failed to start: ${error.message}`)
+            });
+        });
+        child.once("exit", (code) => {
+            settle({
+                error: new ServeTunnelError("HUMANISH_SERVE_TUNNEL_START_FAILED", `ngrok exited (${code ?? "signal"}) before reporting a started tunnel.`)
+            });
+        });
+        child.stdout?.setEncoding("utf8");
+        child.stdout?.on("data", (chunk) => {
+            buffered += chunk;
+            const lines = buffered.split("\n");
+            buffered = lines.pop() ?? "";
+            for (const line of lines) {
+                let parsed;
+                try {
+                    parsed = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                if (typeof parsed === "object"
+                    && parsed !== null
+                    && parsed.msg === "started tunnel"
+                    && typeof parsed.url === "string") {
+                    settle({ url: parsed.url });
+                    return;
+                }
+            }
+        });
+    });
+    return {
+        url,
+        close: async () => {
+            await killChild(child);
+        }
+    };
+}
+function killChild(child) {
+    return new Promise((resolve) => {
+        if (child.exitCode !== null || child.signalCode !== null) {
+            resolve();
+            return;
+        }
+        child.once("exit", () => resolve());
+        // Reclamation stays scoped to the exact child this call created.
+        child.kill("SIGTERM");
+        setTimeout(() => {
+            if (child.exitCode === null && child.signalCode === null) {
+                child.kill("SIGKILL");
+            }
+            resolve();
+        }, 2_000).unref();
+    });
+}
+//# sourceMappingURL=serve-tunnel.js.map

package/dist/serve-tunnel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve-tunnel.js","sourceRoot":"","sources":["../src/serve-tunnel.ts"],"names":[],"mappings":"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"}

package/docs/architecture/actor-contract.md

@@ -111,7 +111,10 @@ export type ActorCompletionReason =
   | "turn_completed"      // harness saw an explicit done signal, no predicate
   | "gave_up"             // persona abandoned in character: friction exceeded its tolerance
   | "blocked_approval"    // an action was auto-declined and the actor could not proceed
-  | "timed_out"
+  | "timed_out"           // wall-clock deadline hit with ZERO material progress → still a FAILURE
+  | "budget_reached"      // wall-clock time budget hit AFTER productive activity (>=1 material
+                          // action) → ActorStatus "passed", a NON-FAILURE open-ended-watch
+                          // completion; distinct from goal_satisfied (no goal was claimed)
   | "actor_error"
   | "step_failed"         // a deterministic scripted step/expectation evaluated false: the
                           // SUBJECT failed the script; the harness executed faithfully
@@ -245,8 +248,31 @@ Completion semantics: `goal_satisfied` means the scenario's `expect` blocks —
 predicate — all held ("the app still affords this exact journey", nothing about user
 behavior); `step_failed` means a deterministic step or expectation evaluated false (the
 subject failed the script; the harness ran faithfully); `timed_out` is the journey wall-clock
-budget; `harness_error` is a browser that could not launch. `gave_up` and `blocked_approval`
-are unreachable — no persona patience, no approvals exist on a deterministic replay.
+budget hit with NO material progress (still a failure); `harness_error` is a browser that could
+not launch. `gave_up` and `blocked_approval` are unreachable — no persona patience, no
+approvals exist on a deterministic replay.
+
+### The time budget vs. a stuck timeout (`budget_reached`)
+
+`execution.timeoutMs` is a GENEROUS wall-clock SAFETY cap, not a goal. For an open-ended
+"watch it play" session there is no success predicate — productive play IS the outcome — so the
+computer-use loop distinguishes two ways to hit the cap:
+
+- **`budget_reached`** — the deadline was reached AFTER at least one material (non-idle) action.
+  This maps to `ActorStatus: "passed"`: a non-failure completion, `laneOutcomeOk` returns true,
+  the verdict is `pass`, and the CLI exits `0`. It stays a distinct `completionReason` (never
+  `goal_satisfied`), and the trace `reason` says it reached the budget after productive activity,
+  so a reviewer of a strictly goal-directed lab sees it hit the cap rather than reaching a goal
+  (goal-directed labs should set a tight `timeoutMs`).
+- **`timed_out`** — the deadline was reached with ZERO material actions (a hung provider, an
+  idle-only stall). This maps to `ActorStatus: "timed_out"`, `laneOutcomeOk` is false, the
+  verdict is `fail`, and the CLI exits `2`. "Made zero progress then timed out" stays a failure.
+
+`ActorStatus` intentionally gains NO new member — the honest distinction lives in
+`completionReason`/`reason` — which keeps the change from rippling through ~10 provider mappers.
+`statusForCompletion` is an exhaustive switch with no default, so a new completion reason forces a
+compile-time decision about its status. ~30 min (`1_800_000`) is a reasonable default for
+open-ended watch; the persona still stops early on `goal_satisfied`/`gave_up`/`stopWhen`.
 
 Actuation-vs-spend gate: on the scripted lab route `scenario.mode: live` is still required
 even though provider spend is $0 by mechanism. The gate's justification there is ACTUATION,

package/docs/architecture/observer.md

@@ -71,6 +71,43 @@ sanitized transcripts, traces, and verdict events are available. This gives a
 served Observer a truthful active state to poll while noninteractive local
 actors are still running.
 
+Watch is deliberately distinct from `humanish serve`. Watch serves ONE
+attached run, and the process that created it may inject runtime stream URLs
+(live hosted-desktop viewers) into the observer data it serves. Serve is the
+LIBRARY surface — every run under `.humanish/runs/` — and never serves runtime
+stream URLs in any mode; remote viewers see persisted evidence only. See
+[Serve: the run library surface](serve.md).
+
+### Exposed hardening and `watch --expose`
+
+The live `serveObserver` server binds `127.0.0.1` and, by default, is a
+permissive local-dev server (no Host allowlist, no security headers). Under its
+`exposed` option — set by `watch --expose` — it enforces the SAME
+DNS-rebinding defense as the library surface: a strict Host allowlist (loopback
+names at bind, extended by `addPublicOrigin(tunnel.url | public-url)`, `421
+Misdirected Request` otherwise) and the shared `buildServeSecurityHeaders()` on
+every response (both live in `src/serve-http.ts`, shared without a module cycle).
+Loopback (non-exposed) behavior is byte-identical to before.
+
+Exposed mode also SCOPES the surface to the attached live run (`result.run`): the
+`/_humanish/history.json` index is filtered to that one run, and `/_humanish/runs/<id>/…`
+404s byte-identically to a nonexistent run for any other id. A remote viewer who
+clears the edge auth can therefore see only the run being watched — never enumerate
+or fetch a prior run's raw, unverified evidence. Loopback keeps the full cross-run
+library (history + any run by id) exactly as before.
+
+`watch --expose` is the ONE surface that DELIBERATELY streams the live E2B
+desktop to a remote viewer: the attached watch process genuinely holds the
+runtime stream URLs (in the in-memory `WeakMap`, never persisted), and streaming
+them is the whole point of watching from a phone. It is safe only because the
+ngrok edge (Google OAuth + allow rules) or an operator `--public-url` edge
+authenticates the viewer first — `watch --expose` therefore always requires edge
+auth (a live run is never `share_ready`, so `--safe` alone cannot gate it). The
+attached server comes up DURING the run and survives a `timed_out`/`failed` run
+(serving is not gated on pass/fail), so a failed run's evidence stays inspectable
+to Ctrl-C. `serve` still never injects stream URLs. See
+[Serve: the run library surface](serve.md).
+
 ## UI Shape
 
 The Observer shell has:

package/docs/architecture/serve.md

@@ -0,0 +1,196 @@
+# Serve: the run library surface
+
+Date: 2026-08-02
+
+Status: shipped — `loopback`, `exposed` (edge-authed), and `share-safe-open`
+modes (`src/observer-serve.ts`, `src/observer-library.ts`, `src/serve-http.ts`,
+`src/serve-exposure.ts`, `src/serve-tunnel.ts`; CLI wiring in `src/program.ts`).
+The `/_humanish/api/*` control-plane namespace is reserved and answers `501`; no
+mutating route ships.
+
+Exposure auth is **tunnel-edge only**. As of 0.18.0 humanish carries NO
+in-process auth: the hand-rolled capability-link (cookie/token/TTL, the whole
+`observer-auth.ts` module and the `serve --auth link|none` flags) was removed as
+a pre-1.0 breaking change. The gate now lives entirely at the edge — ngrok
+`--oauth google` (with `--allow-email`/`--allow-domain` allow rules), or an
+operator-secured `--public-url` (Cloudflare Access, Tailscale, a reverse proxy
+you own).
+
+## What serve is
+
+`humanish serve` is the third observer surface, and the first whose subject is
+the LIBRARY rather than a run:
+
+- `humanish watch` — one ATTACHED run: the process that created the run serves
+  it and may inject runtime stream URLs for live following (see the stream-URL
+  doctrine below and `watch --expose`);
+- `humanish observe` — one FINISHED run, re-served read-only;
+- `humanish serve` — the whole local library under `.humanish/runs/`: a
+  library index, per-run Observer pages, `/_humanish/history.json` polling, and
+  optional edge-authenticated exposure beyond the machine.
+
+The server binds `127.0.0.1` unconditionally (`serveObserverLibrary`); exposure
+only ever happens through a tunnel or proxy forwarding to the loopback port.
+`--expose` never changes the bind — it declares intent and requires an
+authenticated edge (or `--safe`, see the fail-closed matrix).
+
+## Fail-closed exposure matrix
+
+One shared validator (`validateExposure` in `src/serve-exposure.ts`) governs
+both `serve` and `watch`. `--expose` must ALWAYS resolve to a reachable public
+origin (a `--tunnel` or a `--public-url`) — even under `--safe`, since an
+origin-less exposed server is an unreachable loopback no-op. With an origin
+present, exposure requires EITHER edge auth (`--oauth` on the ngrok edge, or a
+`--public-url` you secure) OR `--safe` (share_ready runs only). A tunnel with
+neither is a wide-open public URL to local bundles and is refused.
+
+| `--expose` | `--tunnel` | `--oauth` | `--public-url` | `--safe` | Outcome |
+| --- | --- | --- | --- | --- | --- |
+| — | — | — | — | any | `loopback` (no exposure) |
+| ✓ | ✓ | ✓ | — | any | OK → `exposed` (edge-authed; all runs unless `--safe`) |
+| ✓ | ✓ | — | — | ✓ | OK → `share-safe-open` (public, share_ready only) |
+| ✓ | ✓ | — | — | — | **REFUSED** `HUMANISH_SERVE_EXPOSE_REQUIRES_EDGE_AUTH_OR_SAFE` |
+| ✓ | — | — | ✓ | any | OK → `exposed` (operator-secured edge) |
+| ✓ | — | — | — | any | **REFUSED** `HUMANISH_SERVE_EXPOSE_REQUIRES_ORIGIN` (no reachable origin, even with `--safe`) |
+| ✓ | — | ✓ | — | any | **REFUSED** `HUMANISH_SERVE_OAUTH_REQUIRES_TUNNEL` |
+| ✓ | ✓ | ✓ | ✓ | any | **REFUSED** `HUMANISH_SERVE_OPTION_CONFLICT` (tunnel + public-url) |
+
+Guard order (all before any bind/spawn): `--allow-email`/`--allow-domain`
+without `--oauth` → `HUMANISH_SERVE_ALLOW_REQUIRES_OAUTH`; `--oauth` without
+`--tunnel` → `HUMANISH_SERVE_OAUTH_REQUIRES_TUNNEL`; `--tunnel`+`--public-url` →
+conflict; `--tunnel-domain` without `--tunnel` → conflict; `--expose` with no
+tunnel and no `--public-url` (even under `--safe`) →
+`HUMANISH_SERVE_EXPOSE_REQUIRES_ORIGIN`; `--expose` with an origin but without
+edge auth and without `--safe` →
+`HUMANISH_SERVE_EXPOSE_REQUIRES_EDGE_AUTH_OR_SAFE`; a tunnel/public-url without
+`--expose` → `HUMANISH_SERVE_TUNNEL_REQUIRES_EXPOSE`/conflict. `--oauth google`
+with NO allow rule is ALLOWED (any Google account authenticates) but pushes a
+prominent warning recommending at least one `--allow-email`/`--allow-domain`.
+
+The `watch` surface reuses the same validator but is stricter: a live,
+in-progress run is never `share_ready` (raw, unverified screenshots), so `--safe`
+would admit nothing. `watch --expose --safe` is therefore REFUSED outright with
+`HUMANISH_WATCH_SAFE_NOT_APPLICABLE` (rather than silently ignoring the flag);
+`watch --expose` ALWAYS requires edge auth (`--tunnel --oauth` or `--public-url`),
+and is additionally refused with `--dry-run`/`--detach`/`--json` (no live desktop
+/ no attached follow). An exposed watch serves ONLY the attached live run: its
+`/_humanish/history.json` lists just that run and every other run id 404s
+byte-identically to a nonexistent one, so a remote viewer can never enumerate or
+reach any prior run's raw evidence (loopback watch still serves the full library).
+
+## ngrok edge OAuth
+
+`startNgrokTunnel` builds `ngrok http <port> [--url <domain>] [--oauth google
+[--oauth-allow-email <addr>]… [--oauth-allow-domain <domain>]…] --log stdout
+--log-format json`. ngrok authenticates the viewer at its edge before any request
+reaches the loopback port; the stdout JSON parser skips every line except
+`msg:"started tunnel"`, so ngrok's `--oauth has been deprecated` info line (it is
+still accepted and functional on ngrok 3.39.x) is ignored automatically. The
+forward-compatible path if ngrok removes the flags is a Traffic Policy YAML — a
+documented fast-follow, out of scope for 0.18.0.
+
+## Threat model
+
+**No in-process secret to leak.** The old capability-link posture (a token in
+the URL path, an HttpOnly cookie, unfurler/history leakage, host-only cookie
+scope, TTL/revocation) is gone with the module. There is no secret in any URL
+served by humanish; the operator's edge owns authentication and session
+lifetime.
+
+**DNS rebinding and the strict Host allowlist.** A malicious page can point an
+attacker-controlled DNS name at 127.0.0.1 and read a permissive local server
+from the victim's browser. Serve keeps a strict Host allowlist in ALL modes —
+loopback names plus the declared tunnel/public origin only — and answers `421
+Misdirected Request` otherwise. Even the unauthenticated loopback default never
+trusts an arbitrary Host header. The live `serveObserver` server gains the same
+allowlist + security headers under its new `exposed` option (see observer.md), so
+`watch --expose` is not a header-less, rebinding-vulnerable surface.
+
+**Security headers.** Every response carries `cache-control: no-store`,
+`referrer-policy: no-referrer`, `x-content-type-options: nosniff`,
+`x-frame-options: DENY`, and `x-robots-tag: noindex, nofollow`
+(`buildServeSecurityHeaders`).
+
+## Mode-to-boundary mapping
+
+| Mode | Invocation | Boundary class |
+| --- | --- | --- |
+| `loopback` | `humanish serve` | Capture-side trust: readable only by whoever can already read gitignored `.humanish/` on this machine; no new boundary is crossed. |
+| `exposed` | `--expose --tunnel ngrok --oauth google …`, or `--expose --public-url <origin>` | Edge-authed exposure: only viewers who clear the edge OAuth (or the operator's own edge) reach the loopback server, which then serves everything it grants unless `--safe` composes in. The gate is the edge, not humanish. |
+| `share-safe-open` | `--expose --safe --tunnel ngrok` (no `--oauth`) | Genuine publishing behind the feedback-grade `share_ready` gate: only runs that pass verify are served — admission is re-checked when a bundle changes and re-verified within a bounded window (default 30s); everything else is absent, 404ing byte-identically to a nonexistent run (no existence oracle). |
+
+## Stream-URL doctrine
+
+Live desktop stream URLs (auth-bearing hosted-VNC links) are never served by the
+LIBRARY surface, in any mode, and the guarantee is layered:
+
+- **structural** — runtime stream URLs live in a `WeakMap` keyed by the watch
+  process's in-memory `ObserverResult` (`src/observer.ts`) and are never
+  persisted into any bundle artifact; serve is a separate process reading disk,
+  so there is nothing for it to find;
+- **defensive** — the serve handler passes an explicit empty array at its
+  `serveRunPath` call site, so a future refactor that makes injection ambient
+  would still serve zero stream URLs here;
+- **tested** — the serve suite pins a no-injection test: observer data served
+  through the library surface carries no runtime stream URLs.
+
+`watch --expose` is the ONE surface that deliberately serves runtime E2B stream
+URLs — the attached watch process genuinely holds them, and streaming the live
+desktop is the whole point of watching from a phone. It is safe only because the
+edge authenticates first, and the URLs are still never persisted (they are
+injected into the in-memory bundle, not disk). See observer.md.
+
+## The share_ready doctrine
+
+`share_ready` was designed as the bar for FEEDBACK payloads: evidence eligible
+to leave the machine inside a public issue draft. Serve's `share-safe-open` mode
+extends that same gate to arbitrary-audience BROWSING, which is a broader
+exposure of the same artifacts. The honest caveat carries over unchanged:
+`humanish verify` does not yet detect free-form PII/PHI (names, emails, medical
+identifiers — see the README's public-safety boundary and issue #108), so
+`share_ready` means the automated secret/path scan passed, not that a human would
+publish every pixel. Maintainers should treat open mode accordingly: synthetic
+data upstream, review before exposing, and treat `--safe` without edge auth as
+publishing because it is.
+
+## v2 control-plane seam contract
+
+The reserved `/_humanish/api/*` namespace answers `501` with
+`HUMANISH_SERVE_CONTROL_PLANE_DISABLED` to any request. Because the in-process
+auth gate is gone, a request that clears the edge (or a loopback caller) reaches
+the `501` directly — there is no `401`-first anymore. No run artifact can ever
+shadow the namespace. The seam is already typed: `createServeRequestHandler`
+accepts an optional `ServeControlPlane`, and v1 always passes `undefined`. Before
+any mutating route ships, the contract is:
+
+- an operator identity distinct from a viewer — but sourced from the edge/control
+  plane, not a humanish-minted cookie;
+- mutating routes require CSRF defenses appropriate to the chosen edge session;
+- the spend rule is invariant 3 applied to remote hands: a phone-initiated LIVE
+  run needs its own affirmative declaration at serve startup (an explicit opt-in
+  naming the lab and budget), never a default the viewer UI can reach.
+
+## Why not Better Auth here
+
+Better Auth is a strong TypeScript auth framework, but it is deliberately NOT
+used for this CLI serve surface: serve is an ephemeral, no-database,
+per-invocation loopback server whose only job is to hand persisted evidence to an
+already-authenticated edge. A password/session/social-login framework with a
+schema and a datastore is the wrong shape for a process that lives for the length
+of a `Ctrl-C`. The right home for Better Auth is a FUTURE hosted humanish
+dashboard / control-plane — a persistent, multi-user service with a database —
+where accounts, org membership, and durable sessions actually exist.
+
+## Future work
+
+- **Traffic Policy for ngrok.** Migrate off the deprecated `--oauth*` flags to a
+  generated Traffic Policy YAML once ngrok requires it (the `yaml` dep is already
+  available); pin the behavior in `serve-tunnel` tests first.
+- **Google Fonts inlining for per-run observer pages.** The library index is
+  self-contained; the per-run observer HTML still references remote Google Fonts,
+  which degrade gracefully offline but should be inlined (or dropped) so a served
+  run page makes no third-party requests from a viewer's browser.
+- **Shipped in 0.18.0: `watch --expose`.** Remote LIVE following of a run,
+  including its live E2B desktop stream, behind the same edge auth — the one
+  surface that deliberately serves runtime stream URLs. See observer.md and
+  live_watch_wiring.