humanish 0.107.0 → 0.108.0

package/docs/architecture/desktop-sessions.md

@@ -2,7 +2,7 @@
 
 Independent computer-use participants, on hosted E2B desktops and local Firecracker
 desktops, acquire an owned desktop allocation before subject setup, then bind its
-executor after browser setup. The participant loop still consumes `CuaExecutor`;
+executor after browser setup. The participant loop still consumes `ComputerUseExecutor`;
 provisioning commands stay in the desktop adapter. This internal interface is not
 a public runtime plugin API.
 
@@ -45,7 +45,7 @@ span, not a provider billing measurement.
 2. The runner starts its model session and signals the existing hosted pipeline
    gate, preserving the current scheduling order.
 3. `openSession()` measures initial browser geometry, starts the optional live
-   stream, and supplies a `CuaExecutor` plus any participant inbox location.
+   stream, and supplies a `ComputerUseExecutor` plus any participant inbox location.
 4. The runner executes the participant loop and closes its model session.
 5. `finalize()` collects final evidence and releases the desktop, including after
    preparation or participant failure. Repeated calls share one finalization.
@@ -62,16 +62,16 @@ its steps in the files beside it; acquisition and release are in
 `src/substrates/e2b/desktop-media.ts`. Subject provisioning lives in
 `src/subject/` and reaches the sandbox only through a `Shell`
 (`src/substrates/shell.ts`), which `e2bShell` (`src/substrates/e2b/shell.ts`)
-builds from the sandbox handle. The adapter never imports the lab runner at
+builds from the sandbox handle. The adapter never imports the study runner at
 runtime.
 
 The runner owns instructions, model execution, spend guards, screenshots, trace
 persistence and participant outcome interpretation. It does not invoke desktop
 shell commands or manufacture E2B objects for an alternate executor. A local
 Firecracker run supplies its desktops through the computer-use run's `localVm`
-input (`LocalVmInput` in `src/routes/computer-use/types.ts`). runLab builds that
+input (`LocalVmInput` in `src/routes/computer-use/types.ts`). runStudy builds that
 input with `prepareLocalVmRun` (`src/routes/computer-use/local-vm.ts`), and no
-package caller can set it. Contract tests pass a `localVm` desktop on a lab with
+package caller can set it. Contract tests pass a `localVm` desktop on a study with
 `execution.target: local`. Neither bypasses CLI admission checks.
 
 Final evidence errors cannot skip desktop release. Existing bundle fields and
@@ -81,12 +81,12 @@ adapter cannot establish them.
 
 Independent hosted browser and terminal participants, local Firecracker participants, and
 shared-world participants that use `runCuaParticipant` use this boundary. Local execution is
