humanish 0.104.3 → 0.106.0

package/docs/architecture/browser-control.md

@@ -2,23 +2,26 @@
 
 The browser-control client implements the existing `CuaExecutor` over an
 already-owned Node `Duplex`. The matching dispatcher invokes an owner-supplied
-executor. This is a preparatory internal boundary, not a managed-local runtime,
-CLI mode, browser launcher, VM isolation claim, or installer.
+executor. Local Firecracker desktops use it as their host-to-guest control
+channel: `src/guest/bootstrap.ts` creates the client and `src/guest/runtime.ts`
+attaches the dispatcher. This page covers only the protocol; it is not itself a
+runtime, CLI mode, browser launcher, VM isolation claim, or installer.
 
 ## Ownership and admission
 
-`createBrowserControlClient({ transport, identity, requestTimeoutMs? })` returns
-`{ executor, ready(), close() }`. `ready()` performs a lazy handshake; the first
-observation/action also performs it when needed. The owner closes the client
-when its session ends. The client never discovers endpoints, opens sockets,
-spawns processes, reconnects, retries, or replays a mutation.
+`createBrowserControlClient({ transport, identity, requestTimeoutMs?,
+speechEnabled? })` returns `{ executor, ready(), finishRecording(destination),
+close() }`. `ready()` performs a lazy handshake; the first observation/action
+also performs it when needed. The owner closes the client when its session ends.
+The client never discovers endpoints, opens sockets, spawns processes,
+reconnects, retries, or replays a mutation.
 
 `attachBrowserControlDispatcher({ transport, identity, executor, isAuthorized,
-authoritySignal })` returns `{ close() }`. The authority signal is required.
-The owner establishes the channel and authority independently; the identity's
-`generation`, `challenge`, and `runtimeRevision` only check consistency.
-Each is a bounded ASCII token. A matching string does not prove a lease or
-authenticate executable bytes.
+authoritySignal, finishRecording? })` returns `{ close() }`. The authority signal
+is required. The owner establishes the channel and authority independently; the
+identity's `generation`, `challenge`, and `runtimeRevision` only check
+consistency. Each is a bounded ASCII token. A matching string does not prove a
+lease or authenticate executable bytes.
 
 The dispatcher checks current authorization immediately before invoking browser
 I/O. It passes a signal combining owner revocation, channel loss, and its request
@@ -47,13 +50,16 @@ JSON. The parser allocates its bounded payload only after validating the length;
 it handles fragmented and coalesced input without repeatedly concatenating it.
 A partially received frame has a nonrenewing 35-second assembly deadline.
 
-Version 1 has only `HELLO`, `OBSERVE`, and `EXECUTE`. Both directions carry the
-version, operation, identity, strictly increasing sequence and `request-N`
-correlation ID. Execute additionally carries the distinct `action-N` ID.
-Unknown fields, methods, versions, stale identity, duplicates, missing or wrong
-correlation, malformed UTF-8/JSON and oversized frames close admission. There is
-no generic CDP, command, file, navigation-management, or runtime-management method.
-Initial target navigation remains an adapter-owned operation.
+Version 1 has `HELLO`, `OBSERVE`, `EXECUTE` and `FINISH_RECORDING`. An ok
+`FINISH_RECORDING` reply hands the channel to one bounded raw recording transfer
+(`src/browser-control/recording-transfer.ts`), after which the channel closes.
+Both directions carry the version, operation, identity, strictly increasing
+sequence and `request-N` correlation ID. Execute also carries the distinct
+`action-N` ID. Unknown fields, methods, versions, stale identity, duplicates,
+missing or wrong correlation, malformed UTF-8/JSON and oversized frames close
+admission. There is no generic CDP, command, file, navigation-management, or
+runtime-management method. Initial target navigation remains an adapter-owned
+operation.
 
 Replies acknowledge completion or contain a finite `CuaExecutorError` code and
 `not_dispatched` / `outcome_uncertain` disposition. They never include raw
@@ -70,24 +76,32 @@ failure. No exactly-once or rollback guarantee is implied by sequence IDs.
 
 ## Finite bounds
 
-| Input | Version 1 bound |
-| --- | --- |
-| Framed JSON | 12 MiB |
-| PNG bytes | 8 MiB |
-| Image dimensions | 4096 per side, at most 16,000,000 pixels |
-| Typed text and each observed string | 64 KiB UTF-8 |
-| Key chord | 16 keys, 64 characters per key |
-| Drag | 1–1024 points |
-| Coordinates, deltas, scroll position | Finite, within ±1,000,000; fractions preserved |
-| Wait | 0–30 seconds, fractions preserved |
-| Client request | 35 seconds by default; caller may choose 1–60 seconds |
-| Dispatcher request | 35 seconds including acknowledgement write |
+| Input                                | Version 1 bound                                     |
+| ------------------------------------ | --------------------------------------------------- |
+| Framed JSON                          | 12 MiB                                              |
+| PNG bytes                            | 8 MiB                                               |
+| Image dimensions                     | 4096 per side, at most 16,000,000 pixels            |
+| Typed text and each observed string  | 64 KiB UTF-8                                        |
+| Key chord                            | 16 keys, 64 characters per key                      |
+| Held keys on a pointer action        | Same bound as a key chord, at least one key         |
+| Drag                                 | 1–1024 points                                       |
+| Coordinates, deltas, scroll position | Finite, within ±1,000,000; fractions preserved      |
+| Wait                                 | 0–30 seconds, fractions preserved                   |
+| Spoken text and each heard utterance | 400 characters, 1600 bytes                          |
+| Heard speech per observation         | 4 utterances, each at most 120 seconds              |
+| Client request                       | 35 seconds by default; caller may choose up to 60 s |
+| Dispatcher request                   | 35 seconds including acknowledgement write          |
 
 Observation requires a PNG and state signature. It may include bounded URL,
-title, text, and fractional scroll position; those remain runtime-only under the
-existing loop contract. Arbitrary `appState` is refused because v1 has no closed
-schema for it. The protocol does not truncate strings, round coordinates, or
-silently drop unsupported state.
+title, text, fractional scroll position and heard speech; those remain
+runtime-only under the existing loop contract. Arbitrary `appState` is refused
+because v1 has no closed schema for it. The protocol does not truncate strings,
+round coordinates, or silently drop unsupported state.
+
+Click, double-click, move, scroll and drag may carry `heldKeys`, which the
+OpenAI provider maps from its computer tool's `keys`. The Codex participant's
+tool schema does not offer them. A guest older than this field refuses such an
+action as an invalid request.
 
 PNG admission checks signature, IHDR before decoder allocation, chunk framing,
 IDAT/IEND presence, no trailing bytes, CRCs and full decode. Version 1 admits
@@ -98,8 +112,8 @@ pixel product are checked before decoding, independently of compressed size.
 
 ## Verification boundary
 
-`tests/browser-control-protocol.test.ts`, `browser-control-transport.test.ts`
-and `browser-control-client.test.ts` exercise production schemas and framing,
+`tests/browser-control/protocol.test.ts`, `transport.test.ts`
+and `client.test.ts` exercise production schemas and framing,
 all action kinds, image limits, correlation, malformed input, revocation,
 concurrency, lost acknowledgements, backpressure and cancellation. These use
 synthetic PNGs and inert paired byte streams, with no network, model or VM calls.

package/docs/architecture/comms-inbox.md

@@ -5,11 +5,11 @@ This page describes local capture. For fresh hosted inboxes, see
 parsed renderer, strict remote-asset blocking and private lease lifecycle.
 
 The catch captures application mail without sending it to an external recipient.
-Humanish gives each participant an address and a matching
+humanish gives each participant an address and a matching
 `/inbox/for/<address-digest>` URL. The same address scope applies to list, message,
-plain view, latest-message and JSON routes. Navigating back from a missing message
+plain view, latest-message and JSON routes. Going back from a missing message
 stays in that scope. An unknown scope is empty; it never falls back to all mail.
-A lane without an assigned address receives no inbox instruction.
+A participant without an assigned address receives no inbox instruction.
 
 This works with separate participant worlds, shared worlds, and an external catch.
 Sharing an application world does not require sharing an inbox. If a lab deliberately
@@ -39,7 +39,7 @@ humanish comms catch --port 8025 --dir .humanish/mail-catch
 
 Configure your **app's** email transport to send to `http://127.0.0.1:8025`
 using its supported HTTP send configuration, or add `--smtp-port 1025` and
