humanish 0.104.3 → 0.106.0

package/AGENTS.md

@@ -1,102 +1,97 @@
 # AGENTS.md
 
-Build a maintainable persona simulation CLI: study an application, retain
-observable evidence, review findings, repair and rerun. Run bundles are the
-source of truth; Observer is their review surface.
-
-## Engineering Judgment
-
-Public OSS quality includes clear, idiomatic code, straightforward setup and
-low maintenance cost, alongside correctness, privacy and security.
-
-- **KISS:** use familiar patterns, existing repo code and maintained upstream
-  components. Judge total complexity: dependencies, services, configuration,
-  deployment and failure handling, not just source lines.
-- **YAGNI:** implement the requested behavior. Explicit near-term requirements
-  constrain today's design: defer their implementation, not compatibility. Avoid
-  choices that force an overhaul to deliver an already-required follow-up.
-  Speculative future uses do not justify frameworks.
-- **DRY:** share policy and behavior that must stay consistent. Similar-looking
-  code alone does not justify an abstraction; modest duplication can be clearer.
-- Deliver one working end-to-end path early, then harden it. An experiment is
-  not a release, and its qualification fixture need not become the architecture.
-- Before adding a service, protocol, mode or framework, explain the concrete
-  need and why an existing approach is insufficient. A sentence in the current
-  plan or PR is enough; routine changes need no separate design document.
-- Apply security controls at the relevant trust boundary for a credible failure
-  mode. Reuse established controls; public visibility alone does not justify
-  new runtime restrictions. Simplicity does not waive isolation or authorization.
-- Prefer removing an unnecessary mechanism to adding more documentation and
-  tests around it. Existing work is not a reason to retain a poor design.
-- If prerequisites keep expanding without an end-to-end result, reassess and
-  narrow the approach. Surface material scope or architecture changes promptly;
-  do not repeatedly ask permission for ordinary work already authorized.
-- Keep code, comments and updates concise. Explain surprising decisions and
-  tradeoffs; avoid redundant narration, invented jargon and repeated history.
-
-## Architecture
-
-- Product-specific routes, ports, scenarios and vocabulary belong in adapters.
-  Core owns shared execution, lifecycle, evidence and review behavior. Preserve
-  common interfaces across providers; avoid parallel copies of the study loop.
-- CLI results must be truthful. Reject unsupported execution before side effects;
-  preserve useful evidence and explain recoverable interruptions.
-- Documented bundle schemas and supported artifact paths are contracts.
-  Experimental receipts and internal diagnostics are not automatically APIs.
-- Tests establish observed behavior, not necessarily intended behavior. Resolve
-  code/test/doc conflicts against the current requirement and report the mismatch;
-  neither stale prose nor a passing test makes a bug correct.
+humanish runs persona studies: AI participants use a target app, CLI or agent-facing flow on
+hosted or local desktops, and every run leaves a verifiable evidence bundle. Run bundles are the
+source of truth; the Observer is their review surface.
+
+Sub-guides take precedence inside their directories: [observer/](https://github.com/danielgwilson/humanish/blob/main/observer/AGENTS.md),
+[tui/](https://github.com/danielgwilson/humanish/blob/main/tui/AGENTS.md), [site/](https://github.com/danielgwilson/humanish/blob/main/site/AGENTS.md). The reasoning behind the rules below is in
+[docs/principles/engineering.md](docs/principles/engineering.md). [CONTEXT.md](CONTEXT.md) defines
+the domain terms, and [docs/decisions/](docs/decisions/README.md) records the decisions that
+shape the code.
+
+## Commands
+
+Node >= 22.19.0, pnpm 12 (`packageManager` pins the version).
+
+```bash
+pnpm install
+pnpm humanish <command>          # run the CLI from source (tsx src/cli.ts)
+pnpm vitest run tests/<file>     # one test file
+pnpm format                      # oxfmt; run before every commit
+pnpm check                       # the full local gate (below)
+pnpm release:check               # check + API proof + public-surface scan + skill check + pack; CI runs this
+```
+
+`pnpm check` runs format:check, lint (oxlint, type-aware), knip, prose:check, vocabulary:check,
+typecheck, the vitest suite, the TUI tests, build, the startup proofs and a TUI smoke test. After
+changing a CLI option, run `pnpm docs:generate`; CI fails on a stale `site/content/docs/cli.mdx`.
+Observer changes also need `pnpm build` and the four `observer:*:proof` scripts, which CI's observer
+job runs in Chromium. `pnpm api:proof` (after `pnpm build`) installs the packed tarball in a
+temporary project, compares its export names with `tests/golden/public-api.json` and runs
+`examples/`. After an intended export change, run `pnpm api:proof --update` and review the golden
+diff.
+
+Three counts are held to caps in package.json: oxlint warnings (`lint`, `--max-warnings`), comment
+prose (`prose:check`) and the retired words lane, seat, role, sim and study in `src/` identifiers
+(`vocabulary:check`). Each checker fails when a count is above its cap or below it, so the PR that
+reduces a count lowers its cap to the new count; the failure names the flag and the value.
+
+## Layout
+
+[ARCHITECTURE.md](ARCHITECTURE.md#find-the-code-for-each-part-of-the-system) maps each folder to
+the file to read first. Keep these layout rules:
+
+- `src/index.ts` is the package's only library export surface. `src/cli.ts` is its bin.
+- `src/guest-runtime-main.ts`, `src/guest-runtime-revision.ts` and `src/guest-media-worker.ts`
+  stay at the root of `src/`. `scripts/guest-runtime-package.mjs` and the image recipes in
+  `runtime/` address their `dist/` output by file name. The rest of the guest runtime is in
+  `src/guest/`.
+
+## Conventions
+
+- TypeScript ESM with strict settings. No `any`; narrow `unknown` at the boundary.
+- Keep files under about 700 lines and functions under about 150 (oxlint warns past both). Split
+  when it helps a reader; do not add to `src/routes/computer-use/route.ts` or
+  `src/actors/computer-use/loop.ts` when a smaller module fits.
+- Comments say why the code is the way it is. History, incident narratives, issue archaeology and
+  PR numbers go in the commit message. `TODO(#123)` may link an open issue. No all-caps emphasis.
+  `prose:check` counts violations in `src/`.
+- Tests assert behavior. Do not pin prose in docs or comments with `toContain`. The default test
+  timeout is 20 s. Provider-API fixtures come from captured wire shapes.
+- New dependencies go in the pnpm catalog (`pnpm-workspace.yaml`) when more than one workspace
+  uses them. Stay on the latest release; a comment next to the entry gives the reason for any
+  older pin. knip fails on unused files, dependencies and exports.
+- CLI results are truthful: reject unsupported execution before side effects, and keep useful
+  evidence when a run is interrupted. Documented bundle schemas and artifact paths are contracts.
 
 ## Public Boundary
 
 Assume this repository is public.
 
-- Never commit or publish secrets, PII/PHI, private customer data, private source,
-  raw private transcripts or screenshots. Public examples must be synthetic or
-  appropriately redacted. Do not copy credential files or secret values into
-  evidence, comments, docs, issues or PRs.
-- Authorized local studies may retain private evidence in designated private
-  locations under the existing capture/redaction rules. Gitignored local capture
-  is not publication permission. Follow the
-  [invariants](docs/principles/invariants-and-defaults.md) and
+- Never commit or publish secrets, PII/PHI, private customer data, private source, or raw
+  private transcripts or screenshots. Public examples are synthetic or redacted. Do not copy
+  credential files or secret values into evidence, comments, docs, issues or PRs.
+- Authorized local studies may keep private evidence in gitignored `.humanish/` under the
+  capture and redaction rules. Local capture is not publication permission. See the
+  [invariants](docs/principles/invariants-and-defaults.md) and the
   [public-readiness standard](docs/release/public-readiness-standard.md).
-- Do not commit `.env*`, `.npmrc`, generated run bundles, runtime caches or packed
-  tarballs. Keep research/operator artifacts outside the public source tree.
-- The owner's other projects, products and domains require explicit sign-off
-  before naming them in public material, even if deployed publicly. Use fictional
-  examples and placeholder owners/domains. Named public third-party OSS study
-  subjects with retained evidence remain permitted.
-
-## Working And Resuming
-
-- Read the [ramp](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.
-- Keep `main` clean; use a scoped worktree/branch. Make reviewable commits.
-- Existing explicit authority governs directly assigned work. Machine-readiness
-  metadata gates automated queue pickup, not every interactive task. Do not
-  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](docs/release/open-source-readiness.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.
-- Keep one current task handoff: requested outcome, what actually works, next
-  complete user-visible result, explicit constraints and rejected/deferred paths.
-  Link detailed evidence; mark superseded plans historical.
-
-## Verification
-
-- Use evidence appropriate to the changed behavior and material risk. Docs may
-  need link/command review; runtime changes need meaningful execution checks.
-  Required CI and release gates remain mandatory.
-- Test behavior and real failure modes, not incidental implementation structure
-  unless that structure enforces a required boundary. Provider-API fixtures must
-  derive from captured live wire shapes, never guesses that merely mirror code.
-- Once applicable checks pass, broaden or repeat them only for a new change,
-  failure or unresolved material risk. Do not rebuild upstream validation suites
-  when a focused integration check answers the question.
-- Claims of live execution need retained evidence; dry runs do not establish live
-  behavior. State what changed, what was checked and any material uncertainty.
+- Do not commit `.env*`, `.npmrc`, run bundles, runtime caches or packed tarballs.
+- Naming the owner's other projects, products or domains in public material needs explicit
+  sign-off. Use fictional examples. Named public third-party OSS study subjects are fine.
+
+## Working
+
+- Read the files in [CONTRIBUTING.md's reading order](CONTRIBUTING.md#read-these-in-order), then
+  the current task; read the contract for the boundary you are changing. Historical plans do not
+  authorize work.
+- Keep `main` clean: one worktree and branch per task, reviewable commits, squash merges.
+- Before adding a service, protocol, mode or framework, state the concrete need in the PR.
+  Prefer removing an unnecessary mechanism to documenting around it.
+- Verify in proportion to the change. Runtime changes need an execution check; claims of live
+  behavior need a retained run bundle, since dry runs do not establish live behavior. PRs say
+  what changed, what was checked and what was not.
+- With shipping authority: push, open the PR, address checks, merge when green, fast-forward
+  main and remove the worktree and branch. Releases follow the
+  [release procedure](docs/release/open-source-readiness.md). Stay on `0.x` until the maintainer
+  chooses 1.0; the minor after `0.99.0` is `0.100.0`.

package/ARCHITECTURE.md

@@ -0,0 +1,146 @@
+# Find your way around the humanish code
+
+This file describes the code on `main` and names real functions and files. `pnpm docs:check`
+fails when a path in it no longer exists, or when a file named beside a function or type no
+longer declares that name. [CONTEXT.md](CONTEXT.md) defines the domain terms, and
+[docs/decisions/](docs/decisions/README.md) records the decisions behind the rules below.
+
+## Follow one `humanish run <lab>` from manifest to findings
+
+The steps follow a live computer-use lab on a hosted E2B desktop. Every route shares steps 1, 2, 7
+and 8. Steps 3 to 6 run in the route's admit function and the `run()` it returns, which `runLab`
+reaches through `admitPlan` (`src/run-lab.ts`):
+
+- computer-use: `admitComputerUsePlan` (`src/routes/computer-use/route.ts`); its `run()` calls
+  `runAdmittedCuaRun` (`src/routes/computer-use/route.ts`).
+- scripted: `admitScriptedPlan` (`src/routes/scripted/route.ts`); its `run()` calls
+  `runScriptedPlan` (`src/routes/scripted/route.ts`).
+- terminal: `admitTerminalPlan` (`src/routes/terminal/route.ts`); its `run()` calls
+  `runAdmittedTerminalRun` (`src/routes/terminal/route.ts`).
+- shared-world: `admitSharedWorldPlan` (`src/routes/shared-world/route.ts`); its `run()` calls
+  `runAdmittedSharedWorldRun` (`src/routes/shared-world/route.ts`).
+- preview: `admitPreviewPlan` (`src/routes/preview.ts`); its `run()` calls `runPreviewPlan`
+  (`src/routes/preview.ts`), which publishes a fixture bundle.
+
+`runComputerUsePlan` (`src/routes/computer-use/route.ts`), `runTerminalPlan`
+(`src/routes/terminal/route.ts`) and `runSharedWorldPlan` (`src/routes/shared-world/route.ts`)
+admit and run in one call. Only tests and the deprecated runners call them: `runCuaActorLab`
+(`src/deprecated.ts`), `runTerminalProductLab` (`src/deprecated.ts`) and `runConcurrentSharedWorld`
+(`src/deprecated.ts`), through their route modules. `runLab` and the CLI do not.
+
+1. **Parse.** `runLabCommand` (`src/cli/commands/lab-run.ts`) calls `resolveLabManifest`
+   (`src/lab/discover.ts`), which calls `parseLabConfig` (`src/lab/config.ts`). It rejects unknown
+   keys and the compositions the
+   [support matrix](docs/ramp/README.md#check-which-compositions-a-lab-can-declare) refuses. A
+   refusal exits with code 2 before a run id exists.
+2. **Plan.** The route's CLI setup, here `computerUseRouteRun`
+   (`src/cli/commands/lab-route-computer-use.ts`), hands off to `runRoute`
+   (`src/cli/commands/lab-route-run.ts`), which calls `prepareLab` (`src/run-lab.ts`). That picks the
+   route with `routeOf` (`src/lab/plan.ts`) and plans once with `planLab` (`src/lab/plan.ts`), here
+   through `planComputerUseLab` (`src/routes/computer-use/plan.ts`). It then calls the route's admit
+   function, here `admitComputerUsePlan` (`src/routes/computer-use/route.ts`), which makes the
+   checks in step 3. A refusal from the planner or those checks returns before a declared scorer
+   loads. Otherwise a `run()` returns that takes the scorer and continues the run. `runLab` is
+   `prepareLab`, then `run()`.
+3. **Preflight.** `admitCuaRun` (`src/routes/computer-use/setup.ts`) calls `liveCuaRejection`
+   (`src/routes/computer-use/preflight.ts`) for keys, local-agent sign-in, subject env and caps, and
+   packs a `local-tree` subject. The `run()` opens the run's lifetime with `runScope`
+   (`src/run/run.ts`), and `startCuaRun` calls `startRun`, all before any sandbox or provider call.
+4. **Desktop.** Each participant runs on a `ParticipantDesktop`
+   (`src/routes/computer-use/participant-desktop.ts`): a hosted one from
+   `createE2BParticipantDesktop` (`src/routes/computer-use/e2b-desktop/desktop.ts`), a local VM
+   from `createLocalParticipantDesktop` (`src/routes/computer-use/local-vm.ts`), or
+   `createInProcessDesktop` (`src/routes/computer-use/in-process-desktop.ts`).
+   `acquireE2BDesktopSandbox` (`src/substrates/e2b/sandbox.ts`) records the sandbox id before it
+   returns. `src/subject/`
+   provisions a `clone` or `local-tree` subject over a `Shell` (`src/substrates/shell.ts`).
+5. **Participants.** `runLabParticipants` (`src/routes/computer-use/run-lanes.ts`) publishes an
+   in-progress bundle, then calls `runAllCuaParticipants` (`src/routes/computer-use/lanes.ts`). That
+   runs `runCuaParticipant` for each participant, at most `execution.concurrency` at a time, and
+   each one drives `runComputerUseLoop` (`src/actors/computer-use/loop.ts`).
+6. **Judge and publish.** `finishCuaRun` (`src/routes/computer-use/result.ts`) judges once with
+   `judgeComputerUseRun` (`src/routes/computer-use/bundle.ts`) and builds the bundle with
+   `buildCuaRunBundle` (`src/routes/computer-use/bundle.ts`), by the rules in `src/run/judge.ts`. A
+   declared scorer's failures fold in through `foldScorerFailures` (`src/run/judge.ts`), so a scorer
+   can fail a run and never pass one. `Run.finish` publishes `run.json`, then the `status.json`
+   outcome, the review and Observer data, and `.humanish/runs/latest.json` last.
+7. **Observer.** `renderObserver` (`src/observer/render.ts`) verifies the bundle with
+   `verifyRunPrepared` (`src/verify/verify.ts`) and writes `observer/index.html` from
+   `buildObserverData` (`src/observer/data.ts`).
+8. **Analysis.** `completeAutomaticAnalysis` (`src/analysis/automatic-completion.ts`) runs
+   `runAutomaticStudyAnalysis` (`src/analysis/automatic.ts`) on the `FinishedRun` that `Run.finish`
+   issued. Dry runs and labs with `review.analysis: false` skip it.
+
+## Find the code for each part of the system
+
+| Folder                     | What it holds                                                                          | Read first                          |
+| -------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------- |
+| `src/cli/`                 | The commander program, with one file per command family in `commands/`                 | `src/cli/program.ts`                |
+| `src/keys/`                | Provider key discovery: env files, the user key store and key-source probes            | `src/keys/key-resolution.ts`        |
+| `src/run-lab.ts`           | `runLab`: plan the lab once, then run the plan on its route                            | `src/run-lab.ts`                    |
+| `src/lab/`                 | Manifest parsing and warnings (`config.ts`, `parse/`), types, routing and planning     | `src/lab/plan.ts` for planning      |
+| `src/routes/`              | One folder per route; `routeOf` in `src/lab/plan.ts` picks it                          | `src/lab/plan.ts`                   |
+| `src/routes/computer-use/` | Computer-use participants and the desktops composing `src/substrates/` with route code | `src/routes/computer-use/route.ts`  |
+| `src/routes/scripted/`     | Committed scenario steps replayed on a loopback app or a provisioned clone             | `src/routes/scripted/route.ts`      |
+| `src/routes/shared-world/` | Several participants on one shared plane, provisioned or external-public               | `src/routes/shared-world/route.ts`  |
+| `src/routes/terminal/`     | A Codex agent in an E2B shell against a terminal product, with its ledgers             | `src/routes/terminal/route.ts`      |
+| `src/actors/`              | The actor contract, the registry and each actor's session code                         | `src/actors/registry.ts`            |
+| `src/subject/`             | Subject provisioning over a `Shell`: clone, local tree, desktop CLI, serve             | `src/subject/serve.ts`              |
+| `src/substrates/`          | Provider primitives: E2B in `e2b/`, Firecracker and Lima VMs in `local/`, the `Shell`  | `src/substrates/desktop-session.ts` |
+| `src/run/`                 | Run lifecycle, bundle types, bundle guards, paths, status, receipts, reclaim           | `src/run/run.ts`                    |
+| `src/verify/`              | `humanish verify`: evidence checks, share-safety grades, cost and rerun checks         | `src/verify/verify.ts`              |
+| `src/evidence/`            | Redaction, screenshot checks and desktop recordings                                    | `src/evidence/redaction.ts`         |
+| `src/analysis/`            | Automatic and on-demand study analysis                                                 | `src/analysis/automatic.ts`         |
+| `src/observer/`            | Observer data, the HTML render and the local server                                    | `src/observer/render.ts`            |
+| `src/comms/`               | Captured and received email for participant inboxes                                    | `src/comms/types.ts`                |
+| `src/feedback/`            | Feedback drafts and export bundles                                                     | `src/feedback/feedback.ts`          |
+| `src/tui/`                 | The CLI side of `humanish tui`                                                         | `src/tui/launch.ts`                 |
+| `src/browser-control/`     | The host-guest browser control protocol                                                | `src/browser-control/protocol.ts`   |
+| `src/guest/`               | The guest runtime that the local VM image runs: bootstrap, desktop, input and media    | `src/guest/runtime.ts`              |
+| `observer/`                | The Observer page, a single-file Vite build                                            | `observer/AGENTS.md`                |
+| `tui/`                     | The Ink terminal app                                                                   | `tui/AGENTS.md`                     |
+| `site/`                    | humanish.dev and its user docs in `site/content/docs/`                                 | `site/AGENTS.md`                    |
+| `humanish/`                | This repo's own labs, personas, scenarios, fixtures and coverage notes                 | `humanish/labs/first-run.yaml`      |
+| `examples/`                | Library examples shipped in the npm package: a participant and a scorer                | `examples/README.md`                |
+| `adapters/`                | Adapter fixture sets that `tests/lab/adapter-fixtures.test.ts` checks                  | `adapters/fixtures/README.md`       |
+| `bench/`                   | Benchmark apps with planted defects and their dated results                            | `bench/DEFECTS.md`                  |
+| `fixtures/`                | Synthetic apps and cases that tests and scripts copy                                   | `fixtures/minimal-app/README.md`    |
+| `skills/`                  | The companion agent skill that `npx skills add` installs                               | `skills/humanish/SKILL.md`          |
+| `runtime/`                 | Desktop and browser image recipes                                                      | `runtime/browser-guest/README.md`   |
+| `scripts/`                 | Proof, release and check scripts that `package.json` runs                              | `scripts/check-doc-paths.ts`        |
+| `docs/contracts/`          | Bundle and schema contracts, whose documented fields are API                           | `docs/contracts/run-bundle.md`      |
+| `tests/`                   | Vitest suites that mirror `src/`, plus six folders outside the mirror                  | `tests/helpers/run-golden.ts`       |
+
+`pnpm docs:check` fails when a folder directly under `src/` or `src/routes/` has no row here, or
+when a row names a folder that is gone; add the row with the folder. Participant desktops stay in
+`src/routes/computer-use/` ([decision 0004](docs/decisions/0004-participant-desktops-stay-in-the-route.md)),
+three guest entry files stay at the `src/` root
+([why](docs/architecture/guest-desktop.md#three-guest-files-stay-at-the-src-root)), and six
+`tests/` folders sit outside the mirror
+([list](CONTRIBUTING.md#find-the-test-folders-outside-the-src-mirror)).
+
+## Keep these invariants when you change code
+
+| Invariant                                                                                                                | Enforced by                                                                                                                                                                                                                                                                                                                                   | Pinned by                                                                                                                                                                                                                                                                     |
+| ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| The run bundle is the source of truth, and the Observer derives from it                                                  | `verifyRun` grades only `run.json` and its artifacts (`src/verify/verify.ts`). It reads `status.json` and the sandbox and reclaim receipts only for the `RUN_NOT_FINISHED` warning (`runNotFinishedWarnings` in `src/verify/liveness.ts`), which changes no check and no grade. `buildObserverData` takes the bundle (`src/observer/data.ts`) | `tests/observer/data-contract.test.ts`; `tests/verify/run-not-finished.test.ts` checks that the grades are the same when `status.json` contradicts the bundle or is gone; `docs/decisions/0001-run-bundle-is-the-source-of-truth.md`                                          |
+| Unsupported execution is refused before side effects                                                                     | `parseLabConfig` (`src/lab/config.ts`), `taskProtocolValidationReason` (`src/lab/validation.ts`), `planComputerUseLab` (`src/routes/computer-use/plan.ts`)                                                                                                                                                                                    | `tests/lab/task-route-preflight.test.ts`; `pnpm cli:preflight:test` runs `scripts/task-route-preflight-proof.mjs` with `tests/fixtures/task-route-preflight/deny-side-effects.mjs` preloaded                                                                                  |
+| A sandbox id is recorded before any work runs in it                                                                      | `acquireE2BDesktopSandbox` and `acquireE2BShellSandbox` (`src/substrates/e2b/sandbox.ts`) write the receipt before they return the handle, and every route that creates a sandbox calls them; `reclaimRunSandboxes` (`src/run/reclaim.ts`) switches on the receipt's provider and kills by exact id                                           | `tests/substrates/e2b/sandbox.test.ts`, which also checks that `Sandbox.create` has one call site in `src/`, `tests/routes/terminal/acquisition-boundary.test.ts`, `tests/run/reclaim.test.ts`; `tests/routes/scripted/route.test.ts` checks create, receipt, then first work |
+| Bundles carry no secrets                                                                                                 | `redactText` and `scrubLiterals` (`src/evidence/redaction.ts`); `scanRunPublicSafetyArtifacts` (`src/verify/artifacts.ts`); `buildShareSafety` (`src/verify/verify.ts`) grades `share_ready`, `local_only` or `blocked`                                                                                                                       | `tests/evidence/redaction-hooks.test.ts`, `tests/run/transient-comms-secrets.test.ts`, `tests/verify/evidence-refs.test.ts`                                                                                                                                                   |
+| Goldens pin route output                                                                                                 | `runDirSnapshot` (`tests/helpers/run-golden.ts`) snapshots a whole run folder                                                                                                                                                                                                                                                                 | `tests/golden/routes/`, `tests/golden/observer-data/`, `tests/golden/labs/`; `tests/lab/plan-lab.test.ts` checks that every `LabRoute` has a dry-run golden                                                                                                                   |
+| A run is closed on every exit, only a published run is analyzed, and `latest.json` moves only after its run is published | `runScope` and `FinishedRun` (`src/run/run.ts`); `completeAutomaticAnalysis` requires an issued `FinishedRun` for the result's run; `Run.finish` writes `latest.json` last through `writePreparedRunLatestPointer` (`src/run/contained-output.ts`)                                                                                            | `tests/run/run-lifecycle.test.ts`, which also checks that `src/run/run.ts` is the pointer's one writer, `tests/analysis/automatic-analysis.test.ts`                                                                                                                           |
+
+The receipt write is best-effort; the sandbox's server-side timeout ends a sandbox with no
+receipt. A lab preflight probe journals its receipt with `withPreflightSandbox`
+(`src/lab/preflight-probes.ts`), and `humanish reclaim --preflight` (`src/run/reclaim.ts`) kills
+what a failed probe left. [Trust boundaries](https://github.com/danielgwilson/humanish/blob/main/site/content/docs/trust-boundaries.mdx) gives the
+probe timeouts.
+
+## Read next
+
+- [docs/architecture/project-layout.md](docs/architecture/project-layout.md): the `humanish/`
+  and `.humanish/` folders in a project that runs studies.
+- [docs/ramp/README.md](docs/ramp/README.md#check-which-compositions-a-lab-can-declare): the
+  support matrix, which compositions a lab can declare and which tests pin each row.
+- [CONTRIBUTING.md](CONTRIBUTING.md#make-your-first-change): a first change, offline, and the
+  tests and contracts that common changes touch.