humanish 0.107.0 → 0.108.0

package/docs/architecture/serve.md

@@ -1,33 +1,28 @@
 # Serve: the run library surface
 
-Date: 2026-08-02
-
-Status: shipped. The `loopback`, `exposed` (edge-authed) and `share-safe-open`
-modes live in `src/observer/serve.ts`, `src/observer/library.ts`,
-`src/observer/http.ts`, `src/observer/exposure.ts` and `src/observer/tunnel.ts`,
-with per-run routes and the history index in `src/observer/run-routes.ts` and the
-loopback bind in `src/observer/listen.ts`. The CLI wiring is in
+The `loopback`, `exposed` (edge-authed) and `share-safe-open` modes live in
+`src/observer/serve.ts`, `src/observer/library.ts`, `src/observer/http.ts`,
+`src/observer/exposure.ts` and `src/observer/tunnel.ts`, with per-run routes and the history
+index in `src/observer/run-routes.ts` and the loopback bind in `src/observer/listen.ts`. The CLI wiring is in
 `src/cli/commands/observe.ts`. The `/_humanish/api/*` control-plane namespace is
 reserved and answers `501`; no mutating route ships.
 
-Exposure auth is **tunnel-edge only**. As of 0.18.0 humanish carries NO
-in-process auth: the hand-rolled capability-link (cookie/token/TTL, its auth
-module and the `serve --auth link|none` flags) was removed as
-a pre-1.0 breaking change. The gate now lives entirely at the edge: ngrok
-`--oauth google` (with `--allow-email`/`--allow-domain` allow rules), or an
-operator-secured `--public-url` (Cloudflare Access, Tailscale, a reverse proxy
-you own).
+Exposure auth happens only at the tunnel edge. humanish has had no in-process auth since 0.18.0,
+which removed the capability link (cookie, token and TTL), its auth module and the
+`serve --auth link|none` flags. The gate is ngrok `--oauth google` with `--allow-email` or
+`--allow-domain` rules, or an operator-secured `--public-url` (Cloudflare Access, Tailscale or a
+reverse proxy you own).
 
 ## What serve is
 
-`humanish serve` is the third observer surface, and the first whose subject is
-the LIBRARY rather than a run:
+`humanish observe --all` is the third observer surface, and the first whose subject is
+the library rather than a run:
 
 - `humanish watch` serves one attached run: the process that created the run
   serves it and may inject runtime stream URLs for live following (see the
   stream-URL rules below and `watch --expose`);
 - `humanish observe` re-serves one finished run read-only;
-- `humanish serve` serves the whole local library under `.humanish/runs/`: a
+- `humanish observe --all` serves the whole local library under `.humanish/runs/`: a
   library index, per-run Observer pages, `/_humanish/history.json` polling, and
   optional edge-authenticated exposure beyond the machine.
 
@@ -39,11 +34,11 @@ authenticated edge (or `--safe`, see the fail-closed matrix).
 ## Fail-closed exposure matrix
 
 One shared validator (`validateExposure` in `src/observer/exposure.ts`) governs
-both `serve` and `watch`. `--expose` must always resolve to a reachable public
+both `observe --all` and `watch`. `--expose` must always resolve to a reachable public
 origin (a `--tunnel` or a `--public-url`), even under `--safe`, since an
 origin-less exposed server is an unreachable loopback no-op. With an origin
-present, exposure requires EITHER edge auth (`--oauth` on the ngrok edge, or a
-`--public-url` you secure) OR `--safe` (share_ready runs only). A tunnel with
+present, exposure requires either edge auth (`--oauth` on the ngrok edge, or a
+`--public-url` you secure) or `--safe` (share_ready runs only). A tunnel with
 neither is a wide-open public URL to local bundles and is refused.
 
 | `--expose` | `--tunnel` | `--oauth` | `--public-url` | `--safe` | Outcome                                                                                       |
@@ -51,11 +46,11 @@ neither is a wide-open public URL to local bundles and is refused.
 | no         | no         | no        | no             | any      | `loopback` (no exposure)                                                                      |
 | yes        | yes        | yes       | no             | any      | OK → `exposed` (edge-authed; all runs unless `--safe`)                                        |
 | yes        | yes        | no        | no             | yes      | OK → `share-safe-open` (public, share_ready only)                                             |
