humanish 0.104.3 → 0.106.0

package/docs/principles/engineering.md

@@ -0,0 +1,81 @@
+# Engineering principles
+
+These are the judgment calls behind the rules in [AGENTS.md](../../AGENTS.md). Read them
+before adding a service, mode, dependency or new boundary.
+
+## Engineering Judgment
+
+Public OSS quality includes clear, idiomatic code, straightforward setup and
+low maintenance cost, alongside correctness, privacy and security.
+
+- **KISS:** use familiar patterns, existing repo code and maintained upstream
+  components. Judge total complexity: dependencies, services, configuration,
+  deployment and failure handling as well as source lines.
+- **YAGNI:** implement the requested behavior. Explicit near-term requirements
+  constrain today's design: defer their implementation, not compatibility. Avoid
+  choices that force an overhaul to deliver an already-required follow-up.
+  Speculative future uses do not justify frameworks.
+- **DRY:** share policy and behavior that must stay consistent. Similar-looking
+  code alone does not justify an abstraction; modest duplication can be clearer.
+- Deliver one working end-to-end path early, then harden it. An experiment is
+  not a release, and its qualification fixture need not become the architecture.
+- Before adding a service, protocol, mode or framework, explain the concrete
+  need and why an existing approach is insufficient. A sentence in the current
+  plan or PR is enough; routine changes need no separate design document.
+- Apply security controls at the relevant trust boundary for a credible failure
+  mode. Reuse established controls; public visibility alone does not justify
+  new runtime restrictions. Simplicity does not waive isolation or authorization.
+- Prefer removing an unnecessary mechanism to adding more documentation and
+  tests around it. Existing work is not a reason to retain a poor design.
+- If prerequisites keep expanding without an end-to-end result, reassess and
+  narrow the approach. Surface material scope or architecture changes promptly;
+  do not repeatedly ask permission for ordinary work already authorized.
+- Keep code, comments and updates concise. Explain surprising decisions and
+  tradeoffs; avoid redundant narration, invented jargon and repeated history.
+
+## Architecture
+
+- Product-specific routes, ports, scenarios and vocabulary belong in adapters.
+  Core owns shared execution, lifecycle, evidence and review behavior. Preserve
+  common interfaces across providers; avoid parallel copies of the study loop.
+- CLI results must be truthful. Reject unsupported execution before side effects;
+  preserve useful evidence and explain recoverable interruptions.
+- Documented bundle schemas and supported artifact paths are contracts.
+  Experimental receipts and internal diagnostics are not automatically APIs.
+- Tests establish observed behavior, not necessarily intended behavior. Resolve
+  code/test/doc conflicts against the current requirement and report the mismatch;
+  neither stale prose nor a passing test makes a bug correct.
+
+## Working And Resuming
+
+- Read the [ramp](../ramp/README.md), current task and relevant component
+  instructions. Read detailed contracts for the boundary being changed, not every
+  historical roadmap. Consult the invariants for security/evidence changes and the
+  release procedure before publishing.
+- Keep `main` clean; use a scoped worktree/branch. Make reviewable commits.
+- Existing explicit authority governs directly assigned work. Machine-readiness
+  metadata gates automated queue pickup, not every interactive task. Do not
+  treat an old plan as authorization to resume paused or rejected work.
+- When granted autonomous shipping authority, push, open the PR, address reviews
+  and required checks, merge when green, fast-forward main and clean up the task
+  worktree/branch. Follow [release gates](../release/open-source-readiness.md)
+  when a release is authorized; do not add new approval steps on your own.
+- Stay on `0.x` until the maintainer explicitly chooses 1.0. The next minor
+  after `0.99.0` is `0.100.0`; routine shipping authority does not authorize 1.0.
+- Keep one current task handoff: requested outcome, what actually works, next
+  complete user-visible result, explicit constraints and rejected/deferred paths.
+  Link detailed evidence; mark superseded plans historical.
+
+## Verification
+
+- Use evidence appropriate to the changed behavior and material risk. Docs may
+  need link/command review; runtime changes need meaningful execution checks.
+  Required CI and release gates remain mandatory.
+- Test behavior and real failure modes, not incidental implementation structure
+  unless that structure enforces a required boundary. Provider-API fixtures must
+  derive from captured live wire shapes, never guesses that merely mirror code.
+- Once applicable checks pass, broaden or repeat them only for a new change,
+  failure or unresolved material risk. Do not rebuild upstream validation suites
+  when a focused integration check answers the question.
+- Claims of live execution need retained evidence; dry runs do not establish live
+  behavior. State what changed, what was checked and any material uncertainty.

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

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

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

