humanish 0.109.1 → 0.110.1

package/ARCHITECTURE.md

@@ -63,11 +63,14 @@ not.
    `judgeComputerUseRun` (`src/routes/computer-use/bundle.ts`) and builds the bundle with
    `buildCuaRunBundle` (`src/routes/computer-use/bundle.ts`), by the rules in `src/run/judge.ts`. A
    declared scorer's failures fold in through `foldScorerFailures` (`src/run/judge.ts`), so a scorer
-   can fail a run and never pass one. `Run.finish` publishes `run.json`, then the `status.json`
-   outcome, the review and Observer data, and `.humanish/runs/latest.json` last.
+   can fail a run and never pass one. `Run.finish` publishes `run.json` with the run's `ok` and
+   execution outcome in its `outcome`, then the `status.json` outcome copied from it, the review
+   and Observer data, and `.humanish/runs/latest.json` last.
 7. **Observer.** `renderObserver` (`src/observer/render.ts`) verifies the bundle with
    `verifyRunPrepared` (`src/verify/verify.ts`) and writes `observer/index.html` from
-   `buildObserverData` (`src/observer/data.ts`).
+   `buildObserverData` (`src/observer/data.ts`). When it does not render, `FinishedRun.renderObserver`
+   (`src/run/run.ts`) adds the `evidence` failure to `run.json`'s outcome. Every surface that shows
+   whether a run passed reads that outcome through `runDisplay` (`src/run/display.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 studies with `review.analysis: false` skip it.
@@ -126,14 +129,14 @@ Each row names the code that enforces a guarantee and the tests that pin it. The
 numbered invariants are in [invariants and defaults](docs/principles/invariants-and-defaults.md#invariants);
 comments name an invariant by its rule.
 
-| Guarantee                                                                                                                | Enforced by                                                                                                                                                                                                                                                                                                                                   | Pinned by                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| The run bundle is the source of truth, and the Observer derives from it                                                  | `verifyRun` grades only `run.json` and its artifacts (`src/verify/verify.ts`). It reads `status.json` and the sandbox and reclaim receipts only for the `RUN_NOT_FINISHED` warning (`runNotFinishedWarnings` in `src/verify/liveness.ts`), which changes no check and no grade. `buildObserverData` takes the bundle (`src/observer/data.ts`) | `tests/observer/data-contract.test.ts`; `tests/verify/run-not-finished.test.ts` checks that the grades are the same when `status.json` contradicts the bundle or is gone; `docs/decisions/0001-run-bundle-is-the-source-of-truth.md`                                                                                                                                                                                                                                             |
-| Unsupported execution is refused before side effects                                                                     | `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`                                                                                                                                                                                                                                                                                                                              |
+| 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 (`runNotFinished` 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`) tag the sandbox with its run's owner tags, register the create with `beginSandboxCreate` (`src/run/sandbox-creates.ts`) and 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, kills by exact id and by the run's exact tags | `tests/substrates/e2b/sandbox.test.ts`, which also checks that `Sandbox.create` has one call site in `src/`, `tests/routes/terminal/acquisition-boundary.test.ts`, `tests/run/reclaim.test.ts`; `tests/routes/scripted/route.test.ts` checks create, receipt, then first work                                                                                                                                                                                                    |
+| Bundles carry no secrets                                                                                                 | `redactText` and `scrubLiterals` (`src/evidence/redaction.ts`); `scanRunPublicSafetyArtifacts` (`src/verify/artifacts.ts`); `buildShareSafety` (`src/verify/verify.ts`) grades `share_ready`, `local_only` or `blocked`                                                                                                                                                                                                                                  | `tests/evidence/redaction-hooks.test.ts`, `tests/run/transient-comms-secrets.test.ts`, `tests/verify/evidence-refs.test.ts`                                                                                                                                                                                                                                                                                                                                                      |
+| Goldens pin route output                                                                                                 | `runDirSnapshot` (`tests/helpers/run-golden.ts`) snapshots a whole run folder                                                                                                                                                                                                                                                                                                                                                                            | `tests/golden/routes/`, `tests/golden/observer-data/`, `tests/golden/labs/`; `tests/study/plan-lab.test.ts` checks that every `StudyRoute` has a dry-run golden                                                                                                                                                                                                                                                                                                                  |
+| A run is closed on every exit, only a published run is analyzed, and `latest.json` moves only after its run is published | `runScope` and `FinishedRun` (`src/run/run.ts`); `completeAutomaticAnalysis` requires an issued `FinishedRun` for the result's run; `Run.finish` writes `latest.json` last through `writePreparedRunLatestPointer` (`src/run/contained-output.ts`)                                                                                                                                                                                                       | `tests/run/run-lifecycle.test.ts`, which also checks that `src/run/run.ts` is the pointer's one writer, `tests/analysis/automatic-analysis.test.ts`                                                                                                                                                                                                                                                                                                                              |
 
 The receipt write is best-effort; the sandbox's server-side timeout ends a sandbox with no
 receipt. A study check probe journals its receipt with `withPreflightSandbox`