-| yes        | yes        | no        | no             | no       | **REFUSED** `HUMANISH_SERVE_EXPOSE_REQUIRES_EDGE_AUTH_OR_SAFE`                                |
+| yes        | yes        | no        | no             | no       | **refused** `HUMANISH_SERVE_EXPOSE_REQUIRES_EDGE_AUTH_OR_SAFE`                                |
 | yes        | no         | no        | yes            | any      | OK → `exposed` (operator-secured edge)                                                        |
-| yes        | no         | no        | no             | any      | **REFUSED** `HUMANISH_SERVE_EXPOSE_REQUIRES_ORIGIN` (no reachable origin, even with `--safe`) |
-| yes        | no         | yes       | no             | any      | **REFUSED** `HUMANISH_SERVE_OAUTH_REQUIRES_TUNNEL`                                            |
-| yes        | yes        | yes       | yes            | any      | **REFUSED** `HUMANISH_SERVE_OPTION_CONFLICT` (tunnel + public-url)                            |
+| yes        | no         | no        | no             | any      | **refused** `HUMANISH_SERVE_EXPOSE_REQUIRES_ORIGIN` (no reachable origin, even with `--safe`) |
+| yes        | no         | yes       | no             | any      | **refused** `HUMANISH_SERVE_OAUTH_REQUIRES_TUNNEL`                                            |
+| yes        | yes        | yes       | yes            | any      | **refused** `HUMANISH_SERVE_OPTION_CONFLICT` (tunnel + public-url)                            |
 
 Guard order (all before any bind/spawn): `--allow-email`/`--allow-domain` without
 `--oauth` → `HUMANISH_SERVE_ALLOW_REQUIRES_OAUTH`; `--oauth` without `--tunnel` →
@@ -66,8 +61,8 @@ http(s) origin → conflict; a tunnel/public-url without `--expose` →
 no `--public-url` (even under `--safe`) →
 `HUMANISH_SERVE_EXPOSE_REQUIRES_ORIGIN`; `--expose` with an origin but without
 edge auth and without `--safe` →
-`HUMANISH_SERVE_EXPOSE_REQUIRES_EDGE_AUTH_OR_SAFE`. `--oauth google` with NO
-allow rule is ALLOWED (any Google account authenticates) but pushes a prominent
+`HUMANISH_SERVE_EXPOSE_REQUIRES_EDGE_AUTH_OR_SAFE`. `--oauth google` with no
+allow rule is allowed (any Google account authenticates) but pushes a prominent
 warning recommending at least one `--allow-email`/`--allow-domain`.
 
 The `watch` surface reuses the same validator but is stricter: a live,
@@ -77,7 +72,7 @@ therefore refused outright with `HUMANISH_WATCH_SAFE_NOT_APPLICABLE` (exit 2), s
 never silently ignored.
 `watch --expose` always requires edge auth (`--tunnel --oauth` or `--public-url`),
 and is also refused with `--dry-run`/`--detach`/`--json` (no live desktop / no
-attached follow). An exposed watch serves ONLY the attached live run: its
+attached follow). An exposed watch serves only the attached live run: its
 `/_humanish/history.json` lists just that run and every other run id 404s
 byte-identically to a nonexistent one, so a remote viewer can never enumerate or
 reach any prior run's raw evidence (loopback watch still serves the full library).
@@ -122,14 +117,14 @@ which adds `sandbox allow-scripts` to that policy.
 
 | Mode              | Invocation                                                                      | Boundary class                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | ----------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `loopback`        | `humanish serve`                                                                | Capture-side trust: readable only by whoever can already read gitignored `.humanish/` on this machine; no new boundary is crossed.                                                                                                                                                                                                                                                                                                                                             |