@@ -2,12 +2,12 @@
 
 Date: 2026-06-01
 
-Status: initial repo doctrine for `humanish`.
+Status: initial principles for `humanish`.
 
 ## Thesis
 
-`humanish` should be a closed-loop product simulation system, not just a
-CLI that launches agents.
+`humanish` should be a closed-loop product simulation system. Launching agents
+is one step of that loop.
 
 The operating loop is:
 
@@ -21,9 +21,9 @@ persona scenario run
 -> rerun and compare
 ```
 
-The hard part is not getting an agent to do something. The hard part is making
-the result verifiable, repeatable, safe to file, and useful to the next
-agent with no chat context.
+Getting an agent to act is the easy step. The work is making the result
+verifiable, repeatable, safe to file, and useful to the next agent with no chat
+context.
 
 ## Public Boundary
 
@@ -51,8 +51,9 @@ or issue links.
 
 ### 3. Run Bundles Are Source Of Truth
 
-The observer is a projection. The GitHub Project is a cockpit. The issue queue
-is a work surface. The run bundle is the canonical evidence record.
+The Observer is a view derived from the bundle. The GitHub Project and the issue
+queue track work. The run bundle is the evidence record the other surfaces derive
+from.
 
 ### 4. Coverage Is The Product
 
@@ -118,12 +119,12 @@ or reviewer-like gate that checks coverage, evidence, and product relevance.
 ## Anti-Patterns
 
 - Treating the best model as a substitute for harness quality.
-- Using screenshots as vibes without state or transcript evidence.
+- Treating screenshots as proof without state or transcript evidence.
 - Letting product-specific nouns leak into generic core.
 - Generating GitHub issue drafts from vague summaries without bundle links.
 - Closing issues because a PR exists, not because product proof exists.
 - Giving autonomous agents broad write authority before observe/draft stages
   are reliable.
-- Letting project fields become canonical state.
+- Letting project fields become the source of truth.
 - Retrying failed issue submission paths until duplicates appear.
 - Storing private data in examples because it was convenient during extraction.

package/docs/principles/three-roles.md

@@ -1,6 +1,6 @@
 # Three roles: researcher, stakeholder, participant
 
-Humanish runs user research. Every design decision should be checked against the
+humanish runs user research. Every design decision should be checked against the
 three people a study actually involves, because they want different things and
 conflating any two of them produces a specific, recurring class of bug.
 
@@ -16,7 +16,7 @@ adjust.
 **The stakeholder** watches. In a real study they sit behind the glass in the
 viewing room; here they open Observer, `watch`, or `serve`. They want none of the
 protocol. They want to know what happened, where people got stuck, how bad it is,
-and whether anyone succeeded — moments, severity, and the denominator.
+and whether anyone succeeded: moments, severity, and the denominator.
 
 **The participant** is the persona. They have a goal, limited patience, and their
 own idea of how the product works. They are the subject of the study, never its
@@ -24,20 +24,19 @@ instrument.
 
 ## Why the distinction earns its place
 
-Two of humanish's worst bugs were category errors between these roles, not
-missing features.
+Two of humanish's worst bugs were category errors between these roles.
 
 **Fusing the participant into the harness** made abandonment look like a
-malfunction. `gave_up` mapped to a `failed` status, so a persona giving up — the
-single most valuable thing a usability study produces — dragged the run verdict
-red as though the instrument had broken. A participant abandoning a task is a
+malfunction. `gave_up` mapped to a `failed` status, so a persona giving up, which is what a
+usability study exists to catch, dragged the run verdict red as though the
+instrument had broken. A participant abandoning a task is a
 finding. The harness only fails when the harness fails.
 
 **Fusing the researcher's question with the stakeholder's** put one pass/fail
 verdict on a bundle that answers two different questions. "Is this evidence
 trustworthy?" is genuinely pass/fail: did the harness do what it claimed, with a
 real sandbox, real actions, and cost lines nobody forged. "What did we learn?" has
-no pass/fail at all — asking whether a study passed is a category error. Because
+no pass/fail at all; asking whether a study passed is a category error. Because
 there was one slot, a session that stopped early had to be called `passed`, and a
 truncated study was reported as a green one.
 
@@ -55,14 +54,14 @@ When adding a surface, a default, or a verdict, ask:
   forms conclusions from vivid moments; that is the classic failure of the viewing
   room, and it is why researchers synthesize rather than letting the room decide.
   Anything shown to a stakeholder carries its count and its confidence, or it
-  becomes a machine for manufacturing certainty from n=1.
+  invites certainty from n=1.
 - **Would a researcher recognize this as a study?** Budgets are recruiting
-  decisions made once, up front — how many participants can we afford. No
-  researcher has ever ended a session because it got expensive.
+  decisions made once, up front: how many participants can we afford. Researchers
+  do not end a session because it got expensive.
 
 ## Related
 
-- [invariants-and-defaults.md](invariants-and-defaults.md) — fail-closed rules and
+- [invariants-and-defaults.md](invariants-and-defaults.md): fail-closed rules and
   what defaults are allowed to assume
-- [actor-fidelity.md](actor-fidelity.md) — what a claim about persona realism can
+- [actor-fidelity.md](actor-fidelity.md): what a claim about persona realism can
   and cannot mean

package/docs/product/automatic-analysis.md

@@ -5,7 +5,7 @@ separate from participant feedback and the recorded study verdict.
 
 The default is `gpt-6-astra` with high reasoning effort, a separate $3 admission
 estimate limit and a 600-second timeout. When no output limit is specified,
-Humanish selects 32,768 tokens if the exact input's admission estimate fits that
+humanish selects 32,768 tokens if the exact input's admission estimate fits that
 budget; otherwise it keeps the established 16,384-token allowance. This preserves
 previously admitted studies without increasing their spending limit. To customize it:
 
@@ -31,7 +31,7 @@ the estimate and selected token allowance before deliberately choosing a larger
 includes reasoning as well as the report; exhausting it does not produce a usable
 report and never starts an automatic retry. Analysis
 sends selected retained text and captures to OpenAI using `OPENAI_API_KEY`.
-Analysis runs in the Humanish runner using its credentials. This setting adds no
+Analysis runs in the humanish runner using its credentials. This setting adds no
 credential channel to the target application; each participant backend retains
 its existing authentication boundary. Review the separate analysis budget before running a manifest live; an actor's
 zero-dollar cap does not cap post-run analysis. The bundled first-contact
@@ -47,7 +47,7 @@ review:
     timeoutMs: 600000
 ```
 