package/CHANGELOG.md

@@ -8,6 +8,30 @@ The Unreleased section holds the full notes for the next version until it is tag
 
 ## Unreleased
 
+## 0.110.1: Claude participants restricted, sandboxes reclaimed by tag (2026-10-04)
+
+humanish 0.110.1 starts a Claude Code participant with Read as its only tool, in a scratch folder,
+with a short environment allowlist and no saved transcript, and needs Claude Code 2.1.248 or newer.
+A Ctrl-C in the first seconds of a live run no longer leaves a sandbox running: every sandbox
+carries the run's tags, and the signal handler and `humanish reclaim` kill what E2B lists under
+them. `reclaim` reports `clean`, `unconfirmed` or `unknown`, and `humanish cleanup` is now a
+deprecated alias of `reclaim --check`. run.json records how a run ended, every surface shows a
+failed run as failed, and `review`, `analyze show` and a live run's last lines print the analysis
+findings as text.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.110.1)
+
+## 0.110.0: --dotenv, and sandbox ids only in receipts (2026-10-03)
+
+humanish 0.110.0 renames `--env-file` to `--dotenv`, so a missing file reaches humanish's exit 2
+result where Node exited 9 first. `--env-file` stays as a hidden alias until 0.111.0. Raw sandbox
+ids live only in a run's `sandbox-receipts.ndjson`: every other record, output and export copy names
+a sandbox as `[redacted-sandbox-id]` with a digest, and `humanish verify` grades a run that still
+holds a raw id `local_only` with `RAW_SANDBOX_ID`. The release notes list each changed field and
+what to read instead.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.110.0)
+
 ## 0.109.1: Current option names in messages, reclaim --env-file (2026-10-03)
 
 humanish 0.109.1 is a patch. Library refusals and warnings name `RunStudyOptions`, which 0.109.0

package/CONTEXT.md

@@ -1,9 +1,10 @@
 # Glossary
 
