humanish 0.108.0 → 0.109.1

package/dist/verify/subject.d.ts

@@ -9,7 +9,7 @@ import type { RunBundle } from "../run/bundle.js";
 export declare function subjectStateFindings(bundle: RunBundle): string[];
 /**
  * Advisory (never flips ok): a live clone bundle whose subject env is provisioned while its
- * state story is undeclared probably points at state the lab does not control. Emitted at
+ * state story is undeclared probably points at state the study does not control. Emitted at
  * most once per bundle (the subject block is bundle-level, never per stream). GITHUB_TOKEN
  * is mechanically excluded: the harness consumes that name for clone auth, and it carries no
  * state implication.

package/dist/verify/subject.js

@@ -100,7 +100,7 @@ export function subjectStateFindings(bundle) {
 }
 /**
  * Advisory (never flips ok): a live clone bundle whose subject env is provisioned while its
- * state story is undeclared probably points at state the lab does not control. Emitted at
+ * state story is undeclared probably points at state the study does not control. Emitted at
  * most once per bundle (the subject block is bundle-level, never per stream). GITHUB_TOKEN
  * is mechanically excluded: the harness consumes that name for clone auth, and it carries no
  * state implication.

package/dist/verify/verify.js

@@ -17,6 +17,7 @@ import { costAndReceiptFindings } from "./costs.js";
 import { rerunLineageFindings } from "./rerun.js";
 import { sharedWorldEvidenceFindings } from "./shared-world.js";
 import { subjectStateFindings, undeclaredSubjectStateWarnings } from "./subject.js";
+import { plural } from "../run/text.js";
 export const VERIFY_SCHEMA = "humanish.verify-result.v1";
 // The UNSCANNED_ARTIFACT reason names this many paths and counts the rest.
 const MAX_LISTED_UNSCANNED = 10;
@@ -362,7 +363,7 @@ function buildShareSafety(args) {
         const more = paths.length - MAX_LISTED_UNSCANNED;
         reasons.push({
             code: "UNSCANNED_ARTIFACT",
-            message: `The public-safety scan cannot read ${paths.length} file(s) as text, and they are not stream screenshots under screenshots/ or registered recordings: ${shown}${more > 0 ? ` and ${more} more` : ""}. Review them before sharing.`,
+            message: `The public-safety scan cannot read ${plural(paths.length, "file")} as text that ${paths.length === 1 ? "is not a stream screenshot under screenshots/ or a registered recording" : "are not stream screenshots under screenshots/ or registered recordings"}: ${shown}${more > 0 ? ` and ${more} more` : ""}. Review them before sharing.`,
         });
     }
     const rawStreamIds = rawScreenshotStreamIds(args.bundle, args.redactedShapeFrames);

package/docs/architecture/actor-contract.md

@@ -9,7 +9,7 @@ extension seams, but public out-of-tree actor registration and its conformance c
 shipped. Also not shipped: the full `Actor.run(input)` interface, `ApprovalPolicy`,
 `StagehandCuaActor`, and the `persona-fidelity` verify check. `RedactionHooks` ships in
 `src/evidence/redaction.ts`, and the computer-use loop takes it; the other adapters do not take it
-yet. Of the capabilities, routing checks `lanes` and `producesScreenshots` (`src/lab/routing.ts`):
+yet. Of the capabilities, routing checks `lanes` and `producesScreenshots` (`src/study/routing.ts`):
 an actor that declares no screenshots cannot run on the computer-use or scripted-browser route.
 Decision 6's capture-time screenshot stance was recanted in 0.6.0; see the inline notes and the
 capture-vs-publish rule in
@@ -17,7 +17,7 @@ capture-vs-publish rule in
 
 `codex-exec` is a real dispatch key for terminal-product studies, but the exported
 descriptor `runSession` is a fail-closed compatibility entry. Live execution is
-owned by `runTerminalProductLab`, which coordinates sandbox creation,
+owned by `runTerminalProductStudy`, which coordinates sandbox creation,
 command-scoped runtime auth, evidence, caps, and by-id cleanup.
 
 The `pi-agent-core` and `claude-agent-sdk` descriptors, the `app` run kind and the
@@ -409,7 +409,7 @@ Plan:
 
 1. **Parse the whole persona** into a `ResolvedPersona`: `{ id, name, summary, goals[],
 traits: { patience, skill, accessibilityNeeds? }, constraints[], sourceDigest }` (map
-   `technical_confidence` to `skill`). The shipped shape in `src/lab/persona.ts` has no
+   `technical_confidence` to `skill`). The shipped shape in `src/study/persona.ts` has no
    `goals`, adds `background`, and makes every trait optional.
 2. **Compile traits into actor-neutral directives**, not prose, via a pure
    `personaToDirectives(p)`:
@@ -435,7 +435,7 @@ traits: { patience, skill, accessibilityNeeds? }, constraints[], sourceDigest }`
    candidate. The harness imposes no turn cap; its hard stops are the wall-clock
    `timeoutMs` and declared spend caps.
 4. **Bind the same directives per harness.** `renderPersonaPromptSection`
-   (`src/lab/persona.ts`) renders the directives as one prompt section, and each harness puts
+   (`src/study/persona.ts`) renders the directives as one prompt section, and each harness puts
    that section where its model reads standing instructions:
    - Computer use: `composeParticipantInstructions`
      (`src/routes/computer-use/participant-prompt.ts`) opens the participant instructions
@@ -465,7 +465,7 @@ traits: { patience, skill, accessibilityNeeds? }, constraints[], sourceDigest }`
    `persona-fidelity` verify check asserts that the friction and accessibility directives
    reached the actor input and that a `gave_up` run cites a concrete friction reason (not a
    turn count). "Did the persona drive the run" becomes a verifiable artifact. (Status
-   2026-06-11: `personaToDirectives` shipped in `src/lab/persona.ts` and `traitsApplied` is
+   2026-06-11: `personaToDirectives` shipped in `src/study/persona.ts` and `traitsApplied` is
    threaded on the codex-exec terminal route, but the `persona-fidelity` verify check is
    not-yet-shipped roadmap. The computer-use route records `persona.traitsApplied` from the
    resolved persona in `src/routes/computer-use/participant-prompt.ts`.)

package/docs/architecture/browser-control.md

@@ -61,7 +61,7 @@ admission. There is no generic CDP, command, file, navigation-management, or
 runtime-management method. Initial target navigation remains an adapter-owned
 operation.
 
-Replies acknowledge completion or contain a finite `CuaExecutorError` code and
+Replies acknowledge completion or contain a finite `ComputerUseExecutorError` code and
 `not_dispatched` / `outcome_uncertain` disposition. They never include raw
 exception prose, typed text, page URLs, or browser errors in their error fields.
 A generic driver exception after invocation is uncertain; only a genuine typed

package/docs/architecture/external-public-shared-world.md

@@ -31,13 +31,13 @@ dropped: `plane.exposure` must be absent (claiming synthetic on a real site is a
 external-public disclosure limits are required.
 
 Why the getHost synthetic gate is deliberately not reachable from the app-url branch: that gate
-(`concurrentSharedWorldValidationReason` in `src/lab/validation.ts` requires `subject.exposure:
+(`concurrentSharedWorldValidationReason` in `src/study/validation.ts` requires `subject.exposure:
 synthetic`, a `0.0.0.0` bind and no `keep`; verify's `getHostPlaneFindings` in
 `src/verify/shared-world-concurrent.ts` then requires `plane.exposure == synthetic` and
 `subject.state.provenance == seeded`) exists because a getHost URL is internet-reachable and
 harness-owned; real data behind a harness-exposed URL is the hazard. A public site the harness
 neither provisioned nor exposed has neither property, so the gate's hazard does not exist there. The
-app-url branch is validated by `externalPublicSharedWorldValidationReason` (`src/lab/validation.ts`)
+app-url branch is validated by `externalPublicSharedWorldValidationReason` (`src/study/validation.ts`)
 and is reached before the getHost gate; a snapshot regression test pins the getHost path
 byte-unchanged.
 
@@ -51,17 +51,18 @@ page, and sends `Runtime.evaluate({ url: location.href, title, text })` over the
 `CuaObservation.url` is runtime-only by contract (it drives `stopWhen`/progress but is never
 persisted raw into the trace).
 
-The route reads each participant's URL through one callback, `CuaLoopOptions.onObservedUrl?(url)`,
+The route reads each participant's URL through one callback, `LoopTaps.onObservedUrl?(url)`,
 invoked right after every `executor.observe()` (the initial observe and each loop observe) with
 `observation.url`, threaded through `CuaActorSessionOptions` → `CuaParticipantDeps` → the concurrent
 orchestrator. It adds no CDP code and needs no change to the lobby-trivia app. The CDP URL read is
 unreliable on E2B desktops, so the host's code can also come from its narration or its screen
 (step 2).
 
-`onObservedUrl`, `onMessage` and `onScreenshot` are deprecated on `CuaLoopOptions`, and the next
-minor removes them. A `runComputerUseLoop` caller that used them wraps the executor's `observe`
-(for `url` and `screenshot`) or the provider's `nextTurn` (for `reasoning` and `message`). The
-handoff still passes all three.
+`onObservedUrl`, `onMessage` and `onScreenshot` are internal `LoopTaps`
+(`src/actors/computer-use/loop/types.ts`): 0.109.0 removed them from `ComputerUseLoopOptions`, and the
+public `runComputerUseLoop` refuses them. The actor passes them through
+`runComputerUseLoopWithTaps`. A library caller wraps the executor's `observe` (for `url` and
+`screenshot`) or the provider's `nextTurn` (for `reasoning` and `message`).
 
 Flow, a host-first barrier inside `runConcurrentSharedWorld`'s fan-out:
 

package/docs/architecture/github-feedback-loop.md

@@ -79,7 +79,7 @@ readiness, uses the labels and the `humanish_swarm` block below.
   draft (`src/feedback/draft.ts`).
 - `adapter-hardening`, `target-app-setup`, `actor-auth` and
   `setup-quality-review`: feedback candidates that an adapter adds to the
-  bundle. `src/lab/adapter-extension.ts` checks the value.
+  bundle. `src/study/adapter-extension.ts` checks the value.
 
 ## Issue Body Contract
 

package/docs/architecture/task-protocol-support.md

@@ -24,7 +24,7 @@ this preflight does not certify arbitrary hook behavior.
 
 The parser reports `HUMANISH_STUDY_INVALID` with the unsupported field path. `runStudy`
 reports `HUMANISH_STUDY_TASKS_UNSUPPORTED` in the route's failure envelope, from
-`planLab` (`src/lab/plan.ts`) and each route's plan.
+`planStudy` (`src/study/plan.ts`) and each route's plan.
 Refusal precedes run storage, source preparation, user hooks, local processes,
 sandbox allocation, and model calls. No task content appears in the error.
 

package/docs/architecture/terminal-product-route.md

@@ -24,23 +24,23 @@ fail-closed cross-validation, and forward-declared warnings.
 
 ## The composition
 
-| Axis                              | Value                                                                                                                                                     |
-| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `subject.source`                  | `terminal-product`                                                                                                                                        |
-| `subject.product`                 | `{ name, publicSurfaces[], install?, workdir?, upload? }`: the only world the agent sees                                                                  |
-| `execution.target`                | `e2b-terminal` (or absent → implied)                                                                                                                      |
-| `execution.terminal`              | `{ transport: exec-stream, stdin: disabled }`                                                                                                             |
-| `execution.runtimeAuth`           | `openai-env` (default) or opt-in `openai-egress`; names-only durable evidence                                                                             |
-| `execution.runtime.version`       | Optional exact `@openai/codex` version; observed before keyed execution                                                                                   |
-| `actor.model` / `reasoningEffort` | Passed to Codex as `--model` (default `gpt-5.6-sol`) and `-c model_reasoning_effort`; declarations, not observed provider identity                        |
-| `caps`                            | `{ maxUsd, maxJobs, maxMinutes }`: the blast-radius budget; `maxUsd > 0` is refused unless a `costProbe` measures spend                                   |
-| `policies`                        | `allowPrivateRepoAccess` / `allowProviderCredentials` / `allowPaymentCredentials` / `allowGitHubMutation`, all default false                              |
-| `actor.type`                      | `codex-exec`: a registered terminal actor (`keyPlacement: in-sandbox-command-scoped`)                                                                     |
-| route                             | `terminal` → `runTerminalProductLab` ([`src/routes/terminal/route.ts`](https://github.com/danielgwilson/humanish/blob/main/src/routes/terminal/route.ts)) |
-
-Routing is `routeOf` (`src/lab/plan.ts`). It sends every `terminal-product` subject to
+| Axis                              | Value                                                                                                                                                       |
+| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `subject.source`                  | `terminal-product`                                                                                                                                          |
+| `subject.product`                 | `{ name, publicSurfaces[], install?, workdir?, upload? }`: the only world the agent sees                                                                    |
+| `execution.target`                | `e2b-terminal` (or absent → implied)                                                                                                                        |
+| `execution.terminal`              | `{ transport: exec-stream, stdin: disabled }`                                                                                                               |
+| `execution.runtimeAuth`           | `openai-env` (default) or opt-in `openai-egress`; names-only durable evidence                                                                               |
+| `execution.runtime.version`       | Optional exact `@openai/codex` version; observed before keyed execution                                                                                     |
+| `actor.model` / `reasoningEffort` | Passed to Codex as `--model` (default `gpt-5.6-sol`) and `-c model_reasoning_effort`; declarations, not observed provider identity                          |
+| `caps`                            | `{ maxUsd, maxJobs, maxMinutes }`: the blast-radius budget; `maxUsd > 0` is refused unless a `costProbe` measures spend                                     |
+| `policies`                        | `allowPrivateRepoAccess` / `allowProviderCredentials` / `allowPaymentCredentials` / `allowGitHubMutation`, all default false                                |
+| `actor.type`                      | `codex-exec`: a registered terminal actor (`keyPlacement: in-sandbox-command-scoped`)                                                                       |
+| route                             | `terminal` → `runTerminalProductStudy` ([`src/routes/terminal/route.ts`](https://github.com/danielgwilson/humanish/blob/main/src/routes/terminal/route.ts)) |
+
+Routing is `routeOf` (`src/study/plan.ts`). It sends every `terminal-product` subject to
 this route, even with an unregistered actor, so this route refuses the actor.
-`isTerminalProductComposition(config)` (`src/lab/routing.ts`) also feeds the forward-declared
+`isTerminalProductComposition(config)` (`src/study/routing.ts`) also feeds the forward-declared
 warnings.
 
 ## Repeating a terminal study with the same runtime
@@ -214,8 +214,8 @@ the cleanup proof, the interventions ledger and a minimal fail-closed cap.
 ## Test seams
 
 The route reads `env` and `scorer` from its options (`src/routes/terminal/types.ts`), and a test
-passes its seams (`desktopModule`, `renderObserver`, `now`, `costProbe`) as `LabDeps`
-(`src/lab/lab-deps.ts`).
+passes its seams (`desktopModule`, `renderObserver`, `now`, `costProbe`) as `StudyDeps`
+(`src/study/study-deps.ts`).
 
 ## The product-adapter extension seam
 

package/docs/contracts/adapter-fixtures.md

@@ -39,7 +39,7 @@ A fixture can be promoted only when:
 - credential policy records env var names only, never values;
 - adapter-owned nouns do not appear in core schema docs or core runtime code;
 - public feedback material states that GitHub mutation was not performed;
-- the fixture can be checked with `pnpm test tests/lab/adapter-fixtures.test.ts`
+- the fixture can be checked with `pnpm test tests/study/adapter-fixtures.test.ts`
   and `pnpm public-surface:scan`.
 
 ## Dry-Run Web-App Fixture Shape
@@ -74,6 +74,6 @@ This keeps terminal and feedback parity independent from browser screenshots.
 ## Proof Commands
 
 ```bash
-pnpm test tests/lab/adapter-fixtures.test.ts
+pnpm test tests/study/adapter-fixtures.test.ts
 pnpm public-surface:scan
 ```

package/docs/contracts/errors.md

@@ -15,7 +15,7 @@ release.
 - Human mode: two or three lines on stderr.
 
   ```text
-  humanish run failed: Study not found: nope. Look in humanish/studies/ or humanish/labs/, or pass a .yaml path.
+  humanish run failed: Study not found: nope. Look in humanish/studies/, or pass a .yaml path.
   code: HUMANISH_STUDY_NOT_FOUND
   next: humanish study list
   ```
@@ -33,13 +33,13 @@ release.
 
 ## Families
 
-| Family                 | Codes | Emitted by                                                               | Appears in                                                              |
-| ---------------------- | ----- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------- |
-| `HUMANISH_*`           | 137   | every CLI command and route result                                       | JSON `error.code`, library `error.code`, human `code:` line             |
-| `ANALYSIS_*`           | 86    | `humanish analyze` and the analysis service (`src/analysis/`)            | JSON `error.code` of analysis results                                   |
-| `AUTOMATIC_ANALYSIS_*` | 21    | the post-run analysis job                                                | `automaticAnalysis.reason` on a run result and the job record           |
-| `analysis_*` lowercase | 29    | analysis execution                                                       | `error` fields in analysis artifacts and execution receipts             |
-| `codex_*` lowercase    | 13    | the Codex CLI readiness check (`src/actors/codex/`, `src/lab/doctor.ts`) | doctor rows and analysis readiness, such as `codex_unsupported_version` |
+| Family                 | Codes | Emitted by                                                                 | Appears in                                                              |
+| ---------------------- | ----- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `HUMANISH_*`           | 138   | every CLI command and route result                                         | JSON `error.code`, library `error.code`, human `code:` line             |
+| `ANALYSIS_*`           | 86    | `humanish analyze` and the analysis service (`src/analysis/`)              | JSON `error.code` of analysis results                                   |
+| `AUTOMATIC_ANALYSIS_*` | 21    | the post-run analysis job                                                  | `automaticAnalysis.reason` on a run result and the job record           |
+| `analysis_*` lowercase | 29    | analysis execution                                                         | `error` fields in analysis artifacts and execution receipts             |
+| `codex_*` lowercase    | 13    | the Codex CLI readiness check (`src/actors/codex/`, `src/study/doctor.ts`) | doctor rows and analysis readiness, such as `codex_unsupported_version` |
 
 Counts are the distinct quoted codes in `src/` on 2026-10-03.
 

package/docs/contracts/run-bundle.md

@@ -26,10 +26,7 @@ study: # optional, additive: which study file produced this run
   id: "<study id>"
   path: "humanish/studies/<study id>.yaml"
   origin: "committed|ignored|explicit"
-lab: # the same value as study, written until 0.109
-  id: "<study id>"
-  path: "humanish/studies/<study id>.yaml"
-  origin: "committed|ignored|explicit"
+# Runs saved by 0.108 and earlier also have `lab:`, with the same value as `study:`.
 source:
   packageName: "<public package name or null>"
   humanishSource: "present|missing"
@@ -636,6 +633,11 @@ The receipt describes the transformation; it does not attest that a participant'
 finding is true. Its own bytes are not included in its hash inventory. Feedback
 commands can subsequently generate new derivative-local artifacts.
 
+The derivative names no sandbox. In every JSON and NDJSON file it copies, the
+values at `sandboxId`, `subjectSandboxId` and each `providerResources[].id` read
+`[redacted-sandbox-id]`; `sandbox-receipts.ndjson` is omitted. The source keeps
+its raw ids, which cleanup and reclaim read.
+
 PNG files that actor traces reference as stream screenshots are re-encoded as
 blurred thumbnails. A PNG that nothing in `run.json` cites is omitted and
 inventoried. Export refuses a run whose feedback candidates, adapter artifacts or

package/docs/contracts/schemas.md

@@ -58,9 +58,10 @@ workflow without leaking private upstream truth into core.
 
 ## Study File
 
-Schema: `humanish.study.v3`. `src/lab/parse/study-v3.ts` rewrites a v3 document into the
-normalized config in `src/lab/types.ts`, which `src/lab/config.ts` parses. A `humanish.lab.v2`
-file still parses in 0.108 with one warning that names `humanish migrate`; 0.109 removes it.
+Schema: `humanish.study.v3`. `src/study/parse/study-v3.ts` rewrites a v3 document into the
+normalized config in `src/study/types.ts`, which `src/study/config.ts` parses. humanish refuses a
+`humanish.lab.v2` file with `HUMANISH_STUDY_V2_UNSUPPORTED`, whose message names
+`humanish migrate <path>`; migrate converts the file to v3.
 
 A study declares its route and composes code primitives; it is not a hardcoded kind. The
 top-level keys:
@@ -95,7 +96,7 @@ unknown key is an error that lists the known ones; both are `HUMANISH_STUDY_INVA
 `computer-use` and `shared-world` read `maxUsd` and `maxTotalUsd`; `terminal` reads `maxUsd`,
 `maxJobs` and `maxMinutes`; `preview` and `scripted` take no `caps`.
 
-A v2 file maps as follows: `actors[0]` is `actor`; `lanes` is the `participants` list; a
+`humanish migrate` maps a v2 file as follows: `actors[0]` is `actor`; `lanes` is the `participants` list; a
 `roster` group is an entry with `count`; `count` is the count; `count` with `laneFocus` is the
 homogeneous object; `execution.caps` (computer-use, shared-world) or `scenario.caps`
 (terminal) is `caps`; `scenario.mode` is `mode`; `scenario.ref` is `scenario`; and
@@ -413,8 +414,8 @@ run local-only regardless of screenshot redaction. See the
 [receiving contract](https://humanish.dev/docs/email-receiving).
 
 A study's result has one schema on every route, `humanish.study-result.v1`
-(`src/run/study-result.ts`), with `route`, `studyId` and, until 0.109, a deprecated `labId`
-holding the same value. Route-specific fields stay on their route's result. `humanish run`
+(`src/run/study-result.ts`), with `route` and `studyId`. 0.109.0 removed `labId`, which 0.108.0
+wrote with the same value. Route-specific fields stay on their route's result. `humanish run`
 with no study, `observe`, and a refusal made before a route is picked keep
 `humanish.run-result.v1`. The evidence record stays `humanish.run-bundle.v1` in every case.
 The computer-use result carries `plan` (the pre-flight participant table: concurrency, waves,
@@ -449,7 +450,11 @@ Study files are human-authored `.yaml` source under `humanish/studies/*.yaml` fo
 committed public-safe studies, or ignored `.humanish/studies/*.yaml` /
 `.humanish/local/studies/*.yaml` for private local dogfood. A v3 key the declared route
 does not read is an error, so a study file never silently claims behavior that did not run.
-A v2 file keeps its inert-field warnings until 0.109 (`humanish study show` shows them).
+A name found only in one of the three `labs/` directories is refused: a v2 file with
+`HUMANISH_STUDY_V2_UNSUPPORTED`, and a v3 file with `HUMANISH_STUDY_RETIRED_DIRECTORY`, whose
+message names the matching `studies/` directory to move it to. A path to a v3 file runs wherever
+the file is. `study list --json`
+lists the refused files in `retired`, each `{ path, code, message }`.
 
 Committed fixture (`humanish/studies/first-run.yaml`):
 
@@ -496,14 +501,13 @@ Core-owned fields:
 - `review`
 - `feedbackCandidates`
 - `study` (optional, additive): which study file produced the run,
-  `{ id, path?, origin? }`, where `origin` is `committed` (`humanish/studies/`, or
-  `humanish/labs/` for a v2 file),
-  `ignored` (a local overlay), or `explicit` (a path the operator passed).
-  `lab` holds the same value until 0.109 removes it, so a 0.107 reader keeps working.
-  Both are absent on bundles written before this contract and on library callers who
-  hand a `StudyConfig` directly; such a run has no study. Readers go through
-  `studyProvenanceOf` (`src/run/study-provenance.ts`): a valid `study`, else a valid `lab`,
-  else `inferLegacyStudyId`, which reads the `persona.source` or `scenario.source`
+  `{ id, path?, origin? }`, where `origin` is `committed` (`humanish/studies/`; a run saved by
+  0.108 or earlier can name `humanish/labs/`), `ignored` (a local overlay), or `explicit` (a path
+  the operator passed). Runs saved by 0.108 and earlier also have `lab` with the same value;
+  0.109 writes `study` only. `study` is absent on bundles written before this contract and on
+  library callers who hand a `StudyConfig` directly; such a run has no study. Readers go through
+  `studyProvenanceOf` (`src/run/study-provenance.ts`): a valid `study`, else a valid `lab` from
+  an older run, else `inferLegacyStudyId`, which reads the `persona.source` or `scenario.source`
   convention `study:<id>`, or `lab:<id>` from runs written before 0.108, and nothing else.
 - `subject` (optional, additive): structured subject provenance,
   `{ source: clone | app-url | local-tree, repo?, commit?, archiveSha256?,
@@ -1141,10 +1145,11 @@ proof claims zero on a `null` line, or when known spend exceeds the declared cap
 `humanish.run-status.v1` is `status.json`, written inside each run directory by
 every route at run start, refreshed on a fixed cadence while the run is
 alive, and finalized when it ends: `{ schema, runId, state: running |
-finished | interrupted, mode, study?, lab?, pid, startedAt, updatedAt, completedAt?,
-signal?, outcome? }`. `lab` repeats `study` until 0.109.
-`outcome` carries the bundle's `verdict`, `participants` and `estimatedCostUsd`
-when the run finishes, then the result's `ok` and `execution: { succeeded,
+finished | interrupted, mode, study?, pid, startedAt, updatedAt, completedAt?,
+signal?, outcome? }`. A record written by 0.108 or earlier also has `lab`, with the same value as
+`study`, and readers accept it.
+`outcome` carries the bundle's `verdict`, `participants`, `estimatedCostUsd` and
+`estimatedCostComplete` when the run finishes, then the result's `ok` and `execution: { succeeded,
 failures: [{ kind, message }], warnings? }` once the Observer has rendered. The
 verdict is what the participants experienced; `execution` is whether the run
 worked as an execution (`kind` is `harness`, `provider-cleanup`,
@@ -1164,6 +1169,11 @@ the participant (or `subject`), the release warning and the
 `humanish reclaim --run <id>` command. A local VM writes no receipt, so its
 entry names the container and the `docker rm --force --volumes <container>`
 command that removes it (through `limactl shell` on a Mac).
+`estimatedCostUsd` is the participants-and-desktops estimate and excludes
+analysis. `estimatedCostComplete` is the bundle's `cost.fullyEstimated`, written
+with it at publish: false means some participant or desktop usage has no price
+and the estimate is a lower bound. A record without it, as every record before
+0.109, says nothing about completeness, and readers treat it as unknown.
 
 `interrupted` with `signal` (`SIGINT`, `SIGTERM` or `SIGHUP`) is written by
 the CLI's run command when that signal stops a live run outside post-run
@@ -1201,7 +1211,8 @@ them is a claim about what a participant did.
 cheapest-source-first: the `status.json` record, else the bundle, else the run
 directory alone. `{ runId, derivedFrom: status | bundle | directory, liveness,
 mode?, pid?, study?, startedAt?, updatedAt?, completedAt?, verdict?,
-participants?, estimatedCostUsd?, durationMs? }`. The point is cost: walking
+participants?, estimatedCostUsd?, estimatedCostComplete?, analysisCost?,
+durationMs? }`. The point is cost: walking
 every run tree and parsing every bundle measured 167ms on a 25-run project,
 against 16ms cold and 2.8ms warm here, which is what makes a surface that
 refreshes on a cadence affordable. `derivedFrom` is reported so a surprising row
@@ -1210,6 +1221,14 @@ can be traced to the file it came from. A run with receipts and no outcome is
 in-progress bundle reached without a status record: there is no freshness to
 judge, and nothing in it says the run finished.
 
+`estimatedCostUsd` is the participants-and-desktops figure from the status
+record or bundle and excludes analysis. `estimatedCostComplete` says whether that
+figure is whole, and is absent when the record does not say. `analysisCost`
+covers the analysis: `{ requests, estimatedUsd, complete, providers }` for every
+analysis attempt the run sent, read by the same reader as `humanish stats`, and
+absent when the run sent none. Analysis is written after the status record, so
+`analysisCost` is cached on a fingerprint of the run's analysis directories.
+
 `humanish.run-detail.v1` is the watching projection, for one run. Who is in it
 and what they are thinking: `{ runId, participants: [{ id, label, personaId?,
 traits, status?, completionReason?, thought?, turns?, actions?, thoughts?,
@@ -1472,23 +1491,22 @@ bundle, and its absence is tolerated by verify.
 
 `runStudy(config, options)` checks its `RunStudyOptions` against the study's route before anything
 runs. A refusal comes back in the route's own result envelope, with no run directory, receipt or
-sandbox. The 0.107 names (`runLab`, `RunLabOptions`, `parseLabConfig`, `LAB_CONFIG_SCHEMA`,
-`LabConfig`, the `Lab*` result and event types, the nine `Cua*` loop types, `CuaAdmissionLimitError`
-and `BrowserLabScoringContext`) are deprecated aliases with the same value or class until 0.109
-(`src/library-aliases.ts`).
-
-| Option                                   | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Routes                                                                                                                                                                  |
-| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `env`                                    | Keys and subject env for the run. Defaults to `process.env`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | all                                                                                                                                                                     |
-| `scorer`                                 | An `AdapterScorerModule` (`score`, `deriveFeedback`, and `deriveArtifacts` on browser routes) over the finished evidence. A scorer written for one context passes through `browserScorer` or `terminalScorer`                                                                                                                                                                                                                                                                                                                                                                                                                                              | computer use, shared world, terminal                                                                                                                                    |
-| `createProvider(ctx)`                    | The participant's brain. `ctx` is `ProviderContext`: `config`, `participant { id, index, count }` and `executor`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | computer use: E2B, local VM or in process                                                                                                                               |
-| `inProcess.executor({ config, appUrl })` | Drives an `app-url` or `local-app` subject in process, one participant. Requires `createProvider`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | computer use                                                                                                                                                            |
-| `prepareDesktop(desktop, target)`        | Runs on an E2B sandbox before provisioning. `target` is `{ kind: "subject" }` or `{ kind: "participant", participant }`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | computer use on E2B (each participant); shared world (provisioned: the subject, then each participant; external-public: each participant); scripted clone (the subject) |
-| `onEvent(event)`                         | Observes `StudyEvent`s, below                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | all                                                                                                                                                                     |
-| `onStream(event)`                        | Awaited. `ready` after a participant's live stream starts; its `url` carries an auth key and must never be persisted. `ended` after the participant's sandbox is gone. A rejected `ready` becomes a run warning; an `ended` rejection is swallowed. Each event carries `participantId`, `recordId` (the id of this participant's entry in `run.json` `simulations[]`, such as `sim-001`, which `streams[].simId` also holds) and `streamId`; `ready` adds `sandboxId` and `url`. `simId` is the older name for `recordId`: its first read prints a `DeprecationWarning` with code `HUMANISH_STREAM_EVENT_FIELD_DEPRECATED`, and the next minor removes it. | computer use and shared world on E2B                                                                                                                                    |
-| `analysisSignal`                         | Cancels post-run analysis only                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | routes with post-run analysis                                                                                                                                           |
-| `onObserverReady(observer)`              | Awaited before any participant desktop exists                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | live computer use; live shared world, where the provisioned subject sandbox is already billed                                                                           |
-| `rerun.participantIds`                   | Participants to rerun from `rerun.sourceRunId`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | computer use                                                                                                                                                            |
+sandbox. 0.109.0 removed the 0.107 names (`runLab`, `RunLabOptions`, `parseLabConfig`,
+`LAB_CONFIG_SCHEMA`, `LabConfig`, the `Lab*` result and event types, the nine `Cua*` loop types,
+`CuaAdmissionLimitError` and `BrowserLabScoringContext`), which 0.108.0 kept as deprecated aliases.
+
+| Option                                   | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Routes                                                                                                                                                                  |
+| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `env`                                    | Keys and subject env for the run. Defaults to `process.env`                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | all                                                                                                                                                                     |
+| `scorer`                                 | An `AdapterScorerModule` (`score`, `deriveFeedback`, and `deriveArtifacts` on browser routes) over the finished evidence. A scorer written for one context passes through `browserScorer` or `terminalScorer`                                                                                                                                                                                                                                                                                                                            | computer use, shared world, terminal                                                                                                                                    |
+| `createProvider(ctx)`                    | The participant's brain. `ctx` is `ProviderContext`: `config`, `participant { id, index, count }` and `executor`                                                                                                                                                                                                                                                                                                                                                                                                                         | computer use: E2B, local VM or in process                                                                                                                               |
+| `inProcess.executor({ config, appUrl })` | Drives an `app-url` or `local-app` subject in process, one participant. Requires `createProvider`                                                                                                                                                                                                                                                                                                                                                                                                                                        | computer use                                                                                                                                                            |
+| `prepareDesktop(desktop, target)`        | Runs on an E2B sandbox before provisioning. `target` is `{ kind: "subject" }` or `{ kind: "participant", participant }`                                                                                                                                                                                                                                                                                                                                                                                                                  | computer use on E2B (each participant); shared world (provisioned: the subject, then each participant; external-public: each participant); scripted clone (the subject) |
+| `onEvent(event)`                         | Observes `StudyEvent`s, below                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | all                                                                                                                                                                     |
+| `onStream(event)`                        | Awaited. `ready` after a participant's live stream starts; its `url` carries an auth key and must never be persisted. `ended` after the participant's sandbox is gone. A rejected `ready` becomes a run warning; an `ended` rejection is swallowed. Each event carries `participantId`, `recordId` (the id of this participant's entry in `run.json` `simulations[]`, such as `sim-001`, which `streams[].simId` also holds) and `streamId`; `ready` adds `sandboxId` and `url`. 0.109.0 removed `simId`, the older name for `recordId`. | computer use and shared world on E2B                                                                                                                                    |
+| `analysisSignal`                         | Cancels post-run analysis only                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | routes with post-run analysis                                                                                                                                           |
+| `onObserverReady(observer)`              | Awaited before any participant desktop exists                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | live computer use; live shared world, where the provisioned subject sandbox is already billed                                                                           |
+| `rerun.participantIds`                   | Participants to rerun from `rerun.sourceRunId`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | computer use                                                                                                                                                            |
 
 `StudyEvent` has four types:
 
@@ -1515,7 +1533,7 @@ still passes it is refused with `HUMANISH_STUDY_OPTION_UNSUPPORTED`; use `rerun.
 
 The route hook bags (`cuaHooks`, `scriptedHooks`, `terminalHooks`, `sharedWorldHooks`,
 `automaticAnalysis`) were removed from `RunStudyOptions`, with the hook bag types and the four route
-runners that took them (`runCuaActorLab`, `runScriptedBrowserLab`, `runTerminalProductLab`,
+runners that took them (`runCuaActorStudy`, `runScriptedBrowserStudy`, `runTerminalProductStudy`,
 `runConcurrentSharedWorld`). `lab` and `scorerProvenance` are set only by the humanish CLI. A
 JavaScript caller that passes any of these fields is refused before anything runs. Where each
 bag field's job went:
@@ -1544,11 +1562,11 @@ of it fails.
 | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `runDryRun`, `RunOptions`, `RunResult`                                                                                                         | `runStudy(config, options)` on a `this-repo` study; its result is `StudyResult<"preview">`                                                                                                                                                                                                                                                     |
 | `runCuaActorSession`                                                                                                                           | `runComputerUseLoop` with `createOpenAiResponsesProvider({ singleDispatch: true })`, `redaction: defaultRedactionHooks` and `now: Date.now`, which `runCuaActorSession` defaulted (the composition above). A caller that passed `desktop` and `executorOptions` writes its own `ComputerUseExecutor`: the E2B desktop executor is not exported |
-| `CuaActorLabResult`, `ScriptedBrowserLabResult`, `TerminalProductLabResult`, `ConcurrentSharedWorldLabResult`                                  | `StudyResult<"computer-use">`, `StudyResult<"scripted">`, `StudyResult<"terminal">`, `StudyResult<"shared-world">`                                                                                                                                                                                                                             |
+| `CuaActorStudyResult`, `ScriptedBrowserStudyResult`, `TerminalProductStudyResult`, `ConcurrentSharedWorldStudyResult`                          | `StudyResult<"computer-use">`, `StudyResult<"scripted">`, `StudyResult<"terminal">`, `StudyResult<"shared-world">`                                                                                                                                                                                                                             |
 | `SubjectPhaseEvent`                                                                                                                            | the `subject-phase` `StudyEvent` through `onEvent`. Its `type` is `"subject-phase"`; the phase that was `type` is `name`, and `target` is `{ kind: "subject" }` or `{ kind: "participant", participant }`. `message`, `at`, `ok` and `durationMs` are unchanged                                                                                |
 | `StudyOutcome.backend`, `LabBackend`                                                                                                           | `outcome.route`                                                                                                                                                                                                                                                                                                                                |
 | `selectLabBackend`, the `routesTo*` predicates, `actorResolvesToTerminal`                                                                      | `routeOf(config)`                                                                                                                                                                                                                                                                                                                              |
-| `resolveLabDryRun`                                                                                                                             | `RunStudyOptions.dryRun`; without it, `scenario.mode` decides                                                                                                                                                                                                                                                                                  |
+| `resolveStudyDryRun`                                                                                                                           | `RunStudyOptions.dryRun`; without it, `scenario.mode` decides                                                                                                                                                                                                                                                                                  |
 | `cuaLaneCount`                                                                                                                                 | the `plan` `StudyEvent`, which lists every participant                                                                                                                                                                                                                                                                                         |
 | `resolveSeatUrl`                                                                                                                               | `parseStudy`, which refuses a participant entry that is not same-origin loopback; build the URL with `new URL(entry, serveUrl)`                                                                                                                                                                                                                |
 | `cuaLaneValidationReason`, `sharedWorldValidationReason`, `concurrentSharedWorldValidationReason`, `externalPublicSharedWorldValidationReason` | `parseStudy`, which returns the same reason                                                                                                                                                                                                                                                                                                    |
@@ -1636,8 +1654,9 @@ The `e2b-terminal` substrate is added to `RunFeedbackCandidate.substrate` so a
 terminal-agent candidate names the substrate it ran on; browser candidates use
 the existing `e2b-desktop` substrate. The routes invoke hooks over fully-assembled,
 redacted evidence (`TerminalProductScoringContext` or
-`BrowserScoringContext`: `bundle`, runtime-only `runDir`, run identifiers,
-actor and route metadata; all exported public types), scrub+redact returned
+`BrowserScoringContext`: `bundle`, runtime-only `runDir`, the run identifiers
+`studyId` and `runId`, actor and route metadata; all exported public types; 0.109.0
+renamed the context's `labId` to `studyId`), scrub+redact returned
 payloads, and drop any malformed score, candidate, or artifact reference with a
 warning so a bad extension never poisons a verifiable bundle. On the terminal
 route the context also carries `transcript`: the full normalized session

package/docs/contracts/study-analysis.md

@@ -229,7 +229,10 @@ This presentation does not rewrite the saved analysis or reviewer corrections.
 The frozen `humanish.observer-data.v1` schema is unchanged. A companion
 `humanish.study-analysis.v1` artifact records source/config/input hashes,
 participant context, evidence manifest, coverage, provider/model/prompt version,
-status, usage and validated findings:
+status, usage and validated findings. The Observer's projection of it,
+`observer/study-analysis.json`, also carries `spend`: what every analysis
+request of the run cost, as [study costs](study-costs.md#one-runs-cost)
+describes:
 
 ```text
 .humanish/runs/<run>/

package/docs/contracts/study-costs.md

@@ -26,8 +26,23 @@ said `lab` and `labs`. Its fields keep their meanings: `totals.estimatedSpendUsd
 `days[].estimatedSpendUsd`, each study's `medianCostUsd`,
 `costSamples` and `unpricedRuns` describe participant/desktop run estimates.
 They do not suddenly include a separate analysis request. The bundle's
-`cost.estimatedTotalUsd` and the cached run-index estimate also remain unchanged.
-Observer and terminal run summaries label this narrower scope.
+`cost.estimatedTotalUsd`, `status.json`'s `outcome.estimatedCostUsd` and the run
+index's `estimatedCostUsd` stay participants and desktops only.
+
+## One run's cost
+
+A run's analysis spend has one reader, `readAnalysisAccounting` in
+`src/run/costs.ts`. Stats calls it for `costs.analysisEstimatedUsd`, and the
+surfaces that show one run's cost read it too: the run index's `analysisCost`,
+and the `spend` field of the Observer's companion `observer/study-analysis.json`.
+It counts every distinct attempt the way stats does, so a run analyzed twice
+shows two analyses. `src/run/run-cost.ts` adds that spend to the run's
+participants-and-desktops figure, and the Observer's cost line, the Observer
+library row's `costLabel` and the terminal UI all format the result through it.
+The total is a lower bound, shown as `est. ~$X plus unpriced usage`, while any
+part has an unpriced or incomplete figure. A Codex-account analysis has no
+dollar price and reads "dollar cost unknown". An analysis that sent no request
+adds nothing.
 
 The new `costs` object appears on totals, each study and each day. `costsByRun`
 contains the same accounting per selected run with stable warning codes.

package/examples/README.md

@@ -5,7 +5,7 @@ one from `node_modules/humanish/examples/`. Both need Node.js 22.19 or newer, an
 key. `pnpm api:proof`, part of `pnpm release:check`, runs both against the packed package.
 
 - [participant/](participant/README.md): bring your own participant. A synthetic loopback app is
-  driven through its state contract by a `CuaExecutor` and a deterministic provider, with no
+  driven through its state contract by a `ComputerUseExecutor` and a deterministic provider, with no
   browser, screenshots or E2B.
 - [scorer/](scorer/README.md): score a run with your own rubric. One scorer module is attached to a
   dry run from a library caller and from the CLI, with no desktop or running app.