humanish 0.106.1 → 0.108.0

package/docs/architecture/actor-contract.md

@@ -1,32 +1,29 @@
 # Actor Contract
 
-Date: 2026-06-06 (current-state note updated 2026-09-30)
-
-Status: accepted contract with a partially open extension surface. Shipped: the evidence
-schema `humanish.actor-trace.v1` (`src/actors/contract.ts`) and a closed first-party
-registry of five descriptors (`src/actors/registry.ts`: `codex-app-server`,
-`openai-computer-use`, `local-agent`, `scripted-browser`, `codex-exec`). `actors[0].type`
-is a real dispatch key on the computer-use, scripted-browser, and terminal-product routes.
-Product scoring, feedback, and artifact hooks are extension seams, but public out-of-tree
-actor registration and its conformance certification are not shipped. Also not shipped: the
-full `Actor.run(input)` interface, `ApprovalPolicy`, `StagehandCuaActor`, and the
-`persona-fidelity` verify check. `RedactionHooks` ships in `src/evidence/redaction.ts`, and
-the computer-use loop takes it; the other adapters do not take it yet. Of the capabilities,
-routing checks `lanes` and `producesScreenshots` (`src/lab/routing.ts`): an actor that
-declares no screenshots cannot run on the computer-use or scripted-browser route. Decision
-6's capture-time screenshot stance was recanted in 0.6.0; see the inline notes and the
+Part of this contract ships and part is still open. Shipped: the evidence schema
+`humanish.actor-trace.v1` (`src/actors/contract.ts`) and a closed first-party registry of five
+descriptors (`src/actors/registry.ts`: `codex-app-server`, `openai-computer-use`, `local-agent`,
+`scripted-browser`, `codex-exec`). `actor.type` is a real dispatch key on the computer-use,
+scripted-browser, and terminal-product routes. Product scoring, feedback, and artifact hooks are
+extension seams, but public out-of-tree actor registration and its conformance certification are not
+shipped. Also not shipped: the full `Actor.run(input)` interface, `ApprovalPolicy`,
+`StagehandCuaActor`, and the `persona-fidelity` verify check. `RedactionHooks` ships in
+`src/evidence/redaction.ts`, and the computer-use loop takes it; the other adapters do not take it
+yet. Of the capabilities, routing checks `lanes` and `producesScreenshots` (`src/lab/routing.ts`):
+an actor that declares no screenshots cannot run on the computer-use or scripted-browser route.
+Decision 6's capture-time screenshot stance was recanted in 0.6.0; see the inline notes and the
 capture-vs-publish rule in
 [`docs/principles/invariants-and-defaults.md`](../principles/invariants-and-defaults.md).
 
-`codex-exec` is a real dispatch key for terminal-product labs, but the exported
+`codex-exec` is a real dispatch key for terminal-product studies, but the exported
 descriptor `runSession` is a fail-closed compatibility entry. Live execution is
 owned by `runTerminalProductLab`, which coordinates sandbox creation,
 command-scoped runtime auth, evidence, caps, and by-id cleanup.
 
 The `pi-agent-core` and `claude-agent-sdk` descriptors, the `app` run kind and the
-`in-process-sdk` protocol were removed. No lab route dispatched either descriptor, and a
-lab that names one now fails to parse. A signed-in Claude Code drives computer-use studies
-through `local-agent`, which plugs into the provider-neutral `CuaProvider` port
+`in-process-sdk` protocol were removed. No study route dispatched either descriptor, and a
+study that names one now fails to parse. A signed-in Claude Code drives computer-use studies
+through `local-agent`, which plugs into the provider-neutral `ComputerUseProvider` port
 (`src/actors/computer-use/loop/types.ts`, re-exported from `loop.ts`).
 
 ## Context
@@ -64,13 +61,24 @@ API surface.
    Agent SDK, Stagehand). The existing Codex app-server integration is the
    reference adapter. `pi-agent-core` was planned as the first in-process-SDK
    adapter to prove both shapes early; it shipped only as a trace mapper with no