-point its SMTP transport at `127.0.0.1:1025`. Humanish does not change an
+point its SMTP transport at `127.0.0.1:1025`. humanish does not change an
 already-running app's environment. No real mailbox-provider credentials are
 needed. This captures mail sent by that app; it does not receive arbitrary
 internet email.
@@ -54,7 +54,7 @@ comms:
 ```
 
 Then run `humanish doctor --lab <lab>` and `humanish run <lab>`. Omit
-`recipients` to assign an address per lane automatically, or declare explicit
+`recipients` to assign an address per participant automatically, or declare explicit
 `{ lane, address }` entries for an existing roster. The participant receives its
 address and inbox URL in its mission. Verification links keep their original
 app origin; ensure they target the loopback app port selected by the lab.
@@ -71,7 +71,7 @@ retains its separate hosted-route and management-credential requirements.
 
 ## Existing external catches
 
-Upgrade the Humanish installation that runs `humanish comms catch` and **restart that
+Upgrade the humanish installation that runs `humanish comms catch` and **restart that
 catch process**, as well as upgrading the installation that starts the study. Updating
 only the study client leaves an older catch without participant routes.
 
@@ -95,7 +95,7 @@ data URL. This is not a full image decoder; malformed raster content can still f
 in the browser. Inline data URLs receive the same per-image checks. SVG, arbitrary
 attachment URLs and local paths are not fetched or converted.
 
-HTTP(S) images remain browser loads with `no-referrer`. Humanish does not fetch or
+HTTP(S) images remain browser loads with `no-referrer`. humanish does not fetch or
 proxy them server-side. Relative image URLs use the existing declared origin-rewrite
 map when available; otherwise they receive an explicit placeholder. Remote URLs that
 return errors retain the browser's alt-text fallback. The renderer does not claim to
@@ -108,7 +108,7 @@ digest-only; adding image capture does not add raw attachments to the run artifa
 ## Reproduce the contract
 
 ```bash
