humanish 0.108.0 → 0.109.0

package/ARCHITECTURE.md

@@ -8,8 +8,8 @@ longer declares that name. [CONTEXT.md](CONTEXT.md) defines the domain terms, an
 ## Follow one `humanish run <study>` from manifest to findings
 
 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`):
+and 8. Steps 3 to 6 run in the route's admit function and the `run()` it returns, which `runStudyWith`
+reaches through `admitPlan` (`src/run-study.ts`):
 
 - computer-use: `admitComputerUsePlan` (`src/routes/computer-use/route.ts`); its `run()` calls
   `runAdmittedCuaRun` (`src/routes/computer-use/route.ts`).
@@ -25,23 +25,23 @@ reaches through `admitPlan` (`src/run-lab.ts`):
 `runComputerUsePlan` (`src/routes/computer-use/route.ts`), `runTerminalPlan`
 (`src/routes/terminal/route.ts`) and `runSharedWorldPlan` (`src/routes/shared-world/route.ts`)
 admit and run in one call. Only tests call them, directly or through the route modules'
-`runCuaActorLab`, `runTerminalProductLab` and `runConcurrentSharedWorld`. `runLab` and the CLI do
+`runCuaActorStudy`, `runTerminalProductStudy` and `runConcurrentSharedWorld`. `runStudyWith` and the CLI do
 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
+1. **Parse.** `runStudyCommand` (`src/cli/commands/study-run.ts`) calls `resolveStudyManifest`
+   (`src/study/discover.ts`), which calls `parseStudy` (`src/study/config.ts`). It rejects unknown
    keys and the compositions the
    [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`
-   (`src/cli/commands/lab-route-run.ts`), which calls `prepareLab` (`src/run-lab.ts`). That picks the
-   route with `routeOf` (`src/lab/plan.ts`) and plans once with `planLab` (`src/lab/plan.ts`), here
-   through `planComputerUseLab` (`src/routes/computer-use/plan.ts`). It then calls the route's admit
+   (`src/cli/commands/study-route-computer-use.ts`), hands off to `runRoute`
+   (`src/cli/commands/study-route-run.ts`), which calls `prepareStudy` (`src/run-study.ts`). That picks the
+   route with `routeOf` (`src/study/plan.ts`) and plans once with `planStudy` (`src/study/plan.ts`), here
+   through `planComputerUseStudy` (`src/routes/computer-use/plan.ts`). It then calls the route's admit
    function, here `admitComputerUsePlan` (`src/routes/computer-use/route.ts`), which makes the
    checks in step 3. A refusal from the planner or those checks returns before a declared scorer
-   loads. Otherwise a `run()` returns that takes the scorer and continues the run. `runLab` is
-   `prepareLab`, then `run()`.
+   loads. Otherwise a `run()` returns that takes the scorer and continues the run. `runStudyWith` is
+   `prepareStudy`, then `run()`.
 3. **Preflight.** `admitCuaRun` (`src/routes/computer-use/setup.ts`) calls `liveCuaRejection`
    (`src/routes/computer-use/preflight.ts`) for keys, local-agent sign-in, subject env and caps, and
    packs a `local-tree` subject. The `run()` opens the run's lifetime with `runScope`
@@ -54,7 +54,7 @@ not.
    `acquireE2BDesktopSandbox` (`src/substrates/e2b/sandbox.ts`) records the sandbox id before it
    returns. `src/subject/`
    provisions a `clone` or `local-tree` subject over a `Shell` (`src/substrates/shell.ts`).
-5. **Participants.** `runLabParticipants` (`src/routes/computer-use/live-phase.ts`) publishes an
+5. **Participants.** `runStudyParticipants` (`src/routes/computer-use/live-phase.ts`) publishes an
    in-progress bundle, then calls `runAllCuaParticipants`
    (`src/routes/computer-use/participant-execution.ts`). That runs `runCuaParticipant` for each
    participant, at most `execution.concurrency` at a time, and each one drives `runComputerUseLoop`
@@ -74,44 +74,43 @@ not.
 
 ## Find the code for each part of the system
 
