humanish 0.104.3 → 0.106.0

package/docs/architecture/real-email-receiving.md

@@ -1,7 +1,7 @@
 # Real email receiving
 
 A supported browser study can give each participant a fresh AgentMail inbox. The
-application sends real email to that address; Humanish polls it on the host and
+application sends real email to that address; humanish polls it on the host and
 publishes a private inbox surface on that participant's desktop. The participant
 can read the original email, switch to a plain view and follow an approved link.
 
@@ -12,9 +12,11 @@ SMS and participant outbound mail are not supported.
 
 ## Setup
 
-Open `humanish tui`, press **c**, and add an AgentMail key. Hidden entry saves it
-in the existing user key store and checks authentication without creating an inbox.
-The project profile stores only the provider and environment-variable name.
+Open `humanish tui`, press **c** for Connections, and choose **Add API key** to add an
+AgentMail key. Hidden entry saves it in the existing user key store and checks
+authentication without creating an inbox; Ctrl+C cancels entry and returns to the TUI.
+The project profile, `.humanish/local/comms.yaml`, stores only the provider and
+environment-variable name.
 Environment and explicit env-file values retain precedence over saved keys.
 A rejected or unavailable authentication check does not delete the saved key.
 Authentication does not prove inbox creation/deletion permissions, quota or delivery.
@@ -53,8 +55,7 @@ Review additional origins as destinations the participant is allowed to open fro
 mail. This policy governs the inbox surface, not all later browser navigation.
 
 Supported execution is hosted computer use with app-url, clone or local-tree
-subjects, including concurrent shared-world studies. Sequential shared-world,
-local-agent, scripted, terminal, desktop-cli, in-process and local-app routes reject
+subjects, including shared-world studies. Local-agent, scripted, terminal, desktop-cli, in-process and local-app routes reject
 real receiving before allocation. Connection mode cannot declare capture options,
 recipients or borrowed mailbox IDs. A fresh address is not an existing account;
 assignments must allow signup or arranging mail to the new identity.

package/docs/architecture/restricted-codex-analysis.md

@@ -5,24 +5,44 @@ execution, with a separate conversation, process and tool authority. It can use
 the same host Codex login as a local-agent participant. Existing API analysis
 remains a separate provider.
 