-pnpm exec vitest run tests/comms*.test.ts
+pnpm exec vitest run tests/comms/ tests/substrates/local/captured-inbox.test.ts
 pnpm exec tsx scripts/comms-inbox-proof.ts
 ```
 

package/docs/architecture/desktop-recording.md

@@ -1,6 +1,6 @@
 # Optional desktop recording
 
-Humanish keeps screenshots, actions, participant feedback and analysis by default.
+humanish keeps screenshots, actions, participant feedback and analysis by default.
 For continuous playback, opt into a desktop video:
 
 ```yaml
@@ -10,7 +10,7 @@ execution:
 ```
 
 Set `audio: false` for screen-only video. Omit `recording` to keep the lightweight
-snapshot recording. This applies to independent computer-use desktop lanes on
+snapshot recording. This applies to independent computer-use desktop participants on
 local Firecracker and E2B; scripted-browser, shared-world and in-process executors
 do not consume this setting and reject it before execution.
 

package/docs/architecture/desktop-sessions.md

@@ -1,9 +1,10 @@
 # Owned desktop sessions
 
-Independent hosted computer-use lanes acquire an owned desktop allocation before
-subject setup, then bind its executor after browser setup. The participant loop
-still consumes `CuaExecutor`; provisioning commands stay in the hosted adapter.
-This internal interface is not a public runtime plugin API.
+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`;
+provisioning commands stay in the desktop adapter. This internal interface is not
+a public runtime plugin API.
 
 `desktop-session.ts` holds the lifecycle contract. The allocation captures a
 resource ID and a release closure. Its ID is a record of acquisition, not
@@ -37,7 +38,7 @@ Already-absent cleanup carries a warning: the exact termination time is unknown.
 As before, desktop cost is an estimate over the host's acquisition-to-cleanup
 span, not a provider billing measurement.
 
-`CuaDesktopLane` separates desktop preparation from the participant runner:
+`ParticipantDesktop` separates desktop preparation from the participant runner:
 
 1. `prepare()` acquires and prepares the desktop. Failures still leave cleanup
    authority with the adapter.
@@ -48,33 +49,44 @@ span, not a provider billing measurement.
 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.
-6. `snapshot()` supplies the desktop facts for the existing lane outcome.
+6. `snapshot()` supplies the desktop facts for the existing participant outcome.
 