-This requires Linux x64, qualified Codex CLI `0.154.0`, and a file-backed ChatGPT account login; the analyst
+This requires Linux x64, a Codex CLI release qualified for it (`src/actors/codex/qualified-versions.ts`), and a file-backed ChatGPT account login; the analyst
 uses low reasoning effort and remote inference. Dollar cost and a provider
 enforced output-token ceiling are unknown, so omit `maxCostUsd` and
 `maxOutputTokens`. Numeric values are rejected before participant resources are
@@ -61,9 +61,9 @@ does not enable managed local desktops.
 The same configuration works through `humanish run <lab>`, `lab run <lab>`,
 `watch <lab>`, and TUI live starts. Direct library calls to the five recording
 producers honor it too. Supported routes are computer-use, scripted-browser,
-terminal-product, sequential shared-world and concurrent shared-world. Synthetic,
-smoke and meta routes never enable analysis by default and reject an explicit
-analysis mapping before execution. `false` is accepted on every route. Dry runs show analysis
+terminal-product and shared-world. The synthetic route
+never enables analysis by default and rejects an explicit analysis mapping
+before execution. `false` is accepted on every route. Dry runs show analysis
 as skipped, without reading analysis credentials or making a provider request.
 
 Participant execution finishes and its recording is finalized before analysis is
@@ -100,12 +100,42 @@ The CLI's JSON keeps `runOk` for the original backend result, `automaticAnalysis
 for post-run analysis, and `ok` for the overall request. Failed, cancelled or
 unknown analysis produces exit code 2 without discarding the recording. A missing
 `OPENAI_API_KEY` skips default analysis and preserves a successful run exit;