-| Folder                     | What it holds                                                                          | Read first                          |
-| -------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------- |
-| `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 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`      |
-| `src/routes/shared-world/` | Several participants on one shared plane, provisioned or external-public               | `src/routes/shared-world/route.ts`  |
-| `src/routes/terminal/`     | A Codex agent in an E2B shell against a terminal product, with its ledgers             | `src/routes/terminal/route.ts`      |
-| `src/actors/`              | The actor contract, the registry and each actor's session code                         | `src/actors/registry.ts`            |
-| `src/subject/`             | Subject provisioning over a `Shell`: clone, local tree, desktop CLI, serve             | `src/subject/serve.ts`              |
-| `src/substrates/`          | Provider primitives: E2B in `e2b/`, Firecracker and Lima VMs in `local/`, the `Shell`  | `src/substrates/desktop-session.ts` |
-| `src/run/`                 | Run lifecycle, bundle types, bundle guards, paths, status, receipts, reclaim           | `src/run/run.ts`                    |
-| `src/verify/`              | `humanish verify`: evidence checks, share-safety grades, cost and rerun checks         | `src/verify/verify.ts`              |
-| `src/evidence/`            | Redaction, screenshot checks and desktop recordings                                    | `src/evidence/redaction.ts`         |
-| `src/analysis/`            | Automatic and on-demand study analysis                                                 | `src/analysis/automatic.ts`         |
-| `src/observer/`            | Observer data, the HTML render and the local server                                    | `src/observer/render.ts`            |
-| `src/comms/`               | Captured and received email for participant inboxes                                    | `src/comms/types.ts`                |
-| `src/feedback/`            | Feedback drafts and export bundles                                                     | `src/feedback/feedback.ts`          |
-| `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/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`                  |
-| `fixtures/`                | Synthetic apps and cases that tests and scripts copy                                   | `fixtures/minimal-app/README.md`    |
-| `skills/`                  | The companion agent skill that `npx skills add` installs                               | `skills/humanish/SKILL.md`          |
-| `runtime/`                 | Desktop and browser image recipes                                                      | `runtime/browser-guest/README.md`   |
-| `scripts/`                 | Proof, release and check scripts that `package.json` runs                              | `scripts/check-doc-paths.ts`        |
-| `docs/contracts/`          | Bundle and schema contracts, whose documented fields are API                           | `docs/contracts/run-bundle.md`      |
-| `tests/`                   | Vitest suites that mirror `src/`, plus six folders outside the mirror                  | `tests/helpers/run-golden.ts`       |
+| Folder                     | What it holds                                                                                                                   | Read first                          |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |
+| `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-study.ts`         | `runStudyWith`: plan the study once, then run the plan on its route                                                             | `src/run-study.ts`                  |
+| `src/study/`               | Study files: discovery in studies/ (refusing a file found only in labs/), parsing (`config.ts`, `parse/`), routing and planning | `src/study/plan.ts` for planning    |
+| `src/routes/`              | One folder per route; `routeOf` in `src/study/plan.ts` picks it                                                                 | `src/study/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`      |
+| `src/routes/shared-world/` | Several participants on one shared plane, provisioned or external-public                                                        | `src/routes/shared-world/route.ts`  |
+| `src/routes/terminal/`     | A Codex agent in an E2B shell against a terminal product, with its ledgers                                                      | `src/routes/terminal/route.ts`      |
+| `src/actors/`              | The actor contract, the registry and each actor's session code                                                                  | `src/actors/registry.ts`            |
+| `src/subject/`             | Subject provisioning over a `Shell`: clone, local tree, desktop CLI, serve                                                      | `src/subject/serve.ts`              |
+| `src/substrates/`          | Provider primitives: E2B in `e2b/`, Firecracker and Lima VMs in `local/`, the `Shell`                                           | `src/substrates/desktop-session.ts` |
+| `src/run/`                 | Run lifecycle, bundle types, bundle guards, paths, status, receipts, reclaim                                                    | `src/run/run.ts`                    |
+| `src/verify/`              | `humanish verify`: evidence checks, share-safety grades, cost and rerun checks                                                  | `src/verify/verify.ts`              |
+| `src/evidence/`            | Redaction, screenshot checks and desktop recordings                                                                             | `src/evidence/redaction.ts`         |
+| `src/analysis/`            | Automatic and on-demand study analysis                                                                                          | `src/analysis/automatic.ts`         |
+| `src/observer/`            | Observer data, the HTML render and the local server                                                                             | `src/observer/render.ts`            |
+| `src/comms/`               | Captured and received email for participant inboxes                                                                             | `src/comms/types.ts`                |
+| `src/feedback/`            | Feedback drafts and export bundles                                                                                              | `src/feedback/feedback.ts`          |
+| `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/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/study/adapter-fixtures.test.ts` checks                                                         | `adapters/fixtures/README.md`       |
+| `bench/`                   | Benchmark apps with planted defects and their dated results                                                                     | `bench/DEFECTS.md`                  |
+| `fixtures/`                | Synthetic apps and cases that tests and scripts copy                                                                            | `fixtures/minimal-app/README.md`    |
+| `skills/`                  | The companion agent skill that `npx skills add` installs                                                                        | `skills/humanish/SKILL.md`          |
+| `runtime/`                 | Desktop and browser image recipes                                                                                               | `runtime/browser-guest/README.md`   |
+| `scripts/`                 | Proof, release and check scripts that `package.json` runs                                                                       | `scripts/check-doc-paths.ts`        |
+| `docs/contracts/`          | Bundle and schema contracts, whose documented fields are API                                                                    | `docs/contracts/run-bundle.md`      |
+| `tests/`                   | Vitest suites that mirror `src/`, plus six folders outside the mirror                                                           | `tests/helpers/run-golden.ts`       |
 
 `pnpm docs:check` fails when a folder directly under `src/` or `src/routes/` has no row here, or
 when a row names a folder that is gone; add the row with the folder. Participant desktops stay in
