humanish 0.106.1 → 0.107.0

package/AGENTS.md

@@ -34,10 +34,10 @@ 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. CI's
-`caps` workflow fails a PR that raises or removes a cap against the base branch, unless the PR has
-the `raise-cap` label and a `Cap raise:` line in its body that says why.
+and file names (`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. CI's `caps` workflow fails a PR that raises or removes a cap against the base branch, unless
+the PR has the `raise-cap` label and a `Cap raise:` line in its body that says why.
 
 ## Layout
 

package/ARCHITECTURE.md

@@ -24,9 +24,9 @@ reaches through `admitPlan` (`src/run-lab.ts`):
 
 `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.
+admit and run in one call. Only tests call them, directly or through the route modules'
+`runCuaActorLab`, `runTerminalProductLab` and `runConcurrentSharedWorld`. `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
@@ -54,10 +54,11 @@ admit and run in one call. Only tests and the deprecated runners call them: `run
    `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`).
+5. **Participants.** `runLabParticipants` (`src/routes/computer-use/live-phase.ts`) publishes an
+   in-progress bundle, then calls `runAllCuaParticipants`
+   (`src/routes/computer-use/participant-execution.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
@@ -68,7 +69,7 @@ admit and run in one call. Only tests and the deprecated runners call them: `run
    `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`
+   `runAutomaticAnalysis` (`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
@@ -121,14 +122,14 @@ three guest entry files stay at the `src/` root
 
 ## 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`                                                                                                                           |
+| 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/admission/library.test.ts` checks each library refusal for a run directory, a desktop module load, a caller executor or provider, and a subprocess; `tests/admission/cli.test.ts` checks each CLI refusal for a run directory, a started process and a scorer's host code; `tests/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`

package/CHANGELOG.md

@@ -8,6 +8,20 @@ The Unreleased section holds the full notes for the next version until it is tag
 
 ## Unreleased
 
+## 0.107.0: A 44-name library API, --count and --participants (2026-10-02)
+
+humanish 0.107.0 removes the library surfaces 0.106.0 deprecated, so the entry point exports 44
+names, down from 83. `runLab(config, options)` is the one way to run a lab: the route runners, the
+`RunLabOptions` hook bags, `LabOutcome.backend`, the `routesTo*` predicates and `rerun.laneIds` are
+gone, and a JavaScript caller that still passes a removed option is refused before anything runs.
+The release notes map each removed name to its replacement. On the CLI, `--count` replaces
+`--sims` and `--participants` replaces `--lanes`; the old flags work with a warning until 0.108.0.
+A scripted `press` step sends its key. A signalled live run records itself as interrupted and
+kills its sandboxes. Restricted Codex launches check the release's app-server schema before they
+start, and a terminal lab with no declared model runs on `gpt-5.6-sol` and prices its tokens.
+
+[Release notes](https://github.com/danielgwilson/humanish/releases/tag/v0.107.0)
+
 ## 0.106.1: Codex CLI 0.160.0 and reclaim in E2B debug mode (2026-10-01)
 
 Codex participants, Codex-account analysis and `humanish doctor` admit Codex CLI 0.160.0 (published

package/CONTEXT.md

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

package/CONTRIBUTING.md

@@ -68,14 +68,14 @@ Two kinds of change need one more step:
 
 `pnpm format` rewrites files with oxfmt. `pnpm check` fails on unformatted files.
 It also holds three counts to caps in package.json: oxlint warnings (`lint`), prose in `src/`
-comments (`prose:check`: issue references, `FIX-N` tags, all-caps emphasis), and identifiers in
-`src/` outside the exempt contract modules that still say lane, seat, role, sim or study
-(`vocabulary:check`). Each check fails when its count rises above the cap and also when it falls
-below it, so the PR that reduces a count lowers the cap in the same commit; the failure message
-names the flag and the new value. CI's `caps` workflow (`scripts/check-cap-direction.mjs`) also
-fails a PR that raises or removes a cap against the base branch, unless the PR has the `raise-cap`
-label and a `Cap raise:` line in its body that says why. `pnpm lint` prints the warnings that
-already exist, several hundred of them; that is expected. `pnpm knip` fails on unused files,
+comments (`prose:check`: issue references, `FIX-N` tags, all-caps emphasis), and identifiers and
+file names in `src/` outside the exempt contract modules that still say lane, seat, role, sim or
+study (`vocabulary:check`). Each check fails when its count rises above the cap and also when it
+falls below it, so the PR that reduces a count lowers the cap in the same commit; the failure
+message names the flag and the new value. CI's `caps` workflow (`scripts/check-cap-direction.mjs`)
+also fails a PR that raises or removes a cap against the base branch, unless the PR has the
+`raise-cap` label and a `Cap raise:` line in its body that says why. `pnpm lint` prints the warnings
+that already exist, several hundred of them; that is expected. `pnpm knip` fails on unused files,
 dependencies and exports, and on any import cycle.
 
 ## Useful Commands

package/README.md

@@ -294,8 +294,8 @@ and Intel macOS keep the one version they ran before qualification began, which
 qualified there. Any other version, including one Codex updated itself to, is refused with the
 list of accepted versions.
 
-**Credentials.** For each provider key a command needs, humanish uses the first
-of these sources that has it. It prints the name and source of each key it
+**Credentials.** humanish fills each provider key that is not already set from
+the first of these sources that has it. It prints the name and source of a key it
 fills from sources 2 to 4, never the value:
 
 1. the process environment, including a file passed with `--env-file`;
@@ -306,7 +306,12 @@ fills from sources 2 to 4, never the value:
    which `humanish keys set` writes as plain text with mode `0600`.
 
 A dry run reads no provider key, so `run`, `lab run` and `watch` consult sources 2 to 4 only
-for a live lab. `lab preflight`, `doctor`, `tui` and the `comms` commands still consult them.
+for a live lab. A live run fills every key it finds and prints the ones its plan reads: its model,
+desktop and runtime keys, its `subject.env` names, the variable
+`comms.email.external.authTokenEnv` names, `ANTHROPIC_API_KEY` for a Claude Code participant, and
+`OPENAI_API_KEY` when its automatic analysis runs on OpenAI. With a declared scorer it prints
+every key it fills, since the scorer's code may read any. `lab preflight`, `doctor`, `tui` and the
+`comms` commands still consult them.
 `humanish analyze` consults them for a live OpenAI analysis, and not for `--dry-run` or the
 Codex analyst.
 `HUMANISH_STRICT_KEYS=1` turns off sources 2 to 4. `init` and `doctor` also run

package/dist/actors/codex/app-server-client.js

@@ -1,6 +1,7 @@
 import readline from "node:readline";
 import { redactText } from "../../evidence/redaction.js";
-import { formatJsonRpcError, isRecord, } from "./app-server-trace.js";
+import { isRecord } from "../../run/type-guards.js";
+import { formatJsonRpcError } from "./app-server-trace.js";
 export class CodexStdioClient {
     child;
     commandName;

package/dist/actors/codex/app-server-trace.d.ts

@@ -150,5 +150,4 @@ export declare function renderTranscript(trace: CodexAppServerTrace): string;
 export declare function readNestedString(value: unknown, pathParts: string[]): string | undefined;
 export declare function formatJsonRpcError(error: JsonObject): string;
 export declare function redactCodexEnvelope(value: unknown, rootCwd: string): unknown;
-export declare function isRecord(value: unknown): value is JsonObject;
 export {};

package/dist/actors/codex/app-server-trace.js

@@ -1,6 +1,7 @@
 // The trace a codex-app-server run writes (summary.json): its schema, the recorder that builds it
 // from app-server envelopes, and the redaction applied before anything is persisted.
 import { digestText, publicPathForTrace, redactText, tailText } from "../../evidence/redaction.js";
+import { isRecord } from "../../run/type-guards.js";
 export const CODEX_APP_SERVER_TRACE_SCHEMA = "humanish.codex-app-server-trace.v1";
 const authLikeKey = /(api[_-]?key|access[_-]?token|auth[_-]?url|authorization|bearer|credential|password|secret|token)$/i;
 const pathLikeKey = /^(cwd|path|writableRoots|workspaceRoot)$/i;
@@ -419,6 +420,3 @@ function limitTranscript(value) {
     }
     return `[...sanitized transcript truncated to last ${maxChars} characters...]\n${value.slice(-maxChars)}`;
 }
-export function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}

package/dist/actors/codex/app-server.js

@@ -2,8 +2,9 @@ import { spawn } from "node:child_process";
 import path from "node:path";
 import { digestText, tailText } from "../../evidence/redaction.js";
 import { prepareContainedOutputDirectory, prepareContainedOutputFile, prepareSelectedOutputDirectory, writeContainedOutputFile, } from "../../run/contained-output.js";
+import { isRecord } from "../../run/type-guards.js";
 import { CodexStdioClient } from "./app-server-client.js";
-import { CodexTraceRecorder, isRecord, readNestedString, redactCodexEnvelope, renderTranscript, } from "./app-server-trace.js";
+import { CodexTraceRecorder, readNestedString, redactCodexEnvelope, renderTranscript, } from "./app-server-trace.js";
 export async function runCodexAppServerSession(options) {
     const preparedRunRoot = await prepareSelectedOutputDirectory(process.cwd(), options.runRoot);
     return runCodexAppServerSessionInPreparedRoot(options, preparedRunRoot);

package/dist/actors/codex/protocol-compat.d.ts

@@ -0,0 +1,27 @@
+import type { ProtocolContract } from "./protocol-contract.js";
+type Schema = boolean | Record<string, unknown>;
+/** The definitions of one generated schema, and the params definition of each method. */
+export interface ProtocolSchema {
+    readonly definitions: ReadonlyMap<string, Schema>;
+    readonly requestParams: ReadonlyMap<string, string>;
+    readonly notificationParams: ReadonlyMap<string, string>;
+}
+/** What the check found: changes that refuse the launch, and additions it only records. */
+export interface ProtocolCheck {
+    readonly incompatibilities: string[];
+    readonly additions: string[];
+}
+/**
+ * Reads the files `codex app-server generate-json-schema --experimental` writes: the v2 and full
+ * bundles for definitions, and the ClientRequest and ServerNotification unions for params.
+ */
+export declare function loadProtocolSchema(directory: string): Promise<ProtocolSchema>;
+/** A field's alternatives at `path` under a definition, or none when the field is gone. */
+export declare function resolveField(schema: ProtocolSchema, definition: string, fieldPath: string): Schema[];
+/** Checks a generated schema against the contract; any incompatibility refuses the launch. */
+export declare function checkProtocol(schema: ProtocolSchema, contract: ProtocolContract): ProtocolCheck;
+/** The refusal detail for an incompatible release. */
+export declare function protocolIncompatibilityMessage(cliVersion: string | undefined, incompatibilities: readonly string[]): string;
+/** The run warning for schema values beyond the baseline, or undefined when there were none. */
+export declare function protocolAdditionsWarning(cliVersion: string | undefined, additions: readonly string[] | undefined): string | undefined;
+export {};