humanish 0.34.0 → 0.35.0

package/docs/contracts/schemas.md

@@ -3,7 +3,7 @@
 Date: 2026-06-02 (current-state note updated 2026-07-14)
 
 Status: reference map for the major contracts shipped through source version
-`0.34.0`; it is not an exhaustive inventory of command/result envelopes. Exported types,
+`0.35.0`; it is not an exhaustive inventory of command/result envelopes. Exported types,
 schema constants, parsers, and validators in `src/` are authoritative. Rows
 marked "reserved" name layering intent only — no code emits or validates them
 yet. Do not emit a reserved schema.
@@ -160,10 +160,19 @@ A lab is a composition over code primitives, not a hardcoded kind:
   deterministic `lanes[]` before the engine runs (`viewer-01`, `viewer-02`,
   ...), so the runtime and run bundle keep one normalized lane shape. `roster`
   is XOR with explicit `lanes`, homogeneous `count`, and `laneFocus`;
-- `execution.concurrency` (computer-use E2B route): bounds in-flight (paid)
-  fan-out lanes; default `min(laneCount, 3)`. The env override
-  `HUMANISH_CUA_MAX_CONCURRENCY` may only LOWER the effective bound, never raise
-  concurrent paid desktops (invariant 3). Inert (warned) on other routes.
+- `execution.concurrency` (computer-use E2B routes, including shared-world): a
+  CAP on lanes in flight at once. When omitted, every declared seat runs
+  simultaneously (the parser fills `concurrency = laneCount` for multi-seat
+  labs) — total sessions and spend are identical either way; only wall-clock
+  and simultaneity differ. Declaring a value below the seat count runs seats in
+  waves and emits a warning saying so, because a green waved run is otherwise
+  indistinguishable from the all-live run the author meant. On shared-world
+  labs this field is also the sequential/concurrent selector: `concurrency: 1`
+  is the sequential turn-taking PoC; anything higher (including the filled
+  default) is the concurrent substrate. The env override
+  `HUMANISH_CUA_MAX_CONCURRENCY` may only LOWER the effective bound, never
+  raise concurrent paid desktops (invariant 3), and a lowering is recorded on
+  the plan (`envLoweredConcurrencyFrom`). Inert (warned) on other routes.
   `execution.timeoutMs` is the PER-LANE session budget on this route (semantics
   change: it was the single-session budget pre-fan-out); there is no run-level
   wall clock. `policies.allowPublicTargets` cannot combine with N>1 against one
@@ -243,22 +252,35 @@ A lab is a composition over code primitives, not a hardcoded kind:
   only command-scoped). The scripted-browser route is loopback-only and rejects
   `redactScreenshots: true` (blur unimplemented there) and
   `allowPublicTargets: true` fail-closed rather than ignoring them.
