humanish 0.107.0 → 0.109.0

package/docs/contracts/study-analysis.md

@@ -57,7 +57,7 @@ humanish analyze --run latest --provider codex --dry-run --json
 humanish analyze --run latest --provider codex --json
 ```
 
-This branch is qualified on Linux x64 and Apple Silicon macOS with the Codex CLI releases listed for each host in `src/actors/codex/qualified-versions.ts`, a file-backed
+This branch runs on Linux x64 and Apple Silicon macOS with any stable Codex CLI release `src/actors/codex/codex-admission.ts` admits (0.154.0 on, except refused releases), a file-backed
 ChatGPT account login, and `gpt-6-astra` with low reasoning effort. The participant conversation
 is never reused. Selected text and screenshots still go to remote inference;
 this is account authentication, not local inference. No API-key, alternate model
@@ -76,7 +76,7 @@ remain null. Interrupted token observations remain explicitly incomplete.
 
 The dry-run validates only local evidence and configuration. It does not check
 the CLI, login, model access or quota and does not start a provider request.
-`doctor --lab <lab>` checks the selected analyst setup without a model call.
+`doctor --study <study>` checks the selected analyst setup without a model call.
 Failures leave the recording available; inspect `analyze show` and the attempt's
 accounting before an explicit `analyze --provider codex --rerun`.
 
@@ -194,7 +194,7 @@ validation exception keeps nothing.
 
 The directory sits outside every run directory, and export, verify and the
 Observer read only run directories. `humanish analyze` returns the file's path as
-`rejectedOutputPath` and prints it, and so does a lab run's automatic analysis.
+`rejectedOutputPath` and prints it, and so does a run's automatic analysis.
 Each write removes all but the newest 20 records across runs. It removes a
 record only while its directory is still the listed one, so a directory
 replaced by a symlink after listing is left alone. The record's
@@ -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

@@ -7,28 +7,44 @@ All amounts are estimates from retained rate-table accounting, not provider bill
 
 ```bash
 humanish stats