-The qualified launcher profile is **Codex CLI 0.154.0, Linux x64 or Apple Silicon
-macOS, file-backed ChatGPT login, `gpt-6-astra`, low reasoning effort**. The Mac
-profile passed installed participant/analysis studies and the native dispatch
-restriction check on an M5 Max. Other versions/platforms,
-keychain-only logins and API-key Codex logins are refused before a model turn.
+The qualified launcher profile is **a qualified Codex CLI release for the host, Linux x64
+or Apple Silicon macOS, file-backed ChatGPT login, `gpt-6-astra`, low reasoning effort**.
+Qualified releases are listed per host in
+[`src/actors/codex/qualified-versions.ts`](https://github.com/danielgwilson/humanish/blob/main/src/actors/codex/qualified-versions.ts).
+Linux x64 accepts 0.154.0, 0.157.1
+([receipt](https://github.com/danielgwilson/humanish/blob/main/docs/goals/computer-use-actor/receipts/codex-cli-0.157.1-requalification-2026-09-30.md))
+0.159.2
+([receipt](https://github.com/danielgwilson/humanish/blob/main/docs/goals/computer-use-actor/receipts/codex-cli-0.159.2-qualification-2026-09-30.md))
+and 0.159.3
+([receipt](https://github.com/danielgwilson/humanish/blob/main/docs/goals/computer-use-actor/receipts/codex-cli-0.159.3-qualification-2026-10-01.md)).
+Apple Silicon accepts 0.154.0, which passed installed participant/analysis studies and the
+native dispatch restriction check on an M5 Max; later releases need the same check on a Mac.
+Hosted participants on Linux arm64 and Intel macOS keep 0.154.0 as a pre-existing admission,
+listed separately in `PREEXISTING_CODEX_CLI_ADMISSIONS`: it is what they ran before per-host
+lists existed, not a qualification, and no later release is admitted there. Other releases and
+platforms, keychain-only logins and API-key Codex logins are refused before a model turn.
+
+A release string is a compatibility check, not binary attestation. The launcher compares the
+release that `codex --version`, initialize and thread start report, then executes the same
+path; it does not pin the executable's contents, and a modified binary can report any release.
+The launcher records the detected release in the participant execution profile and in the
+analysis identity. A recorded release alone is not execution proof: prelaunch and failed
+attempts can carry the declared default, and a request's `dispatched` and `profileVerified`
+receipt shows that the launched release passed its checks. Saved bundles naming any recorded
+release stay readable.
 Readiness validates the installation and effective profile without submitting a
 model turn; it does not guarantee current quota or model access.
 
 ## Authority and request limits
 
 The host creates a private temporary Codex home and links only the existing
-`auth.json`. Humanish never reads or copies its values. The native CLI owns
+`auth.json`. humanish never reads or copies its values. The native CLI owns
 authentication and provider network traffic. Its environment excludes provider
 keys, target-app variables, alternate endpoints and operator configuration.
 The selected native binary is launched directly; npm wrappers are resolved to
 their native executable before launch.
 
-Before creating a thread, Humanish checks the effective config. Nonempty system
+Before creating a thread, humanish checks the effective config. Nonempty system
 settings, inherited instructions, MCP, plugins, hooks, alternate stores/endpoints
 and unsupported authority are rejected. The thread is ephemeral, has no runtime
 environments or workspace roots, and uses only the supplied text/images and
@@ -31,35 +51,34 @@ closed output schema. No provider/model fallback is allowed.
 This profile is **not advertised as tool-free**. The CLI retains code-mode
 descriptions, but the qualified `features.code_mode_host=false` setting rejects
 their actual dispatch. `agents.enabled=false` removes delegation; the older
-feature toggle alone did not. Humanish also refuses raw tool calls, unexpected
+feature toggle alone did not. humanish also refuses raw tool calls, unexpected
 host RPCs and asynchronous question messages before accepting any report. The
 actual notification/denial captures and provenance are in
 [`tests/fixtures/restricted-codex`](https://github.com/danielgwilson/humanish/blob/46330116726f74080fa18947c36da4fb4b333805/tests/fixtures/restricted-codex/README.md).
 
 Each analyst or readiness request owns a separate child process, temporary home
 and fresh thread. Participants share the native session implementation with a
-separate UI-tool policy: Code Mode can call one Humanish desktop tool, and each
+separate UI-tool policy: Code Mode can call one humanish desktop tool, and each
 result supplies actual input acknowledgments and the current screenshot. Local
 Firecracker and hosted E2B use this same participant implementation. Hosted
 participants preserve operator authentication and model configuration; the
 restricted analyst profile above remains unchanged.
-Codex manages context compaction. Humanish does not replace it with a rolling
+Codex manages context compaction. humanish does not replace it with a rolling
 history window or restart a failed conversation without its memory. Participant
 threads never share conversation state with each other or the analyst.
 
-An unresolved child process blocks new sessions until its exit is confirmed.
-Limits and deadlines apply to each request, including startup on the first turn.
-Thread-cumulative token usage is converted to per-turn usage before accounting.
-The qualified CLI omits compaction requests from its thread totals. A turn that
-compacts therefore retains known counts but records incomplete usage.
-Evidence is not silently downselected: at most 128 images, 20 MiB decoded image data, and 32 MiB serialized
-request data are admitted. Generated report text is limited to 2 MiB. Raw input
-notifications echo image data URLs, so their frame budget is the larger of 2 MiB
-or the admitted serialized packet plus 1 MiB; total stdout is bounded separately
-at the larger of 8 MiB or twice that frame budget plus 4 MiB. Stderr is bounded at
-2 MiB and is not retained. Notifications are limited to 65,536; aggregate
-generated assistant-text deltas are independently limited to 2 MiB, regardless
-of the input-image wire budget. The request's
+An unresolved child process blocks new sessions until its exit is confirmed. Limits and
+deadlines apply to each request, including startup on the first turn. Thread-cumulative token
+usage is converted to per-turn usage before accounting. CLI 0.154.0 omitted compaction
+requests from its thread totals, and later releases were not re-measured. A turn that compacts
+therefore retains known counts but records incomplete usage. Evidence is not silently
+downselected: at most 128 images, 20 MiB decoded image data, and 32 MiB serialized request
+data are admitted. Generated report text is limited to 2 MiB. Raw input notifications echo
+image data URLs, so their frame budget is the larger of 2 MiB (32 MiB for participant
+requests) or the admitted serialized packet plus 1 MiB; total stdout is bounded separately at
+the larger of 8 MiB or twice that frame budget plus 4 MiB. Stderr is bounded at 2 MiB and is
+not retained. Notifications are limited to 65,536; aggregate generated assistant-text deltas
+are independently limited to 2 MiB, regardless of the input-image wire budget. The request's
 deadline includes startup; individual RPCs also have a 15-second ceiling.
 
 Account analysis has unknown dollar cost and no supported generated-token cap.
@@ -75,13 +94,13 @@ Cancellation interrupts the turn, then closes the directly owned native child
 and its stdio with bounded termination/kill waits. No stored PID or process group
 is signaled after exit. This proves the direct child's lifecycle, not arbitrary
 descendant-tree reclamation; process-spawning tools are outside this profile.
-If native closure cannot be confirmed, Humanish preserves its private state and
+If native closure cannot be confirmed, humanish preserves its private state and
 blocks another session in the same process until that exact child closes.
 
 After confirmed closure, normal cleanup removes the owned auth symlink and
 temporary directory. It never deletes or overwrites the operator's original
 login. Unexpected replacement of the symlink is different: it might contain
-rotated auth state. Humanish preserves that private file with mode 0600 inside a
+rotated auth state. humanish preserves that private file with mode 0600 inside a
 0700 task home, removes other scratch/evidence, refuses the report, and returns
 `codex_cleanup_failed`. It does not copy the replacement into the original
 login, which could overwrite a newer concurrent login.
@@ -103,3 +122,170 @@ binary refresh behavior and concurrency with unrelated Codex applications are
 not established by that proof. Recovery deliberately fails closed if storage
 behaves differently. Keychain/other-platform support and whole-process-tree
 leases require their own qualification.
+
+## Admitting a Codex CLI release
+
+A release enters a host's list only with a dated receipt under
+`docs/goals/computer-use-actor/receipts/` showing all of the following, on that host:
+
+1. The release notes since the baseline were read for changes near the tool boundary.
+2. A drift check against a release already qualified on the host found no exec, connection or
+   file write the baseline did not make in the same scenarios, including live account-backed
+   launches, and the same tool inventory, denials and isolate behavior. `pnpm codex:qualify`
+   runs this check; see "The qualifier" below.
+3. One hosted participant study with the candidate first on `PATH` (for example
+   `PATH=<evidence>/npm-<version>/node_modules/.bin:$PATH pnpm humanish lab run <lab>
+--env-file <file with E2B_API_KEY only>`) reached its goal in the final capture, with a
+   verified request receipt, `humanish verify --run <id>` passing and the automatic Codex
+   analysis recording the release. Keep `OPENAI_API_KEY` out of that environment so the
+   participant stays on ChatGPT-account billing.
+
+The drift check compares a candidate with a vendor release that has already been qualified. It
+can show that an honest new release does nothing new in those scenarios; it cannot show that a
+binary built to evade it is safe. Pair that with the attestation limit above: the launcher
+admits by release string and does not pin the executable.
+
+Then commit the release in `QUALIFIED_CODEX_CLI_VERSIONS`
+(`src/actors/codex/qualified-versions.ts`) for that host, in `RECORDED_CODEX_CLI_VERSIONS`
+(`src/actors/contract.ts`) and in the Observer's copy
+(`observer/lib/actor-execution-profile.ts`). If any check fails, change no code and record
+what differs.
+
+### The qualifier
+
+`pnpm codex:qualify` produces the drift evidence step 2 above requires. Its threat model:
+it detects an honest new vendor release that, in these scenarios, executes a program, connects
+to a destination or writes a file the baseline release did not, and it fails closed when the
+harness cannot see (a failed trace, sampler read or parse). A binary built to evade it is out of
+scope. Named limits, none of which it inspects:
+
+- io_uring: a ring's operations bypass the traced syscalls. `io_uring_setup` is traced and any
+  ring fails qualification, but what a ring would do is not seen.
+- Writes on connected sockets: `write`, `writev` and `send` without an address on an already
+  connected socket are not traced. The connect is, and the sampler lists held remotes.
+- SCM_RIGHTS: descriptors passed over a unix socket are not followed.
+- DNS payloads: a query to the resolver compares by destination, not by what it asks.
+- `/proc/<pid>/` and the random suffixes of Codex's temporary names compare as patterns, so any
+  pid and any suffix match.
+- Paths inside a new mount namespace (bubblewrap's sandbox) compare as written, not as host
+  paths. Work a process does in memory and writes through inherited descriptors are unseen.
+
+It compares the candidate with a release already qualified on the host, so each step reports
+differences, not absolute facts. Evidence lands under `.humanish/codex-qualify/` (gitignored).
+It qualifies Linux hosts only: its process checks need `strace`, so on macOS, or on Linux
+without `strace` on `PATH`, it refuses before installing anything. Apple Silicon therefore stays
+at 0.154.0 until an equivalent macOS tracer exists.
+
+1. `pnpm codex:qualify <version>` installs the candidate and a baseline from npm, then runs
+   offline checks with no model or account. The baseline must be a release already qualified
+   on this host and not the candidate; by default it is the newest qualified release older
+   than the candidate, and `--baseline` must name a qualified release. Hosts with only the
+   pre-existing admission have no baseline and cannot qualify a release this way. Every
+   invocation of either binary runs under `strace -f -yy`, including `--version`, schema
+   generation and feature listing. The trace follows the process and every descendant,
+   detached ones included, and records execs, socket operations (`connect`, `bind`, `sendto`,
+   `sendmsg`, `sendmmsg`, `socketpair`), write-intent file operations with their outcome, the
+   working directory of each process (`chdir`, `fchdir`, `clone`) and `io_uring_setup`. A
+   trace line outside strace's syscall grammar fails the trace. The only other lines allowed
+   are strace's own: a process's exit or kill line, a signal delivery, a thread's execve
+   superseding its thread-group leader, and the `???` start and `= ?` resumption strace prints
+   for a call it could not decode in a thread being killed. Every traced process must reach
+   its exit or kill line, so a trace cut short fails. A call still unfinished when its process
+   ended counts as one it died in: an exec counts as run and a file operation as attempted. The
+   checks:
+   - the generated app-server schema: thread item, raw response item and server request types
+     must be unchanged; new notifications and changed launcher-facing files are listed for
+     review;
+   - `codex features list` under the analyst and participant configs: every pinned feature
+     keeps its stage and value; newly enabled features are listed for review;
+   - the preparatory commands: each one's execs, sockets and file writes must stay within the
+     baseline's same command. Schema-generator writes are skipped only when no path contains
+     `..` and the kernel resolved the open inside the schema output directory, whose files the
+     schema check above compares;
+   - five loopback-provider probes on both releases (tool inventory, 18 injected tool calls,
+     question tools, participant Code Mode lifecycle, and an isolate escape attempt). The
+     candidate may advertise no more tools than the baseline. Inside the participant isolate,
+     its own tool keys and its successful calls must stay within the baseline's, and a tool
+     both releases expose must fail with the same message, so a refusal cannot turn into an
+     input error unnoticed. Descriptions are not taken as dispatch evidence. It must return
+     the same denials, the same question outputs and the same question-event multiset (order
+     is listed for review), and the same participant lifecycle sequence.
+   - execs, per scenario and overall. Each exec compares as its exact program path and argv,
+     `argv[0]` included. The first exec must be the launched binary and is set aside. The
+     candidate's execs in each scenario must all appear among the baseline's in the same
+     scenario, so a helper cannot move from the participant to the analyst. None may carry an
+     argument the model supplied, and nothing traced may outlive the app-server. A failure
+     prints each added exec's raw and normalized argv. `execveat` resolves against the
+     descriptor path `-yy` prints; an exec path relative to an unknown directory, a truncated
+     argument, a missing `strace` or an unpaired start and result fails the check. Every
+     release so far runs the same helpers: the Code Mode host for participants, a bubblewrap
+     capability probe (`bwrap --unshare-user --unshare-net --ro-bind / / /bin/true`), and OS
+     information (`lsb_release -a` with `getopt`, `cut` and `tr`, and `getconf LONG_BIT`).
+   - sockets, per scenario. The traced connects, binds and sends must stay within the
+     baseline's, and every TCP or UDP destination must be the loopback provider, however
+     brief. A connect names the unix socket path even though the client socket itself is
+     unnamed. Sends between the two ends of a socketpair the traced tree created stay inside it
+     and are listed for review.
+   - file writes, per scenario, from the trace, which also covers paths outside the work
+     directory; and a recursive snapshot (path, type, size) of the probe's work directory
+     (`HOME`, `CODEX_HOME`, the project and `TMPDIR`) before and after each scenario. Added,
+     removed and retyped entries and traced writes must stay within the baseline's same
+     scenario; size changes are listed for review. A relative path resolves against the
+     process's tracked working directory, and one whose directory is unknown fails the trace.
+     A successful open compares on the path the kernel reports through `-yy`. A `chdir`
+     through `..` leaves the directory unknown until the kernel reports it (`AT_FDCWD<path>`),
+     and a path containing `..` without a kernel-reported path fails the trace.
+     Skipped events are judged one occurrence at a time, in order and on their outcome:
+     - an open that the kernel resolved to the `-journal`, `-wal` or `-shm` file of a known
+       database (`goals_1`, `logs_2`, `memories_1`, `queue_1`, `state_5`) it named, or an
+       unlink of one, since those come and go with checkpoint timing. A symlink, link or
+       rename that names one is always compared;
+     - operations on a file whose first successful operation was an exclusive create
+       (`O_CREAT|O_EXCL`, so it did not exist before) and whose last was a successful unlink,
+       such as SQLite's `etilqs_` temporary files. A failed unlink is not a removal, and a
+       recreation after the unlink keeps the file;
+     - a successful unlink or rmdir, with no `..`, of a path inside the run's own private
+       directory that an earlier create, rename or link in the same trace made and that was
+       not there when the command started.
+   - a `/proc` sampler, every 50 ms from spawn to close, over the app-server's descendant tree
+     and any process carrying the probe's private `CODEX_HOME`. It records TCP and UDP
+     remotes, bound unix paths and, through `ss`, the listener path behind each connected unix
+     client. Nothing may outlive the app-server, TCP and UDP may reach only the loopback
+     provider, and unix sockets must sit in the probe directory. Any read the sampler needs
+     that fails for a reason other than the process having exited (including a zombie) fails
+     qualification, for the baseline as for the candidate, and so does a `/proc` or `ss` table
+     without its header, a row that does not parse, or an empty or malformed `stat`. A task
+     that has begun to exit drops its memory map, and the kernel then gives its `/proc`
+     entries to root, so when a process's descriptors refuse, each thread's are read; a thread
+     that refuses counts as holding nothing only if its `stat` flags show it exiting
+     (`PF_EXITING`) or it has exited. The one exception is a descendant that dropped
+     dumpability, as bubblewrap's sandboxed child does: the kernel refuses its descriptors, so
+     it is listed, and it must be one of the traced execs, whose sockets strace records.
+
+   Events compare exactly after rewrites listed in the script and printed with every run, and
+   nothing else. Literal paths: `<codex-home>` for a launch's private `CODEX_HOME`,
+   `<operator-codex-home>` for the operator's own Codex home (the live operator-mode
+   participant), `<probe>` and `<work>` for the offline probe's and a live launch's private
+   directory, `<schema-out>` for the schema output and `<codex>` for the release's native
+   vendor directory. File and socket paths, never exec argv, also get three patterns:
+   `/proc/<pid>/`, and the six random characters of Codex's `codex-arg0` and `.tmp` temporary
+   names. Addresses get labels: `<loopback>` for the offline provider, and live
+   `<chatgpt.com>` for the addresses that host resolves to during the run and `<resolver>` for
+   each `/etc/resolv.conf` nameserver. Snapshot entries whose names collapse to one pattern keep
+   a numbered suffix, so an extra file still shows. Any `io_uring_setup` in any trace fails,
+   since a ring's operations bypass the traced syscalls.
+
+2. `pnpm codex:qualify <version> --live` adds account-backed phases through the real launcher,
+   run for the baseline and then the candidate: readiness without a model turn, one analyst
+   turn, an analyst cancelled at its first streamed delta and a participant cancelled during
+   its first tool call. These use a small amount of account quota. Every launch of either
+   binary, including its `--version` checks, runs under `strace`, and each app-server is also
+   sampled. Each candidate launch's execs, sockets, file writes and sampled TCP and UDP remotes
+   must stay within the baseline's same launch, TCP and UDP may reach only `<chatgpt.com>` and
+   `<resolver>`, and no traced connect or sampled socket may reach the operator's Codex daemon
+   socket. A sampler failure on either release fails. The
+   baseline's phases must reach the same outcomes, so its launches are comparable. The
+   script admits the candidate through `cliVersions`, an internal launcher option that
+   bypasses the host list; no library export, manifest, CLI flag or run hook reaches it.
+
+Removing a release from a host list stops new launches only; readers keep accepting it.

package/docs/architecture/serve.md

@@ -2,16 +2,18 @@
 
 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.
+Status: shipped. The `loopback`, `exposed` (edge-authed) and `share-safe-open`
+modes live in `src/observer/serve.ts`, `src/observer/library.ts`,
+`src/observer/http.ts`, `src/observer/exposure.ts` and `src/observer/tunnel.ts`,
+with per-run routes and the history index in `src/observer/run-routes.ts` and the
+loopback bind in `src/observer/listen.ts`. The CLI wiring is in
+`src/cli/commands/observe.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
+in-process auth: the hand-rolled capability-link (cookie/token/TTL, its auth
+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).
@@ -21,73 +23,75 @@ you own).
 `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
+- `humanish watch` serves one attached run: the process that created the run
+  serves it and may inject runtime stream URLs for live following (see the
+  stream-URL rules below and `watch --expose`);
+- `humanish observe` re-serves one finished run read-only;
+- `humanish serve` serves 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
+`--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
+One shared validator (`validateExposure` in `src/observer/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`) →
+| `--expose` | `--tunnel` | `--oauth` | `--public-url` | `--safe` | Outcome                                                                                       |
+| ---------- | ---------- | --------- | -------------- | -------- | --------------------------------------------------------------------------------------------- |
+| no         | no         | no        | no             | any      | `loopback` (no exposure)                                                                      |
+| yes        | yes        | yes       | no             | any      | OK → `exposed` (edge-authed; all runs unless `--safe`)                                        |
+| yes        | yes        | no        | no             | yes      | OK → `share-safe-open` (public, share_ready only)                                             |
+| yes        | yes        | no        | no             | no       | **REFUSED** `HUMANISH_SERVE_EXPOSE_REQUIRES_EDGE_AUTH_OR_SAFE`                                |
+| yes        | no         | no        | yes            | any      | OK → `exposed` (operator-secured edge)                                                        |
+| yes        | no         | no        | no             | any      | **REFUSED** `HUMANISH_SERVE_EXPOSE_REQUIRES_ORIGIN` (no reachable origin, even with `--safe`) |
+| yes        | no         | yes       | no             | any      | **REFUSED** `HUMANISH_SERVE_OAUTH_REQUIRES_TUNNEL`                                            |
+| yes        | yes        | yes       | yes            | 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; a `--public-url` that is not an
+http(s) origin → conflict; a tunnel/public-url without `--expose` →
+`HUMANISH_SERVE_TUNNEL_REQUIRES_EXPOSE`/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`.
+`HUMANISH_SERVE_EXPOSE_REQUIRES_EDGE_AUTH_OR_SAFE`. `--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
+would admit nothing. `watch --safe`, with or without `--expose` and on every route, is
+therefore refused outright with `HUMANISH_WATCH_SAFE_NOT_APPLICABLE` (exit 2), so the flag is
+never silently ignored.
+`watch --expose` always requires edge auth (`--tunnel --oauth` or `--public-url`),
+and is also 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
+`startNgrokTunnel` builds `ngrok http --log stdout --log-format json [--url
+<domain>] [--oauth google [--oauth-allow-email <addr>]… [--oauth-allow-domain
+<domain>]…] <port>`. 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.
+forward-compatible path if ngrok removes the flags is a Traffic Policy YAML. That
+is a documented fast-follow, out of scope for 0.18.0.
 
 ## Threat model
 
@@ -98,56 +102,59 @@ 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.
+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 applies the same Host
+allowlist under its `exposed` option and sends the security headers below in
+every mode (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`).
+`x-frame-options: DENY`, `content-security-policy: frame-ancestors 'none'`, and
+`x-robots-tag: noindex, nofollow` (`buildServeSecurityHeaders` in
+`src/observer/http.ts`). Raw run artifacts get `buildArtifactSecurityHeaders`,
+which adds `sandbox allow-scripts` to that policy.
 
 ## 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). |
+| 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. Each request walks the run, and any added, removed or changed file re-verifies it first; a file is read only while its inode, size, mtime and ctime match the walk verify covered, and its bytes are served only when their sha256 matches the hash taken at admission. Everything else is absent, 404ing byte-identically to a nonexistent run (no existence oracle). |
 
-## Stream-URL doctrine
+## Keep stream URLs off the library surface
 
 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
+- **Structural:** runtime stream URLs live in a `WeakMap` keyed by the watch
+  process's in-memory `ObserverResult` (`src/observer/render.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
+- **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
+- **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.
+`watch --expose` is the one surface that deliberately serves runtime E2B stream
+URLs. The attached watch process holds them, and watching from a phone needs the
+live desktop stream. 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
+## Know what `share_ready` checks
 
 `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
+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
@@ -158,13 +165,13 @@ publishing because it is.
 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
+the `501` directly. No `401` precedes it 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;
+- an operator identity distinct from a viewer, sourced from the edge/control
+  plane, not from 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
@@ -177,20 +184,15 @@ 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 —
+of a `Ctrl-C`. Better Auth fits a future hosted humanish
+dashboard or 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.
+  available); pin the behavior in `tests/observer/tunnel.test.ts` first.
 - **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.
+  including its live E2B desktop stream, behind the same edge auth. It is the one
+  surface that deliberately serves runtime stream URLs. See observer.md.