+| `loopback`        | `humanish observe --all`                                                        | Capture-side trust: readable only by whoever can already read gitignored `.humanish/` on this machine; no new boundary is crossed.                                                                                                                                                                                                                                                                                                                                             |
 | `exposed`         | `--expose --tunnel ngrok --oauth google …`, or `--expose --public-url <origin>` | Edge-authed exposure: only viewers who clear the edge OAuth (or the operator's own edge) reach the loopback server, which then serves everything it grants unless `--safe` composes in. The gate is the edge, not humanish.                                                                                                                                                                                                                                                    |
 | `share-safe-open` | `--expose --safe --tunnel ngrok` (no `--oauth`)                                 | Genuine publishing behind the feedback-grade `share_ready` gate: only runs that pass verify are served. Each request walks the run, and any added, removed or changed file re-verifies it first; a file is read only while its inode, size, mtime and ctime match the walk verify covered, and its bytes are served only when their sha256 matches the hash taken at admission. Everything else is absent, 404ing byte-identically to a nonexistent run (no existence oracle). |
 
 ## Keep stream URLs off the library surface
 
 Live desktop stream URLs (auth-bearing hosted-VNC links) are never served by the
-LIBRARY surface, in any mode, and the guarantee is layered:
+library surface, in any mode, and the guarantee is layered:
 
 - **Structural:** runtime stream URLs live in a `WeakMap` keyed by the watch
   process's in-memory `ObserverResult` (`src/observer/render.ts`) and are never
@@ -149,12 +144,14 @@ disk). See observer.md.
 
 ## Know what `share_ready` checks
 
-`share_ready` was designed as the bar for FEEDBACK payloads: evidence eligible
+`share_ready` was designed as the bar for feedback payloads: evidence eligible
 to leave the machine inside a public issue draft. Serve's `share-safe-open` mode
