humanish 0.107.0 → 0.109.0

package/docs/contracts/core.md

@@ -1,8 +1,6 @@
 # Core Contract
 
-Date: 2026-06-02 (current-state note updated 2026-09-30)
-
-Status: each route mints its run id and builds its bundle, and starts the run
+Each route mints its run id and builds its bundle, and starts the run
 through the run scope in `src/run/run.ts`. `startRun` creates
 `.humanish/runs/<id>` and begins `status.json`; the `Run` it returns publishes
 `run.json`, its projections and the latest pointer. `src/run/paths.ts` holds the

package/docs/contracts/errors.md

@@ -0,0 +1,62 @@
+# Error codes
+
+A failed command or library call reports a code and a message. The code is the stable part: a
+rename or removal gets a CHANGELOG entry in the release that makes it. Messages may change in any
+release.
+
+## Where a code appears
+
+- `--json`: the envelope has `ok: false` and `error: { code, message }`, and the command exits 2.
+  This output is the interface for scripts and agents. Two exceptions:
+  - A command-line usage error, such as an unknown option or a missing argument, prints
+    Commander's message on stderr, exits 1 and prints no JSON.
+  - `keys` and the `comms` connection commands report a failure as `ok: false` with a `message`
+    and no `error` field.
+- Human mode: two or three lines on stderr.
+
+  ```text
+  humanish run failed: Study not found: nope. Look in humanish/studies/, or pass a .yaml path.
+  code: HUMANISH_STUDY_NOT_FOUND
+  next: humanish study list
+  ```
+
+  A result with no code (`keys`, `comms`) prints no `code:` line. The `next:` line comes from a
+  table in `src/cli/io.ts` keyed by code, which today holds `HUMANISH_STUDY_NOT_FOUND`. Other
+  codes get no `next:` line, though some messages name a command, as the run-not-found message
+  names `humanish runs`. Stdout keeps a result's other lines: a failed run
+  prints its run id, route and participants there, and a failed `verify` prints its failing
+  checks there, since they are its result. Before 0.108.0, human mode printed the code and message
+  on stdout.
+
+- Library: the result objects `runStudy` and the analysis entry points return carry the same
+  `error.code`.
+
+## Families
+
+| Family                 | Codes | Emitted by                                                                 | Appears in                                                              |
+| ---------------------- | ----- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `HUMANISH_*`           | 138   | every CLI command and route result                                         | JSON `error.code`, library `error.code`, human `code:` line             |
+| `ANALYSIS_*`           | 86    | `humanish analyze` and the analysis service (`src/analysis/`)              | JSON `error.code` of analysis results                                   |
+| `AUTOMATIC_ANALYSIS_*` | 21    | the post-run analysis job                                                  | `automaticAnalysis.reason` on a run result and the job record           |
+| `analysis_*` lowercase | 29    | analysis execution                                                         | `error` fields in analysis artifacts and execution receipts             |
+| `codex_*` lowercase    | 13    | the Codex CLI readiness check (`src/actors/codex/`, `src/study/doctor.ts`) | doctor rows and analysis readiness, such as `codex_unsupported_version` |
+
+Counts are the distinct quoted codes in `src/` on 2026-10-03.
+
+The lowercase families are values recorded inside artifacts and receipts, and an artifact keeps
+the code it was written with. Automatic analysis reads two of them back:
+`analysis_admission_estimate_exceeded` becomes the reason `AUTOMATIC_ANALYSIS_ADMISSION_EXCEEDED`,
+and `analysis_budget_exceeded` on a default analysis prints the hint to rerun with
+`humanish analyze --max-cost`. Validation also accepts a partial artifact whose error is
+`analysis_admission_estimate_exceeded`.
+
+Share-safety reasons in `humanish verify` (`VERIFY_FAILED`, `RAW_SCREENSHOTS` and the rest) are
+grades, not errors; [run-bundle.md](run-bundle.md) lists them.
+
+## Renames
+
+0.108.0 renamed the codes that said lab: `HUMANISH_LAB_*` is `HUMANISH_STUDY_*`,
+`HUMANISH_CUA_LAB_*` is `HUMANISH_COMPUTER_USE_*`, `HUMANISH_CONCURRENT_SHARED_WORLD_LAB_*` is
+`HUMANISH_SHARED_WORLD_*`, and the terminal and scripted families drop `_LAB`. It also renamed
+`HUMANISH_INVALID_SIM_COUNT` to `HUMANISH_INVALID_PARTICIPANT_COUNT`. A run saved before a rename
+keeps the codes it was written with.