-`automaticAnalysisTrigger: "default"` distinguishes that case in JSON. A missing
-key for an explicitly configured analysis remains a failed overall request.
-Either skip is retained for review and does not retry automatically. Partial
+`automaticAnalysisTrigger: "default"` distinguishes that case in JSON. So does a
+default analysis whose conservative estimate is over the default $3 limit: it is
+skipped with `AUTOMATIC_ANALYSIS_ADMISSION_REFUSED`, the run exits 0, and the CLI
+prints the `humanish analyze --run <id> --max-cost <usd>` command that runs it.
+A missing key or an over-limit estimate for an explicitly configured analysis
+remains a failed overall request. Every skip is retained for review and does not
+retry automatically. Partial
 findings remain visibly partial; a valid partial result can succeed, while a
 partial result with an analysis error still fails the command. Recorded task
 outcomes and the deterministic review verdict are never rewritten by analysis.
 
+`automaticAnalysis.reason` is one of these codes, in `--json` and in the human line
+`analysis: <state> (<reason>)`:
+
+| `reason`                                      | `state`                   | Meaning                                                               |
+| --------------------------------------------- | ------------------------- | --------------------------------------------------------------------- |
+| none (`null`)                                 | `complete`                | Analysis completed                                                    |
+| `AUTOMATIC_ANALYSIS_REUSED`                   | that of the reused result | An earlier analysis of this run was reused                            |
+| `AUTOMATIC_ANALYSIS_LIMITATIONS`              | `partial`                 | Analysis completed with recorded limitations                          |
+| `AUTOMATIC_ANALYSIS_ADMISSION_EXCEEDED`       | `partial`                 | Usage passed the admission estimate                                   |
+| `AUTOMATIC_ANALYSIS_FAILED`                   | `failed` or `partial`     | Analysis failed, or an unexpected error stopped it                    |
+| `AUTOMATIC_ANALYSIS_CANCELLED`                | `cancelled`               | Ctrl-C or the TUI's **Cancel analysis** stopped it                    |
+| `AUTOMATIC_ANALYSIS_DRY_RUN`                  | `skipped`                 | A dry run records no participant evidence                             |
+| `AUTOMATIC_ANALYSIS_SOURCE_UNAVAILABLE`       | `skipped`                 | This invocation published no run to analyze, or the run id is invalid |
+| `AUTOMATIC_ANALYSIS_SOURCE_CHANGED`           | `failed`                  | The run directory changed after the run published its bundle          |
+| `AUTOMATIC_ANALYSIS_KEY_MISSING`              | `skipped`                 | No OpenAI API key                                                     |
+| `AUTOMATIC_ANALYSIS_NO_PARTICIPANT_EVIDENCE`  | `skipped`                 | A default analysis found no participant evidence                      |
+| `AUTOMATIC_ANALYSIS_ACTOR_CANCELLED`          | `skipped`                 | The harness cancelled the participants                                |
+| `AUTOMATIC_ANALYSIS_ALREADY_REQUESTED`        | `skipped`                 | Another request already claimed this run's analysis                   |
+| `AUTOMATIC_ANALYSIS_BUSY`                     | `skipped`                 | Another analysis is running                                           |
+| `AUTOMATIC_ANALYSIS_ADMISSION_REFUSED`        | `skipped`                 | The configuration or the cost estimate was refused before any request |
+| `AUTOMATIC_ANALYSIS_STORAGE_UNAVAILABLE`      | `skipped` or `unknown`    | Analysis history or the job record could not be read or written       |
+| `AUTOMATIC_ANALYSIS_CODEX_UNAVAILABLE`        | `failed`                  | The Codex analysis provider was unavailable                           |
+| `AUTOMATIC_ANALYSIS_PUBLICATION_FAILED`       | `failed`                  | The analysis could not be published                                   |
+| `AUTOMATIC_ANALYSIS_CANCELLATION_UNAVAILABLE` | `unknown`                 | A cancellation could not be recorded                                  |
+| `AUTOMATIC_ANALYSIS_OUTCOME_UNKNOWN`          | `unknown`                 | The outcome could not be determined                                   |
+
 See the [analysis contract](../contracts/study-analysis.md) for selection limits,
 evidence validation, actual usage, corrections and share-safe export behavior.

package/docs/product/lobby-trivia-3player-external-public.md

@@ -7,17 +7,17 @@ a public deployment YOU own/operate.
 
 ## What it does
 
