humanish 0.106.1 → 0.108.0

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,48 +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, `runCuaActorLab` 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`, or the deprecated `cuaHooks.buildExecutor`,
-  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 deprecated `cuaHooks.buildExecutor` without
-  `cuaHooks.buildProvider`.
+- `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:
 
@@ -237,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,14 +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`
-and the deprecated direct route runners report `HUMANISH_LAB_TASKS_UNSUPPORTED` in
-their failure envelopes, from `planLab` (`src/lab/plan.ts`) and each route's plan.
+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. The
-deprecated synthetic API, `runDryRun`, accepts no lab config or tasks. Its lab
-declaration boundary is `runLab`.
+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.

package/docs/architecture/{terminal-product-lane.md → terminal-product-route.md}

@@ -1,20 +1,14 @@
-# Terminal-product real-agent route (issue #154)
+# Terminal-product route
 
-Date: 2026-06-16 (runtime-auth contract updated 2026-09-05)
-
-Status: live terminal-product route shipped in `0.8.0`. The in-sandbox backend,
-command-scoped credential placement, exact-id cleanup proof, an interventions ledger,
-cost/no-spend ledger, caps, and product scoring/feedback hooks are implemented;
-the kept 2026-07-09 live receipt verifies 15/15 checks and `share_ready` at a
-`$0` cap. That capability receipt is not adopter replacement: no deletion
-branch has yet removed the reference adopter's bespoke generic study harness.
-See the goal packet
-([`docs/goals/terminal-product-lane/goal.md`](https://github.com/danielgwilson/humanish/blob/main/docs/goals/terminal-product-lane/goal.md))
-for the full slice plan and the safety contract.
+The live terminal-product route has shipped since `0.8.0`, with the in-sandbox runtime,
+command-scoped credential placement, exact-id cleanup proof, an interventions ledger, a cost and
+no-spend ledger, caps, and product scoring and feedback hooks. The
+[original plan](https://github.com/danielgwilson/humanish/blob/main/docs/history/goals/terminal-product-lane/goal.md)
+holds the build order and the safety contract.
 
 ## What this is
 
-A lab route for **terminal-product real-agent studies**: a real autonomous coding
+A study route for **terminal-product real-agent studies**: a real autonomous coding
 agent (Codex) discovering and using a CLI/product from its **public surfaces
 only**, running **inside an E2B shell** with declared runtime-auth placement and
 spend/time caps, emitting durable terminal/substrate/cost/no-spend/cleanup/
@@ -23,38 +17,39 @@ routes. It tests whether an autonomous agent can discover and use a CLI/product
 surface from public materials. It does not test whether a browser can click a
 local web app.
 
-It rides the established route-addition pattern (proven by the scripted-browser
-and local-app routes): a new `subject.source` × `execution.target`, a routing
-predicate, a backend enum + dispatch, a registered actor that declares the run kind in its capabilities,
+It follows the pattern the scripted-browser and local-app routes added: a new
+`subject.source` × `execution.target` pairing, a `terminal` case in `routeOf(config)`
+and its dispatch, a registered actor that declares the run kind in its capabilities,
 fail-closed cross-validation, and forward-declared warnings.
 
 ## The composition
 
-| Axis                                  | Value                                                                                                                                                     |
-| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `subject.source`                      | `terminal-product`                                                                                                                                        |
-| `subject.product`                     | `{ name, publicSurfaces[], install?, workdir?, upload? }`: the only world the agent sees                                                                  |
-| `execution.target`                    | `e2b-terminal` (or absent → implied)                                                                                                                      |
-| `execution.terminal`                  | `{ transport: exec-stream, stdin: disabled }`                                                                                                             |
-| `execution.runtimeAuth`               | `openai-env` (default) or opt-in `openai-egress`; names-only durable evidence                                                                             |
-| `execution.runtime.version`           | Optional exact `@openai/codex` version; observed before keyed execution                                                                                   |
-| `actors[0].model` / `reasoningEffort` | Forwarded to Codex; retained as declarations, not observed provider identity                                                                              |
-| `scenario.caps`                       | `{ maxUsd, maxJobs, maxMinutes }`: the blast-radius budget; `maxUsd > 0` is refused unless a `costProbe` measures spend                                   |
-| `policies`                            | `allowPrivateRepoAccess` / `allowProviderCredentials` / `allowPaymentCredentials` / `allowGitHubMutation`, all DEFAULT FALSE                              |
-| `actors[0].type`                      | `codex-exec`: a registered terminal actor (`keyPlacement: in-sandbox-command-scoped`)                                                                     |
-| `LabBackend`                          | `terminal` → `runTerminalProductLab` ([`src/routes/terminal/route.ts`](https://github.com/danielgwilson/humanish/blob/main/src/routes/terminal/route.ts)) |
+| Axis                              | Value                                                                                                                                                     |
+| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `subject.source`                  | `terminal-product`                                                                                                                                        |
+| `subject.product`                 | `{ name, publicSurfaces[], install?, workdir?, upload? }`: the only world the agent sees                                                                  |
+| `execution.target`                | `e2b-terminal` (or absent → implied)                                                                                                                      |
+| `execution.terminal`              | `{ transport: exec-stream, stdin: disabled }`                                                                                                             |
+| `execution.runtimeAuth`           | `openai-env` (default) or opt-in `openai-egress`; names-only durable evidence                                                                             |
+| `execution.runtime.version`       | Optional exact `@openai/codex` version; observed before keyed execution                                                                                   |
+| `actor.model` / `reasoningEffort` | Passed to Codex as `--model` (default `gpt-5.6-sol`) and `-c model_reasoning_effort`; declarations, not observed provider identity                        |
+| `caps`                            | `{ maxUsd, maxJobs, maxMinutes }`: the blast-radius budget; `maxUsd > 0` is refused unless a `costProbe` measures spend                                   |
+| `policies`                        | `allowPrivateRepoAccess` / `allowProviderCredentials` / `allowPaymentCredentials` / `allowGitHubMutation`, all default false                              |
+| `actor.type`                      | `codex-exec`: a registered terminal actor (`keyPlacement: in-sandbox-command-scoped`)                                                                     |
+| route                             | `terminal` → `runTerminalProductLab` ([`src/routes/terminal/route.ts`](https://github.com/danielgwilson/humanish/blob/main/src/routes/terminal/route.ts)) |
 
 Routing is `routeOf` (`src/lab/plan.ts`). It sends every `terminal-product` subject to
 this route, even with an unregistered actor, so this route refuses the actor.
-`routesToTerminalProduct(config)` also feeds the forward-declared warnings.
+`isTerminalProductComposition(config)` (`src/lab/routing.ts`) also feeds the forward-declared
+warnings.
 
 ## Repeating a terminal study with the same runtime
 
 ```yaml