-   route and has been removed.
-
-2. **One normalized evidence schema: `humanish.actor-trace.v1`.** Codex `item/*`
-   events, Claude `ToolUse`/`ToolResult` blocks, pi `tool_execution_*` events,
-   and computer-use `computer_call` cycles all map onto one `ActorTrace` with a
-   typed `items[]`. `humanish.codex-app-server-trace.v1` remains a back-compat
-   alias during migration.
+   route, and was removed.
+
+2. **One normalized evidence schema: `humanish.actor-trace.v1`.** Four producers map
+   their records onto one `ActorTrace` with a typed `items[]`:
+   - Codex app-server `item/*` events, protocol `json-rpc`: `codexResultToActorTrace`
+     (`src/actors/codex/app-server-actor-trace.ts`).
+   - Computer-use loop turns, protocol `cua-loop`, whether the provider returned an OpenAI
+     `computer_call` or a local agent's JSON actions: `loopResult`
+     (`src/actors/computer-use/loop/trace.ts`).
+   - Scripted-browser steps, protocol `scripted-steps`: `projectScriptedActorTrace`
+     (`src/actors/scripted-browser/actor.ts`).
+   - The terminal route's command log and terminal events, protocol `terminal-exec`:
+     `buildTerminalActorTrace` (`src/routes/terminal/trace.ts`).
+
+   The Codex app-server still writes its own `humanish.codex-app-server-trace.v1` record
+   (`CodexAppServerTrace` in `src/actors/codex/app-server-trace.ts`), which
+   `codexResultToActorTrace` converts. The Claude Agent SDK `ToolUse`/`ToolResult` and pi
+   `tool_execution_*` mappers were removed with their adapters.
 
 3. **A run is multi-turn within one trace; it stops on goal, abandonment, unrecoverable
    failure, or a wall-clock safety timeout, never on a turn cap.** Turn count is explicitly
@@ -85,7 +93,7 @@ API surface.
 4. **Redaction is injected once, never re-implemented per adapter.** Every
    adapter receives `RedactionHooks` (the shared secret/path/prompt-digest
    redaction, plus screenshot redaction) and must route all persisted evidence