-- The public site is the shared plane DIRECTLY — no clone, no getHost, no subject sandbox, no seed.
-- A host-first barrier: the `host: true` seat creates the lobby; the orchestrator reads the
+- The public site is the shared plane DIRECTLY: no clone, no getHost, no subject sandbox, no seed.
+- A host-first barrier: the `host: true` participant creates the lobby; the orchestrator reads the
   `/lobby/CODE` from the host's CDP-observed URL and threads it into the follower Join missions.
   Followers go through the real Join flow (a direct `/lobby/CODE` visit does not auto-join a
   non-member).
-- Convergence — all three seats reaching one `/lobby/CODE` — is the pass signal (a digest-only
-  `lobbyConvergenceDigest`), plus temporal co-occupancy of the three seats' windows.
+- Convergence (all three participants reaching one `/lobby/CODE`) is the pass signal (a digest-only
+  `lobbyConvergenceDigest`), plus temporal co-occupancy of the three participants' windows.
 
 ## Mobile fidelity caveat (read before over-reading the results)
 
-The seats are `device: mobile` (414×896) and `device: small-mobile` (360×740). On the E2B-desktop
+The participants are `device: mobile` (414×896) and `device: small-mobile` (360×740). On the E2B-desktop
 route the rendered WIDTH is floored to `MIN_DESKTOP_RENDER_WIDTH` (500): Chrome refuses a window
 narrower than ~500 CSS px, and a narrower X screen let the window overflow and clip the page
 (0.20.3, #304). So both presets render at **500 wide**, `mobile` and `small-mobile` are identical in
@@ -29,39 +29,40 @@ Note that `desktopGeometry.screen.verified` checks the FLOORED number against it
 in `device-presets.ts` if you need to know.
 
 There is NO touch input, and isMobile/DPR are prompt-signal + metadata (DPR renders only via the CDP
-geometry path). So "3 mobile personas" means 3 mobile-LAYOUT desktop-Chromium seats, NOT touch
-devices. If a flow needs true touch/tap semantics, these seats will not exercise it. True sub-500
+geometry path). So "3 mobile personas" means 3 mobile-LAYOUT desktop-Chromium participants, NOT touch
+devices. If a flow needs true touch/tap semantics, these participants will not exercise it. True sub-500
 CSS-viewport rendering is the #221 CDP-device-emulation upgrade.
 
 ## Run it
 
-Dry-run (the default, $0 — proves the plumbing + the honesty contract, no sandboxes, no tokens):
+Dry-run (the default, $0; proves the plumbing + the honesty contract, with no sandboxes and no tokens):
 
 ```
 humanish lab run lobby-trivia-3player          # or: humanish watch lobby-trivia-3player
 ```
 
-Live (opens 3 real mobile-layout seats against the public app):
+Live (opens 3 real mobile-layout participants against the public app):
 
 ```
 # flip scenario.mode to live in the lab (or override), then:
 humanish watch lobby-trivia-3player --env-file .env.local   # OPENAI_API_KEY + E2B_API_KEY
 ```
 
-Watch it from a phone (today): serve the run directory's Observer through an authed edge —
+Watch it from a phone (today): serve the run directory's Observer through an authed edge:
 
 ```
 humanish serve --expose --tunnel <provider> --oauth <provider> --allow-emails you@example.com
 ```
 
-Native live-desktop `--expose` streaming on the concurrent path (watch the 3 live desktops, not just
+Native live-desktop `--expose` streaming on the concurrent path (watch the 3 live desktops as well as
 the evolving Observer artifacts) is a 0.20.1 fast-follow.
 
 ## Honesty
 
 This is a real public-application study of a deployment the operator attests they own/operate
-(`subject.publicTarget: { owner, authorized: true }` — author-trust, unverifiable by the harness).
-Attribution stays `shared-world` (N seats, ONE plane), but every strength claim degrades honestly and
+(`subject.publicTarget: { owner, authorized: true }`; this is author trust, which the harness cannot
+verify).
+Attribution stays `shared-world` (N participants, ONE plane), but every strength claim degrades honestly and
 is asserted-absent by verify: provenance `external-public` (not seeded); NO synthetic attestation (you
 cannot claim synthetic on a real site); plane control is operator-attested, not harness-controlled; NO
 authoritative shared-state proof; concurrency by temporal co-occupancy + observed lobby convergence.