-- `comms` (clone/local-tree + shared-world computer-use routes; #297): off-app
+- `comms` (#297; hosted on the clone/local-tree computer-use lanes and the
+  CONCURRENT shared-world getHost plane — warned inert everywhere else,
+  including app-url/operator-provided subjects and the sequential
+  `concurrency: 1` shared world, neither of which has a catch to host): off-app
   email/SMS the app itself SENDS, made a persona-driven testable surface.
   `comms.email` = `{ kind: fake, injectEnv, port?, recipients?, linkOrigin? }`.
   `injectEnv` is the ADOPTER-NAMED env var the app reads for its email-API base
   URL (e.g. `RESEND_API_URL`); the harness sets it to an in-sandbox catch (so it
   is NOT declared in `subject.env`) that captures the app's sends without touching
-  the internet. `kind` must be `fake` (`real`/provider-backed is rejected until
-  implemented); `port` ≤ 65534 (the catch reserves `port+1` for the read-only
-  inbox listener the shared-world route getHost-exposes); `recipients[]` =
-  `{ lane, address? }` declare the literal address each lane's app emails (so the
-  drain can match it, and the persona is told an inbox URL to read + click);
-  `linkOrigin` is an optional operator-declared origin the app bakes into links
-  when it differs from the serve origin. Captured mail is drained into a
+  the internet — verify the app actually reads that variable, because a run whose
+  catch captured zero sends warns at teardown for exactly that. `kind` must be
+  `fake` (`real`/provider-backed is rejected until implemented); `port` ≤ 65534
+  (the catch reserves `port+1` for the read-only inbox listener the shared-world
+  route getHost-exposes). `recipients[]` = `{ lane, address? }`: OMIT the list
+  and the parser fills one deterministic address per lane
+  (`<laneId>@example.test`) so every seat can do email (#351). When declared, a
+  `lane` must be one of the lab's real lane ids (roster ids, or the generated
+  `lane-01..lane-NN` under `count`) — an unknown lane is a hard parse error
+  listing them, zero addressed lanes is a hard error, partial coverage warns
+  with the uncovered lanes. Each addressed lane's actor prompt is extended with
+  the full handoff: its address ("enter exactly that"), the inbox URL, and the
+  wait steering ("waiting for an email is normal, not a blocker"). `linkOrigin`
+  is an optional operator-declared origin the app bakes into links when it
+  differs from the serve origin; the harness rewrites captured links through it
+  so a clicked link resolves to a reachable host. Captured mail is drained into a
   digest-only `humanish.comms-thread.v1` artifact (from/to/subject/link DIGESTS +
-  an OTP COUNT — no raw address/link/code persists). Requires `python3` in the
-  subject sandbox (the stock E2B desktop template has it).
+  an OTP COUNT — no raw address/link/code persists); the READABLE proof a
+  persona saw the email is its screenshots of the inbox page. Requires `python3`
+  in the subject sandbox (the stock E2B desktop template has it).
 
 Lab backends report results in their own schemas (`humanish.run-result.v1`,
 `humanish.oss-lab-result.v1`, `humanish.oss-meta-lab-result.v1`,

package/docs/goals/current.md

@@ -16,7 +16,7 @@ Humanish should be the open-source CLI that lets a maintainer ask:
 The answer should be observable, verifiable, public-safe, and easy to turn into
 actionable feedback.
 
-## Current Program Truth (source `0.34.0`)
+## Current Program Truth (source `0.35.0`)
 
 The package source and repository implementation in this tree agree on these
 points:

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

@@ -82,7 +82,7 @@ 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` |
-| 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` (default) = SEQUENTIAL turns (one sandbox); `> 1` = CONCURRENT (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. |
+| 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 for share-as-is bundles (a redact-on-export step for raw bundles is planned) |

package/docs/ramp/README.md

@@ -2,7 +2,7 @@
 
 Status: public-safe contributor and agent ramp.
 
-Package/source version in this tree: `0.34.0` (2026-08-05). The containment boundary introduced in
+Package/source version in this tree: `0.35.0` (2026-08-05). The containment boundary introduced in
 `0.15.1` remains in force: managed run and output paths bind to validated
 physical filesystem identities, and stored provider IDs are evidence, not
 cleanup authority. The bundled OSS meta-lab is dry-run only until
@@ -17,7 +17,7 @@ context.
 Read these in order:
 
 1. [`AGENTS.md`](../../AGENTS.md) for public boundary and engineering rules.
-2. [`docs/principles/invariants-and-defaults.md`](../principles/invariants-and-defaults.md) — the constitution: which rules are invariants and which are overridable defaults.
+2. [`docs/principles/invariants-and-defaults.md`](../principles/invariants-and-defaults.md) — which rules are invariants and which are overridable defaults, each with the reason it exists and the check that enforces it. (The enforcement is what makes a rule real here — when a doc sentence and a test disagree, trust the test and say so.)
 3. [`README.md`](../../README.md) for install, commands, and package shape.
 4. [`docs/goals/current.md`](../goals/current.md) for the active product goal.
 5. [`docs/goals/proof-roadmap/goal.md`](https://github.com/danielgwilson/humanish/blob/main/docs/goals/proof-roadmap/goal.md) for the ratified proof architecture (repo-only; not shipped in the npm package, hence the absolute link).
@@ -113,8 +113,9 @@ Implemented:
 Still not good enough:
 
 The [current proof-roadmap checkpoint](https://github.com/danielgwilson/humanish/blob/main/docs/goals/proof-roadmap/README.md)
-supersedes implementation-status phrases in the immutable 2026-06-10 roadmap
-packet without changing its success standard.
+supersedes implementation-status phrases in the 2026-06-10 roadmap packet
+(kept as written — it is a dated record; its README carries current status)
+without changing its success standard.
 
 - capability receipts are not adopter replacement: no first-party deletion
   branch has yet removed a bespoke generic harness while preserving

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanish",
-  "version": "0.34.0",
+  "version": "0.35.0",
   "description": "Open-source-safe CLI for persona simulation, observer review, and public-safe feedback drafts.",
   "author": "Daniel G Wilson <daniel@danielgwilson.com>",
   "keywords": [

package/skills/humanish/SKILL.md

@@ -151,6 +151,24 @@ A lab is a composition (`subject` × `actors` × `execution` × `scenario` ×
 `npx humanish lab inspect <lab>` to see how a manifest parses, including
 warnings for fields the engine does not consume yet.
 
+### Many actors at once (fan-out, shared worlds, concurrency)
+
+- **Every declared seat runs live at once by default.** A 6-lane roster is 6
+  simultaneous actors; total sessions and spend are the same either way, only
+  wall-clock and simultaneity differ. `execution.concurrency` is a CAP, not a
+  mode: declare it only to bound simultaneous paid desktops, and expect a parse
+  warning when the cap makes seats run in waves (a green waved run looks
+  identical to the all-live run you meant, so the harness says so up front).
+- **Per-lane worlds vs one shared world.** A plain multi-lane computer-use lab
+  gives each actor its OWN app instance (independent studies in parallel). Add
+  `subject.topology: shared-world` for N actors in ONE world (a lobby, a shared
+  DB, actors seeing each other's changes). `execution.concurrency: 1` on a
+  shared-world lab is the sequential turn-taking variant — one actor at a time,
+  and note comms/email has no wiring there.
+- **Watching it:** each live lane is its own Observer tile/stream; lanes beyond
+  a declared cap start when a slot frees, which on a capped run looks like idle
+  tiles — another reason to leave the cap out unless you need it.
+
 Use committed `humanish/labs/*.yaml` for public-safe, reproducible labs. Use
 ignored `.humanish/labs/*.yaml` or `.humanish/local/labs/*.yaml` for private repo
 targets, local-only dogfood, or machine-specific settings. Never commit private
@@ -179,19 +197,45 @@ the app sent it to finish a step.
 ```yaml
 comms:
   email:
-    injectEnv: RESEND_API_URL      # adopter-named: whatever env var YOUR app reads for its
-                                   # email-API base URL. The harness sets it to the in-sandbox
-                                   # catch — do NOT also list it in subject.env.
+    injectEnv: RESEND_API_URL # adopter-named: whatever env var YOUR app reads for its
+      # email-API base URL. The harness sets it to the in-sandbox catch — do NOT also
+      # list it in subject.env. VERIFY the app actually reads this variable: a stock
+      # email SDK does not honor a base-URL env unless the app passes it through, and
+      # an app that ignores it sends real mail (or throws) while the inbox stays empty.
+      # A run where the catch captured zero sends warns at teardown for exactly this.
+```
+
+That is the whole block for the common case. Every lane automatically gets a
+deterministic inbox address (`<laneId>@example.test`), and each actor's prompt is
+extended with the full handoff: its address ("when the app asks for an email
+address, enter exactly that"), the inbox URL to open, and the wait steering
+("waiting for an email is normal, not a blocker"). Declare `recipients` only to
+customize addresses or limit which lanes do email:
+
+```yaml
     recipients:
-      - lane: lane-01              # the actor lane that signs up
-        address: user@example.test # the literal address the app emails (what the persona uses)
+      - lane: signup-01 # this lab's REAL lane id — a roster lane's `id`, or the
+        # generated lane-01..lane-NN names when you use `count`. An unknown lane
+        # is a hard parse error listing the lab's actual lane ids (a mismatch
+        # would silently disable the funnel for that seat, which is how a
+        # 6-actor field run lost every inbox at once). Lanes you leave out get
+        # no inbox and are never told one exists — the parser warns which.
+        address: user@example.test # what the actor signs up with; the evidence
+        # drain matches captured mail against it.
 ```
 
 The app keeps calling its email API normally (Resend/SendGrid-shaped, or a custom
-profile); only the base URL is redirected. Works on the clone/local-tree route and
-the concurrent shared-world route. It needs `python3` in the subject sandbox (the
-stock E2B desktop has it). See `docs/contracts/schemas.md` for the full `comms:`
-shape and `humanish <cmd> --help` for run flags — this skill does not restate them.
+profile); only the base URL is redirected. Route support: the clone/local-tree
+computer-use route (inbox on the sandbox's own loopback) and the CONCURRENT
+shared-world route (inbox getHost-exposed from the subject sandbox; the default
+since every seat now runs live at once). Declared anywhere else — app-url /
+operator-provided subjects, or a sequential `concurrency: 1` shared world — it is
+warned inert at parse: no catch exists there and no actor hears about an inbox.
+It needs `python3` in the subject sandbox (the stock E2B desktop has it).
+Evidence is digest-only (`humanish.comms-thread.v1` — counts and digests, never
+raw mail); the *readable* proof a persona saw the email is its screenshots of the
+inbox page. See `docs/contracts/schemas.md` for the full `comms:` shape and
+`humanish <cmd> --help` for run flags — this skill does not restate them.
 
 ## First Proof Run