-described in [local browser studies](local-browser-runtime.md).
+described in [local browser studies](https://humanish.dev/docs/local-browser).
 
 The `runSession` testing hook for independent participants now receives a constructed
 `executor` instead of `desktop`/`executorOptions`. A hook should consume the
 normal `CuaActorSessionOptions` executor or delegate to the internal
 `runCuaActorSession`. The `runCuaActorSession` export was removed in 0.107.0; a
 library caller uses `runComputerUseLoop`. A custom in-process
-executor now goes through `RunLabOptions.inProcess`, which replaces the
+executor now goes through `RunStudyOptions.inProcess`, which replaces the
 removed `cuaHooks.buildExecutor`.

package/docs/architecture/external-public-shared-world.md

@@ -1,6 +1,6 @@
-# External-public shared-world plane + the CDP lobby-code handoff (#164 phase 2, 0.20.0)
+# External-public shared world and the lobby-code handoff
 
-The concurrent shared-world backend now has TWO plane classes. This note documents the new
+The shared-world route has two plane classes. This note documents the new
 `external-public` class and the host-first handoff barrier that makes cross-persona coordination on a
 real public app possible without any persona-to-persona messaging.
 
@@ -8,35 +8,35 @@ real public app possible without any persona-to-persona messaging.
 
 |                     | provisioned-getHost (historical)                                     | external-public (new)                                                                             |
 | ------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
-| Shared plane        | a `clone`/`local-tree` subject served + `getHost`-exposed IN-SANDBOX | a real operator-OWNED public deployment (`source: app-url`) used DIRECTLY                         |
-| Harness role        | MINTED and controls the host URL                                     | OBSERVES that the participants converged on ONE origin (tolerant of a declared→observed redirect) |
+| Shared plane        | a `clone`/`local-tree` subject served + `getHost`-exposed in-sandbox | a real operator-owned public deployment (`source: app-url`) used directly                         |
+| Harness role        | Minted and controls the host URL                                     | Observes that the participants converged on one origin (tolerant of a declared→observed redirect) |
 | Subject sandbox     | one (headless service host) + N actor desktops                       | none; only N actor desktops                                                                       |
 | Attestation         | `subject.exposure: synthetic` (synthetic seeded data)                | `subject.publicTarget: { owner, authorized }` (you own/operate it)                                |
 | Provenance          | `subject.state.provenance == seeded`                                 | `subject.state.provenance == external-public`                                                     |
 | Plane identity      | `plane.hostDigest`; every `routeHostDigest == it` (harness-minted)   | `plane.publicOriginDigest`; every CDP-observed `routeHostDigest == it` (observed)                 |
-| Shared-state proof  | authoritative in-sandbox checkpoint `stateSeries` + delta-on-pass    | none; `stateSeries` OMITTED (Option A)                                                            |
-| Concurrency-on-pass | ≥2 overlapping windows AND a state delta at/after an overlap start   | ≥2 overlapping windows ONLY (temporal co-occupancy)                                               |
+| Shared-state proof  | authoritative in-sandbox checkpoint `stateSeries` + delta-on-pass    | none; `stateSeries` omitted (Option A)                                                            |
+| Concurrency-on-pass | ≥2 overlapping windows and a state delta at/after an overlap start   | ≥2 overlapping windows only (temporal co-occupancy)                                               |
 | Extra proof         | none                                                                 | `lobbyConvergenceDigest` (all participants on one `/lobby/CODE`)                                  |
 
 The run's own verdict applies the same concurrency-on-pass rule per plane (`judgeSharedWorld` in
-`src/run/judge.ts`), so a run whose participants all passed but missed it reads fail and the lab exits
+`src/run/judge.ts`), so a run whose participants all passed but missed it reads fail and the study exits
 non-zero.
 
 In short: getHost = harness-minted host + synthetic-seeded attestation + authoritative
-in-sandbox checkpoint `stateSeries`. external-public = operator-attested public origin + NO synthetic
-claim + NO authoritative shared-state proof (concurrency evidenced by temporal co-occupancy +
-observed lobby-path convergence only). Every downgrade is asserted-ABSENT by verify, never silently
-dropped: `plane.exposure` MUST be absent (claiming synthetic on a real site is a lie),
-`plane.hostDigest` MUST be absent, the `seeded`/`synthetic` attribution limits are FORBIDDEN, and the
-external-public honest-downgrade limits are REQUIRED.
-
-Why the getHost synthetic gate is deliberately NOT reachable from the app-url branch: that gate
+in-sandbox checkpoint `stateSeries`. external-public = operator-attested public origin + no synthetic
+claim + no authoritative shared-state proof (concurrency evidenced by temporal co-occupancy +
+observed lobby-path convergence only). Every downgrade is asserted-absent by verify, never silently
+dropped: `plane.exposure` must be absent (claiming synthetic on a real site is a lie),
+`plane.hostDigest` must be absent, the `seeded`/`synthetic` attribution limits are forbidden, and the
+external-public disclosure limits are required.
+
+Why the getHost synthetic gate is deliberately not reachable from the app-url branch: that gate
 (`concurrentSharedWorldValidationReason` in `src/lab/validation.ts` requires `subject.exposure:
 synthetic`, a `0.0.0.0` bind and no `keep`; verify's `getHostPlaneFindings` in
 `src/verify/shared-world-concurrent.ts` then requires `plane.exposure == synthetic` and
-`subject.state.provenance == seeded`) exists because a getHost URL is internet-reachable AND
+`subject.state.provenance == seeded`) exists because a getHost URL is internet-reachable and
 harness-owned; real data behind a harness-exposed URL is the hazard. A public site the harness