-extends that same gate to arbitrary-audience BROWSING, which is a broader
-exposure of the same artifacts. The honest caveat carries over unchanged:
+extends that same gate to arbitrary-audience browsing, which is a broader
+exposure of the same artifacts. The same caveat carries over:
 `humanish verify` does not yet detect free-form PII/PHI (names, emails, medical
-identifiers; see the README's public-safety boundary and issue #108), so
+identifiers; see
+[Share evidence safely](../../README.md#share-evidence-safely) and the
+[open detector issue](https://github.com/danielgwilson/humanish/issues/108)), so
 `share_ready` means the automated secret/path scan passed, not that a human would
 publish every pixel. Maintainers should treat open mode accordingly: synthetic
 data upstream, review before exposing, and treat `--safe` without edge auth as
@@ -173,13 +170,13 @@ any mutating route ships, the contract is:
 - an operator identity distinct from a viewer, sourced from the edge/control
   plane, not from a humanish-minted cookie;
 - mutating routes require CSRF defenses appropriate to the chosen edge session;
-- the spend rule is invariant 3 applied to remote hands: a phone-initiated LIVE
+- the live-spend rule applies to remote hands too: a phone-initiated live
   run needs its own affirmative declaration at serve startup (an explicit opt-in
-  naming the lab and budget), never a default the viewer UI can reach.
+  naming the study and budget), never a default the viewer UI can reach.
 
 ## Why not Better Auth here
 
-Better Auth is a strong TypeScript auth framework, but it is deliberately NOT
+Better Auth is a strong TypeScript auth framework, but it is deliberately not
 used for this CLI serve surface: serve is an ephemeral, no-database,
 per-invocation loopback server whose only job is to hand persisted evidence to an
 already-authenticated edge. A password/session/social-login framework with a
@@ -193,6 +190,6 @@ where accounts, org membership, and durable sessions actually exist.
 - **Traffic Policy for ngrok.** Migrate off the deprecated `--oauth*` flags to a
   generated Traffic Policy YAML once ngrok requires it (the `yaml` dep is already
   available); pin the behavior in `tests/observer/tunnel.test.ts` first.
-- **Shipped in 0.18.0: `watch --expose`.** Remote LIVE following of a run,
+- **Shipped in 0.18.0: `watch --expose`.** Remote live following of a run,
   including its live E2B desktop stream, behind the same edge auth. It is the one
   surface that deliberately serves runtime stream URLs. See observer.md.

package/docs/architecture/state-driven-executor.md

@@ -1,18 +1,15 @@
-# State-driven executor (the `CuaExecutor` port)
+# State-driven executor (the `ComputerUseExecutor` port)
 
-Date: 2026-06-15
-
-Status: shipped (PR1 of issue #148). The library path (a custom executor + a
-non-vision provider, driven through the lab with NO E2B and NO vision) is
-implemented and proven. A config-only deterministic route and a
-`subject.contract.ref` JS-module loader are deferred (see "Deferred", below).
+The library path ships: a custom executor and a non-vision provider, driven through a study with
+no E2B desktop and no vision model. A config-only deterministic route and a `subject.contract.ref`
+module loader are not built (see Not built, below).
 
 ## What this is
 
 The computer-use (CUA) loop in
 [`src/actors/computer-use/loop.ts`](https://github.com/danielgwilson/humanish/blob/main/src/actors/computer-use/loop.ts) is provider- and
-substrate-agnostic by design: the model lives behind a `CuaProvider` port and the thing
-being driven lives behind a `CuaExecutor` port. Both ports are declared in
+substrate-agnostic by design: the model lives behind a `ComputerUseProvider` port and the thing
+being driven lives behind a `ComputerUseExecutor` port. Both ports are declared in
 `src/actors/computer-use/loop/types.ts`. You do not have to drive a screen with a vision
 model. You can point the loop at **an already-running local app** and drive it through that
 app's **in-process JavaScript automation contract** (e.g. `window.app.getState()`,
@@ -27,12 +24,12 @@ This is the "plural harnesses / transport-agnostic" intent of
 ## The port
 
 ```ts
-interface CuaExecutor {
-  observe(): Promise<CuaObservation>; // capture current state
-  execute(action: CuaAction, signal?: AbortSignal): Promise<void>; // perform one action
+interface ComputerUseExecutor {
+  observe(): Promise<ComputerUseObservation>; // capture current state
+  execute(action: ComputerUseAction, signal?: AbortSignal): Promise<void>; // perform one action
 }
 
-interface CuaObservation {
+interface ComputerUseObservation {
   screenshot?: Buffer; // OPTIONAL — a state executor omits it
   stateSignature: string; // REQUIRED — the fallback progress key
   appState?: Record<string, unknown>; // structured state; preferred for progress
@@ -71,9 +68,9 @@ graphically dense (pixel-art) UI. `stableProgressKey(appState)`:
 - sorts object keys, so key order never counts as progress;
 - caps depth, key count, array length, string length, and total output;
 - never throws on a cyclic or huge `appState`; it degrades to a bounded value
-  (cycles become `"[Circular]"`, over-cap nodes become markers). This is
-  correctness-load-bearing: a hostile or merely large state blob cannot crash the
-  loop.
+  (cycles become `"[Circular]"`, over-cap nodes become markers). The loop's
+  correctness depends on this: a hostile or merely large state blob cannot crash
+  it.
 
 ## A single desktop command failure is a recoverable skipped action
 
@@ -102,7 +99,7 @@ skipped: desktop command failed`, text = the public-safe action label + exit cod
   and any genuine non-`CommandExitError` adapter fault as `actor_error`.
 - **No infinite loop.** A skipped action changes nothing on screen, so it is not
   progress. A run that keeps failing every action makes no progress and still
-  terminates honestly through the existing idle / no-progress backstop
+  terminates through the existing idle / no-progress backstop
   (`gave_up`). The resilience only converts a _single flaky command_ from fatal
   to survivable; it never masks a genuinely stuck run.
 
@@ -112,7 +109,7 @@ whitespace-collapsed) and a numeric exit code, and is still run through the loop
 values, and machine paths never appear. The action label comes from
 `describeCuaAction`, which never includes typed text.
 
-## You need a NON-vision provider too
+## You need a non-vision provider too
 
 Swapping the executor is not enough. The default OpenAI computer-use provider is
 **vision-based**: it sends the screenshot as the `computer_call_output`, so a
@@ -122,7 +119,7 @@ reasons over app state).
 
 **Provider-authoring contract:**
 
-- A **vision** provider MUST set `requiresFrame: true` (the OpenAI provider does). When a
+- A **vision** provider must set `requiresFrame: true` (the OpenAI provider does). When a
   `requiresFrame: true` provider is handed a screenshot-less observation, the loop ends the
   session with a structured `harness_error` (`missingFrame` in
   `src/actors/computer-use/loop/ending.ts`). It neither crashes silently nor passes falsely.
@@ -131,10 +128,10 @@ reasons over app state).
 
 `requiresFrame` defaulting to falsey is a known third-party-author footgun (a vision
 provider that forgets to set it would get a blank-frame crash instead of a clean verdict).