-   through it. This is also where the remaining consolidation of #107 lands.
+   through it.
 
 5. **The registry refuses capability mismatches.** Each adapter declares
    `ActorCapabilities`. A scenario that needs `producesScreenshots` (a GUI
@@ -260,7 +268,13 @@ export interface Actor {
   run-bundle wiring is provider-agnostic. The artifact names differ by route: the Codex
   app-server adapter writes `events.ndjson`, `summary.json` and `transcript.txt`; a
   computer-use participant writes its trace to `actor.json` or `actors/<streamId>.json`; the
-  terminal route writes `terminal-events.ndjson` and `terminal-transcript.txt`.
+  terminal route writes `terminal-events.ndjson` and `terminal-transcript.txt`. Analysis quotes
+  only `message` and `reasoning` items, so they carry the participant's own words. The terminal
+  route reads them from the Codex `agent_message` and `reasoning` items in the raw exec JSON
+  stream, in memory, before source redaction can break a line's JSON. It removes verdict marker
+  lines, then scrubs and redacts the decoded text. The trace keeps the last 200 items within
+  128 KiB and adds a `notice` item when it leaves older ones out. The stream's last 2000
+  characters stay in the `command` item's `outputTail`.
 - **Approvals.** Call `approval.onRequest`; never embed adapter-local decline
   strings. Every call is recorded as an `items[kind=approval]`.
 - **Redaction.** Use the injected `RedactionHooks`. Never re-implement redaction
@@ -270,27 +284,27 @@ export interface Actor {
   public-safe: redacted message, coarse loop phase, last normalized UI action,
   and last screenshot reference only. Do not persist raw stacks, env values,
   target URLs, or unredacted provider payloads in the trace.
-- **Capabilities.** Declare them honestly. Routing refuses an actor whose `lanes` or
+- **Capabilities.** Declare only what the actor does. Routing refuses an actor whose `lanes` or
   `producesScreenshots` do not fit the route; the other capabilities are not checked.
-- **Cost (estimate vs. charge).** `tokenUsage.costUsd` stays RESERVED for a
+- **Cost (estimate vs. charge).** `tokenUsage.costUsd` stays reserved for a
   real, provider-returned charge (the codex path); a bare `costUsd`
   always means "the provider billed this". The optional `estimatedCost`
-  (`humanish.actor-estimated-cost.v1`) is a SEPARATE, differently-named field: a
+  (`humanish.actor-estimated-cost.v1`) is a separate, differently-named field: a
   token-derived rate-table multiply from the operator-editable `src/run/pricing.ts`,
-  labeled honestly as an estimate and projected up into `RunBundle.cost` (see
+  labeled as an estimate and projected up into `RunBundle.cost` (see
   [`../contracts/schemas.md`](../contracts/schemas.md) → Run Cost Summary And
-  Estimated Actor Cost). The CUA lab computes and attaches `estimatedCost` at the
-  lab boundary before persisting the trace, so the pure computer-use loop never
+  Estimated Actor Cost). The CUA study computes and attaches `estimatedCost` at the
+  study boundary before persisting the trace, so the pure computer-use loop never
   depends on the pricing table. An unknown model yields
   `estimatedCostUsd: null` + a `reason`, never a guessed charge.
 
-## The scripted-browser route (shipped)
+## The scripted-browser route
 
 `scripted-browser` is the deterministic, model-free browser-actuation route, distinct from
 `computer-use` (raw pixels + a model deciding actions). The registered
 `scripted-browser` actor (`src/actors/scripted-browser/`) replays a committed scenario's
-browser steps with playwright against a loopback app; the steps ARE the behavior, so
-`byoModel: false` means there is NO model, and `tokenUsage` records zeros as an affirmative
+browser steps with playwright against a loopback app; the steps are the behavior, so
+`byoModel: false` means there is no model, and `tokenUsage` records zeros as an affirmative
 $0 declaration that is true by mechanism (no provider client is importable from that code
 path). Its trace keeps the concrete driver name `provider: "browser-persona"` (matching the
 native `humanish.browser-persona-trace.v1` it also emits) with `protocol: "scripted-steps"`.
@@ -305,16 +319,16 @@ has no persona patience and no approvals.
 
 ### The time budget vs. a stuck timeout (`budget_reached`)
 
-`execution.timeoutMs` is a GENEROUS wall-clock SAFETY cap, not a goal. An open-ended
+`execution.timeoutMs` is a generous wall-clock safety cap, not a goal. An open-ended
 "watch it play" session has no success predicate, because productive play is the outcome. So
 the computer-use loop distinguishes two ways to hit the cap:
 
-- **`budget_reached`**: the deadline was reached AFTER at least one material (non-idle)
+- **`budget_reached`**: the deadline was reached after at least one material (non-idle)
   action, or a spend, adapter or token limit ended the session. This maps to `ActorStatus:
 "incomplete"`: the participant did not reach the goal, and the harness did not fail.
   `participantOutcomeOk` is false, the verdict is `fail`, and the CLI exits `2`. The trace
   `reason` and optional `stopCause` say which limit ended the session.
-- **`timed_out`**: the deadline was reached with ZERO material actions (a hung provider, an
+- **`timed_out`**: the deadline was reached with zero material actions (a hung provider, an
   idle-only stall). This maps to `ActorStatus: "timed_out"`, `participantOutcomeOk` is false, the
   verdict is `timed_out`, and the CLI exits `2`.
 
@@ -325,7 +339,7 @@ switch with no default, so a new completion reason forces a compile-time decisio
 status. ~30 min (`1_800_000`) is a reasonable default for open-ended watch; the persona
 still stops early on `goal_satisfied`/`gave_up`/`stopWhen`.
 
-Actuation-vs-spend gate: on the scripted lab route `scenario.mode: live` is still required
+Actuation-vs-spend gate: on the scripted route `mode: live` is still required
 even though provider spend is $0 by mechanism. The gate's justification there is actuation,
 not cost: a live scripted run drives a real browser against a real running app
 (state-mutating effects on the operator's app), which deserves the same affirmative
@@ -334,8 +348,8 @@ this paragraph is the record of that decision.
 
 ## Optional closing report
 
-`CuaProvider.debrief` is an optional read-only request after a structured
-`stopWhen` or dwell stop. It returns a `CuaTurn` with `closingReport` containing
+`ComputerUseProvider.debrief` is an optional read-only request after a structured
+`stopWhen` or dwell stop. It returns a `ComputerUseTurn` with `closingReport` containing
 `summary` and `frictionReports`; an empty friction list is valid. The loop rejects
 actions, pending safety checks, and invalid report shapes. It redacts accepted
 reports, records them in `ActorTrace.debrief`, and projects one readable message
@@ -350,39 +364,40 @@ from interaction turns, and reported usage contributes to aggregate cost.
 
 The OpenAI implementation makes one request with tools disabled and structured
 output; no HTTP or policy retries. Stateless/ZDR mode does not offer retrospective
-reporting because it does not retain the required session history. The
-[paired live receipt](https://github.com/danielgwilson/humanish/blob/main/docs/goals/computer-use-actor/receipts/structured-closing-report-2026-09-05.md)
+reporting: its client-carried conversation summarizes its oldest turns past a token
+budget, so it may not hold the whole session a retrospective report needs. The
+[paired live receipt](https://github.com/danielgwilson/humanish/blob/main/docs/evidence/computer-use/structured-closing-report-2026-09-05.md)
 records both report recovery and control failures in the separate legacy parser.
 
-## The state-driven executor seam (shipped)
+## The state-driven executor seam
 
-The `CuaExecutor` / `CuaProvider` ports are the concrete realization of the "plural harnesses /
+The `ComputerUseExecutor` / `ComputerUseProvider` ports are the concrete realization of the "plural harnesses /
 transport-agnostic" intent above: the computer-use loop does not require a screen or a vision
 model. A library caller can drive an **already-running local app** through its in-process JS
-contract (`window.app.getState()` etc.) with a custom `CuaExecutor` (screenshot optional,
-`appState` as the progress signal) paired with a **non-vision** `CuaProvider` (`requiresFrame`
-falsey), keeping the whole lab composition with NO E2B desktop and NO clone. See
+contract (`window.app.getState()` etc.) with a custom `ComputerUseExecutor` (screenshot optional,
+`appState` as the progress signal) paired with a **non-vision** `ComputerUseProvider` (`requiresFrame`
+falsey), keeping the whole study composition with no E2B desktop and no clone. See
 [`state-driven-executor.md`](./state-driven-executor.md) for the port, both entry points
-(`runComputerUseLoop` and `runLab` + `inProcess`/`createProvider`), the `subject.source:
+(`runComputerUseLoop` and `runStudy` + `inProcess`/`createProvider`), the `subject.source:
 local-app` config surface, the `requiresFrame` provider-authoring contract, and the
 appState-is-runtime-only stance.
 
-## The product-adapter extension seam (shipped in the terminal-product route, layer 6)
+## The product-adapter extension seam
 
-The terminal-product route carries the proof-roadmap layer-6 deliverable: a product adopter
-attaches product-specific scoring + feedback as a THIN in-repo extension WITHOUT forking
+The terminal-product route has a product-adapter extension seam: a product adopter
+attaches product-specific scoring + feedback as a thin in-repo extension without forking
 core. The seam is exported contract types (`RunBundle`, `RunFeedbackCandidate`,
 `RunAdapterScore`, `ActorTrace`, `AdapterScorerModule` and the terminal-route
-`TerminalProductScoringContext`) plus a registrable scorer module, `RunLabOptions.scorer`,
-with optional `score` and `deriveFeedback`. The older `score` / `deriveFeedback` members of
-`terminalHooks` and `cuaHooks` are deprecated. The adapter records its product nouns ONLY
-under an adapter-NAMESPACED block (`RunFeedbackCandidate.adapter` /
+`TerminalProductScoringContext`) plus a registrable scorer module, `RunStudyOptions.scorer`,
+with optional `score` and `deriveFeedback`. The older `terminalHooks` and `cuaHooks` bags were
+removed from `RunStudyOptions`. The adapter records its product nouns only
+under an adapter-namespaced block (`RunFeedbackCandidate.adapter` /
 `RunAdapterScore.{namespace,data}`), so core's enums stay product-agnostic: no adopter noun
 is hardcoded into a core enum. Default (no hook) behavior is unchanged. See
-[`terminal-product-lane.md`](./terminal-product-lane.md#slice-4-the-product-adapter-extension-seam-layer-6)
+[`terminal-product-route.md`](./terminal-product-route.md#the-product-adapter-extension-seam)
 for the full seam and the thin-adapter conformance proof.
 
-## Making personas load-bearing
+## Making personas change the actor's behavior
 
 The original bug, now fixed: `loadDryRunInputs` (`src/run/dry-run-inputs.ts`) parsed
 persona YAML down to `{ id, name, source, sourceDigest }` and discarded `summary`,
@@ -419,12 +434,33 @@ traits: { patience, skill, accessibilityNeeds? }, constraints[], sourceDigest }`
    toward the success predicate) and annotates the abandonment friction as a feedback
    candidate. The harness imposes no turn cap; its hard stops are the wall-clock
    `timeoutMs` and declared spend caps.
-4. **Bind the same directives per harness**: pi (`systemPrompt` +
-   `beforeToolCall` allow rules), Claude (`system_prompt`/`--append-system-prompt`
-   - `allowedTools`), Codex (prepend to `turn/start` input), Stagehand (agent
-     context + action policy). Each binds the friction-tolerance, skill, and
-     accessibility directives identically; none uses a `max_turns`-style cap as the
-     persona stop condition.
+4. **Bind the same directives per harness.** `renderPersonaPromptSection`
+   (`src/lab/persona.ts`) renders the directives as one prompt section, and each harness puts
+   that section where its model reads standing instructions:
+   - Computer use: `composeParticipantInstructions`
+     (`src/routes/computer-use/participant-prompt.ts`) opens the participant instructions
+     with it. `openai-computer-use` sends those instructions as each Responses request's
+     `instructions`. A local-agent Codex runs as a restricted app-server participant and
+     receives them as thread/start `baseInstructions` (`threadStartParams` in
+     `src/actors/codex/restricted-launch.ts`), on an ephemeral read-only thread whose only
+     dynamic tool is `humanish_ui`. A local-agent Claude Code runs one `claude -p`
+     stream-json session with `--allowedTools Read`; the instructions open its first user
+     message (`promptFor` in `src/actors/local-agent/cli.ts`), and later turns rely on the
+     session's memory. `HUMANISH_LOCAL_AGENT_ONE_SHOT` instead spawns one `claude -p` per
+     turn, which resends the instructions every turn.
+   - Terminal: the section opens the `codex exec` prompt (`composeLivePrompt` in
+     `src/routes/terminal/session.ts`).
+   - The scripted-browser route replays declared steps with no model, so it binds no
+     directives and records an empty `traitsApplied`. The Codex app-server session behind
+     `humanish codex app-server` and the `codex-app-server` registry descriptor binds none
+     either: it sends the operator's prompt to turn/start as given.
+   - Stagehand remains roadmap. This rule once planned a pi binding (`systemPrompt` +
+     `beforeToolCall`) and a Claude Agent SDK one (`systemPrompt` + `allowedTools`). pi
+     shipped only as a trace mapper, the Claude Agent SDK descriptor never had a route, and
+     both were removed.
+
+   None of these uses a `max_turns`-style cap as the persona stop condition.
+
 5. **Prove it.** `ActorTrace.persona.traitsApplied` lists the injected directives; a
    `persona-fidelity` verify check asserts that the friction and accessibility directives
    reached the actor input and that a `gave_up` run cites a concrete friction reason (not a
@@ -475,7 +511,7 @@ Non-obvious tradeoffs to revisit with real-run data:
 - `persona-fidelity` treats a `gave_up` with no cited friction as a fidelity
   failure, not an accepted stop, so the model cannot quietly quit for no reason.
 
-This keeps patience load-bearing and reproducible without ever using elapsed
+So patience decides when a run stops, reproducibly, without ever using elapsed
 turns as a stop signal.
 
 ## Capability matrix (target adapters)
@@ -487,41 +523,12 @@ turns as a stop signal.
 | claude-agent-sdk (removed)                                                                    | yes (SDK + `-p` stream-json) | typed ToolUse/ToolResult + cost           | OS sandbox + dontAsk/allowedTools    | Anthropic-centric       | SDK MIT (CLI proprietary) | code, app    |
 | stagehand-cua (roadmap, not shipped; `openai-computer-use` is the shipped computer-use actor) | yes (SDK, mode:'cua')        | structured results + replay               | Playwright/Browserbase isolation     | OpenAI/Anthropic/Google | MIT                       | computer-use |
 
-## Sequencing
-
-1. This document.
-2. Shared `RedactionHooks` module (completes the remaining #107 criterion) plus
-   the `Actor` contract types, with the Codex integration refactored to implement
-   `Actor` and emit `ActorTrace` behind the back-compat alias. Add an
-   `actorRegistry`; generalize `RunStream.codex` to `RunStream.actor`.
-3. Personas load-bearing: `ResolvedPersona`, `personaToDirectives`, harness turn
-   budget, and the `persona-fidelity` verify check.
-4. `pi-agent-core` adapter (proves the contract against a non-Codex protocol;
-   local-model dogfood for ~$0). Landed in two slices: first the pure
-   `piSessionToActorTrace` mapper + registry generalization (discriminated
-   `ActorDescriptor` union + `getActor` overloads) + a fixture conformance test,
-   with no pi dependency and no model key required (proves the evidence contract
-   is provider-neutral); then a follow-up live SDK shim behind a DI seam, deferred
-   until the package identity (`@earendil-works/pi-agent-core` vs
-   `@mariozechner/pi-coding-agent`) and the Node `>=22.19` vs engines `>=20` gap
-   are pinned against an installed build. The live shim never landed, and the
-   mapper-only descriptor was removed because no route dispatched it.
-5. `claude-agent-sdk` adapter (the `app` run kind). It shipped as a descriptor with
-   a live session but no route, and was removed along with the `app` run kind.
-6. Computer-use route. (Shipped as `openai-computer-use`: registered 0.3.0,
-   lab-dispatched 0.4.0; `stagehand-cua` as a multi-provider front remains
-   not-yet-shipped roadmap.)
-7. Cross-harness conformance test: one persona x scenario through every adapter,
-   asserting identical trace shape, completion vocabulary, and redaction status.
-8. The proof point: run the harness-plural loop against popular OSS repos and turn
-   real, merged issues into the receipt.
-
 ## Risks
 
 - Protocol/version drift across four moving harnesses. Pin every binary/SDK and
   assert the init handshake; the registry refuses an actor whose declared
   capabilities do not satisfy the scenario.
-- Screenshot PII in the computer-use route. Redaction binds the PUBLISH
+- Screenshot PII in the computer-use route. Redaction binds the publish
   boundary, not capture (0.6.0): raw frames stay local in gitignored
   `.humanish/` and are never emitted by a publish command (this repo's CI
   binary-asset scan also blocks them from commit);
@@ -540,4 +547,4 @@ turns as a stop signal.
 
 - Self-driving harness principles: `docs/principles/self-driving-harness.md`.
 - Observer architecture: `docs/architecture/observer.md`.
-- Related issues: shared redaction module (#107), PII/PHI detector (#108).
+- Open issue: [a PII/PHI detector for the redaction gate](https://github.com/danielgwilson/humanish/issues/108).

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,17 +62,17 @@ 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 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.
+Firecracker run supplies its desktops through the computer-use run's `localVm`
+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 study with
+`execution.target: local`. 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
@@ -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 `runCuaActorSession`.
-Library calls directly using `runCuaActorSession({ desktop, executorOptions })`
-still work but warn as deprecated; use `runComputerUseLoop`. A custom in-process
-executor now goes through `RunLabOptions.inProcess`, which replaces the
-deprecated `cuaHooks.buildExecutor`.
+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 `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,20 @@ 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`
+(for `url` and `screenshot`) or the provider's `nextTurn` (for `reasoning` and `message`). The
+handoff still passes all three.
 
 Flow, a host-first barrier inside `runConcurrentSharedWorld`'s fan-out:
 
@@ -66,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