-humanish stats --lab sample-study --since 2026-09-01 --json
+humanish stats --study sample-study --since 2026-09-01 --json
 ```
 
-The filters select runs by lab and run start date. All later analysis reruns
+The filters select runs by study and run start date. All later analysis reruns
 belong to their source run for filtering and daily grouping. This is study-cost
 attribution, not a calendar of provider charges.
 
 With no filters, a directory whose source metadata is unreadable can still
-contribute valid analysis receipts under `(no lab)` and `(undated)`. Lab/date
+contribute valid analysis receipts under `(no study)` and `(undated)`. Study/date
 filters exclude such unattributable directories; they remain named in
-`unreadable`. The command does not guess their date or lab from an analysis.
+`unreadable`. The command does not guess their date or study from an analysis.
 
 ## Additive JSON contract
 
-The envelope remains `humanish.stats.v1`. Existing fields keep their meanings:
-`totals.estimatedSpendUsd`, `days[].estimatedSpendUsd`, lab `medianCostUsd`,
+The envelope is `humanish.stats.v2`, which says `study` and `studies` where `humanish.stats.v1`
+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.
 
-The new `costs` object appears on totals, each lab and each day. `costsByRun`
+## 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.
 
 | Field                           | Meaning                                                                 |
@@ -57,6 +73,9 @@ its report was published, its findings are current, or the original recording
 later changed. The receipt and report with the same run/analysis ID count once;
 new IDs from explicit reruns count separately. Reusing a prior result adds no
 attempt or expense. Conflicting accounting for the same ID stays unresolved.
+A dry run with no recorded cost counts as a known $0, because it makes no model
+request and creates no desktop. A dry run that records an unknown figure stays
+unknown.
 
 Older reports without receipts contribute their strictly validated accounting
 metadata with a legacy warning. Provider requests that left no durable record

package/docs/decisions/0001-run-bundle-is-the-source-of-truth.md

@@ -4,7 +4,7 @@ Accepted.
 
 ## Context
 
-Several surfaces read a finished or running study: the Observer, `humanish tui`, `serve`,
+Several surfaces read a finished or running study: the Observer, `humanish tui`, `observe --all`,
 `export`, feedback drafts and study analysis. Each of them wants a smaller, faster view than the
 full bundle, and a view that can drift from the evidence would let a surface show a result the
 evidence does not support.

package/docs/decisions/0002-observer-is-one-self-contained-file.md

@@ -12,7 +12,7 @@ exactly those cases.
 
 The `observer/` workspace builds with Vite into a single HTML file with fonts inlined and no
 network references. The root build copies it to `dist/observer-app.html`. `renderObserverHtml`
-is the one path every surface (observe, watch, serve, labs) uses; it injects the run's
+is the one path every surface (observe, observe --all, watch, studies) uses; it injects the run's
 `humanish.observer-data.v1` snapshot into that file. There is no second renderer and no feature
 flag; rolling back means pinning an older package version.
 
@@ -21,7 +21,7 @@ flag; rolling back means pinning an older package version.
 - An Observer page opens from disk, and an exported bundle carries its own viewer.
 - Every dependency the Observer adds ships inside each rendered page, so page weight is a cost
   reviewers check.
-- Live views (`watch`, `serve`) use the same file and poll for new snapshots.
+- Live views (`watch`, `observe --all`) use the same file and poll for new snapshots.
 
 ## Enforced by
 

package/docs/decisions/0003-contained-paths-and-cleanup-authority.md

@@ -1,6 +1,6 @@
 # 0003: Managed paths bind to physical identities; cleanup uses create-time receipts
 
-Accepted in 0.15.1 (#280), extended in 0.36.0 (`humanish reclaim`).
+Accepted in 0.15.1, extended in 0.36.0 (`humanish reclaim`).
 
 ## Context
 
@@ -11,7 +11,7 @@ Separately, an account-wide provider operation once destroyed unrelated infrastr
 
 ## Decision
 
-- Managed run, Observer, feedback, lab, actor-output, git-metadata and source-archive paths bind
+- Managed run, Observer, feedback, study, actor-output, git-metadata and source-archive paths bind
   to validated physical filesystem identities. Traversal-shaped ids, unsafe links, special files
   and root retargeting are rejected before any write.
 - Provider ids in `run.json` are evidence. Nothing mutates a provider resource because of them.
@@ -32,4 +32,4 @@ Separately, an account-wide provider operation once destroyed unrelated infrastr
 - `src/run/paths.ts` and `src/run/contained-output.ts`, with `tests/run/path-containment.test.ts`.
 - `src/run/git-workspace.ts`, with `tests/run/git-state.test.ts`.
 - `src/run/reclaim.ts`, with `tests/run/reclaim.test.ts`.
-- Invariant 7 in [invariants and defaults](../principles/invariants-and-defaults.md).
+- Reclamation by exact created id, in [invariants and defaults](../principles/invariants-and-defaults.md).

package/docs/principles/actor-fidelity.md

@@ -1,7 +1,7 @@
 # Actor Fidelity: whose behavior is this evidence about?
 
-Status: research digest + design position. Sources are public papers and open-source
-harnesses; every claim below carries its citation so a reader can check it.
+This page is a research digest and a design position. Its sources are public papers and
+open-source harnesses, and each claim carries its citation so a reader can check it.
 
 ## The question
 
@@ -21,7 +21,7 @@ Whether that is a defect depends entirely on a question the harness never asked:
   finding about how legible the surface is to its actual users.
 
 The proof roadmap already anticipated this: its strongest evidence class,
-`user-census`, is defined as "the users of the product ARE agents, and the lab runs
+`user-census`, is defined as "the users of the product are agents, and the study runs
 real production harnesses." This page is the layer that makes the distinction
 operable.
 
@@ -104,7 +104,7 @@ a green run proves nothing.
 
 **Declare, record, and let the adopter judge.**
 
-1. **Declared population is a property of a persona, not of a lab.** One study program
+1. **Declared population is a property of a persona, not of a study.** One study program
    can legitimately run agents and people against the same surface; the comparison
    between them is itself a finding. Prior art runs both populations
    through one instrument and reports the difference

package/docs/principles/engineering.md

@@ -1,6 +1,6 @@
 # Engineering principles
 
-These are the judgment calls behind the rules in [AGENTS.md](../../AGENTS.md). Read them
+These are the judgment calls behind the rules in [AGENTS.md](https://github.com/danielgwilson/humanish/blob/main/AGENTS.md). Read them
 before adding a service, mode, dependency or new boundary.
 
 ## Engineering Judgment
@@ -48,7 +48,7 @@ low maintenance cost, alongside correctness, privacy and security.
 
 ## Working And Resuming
 
-- Read the [ramp](../ramp/README.md), current task and relevant component
+- Read the [ramp](https://github.com/danielgwilson/humanish/blob/main/docs/ramp/README.md), current task and relevant component
   instructions. Read detailed contracts for the boundary being changed, not every
   historical roadmap. Consult the invariants for security/evidence changes and the
   release procedure before publishing.
@@ -58,7 +58,7 @@ low maintenance cost, alongside correctness, privacy and security.
   treat an old plan as authorization to resume paused or rejected work.
 - When granted autonomous shipping authority, push, open the PR, address reviews
   and required checks, merge when green, fast-forward main and clean up the task
-  worktree/branch. Follow [release gates](../release/open-source-readiness.md)
+  worktree/branch. Follow [the release procedure](https://github.com/danielgwilson/humanish/blob/main/docs/release/publish.md)
   when a release is authorized; do not add new approval steps on your own.
 - Stay on `0.x` until the maintainer explicitly chooses 1.0. The next minor
   after `0.99.0` is `0.100.0`; routine shipping authority does not authorize 1.0.

package/docs/principles/invariants-and-defaults.md

@@ -1,6 +1,6 @@
 # Invariants and Defaults
 
-humanish's safety and honesty rules come in exactly two strengths. Confusing them causes
+humanish's safety and evidence rules come in exactly two strengths. Confusing them causes
 two failures: a route-scoped default gets written down as if it held on every route, then the
 next legitimate use case looks like a violation and either gets blocked (capability loss) or
 waved through ad hoc (safety loss). This page draws the line between the two.
@@ -11,7 +11,7 @@ True on every route, enforced in code, never overridable by config. A feature th
 satisfy these does not ship; a third-party extension that cannot satisfy these does not
 certify (see the conformance suite).
 
-1. **Secret values never reach PUBLISHED evidence.** No key, token, credential value, or
+1. **Secret values never reach published evidence.** No key, token, credential value, or
    session-secret may appear in any artifact that leaves the operator's machine: a committed
    file, a shared bundle, a feedback issue. Names of provisioned environment variables are
    evidence; their values never are. Harness-level errors pass through redaction before
@@ -27,8 +27,8 @@ certify (see the conformance suite).
    separately verified copy while preserving readable local evidence. (See "the
    capture-vs-publish rule" below: blurring frames at _capture_ was a default mistaken for
    this invariant.)
-   - Scope note: the literal scrub of KNOWN provisioned values runs on harness log-tails,
-     errors, AND model-authored narration (reasoning/message) before it persists; secret-SHAPED
+   - Scope note: the literal scrub of known provisioned values runs on harness log-tails,
+     errors, and model-authored narration (reasoning/message) before it persists; secret-shaped
      values are caught everywhere by pattern redaction. The text artifacts are local
      (gitignored) regardless.
 2. **Actors only drive harness-minted URLs.** A model with input control (mouse, keyboard,
@@ -47,35 +47,35 @@ certify (see the conformance suite).
 5. **Provenance is recorded or its absence is declared.** Every bundle states what the
    subject was (commit, image, fixture, or an explicit "unpinned" marker). Evidence that
    cannot say what it measured cannot support a decision.
-   - External-public plane class (#164 phase 2, 0.20.0): when a real operator-owned public
-     deployment is used DIRECTLY as a concurrent shared-world plane (`source: app-url` +
-     `topology: shared-world` + `allowPublicTargets` + `concurrency > 1`), provenance is the
-     marker `external-public`; humanish neither provisioned nor seeded it, so it is NOT `seeded`
-     and NOT `unpinned`. Attribution stays `shared-world` (N participants, ONE plane), but every strength
-     claim degrades HONESTLY and is asserted-ABSENT, never silently dropped: a synthetic attestation
-     is FORBIDDEN (you cannot claim synthetic on a real site; the honest analog is the
+   - External-public plane class: when a real operator-owned public
+     deployment is used directly as a concurrent shared-world plane (`source: app-url` +
+     `route: shared-world` + `allowPublicTargets` + `concurrency > 1`), provenance is the
+     marker `external-public`; humanish neither provisioned nor seeded it, so it is not `seeded`
+     and not `unpinned`. Attribution stays `shared-world` (N participants, one plane), but every strength
+     claim is downgraded and asserted-absent, never silently dropped: a synthetic attestation
+     is forbidden (you cannot claim synthetic on a real site; its real-site counterpart is the
      operator-ownership attestation `subject.publicTarget`, author-trust and unverifiable); plane
      control is "operator-attested, observed-only" (`plane.publicOriginDigest`) not
-     "harness-controlled" (`plane.hostDigest`); there is NO authoritative shared-state proof
+     "harness-controlled" (`plane.hostDigest`); there is no authoritative shared-state proof
      (`stateSeries` omitted); and concurrency is proven by temporal co-occupancy + observed lobby
-     convergence only. Verify FAILS CLOSED if any honest-downgrade limit is missing or if a
+     convergence only. Verify fails closed if any external-public disclosure limit is missing or if a
      getHost-only claim (`exposure: synthetic`, `hostDigest`, a `seeded`/`synthetic` limit) appears
      on this class. The getHost synthetic gate is deliberately unreachable here. It exists because
-     getHost is internet-reachable AND harness-owned; a public site the harness neither provisioned
+     getHost is internet-reachable and harness-owned; a public site the harness neither provisioned
      nor exposed is neither.
 6. **Claims match mechanism.** A config field that is parsed but not consumed warns; a
    document that overstates behavior is a defect; an evidence artifact never claims a
    stronger evidence class than its actor and scenario can support.
 7. **Reclamation is by exact created id, never account-wide enumeration.** A route that
    creates a provider resource (an E2B sandbox, for example) tracks the exact id it created and
-   reclaims and PROVES cleanup against that id alone (a returned found-and-killed boolean, a
+   reclaims and proves cleanup against that id alone (a returned found-and-killed boolean, a
    getInfo-by-id NotFound check). No route ever calls a provider's list-everything endpoint to
    discover or verify its own cleanup, because that endpoint enumerates the whole account/team,
    including resources humanish did not create. This is what makes a single shared operator key
    safe: humanish only ever reaches a resource it created, never anything else the key's owner
    is running.
    The one narrow exception is an explicit, maintainer-run orphan sweep (never a default, never
-   reachable by a normal lab run) that is itself opt-in gated (an explicit flag or env var) and
+   reachable by a normal run) that is itself opt-in gated (an explicit flag or env var) and
    documented as such at its call site.
 
 ## Defaults
@@ -84,20 +84,20 @@ Right most of the time, overridable with declared friction (an explicit config f
 env gate, a warning in the run output). Overriding a default is a supported use case;
 silently drifting from one is not.
 
-| Default                                     | Why it is the default                                                                                                                                                                                                                                               | Legitimate override                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Dry-run                                     | Spend safety (invariant 3 sets the floor; dry-run keeps the floor far away)                                                                                                                                                                                         | `scenario.mode: live`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| Post-run analysis on supported live studies | Findings accompany the recording; a separate $3 admission estimate limit is visible before execution                                                                                                                                                                | `review.analysis: false` disables it; an explicit mapping sets another analysis budget. Dry-run and unsupported routes never dispatch; missing default credentials produce a recorded skip                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| Separate worlds (`per-lane-worlds`)         | Isolation, attribution, reproducibility                                                                                                                                                                                                                             | `subject.topology: shared-world`: N participants against ONE mutable plane for scenarios that ARE about interaction between roles (#164). Every participant runs at once: `execution.concurrency` must be 2 or more, and an omitted value fills to the participant count (#350). The plane is one getHost-exposed subject sandbox with synthetic seeded data, or an operator-owned public deployment (external-public), driven by N actor sandboxes. The bundle declares the weaker `attributionClass: shared-world` and a verify-enforced `attributionLimits` ceiling (`best-effort-causal-attribution` and the rest of the concurrent set). Sequential turns at `execution.concurrency: 1` were removed in 0.106.0. |
-| External key placement                      | Smallest blast radius: when the keyed process (e.g. a computer-use provider loop) runs outside the sandbox, its key never enters                                                                                                                                    | In-sandbox placement when the keyed process runs inside (an agent harness under test); declared per actor type, with a spend budget                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| Loopback entry URLs                         | Public-safety: never drive third-party sites unbidden                                                                                                                                                                                                               | `policies.allowPublicTargets` for an owner-declared deployment/preview (a Vercel preview of your own app). Multi-participant public/preview fan-out needs explicit `actors[0].lanes[].target` for every participant, so the adapter-owned topology is declared rather than inferred. Provisioned clone subjects always serve in-sandbox on loopback                                                                                                                                                                                                                                                                                                                                                                   |
-| Full-fidelity screenshots, local            | The common case is watching a run of your OWN app locally; blur destroys the deliverable. Raw frames live in gitignored `.humanish/` (this repo's CI adds a binary-asset commit scan; downstream projects rely on the scaffolded `.gitignore` and their own review) | `policies.redactScreenshots: true` blurs at capture; `export --format bundle --redact-screenshots` produces a separate verified copy of a completed run                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| Synthetic, seeded state                     | Pinned provenance; no real user data in evidence paths                                                                                                                                                                                                              | Declared external state, recorded as UNPINNED in provenance                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| Single participant                          | Cost + evidence simplicity                                                                                                                                                                                                                                          | Declared fan-out where the backend supports it: `actors[0].count: N` (homogeneous), explicit `actors[0].lanes[]` (differentiated persona/device/instruction), or compact `actors[0].roster[]` groups that normalize into `lanes[]` entries on the computer-use E2B route (separate worlds, cap 16; `execution.concurrency` bounds concurrent paid participants)                                                                                                                                                                                                                                                                                                                                                       |
-| Stock `desktop` template                    | The stock E2B desktop image is right for most subjects; absent `execution.desktop.template` keeps `Sandbox.create(opts)` byte-stable                                                                                                                                | `execution.desktop.template` names a custom E2B desktop image (any name/id, no allowlist) for a subject needing baked-in runtimes the stock image lacks (e.g. node/bun/a local Postgres); it is threaded to `Sandbox.create(template, opts)` on every desktop-creating route and recorded in the bundle as `desktopTemplate` (public-safe)                                                                                                                                                                                                                                                                                                                                                                            |
-| Desktop default URL opener                  | Preserve the route/image's historical browser/default opener behavior when unset                                                                                                                                                                                    | `execution.desktop.browser` set to `chrome`, `chromium` or `firefox` makes the hosted CUA/shared-world browser choice explicit, fail-closed, and recorded as `desktopBrowser` in the run bundle                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| Loopback-only observer serving              | Run bundles are local by default (public-safety plank 3); the serve/watch surfaces bind `127.0.0.1` unconditionally, and exposing them is publishing-adjacent, so exposure is fail-closed and carries declared friction                                             | `humanish serve --expose` behind tunnel-edge auth (ngrok `--oauth google` with `--allow-email`/`--allow-domain` allow rules, or an operator `--public-url` you secure), or `--expose --safe` (open, gated on verify-`share_ready` runs only). `watch --expose` streams a live run behind edge auth (a live run is never `share_ready`, so `--safe` alone is refused). humanish carries no in-process auth; both print computed warnings naming exactly what became reachable                                                                                                                                                                                                                                          |
-| Generous wall-clock safety cap              | `execution.timeoutMs` bounds runaway spend, not a goal; ~30 min is reasonable for open-ended "watch it play"                                                                                                                                                        | A session that reaches the cap AFTER productive activity is recorded as `budget_reached` (status `passed`, a NON-FAILURE completion, exit `0`), distinct from a zero-progress `timed_out` (a failure, exit `2`). Goal-directed labs set a tight `timeoutMs` and read `completionReason` to confirm the goal, not the cap                                                                                                                                                                                                                                                                                                                                                                                              |
+| Default                                     | Why it is the default                                                                                                                                                                                                                                               | Legitimate override                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Dry-run                                     | Spend safety (the live-spend rule sets the floor; dry-run keeps it far away)                                                                                                                                                                                        | `mode: live`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| Post-run analysis on supported live studies | Findings accompany the recording; a separate $3 admission estimate limit is visible before execution                                                                                                                                                                | `review.analysis: false` disables it; an explicit mapping sets another analysis budget. Dry-run and unsupported routes never dispatch; missing default credentials produce a recorded skip                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| Separate worlds (`per-lane-worlds`)         | Isolation, attribution, reproducibility                                                                                                                                                                                                                             | `route: shared-world`: N participants against one mutable plane for scenarios that are about interaction between participants. Every participant runs at once: `execution.concurrency` must be two or more, and an omitted value fills to the number of participants. The plane is one getHost-exposed subject sandbox with synthetic seeded data, or an operator-owned public deployment (external-public), driven by N actor sandboxes. The bundle declares the weaker `attributionClass: shared-world` and a verify-enforced `attributionLimits` ceiling (`best-effort-causal-attribution` and the rest of the concurrent set). Sequential turns at `execution.concurrency: 1` were removed in 0.106.0. |
+| External key placement                      | Smallest blast radius: when the keyed process (e.g. a computer-use provider loop) runs outside the sandbox, its key never enters                                                                                                                                    | In-sandbox placement when the keyed process runs inside (an agent harness under test); declared per actor type, with a spend budget                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| Loopback entry URLs                         | Public-safety: never drive third-party sites unbidden                                                                                                                                                                                                               | `policies.allowPublicTargets` for an owner-declared deployment/preview (a Vercel preview of your own app). Multi-participant public/preview fan-out needs explicit `participants[].target` for every participant, so the adapter-owned topology is declared rather than inferred. Provisioned clone subjects always serve in-sandbox on loopback                                                                                                                                                                                                                                                                                                                                                           |
+| Full-fidelity screenshots, local            | The common case is watching a run of your own app locally; blur destroys the deliverable. Raw frames live in gitignored `.humanish/` (this repo's CI adds a binary-asset commit scan; downstream projects rely on the scaffolded `.gitignore` and their own review) | `policies.redactScreenshots: true` blurs at capture; `export --format bundle --redact-screenshots` produces a separate verified copy of a completed run                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| Synthetic, seeded state                     | Pinned provenance; no real user data in evidence paths                                                                                                                                                                                                              | Declared external state, recorded as unpinned in provenance                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| Single participant                          | Cost + evidence simplicity                                                                                                                                                                                                                                          | Declared fan-out where the route supports it: `participants: N` (homogeneous), an explicit `participants` list (differentiated persona/device/instruction), or list entries with a `count` that expand into one entry per participant on the computer-use E2B route (separate worlds, cap 16; `execution.concurrency` bounds concurrent paid participants)                                                                                                                                                                                                                                                                                                                                                 |
+| Stock `desktop` template                    | The stock E2B desktop image is right for most subjects; absent `execution.desktop.template` keeps `Sandbox.create(opts)` byte-stable                                                                                                                                | `execution.desktop.template` names a custom E2B desktop image (any name/id, no allowlist) for a subject needing baked-in runtimes the stock image lacks (e.g. node/bun/a local Postgres); it is threaded to `Sandbox.create(template, opts)` on every desktop-creating route and recorded in the bundle as `desktopTemplate` (public-safe)                                                                                                                                                                                                                                                                                                                                                                 |
+| Desktop default URL opener                  | Preserve the route/image's historical browser/default opener behavior when unset                                                                                                                                                                                    | `execution.desktop.browser` set to `chrome`, `chromium` or `firefox` makes the hosted CUA/shared-world browser choice explicit, fail-closed, and recorded as `desktopBrowser` in the run bundle                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| Loopback-only observer serving              | Run bundles are local by default (public-safety plank 3); the serve/watch surfaces bind `127.0.0.1` unconditionally, and exposing them is publishing-adjacent, so exposure is fail-closed and carries declared friction                                             | `humanish observe --all --expose` behind tunnel-edge auth (ngrok `--oauth google` with `--allow-email`/`--allow-domain` allow rules, or an operator `--public-url` you secure), or `--expose --safe` (open, gated on verify-`share_ready` runs only). `watch --expose` streams a live run behind edge auth (a live run is never `share_ready`, so `--safe` alone is refused). humanish carries no in-process auth; both print computed warnings naming exactly what became reachable                                                                                                                                                                                                                       |
+| Generous wall-clock safety cap              | `execution.timeoutMs` bounds runaway spend, not a goal; ~30 min is reasonable for open-ended "watch it play"                                                                                                                                                        | A session that reaches the cap after productive activity is recorded as `budget_reached` (status `passed`, a non-failure completion, exit `0`), distinct from a zero-progress `timed_out` (a failure, exit `2`). Goal-directed studies set a tight `timeoutMs` and read `completionReason` to confirm the goal, not the cap                                                                                                                                                                                                                                                                                                                                                                                |
 
 ## The placement rule (worked example)
 
@@ -105,7 +105,7 @@ silently drifting from one is not.
 external-placement _default_ as instantiated on the computer-use route, where the
 model's brain runs outside the sandbox. The underlying invariant-level principle is:
 
-> **Keys live where the keyed process runs — and nowhere else. Names go in evidence; values
+> **Keys live where the keyed process runs, and nowhere else. Names go in evidence; values
 > never. Blast radius is bounded by key scoping and budgets, not by hoping.**
 
 Consequences:
@@ -113,7 +113,7 @@ Consequences:
 - A computer-use provider loop runs outside → forwarding env into its sandbox is rejected.
 - A subject app (a real web app under test) runs inside → its declared env names are
   provisioned in, values never persisted.
-- An agent harness under test runs inside with real keys → that is the point of the lab;
+- An agent harness under test runs inside with real keys → that is the point of the study;
   the keys are presumed exfiltratable by the agent (key scoping and spend budgets protect
   them; sandboxing does not), and the participant carries a budget/ledger.
 
@@ -121,27 +121,27 @@ Placement is registry metadata per actor type, and the engine enforces it.
 
 Two corollaries:
 
-- **Serve commands are author-trusted.** A lab's `serve` steps execute inside the disposable
+- **Serve commands are author-trusted.** A study's `serve` steps execute inside the disposable
   sandbox with the declared subject env present, in the same trust class as the repo's own
-  package.json scripts. Run only lab configs you trust; declare only the env names the
+  package.json scripts. Run only study configs you trust; declare only the env names the
   subject genuinely needs.
 - **Pattern redaction is not enough for provisioned values.** A provisioned value (a database
   password, an arbitrary token) has no detectable "shape," so the harness scrubs every value
-  it provisioned by LITERAL match before any log tail or error can persist. Pattern-based
+  it provisioned by literal match before any log tail or error can persist. Pattern-based
   redaction is the second pass.
 
 ## The capture-vs-publish rule (worked example)
 
 "Every screenshot is blurred to a 128px thumbnail" was once enforced at _capture_: the
 loop never retained a usable frame. That destroyed the core deliverable for the common case
-(a developer watching a run of their OWN app locally) to defend against a leak that can only
+(a developer watching a run of their own app locally) to defend against a leak that can only
 happen at _publish_. The proof it was a default, not an invariant: the same product already
 shipped raw full-resolution frames on the meta route (since removed) with only a "do not publish" warning +
 the `.humanish/` gitignore + the binary-asset scan. Two routes, opposite policies, identical
 threat. The corrected principle:
 
-> **A default's enforcement point belongs at the PUBLISH/VERIFY boundary, never at
-> CAPTURE/RUNTIME — unless capture-time is the only physically possible point.**
+> **A default's enforcement point belongs at the publish/verify boundary, never at
+> capture/runtime, unless capture-time is the only physically possible point.**
 
 Consequences:
 

package/docs/principles/self-driving-harness.md

@@ -1,9 +1,5 @@
 # Self-Driving Harness Principles
 
-Date: 2026-06-01
-
-Status: initial principles for `humanish`.
-
 ## Thesis
 
 `humanish` should be a closed-loop product simulation system. Launching agents
@@ -27,7 +23,7 @@ context.
 
 ## Public Boundary
 
-This repo must be designed as if it will become public.
+This repository is public.
 
 No PII, PHI, secrets, keys, tokens, raw private transcripts, real patient data,
 real customer data, or private product artifacts belong here. Examples,

package/docs/principles/three-roles.md

@@ -14,7 +14,7 @@ They care about rigor and control, and they need output they can reason over and
 adjust.
 
 **The stakeholder** watches. In a real study they sit behind the glass in the
-viewing room; here they open Observer, `watch`, or `serve`. They want none of the
+viewing room; here they open Observer, `watch`, or `observe --all`. They want none of the
 protocol. They want to know what happened, where people got stuck, how bad it is,
 and whether anyone succeeded: moments, severity, and the denominator.
 

package/docs/product/automatic-analysis.md

@@ -32,7 +32,7 @@ includes reasoning as well as the report; exhausting it does not produce a usabl
 report and never starts an automatic retry. Analysis
 sends selected retained text and captures to OpenAI using `OPENAI_API_KEY`.
 Analysis runs in the humanish runner using its credentials. This setting adds no
-credential channel to the target application; each participant backend retains
+credential channel to the target application; each participant's route keeps
 its existing authentication boundary. Review the separate analysis budget before running a manifest live; an actor's
 zero-dollar cap does not cap post-run analysis. The bundled first-contact
 zero-spend product fixture explicitly disables analysis.
@@ -47,19 +47,19 @@ review:
     timeoutMs: 600000
 ```
 