-The E2B implementation lives in `e2b-cua-desktop.ts`; its browser, media and
-subject provisioning primitives live in `e2b-cua-provisioning.ts`. Existing
-helper imports through `cua-actor-lab.ts` remain supported. The adapter never
-imports the lab runner at runtime.
+The E2B participant desktop is composed in `src/routes/computer-use/e2b-desktop/desktop.ts`, with
+its steps in the files beside it; acquisition and release are in
+`src/substrates/e2b/sandbox.ts`. The local desktop is `createLocalParticipantDesktop` in
+`src/routes/computer-use/local-vm.ts`, over
+`src/substrates/local/firecracker-desktop.ts`. Browser launch is in
+`src/substrates/e2b/desktop-browser.ts`, DevTools reads and mobile emulation in
+`src/substrates/e2b/desktop-cdp.ts`, geometry in
+`src/substrates/e2b/desktop-geometry.ts` and media 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
+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. The internal
-`CuaLaneDeps.createDesktopLane` seam is for construction and contract testing;
-it does not add a user-facing runtime option or bypass CLI admission checks.
+shell commands or manufacture E2B objects for an alternate executor. A local
+Firecracker study supplies its desktops through the `PARTICIPANT_DESKTOP` symbol on
+the hook bag (`src/routes/computer-use/participant-desktop.ts`), which no caller
+can set by name. The public `cuaHooks.createDesktopLane` is deprecated, warns once,
+and goes in the next minor; contract tests still inject a desktop through it. Neither
+bypasses CLI admission checks.
 
 Final evidence errors cannot skip desktop release. Existing bundle fields and
 desktop lifetime accounting retain their meanings; unconfirmed or retained
 desktops do not become confirmed cleanup. Provider facts remain absent when the
 adapter cannot establish them.
 
-This change supplies an internal boundary for future runtime adapters. Managed
-local execution, artifact installation, controller-death leases, capability
-admission and new media support require separate implementations and proofs.
-Independent hosted browser and terminal lanes, plus concurrent shared-world
-seats that use `runCuaLane`, use this boundary. Sequential shared-world lifecycle
-remains separate and uses the same re-exported provisioning helpers.
+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).
 
-The independent lane's `runSession` testing hook now receives a constructed
+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 `runCuaActorSession`.
 Library calls directly using `runCuaActorSession({ desktop, executorOptions })`
-remain supported; the custom in-process `buildExecutor` route is unchanged.
+still work but warn as deprecated; use `runComputerUseLoop`. A custom in-process
+executor now goes through `RunLabOptions.inProcess`, which replaces the
+deprecated `cuaHooks.buildExecutor`.

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

@@ -6,19 +6,23 @@ real public app possible without any persona-to-persona messaging.
 
 ## The two plane classes side by side
 
