humanish 0.107.0 → 0.109.0

package/ARCHITECTURE.md

@@ -5,11 +5,11 @@ fails when a path in it no longer exists, or when a file named beside a function
 longer declares that name. [CONTEXT.md](CONTEXT.md) defines the domain terms, and
 [docs/decisions/](docs/decisions/README.md) records the decisions behind the rules below.
 
-## Follow one `humanish run <lab>` from manifest to findings
+## Follow one `humanish run <study>` from manifest to findings
 
-The steps follow a live computer-use lab on a hosted E2B desktop. Every route shares steps 1, 2, 7
-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`):
+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 `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](docs/ramp/README.md#check-which-compositions-a-lab-can-declare) refuses. A
+   [support matrix](https://github.com/danielgwilson/humanish/blob/main/docs/ramp/README.md#check-which-compositions-a-lab-can-declare) refuses. A
    refusal exits with code 2 before a run id exists.
 2. **Plan.** The route's CLI setup, here `computerUseRouteRun`
-   (`src/cli/commands/lab-route-computer-use.ts`), hands off to `runRoute`
-   (`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`
@@ -70,47 +70,47 @@ not.
    `buildObserverData` (`src/observer/data.ts`).
 8. **Analysis.** `completeAutomaticAnalysis` (`src/analysis/automatic-completion.ts`) runs
    `runAutomaticAnalysis` (`src/analysis/automatic.ts`) on the `FinishedRun` that `Run.finish`
-   issued. Dry runs and labs with `review.analysis: false` skip it.
+   issued. Dry runs and studies with `review.analysis: false` skip it.
 
 ## Find the code for each part of the system
 
-| 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 lab 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/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/AGENTS.md`                |
-| `tui/`                     | The Ink terminal app                                                                   | `tui/AGENTS.md`                     |
-| `site/`                    | humanish.dev and its user docs in `site/content/docs/`                                 | `site/AGENTS.md`                    |
-| `humanish/`                | This repo's own labs, personas, scenarios, fixtures and coverage notes                 | `humanish/labs/first-run.yaml`      |
-| `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
@@ -118,30 +118,34 @@ when a row names a folder that is gone; add the row with the folder. Participant
 three guest entry files stay at the `src/` root
 ([why](docs/architecture/guest-desktop.md#three-guest-files-stay-at-the-src-root)), and six
 `tests/` folders sit outside the mirror
-([list](CONTRIBUTING.md#find-the-test-folders-outside-the-src-mirror)).
+([list](https://github.com/danielgwilson/humanish/blob/main/CONTRIBUTING.md#find-the-test-folders-outside-the-src-mirror)).
 
-## Keep these invariants when you change code
+## Keep these code guarantees when you change code
 
-| Invariant                                                                                                                | Enforced by                                                                                                                                                                                                                                                                                                                                   | Pinned by                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| 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`                                                                                                                                                                                                                                                                                                                            |
+Each row names the code that enforces a guarantee and the tests that pin it. The product's
+numbered invariants are in [invariants and defaults](docs/principles/invariants-and-defaults.md#invariants);
+comments name an invariant by its rule.
+
+| Guarantee                                                                                                                | Enforced by                                                                                                                                                                                                                                                                                                                                   | Pinned by                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| The run bundle is the source of truth, and the Observer derives from it                                                  | `verifyRun` grades only `run.json` and its artifacts (`src/verify/verify.ts`). It reads `status.json` and the sandbox and reclaim receipts only for the `RUN_NOT_FINISHED` warning (`runNotFinishedWarnings` in `src/verify/liveness.ts`), which changes no check and no grade. `buildObserverData` takes the bundle (`src/observer/data.ts`) | `tests/observer/data-contract.test.ts`; `tests/verify/run-not-finished.test.ts` checks that the grades are the same when `status.json` contradicts the bundle or is gone; `docs/decisions/0001-run-bundle-is-the-source-of-truth.md`                                                                                                                                                                                                                                             |
+| Unsupported execution is refused before side effects                                                                     | `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 lab preflight probe journals its receipt with `withPreflightSandbox`
-(`src/lab/preflight-probes.ts`), and `humanish reclaim --preflight` (`src/run/reclaim.ts`) kills
+receipt. A study check probe journals its receipt with `withPreflightSandbox`
+(`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.
 
 ## Read next
 
-- [docs/architecture/project-layout.md](docs/architecture/project-layout.md): the `humanish/`
+- [Project layout](https://humanish.dev/docs/project-layout): the `humanish/`
   and `.humanish/` folders in a project that runs studies.
-- [docs/ramp/README.md](docs/ramp/README.md#check-which-compositions-a-lab-can-declare): the
-  support matrix, which compositions a lab can declare and which tests pin each row.
-- [CONTRIBUTING.md](CONTRIBUTING.md#make-your-first-change): a first change, offline, and the
+- [docs/ramp/README.md](https://github.com/danielgwilson/humanish/blob/main/docs/ramp/README.md#check-which-compositions-a-lab-can-declare): the
+  support matrix, which compositions a study can declare and which tests pin each row.
+- [CONTRIBUTING.md](https://github.com/danielgwilson/humanish/blob/main/CONTRIBUTING.md#make-your-first-change): a first change, offline, and the
   tests and contracts that common changes touch.

package/CHANGELOG.md

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