@@ -127,18 +126,18 @@ Each row names the code that enforces a guarantee and the tests that pin it. The
 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 |
-| A sandbox id is recorded before any work runs in it                                                                      | `acquireE2BDesktopSandbox` and `acquireE2BShellSandbox` (`src/substrates/e2b/sandbox.ts`) write the receipt before they return the handle, and every route that creates a sandbox calls them; `reclaimRunSandboxes` (`src/run/reclaim.ts`) switches on the receipt's provider and kills by exact id                                           | `tests/substrates/e2b/sandbox.test.ts`, which also checks that `Sandbox.create` has one call site in `src/`, `tests/routes/terminal/acquisition-boundary.test.ts`, `tests/run/reclaim.test.ts`; `tests/routes/scripted/route.test.ts` checks create, receipt, then first work                                                                                                                                                                                                  |
-| Bundles carry no secrets                                                                                                 | `redactText` and `scrubLiterals` (`src/evidence/redaction.ts`); `scanRunPublicSafetyArtifacts` (`src/verify/artifacts.ts`); `buildShareSafety` (`src/verify/verify.ts`) grades `share_ready`, `local_only` or `blocked`                                                                                                                       | `tests/evidence/redaction-hooks.test.ts`, `tests/run/transient-comms-secrets.test.ts`, `tests/verify/evidence-refs.test.ts`                                                                                                                                                                                                                                                                                                                                                    |
-| Goldens pin route output                                                                                                 | `runDirSnapshot` (`tests/helpers/run-golden.ts`) snapshots a whole run folder                                                                                                                                                                                                                                                                 | `tests/golden/routes/`, `tests/golden/observer-data/`, `tests/golden/labs/`; `tests/lab/plan-lab.test.ts` checks that every `LabRoute` has a dry-run golden                                                                                                                                                                                                                                                                                                                    |
-| 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`                                                                                                                                                                                                                                                                                                                            |
+| 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                                                                     | `parseStudy` (`src/study/config.ts`), `taskProtocolValidationReason` (`src/study/validation.ts`), `planComputerUseStudy` (`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/study/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 |
+| A sandbox id is recorded before any work runs in it                                                                      | `acquireE2BDesktopSandbox` and `acquireE2BShellSandbox` (`src/substrates/e2b/sandbox.ts`) write the receipt before they return the handle, and every route that creates a sandbox calls them; `reclaimRunSandboxes` (`src/run/reclaim.ts`) switches on the receipt's provider and kills by exact id                                           | `tests/substrates/e2b/sandbox.test.ts`, which also checks that `Sandbox.create` has one call site in `src/`, `tests/routes/terminal/acquisition-boundary.test.ts`, `tests/run/reclaim.test.ts`; `tests/routes/scripted/route.test.ts` checks create, receipt, then first work                                                                                                                                                                                                    |
+| Bundles carry no secrets                                                                                                 | `redactText` and `scrubLiterals` (`src/evidence/redaction.ts`); `scanRunPublicSafetyArtifacts` (`src/verify/artifacts.ts`); `buildShareSafety` (`src/verify/verify.ts`) grades `share_ready`, `local_only` or `blocked`                                                                                                                       | `tests/evidence/redaction-hooks.test.ts`, `tests/run/transient-comms-secrets.test.ts`, `tests/verify/evidence-refs.test.ts`                                                                                                                                                                                                                                                                                                                                                      |
+| Goldens pin route output                                                                                                 | `runDirSnapshot` (`tests/helpers/run-golden.ts`) snapshots a whole run folder                                                                                                                                                                                                                                                                 | `tests/golden/routes/`, `tests/golden/observer-data/`, `tests/golden/labs/`; `tests/study/plan-lab.test.ts` checks that every `StudyRoute` has a dry-run golden                                                                                                                                                                                                                                                                                                                  |
+| 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 study check probe journals its receipt with `withPreflightSandbox`
-(`src/lab/preflight-probes.ts`), and `humanish reclaim --preflight` (`src/run/reclaim.ts`) kills
+(`src/study/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.
 

package/CHANGELOG.md

@@ -8,6 +8,19 @@ The Unreleased section holds the full notes for the next version until it is tag
 
 ## Unreleased
 
+## 0.109.0: Lab names removed, v2 study files refused (2026-10-03)
+
+humanish 0.109.0 removes what 0.108.0 deprecated. A `humanish.lab.v2` file, or any study file in a
+`labs/` directory, is refused with the command that fixes it: `humanish migrate` converts and moves
+v2 files, and a v3 file in `labs/` moves to the matching `studies/` directory. The `lab` commands,
+`--lab`, `serve` and `watch --run` are unknown to the CLI. The library drops its 0.107 names:
+`runLab`, `parseLabConfig`, the `Lab*` types and the `Cua*` names. Run records and telemetry name
+the study as `study` only, a study's result has `studyId` only, and bare `--json`, scorer contexts
+and computer-use `error.name` use study and `ComputerUse` names. The release notes list each removal
+and what to change.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.109.0)
+
 ## 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

package/CONTEXT.md

@@ -8,37 +8,37 @@ them equal.
 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/`                                                                                                                                                                                                                                                                                                                                                                                           |
+| 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`. humanish refuses a 0.107 `humanish.lab.v2` file, and `humanish migrate` converts it (second table).                                                                                                                                                                                          | `src/study/`; `StudyConfig` in `src/study/types.ts`, parsed by `parseStudy` in `src/study/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`; `resolveStudyDryRun` in `src/study/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/study/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/study/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/study/persona.ts`, `src/study/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.                                                                                                                                                                                                                                                                                                                                    | `StudyActor` in `src/study/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/study/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.                                                                                                                                                     | `StudyScenario` in `src/study/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`.                                                                                                                                                                                                                                                                                                                            | `StudySubject` in `src/study/types.ts`, parsed in `src/study/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/study/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 `RunStudyOptions.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/study/adapter-scorer-loader.ts`; `applyBrowserScorer` in `src/study/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 `StudyRoute` in `src/study/plan.ts`; predicates in `src/study/routing.ts`; one folder or file per route in `src/routes/`                                                                                                                                                                                                                                                                      |
+| plan                | What `planStudy` 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. `planStudy` 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.                                                                                                          | `StudyPlan` in `src/study/plan-types.ts`; `planStudy` in `src/study/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`.                                                                                                                                                                                                                                                                                                               | `StudySubjectTopology` in `src/study/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/study/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
 
@@ -46,16 +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` | `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  |
+| 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. | 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/study/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, `--lab` and the library exports. 0.109 removes the commands, `--lab` and the library names. It refuses a `humanish.lab.v2` file, which `humanish migrate <path>` converts, and a v3 file found by name only in a `labs/` directory, which moves to the matching `studies/` directory. Runs saved by 0.108 and earlier keep `lab` in `run.json` and `status.json`, and humanish reads it. vocabulary:check counts lab in `src/` identifiers.   |
+| `backend`                                                                                                | `BrowserScoringContext.backend` (removed in 0.109), `selectLabBackend`, `LabOutcome.backend`, `LabBackend` and the preflight result's `backend` field, all removed; read `route`. The values were 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` and the fallback persona id `cua-operator`                                                                                                                                                                                                                                                                                                                                                                                                                                    | 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  |

package/README.md

@@ -368,9 +368,9 @@ Source: [`skills/humanish/SKILL.md`](skills/humanish/SKILL.md).
 
 ## Find more guides
 
-- [Lab manifests](https://humanish.dev/docs/lab-manifests): source directories, route selection,
-  ignored private labs and
-  [scripted browser scenarios](https://humanish.dev/docs/lab-manifests#scripted-browser-scenarios).
+- [Study files](https://humanish.dev/docs/study-files): source directories, route selection,
+  ignored private studies and
+  [scripted browser scenarios](https://humanish.dev/docs/study-files#scripted-browser-scenarios).
 - [Computer use](https://humanish.dev/docs/computer-use): subjects, screenshots, devices, mobile
   emulation, stop rules, dwell windows and reruns of failed participants. The
   [cost model](https://humanish.dev/docs/budgets-and-privacy#how-cost-estimates-work) explains

package/TELEMETRY.md

@@ -26,8 +26,8 @@ telemetry, humanish cannot tell whether new users reach a working first run.
   set of words such as `passed`, `abandoned`, `all_passed`), which brain route
   ran it (`provider-key`, `local-agent`, or `none` for a dry run), and which study
   ran, **only if it is one of the starter studies `humanish init` writes**. That id is sent as
-  `study`, and also as `lab` (the property's earlier name) with the same value until 0.109.0
-  removes `lab`
+  `study`. 0.108 and earlier also sent it as `lab`, the property's earlier name; 0.109 sends
+  `study` only
 - when a command fails: humanish's own error code (`HUMANISH_…`), never the
   message. Which failure ends a first run is the question this exists to answer.
 - for CUA results with diagnostics: `diagnostic_category` is exactly one of

package/dist/actors/codex/app-server-trace.js

@@ -2,6 +2,7 @@
 // from app-server envelopes, and the redaction applied before anything is persisted.
 import { digestText, publicPathForTrace, redactText, tailText } from "../../evidence/redaction.js";
 import { isRecord } from "../../run/type-guards.js";
+import { plural } from "../../run/text.js";
 export const CODEX_APP_SERVER_TRACE_SCHEMA = "humanish.codex-app-server-trace.v1";
 const authLikeKey = /(api[_-]?key|access[_-]?token|auth[_-]?url|authorization|bearer|credential|password|secret|token)$/i;
 const pathLikeKey = /^(cwd|path|writableRoots|workspaceRoot)$/i;
@@ -295,7 +296,7 @@ export function renderTranscript(trace) {
         [
             "File changes",
             trace.fileChanges
-                .map((fileChange) => `${fileChange.status ?? "fileChange"} ${fileChange.changeCount ?? 0} change(s)`)
+                .map((fileChange) => `${fileChange.status ?? "fileChange"} ${plural(fileChange.changeCount ?? 0, "change")}`)
                 .join("\n"),
         ],
     ];