-This requires Linux x64, a Codex CLI release qualified for it (`src/actors/codex/qualified-versions.ts`), and a file-backed ChatGPT account login; the analyst
+This requires Linux x64, a stable Codex CLI release from 0.154.0 on (`src/actors/codex/codex-admission.ts`), and a file-backed ChatGPT account login; the analyst
 uses low reasoning effort and remote inference. Dollar cost and a provider
 enforced output-token ceiling are unknown, so omit `maxCostUsd` and
 `maxOutputTokens`. Numeric values are rejected before participant resources are
 allocated. There is no API fallback. Missing or unsupported account setup leaves
 an explicit failed analysis state and the original recording intact. Use
-`humanish doctor --lab <lab>` for setup checks; account allowance and model access
+`humanish doctor --study <study>` for setup checks; account allowance and model access
 remain untested until a request. An omitted provider still means OpenAI, including
 hosted studies whose participant uses a local Codex or Claude login. This setting
 does not enable managed local desktops.
 
-The same configuration works through `humanish run <lab>`, `lab run <lab>`,
-`watch <lab>`, and TUI live starts. Direct library calls to the five recording
+The same configuration works through `humanish run <study>`,
+`watch <study>`, and TUI live starts. Direct library calls to the five recording
 producers honor it too. Supported routes are computer-use, scripted-browser,
 terminal-product and shared-world. The synthetic route
 never enables analysis by default and rejects an explicit analysis mapping