-This slice accepts it because every in-tree vision provider sets it: OpenAI computer use,
+The loop accepts it because every in-tree vision provider sets it: OpenAI computer use,
 the local-agent Codex and Claude sessions, and the restricted Codex participant.
 
-## `appState` is RUNTIME-ONLY (not evidence, in this slice)
+## `appState` is runtime-only
 
 `appState` is an in-memory progress-comparison input, exactly like
 `stateSignature` (which is itself never written as text). It is **never** copied
@@ -144,35 +141,35 @@ trace. Only the derived progress key is computed in-memory and discarded.
 Why: the published-evidence scan catches only secret-_shaped_ patterns. A
 structured app blob (ids, free-form state, possibly user chat or shapeless
 tokens) is exactly the "value has no shape" gap that pattern redaction cannot
-close. So this slice does not treat `appState` as an evidence surface at all.
+close. So `appState` is not an evidence surface at all.
 
-The bundle is self-describing about it (invariant 6): when a state executor
+The bundle says so: when a state executor
 surfaces `appState`, the trace's `redaction.notes` declares that app state was
-observed each turn to drive progress detection and was NOT written to the trace.
+observed each turn to drive progress detection and was not written to the trace.
 
-A future "appState in evidence" slice MUST route a stringified projection through
-`redaction.redactText` (and the lab's `scrubText`) AND cap / whitelist fields
+A future change that puts `appState` in evidence must route a stringified projection through
+`redaction.redactText` (and the study's `scrubText`) and cap / whitelist fields
 before persisting. Pattern + literal redaction alone cannot sanitize an
 arbitrary blob.
 
-## Provenance is honestly UNPINNED (invariant 5)
+## Provenance is declared unpinned
 
 An already-running local dev server cannot be commit-pinned. The bundle does not
 silently omit a subject block. It declares the absence: `subject.source:
 app-url` with `state.provenance: "undeclared"` (the app-url "absence declared"
 marker), and a `cua-lab.subject.declared` event that states the entry is a local
-dev server driven in-process, caller-provisioned and UNPINNED, with no E2B
+dev server driven in-process, caller-provisioned and unpinned, with no E2B
 desktop created.
 
 ## Two entry points
 
 ### 1. Bare `runComputerUseLoop` (lowest level)
 
-Implement `CuaExecutor.observe()/execute()`, derive `stateSignature`/`appState`
-from your own state, pair it with a non-vision `CuaProvider`, and call
+Implement `ComputerUseExecutor.observe()/execute()`, derive `stateSignature`/`appState`
+from your own state, pair it with a non-vision `ComputerUseProvider`, and call
 `runComputerUseLoop`. You own the bundle/redaction wiring.
 
-### 2. `runLab` + `inProcess` / `createProvider` (keeps the composition)
+### 2. `runStudy` + `inProcess` / `createProvider` (keeps the composition)
 
 The supported library path keeps personas, the Observer, the evidence bundle,
 redaction, and the friction loop, while skipping E2B entirely. Start with the
@@ -185,47 +182,47 @@ node node_modules/humanish/examples/participant/run.mjs
 ```
 
 The example includes a real loopback app, HTTP state/action bridge, full config
-object (`schema: LAB_CONFIG_SCHEMA`), deterministic non-vision provider,
-`stableProgressKey`, `runLab`, verification, a printed report and `finally`
+object (`schema: STUDY_SCHEMA`), deterministic non-vision provider,
+`stableProgressKey`, `runStudy`, verification, a printed report and `finally`
 cleanup. It makes no model calls and does not demonstrate persona efficacy.
-`parseLabConfig` accepts a decoded object, not a YAML string; narrow its result
-on `.ok`, then narrow `runLab`'s result on `backend === "cua"` before accessing
-the CUA result. The example defines all helpers rather than requiring a consumer
-to reconstruct them.
+`parseStudy` accepts a decoded object, not a YAML string; narrow its result
+on `.ok`, then narrow `runStudy`'s result on `route === "computer-use"` before
+reading the computer-use result. The example defines all helpers, so a consumer does not
+reconstruct them.
 
-Pass `inProcess: { executor }` and `createProvider` in `RunLabOptions`. The type requires
+Pass `inProcess: { executor }` and `createProvider` in `RunStudyOptions`. The type requires
 `createProvider` beside `inProcess`: a state executor returns no frame, so it needs a non-vision
-provider. With `inProcess` set, the computer-use route takes a branch that NEVER
+provider. With `inProcess` set, the computer-use route takes a branch that never
 loads the E2B module, creates a sandbox, runs `prepareDesktop`, provisions a
 clone, opens a browser, or starts a stream. `sandboxId`/`streamUrl` stay
 undefined, so `result.sandbox` is omitted. That omission is the verifiable
 "no E2B SDK call" proof.
 
-Fail-closed guards, all BEFORE any key check, so a CLI invocation never sees a misleading
-`HUMANISH_CUA_LAB_KEYS_MISSING` first:
+Fail-closed guards, all before any key check, so a CLI invocation never sees a misleading
+`HUMANISH_COMPUTER_USE_KEYS_MISSING` first:
 
-- `HUMANISH_LAB_OPTION_UNSUPPORTED`: `inProcess` without `createProvider` (from JavaScript,
+- `HUMANISH_STUDY_OPTION_UNSUPPORTED`: `inProcess` without `createProvider` (from JavaScript,
   where the type does not stop it), or on a subject other than `app-url` or `local-app`.
   `createProvider` alone is allowed; that is a model swap on the normal E2B route.
-- `HUMANISH_CUA_LAB_FANOUT_INVALID`: `inProcess` with more than one participant. The planner refuses it, because fan-out gives each participant
+- `HUMANISH_COMPUTER_USE_FANOUT_INVALID`: `inProcess` with more than one participant. The planner refuses it, because fan-out gives each participant
   its own E2B desktop and the in-process route has none.
-- `HUMANISH_CUA_LAB_LOCAL_APP_NO_EXECUTOR`: a `subject.source: local-app` config run
+- `HUMANISH_COMPUTER_USE_LOCAL_APP_NO_EXECUTOR`: a `subject.source: local-app` config run
   without `inProcess` (there is no built-in in-process driver yet). A structured error,
   never a desktop attempt.
-- `HUMANISH_CUA_LAB_LOCAL_DESKTOP_MISSING`: an `app-url` lab with `execution.target: local`
-  and no local desktop. `runLab` gives a local browser study its desktop; a direct route
-  call or an in-process executor on the same lab has none.
-- `HUMANISH_CUA_LAB_EXECUTOR_NO_PROVIDER`: the route's internal executor hook without its
-  provider hook. A package caller gets `HUMANISH_LAB_OPTION_UNSUPPORTED` above instead.
+- `HUMANISH_COMPUTER_USE_LOCAL_DESKTOP_MISSING`: an `app-url` study with `execution.target: local`
+  and no local desktop. `runStudy` gives a local browser study its desktop; a direct route
+  call or an in-process executor on the same study has none.
+- `HUMANISH_COMPUTER_USE_EXECUTOR_NO_PROVIDER`: the route's internal executor hook without its
+  provider hook. A package caller gets `HUMANISH_STUDY_OPTION_UNSUPPORTED` above instead.
 
-Key gating is route-aware: the in-process route uses the caller's OWN model and
+Key gating is route-aware: the in-process route uses the caller's own model and
 executor, so no `OPENAI_API_KEY`/`E2B_API_KEY` is required.
 
 ## A note on `appState` typing
 
-`CuaObservation.appState` is `Record<string, unknown> | undefined` under the
+`ComputerUseObservation.appState` is `Record<string, unknown> | undefined` under the
 repo's strict flags (`exactOptionalPropertyTypes`, `noUncheckedIndexedAccess`).
-A value typed as an `interface` does NOT satisfy `Record<string, unknown>`
+A value typed as an `interface` does not satisfy `Record<string, unknown>`
 (interfaces have no implicit index signature), and a direct `as Record<...>` cast
 on an interface-typed value is rejected. Use one of:
 
@@ -236,15 +233,15 @@ on an interface-typed value is rejected. Use one of:
 Read every optional field defensively, and spread-omit optional fields
 (`...(x === undefined ? {} : { x })`) rather than assigning `undefined`.
 
-## Deferred (tracked, not shipped here)
+## Not built
 
-- **PR2: a config-only deterministic `state-contract` route.** A registered,
+- **A config-only deterministic `state-contract` route.** A registered,
   model-free route driving a built-in `window.app.*` bridge over the existing
-  `ScriptedPageLike.evaluate` primitive + a YAML step program, `scenario.mode:
-live` gating actuation. It would be deterministic step replay, NOT
+  `ScriptedPageLike.evaluate` primitive + a YAML step program, `mode: live`
+  gating actuation. It would be deterministic step replay, not
   `runComputerUseLoop`, and must not overclaim friction-loop reuse.
-- **PR3: a `subject.contract.ref` JS-module loader.** A config-referenced module
-  loaded and run in-process with full harness privileges is a genuinely NEW trust
+- **A `subject.contract.ref` JS-module loader.** A config-referenced module
+  loaded and run in-process with full harness privileges is a genuinely new trust
   surface with no precedent in this repo (the scripted route loads only declarative
   YAML; serve commands run isolated inside the disposable E2B sandbox). It earns
   its place only behind its own clamping / trust / digest-pinning design.

package/docs/architecture/task-protocol-support.md

@@ -1,6 +1,6 @@
 # Task protocol support
 
-`actors[0].tasks` adds a participant protocol to the mission. Goals reach the
+`actor.tasks` adds a participant protocol to the mission. Goals reach the
 participant; hidden success criteria go only to the observation tracker. A route
 that cannot carry both halves refuses the declaration before execution. Removing
 `tasks` is an explicit choice to run a mission-only study, not an automatic fallback.
@@ -14,7 +14,7 @@ that cannot carry both halves refuses the declaration before execution. Removing
 | Shared-world, provisioned or external-public          | Rejected     | Actor specs omit the protocol before CUA session dispatch                                     |
 | Terminal-product                                      | Rejected     | Terminal prompt and result contract do not implement tasks                                    |
 | Scripted-browser, local or provisioned                | Rejected     | Scenario steps drive the participant; no task protocol is consumed                            |
-| Synthetic (`this-repo`)                               | Rejected     | Lab dispatch does not pass task declarations to the dry-run engine                            |
+| Synthetic (`this-repo`)                               | Rejected     | Study dispatch does not pass task declarations to the dry-run engine                          |
 | Any second or later `actors[]` entry                  | Rejected     | Current runners consume only the first actor; declare every participant under the first actor |
 
 Both registered CUA actors (`openai-computer-use` and `local-agent`) share the CUA
@@ -22,12 +22,12 @@ session loop. Their task support does not depend on which provider chooses actio
 Custom session hooks remain caller-owned implementations of that same contract;
 this preflight does not certify arbitrary hook behavior.
 
-The parser reports `HUMANISH_LAB_INVALID` with the unsupported field path. `runLab`
-reports `HUMANISH_LAB_TASKS_UNSUPPORTED` in the route's failure envelope, from
+The parser reports `HUMANISH_STUDY_INVALID` with the unsupported field path. `runStudy`
+reports `HUMANISH_STUDY_TASKS_UNSUPPORTED` in the route's failure envelope, from
 `planLab` (`src/lab/plan.ts`) and each route's plan.
 Refusal precedes run storage, source preparation, user hooks, local processes,
 sandbox allocation, and model calls. No task content appears in the error.
 
 A future route gains support only after proving participant goals, hidden criteria,
-observation-backed completion, honest missing-input treatment, and per-participant
+observation-backed completion, explicit missing-input handling, and per-participant
 bundle evidence together. Appending goals to a prompt alone is insufficient.