-actors:
-  - type: codex-exec
-    model: gpt-5.6-sol
-    reasoningEffort: low
+actor:
+  type: codex-exec
+  model: gpt-5.6-sol
+  reasoningEffort: low
 execution:
   target: e2b-terminal
   runtime:
@@ -70,16 +65,24 @@ and reclaims its owned sandbox. When the version is omitted, the probe resolves
 
 `actor.json`, the bundle's terminal actor, and `terminal-ledgers.json` retain
 `humanish.actor-runtime.v1`: requested and observed versions, verification status,
-declared model/effort, and the usage granularity. The observed executable version
-also appears as `providerVersion`. An undeclared model stays explicitly
-`runtime_default_unobserved`; humanish does not label the runtime name as a model.
+the requested model and where it came from, declared effort, and the usage granularity.
+The observed executable version also appears as `providerVersion`.
+
+Codex's `--json` stream does not name the model it used, and its built-in default can change
+with any release. So the route always passes `--model`: the study's `actor.model`
+(`modelStatus: declared`), or humanish's participant default `gpt-5.6-sol`
+(`modelStatus: humanish_default`). Bundles written before 0.107.0 record
+`runtime_default_unobserved` with no requested model.
 Dry runs record declarations only, in a `terminal-lab.runtime.declared` event.
 
 These settings make a study's request reproducible, but do not attest the actual
-provider model or add a provider spending limit. Codex `turn.completed` usage can
-aggregate several model requests, so humanish does not use a declared model to
-infer per-request pricing tiers or fill in unknown costs. Runtime-token costs
-and the studied product's no-spend boundary still need separate interpretation.
+provider model or add a provider spending limit. humanish prices the agent's tokens from the
+requested model. Codex `turn.completed` usage sums every request in a turn, so no request's own
+size is known and no per-request long-context tier can be applied. The estimate prices every token
+at the base tier, with cached input at the cached rate, and says so with
+`basis: aggregated_turns_base_rate`. It is an estimate, not a measurement. The cost ledger
+checked against `caps.maxUsd` keeps the provider line unmeasured, and the studied
+product's no-spend boundary still needs separate interpretation.
 
 ## Runtime auth: raw-key placement and remaining provider access
 