-| | 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 seats 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) |
-| Extra proof | — | `lobbyConvergenceDigest` (all seats on one `/lobby/CODE`) |
-
-THE HONEST DELTA. getHost = harness-minted host + synthetic-seeded attestation + authoritative
+|                     | 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) |
+| 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)                                               |
+| 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
+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
@@ -27,51 +31,62 @@ dropped: `plane.exposure` MUST be absent (claiming synthetic on a real site is a
 external-public honest-downgrade limits are REQUIRED.
 
 Why the getHost synthetic gate is deliberately NOT reachable from the app-url branch: that gate
-(`concurrentSharedWorldValidationReason` → `plane.exposure == synthetic` + a `0.0.0.0` bind +
-`subject.state.provenance == seeded`, `run.ts` verify) 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 app-url branch is validated by `externalPublicSharedWorldValidationReason` and is
-reached before the getHost gate; a snapshot regression test pins the getHost path byte-unchanged.
+(`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
+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
+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.
 
 ## The CDP lobby-code handoff barrier
 
-The crux — reading a seat's live URL mid-run — is ALREADY implemented: `makeChromeBrowserStateObserver`
-(`cua-actor-lab.ts`) runs an in-sandbox `node -e` script that resolves the seat's Chrome CDP port,
-selects the seat'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 persisted
-raw into the trace).
+Reading a participant's live URL mid-run is already implemented: `makeChromeBrowserStateObserver`
+(`src/substrates/e2b/desktop-cdp.ts`) runs an in-sandbox python3 probe
+(`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
+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` → `CuaLaneDeps` → the concurrent orchestrator. No new CDP
-code; no lobby-trivia change.
+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).
 
 Flow, a host-first barrier inside `runConcurrentSharedWorld`'s fan-out:
 
-1. **Designated host.** Exactly one roster lane carries `host: true` (validated). Its mission = create
+1. **Designated host.** Exactly one roster entry carries `host: true` (validated). Its mission = create
    the shared lobby; its browser opens `subject.appUrl`.
-2. **Latch.** The orchestrator creates `lobbyCodeLatch = deferred<string>()` before fan-out. The host
-   lane's `onObservedUrl` matches `/\/lobby\/([A-Z2-9]{6})(?:$|[/?#])/` (a locale prefix
-   `/en/lobby/CODE` and a query/hash suffix are tolerated), extracts CODE, and resolves the latch. The
-   host KEEPS PLAYING after resolving, so its window overlaps the followers'.
-3. **Barrier.** Follower lanes (`host` absent) do NOT compose a mission or open their target until
-   `await Promise.race([lobbyCodeLatch.promise, timeout(HANDOFF_DEADLINE_MS)])`. On resolve, CODE is
-   threaded into each follower's mission ("…choose Join, enter lobby code {CODE}…") — 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` 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 seat converged on ONE code.
-5. **Fail-closed timeout.** If the host never yields a `/lobby/CODE` within `HANDOFF_DEADLINE_MS`
-   (default 120s, capped by `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 records the host
-   window + a handoff-failed outcome for followers. A host that reaches the lobby but whose followers
-   fail to JOIN is a normal per-lane 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.
+2. **Latch.** `LobbyHandoff` (`src/routes/shared-world/handoff.ts`) creates a private latch before
+   fan-out. The first of three reads of the host participant resolves it: its `onObservedUrl` URL matching
+   `/\/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
+   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,
+   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.
+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
+   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.
@@ -81,14 +96,14 @@ Flow, a host-first barrier inside `runConcurrentSharedWorld`'s fan-out:
 
 ## Observed-origin convergence (not declared)
 
-The convergence proof is about what the seats OBSERVED, not what was DECLARED. `plane.publicOriginDigest`
-is the sha256-16 of the ONE origin the seats' 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
+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 seats did not converge on a single OBSERVED origin
+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
@@ -101,20 +116,21 @@ e2b-URL / host-digest redaction discipline.
 
 ## Mobile fidelity caveat
 
-The example roster runs mobile-LAYOUT seats (`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 clipped the page (0.20.3, #304), 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 seats, not
-touch devices. Do not over-read the results as true mobile-device coverage. True sub-500 rendering is
-the #221 upgrade.
+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
+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
 
-Ship the run + evidence here; native live-desktop `--expose` on the concurrent path is a clean,
-separable 0.20.1 fast-follow (its whole diff is "reuse `startExposedObserver` on the concurrent
-observer server"). Today, watch it from a phone via `humanish serve --expose --tunnel … --oauth …`
-against the run directory's Observer (the concurrent path writes artifacts continuously and attaches
-per-seat runtime stream URLs to the live Observer).
+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
+--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

@@ -38,7 +38,9 @@ before printing an issue body or issue URL.
 
 ## Command Shape
 
-Likely v0 commands:
+There are five feedback commands. Each takes `--run` and `--cwd`. All but `list`
+also take `--candidate`, or `--analysis` with `--finding`, to choose what to
+draft:
 
 ```bash
 humanish feedback list --run latest
@@ -71,18 +73,22 @@ produce a high-quality issue draft and clear filing instructions.
 
 ## Feedback States
 
-| State | Meaning | GitHub action |
-| --- | --- | --- |
-| `watch` | Useful observation, not yet work | Keep as bundle-local feedback or low-priority issue |
-| `needs_spec` | Real signal, scope unclear | Create issue with spec task |
-| `spec_ready` | Docs/spec work can clarify it | Create issue with docs-only authority |
-| `agent_ready` | Narrow enough for autonomous PR draft | Include readiness block for maintainers |
-| `blocked` | Needs human/operator input | Create or update issue with blocker |
-| `wontfix` | Accounted for and rejected | Keep in review packet; no issue by default |
+A draft's `proposed_next_state` is one of six values (`RunFeedbackCandidate` in
+`src/run/bundle.ts`). Maintainer triage beyond it, such as spec or agent
+readiness, uses the labels and the `humanish_swarm` block below.
+
+- `watch`: the dry-run contract-proof draft; the observation is not work yet.
+- `study-quality-review`: the live-run summary draft and every analysis-finding
+  draft (`src/feedback/draft.ts`).
+- `adapter-hardening`, `target-app-setup`, `actor-auth` and
+  `setup-quality-review`: feedback candidates that an adapter adds to the
+  bundle. `src/lab/adapter-extension.ts` checks the value.
 
 ## Issue Body Contract
 
-Promoted feedback should use this stable body shape:
+Promoted feedback uses this body shape. [The feedback
+contract](../contracts/feedback.md) has the full block, including its optional
+fields:
 
 ```yaml
 humanish_feedback:
@@ -94,17 +100,23 @@ humanish_feedback:
   actor: "<actor-runtime>"
   substrate: "<substrate>"
   failure_owner: "harness|target-app|actor|environment|unknown"
+  source_candidate_id: "<candidate-id>" # only when drafted from a candidate
   source_bundle: "<path-or-url>"
   evidence:
-    - "<relative artifact pointer>"
+    - path: "<relative artifact pointer>"
+      kind: "screenshot|state|review|trace|log|filesystem"
+      note: "<public-safe note>"
   redaction:
     status: passed
     notes: "no sensitive data promoted"
   idempotency_key: "<stable-key>"
-  proposed_next_state: "watch|needs_spec|spec_ready|agent_ready|blocked"
+  proposed_next_state: "watch|adapter-hardening|target-app-setup|actor-auth|setup-quality-review|study-quality-review"
+  acceptance_proof:
+    - "<command or artifact that would close this>"
 ```
 
-For maintainer/agent-ready work, the issue can also include:
+For maintainer/agent-ready work, the issue can also include this block from the
+agent-ready issue template (`.github/ISSUE_TEMPLATE/agent-ready-work.yml`):
 
 ```yaml
 humanish_swarm:
@@ -140,24 +152,25 @@ mirror it, but they do not replace it.
 
 ## Labels
 
-Initial label taxonomy:
+Label taxonomy, from `.github/labels.yml`:
 
-| Label | Meaning |
-| --- | --- |
+| Label              | Meaning                                                |
+| ------------------ | ------------------------------------------------------ |
 | `product-feedback` | Persona/user friction captured as public-safe feedback |
-| `agent-candidate` | May become autonomous work after spec/readiness |
-| `needs-spec` | Requires scope or acceptance criteria before mutation |
-| `agent-ready` | Has valid readiness block and narrow write scope |
-| `proof-required` | Cannot close without run bundle or command proof |
-| `harness` | Harness/core/observer/review work |
-| `adapter` | Product adapter work |
-| `feedback-loop` | Feedback, issue-draft, or queue plumbing |
-| `privacy-boundary` | Public/PII/PHI/secret-safety concern |
+| `agent-candidate`  | May become autonomous work after spec/readiness        |
+| `needs-spec`       | Requires scope or acceptance criteria before mutation  |
+| `agent-ready`      | Has valid readiness block and narrow write scope       |
+| `proof-required`   | Cannot close without run bundle or command proof       |
+| `area:core`        | Core run, artifact, lifecycle and verification work    |
+| `area:observer`    | Observer work                                          |
+| `area:adapters`    | Product adapter work; `adapter:*` names the adapter    |
+| `feedback-loop`    | Feedback, issue-draft, or queue plumbing               |
+| `privacy-boundary` | Public/PII/PHI/secret-safety concern                   |
 
 ## GitHub Projects
 
-Projects are useful for maintainer operating visibility, not canonical truth.
-The public CLI should not require Projects. Canonical state should live in:
+Projects are useful for maintainer operating visibility. They do not hold the
+feedback state. The public CLI should not require Projects. The state should live in:
 
 - issue body YAML blocks;
 - labels;
@@ -173,7 +186,7 @@ exists.
 ## Issue Draft Rules
 
 - Capture generously, execute rigorously.
-- Vague feedback can become `watch`; it cannot become `agent_ready`.
+- Vague feedback can become `watch`; it cannot get the `agent-ready` label.
 - A GitHub issue may say `contributes to` broader goals, but should not say
   `closes` without product proof.
 - The issue draft includes an idempotency key so maintainers can dedupe.