-neither provisioned nor exposed has NEITHER property, so the gate's hazard does not exist there. The
+neither provisioned nor exposed has neither property, so the gate's hazard does not exist there. The
 app-url branch is validated by `externalPublicSharedWorldValidationReason` (`src/lab/validation.ts`)
 and is reached before the getHost gate; a snapshot regression test pins the getHost path
 byte-unchanged.
@@ -48,14 +48,15 @@ Reading a participant's live URL mid-run is already implemented: `makeChromeBrow
 (`src/substrates/e2b/cdp-probe.ts`) that resolves the participant's Chrome CDP port, selects the participant's
 page, and sends `Runtime.evaluate({ url: location.href, title, text })` over the page's
 `webSocketDebuggerUrl`. `createE2BDesktopExecutor` stamps `observation.url` from it every turn.
-`CuaObservation.url` is RUNTIME-ONLY by contract (it drives `stopWhen`/progress but is never
+`CuaObservation.url` is runtime-only by contract (it drives `stopWhen`/progress but is never
 persisted raw into the trace).
 
-The 0.20.0 delta is a single surgical callback: `CuaLoopOptions.onObservedUrl?(url)`, invoked right
-after every `executor.observe()` (the initial observe and each loop observe) with `observation.url`,
-threaded through `CuaActorSessionOptions` → `CuaParticipantDeps` → the concurrent orchestrator. No new CDP
-code; no lobby-trivia change. The CDP URL read later proved unreliable on E2B desktops, so the
-host's code can now also come from its narration or its screen (step 2).
+The route reads each participant's URL through one callback, `CuaLoopOptions.onObservedUrl?(url)`,
+invoked right after every `executor.observe()` (the initial observe and each loop observe) with
+`observation.url`, threaded through `CuaActorSessionOptions` → `CuaParticipantDeps` → the concurrent
+orchestrator. It adds no CDP code and needs no change to the lobby-trivia app. The CDP URL read is
+unreliable on E2B desktops, so the host's code can also come from its narration or its screen
+(step 2).
 
 `onObservedUrl`, `onMessage` and `onScreenshot` are deprecated on `CuaLoopOptions`, and the next
 minor removes them. A `runComputerUseLoop` caller that used them wraps the executor's `observe`
@@ -71,71 +72,72 @@ Flow, a host-first barrier inside `runConcurrentSharedWorld`'s fan-out:
    `/\/lobby\/([A-Z2-9]{6})(?:$|[/?#])/` (a locale prefix `/en/lobby/CODE` and a query/hash suffix
    are tolerated), a lobby code in its narration (`extractLobbyCodeFromNarration`), or a vision read
    of its screenshot (`readLobbyCodeFromFrame`). The vision reads are out-of-band OpenAI calls, at
-   most 30 per participant, and are not counted against `execution.caps.maxUsd`. The host KEEPS PLAYING
+   most 30 per participant, and are not counted against `caps.maxUsd`. The host keeps playing
    after resolving, so its window overlaps the followers'.
-3. **Barrier.** Follower participants (`host` absent) do NOT compose a mission or open their target until
-   the latch resolves or the handoff deadline passes. On resolve, CODE is threaded into each
-   follower's mission ("…choose Join, enter lobby code {CODE}…"). It is not a raw URL navigation,
+3. **Barrier.** Follower participants (`host` absent) do not compose a mission or open their target until
+   the latch resolves or the handoff deadline passes. On resolve, code is threaded into each
+   follower's mission (`…choose Join, enter lobby code {CODE}…`). It is not a raw URL navigation,
    because a direct `/lobby/CODE` visit does not auto-join a non-member (lobby-trivia's lobby page
    redirects unknown/non-member sessions home); the follower goes through the real Join flow.
 4. **Convergence confirmation.** Each follower's own `onObservedUrl`, or a vision read of its own
    frame, confirms it reached `/lobby/CODE`; this observed convergence becomes the
-   `lobbyConvergenceDigest`, the pass signal that the handoff LANDED rather than merely being
-   instructed. Recorded only when EVERY participant converged on ONE code.
+   `lobbyConvergenceDigest`, the pass signal that the followers reached the lobby. An instruction to
+   join does not set it. It is recorded only when every participant converged on one code.
 5. **Fail-closed timeout.** If the host never yields a `/lobby/CODE` within the handoff deadline
    (`min(execution.timeoutMs, max(120 s, 40% of execution.timeoutMs))`; injectable in tests), the
-   latch rejects; every follower fails closed WITHOUT opening (no wasted turns against a codeless
-   home page); the run returns `HUMANISH_CONCURRENT_SHARED_WORLD_LAB_HANDOFF_TIMEOUT` and the bundle
+   latch rejects; every follower fails closed without opening (no wasted turns against a codeless
+   home page); the run returns `HUMANISH_SHARED_WORLD_HANDOFF_TIMEOUT` and the bundle
    records the host window + a handoff-failed outcome for followers. If the host participant ends without a
    code before the deadline, `releaseFollowersIfUnlatched` releases the followers at once and the
-   run returns `HUMANISH_CONCURRENT_SHARED_WORLD_LAB_FAILED` with the host's reason. A host that
-   reaches the lobby but whose followers fail to JOIN is a normal per-participant non-pass (the
-   concurrency-on-pass gate then simply won't see ≥2 overlap, and the verdict stays non-pass,
-   honestly), not a whole-run abort.
-
-> **Temporary shim (tracked by #296).** This CDP URL-relay handoff — reading the host's `/lobby/CODE`
-> off its own browser and threading it into the follower missions — is a TEMPORARY coordination shim.
-> It is to be augmented/replaced by the actor message bus (fake SMS/email invite) in #297: the
-> human-realistic version is the HOST SENDING the invite link and followers RECEIVING and tapping it,
-> rather than the orchestrator relaying the code out-of-band.
+   run returns `HUMANISH_SHARED_WORLD_FAILED` with the host's reason. A host that
+   reaches the lobby but whose followers fail to join is a normal per-participant non-pass (the
+   concurrency-on-pass gate then simply won't see ≥2 overlap, and the verdict stays non-pass),
+   not a whole-run abort.
+
+> **Temporary shim.** This CDP URL-relay handoff reads the host's `/lobby/CODE` off its own browser
+> and threads it into the follower missions.
+> [An open issue](https://github.com/danielgwilson/humanish/issues/296) tracks replacing it with the
+> [actor message bus](https://github.com/danielgwilson/humanish/issues/297), where the host sends an
+> SMS or email invite link and the followers receive and tap it. The orchestrator then no longer
+> relays the code out of band.
 
 ## Observed-origin convergence (not declared)
 
-The convergence proof is about what the participants OBSERVED, not what was DECLARED. `plane.publicOriginDigest`
-is the sha256-16 of the ONE origin the participants' CDP-observed final URLs converged on; verify requires every
+The convergence proof is about what the participants observed, not what was declared. `plane.publicOriginDigest`
+is the sha256-16 of the one origin the participants' CDP-observed final URLs converged on; verify requires every
 `laneWindow.routeHostDigest` to agree on it. A normal cross-origin redirect (apex→www, http→https;
-lobby-trivia.example.test 307-redirects) makes the OBSERVED origin differ from the declared `subject.appUrl`, which
-is EXPECTED and must never fail the run. So the declared origin is recorded separately as
-`plane.declaredOriginDigest` for reference and is NEVER asserted equal to the observed one. Operator
-OWNERSHIP rests on the `subject.publicTarget.authorized` attestation + the declared `appUrl`, NOT on
-digest equality. Verify fails closed only when the participants did not converge on a single OBSERVED origin
+lobby-trivia.example.test 307-redirects) makes the observed origin differ from the declared `subject.appUrl`, which
+is expected and must never fail the run. So the declared origin is recorded separately as
+`plane.declaredOriginDigest` for reference and is never asserted equal to the observed one. Operator
+ownership rests on the `subject.publicTarget.authorized` attestation + the declared `appUrl`, not on
+digest equality. Verify fails closed only when the participants did not converge on a single observed origin
 (it then lists the distinct observed origin digests).
 
 ## Hygiene
 
-The runtime `location.href` (and the 6-char CODE inside it) is never persisted raw: `onObservedUrl` is
-runtime-only; the threaded CODE flows only into the follower's composed prompt (never a raw bundle
-field) and is scrubbed from all narration once latched; the shared origin and lobby path persist ONLY
+The runtime `location.href` (and the 6-char code inside it) is never persisted raw: `onObservedUrl` is
+runtime-only; the threaded code flows only into the follower's composed prompt (never a raw bundle
+field) and is scrubbed from all narration once latched; the shared origin and lobby path persist only
 as sha256-16 digests (`publicOriginDigest`, `lobbyConvergenceDigest`). This matches the existing
 e2b-URL / host-digest redaction discipline.
 
 ## Mobile fidelity caveat
 
-The example roster runs mobile-LAYOUT participants (`device: mobile` 414×896, `small-mobile` 360×740). On
-the E2B-desktop route the rendered WIDTH is floored to `MIN_DESKTOP_RENDER_WIDTH` (500) because
-Chrome refuses a narrower window and a narrower X screen clipped the page (0.20.3, #304), so both
-presets render at 500 wide and are identical in layout; only HEIGHT renders as declared.
+The example roster runs mobile-layout participants (`device: mobile` 414×896, `small-mobile` 360×740). On
+the E2B-desktop route the rendered width is floored to `MIN_DESKTOP_RENDER_WIDTH` (500) because
+Chrome refuses a narrower window and a narrower X screen clips the page, so both
+presets render at 500 wide and are identical in layout; only height renders as declared.
 `desktopGeometry.screen.verified` compares the floored number with itself, so it does not attest the
-preset width. There is NO touch input, and `isMobile`/DPR are prompt-signal + metadata (DPR renders
-only via the CDP geometry path). "3 mobile personas" = 3 mobile-LAYOUT desktop-Chromium participants, not
+preset width. There is no touch input, and `isMobile`/DPR are prompt-signal + metadata (DPR renders
+only via the CDP geometry path). "3 mobile personas" = 3 mobile-layout desktop-Chromium participants, not
 touch devices. Do not over-read the results as true mobile-device coverage. That describes the
-default. With `execution.desktop.fidelity.mobileEmulation: true` (#221), Chromium participants on a mobile
+default. With `execution.desktop.fidelity.mobileEmulation: true`, Chromium participants on a mobile
 preset get a DevTools device-metrics override at the preset width, plus DPR, touch emulation and a
 mobile user agent. That is still not physical-device fidelity.
 
 ## Watch-from-phone
 
 Native live-desktop `--expose` is not supported on the concurrent path; only the computer-use
-backend live-serves a run (`src/cli/io.ts`). Today, watch it from a phone via `humanish serve
+route live-serves a run (`src/cli/io.ts`). Today, watch it from a phone via `humanish observe --all
 --expose --tunnel … --oauth …` against the run directory's Observer (the concurrent path writes
 artifacts continuously and attaches per-participant runtime stream URLs to the live Observer).

package/docs/architecture/github-feedback-loop.md

@@ -1,9 +1,6 @@
 # Public GitHub Feedback Loop Architecture
 
-Date: 2026-06-01
-
-Status: design note. The v0 dry-run issue draft path is implemented locally;
-live GitHub mutation remains out of scope.
+This is a design note. The dry-run issue draft path ships; live GitHub mutation is out of scope.
 
 ## Goal
 

package/docs/architecture/guest-desktop.md

@@ -1,7 +1,7 @@
 # Headed browser guest components
 
 These internal components implement native input and full-desktop captures for the browser guest
-that [local browser studies](local-browser-runtime.md) run in a Firecracker VM. This page covers
+that [local browser studies](https://humanish.dev/docs/local-browser) run in a Firecracker VM. This page covers
 the guest driver and its container proof; the local browser page covers the VM, its network
 policy and the installed study.
 
@@ -96,4 +96,4 @@ native scrolling and cancellation. CI reruns this proof for changes to the guest
 recipe, protocol or dependency lockfile. Its deterministic fixture is not a model participant, a
 run bundle, a host network policy, an independent watchdog or a Linux/Mac installed study. The
 local browser runtime is qualified separately; see [local browser
-studies](local-browser-runtime.md).
+studies](https://humanish.dev/docs/local-browser).

package/docs/architecture/observer.md

@@ -1,13 +1,8 @@
 # Observer Architecture
 
-Date: 2026-06-01 (current-state note updated 2026-07-14)
-
-Status: implemented for synthetic streams and persisted live browser,
-terminal-product, fan-out, and shared-world evidence.
-Plain computer-use and shared-world runs can publish an in-progress bundle to
-an attached loopback Observer without persisting runtime stream-auth URLs. The
-version-pinned README image is a synthetic technical sample, not real-application
-proof.
+The Observer renders synthetic streams and saved live browser, terminal-product, fan-out and
+shared-world evidence. A computer-use or shared-world run can publish its in-progress bundle to an
+attached loopback Observer without saving runtime stream-auth URLs.
 
 ## Decision
 
@@ -80,7 +75,7 @@ forwarding, and only contained run paths in the TUI's project are accepted.
 | `watch` during a study   | Saved evidence and available in-memory desktop streams                    | Until the attached command exits |
 | `observe --run <id>`     | Saved evidence from the selected run                                      | Until the command exits          |
 | TUI Open in Observer     | Saved evidence in the selected run; shares the project's evidence library | Until the TUI exits              |
-| `serve`                  | Saved evidence across the project's library                               | Until the server command exits   |
+| `observe --all`          | Saved evidence across the project's library                               | Until the server command exits   |
 | Static HTML or `file://` | The exported snapshot                                                     | Independent of a server          |
 
 `observe` uses the same current-data projection as the attached viewer, scoped
@@ -103,7 +98,7 @@ mismatched records omit the observation. A stale heartbeat alone does not prove
 interruption, and stored PIDs are neither probed nor returned. Static rendering
 and export do not create this served-only observation.
 
-Watch is deliberately distinct from `humanish serve`. Watch serves ONE
+Watch is deliberately distinct from `humanish observe --all`. 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
@@ -123,23 +118,23 @@ Misdirected Request` otherwise) and the shared `buildServeSecurityHeaders()` on
 every response (both live in `src/observer/http.ts`, shared without a module cycle).
 The Host allowlist applies in exposed mode; frame-denial headers apply in both modes.
 
-Exposed mode also SCOPES the surface to the attached live run (`result.run`): the
+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. They can 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
+`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 watching
 from a phone needs them. It is safe only because the
 ngrok edge (Google OAuth + allow rules) or an operator `--public-url` edge
 authenticates the viewer first, so `watch --expose` 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
+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
+to Ctrl-C. `observe --all` still never injects stream URLs. See
 [Serve: the run library surface](serve.md).
 
 ### Live desktop iframe authority
@@ -178,8 +173,9 @@ between an active study and its provisional evidence outcome.
 
 ## UI Shape
 
-See [Watching and reviewing evidence](observer-review.md) for current controls,
-entry-point capabilities, timing limits and browser acceptance commands.
+[Watch and review in the Observer](https://humanish.dev/docs/review-surfaces#watch-and-review-in-the-observer)
+describes the current controls, entry points and timing limits for users;
+[Browser checks](#browser-checks) below covers the proofs that pin them.
 
 The Observer shell has:
 
@@ -198,7 +194,7 @@ the frozen Observer data schema or start provider requests. Analysis polling has
 an independent lifecycle, so a delayed companion does not stall recording updates.
 Invalid or stale interpretation never overwrites original participant outcomes.
 Recording navigation retains its originating view, and nonvisual citations open
-the source event rather than inventing a playback frame.
+the source event with no invented playback frame.
 
 The participant grid uses equal-height previews whose widths follow each screen's
 aspect ratio. A 44px identity/source/outcome caption sits below the captured pixels;
@@ -230,29 +226,16 @@ A host adapter may provide:
 If no embed URL exists, the Observer still renders the Codex-style timeline and
 session contract instead of failing the stream.
 
-## Historical slice and remaining gaps
-
-The original 2026-06-01 slice implemented the Observer substrate and synthetic
-stream contracts; local `codex-exec` active-run snapshots followed.
-
-Subsequent additions through 2026-06-11 included:
+## Remaining gaps
 
-- Playwright-backed browser proof with scripted, app-specific
-  `browser.steps` authored in `humanish/scenarios/*.yaml` (`src/actors/scripted-browser/`);
-- native Codex app-server session adapter (`src/actors/codex/app-server.ts`,
-  registered in `src/actors/registry.ts`);
-- E2B desktop participants on the computer-use and shared-world routes;
-- computer-use bundles persist a `screenshots/` directory and the Observer
-  renders the frames (`src/routes/computer-use/participant-execution.ts` writes them).
-
-Intentionally still adapter work:
+These remain adapter work:
 
 - local PTY capture;
 - Codex TUI live follow after workspace trust bootstrap;
 - richer screenshot/trace galleries across multi-step product journeys;
 - reviewer acceptance gates over real product behavior.
 
-## The rendering layer (#426, cut over 2026-08-16)
+## The rendering layer
 
 The renderer is the `observer/` workspace: a Vite single-file build on the
 `@humanish` registry tokens, frozen against `humanish.observer-data.v1`
@@ -260,10 +243,27 @@ The renderer is the `observer/` workspace: a Vite single-file build on the
 artifact to `dist/observer-app.html`; in a repo checkout a missing or stale
 artifact auto-builds, and an unconditional preflight at CLI startup makes a
 broken artifact cost seconds, never a completed session. `renderObserverHtml`,
-the one function every surface (observe, watch, serve, labs) renders through,
+the one function every surface (observe, observe --all, watch, studies) renders through,
 injects the run's snapshot into the artifact
 (`tests/observer/artifact.test.ts` pins the path, cold, so CI exercises the
 auto-build every run). The legacy string-concat renderer was deleted at
 cutover; there is no flag and no fallback. Rollback is a version pin. The
 workspace's own tests pin the durability constraints (self-contained single
 file, fonts inlined, no network references).
+
+## Browser checks
+
+`pnpm observer:browser:proof` exercises generated synthetic evidence in the
+production artifact. `pnpm observer:iframe:proof`, after `pnpm build`, checks the
+actual serving boundary against direct, redirected and scripted iframe attacks.
+CI retains their screenshots and JSON receipts. These Chromium checks do not
+claim physical-device or non-Chromium coverage. Actual provider checks and their
+resource-cleanup receipts are separate acceptance evidence.
+
+Interaction references rechecked September 8, 2026:
+[Base UI popover](https://base-ui.com/react/components/popover),
+[React state structure](https://react.dev/learn/choosing-the-state-structure),
+[WAI-ARIA tabs](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/),
+[iframe sandboxing](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/iframe),
+[Playwright Trace Viewer](https://playwright.dev/docs/trace-viewer), and
+[PostHog recording controls](https://posthog.com/docs/session-replay/how-to-watch-recordings).

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

@@ -5,24 +5,28 @@ 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 **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))
+The launcher profile is **a stable Codex CLI release from 0.154.0 on, Linux x64 or Apple
+Silicon macOS, file-backed ChatGPT login, `gpt-6-astra`, low reasoning effort**.
+[`src/actors/codex/codex-admission.ts`](https://github.com/danielgwilson/humanish/blob/main/src/actors/codex/codex-admission.ts)
+admits every stable `MAJOR.MINOR.PATCH` release from 0.154.0, the oldest known to work, except
+those in `REFUSED_CODEX_CLI_VERSIONS` (none yet). There is no ceiling: a new release runs the
+day it ships, and one that breaks humanish is refused there until humanish handles it.
+Prereleases and older releases are refused, and the refusal names the release and why. Hosted
+participants (operator mode) run the same releases on Linux x64 and arm64 and macOS x64 and
+arm64; a hosted run on a release outside `TESTED_CODEX_CLI_VERSIONS` records a warning that its
+evidence rests on the checks each launch makes. `TESTED_CODEX_CLI_VERSIONS` gates nothing. It
+lists the releases the qualifier passed on Linux x64, and its newest is the default and the
+install target: 0.154.0, 0.157.1
+([receipt](https://github.com/danielgwilson/humanish/blob/main/docs/evidence/computer-use/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))
+([receipt](https://github.com/danielgwilson/humanish/blob/main/docs/evidence/computer-use/codex-cli-0.159.2-qualification-2026-09-30.md))
 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))
+([receipt](https://github.com/danielgwilson/humanish/blob/main/docs/evidence/computer-use/codex-cli-0.159.3-qualification-2026-10-01.md))
 and 0.160.0
-([receipt](https://github.com/danielgwilson/humanish/blob/main/docs/goals/computer-use-actor/receipts/codex-cli-0.160.0-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.
+([receipt](https://github.com/danielgwilson/humanish/blob/main/docs/evidence/computer-use/codex-cli-0.160.0-qualification-2026-10-01.md)).
+On Apple Silicon, 0.154.0 passed installed participant/analysis studies and the native dispatch
+restriction check on an M5 Max; no later release has run on a Mac. Other 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
@@ -30,8 +34,8 @@ path; it does not pin the executable's contents, and a modified binary can repor
 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.
+receipt shows that the launched release passed its checks. Saved bundles naming any stable
+release from 0.154.0 on stay readable, whether or not a launch list names it.
 Readiness validates the installation and effective profile without submitting a
 model turn; it does not guarantee current quota or model access.
 
@@ -159,10 +163,11 @@ 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
+## Testing 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:
+Admission does not wait for a test. A release enters `TESTED_CODEX_CLI_VERSIONS`, which gates
+nothing, with a dated receipt under `docs/evidence/computer-use/` showing all of
+the following, on Linux x64:
 
 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
@@ -170,27 +175,28 @@ A release enters a host's list only with a dated receipt under
    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>
+   `PATH=<evidence>/npm-<version>/node_modules/.bin:$PATH pnpm humanish run <study>
 --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
+can show that a benign 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.
+Then commit the release in `TESTED_CODEX_CLI_VERSIONS` (`src/actors/codex/codex-admission.ts`);
+launch admission does not change. Readers need no change: saved
+profiles may name any stable release from `RECORDED_CODEX_CLI_FLOOR` (0.154.0) on, in
+`src/actors/contract.ts` and the Observer's copy (`observer/lib/actor-execution-profile.ts`).
+If any check fails, record what differs; a release that breaks humanish goes in
+`REFUSED_CODEX_CLI_VERSIONS` with its issue.
 
 ### 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
+it detects a benign 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: