humanish 0.107.0 → 0.108.0

package/ARCHITECTURE.md

@@ -5,9 +5,9 @@ fails when a path in it no longer exists, or when a file named beside a function
 longer declares that name. [CONTEXT.md](CONTEXT.md) defines the domain terms, and
 [docs/decisions/](docs/decisions/README.md) records the decisions behind the rules below.
 
-## Follow one `humanish run <lab>` from manifest to findings
+## Follow one `humanish run <study>` from manifest to findings
 
-The steps follow a live computer-use lab on a hosted E2B desktop. Every route shares steps 1, 2, 7
+The steps follow a live computer-use study on a hosted E2B desktop. Every route shares steps 1, 2, 7
 and 8. Steps 3 to 6 run in the route's admit function and the `run()` it returns, which `runLab`
 reaches through `admitPlan` (`src/run-lab.ts`):
 
@@ -31,7 +31,7 @@ not.
 1. **Parse.** `runLabCommand` (`src/cli/commands/lab-run.ts`) calls `resolveLabManifest`
    (`src/lab/discover.ts`), which calls `parseLabConfig` (`src/lab/config.ts`). It rejects unknown
    keys and the compositions the
-   [support matrix](docs/ramp/README.md#check-which-compositions-a-lab-can-declare) refuses. A
+   [support matrix](https://github.com/danielgwilson/humanish/blob/main/docs/ramp/README.md#check-which-compositions-a-lab-can-declare) refuses. A
    refusal exits with code 2 before a run id exists.
 2. **Plan.** The route's CLI setup, here `computerUseRouteRun`
    (`src/cli/commands/lab-route-computer-use.ts`), hands off to `runRoute`
@@ -70,7 +70,7 @@ not.
    `buildObserverData` (`src/observer/data.ts`).
 8. **Analysis.** `completeAutomaticAnalysis` (`src/analysis/automatic-completion.ts`) runs
    `runAutomaticAnalysis` (`src/analysis/automatic.ts`) on the `FinishedRun` that `Run.finish`
-   issued. Dry runs and labs with `review.analysis: false` skip it.
+   issued. Dry runs and studies with `review.analysis: false` skip it.
 
 ## Find the code for each part of the system
 
@@ -78,8 +78,9 @@ not.
 | -------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------- |
 | `src/cli/`                 | The commander program, with one file per command family in `commands/`                 | `src/cli/program.ts`                |
 | `src/keys/`                | Provider key discovery: env files, the user key store and key-source probes            | `src/keys/key-resolution.ts`        |
-| `src/run-lab.ts`           | `runLab`: plan the lab once, then run the plan on its route                            | `src/run-lab.ts`                    |
+| `src/run-lab.ts`           | `runLab`: plan the study once, then run the plan on its route                          | `src/run-lab.ts`                    |
 | `src/lab/`                 | Manifest parsing and warnings (`config.ts`, `parse/`), types, routing and planning     | `src/lab/plan.ts` for planning      |
+| `src/study/`               | Where study files live: the studies/ and labs/ directories and the name check          | `src/study/files.ts`                |
 | `src/routes/`              | One folder per route; `routeOf` in `src/lab/plan.ts` picks it                          | `src/lab/plan.ts`                   |
 | `src/routes/computer-use/` | Computer-use participants and the desktops composing `src/substrates/` with route code | `src/routes/computer-use/route.ts`  |
 | `src/routes/scripted/`     | Committed scenario steps replayed on a loopback app or a provisioned clone             | `src/routes/scripted/route.ts`      |
@@ -98,10 +99,10 @@ not.
 | `src/tui/`                 | The CLI side of `humanish tui`                                                         | `src/tui/launch.ts`                 |
 | `src/browser-control/`     | The host-guest browser control protocol                                                | `src/browser-control/protocol.ts`   |
 | `src/guest/`               | The guest runtime that the local VM image runs: bootstrap, desktop, input and media    | `src/guest/runtime.ts`              |
-| `observer/`                | The Observer page, a single-file Vite build                                            | `observer/AGENTS.md`                |
-| `tui/`                     | The Ink terminal app                                                                   | `tui/AGENTS.md`                     |
-| `site/`                    | humanish.dev and its user docs in `site/content/docs/`                                 | `site/AGENTS.md`                    |
-| `humanish/`                | This repo's own labs, personas, scenarios, fixtures and coverage notes                 | `humanish/labs/first-run.yaml`      |
+| `observer/`                | The Observer page, a single-file Vite build                                            | `observer/README.md`                |
+| `tui/`                     | The Ink terminal app                                                                   | `tui/README.md`                     |
+| `site/`                    | humanish.dev and its user docs in `site/content/docs/`                                 | `site/README.md`                    |
+| `humanish/`                | This repo's own studies, personas, scenarios, fixtures and coverage notes              | `humanish/studies/first-run.yaml`   |
 | `examples/`                | Library examples shipped in the npm package: a participant and a scorer                | `examples/README.md`                |
 | `adapters/`                | Adapter fixture sets that `tests/lab/adapter-fixtures.test.ts` checks                  | `adapters/fixtures/README.md`       |
 | `bench/`                   | Benchmark apps with planted defects and their dated results                            | `bench/DEFECTS.md`                  |
@@ -118,11 +119,15 @@ when a row names a folder that is gone; add the row with the folder. Participant
 three guest entry files stay at the `src/` root
 ([why](docs/architecture/guest-desktop.md#three-guest-files-stay-at-the-src-root)), and six
 `tests/` folders sit outside the mirror
-([list](CONTRIBUTING.md#find-the-test-folders-outside-the-src-mirror)).
+([list](https://github.com/danielgwilson/humanish/blob/main/CONTRIBUTING.md#find-the-test-folders-outside-the-src-mirror)).
 
-## Keep these invariants when you change code
+## Keep these code guarantees when you change code
 
-| Invariant                                                                                                                | Enforced by                                                                                                                                                                                                                                                                                                                                   | Pinned by                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+Each row names the code that enforces a guarantee and the tests that pin it. The product's
+numbered invariants are in [invariants and defaults](docs/principles/invariants-and-defaults.md#invariants);
+comments name an invariant by its rule.
+
+| Guarantee                                                                                                                | Enforced by                                                                                                                                                                                                                                                                                                                                   | Pinned by                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | The run bundle is the source of truth, and the Observer derives from it                                                  | `verifyRun` grades only `run.json` and its artifacts (`src/verify/verify.ts`). It reads `status.json` and the sandbox and reclaim receipts only for the `RUN_NOT_FINISHED` warning (`runNotFinishedWarnings` in `src/verify/liveness.ts`), which changes no check and no grade. `buildObserverData` takes the bundle (`src/observer/data.ts`) | `tests/observer/data-contract.test.ts`; `tests/verify/run-not-finished.test.ts` checks that the grades are the same when `status.json` contradicts the bundle or is gone; `docs/decisions/0001-run-bundle-is-the-source-of-truth.md`                                                                                                                                                                                                                                           |
 | Unsupported execution is refused before side effects                                                                     | `parseLabConfig` (`src/lab/config.ts`), `taskProtocolValidationReason` (`src/lab/validation.ts`), `planComputerUseLab` (`src/routes/computer-use/plan.ts`)                                                                                                                                                                                    | `tests/admission/library.test.ts` checks each library refusal for a run directory, a desktop module load, a caller executor or provider, and a subprocess; `tests/admission/cli.test.ts` checks each CLI refusal for a run directory, a started process and a scorer's host code; `tests/lab/task-route-preflight.test.ts`; `pnpm cli:preflight:test` runs `scripts/task-route-preflight-proof.mjs` with `tests/fixtures/task-route-preflight/deny-side-effects.mjs` preloaded |
@@ -132,16 +137,16 @@ three guest entry files stay at the `src/` root
 | A run is closed on every exit, only a published run is analyzed, and `latest.json` moves only after its run is published | `runScope` and `FinishedRun` (`src/run/run.ts`); `completeAutomaticAnalysis` requires an issued `FinishedRun` for the result's run; `Run.finish` writes `latest.json` last through `writePreparedRunLatestPointer` (`src/run/contained-output.ts`)                                                                                            | `tests/run/run-lifecycle.test.ts`, which also checks that `src/run/run.ts` is the pointer's one writer, `tests/analysis/automatic-analysis.test.ts`                                                                                                                                                                                                                                                                                                                            |
 
 The receipt write is best-effort; the sandbox's server-side timeout ends a sandbox with no
-receipt. A lab preflight probe journals its receipt with `withPreflightSandbox`
+receipt. A study check probe journals its receipt with `withPreflightSandbox`
 (`src/lab/preflight-probes.ts`), and `humanish reclaim --preflight` (`src/run/reclaim.ts`) kills
 what a failed probe left. [Trust boundaries](https://github.com/danielgwilson/humanish/blob/main/site/content/docs/trust-boundaries.mdx) gives the
 probe timeouts.
 
 ## Read next
 
-- [docs/architecture/project-layout.md](docs/architecture/project-layout.md): the `humanish/`
+- [Project layout](https://humanish.dev/docs/project-layout): the `humanish/`
   and `.humanish/` folders in a project that runs studies.
-- [docs/ramp/README.md](docs/ramp/README.md#check-which-compositions-a-lab-can-declare): the
-  support matrix, which compositions a lab can declare and which tests pin each row.
-- [CONTRIBUTING.md](CONTRIBUTING.md#make-your-first-change): a first change, offline, and the
+- [docs/ramp/README.md](https://github.com/danielgwilson/humanish/blob/main/docs/ramp/README.md#check-which-compositions-a-lab-can-declare): the
+  support matrix, which compositions a study can declare and which tests pin each row.
+- [CONTRIBUTING.md](https://github.com/danielgwilson/humanish/blob/main/CONTRIBUTING.md#make-your-first-change): a first change, offline, and the
   tests and contracts that common changes touch.

package/CHANGELOG.md

@@ -8,6 +8,20 @@ The Unreleased section holds the full notes for the next version until it is tag
 
 ## Unreleased
 
+## 0.108.0: Studies, one runner and one viewer, errors on stderr (2026-10-03)
+
+humanish 0.108.0 renames labs to studies. A study file is `humanish.study.v3` under
+`humanish/studies/`, and `humanish migrate` converts a `humanish.lab.v2` file, which still runs with
+a warning until 0.109.0. The commands follow: `humanish study list`, `study show` and `study check`,
+and `--study` in place of `--lab`. `humanish run <study>` is the one runner and `humanish observe`
+the one viewer: `lab run`, `serve` and `watch --run` are hidden aliases that warn, and `--sims`,
+`--lanes` and `watch --follow` are gone. Error codes and route results name the study and the
+route: `HUMANISH_LAB_*` is `HUMANISH_STUDY_*`, and every route's result is
+`humanish.study-result.v1`. Human-mode errors print on stderr in one shape, and `--json` output
+keeps its shape. The release notes list each rename and what to change.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.108.0)
+
 ## 0.107.0: A 44-name library API, --count and --participants (2026-10-02)
 
 humanish 0.107.0 removes the library surfaces 0.106.0 deprecated, so the entry point exports 44

package/CONTEXT.md

@@ -1,39 +1,44 @@
 # Glossary
 
-Use one word per concept. Docs and new code use the terms in the first table. Some lab, bundle and
-output fields keep older spellings; the second table maps them.
+humanish is "Synthetic user research for apps, CLIs, and agent-facing product flows." README.md line
+3, package.json, `humanish --help`, bare `humanish` and the humanish skill use that sentence
+(`PRODUCT_SENTENCE` in `src/cli/product-sentence.ts`), and tests/cli/product-sentence.test.ts holds
+them equal.
 
-| Term                | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Where it lives in the code                                                                                                                                                                                                                                                                                                                                                                                |
-| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| study               | The prose word for everything one `humanish run <lab>` produces: participants, evidence and analysis. Each study writes one run.                                                                                                                                                                                                                                                                                                                                                                                                  | No type of its own; see run.                                                                                                                                                                                                                                                                                                                                                                              |
-| run                 | One execution on disk: `.humanish/runs/<runId>/`, with `run.json` (`humanish.run-bundle.v1`) as the source of truth.                                                                                                                                                                                                                                                                                                                                                                                                              | `src/run/`; `RunBundle` in `src/run/bundle.ts`                                                                                                                                                                                                                                                                                                                                                            |
-| lab                 | A YAML manifest that declares a study: `humanish/labs/<id>.yaml`, schema `humanish.lab.v2`.                                                                                                                                                                                                                                                                                                                                                                                                                                       | `src/lab/`; `LabConfig` in `src/lab/types.ts`, parsed by `parseLabConfig` in `src/lab/config.ts`                                                                                                                                                                                                                                                                                                          |
-| participant         | One simulated person, or agent, taking part in a study. The planner builds each one's record (id, persona id, assignment, labels and the route's own fields). Shared-world participants resolve the plan's records; computer-use participants rebuild the same records from the lab config with `computerUseParticipants` (`src/lab/plan-participants.ts`) and resolve those. `ResolvedParticipant` adds the bundle ids, persona and prompt. `run.json` records each one as a `simulations[]` entry with one or more `streams[]`. | `ResolvedParticipant` in `src/run/participant.ts`; the planned records in `src/lab/plan-participants.ts`. Computer-use and shared-world participants run a `DesktopParticipantRun` (`src/routes/computer-use/types.ts`). The terminal session (`src/routes/terminal/session.ts`), scripted surfaces (`src/routes/scripted/plan.ts`) and fixture simulations (`src/run/dry-run.ts`) still build their own. |
-| persona             | Who a participant is: traits, background, device. `humanish/personas/<id>.yaml`.                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `src/lab/persona.ts`, `src/lab/persona-resolve.ts`                                                                                                                                                                                                                                                                                                                                                        |
-| mission             | The free-form brief a model-driven participant receives: `actors[].mission`. `actors[].tasks[]` adds discrete tasks: each has a `goal` the participant sees and an optional `success` check it does not.                                                                                                                                                                                                                                                                                                                          | `LabActor` in `src/lab/types.ts`                                                                                                                                                                                                                                                                                                                                                                          |
-| assignment          | What one participant was asked to do: the mission, a `lanes[]` entry's `instruction` or `laneFocus.instruction` (recorded as `focus`), and the tasks. Each stream records it as `streams[].assignment`.                                                                                                                                                                                                                                                                                                                           | `participantAssignment` in `src/lab/participant-assignment.ts`; `RunParticipantAssignment` in `src/run/streams.ts`                                                                                                                                                                                                                                                                                        |
-| scenario            | Two things share the word. The lab's `scenario` block holds run settings: `mode` (`dry-run` or `live`), `caps`, and an optional `ref`. The `ref` names a scenario file, `humanish/scenarios/<id>.yaml` (`humanish.scenario.v1`): a goal and ordered steps with expectations. Only the scripted-browser route executes those steps. A model-driven participant follows its mission.                                                                                                                                                | `LabScenario` in `src/lab/types.ts`; `src/routes/scripted/route.ts` resolves the scenario, and `executeBrowserPersonaStep` (`src/actors/scripted-browser/steps.ts`) runs each step                                                                                                                                                                                                                        |
-| surface             | One browser viewport that a scripted run replays its journey on: `desktop` or `mobile`. A scripted lab runs the desktop surface by default, and `actors[0].count: 2` adds the mobile one. Each surface writes `actor-<surface>.json` and `traces/<surface>.json`.                                                                                                                                                                                                                                                                 | `BrowserSurface` and `browserSurfaces` in `src/actors/scripted-browser/types.ts`; the plan's `surfaces` in `src/routes/scripted/plan.ts`                                                                                                                                                                                                                                                                  |
-| journey             | A scenario's `browser.steps` parsed into ordered steps with a goal and a start path. The scripted route replays it once on each surface, and each surface's session reports the first step that did not pass.                                                                                                                                                                                                                                                                                                                     | `BrowserPersonaJourney` in `src/actors/scripted-browser/types.ts`; `parseBrowserPersonaJourneyFromScenario` in `src/actors/scripted-browser/journey.ts`                                                                                                                                                                                                                                                   |
-| subject             | The product under study, declared by `subject.source`: `clone`, `app-url`, `local-tree`, `terminal-product`, `desktop-cli`, `local-app` or `this-repo`. `run.json` records its provenance under `subject`.                                                                                                                                                                                                                                                                                                                        | `LabSubject` in `src/lab/types.ts`, parsed in `src/lab/parse/subject.ts`                                                                                                                                                                                                                                                                                                                                  |
-| actor               | The model or program that drives a participant, declared by `actors[0].type`, e.g. `openai-computer-use`, `local-agent`, `scripted-browser`, `codex-exec`.                                                                                                                                                                                                                                                                                                                                                                        | `src/actors/`; `actorRegistry` in `src/actors/registry.ts` lists them, plus `codex-app-server`, which no lab can name; `ActorTrace` in `src/actors/contract.ts` is its record                                                                                                                                                                                                                             |
-| run kind            | What an actor can do: `code`, `computer-use`, `scripted-browser` or `terminal`. An actor declares its run kinds in `capabilities.lanes`, and its trace records the one it ran as `lane`; neither field names a participant. Routing admits a lab's actor only for a run kind it declares. `computer-use` and `terminal` name both a run kind and a route, but a route is where a lab runs and a run kind is what an actor does.                                                                                                   | `ActorRunKind` in `src/actors/contract.ts`; `actorResolvesToComputerUse` (`src/lab/routing.ts`) and its siblings                                                                                                                                                                                                                                                                                          |
-| adapter             | Product-specific code kept out of core. A lab names a scorer module in `review.scorer.ref`, or the CLI passes `--scorer`, and a library caller passes the same functions as `RunLabOptions.scorer`: `score`, `deriveFeedback` and `deriveArtifacts`. Their output is stored under the adapter's namespace in `run.json` (`adapterScore`, `adapterArtifacts` and a feedback candidate's `adapter`).                                                                                                                                | `AdapterScorerModule` in `src/lab/adapter-scorer-loader.ts`; `applyBrowserScorer` in `src/lab/adapter-extension.ts`; fixture sets in `adapters/`                                                                                                                                                                                                                                                          |
-| computer use        | A model drives a participant by reading screenshots of a desktop and acting with mouse and keyboard. `openai-computer-use` and `local-agent` are the computer-use actors. CUA is the short form in code names such as `CuaExecutor` and in the older spellings listed under `cua` below.                                                                                                                                                                                                                                          | `src/routes/computer-use/`, `src/actors/computer-use/`                                                                                                                                                                                                                                                                                                                                                    |
-| fan-out             | A computer-use run with more than one participant, each on its own desktop, or any rerun. It writes the fan-out bundle shape and passes only when every expected participant passes. One participant without a rerun keeps the single-participant shape.                                                                                                                                                                                                                                                                          | `buildCuaFanoutBundle` in `src/routes/computer-use/fanout-bundle.ts`; `judgeComputerUseRun` in `src/routes/computer-use/bundle.ts`                                                                                                                                                                                                                                                                        |
-| route               | The execution path for a lab: `computer-use`, `shared-world`, `scripted`, `terminal` or `preview`. `preview` writes a dry-run bundle for `this-repo` subjects with no live participant.                                                                                                                                                                                                                                                                                                                                           | `routeOf` and `LabRoute` in `src/lab/plan.ts`; predicates in `src/lab/routing.ts`; one folder or file per route in `src/routes/`                                                                                                                                                                                                                                                                          |
-| plan                | What `planLab` decides about a lab before anything runs: the lab id, whether it is a dry run, the analysis settings and the keys, connections and env vars the run needs, plus the route's participants, caps and own fields. There is one variant per route. `planLab` returns a plan, or a refusal with the route's error code, and the route's run function (`runComputerUsePlan` and the others) takes the plan.                                                                                                              | `LabPlan` in `src/lab/plan-types.ts`; `planLab` in `src/lab/plan.ts`; each route's planner in its `plan.ts`                                                                                                                                                                                                                                                                                               |
-| substrate           | Where a participant's desktop or shell runs: a hosted E2B sandbox, or a local Firecracker VM (inside Lima on macOS).                                                                                                                                                                                                                                                                                                                                                                                                              | `src/substrates/e2b/`, `src/substrates/local/`                                                                                                                                                                                                                                                                                                                                                            |
-| participant desktop | The desktop one computer-use or shared-world participant drives: a substrate plus the route's concerns, such as subject provisioning, comms and the participant's plan. It lives in the route, so `src/substrates/` holds only provider primitives ([ADR 0004](docs/decisions/0004-participant-desktops-stay-in-the-route.md)).                                                                                                                                                                                                   | `ParticipantDesktop` in `src/routes/computer-use/participant-desktop.ts`; `createE2BParticipantDesktop` in `src/routes/computer-use/e2b-desktop/desktop.ts`; the local VM's in `src/routes/computer-use/local-vm.ts`                                                                                                                                                                                      |
-| receipt             | A line in a run's `sandbox-receipts.ndjson` that records a sandbox's id, provider, the participant or subject it belongs to (`laneId`), and its time limit as soon as the sandbox is created, before any work runs in it. `humanish reclaim` kills sandboxes by these ids after an interrupted run.                                                                                                                                                                                                                               | `SandboxReceipt` in `src/run/sandbox-receipts.ts`; `reclaimRunSandboxes` in `src/run/reclaim.ts`                                                                                                                                                                                                                                                                                                          |
-| topology            | Whether participants share one instance of the subject. `subject.topology` is `per-lane-worlds` (the default, one each) or `shared-world` (one for all).                                                                                                                                                                                                                                                                                                                                                                          | `LabSubjectTopology` in `src/lab/types.ts`                                                                                                                                                                                                                                                                                                                                                                |
-| plane               | The one instance of the subject that a shared-world study's participants use together. A `provisioned` plane is a `clone` or `local-tree` subject that humanish serves in a sandbox, with a declared subject state. An `external-public` plane is a deployment already running at `subject.appUrl`, whose owner the lab names in `subject.publicTarget.owner`. Each plane has at least two participants.                                                                                                                          | `SharedWorldPlane` in `src/lab/plan-types.ts`; `src/routes/shared-world/`                                                                                                                                                                                                                                                                                                                                 |
-| stream              | One live or recorded view of a participant, such as a browser or a terminal, in `run.json` and the Observer.                                                                                                                                                                                                                                                                                                                                                                                                                      | `RunStream` in `src/run/streams.ts`                                                                                                                                                                                                                                                                                                                                                                       |
-| Observer            | The single-file review page built from `observer/observer-data.json` (`humanish.observer-data.v1`).                                                                                                                                                                                                                                                                                                                                                                                                                               | `observer/` (the page), `src/observer/` (data, render, serve)                                                                                                                                                                                                                                                                                                                                             |
-| evidence            | Files a run keeps: screenshots, traces, transcripts, recordings. `verify` checks them and grades share-safety.                                                                                                                                                                                                                                                                                                                                                                                                                    | `src/evidence/`; `verifyRun` in `src/verify/verify.ts`                                                                                                                                                                                                                                                                                                                                                    |
-| analysis            | An independent model reading of a finished run's retained evidence, kept apart from participant feedback. Supported live runs request it automatically, and `humanish analyze` runs it on demand. It records findings and observations as `humanish.study-analysis.v1`.                                                                                                                                                                                                                                                           | `src/analysis/`; `runAutomaticAnalysis` in `src/analysis/automatic.ts`; `analyzeRun` in `src/analysis/service.ts`; `ANALYSIS_SCHEMA` in `src/analysis/types.ts`                                                                                                                                                                                                                                           |
-| finding             | A result of analysis, with citations to evidence in the run. Each finding groups the observations that support it.                                                                                                                                                                                                                                                                                                                                                                                                                | `src/analysis/`                                                                                                                                                                                                                                                                                                                                                                                           |
-| observation         | One claim in analysis with its basis, evidence ids and limitation. `concernReviews[]` gives each material concern's observation a disposition: `finding`, `context` or `unsupported`.                                                                                                                                                                                                                                                                                                                                             | `src/analysis/`                                                                                                                                                                                                                                                                                                                                                                                           |
+Use one word per concept. Docs and new code use the terms in the first table. Some manifest,
+bundle and output fields keep older spellings; the second table maps them.
+
+| Term                | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Where it lives in the code                                                                                                                                                                                                                                                                                                                                                                                |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| study               | What a user designs and runs: one YAML file that declares the subject, the actor, the participants and the caps. The file lives at `humanish/studies/<id>.yaml` with schema `humanish.study.v3`, read by `humanish study` and `--study`. A 0.107 `humanish.lab.v2` file under `labs/` still runs with a warning until 0.109 (second table).                                                                                                                                                                                         | `src/lab/`; `LabConfig` in `src/lab/types.ts`, parsed by `parseLabConfig` in `src/lab/config.ts`                                                                                                                                                                                                                                                                                                          |
+| run                 | One execution of a study, on disk: `.humanish/runs/<runId>/`, with `run.json` (`humanish.run-bundle.v1`) as the source of truth.                                                                                                                                                                                                                                                                                                                                                                                                    | `src/run/`; `RunBundle` in `src/run/bundle.ts`                                                                                                                                                                                                                                                                                                                                                            |
+| dry run             | A run with no live participant, from `--dry-run` or `mode: dry-run`. humanish writes a synthetic run bundle, review and Observer with no browser, model, keys or provider spend, and tests no product behavior. The `preview` route only dry-runs; "preview" names that route and nothing else.                                                                                                                                                                                                                                     | `runDryRun` in `src/run/dry-run.ts`; `resolveLabDryRun` in `src/lab/plan.ts`                                                                                                                                                                                                                                                                                                                              |
+| participant         | One simulated person, or agent, taking part in a study. The planner builds each one's record (id, persona id, assignment, labels and the route's own fields). Shared-world participants resolve the plan's records; computer-use participants rebuild the same records from the study config with `computerUseParticipants` (`src/lab/plan-participants.ts`) and resolve those. `ResolvedParticipant` adds the bundle ids, persona and prompt. `run.json` records each one as a `simulations[]` entry with one or more `streams[]`. | `ResolvedParticipant` in `src/run/participant.ts`; the planned records in `src/lab/plan-participants.ts`. Computer-use and shared-world participants run a `DesktopParticipantRun` (`src/routes/computer-use/types.ts`). The terminal session (`src/routes/terminal/session.ts`), scripted surfaces (`src/routes/scripted/plan.ts`) and fixture simulations (`src/run/dry-run.ts`) still build their own. |
+| persona             | Who a participant is: traits, background, device. `humanish/personas/<id>.yaml`.                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `src/lab/persona.ts`, `src/lab/persona-resolve.ts`                                                                                                                                                                                                                                                                                                                                                        |
+| mission             | The free-form brief a model-driven participant receives: `actor.mission`. `actor.tasks[]` adds discrete tasks: each has a `goal` the participant sees and an optional `success` check it does not.                                                                                                                                                                                                                                                                                                                                  | `LabActor` in `src/lab/types.ts`                                                                                                                                                                                                                                                                                                                                                                          |
+| assignment          | What one participant was asked to do: the mission, a `participants` entry's `instruction` or the homogeneous `participants.instruction` (recorded as `focus`), and the tasks. Each stream records it as `streams[].assignment`.                                                                                                                                                                                                                                                                                                     | `participantAssignment` in `src/lab/participant-assignment.ts`; `RunParticipantAssignment` in `src/run/streams.ts`                                                                                                                                                                                                                                                                                        |
+| scenario            | A scenario file, `humanish/scenarios/<id>.yaml` (`humanish.scenario.v1`): a goal and ordered steps with expectations. A scripted study names one in `scenario:`, and only the scripted route executes those steps. A v2 study file's `scenario` block held run settings (`mode`, `caps`, `ref`), which v3 moves to the top level. A model-driven participant follows its mission.                                                                                                                                                   | `LabScenario` in `src/lab/types.ts`; `src/routes/scripted/route.ts` resolves the scenario, and `executeBrowserPersonaStep` (`src/actors/scripted-browser/steps.ts`) runs each step                                                                                                                                                                                                                        |
+| surface             | One browser viewport that a scripted run replays its journey on: `desktop` or `mobile`. A scripted study runs the desktop surface by default, and `actors[0].count: 2` adds the mobile one. Each surface writes `actor-<surface>.json` and `traces/<surface>.json`.                                                                                                                                                                                                                                                                 | `BrowserSurface` and `browserSurfaces` in `src/actors/scripted-browser/types.ts`; the plan's `surfaces` in `src/routes/scripted/plan.ts`                                                                                                                                                                                                                                                                  |
+| journey             | A scenario's `browser.steps` parsed into ordered steps with a goal and a start path. The scripted route replays it once on each surface, and each surface's session reports the first step that did not pass.                                                                                                                                                                                                                                                                                                                       | `BrowserPersonaJourney` in `src/actors/scripted-browser/types.ts`; `parseBrowserPersonaJourneyFromScenario` in `src/actors/scripted-browser/journey.ts`                                                                                                                                                                                                                                                   |
+| subject             | The product under study, declared by `subject.source`: `clone`, `app-url`, `local-tree`, `terminal-product`, `desktop-cli`, `local-app` or `this-repo`. `run.json` records its provenance under `subject`.                                                                                                                                                                                                                                                                                                                          | `LabSubject` in `src/lab/types.ts`, parsed in `src/lab/parse/subject.ts`                                                                                                                                                                                                                                                                                                                                  |
+| actor               | The model or program that drives a participant, declared by `actors[0].type`, e.g. `openai-computer-use`, `local-agent`, `scripted-browser`, `codex-exec`.                                                                                                                                                                                                                                                                                                                                                                          | `src/actors/`; `actorRegistry` in `src/actors/registry.ts` lists them, plus `codex-app-server`, which no study can name; `ActorTrace` in `src/actors/contract.ts` is its record                                                                                                                                                                                                                           |
+| run kind            | What an actor can do: `code`, `computer-use`, `scripted-browser` or `terminal`. An actor declares its run kinds in `capabilities.lanes`, and its trace records the one it ran as `lane`; neither field names a participant. Routing admits a study's actor only for a run kind it declares. `computer-use` and `terminal` name both a run kind and a route, but a route is where a study runs and a run kind is what an actor does.                                                                                                 | `ActorRunKind` in `src/actors/contract.ts`; `actorResolvesToComputerUse` (`src/lab/routing.ts`) and its siblings                                                                                                                                                                                                                                                                                          |
+| adapter             | Product-specific code kept out of core. A study names a scorer module in `review.scorer.ref`, or the CLI passes `--scorer`, and a library caller passes the same functions as `RunLabOptions.scorer`: `score`, `deriveFeedback` and `deriveArtifacts`. Their output is stored under the adapter's namespace in `run.json` (`adapterScore`, `adapterArtifacts` and a feedback candidate's `adapter`).                                                                                                                                | `AdapterScorerModule` in `src/lab/adapter-scorer-loader.ts`; `applyBrowserScorer` in `src/lab/adapter-extension.ts`; fixture sets in `adapters/`                                                                                                                                                                                                                                                          |
+| computer use        | A model drives a participant by reading screenshots of a desktop and acting with mouse and keyboard. `openai-computer-use` and `local-agent` are the computer-use actors. CUA is the short form in code names such as `CuaExecutor` and in the older spellings listed under `cua` below.                                                                                                                                                                                                                                            | `src/routes/computer-use/`, `src/actors/computer-use/`                                                                                                                                                                                                                                                                                                                                                    |
+| fan-out             | A computer-use run with more than one participant, each on its own desktop, or any rerun. It writes the fan-out bundle shape and passes only when every expected participant passes. One participant without a rerun keeps the single-participant shape.                                                                                                                                                                                                                                                                            | `buildCuaFanoutBundle` in `src/routes/computer-use/fanout-bundle.ts`; `judgeComputerUseRun` in `src/routes/computer-use/bundle.ts`                                                                                                                                                                                                                                                                        |
+| route               | The execution path for a study: `computer-use`, `shared-world`, `scripted`, `terminal` or `preview`. `preview` writes a dry-run bundle for `this-repo` subjects with no live participant.                                                                                                                                                                                                                                                                                                                                           | `routeOf` and `LabRoute` in `src/lab/plan.ts`; predicates in `src/lab/routing.ts`; one folder or file per route in `src/routes/`                                                                                                                                                                                                                                                                          |
+| plan                | What `planLab` decides about a study before anything runs: the study id, whether it is a dry run, the analysis settings and the keys, connections and env vars the run needs, plus the route's participants, caps and own fields. There is one variant per route. `planLab` returns a plan, or a refusal with the route's error code, and the route's run function (`runComputerUsePlan` and the others) takes the plan.                                                                                                            | `LabPlan` in `src/lab/plan-types.ts`; `planLab` in `src/lab/plan.ts`; each route's planner in its `plan.ts`                                                                                                                                                                                                                                                                                               |
+| substrate           | Where a participant's desktop or shell runs: a hosted E2B sandbox, or a local Firecracker VM (inside Lima on macOS).                                                                                                                                                                                                                                                                                                                                                                                                                | `src/substrates/e2b/`, `src/substrates/local/`                                                                                                                                                                                                                                                                                                                                                            |
+| participant desktop | The desktop one computer-use or shared-world participant drives: a substrate plus the route's concerns, such as subject provisioning, comms and the participant's plan. It lives in the route, so `src/substrates/` holds only provider primitives ([ADR 0004](docs/decisions/0004-participant-desktops-stay-in-the-route.md)).                                                                                                                                                                                                     | `ParticipantDesktop` in `src/routes/computer-use/participant-desktop.ts`; `createE2BParticipantDesktop` in `src/routes/computer-use/e2b-desktop/desktop.ts`; the local VM's in `src/routes/computer-use/local-vm.ts`                                                                                                                                                                                      |
+| receipt             | A line in a run's `sandbox-receipts.ndjson` that records a sandbox's id, provider, the participant or subject it belongs to (`laneId`), and its time limit as soon as the sandbox is created, before any work runs in it. `humanish reclaim` kills sandboxes by these ids after an interrupted run.                                                                                                                                                                                                                                 | `SandboxReceipt` in `src/run/sandbox-receipts.ts`; `reclaimRunSandboxes` in `src/run/reclaim.ts`                                                                                                                                                                                                                                                                                                          |
+| topology            | Whether participants share one instance of the subject. `route: shared-world` gives one for all; every other route gives each participant its own (`per-lane-worlds`). `run.json` records it as `sharedWorld.topology`.                                                                                                                                                                                                                                                                                                             | `LabSubjectTopology` in `src/lab/types.ts`                                                                                                                                                                                                                                                                                                                                                                |
+| plane               | The one instance of the subject that a shared-world study's participants use together. A `provisioned` plane is a `clone` or `local-tree` subject that humanish serves in a sandbox, with a declared subject state. An `external-public` plane is a deployment already running at `subject.appUrl`, whose owner the study names in `subject.publicTarget.owner`. Each plane has at least two participants.                                                                                                                          | `SharedWorldPlane` in `src/lab/plan-types.ts`; `src/routes/shared-world/`                                                                                                                                                                                                                                                                                                                                 |
+| stream              | One live or recorded view of a participant, such as a browser or a terminal, in `run.json` and the Observer.                                                                                                                                                                                                                                                                                                                                                                                                                        | `RunStream` in `src/run/streams.ts`                                                                                                                                                                                                                                                                                                                                                                       |
+| Observer            | The single-file review page built from `observer/observer-data.json` (`humanish.observer-data.v1`).                                                                                                                                                                                                                                                                                                                                                                                                                                 | `observer/` (the page), `src/observer/` (data, render, serve)                                                                                                                                                                                                                                                                                                                                             |
+| evidence            | Files a run keeps: screenshots, traces, transcripts, recordings. `verify` checks them and grades share-safety.                                                                                                                                                                                                                                                                                                                                                                                                                      | `src/evidence/`; `verifyRun` in `src/verify/verify.ts`                                                                                                                                                                                                                                                                                                                                                    |
+| analysis            | An independent model reading of a finished run's retained evidence, kept apart from participant feedback. Supported live runs request it automatically, and `humanish analyze` runs it on demand. It records findings and observations as `humanish.study-analysis.v1`.                                                                                                                                                                                                                                                             | `src/analysis/`; `runAutomaticAnalysis` in `src/analysis/automatic.ts`; `analyzeRun` in `src/analysis/service.ts`; `ANALYSIS_SCHEMA` in `src/analysis/types.ts`                                                                                                                                                                                                                                           |
+| finding             | A result of analysis, with citations to evidence in the run. Each finding groups the observations that support it.                                                                                                                                                                                                                                                                                                                                                                                                                  | `src/analysis/`                                                                                                                                                                                                                                                                                                                                                                                           |
+| observation         | One claim in analysis with its basis, evidence ids and limitation. `concernReviews[]` gives each material concern's observation a disposition: `finding`, `context` or `unsupported`.                                                                                                                                                                                                                                                                                                                                               | `src/analysis/`                                                                                                                                                                                                                                                                                                                                                                                           |
 
 ## Read these field spellings as the concept they name
 
@@ -41,14 +46,16 @@ Fields documented in [docs/contracts/](docs/contracts/schemas.md), in `TELEMETRY
 library exports of `src/index.ts` are API, so they keep their spelling. Prose and new code use the
 concept word.
 
-| Spelling                                                                                                 | Where it appears                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Concept                       |
-| -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
-| `lanes`, `laneFocus`, `laneId`, `laneWindows`, `laneGroups`, `laneSummary`, `per-lane-worlds`, `lane-NN` | `actors[0].lanes[]` and `actors[0].laneFocus` in a lab, and `lane` on each `comms.email.recipients[]` entry; `per-lane-worlds`, the default `subject.topology`; `lane-01`, `lane-02`, … as the ids of independent participants the lab does not name; `streams[].laneId` and `sharedWorld.laneWindows` in `run.json`; `laneId` in `sandbox-receipts.ndjson`, which can also name the subject; `lanes[]` and `laneSummary` in `humanish.cua-lab-result.v2`; `laneGroups` in Observer data. Deprecated until the next minor removes them: `--lanes` (use `--participants`) and `BrowserLabScoringContext.laneCount` (use `participantCount`). | participant                   |
-| `roles`, `roleId`, `roleCount`, `role-NN`                                                                | `run.json` `sharedWorld`: `roleCount`, and `roleId` on `laneWindows`, `outcomes` and the older sequential records; `role-01`, `role-02`, … as the ids of shared-world participants the lab does not name                                                                                                                                                                                                                                                                                                                                                                                                                                    | participant in a shared world |
-| seat                                                                                                     | `resolveSeatUrl` in `src/lab/routing.ts`, comments in `src/lab/warnings.ts`, and the dated records under `docs/goals/`. The shared-world planner's records are `ProvisionedParticipant` and `ExternalPublicParticipant` (`src/lab/plan-participants.ts`). No lab or `run.json` field uses the word.                                                                                                                                                                                                                                                                                                                                         | participant in a shared world |
-| `simulations`, `simId`, `simCount`, `--sims`                                                             | `simulations[]` in `run.json` (one per participant), `simId` on streams and shared-world records, `simCount` in `run.json` and Observer data; `--sims` on `humanish run`, `lab run` and `watch`, deprecated for `--count` until the next minor removes it                                                                                                                                                                                                                                                                                                                                                                                   | participant                   |
-| `streams`, `streamId`                                                                                    | `streams[]` in `run.json`; `streamId` on shared-world records                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | stream                        |
-| `backend`                                                                                                | `BrowserLabScoringContext.backend`, deprecated for `route`: its first read warns, and the next minor removes it. `selectLabBackend`, `LabOutcome.backend`, `LabBackend` and the preflight result's `backend` field are removed; read `route`. The values are older route names: `cua` is computer-use, `concurrent-shared-world` is shared-world and `synthetic` is preview.                                                                                                                                                                                                                                                                | route                         |
-| `cua`                                                                                                    | The `HUMANISH_CUA_LAB_*` error codes, the result schema `humanish.cua-lab-result.v2`, the `cua-lab.*` event types in `run.json`, the `humanish lab cua` summary line, the fallback persona id `cua-operator`, and the `cua` value of the deprecated `BrowserLabScoringContext.backend`                                                                                                                                                                                                                                                                                                                                                      | computer use                  |
-| `CONCURRENT` in `HUMANISH_CONCURRENT_SHARED_WORLD_LAB_*`                                                 | The shared-world route's error codes. The word dates from when a sequential shared-world route also existed; its codes, `HUMANISH_SHARED_WORLD_LAB_*`, went with it in 0.106.0, so new shared-world codes keep `CONCURRENT_` rather than reuse that prefix                                                                                                                                                                                                                                                                                                                                                                                  | shared world                  |
-| `brain`                                                                                                  | The telemetry property: `provider-key`, `local-agent` or `none`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | how the actor gets its model  |
+| Spelling                                                                                                 | Where it appears                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Concept                       |
+| -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
+| `lanes`, `laneFocus`, `laneId`, `laneWindows`, `laneGroups`, `laneSummary`, `per-lane-worlds`, `lane-NN` | `lanes` and `laneFocus` in a v2 study file (v3 says `participants`), and `lane` on each `comms.email.recipients[]` entry; `per-lane-worlds`, the topology of every route but shared-world; `lane-01`, `lane-02`, … as the ids of independent participants the study does not name; `streams[].laneId` and `sharedWorld.laneWindows` in `run.json`; `laneId` in `sandbox-receipts.ndjson`, which can also name the subject; `lanes[]` and `laneSummary` in the computer-use study result; `laneGroups` in Observer data. Deprecated until the next minor removes it: `BrowserLabScoringContext.laneCount` (use `participantCount`). | participant                   |
+| `roles`, `roleId`, `roleCount`, `role-NN`                                                                | `run.json` `sharedWorld`: `roleCount`, and `roleId` on `laneWindows`, `outcomes` and the older sequential records; `role-01`, `role-02`, … as the ids of shared-world participants the study does not name                                                                                                                                                                                                                                                                                                                                                                                                                         | participant in a shared world |
+| seat                                                                                                     | The dated records under `docs/history/goals/`. The shared-world planner's records are `ProvisionedParticipant` and `ExternalPublicParticipant` (`src/lab/plan-participants.ts`). No identifier, comment, test name, study field or `run.json` field uses the word; prose:check holds `seat-comments` at 0.                                                                                                                                                                                                                                                                                                                         | participant in a shared world |
+| `simulations`, `simId`, `simCount`                                                                       | `simulations[]` in `run.json` (one per participant), `simId` on streams and shared-world records, `simCount` in `run.json` and Observer data                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | participant                   |
+| `streams`, `streamId`                                                                                    | `streams[]` in `run.json`; `streamId` on shared-world records                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | stream                        |
+| `contract_proof_only`                                                                                    | `streams[].status` and `review.verdict` in `run.json`, and the participant status in Observer data                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | dry run                       |
+| lab: `humanish/labs/`, `humanish.lab.v2`, `humanish lab`, `--lab`, `LabConfig`, `runLab`                 | The 0.107 study file's directory and schema, the `humanish lab` commands and `--lab` options, and the library exports. 0.108 still reads and accepts each with a warning, or as a deprecated alias, and 0.109 removes them; vocabulary:check counts lab in `src/` identifiers.                                                                                                                                                                                                                                                                                                                                                     |
+| `backend`                                                                                                | `BrowserLabScoringContext.backend`, deprecated for `route`: its first read warns, and the next minor removes it. `selectLabBackend`, `LabOutcome.backend`, `LabBackend` and the preflight result's `backend` field are removed; read `route`. The values are older route names: `cua` is computer-use, `concurrent-shared-world` is shared-world and `synthetic` is preview.                                                                                                                                                                                                                                                       | route                         |
+| `cua`                                                                                                    | The `cua-lab.*` event types in `run.json`, the `humanish lab cua` summary line, the fallback persona id `cua-operator`, and the `cua` value of the deprecated `BrowserLabScoringContext.backend`                                                                                                                                                                                                                                                                                                                                                                                                                                   | computer use                  |
+| `concurrent` in the sandbox tag `concurrent-shared-world-lab`                                            | The `mode` metadata humanish writes on the shared-world route's sandboxes. Existing sandboxes carry it, so it stays. The word dates from when a sequential shared-world route also existed, which went in 0.106.0                                                                                                                                                                                                                                                                                                                                                                                                                  | shared world                  |
+| `brain`                                                                                                  | The telemetry property: `provider-key`, `local-agent` or `none`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | how the actor gets its model  |