@@ -75,7 +75,7 @@ with no retained participant activity. A desktop startup failure does not start
 an analysis request. The original failure remains visible.
 
 CLI live starts disclose the selected analyst and its separate admission estimate limit or unknown account dollars before execution.
-`humanish lab preflight <lab> --json` and the TUI lab screen also expose the
+`humanish study check <study> --json` and the TUI study screen also expose the
 resolved budget without dispatching analysis. Library callers can inspect
 `resolveAutomaticAnalysis` or `automaticAnalysisBudget` before running.
 
@@ -96,7 +96,7 @@ action writes a cancellation request for that recording; it does not signal the
 finished participant process. Cancelling cannot undo provider work already
 accepted. Known usage is retained; missing usage remains unknown.
 
-The CLI's JSON keeps `runOk` for the original backend result, `automaticAnalysis`
+The CLI's JSON keeps `runOk` for the route's own result, `automaticAnalysis`
 for post-run analysis, and `ok` for the overall request. Failed, cancelled or
 unknown analysis produces exit code 2 without discarding the recording. A missing
 `OPENAI_API_KEY` skips default analysis and preserves a successful run exit;

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.

package/examples/participant/README.md

@@ -1,8 +1,8 @@
 # Bring your own participant: a local app through its state contract
 
 This complete library example starts a synthetic loopback HTTP app, reads its