package/docs/contracts/feedback.md

@@ -1,10 +1,7 @@
 # Feedback Contract
 
-Date: 2026-06-01 (current-state note updated 2026-07-14)
-
-Status: local feedback candidate, draft, verification, Markdown, and issue-URL
-generation are shipped. These commands do not mutate GitHub, and public output
-fails closed unless the run verifies as `share_ready`.
+Feedback candidates, drafts, verification, Markdown and issue URLs ship. These commands never
+mutate GitHub, and public output fails closed unless the run verifies as `share_ready`.
 
 ## Purpose
 
@@ -78,10 +75,12 @@ was not repeated in the message trace.
 ### `draft`
 
 Builds structured feedback from the first usable run candidate, or the candidate
-selected with `--candidate`. With no candidate, a dry run produces a contract
-follow-up and a live run produces a summary of its recorded review. These
-fallbacks do not add a finding to the candidate list. All drafts require a
-verified `share_ready` run and are written under the run bundle, not GitHub.
+selected with `--candidate`. With no candidate, a live run produces a summary of
+its recorded review; that fallback does not add a finding to the candidate list.
+A dry run tests no product behavior, so `draft`, `verify`, `issue` and
+`issue-url` refuse it with `HUMANISH_FEEDBACK_REQUIRES_LIVE_RUN`. All drafts
+require a verified `share_ready` live run and are written under the run bundle,
+not GitHub.
 
 ### `verify`
 

package/docs/contracts/policy.md

@@ -1,14 +1,9 @@
 # Policy Contract
 
-Date: 2026-06-02 (current-state note updated 2026-07-14)
-
-Status: shipped policy reference for credential, network, spend, redaction,
-sharing, and assisted-run boundaries. Support remains route-specific; the
-parser, route validation, and verifier determine whether a declared field is
-consumed, rejected, or reported as a warning.
-
-Safety amendment (2026-07-14): beginning with `0.15.1`, stored provider IDs are
-evidence and never authorize core provider mutation.
+This page is the policy reference for credential, network, spend, redaction, sharing and
+assisted-run boundaries. Support is route-specific: the parser, route validation and the verifier
+decide whether a declared field is consumed, rejected or reported as a warning. Stored provider
+ids are evidence and never authorize core provider mutation.
 
 ## Purpose
 
@@ -112,7 +107,7 @@ Spend policy names when provider costs may be incurred.
 | Mode                     | Meaning                                                                                            |
 | ------------------------ | -------------------------------------------------------------------------------------------------- |
 | `no_spend`               | No provider calls that can bill.                                                                   |
-| `dry_run_only`           | Only local contract proof; no live substrate.                                                      |
+| `dry_run_only`           | Only a local dry run; no live substrate.                                                           |
 | `explicit_live_provider` | Provider calls allowed because required env var names are present and operator intent is explicit. |
 | `maintainer_approved`    | Reserved for publish, billing, or high-risk mutation workflows.                                    |
 
@@ -126,7 +121,7 @@ providerClasses:
   - model
   - desktop_substrate
 operatorIntent:
-  command: humanish lab run my-lab --json --no-open
+  command: humanish run my-study --json --no-open
   explicit: true
 budget:
   limit: unspecified
@@ -148,7 +143,7 @@ shapes, and fails closed on a match. It does **not** detect free-form PII/PHI
 those depends on using synthetic data and on reviewer judgment. Accordingly,
 `redaction: passed` means the automated secret/path scan found no matches, not a
 certification that the artifact is free of every class in the policy below. A
