humanish 0.107.0 → 0.109.0

package/CONTEXT.md

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