-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.
+humanish is "Synthetic user research for apps, CLIs, and agent-facing product flows." package.json,
+`humanish --help` and bare `humanish` use that sentence (`PRODUCT_SENTENCE` in
+`src/cli/product-sentence.ts`), line 3 of README.md and the humanish skill's description open with
+it, and tests/cli/product-sentence.test.ts holds them equal. [How a study works](https://humanish.dev/docs/concepts)
+is the user-facing version of the first table below.
 
 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.
@@ -18,10 +19,10 @@ bundle and output fields keep older spellings; the second table maps them.
 | 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`                                                                                                                                                                                                                                                                    |
+| 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 `surfaces: [desktop, mobile]` 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                                                                                                                                                                                                                             |
+| actor               | The model or program that drives a participant, declared by `actor.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/`                                                                                                                                                                                                                                                                                                                                                      |
@@ -31,6 +32,7 @@ bundle and output fields keep older spellings; the second table maps them.
 | 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`                                                                                                                                                                                                                                                                                                            |
+| owner tags          | The E2B metadata every sandbox humanish creates carries: `tool: humanish`, the run's `runId`, and `runKey`, a digest of the run directory's inode and creation time. The run journals them in an owner line before its first create. `humanish reclaim` lists sandboxes that match all three, which finds one whose id never reached a receipt.                                                                                                                                                                                       | `sandboxOwnerTags` in `src/run/sandbox-creates.ts`; `findE2BSandboxesByTags` in `src/substrates/e2b/sandbox.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`                                                                                                                                                                                                                                                                                                                                                                         |

package/README.md

@@ -1,6 +1,6 @@
 # humanish
 
-Synthetic user research for apps, CLIs, and agent-facing product flows.
+Synthetic user research for apps, CLIs, and agent-facing product flows. AI participants with a persona and a task use your app on real desktops, and each run leaves evidence you can verify: what they did, where they got stuck, and what it cost.
 
 [![The Observer grid of a saved eight-participant study: eight desktops in one multiplayer lobby, each tile a participant's live screen](https://humanish.dev/runs/lobby-0927/poster.jpg)](https://humanish.dev/demo)
 
@@ -8,6 +8,24 @@ Synthetic user research for apps, CLIs, and agent-facing product flows.
 lobby of a multiplayer game on its live deployment, each on its own hosted desktop. The page
 replays the real Observer; nothing runs from it.
 
+## Learn how a study works
+
+A study is a YAML file in your project. It names the app under study, the task, the
+participants and a spend limit. Each participant has a persona: a file that sets who they are
+and traits such as patience and keyboard use.
+
+`humanish run <study>` gives each participant a desktop, either a hosted E2B desktop or a
+disposable browser VM on your machine. On the computer-use route a model drives each
+participant: every turn it reads a screenshot and answers with mouse and keyboard actions, until
+the participant finishes, gets stuck or reaches a limit.
+
+The run writes its evidence to gitignored `.humanish/runs/<run id>/`: screenshots, every
+action, each participant's report and the estimated cost. The Observer replays it,
+`humanish review` prints the findings of the analysis that follows a live run, and
+`humanish verify` grades whether the evidence is safe to share.
+[How a study works](https://humanish.dev/docs/concepts) walks through one annotated study file,
+and the [study file reference](https://humanish.dev/docs/study-files) lists every field.
+
 ## Try it without keys
 
 In a project directory, with Node.js 22.19 or newer:
@@ -16,21 +34,43 @@ In a project directory, with Node.js 22.19 or newer:
 npm install --save-dev humanish
 npx humanish init --yes
 npx humanish run first-run
+```
+
+`init` writes starter studies and personas under `humanish/`, adds `.humanish/` to
+`.gitignore`, and adds `humanish:*` scripts to `package.json` and a humanish section to
+`AGENTS.md`. It never overwrites an existing study file. `run first-run` is a dry run: four
+synthetic participants, with no browser, model, key or spend. It prints:
+
+```text
+humanish run dry-run
+run: dryrun-2026-10-04T07-11-55-932Z-d11afab6
+participants: 4
+bundle: .humanish/runs/dryrun-2026-10-04T07-11-55-932Z-d11afab6/run.json
+review: .humanish/runs/dryrun-2026-10-04T07-11-55-932Z-d11afab6/review.md
+```
+
+Replay the run in the Observer, then check its evidence:
+
+```bash
 npx humanish observe --run latest --open
+npx humanish verify
 ```
 
-This writes a preview study with no model calls and no spend, so you can read the evidence format
-before you add keys. To run participants against your own app, follow the
-[own-app guide](https://humanish.dev/docs/your-app).
+```text
+verified dryrun-2026-10-04T07-11-55-932Z-d11afab6 · share_ready · 16 checks passed
+```
 
-[Quickstart](https://humanish.dev/docs) · [Study your app](https://humanish.dev/docs/your-app) · [What a study costs](https://humanish.dev/docs/what-a-study-costs) · [Trust boundaries](https://humanish.dev/docs/trust-boundaries) · [CLI reference](https://humanish.dev/docs/cli) · [Limits and evidence](https://humanish.dev/failure-modes)
+A dry run shows the evidence format and tests no product behavior. To run participants against
+your own app, follow the [own-app guide](https://humanish.dev/docs/your-app).
+
+[Quickstart](https://humanish.dev/docs) · [How a study works](https://humanish.dev/docs/concepts) · [Study your app](https://humanish.dev/docs/your-app) · [What a study costs](https://humanish.dev/docs/what-a-study-costs) · [Trust boundaries](https://humanish.dev/docs/trust-boundaries) · [CLI reference](https://humanish.dev/docs/cli) · [Limits and evidence](https://humanish.dev/failure-modes)
 
 ## Run a live study
 
-`@e2b/desktop` is the optional peer for live hosted desktops. Install it alongside
-humanish when choosing that route (`npm install --save-dev @e2b/desktop`) so the
-CLI can resolve it; a one-shot `npx humanish@latest` can miss the peer. The keyless
-preview and local-browser setup need only `humanish`.
+A live study gives each participant a computer to use. By default that computer is a hosted
+desktop from E2B, which humanish drives through the `@e2b/desktop` package. Install it in the
+same project: `npm install --save-dev @e2b/desktop`. A one-shot `npx humanish@latest` cannot see
+a copy installed elsewhere. The keyless preview and a study in a local browser do not need it.
 
 Choose how the participant runs:
 
@@ -81,7 +121,7 @@ browser, or use Codex account quota. The local study needs a supported Codex CLI
 version and ChatGPT login. Linux x64 also needs local rootful Docker, KVM and
 TUN; M3-or-newer Apple Silicon Macs need native ARM64 Node and Lima 2.2+.
 
-### Study drawDB through the API route
+### Study drawDB with an OpenAI key
 
 Set the desktop and model keys with hidden prompts, then send one synthetic participant into the
 included drawDB study:
@@ -97,7 +137,7 @@ npx humanish observe --run latest --open
 ```
 
 Existing `E2B_API_KEY` and `OPENAI_API_KEY` environment variables also work.
-`doctor --study` checks the selected route's local setup without launching a
+`doctor --study` checks the study's local setup without launching a
 desktop or making a model request. It reports key presence, not remote key
 validity, model access, or quota. `study check` checks manifest metadata by default.
 `try-live` clones and studies drawDB, not your project. Set the keys before `init`:
@@ -110,20 +150,15 @@ dollar cap. Automatic analysis after the run is a separate request;
 [Read the results](#read-the-results) gives its limit and how to turn it off.
 Hosted desktop time is additional. Participant caps are checked
 between turns and are not provider billing ceilings. Allow a few minutes for
-the app to build and the participant to work. See [budgets and privacy](https://humanish.dev/docs/budgets-and-privacy).
+the app to build and the participant to work. See [what a study costs](https://humanish.dev/docs/what-a-study-costs).
 
 ## See what studies have found
 
-humanish runs studies. Realistic synthetic participants, each with its own
-goals, patience, and skill, actually use your product on isolated desktops while
-you watch. A study leaves verifiable evidence: screenshots, action traces,
-per-task completion funnels, participant outcomes with the denominator
-attached, and estimated cost lines. A fail-closed share-safety gate decides what
-goes into feedback drafts, export bundles and an `observe --all --safe` library, and the
-end of the pipeline is a public-safe feedback draft you can turn into a real
-issue. Committed study source lives under `humanish/`; run evidence lands under
-gitignored `.humanish/`. [ARCHITECTURE.md](ARCHITECTURE.md) traces `humanish run <study>` through
-the code.
+A study's evidence includes per-task completion funnels and participant outcomes with the
+denominator attached. The share-safety gate decides what goes into feedback drafts, export
+bundles and an `observe --all --safe` library, and the end of the pipeline is a public-safe
+feedback draft you can turn into a real issue. [ARCHITECTURE.md](ARCHITECTURE.md) traces
+`humanish run <study>` through the code.
 
 The researcher declares the study, the participant tries the product, and the
 stakeholder reads what happened. [Three roles](docs/principles/three-roles.md)
@@ -141,7 +176,7 @@ maintainer did not write: TodoMVC 5 of 6 findings confirmed against the source,
 drawDB 11 of 12, none invented
 ([TodoMVC](https://github.com/danielgwilson/humanish/blob/main/bench/RESULTS-TODOMVC-2026-09-01.md), [drawDB](https://github.com/danielgwilson/humanish/blob/main/bench/RESULTS-DRAWDB-2026-09-01.md)).
 Cold install to a live study: 9 of 9 fresh directories reached the goal in 108 to 200 seconds;
-the five on the API route cost $0.16 to $0.35 each, and the four on Codex or Claude Code are
+the five with an OpenAI key cost $0.16 to $0.35 each, and the four on Codex or Claude Code are
 unpriced ([study record](https://github.com/danielgwilson/humanish/blob/main/docs/evidence/computer-use/cold-install-try-live-2026-09-01.md)).
 Same mission, different personas: keyboard-first participants reported drawDB's
 database modal 5 of 5 times and TodoMVC's mouse-only rename 6 of 6; mouse newcomers
@@ -160,6 +195,8 @@ npx humanish verify --run latest --json
 npx humanish feedback issue --run latest --repo owner/repo --format markdown
 ```
 
+`review` lists each analysis finding with its impact, confidence, recovery,
+affected participants and cited captures; `--json` has them under `analysis`.
 `feedback issue` prints a draft and requires `share_ready` evidence. A live run
 with raw screenshots can be valid local evidence and still fail that sharing
 gate. `humanish export --run latest --format bundle --redact-screenshots` creates
@@ -256,12 +293,22 @@ certified free of PII or PHI. A first-class PII/PHI detector is
 Feedback commands require `share_ready`. A valid local run can still be
 reviewed in Observer without being promoted into a public issue draft.
 
-## Know these limits before you depend on humanish
+## Check the compatibility policy before upgrading
 
-**Stability.** humanish is 0.x. There is no written compatibility policy, and
-a minor release can remove exports and options that an earlier release
-deprecated. Pin the exact version and read [CHANGELOG.md](CHANGELOG.md) before
-upgrading.
+humanish is 0.x, so a minor release can break things. These rules limit how. They cover CLI
+commands and flags, study file fields, the run bundle, `--json` output, exit and error codes,
+and the library exports.
+
+- A deprecated name keeps working for at least 30 days and through at least one minor release
+  before a release removes it.
+- Breaking changes ship together in one minor release. Its release notes carry a migration
+  table: each old form, its new form, and the change to make.
+- The study file and the run bundle carry versioned schemas, `humanish.study.v3` and
+  `humanish.run-bundle.v1`. A breaking change to either one bumps its version.
+
+Pin the exact version in `package.json` and read [CHANGELOG.md](CHANGELOG.md) before upgrading.
+
+## Know these limits before you depend on humanish
 
 **CI runs nothing live.** CI runs the offline test suite, the Observer browser
 proofs and, when guest files change, a guest-desktop container proof. It passes
@@ -285,14 +332,14 @@ why. A hosted participant on a release humanish has not tested records a warning
 the first of these sources that has it. It prints the name and source of a key it
 fills from sources 2 to 4, never the value:
 
-1. the process environment, including a file passed with `--env-file`;
+1. the process environment, including a file passed with `--dotenv`;
 2. `.humanish/local/provider.env`;
 3. the vendor's own store: `~/.e2b/config.json` for `E2B_API_KEY`, and
    `gh auth token` for `GH_TOKEN`;
 4. `$XDG_CONFIG_HOME/humanish/keys.env` (by default `~/.config/humanish/keys.env`),
    which `humanish keys set` writes as plain text with mode `0600`.
 
-A dry run reads no provider key, so `run`, `run` and `watch` consult sources 2 to 4 only
+A dry run reads no provider key, so `run` and `watch` consult sources 2 to 4 only
 for a live study. A live run fills every key it finds and prints the ones its plan reads: its model,
 desktop and runtime keys, its `subject.env` names, the variable
 `comms.email.external.authTokenEnv` names, `ANTHROPIC_API_KEY` for a Claude Code participant, and
@@ -322,19 +369,19 @@ has the providers' retention terms.
 Use `npx humanish` from your project. Full arguments and options are generated
 from the shipped CLI in the [command reference](https://humanish.dev/docs/cli).
 
-| Command                                                  | Purpose                                                                   |
-| -------------------------------------------------------- | ------------------------------------------------------------------------- |
-| `humanish init --yes`                                    | Scaffold study source and ignored runtime state.                          |
-| `humanish doctor --study <study> --json`                 | Check the selected route's setup without exposing key values or spending. |
-| `humanish study list --json`                             | List available studies.                                                   |
-| `humanish study show <study> --json`                     | Read a study before running it.                                           |
-| `humanish study check <study> --json`                    | Check configuration and route warnings.                                   |
-| `humanish run <study>`                                   | Run the named preview or live study.                                      |
-| `humanish watch <study>`                                 | Run a study with an attached Observer.                                    |
-| `humanish runs --json`                                   | List local run history.                                                   |
-| `humanish review --run latest --json`                    | Read an existing run's evidence.                                          |
-| `humanish verify --run latest --json`                    | Check evidence and share-safety gates.                                    |
-| `humanish feedback issue --run latest --repo owner/repo` | Print an eligible feedback draft.                                         |
+| Command                                                  | Purpose                                                        |
+| -------------------------------------------------------- | -------------------------------------------------------------- |
+| `humanish init --yes`                                    | Scaffold study source and ignored runtime state.               |
+| `humanish doctor --study <study> --json`                 | Check a study's setup without exposing key values or spending. |
+| `humanish study list --json`                             | List available studies.                                        |
+| `humanish study show <study> --json`                     | Read a study before running it.                                |
+| `humanish study check <study> --json`                    | Check configuration and route warnings.                        |
+| `humanish run <study>`                                   | Run the named preview or live study.                           |
+| `humanish watch <study>`                                 | Run a study with an attached Observer.                         |
+| `humanish runs --json`                                   | List local run history.                                        |
+| `humanish review --run latest --json`                    | Read a run's outcome and its analysis findings.                |
+| `humanish verify --run latest --json`                    | Check evidence and share-safety gates.                         |
+| `humanish feedback issue --run latest --repo owner/repo` | Print an eligible feedback draft.                              |
 
 ## Check exit codes
 
@@ -368,12 +415,14 @@ Source: [`skills/humanish/SKILL.md`](skills/humanish/SKILL.md).
 
 ## Find more guides
 
-- [Study files](https://humanish.dev/docs/study-files): source directories, route selection,
-  ignored private studies and
+- [How a study works](https://humanish.dev/docs/concepts): study, run, participant, persona,
+  actor, subject, route and the verify grades, on one annotated study file.
+- [Study files](https://humanish.dev/docs/study-files): every field with its type and default,
+  persona files and traits, ignored private studies and
   [scripted browser scenarios](https://humanish.dev/docs/study-files#scripted-browser-scenarios).
 - [Computer use](https://humanish.dev/docs/computer-use): subjects, screenshots, devices, mobile
   emulation, stop rules, dwell windows and reruns of failed participants. The
-  [cost model](https://humanish.dev/docs/budgets-and-privacy#how-cost-estimates-work) explains
+  [cost model](https://humanish.dev/docs/what-a-study-costs#how-cost-estimates-work) explains
   model selection, dated estimates, and study and per-participant caps.
 - [A signed-in coding agent](https://humanish.dev/docs/local-agents): Codex or Claude Code supplies
   the participant's model on your existing plan. E2B still needs a key and bills for desktops.
@@ -417,8 +466,8 @@ take which option.
 humanish sends anonymous usage events to PostHog by default. Each event carries
 the command, the humanish version, your OS and Node major version, whether it
 ran in CI, the exit code, a duration bucket and a random machine id made on
-first use. A study adds whether it was a dry run, an outcome word, the
-participant's brain route, stop and diagnostic categories, and humanish's error
+first use. A study adds whether it was a dry run, an outcome word, where the
+participant's model comes from (`brain`), stop and diagnostic categories, and humanish's error
 code when it fails. The study id is sent only when it is a starter study that
 `humanish init` writes; any other study is sent as `custom`. Your study ids,
 subjects, personas, prompts, paths, run ids and evidence are never sent.

package/dist/actors/computer-use/loop/ending.js

@@ -87,8 +87,8 @@ export function spendLimit(session, estimate, maxUsd) {
     return {
         completionReason: "budget_reached",
         reason: materialActions > 0
-            ? `Stopped before the next model turn: ${spend} passed execution.caps.maxUsd=$${maxUsd} after productive activity (${plural(materialActions, "material action")}, ${plural(turns, "turn")})`
-            : `Stopped before the next model turn: ${spend} passed execution.caps.maxUsd=$${maxUsd} with no material progress`,
+            ? `Stopped before the next model turn: ${spend} passed caps.maxUsd=$${maxUsd} after productive activity (${plural(materialActions, "material action")}, ${plural(turns, "turn")})`
+            : `Stopped before the next model turn: ${spend} passed caps.maxUsd=$${maxUsd} with no material progress`,
         stopCause: "spend_limit",
     };
 }
@@ -96,7 +96,7 @@ export function spendLimit(session, estimate, maxUsd) {
 // trip.
 export const nonFiniteEstimate = {
     completionReason: "harness_error",
-    reason: "the injected estimateTurnCostUsd returned a non-finite estimate while execution.caps.maxUsd is set; the estimator receives one ActorTokenUsage object. Failing closed instead of running uncapped.",
+    reason: "the injected estimateTurnCostUsd returned a non-finite estimate while caps.maxUsd is set; the estimator receives one ActorTokenUsage object. Failing closed instead of running uncapped.",
 };
 /** A study-level stop is a recruiting decision hitting its limit, not this participant's runaway. */
 export function runSpendLimit(reason) {
@@ -131,7 +131,7 @@ export const usageUnreported = {
  * limit is set, so its worst case is the model's whole output allowance.
  */
 export function lostRequestUnbounded(turnNumber, lost) {
-    const reason = `provider turn ${turnNumber} ${lost}; its usage is unknown and no maxOutputTokens bounds what it cost, so the declared model-spend cap cannot be established; no further or closing request was dispatched. Set actors[].maxOutputTokens so a capped session can book the worst case and retry.`;
+    const reason = `provider turn ${turnNumber} ${lost}; its usage is unknown and no maxOutputTokens bounds what it cost, so the declared model-spend cap cannot be established; no further or closing request was dispatched. Set actor.maxOutputTokens so a capped session can book the worst case and retry.`;
     return {
         completionReason: "harness_error",
         reason,

package/dist/actors/local-agent/claude-participant.d.ts

@@ -0,0 +1,74 @@
+type JsonObject = Record<string, unknown>;
+/**
+ * The first release with `--restricted`. The changelog adds it in 2.1.248; `claude --help` of
+ * 2.1.247 does not list it and 2.1.248 lists it with `--tools`, `--strict-mcp-config`,
+ * `--no-session-persistence` and `--permission-mode dontAsk`.
+ */
+export declare const CLAUDE_CODE_MIN_VERSION = "2.1.248";
+/**
+ * The flags that restrict a participant, shared by the session and one-shot paths. Each one was
+ * checked against `claude --help` of 2.1.248 and 2.1.289.
+ */
+export declare function claudeParticipantFlags(model?: string): string[];
+/**
+ * Names the participant's environment keeps from the host. Measured on Linux: `HOME` alone signs
+ * in a `claude.ai` login, and `PATH` finds `claude`. `USER` and `LOGNAME` name the macOS keychain
+ * account, `CLAUDE_CONFIG_DIR` moves Claude Code's own login and config, and the proxy and CA
+ * names are for hosts that reach the API through a proxy. Everything else is dropped: provider
+ * keys, `GH_TOKEN`, every `--dotenv` name, `ANTHROPIC_API_KEY` and `CLAUDE_CODE_OAUTH_TOKEN`, and
+ * the `CLAUDE_CODE_*` variables of a Claude Code session humanish itself runs inside.
+ */
+export declare const CLAUDE_PARTICIPANT_ENV_NAMES: readonly string[];
+/**
+ * The participant's whole environment: the allowlisted names `source` holds, minus any a `--dotenv`
+ * file set. The advisor is a server-side tool Claude Code enables by default on some plans; it is
+ * turned off so the only tool the stream can show is Read.
+ */
+export declare function claudeParticipantEnv(source: Readonly<Record<string, string | undefined>>): NodeJS.ProcessEnv;
+/** `2.1.289` from `2.1.289 (Claude Code)`; undefined for anything else. */
+export declare function parseClaudeCodeVersion(text: string): string | undefined;
+/** Whether `version` is at or above CLAUDE_CODE_MIN_VERSION. */
+export declare function admitsClaudeCodeVersion(version: string | undefined): boolean;
+/** The refusal for a Claude Code release below the floor, or one whose version could not be read. */
+export declare function claudeCodeVersionMessage(version: string | undefined): string;
+export type ClaudeParticipantErrorCode = 
+/** Claude Code started with more than Read, with an MCP server, or in another permission mode. */
+"HUMANISH_CLAUDE_PARTICIPANT_UNRESTRICTED"
+/** The participant called a tool other than Read inside its folder, or Claude Code denied one. */
+ | "HUMANISH_CLAUDE_PARTICIPANT_TOOL_REFUSED";
+/** The participant was stopped because its stream showed something it may not do. */
+export declare class ClaudeParticipantError extends Error {
+    readonly code: ClaudeParticipantErrorCode;
+    constructor(code: ClaudeParticipantErrorCode, reason: string);
+}
+/**
+ * Checks every stream-json message from one participant process. `inspect` returns the error the
+ * message proves, or undefined. A `result` counts only after an init message was admitted.
+ */
+export declare class ClaudeStreamGuard {
+    private readonly folders;
+    private admitted;
+    /** `folders`: the session folder, as given to Claude Code and as resolved on disk. */
+    constructor(folders: readonly string[]);
+    inspect(message: JsonObject): ClaudeParticipantError | undefined;
+    private system;
+    private assistant;
+    private inside;
+}
+/** Transcript folders Claude Code saved for earlier participants, before `--no-session-persistence`. */
+export type LeftoverClaudeTranscripts = {
+    /** Claude Code's projects folder. */
+    directory: string;
+    /** The matched folder names. */
+    names: string[];
+    /** Removes exactly `names`; absent when there are none or the folder path is not ASCII. */
+    removeCommand?: string;
+}
+/** The folder exists but could not be listed; `code` is the error code, such as `EACCES`. */
+ | {
+    directory: string;
+    unreadable: string;
+};
+/** Lists leftover participant transcripts. Reads folder names only, never their contents. */
+export declare function leftoverClaudeTranscripts(env: Readonly<Record<string, string | undefined>>, home: string, list: (directory: string) => Promise<string[]>): Promise<LeftoverClaudeTranscripts>;
+export {};