-state with a `CuaExecutor`, sends a greeting through its action endpoint, and
-verifies the resulting humanish run. It uses a deterministic `CuaProvider` with
+state with a `ComputerUseExecutor`, sends a greeting through its action endpoint, and
+verifies the resulting humanish run. It uses a deterministic `ComputerUseProvider` with
 no model calls, API keys, browser, screenshots or E2B resources. It demonstrates
 the integration; it does not test persona behavior or the quality of an app's UI.
 
@@ -56,9 +56,9 @@ provider. Your replacement owns its model credentials and costs. The
 `openai-computer-use` actor id selects the registered CUA route; `createProvider`
 chooses the actual provider, so this example never invokes OpenAI.
 
-The runner shows both required discriminant checks: `parseLabConfig` receives
-an object containing `schema: LAB_CONFIG_SCHEMA` and is narrowed on `.ok`;
-`runLab` is narrowed on `route === "computer-use"` before inspecting its result.
+The runner shows both required discriminant checks: `parseStudy` receives
+an object containing `schema: STUDY_SCHEMA` and is narrowed on `.ok`;
+`runStudy` is narrowed on `route === "computer-use"` before inspecting its result.
 Supplying `inProcess.executor` and `createProvider` selects the library-assisted
 route. It is not a config-only CLI actor or an out-of-tree actor registration API.
 