@@ -122,11 +125,11 @@ make authenticated requests to that host from sandbox creation until teardown,
 including bootstrap/setup commands and commands launched outside Codex. Calls
 made outside Codex may be absent from its usage ledger. This mode does not impose
 a provider-side spending limit, restrict models/API paths, or make
-`scenario.caps.maxUsd` a preventive provider budget. A hard provider budget needs
+`caps.maxUsd` a preventive provider budget. A hard provider budget needs
 a separately enforced control; do not infer zero spend from an unmeasured ledger
 line.
 
-Public internet discovery stays unrestricted unless the lab already declares
+Public internet discovery stays unrestricted unless the study already declares
 `execution.egressAllow`. The mode preserves that allowlist and its deny-all
 fallback without adding hosts. If an allowlist omits `api.openai.com`, provider
 requests can fail. E2B domain allowlists are routing controls rather than strict
@@ -146,7 +149,7 @@ and [E2B's CA installer](https://github.com/e2b-dev/infra/blob/main/packages/env
 E2B's installed
 SDK documents that transformed headers override request headers. Deterministic
 request/redaction tests do not establish live wire behavior. The [2026-09-05
-transport receipt](https://github.com/danielgwilson/humanish/blob/main/docs/goals/terminal-product-lane/receipts/2026-09-05-runtime-egress-auth.md)
+transport receipt](https://github.com/danielgwilson/humanish/blob/main/docs/evidence/terminal-product/2026-09-05-runtime-egress-auth.md)
 records the controlled live header/auth checks and their scope.
 
 ## Runtime prerequisite
@@ -171,7 +174,7 @@ checks Node/npm in both ordinary and sudo shells after installation. The existin
 runtime fast path preserves user-specific installations; a later sudo product
 install can still fail if that installation is absent from sudo's PATH.
 
-The [global executable receipt](https://github.com/danielgwilson/humanish/blob/main/docs/goals/terminal-product-lane/receipts/2026-09-05-global-npm-prefix.md)
+The [global executable receipt](https://github.com/danielgwilson/humanish/blob/main/docs/evidence/terminal-product/2026-09-05-global-npm-prefix.md)
 records the regression found after the initial runtime-only proof and its stock
 desktop checks. npm documents [global executable locations](https://docs.npmjs.com/cli/v10/configuring-npm/folders#executables)
 and the [distribution built-in configuration](https://docs.npmjs.com/cli/v10/configuring-npm/npmrc#built-in-config-file).
@@ -203,100 +206,65 @@ blast radius is bounded by key scoping and budgets, not by hoping._
 
 The inversion is declared as registry metadata, not a code convention: the
 terminal actor's capabilities carry `keyPlacement: "in-sandbox-command-scoped"`.
-SLICE 1 shipped the DECLARED field + value (the contract was honest about where
-the key would go); SLICE 2's engine added command-scoped injection (only into the
-per-command `envs` of the `codex` invocation, never `Sandbox.create({envs})`)
-keyed off that capability, plus the deny-by-default credential allowlist, the
-positive-allowlist sandbox metadata, the cleanup proof, the interventions ledger,
-and a minimal fail-closed cap.
-
-## Historical SLICE 1 scope (DRY-RUN only when shipped)
-
-At SLICE 1, `runTerminalProductLab` implemented only the dry-run path: it built a valid
-`humanish.run-bundle.v1` contract bundle, honestly labeled contract-only, with:
-
-- the subject declared as a terminal-product with its public surfaces, provenance
-  **UNPINNED** (the agent drives public surfaces, not a clone; invariant 5);
-- the author mission recorded as plaintext (public-safe committed lab text) + a
-  **digest** of the full composed prompt (nothing beyond the author mission goes
-  plaintext);
-- the caps / deny-by-default policies / runtime-auth channel recorded as
-  declarations (names only; invariant 1);
-- a terminal-kind stream that is an honest **contract placeholder**: stdin
-  disabled, empty tail, `transport: snapshot`, **not** `pty` (captured
-  non-interactive exec output is never an interactive PTY; invariant 6 + the
-  goal packet's PTY ruling). SLICE 2 later added redacted exec-stream capture;
-- empty/placeholder ledgers (substrate lifecycle, command log, terminal event
-  stream, interventions, cost) that SLICE 2/3 later filled.
-
-The dry-run bundle passed the existing `verifyRun`. Terminal-specific verifier
-checks (terminal/transcript presence, lifecycle, cleanup, interventions,
-metadata allowlist, no-credential-in-artifacts, no-spend) landed in SLICE 2/3.
-
-At SLICE 1, a non-dry-run call returned a structured
-`HUMANISH_TERMINAL_AGENT_NOT_IMPLEMENTED` failure before launch or spend.
-SLICE 2 implemented the real session.
-
-SLICE 1 declared the DI seams SLICE 2 needed (`loadModule`, `buildSandbox`,
-`runtimeAuthEnv`, `detachedTimers`) on `TerminalProductLabHooks`; only the dry-run
-path was implemented in that slice. The hook bag now carries `loadModule`, `env`,
-`renderObserverFn`, `now`, `costProbe`, `score` and `deriveFeedback`
-(`src/routes/terminal/types.ts`), and `TerminalProductLabHooks` itself is deprecated
-in favor of `RunLabOptions`.
-
-## SLICE 4: the product-adapter extension seam (layer 6)
-
-This route is proof-roadmap **layer 6**: an adopter attaches product-specific
-scoring + feedback as a THIN in-repo extension WITHOUT forking core. SLICE 4
-ships the SEAM. Core ships no built-in product scorer; the adopter's scorecard
-lives in the adopter's repo:
+The route keys off that capability and injects the key only into the per-command
+`envs` of the `codex` invocation, never `Sandbox.create({envs})`. The route also
+has a deny-by-default credential allowlist, positive-allowlist sandbox metadata,
+the cleanup proof, the interventions ledger and a minimal fail-closed cap.
+
+## Test seams
+
+The route reads `env` and `scorer` from its options (`src/routes/terminal/types.ts`), and a test
+passes its seams (`desktopModule`, `renderObserver`, `now`, `costProbe`) as `LabDeps`
+(`src/lab/lab-deps.ts`).
+
+## The product-adapter extension seam
+
+An adopter attaches product-specific scoring and feedback as a thin in-repo extension, without
+forking core. Core ships the seam and no built-in product scorer; the adopter's scorecard lives in
+the adopter's repo:
 
 - **Exported contract types** a thin adapter types against from the package barrel
   (`humanish`) alone, never through a deep `src/` import: `RunBundle`,
   `RunFeedbackCandidate`, `RunAdapterScore`, `RunAdapterArtifact`, `ActorTrace`,
   `AdapterScorerModule` and `TerminalProductScoringContext`. The ledger, cost and
   no-spend shapes are reached through that context's fields, as
-  `TerminalProductScoringContext["ledgers"]`. Before this slice these were not
-  exported, which forced a fork (a thin adapter could not type against the bundle),
-  the gap issue #154 acceptance #8 names.
-- **A registrable scorer / feedback module**, `RunLabOptions.scorer` (an
+  `TerminalProductScoringContext["ledgers"]`.
+- **A registrable scorer / feedback module**, `RunStudyOptions.scorer` (an
   `AdapterScorerModule`): `score?(ctx) => RunAdapterScore | Promise<…>` and
   `deriveFeedback?(ctx) => RunFeedbackCandidate[] | Promise<…>`, where this route's
   `ctx` is a `TerminalProductScoringContext`. The older `terminalHooks.score` and
-  `terminalHooks.deriveFeedback` still work and warn as deprecated. The route calls the
-  hooks over the FULLY-ASSEMBLED, redacted evidence and attaches the results
-  (`bundle.adapterScore`, appended `bundle.feedbackCandidates`) WITHOUT core knowing
+  `terminalHooks.deriveFeedback` were removed with the bag. The route calls the
+  hooks over the fully-assembled, redacted evidence and attaches the results
+  (`bundle.adapterScore`, appended `bundle.feedbackCandidates`) without core knowing
   any product noun. Default (no hook) behavior is unchanged: the mission-based verdict
   stands alone.
 - **Adapter-namespaced product nouns.** Product-specific concepts (public
   CLI/product command observed, hosted product success-or-blocker, feedback
   id/draft, media/job/asset ids, no-media/no-provider-spend proof,
-  defection/friction risk) ride ONLY under a single namespaced field
+  defection/friction risk) ride only under a single namespaced field
   (`RunFeedbackCandidate.adapter: { namespace, data }` and
   `RunAdapterScore.{namespace, data}`) so core's enums stay product-agnostic and
   a future inert-field audit never misfires. No adopter noun is hardcoded into a
   core enum (avoiding closed-taxonomy rot); `e2b-terminal` is added to the
-  substrate enum so a terminal-agent candidate names its substrate honestly.
+  substrate enum so a terminal-agent candidate names the substrate it ran on.
 
-The seam is fail-closed: the route scrubs+redacts the returned payloads and DROPS
+The seam is fail-closed: the route scrubs+redacts the returned payloads and drops
 any malformed score/candidate with a warning, and `verifyRun` re-checks the
 surviving shapes, so a bad extension never poisons a verifiable bundle. Proven by
 `tests/routes/terminal/product-adapter-seam.test.ts` (a thin in-repo example adapter
 typing against the barrel only, registering a scorer, attaching namespaced nouns,
-emitting a candidate; the bundle verifies). At SLICE 4 this was contract proof,
-not a live rung; the later end-to-end route receipt is linked from the status
-note.
+emitting a candidate; the bundle verifies). That test is a contract proof; the
+live end-to-end route receipt is linked from the status note.
 
-The adopter's real scorecard is its OWN thin extension. The end-to-end route's
-live receipt is kept under the terminal-product goal, and true duplex PTY replay
-is deferred to SLICE 5.
+The adopter's real scorecard is its own thin extension. The end-to-end route's
+live receipt is kept under the terminal-product goal. Duplex PTY replay is not
+built.
 
 ## The reference adopter (codename-neutral)
 
-The requesting adopter is a public creative-CLI product (see issue #154 for its
-concrete public surfaces). Committed source and docs here stay codename-neutral
-per the public-surface scan; the committed CI fixture
-([`humanish/labs/terminal-product-demo.yaml`](https://github.com/danielgwilson/humanish/blob/main/humanish/labs/terminal-product-demo.yaml))
-uses a FICTIONAL mock CLI (`widgetsmith-cli`) with `example.com` surfaces. The
-adopter's real public surfaces appear only in operator-run docs and the GitHub
-issue, never in scanned committed text.
+The requesting adopter is a public creative-CLI product. Committed source and docs here
+stay codename-neutral per the public-surface scan; the committed CI fixture
+([`humanish/studies/terminal-product-demo.yaml`](https://github.com/danielgwilson/humanish/blob/main/humanish/studies/terminal-product-demo.yaml))
+uses a fictional mock CLI (`widgetsmith-cli`) with `example.com` surfaces. The adopter's
+real public surfaces appear only in operator-run docs and a GitHub issue, never in
+scanned committed text.

package/docs/contracts/README.md

@@ -0,0 +1,24 @@
+# Contracts
+
+Each page describes a shape that code outside humanish can depend on. A documented field is API;
+the types, parsers and validators in `src/` are the source of truth when a page and the code
+disagree.
+
+- [schemas.md](schemas.md): every `humanish.*` schema id, the study manifest, the library options
+  (`RunStudyOptions`) and the exports removed in 0.107.0.
+- [core.md](core.md): the records a run writes under `.humanish/runs/<id>/` and how each route
+  starts a run.
+- [run-bundle.md](run-bundle.md): `humanish.run-bundle.v1`, the evidence contract that `verify`
+  checks.
+- [policy.md](policy.md): credential, network, spend, redaction, sharing and assisted-run
+  boundaries.
+- [feedback.md](feedback.md): feedback candidates, drafts and issue URLs, which never mutate
+  GitHub.
+- [study-analysis.md](study-analysis.md): post-run analysis of retained participant evidence.
+- [study-costs.md](study-costs.md): what `humanish stats` counts as spend.
+- [errors.md](errors.md): the error code families, where each code appears, and the human
+  error shape on stderr.
+- [adapter-admission.md](adapter-admission.md): the admission limit a custom provider can raise
+  before a request is sent.
+- [adapter-fixtures.md](adapter-fixtures.md): the committed adapter fixtures and the parity checks
+  over them.

package/docs/contracts/adapter-admission.md

@@ -1,18 +1,18 @@
 # Adapter admission limits
 
-Library callers can throw `CuaAdmissionLimitError` from a custom `CuaProvider`
+Library callers can throw `ComputerUseAdmissionLimitError` from a custom `ComputerUseProvider`
 or the `fetchFn` supplied to `createOpenAiResponsesProvider` when a configured
 local control limit refuses a request **before provider dispatch**:
 
 ```ts
-import { CuaAdmissionLimitError, createOpenAiResponsesProvider } from "humanish";
+import { ComputerUseAdmissionLimitError, createOpenAiResponsesProvider } from "humanish";
 
 const provider = createOpenAiResponsesProvider({
   apiKey,
   fetchFn: async (url, init) => {
     if (localLimitReached()) {
       await recordLocalAdmissionRefusal();
-      throw new CuaAdmissionLimitError();
+      throw new ComputerUseAdmissionLimitError();
     }
     return transport(url, init);
   },