-first-class PII/PHI detector is planned (issue #108) and would move the listed
+first-class PII/PHI detector is [planned](https://github.com/danielgwilson/humanish/issues/108) and would move the listed
 PII classes from author-responsibility to enforced.
 
 Required redaction gates:

package/docs/contracts/run-bundle.md

@@ -1,12 +1,10 @@
 # Run Bundle Contract
 
-Date: 2026-06-02 (current-state note updated 2026-07-14)
-
-Status: `humanish.run-bundle.v1` is the shipped evidence contract. The
-TypeScript shape in `src/run/bundle.ts` (with `streams[]` in `src/run/streams.ts` and
-`sharedWorld` as `SharedWorldEvidence` in `src/run/shared-world-evidence.ts`) and fail-closed verification in `src/verify/verify.ts` are
-authoritative; this document explains the stable public fields and extension
-rules rather than independently versioning the runtime.
+`humanish.run-bundle.v1` is the evidence contract. The TypeScript shape in `src/run/bundle.ts`
+(with `streams[]` in `src/run/streams.ts` and `sharedWorld` as `SharedWorldEvidence` in
+`src/run/shared-world-evidence.ts`) and the fail-closed checks in `src/verify/verify.ts` are the
+source of truth. This page explains the stable public fields and the extension rules; it does not
+version the runtime separately.
 
 ## Purpose
 
@@ -22,12 +20,13 @@ runId: "<core run id>"
 mode: "dry-run|live"
 simCount: 1
 createdAt: "<ISO timestamp>"
-lab: # optional, additive: which manifest produced this run
-  id: "<lab id>"
-  path: "humanish/labs/<lab id>.yaml"
-  origin: "committed|ignored|explicit"
 cwd: "[target-cwd]"
 artifactRoot: ".humanish/runs/<run-id>"
+study: # optional, additive: which study file produced this run
+  id: "<study id>"
+  path: "humanish/studies/<study id>.yaml"
+  origin: "committed|ignored|explicit"
+# Runs saved by 0.108 and earlier also have `lab:`, with the same value as `study:`.
 source:
   packageName: "<public package name or null>"
   humanishSource: "present|missing"
@@ -190,7 +189,7 @@ field means no retained video, not proof that nothing happened between captures.
 Verification checks the local file, declared size, MP4 header and matching artifact
 entry without loading the whole video into memory. Raw continuous media makes the
 run `local_only` regardless of screenshot redaction. Analysis input remains text
-and screenshots. See [desktop recording](../architecture/desktop-recording.md).
+and screenshots. See [desktop recording](https://humanish.dev/docs/desktop-recording).
 
 ## Hosted Desktop Geometry
 
@@ -199,10 +198,10 @@ different facts separate:
 
 - `screen.requested`: the E2B/X screen size requested by config;
 - `screen.verified`: the screen size measured in-sandbox with `xdpyinfo`;
-- `screen.declared`: the device preset the lab ASKED for, present only when it differs from
+- `screen.declared`: the device preset the study asked for, present only when it differs from
   `screen.requested` because the rendered width was floored to Chrome's ~500px window minimum.
   `verified` compares the floored number with itself and reports a match, so a matching
-  `verified` block is NOT evidence that the preset width rendered. When `declared` is present,
+  `verified` block is not evidence that the preset width rendered. When `declared` is present,
   it did not: a `mobile` (414) and a `small-mobile` (360) participant both render at 500 and are
   indistinguishable by rendered width;
 - `browserWindow`: measured browser bounds after the window-fill attempt; physical X client
@@ -232,8 +231,8 @@ exactly; this hosted-desktop rule does not change that contract.
 ## Subject Provenance
 
 `subject` is an optional, additive top-level field: structured provenance for
-what the computer-use, shared-world or scripted-browser backend actually drove (code pin plus state story). It
-is absent on pre-existing bundles and on bundles from backends that have not
+what the computer-use, shared-world or scripted route actually drove (code pin plus state story). It
+is absent on pre-existing bundles and on bundles from routes that have not
 adopted it. The field shape, its three sources (`clone`, `app-url`,
 `local-tree`), and the `humanish verify` checks that guard it are the schema doc's
 job, not this one: see the `subject` entry under
@@ -246,7 +245,7 @@ enters this field; identity is digests, a sha, a boolean, and counts.
 ## Cost Estimate (advisory)
 
 `cost` is optional and additive (`humanish.run-cost-summary.v1`): the
-computer-use, shared-world, scripted-browser or terminal-product run's cost ESTIMATE: the sum of each participant's
+computer-use, shared-world, scripted-browser or terminal-product run's cost estimate: the sum of each participant's
 token-derived model cost plus E2B desktop compute lines. New independent CUA runs
 emit one line per owned desktop, keyed by public participant ID and carrying observed CPU/memory,
 resource source, host-measured minutes, and the derived per-second rate. Concurrent
@@ -254,7 +253,7 @@ shared-world runs carry the same lines for each participant, plus a desktop line
 `laneId: subject` for a provisioned plane; an external-public plane is not a humanish
 desktop and has no line. Older single aggregate desktop lines remain valid. Missing resource metadata stays
 unpriced; unconfirmed cleanup adds an unknown remaining-lifetime line. It is an
-ESTIMATE, never authoritative: every dollar is a rate-table multiply from the
+estimate, never authoritative: every dollar is a rate-table multiply from the
 operator-editable `src/run/pricing.ts`, carries the pricing `ratesAsOf` date and
 `source`, and is surfaced with the "estimated (rates as of `<date>`)" label. It is
 never shown as a bare charge. It follows the same **declared-absent** discipline as the
@@ -268,7 +267,7 @@ a provisioned clone records the clone's desktop as a `laneId: subject` line. A l
 without `cost` has an unmeasured spend. A live terminal run's `cost` prices the E2B terminal
 sandbox as a `desktop-minutes` line from its acquired-to-cleanup span and `e2b.getInfo` size.
 Its Codex `model-tokens` line prices the agent's tokens from the model passed as `--model`
-(`actors[0].model`, else `gpt-5.6-sol`). Codex reports usage per turn, summed over the turn's
+(`actor.model`, else `gpt-5.6-sol`). Codex reports usage per turn, summed over the turn's
 requests, so the line prices every token at the base tier and carries
 `basis: aggregated_turns_base_rate`. It stays `null` with `no_token_usage` when Codex reported
 none. `terminal-ledgers.json` still counts those tokens without a price, because its provider line
@@ -283,7 +282,7 @@ This bundle subtotal excludes separate study-analysis requests. Use
 `humanish stats` for the complete retained estimate and explicit accounting
 gaps across run costs and analysis attempts. See [study cost statistics](study-costs.md).
 
-`humanish verify` treats cost as ADVISORY on magnitude and FAIL-CLOSED on
+`humanish verify` treats cost as advisory on magnitude and fail-closed on
 labeling: absence passes, but a claimed dollar figure without its `ratesAsOf`
 date + `source`, or a total that does not match its known lines, fails. Verify
 never inspects the magnitude, so a correctly-labeled large estimate still passes.
@@ -325,34 +324,33 @@ under its namespace.
 Multi-participant browser/shared-world routes may carry optional participant grouping metadata:
 
 ```yaml
-actors:
-  - type: openai-computer-use
-    lanes:
-      - id: lane-01
-        actorType: viewer
-        surface: intake
-        caseGroup: case-001
+actor:
+  type: openai-computer-use
+participants:
+  - id: lane-01
+    actorType: viewer
+    surface: intake
+    caseGroup: case-001
 ```
 
-For repeated participants, authors can use compact roster groups. The parser expands
-each group into deterministic `lanes[]` before the engine runs:
+For repeated participants, a `participants` entry can take a `count`. The parser expands
+each such group into deterministic participants before the engine runs:
 
 ```yaml
-actors:
-  - type: openai-computer-use
-    roster:
-      - id: viewer
-        count: 3
-        actorType: viewer
-        surface: review-queue
-        caseGroup: case-001
-        persona: curious-reviewer
-        device: desktop
+actor:
+  type: openai-computer-use
+participants:
+  - id: viewer
+    count: 3
+    actorType: viewer
+    surface: review-queue
+    caseGroup: case-001
+    persona: curious-reviewer
+    device: desktop
 ```
 
-The generated participant ids are `<group.id>-01`, `<group.id>-02`, and so on. `roster`
-is mutually exclusive with explicit `lanes`, homogeneous `count`, and
-`laneFocus`; it is an authoring convenience, not a second runtime shape.
+The generated participant ids are `<group.id>-01`, `<group.id>-02`, and so on, even when
+`count` is 1. A group is an authoring convenience, not a second runtime shape.
 
 These fields are adapter-owned labels, not core enums. They let downstream
 projects express "N actors of M app-defined types across S surfaces" without
@@ -364,7 +362,7 @@ are projected into:
 - Observer `laneGroups[]`;
 - human-readable Observer stream labels.
 
-`actorType` is deliberately separate from `actors[0].type`. The latter selects
+`actorType` is deliberately separate from `actor.type`. The latter selects
 the humanish execution actor, such as `openai-computer-use` or `scripted-browser`.
 The former is the app-defined simulated user bucket, such as `viewer`,
 `maintainer`, or a downstream adapter's own role label.
@@ -485,7 +483,7 @@ humanish:
 
 For public OSS runs, previews could include allowlisted setup files such as
 `package.json`, `.gitignore`, `humanish/config.ts`, and
-`humanish/labs/*.yaml` / `humanish/personas/*.yaml` /
+`humanish/studies/*.yaml` / `humanish/personas/*.yaml` /
 `humanish/scenarios/*.yaml`. For token-backed or private maintainer runs, raw
 previews were suppressed by default. Generated state, `.git`, `.env*`, `.npmrc`,
 browser profiles, `node_modules`, `.humanish/`, and arbitrary source files were