package/examples/participant/run.mjs

@@ -1,8 +1,8 @@
 // @ts-check
-import { LAB_CONFIG_SCHEMA, parseLabConfig, runLab, stableProgressKey, verifyRun } from "humanish";
+import { STUDY_SCHEMA, parseStudy, runStudy, stableProgressKey, verifyRun } from "humanish";
 import { startLocalApp } from "./app.mjs";
 
-/** @param {string} appUrl @returns {import("humanish").CuaExecutor} */
+/** @param {string} appUrl @returns {import("humanish").ComputerUseExecutor} */
 function createAppContractExecutor(appUrl) {
   return {
     async observe() {
@@ -29,7 +29,7 @@ function createAppContractExecutor(appUrl) {
 }
 
 // A deterministic rule, not an AI participant: no model SDK, requests or credentials.
-/** @type {import("humanish").CuaProvider} */
+/** @type {import("humanish").ComputerUseProvider} */
 const provider = {
   id: "local-app-deterministic-example",
   version: "1.0.0",
@@ -59,20 +59,21 @@ const provider = {
 
 const app = await startLocalApp();
 try {
-  // parseLabConfig accepts a decoded OBJECT, not a YAML string.
-  const parsed = parseLabConfig({
-    schema: LAB_CONFIG_SCHEMA,
+  // parseStudy accepts a decoded object, not a YAML string.
+  const parsed = parseStudy({
+    schema: STUDY_SCHEMA,
     id: "participant-example",
     title: "Deterministic local-app integration example",
+    route: "computer-use",
+    mode: "live",
     subject: { source: "local-app", appUrl: app.appUrl },
-    // This registry id selects the CUA loop. createProvider supplies the actual provider.
-    actors: [{ type: "openai-computer-use", persona: "pixel-pat", mission: "Greet the app." }],
-    scenario: { mode: "live" },
+    // This registry id selects the computer-use loop. createProvider supplies the actual provider.
+    actor: { type: "openai-computer-use", persona: "pixel-pat", mission: "Greet the app." },
     review: { analysis: false }, // Keep this deterministic example free of provider requests.
     execution: { timeoutMs: 15_000 },
   });
   if (!parsed.ok) throw new Error(parsed.error.message);
-  const outcome = await runLab(parsed.config, {
+  const outcome = await runStudy(parsed.config, {
     cwd: process.cwd(),
     dryRun: false,
     // An in-process executor returns app state, not a screenshot, so it needs a provider that

package/examples/scorer/README.md

@@ -5,10 +5,10 @@ evidence of a computer-use, shared-world or terminal run and stores the result a
 `bundle.adapterScore`, under your namespace. A module may also export `deriveFeedback` and
 `deriveArtifacts`; the `AdapterScorerModule` type describes all three.
 
-[run.mjs](run.mjs) attaches the same module to a dry run of one computer-use lab in two ways:
+[run.mjs](run.mjs) attaches the same module to a dry run of one computer-use study in two ways:
 
-- from a library caller, as `runLab(config, { scorer: { score } })`;
-- from the CLI, as `humanish lab run lab.yaml --dry-run --scorer scorer.mjs`.
+- from a library caller, as `runStudy(config, { scorer: { score } })`;
+- from the CLI, as `humanish run study.yaml --dry-run --scorer scorer.mjs`.
 
 A dry run needs no keys, desktop or running app. Each run's bundle carries the score, and
 `verifyRun` checks it. The CLI run also records which module it loaded, as