humanish 0.0.1 → 0.15.0

package/docs/goals/current.md

@@ -0,0 +1,409 @@
+# Current Goals
+
+Status date: 2026-07-08 (rev 13)
+
+This page is the current public-safe operating goal for `humanish`. Keep it
+short enough to reread before a coding session and concrete enough that future
+agents can choose useful work without private context.
+
+## North Star
+
+Humanish should be the open-source CLI that lets a maintainer ask:
+
+> What happens when realistic synthetic personas try to use this app, CLI, or
+> agent-facing workflow?
+
+The answer should be observable, verifiable, public-safe, and easy to turn into
+actionable feedback.
+
+## Definition Of Awesome
+
+A world-class Humanish run should eventually provide:
+
+- one human-friendly command that starts simulations and opens Observer;
+- multiple synthetic personas with different goals, patience, and skill levels;
+- UI, CLI, TUI, and code-agent lanes in one mission-control Observer;
+- real evidence: screenshots, terminal transcripts, lifecycle events, traces,
+  filesystem setup-quality snapshots, artifacts, and verifier output;
+- clear pass, fail, blocked, and gap states;
+- public-safe feedback issue drafts that do not mutate GitHub by default;
+- first-class `.yaml` lab manifests for reusable simulation runs;
+- adapter contracts that let projects customize behavior without forking core;
+- release gates that prevent PII, PHI, secrets, private artifacts, and stale
+  internal residue from reaching the public repo or package.
+
+## Current Objective
+
+Make the public package and repo credible enough that an external maintainer can:
+
+1. install the skill;
+2. install `humanish`;
+3. run `humanish init`;
+4. run `humanish watch`;
+5. run `humanish watch first-run` or another lab manifest;
+6. inspect Observer evidence;
+7. verify the bundle;
+8. produce a public-safe feedback draft;
+9. understand the next live-adapter path without reading chat history.
+
+## Near-Term Goals
+
+### 1. Public Readiness
+
+Keep the repository clean and public-safe.
+
+Acceptance:
+
+```bash
+pnpm release:check
+git diff --check
+```
+
+Fresh clone release checks should pass before public visibility changes.
+
+### 2. Future-Agent Ramp
+
+Maintain a durable ramp that tells future contributors and coding agents where
+to start, what exists, what remains, and what proof is required.
+
+Acceptance:
+
+- [`docs/ramp/README.md`](../ramp/README.md) stays current;
+- this page stays current;
+- README links both;
+- release package includes both docs directories.
+
+### 3. Fresh-Agent Install Proof
+
+Prove the skill and package setup flow from a disposable target app with no chat
+context.
+
+Target proof:
+
+```bash
+npm i -D humanish
+npx humanish init --yes
+npx humanish watch --json --no-open
+npx humanish verify --run latest --json
+npx humanish feedback issue --run latest --repo owner/repo --format markdown
+```
+
+The proof target must use synthetic personas and no real user data.
+
+### 4. Live Browser Adapter
+
+Graduate from synthetic UI lanes to a real browser journey against a local app.
+
+Minimum acceptance:
+
+- local app target detection;
+- browser launch;
+- route/state capture;
+- screenshot artifact;
+- run bundle references screenshot evidence;
+- Observer renders the screenshot;
+- `verify` fails closed if required evidence is missing;
+- bounded desktop/mobile two-step browser persona proof with per-step traces and
+  screenshots. `done`
+- LLM-driven browser lane: the registered `openai-computer-use` actor dispatches
+  from a lab config (`subject.source: app-url`, loopback entry only) into a hosted
+  E2B desktop, fills the provider-neutral `stream.actor` trace seam, and persists
+  a verified redacted bundle (0.3.0 registered the actor; 0.4.0 made
+  `actors[].type` a real dispatch key). `done`
+- Clone subject provider: `subject.source: clone` + `serve` clones a repo INTO the
+  sandbox, installs/builds/starts it from config, probes readiness, and records
+  provenance (repo, commit, env names) in the bundle — config-only computer-use
+  labs against real apps (0.5.0; see `docs/goals/proof-roadmap/goal.md` —
+  repo-only, not shipped in the npm package — and
+  `docs/principles/invariants-and-defaults.md`, which ships in the package).
+  `done`
+- De-paranoia (0.6.0): the redaction redesign + demoted defaults. Screenshots are
+  full-fidelity by default (redaction binds the publish boundary, not capture —
+  `policies.redactScreenshots` opts back in); `policies.allowPublicTargets` lets an
+  owner drive a declared deployment/preview; `subject.clone.keep` is honored on
+  failure for debugging; `serve.installTimeoutMs`/`buildTimeoutMs` are configurable
+  for monorepo-scale builds. Doctrine updated with the capture-vs-publish rule. This
+  re-sequences the proof roadmap: a redaction redesign and an overridable
+  public-target policy are prerequisites for any decision-grade depth evidence, so
+  they land BEFORE the consumer-web-app / agent-skill depth phases. `done`
+- Device presets (0.6.1): viewport/device is a real dimension, with LITERAL values copied
+  from the in-house sims (mobile 414×896 … wide 1920×1080; default `desktop` 1440×950) —
+  not guessed. `execution.desktop.device` picks the per-run viewport; the guessed 1280×800
+  is gone. Honest fidelity: on the E2B route only width/height render (real mobile *layout*)
+  + the model is told its device, matching the sims' organic lanes; true touch/DPR/UA needs
+  the CDP actor. Per-*persona* device (N×devices) rides fan-out. `done`
+
+### 5. Live Terminal And Codex Lanes
+
+Make local PTY and Codex-style lanes reliable enough that Observer can show
+running, passed, failed, blocked, and timed-out states without human inference.
+
+Minimum acceptance:
+
+- sanitized transcript persistence;
+- explicit completion reason;
+- verifier checks redaction status;
+- Observer polling reflects lane completion;
+- no raw private transcript or credential values.
+
+Terminal-product real-agent lane (0.8.0; depth-axis layer 6, so an adopter can delete a
+bespoke real-agent sim for humanish + a thin adapter — see
+`docs/goals/terminal-product-lane/goal.md`):
+
+- `subject.source: terminal-product` + `execution.target: e2b-terminal` + the registered
+  `codex-exec` terminal actor route a config to a real Codex agent studying a product from
+  public surfaces inside an E2B shell. `done`
+- The credential-placement inversion is enforced by construction AND by verifier: the runtime
+  key is injected ONLY command-scoped into the `codex` invocation, never sandbox-global; a
+  deny-by-default allowlist excludes GitHub/payment/deploy/db creds; metadata is a positive
+  allowlist; stdin is disabled with an always-present interventions ledger; cleanup is proven
+  or the run fails closed. `done`
+- Cost/no-spend ledger with the null-vs-known-zero-vs-absent discipline (unknowns are `null`,
+  never guessed); the no-spend proof is DERIVED from the ledger, never asserted; `maxUsd`/
+  `maxJobs`/`maxMinutes` caps enforced fail-closed. `done`
+- Product-adapter extension seam: exported contract types + a scorer/feedback DI hook +
+  adapter-namespaced product nouns, so an adopter attaches scoring/feedback as a thin
+  in-repo extension without forking core. `done`
+- Cleanup is proven BY EXACT CREATED ID: `Sandbox.kill(id)`, confirmed further by
+  `Sandbox.getInfo(id)` where the SDK exposes it, and humanish never calls `Sandbox.list`. A live
+  rung never needs a dedicated or isolated E2B key; the SAME shared operator key used everywhere
+  else in this repo is safe, because humanish only ever reaches a sandbox it created (see
+  "The placement rule" corollary in `docs/principles/invariants-and-defaults.md`).
+- LIVE-PROVEN (2026-07-09): a real Codex agent, bootstrapped in a stock E2B shell (Node
+  installed in-sandbox, run via `npx -y @openai/codex@latest exec`), studied a public
+  agent-CLI product from its declared public surfaces and ran the product's free zero-spend
+  guide within `$0` no-spend caps; verdict nonce-verified, cleanup proven BY EXACT ID
+  (`getInfo(id)` SandboxNotFoundError, never `Sandbox.list`), verify 15/15, share_ready
+  (`docs/goals/terminal-product-lane/receipts/terminal-live-rung-2026-07-09.md`). This closes
+  the #159 live-receipt gap. Optional follow-up: a custom image with the agent runtime baked in
+  to drop the per-run npx bootstrap. Duplex-PTY/xterm replay is a deferred SLICE 5.
+
+Multi-lane fan-out for the computer-use lab (0.9.0; proof-roadmap layer 2, the prerequisite
+for multi-actor shared-state work — #163, see `docs/goals/multi-lane-fanout/goal.md`):
+
+- `actors[0].lanes[]` (differentiated roster: per-lane persona/device/starting-surface) XOR
+  `actors[0].count` (homogeneous) fan out N independent E2B desktops in ONE run bundle;
+  `per-lane worlds` is the only topology this slice (shared-world is #164). `done`
+- `execution.concurrency` bounds in-flight paid desktops (default min(N,3); env may only
+  lower it); a pre-flight spend/lane plan prints before any sandbox/provider call and at $0
+  in dry-run; per-lane teardown reclaims ONLY each lane's own sandbox by id (never
+  account-wide). `done`
+- Proven deterministically (fake substrate: bounded concurrency, by-id teardown, fail-fast,
+  hollow-lane caught) AND with a kept live rung (2 lanes, two distinct desktops, both
+  reclaimed by id, bundle verifies — `docs/goals/multi-lane-fanout/receipts/`). `done`
+- Deferred: seed-fork provisioning (PR-2), in-process-route fan-out, shared-world topology
+  (#164).
+
+Shared-world topology — multi-actor against ONE shared mutable service (0.10.0; proof-roadmap
+layer 7; #164; `docs/goals/shared-world-topology/`). The north-star sim leverage: MANY personas,
+ONE shared world.
+
+- Sequential (`topology: shared-world`, concurrency 1): one sandbox, N role seats take turns
+  against the shared DB; a checkpoint timeline proves role B acted on a world already containing
+  role A's mutation. `done`
+- **Concurrent (`topology: shared-world` + `concurrency > 1`): one subject sandbox served +
+  `getHost`-exposed, N actor desktop sandboxes drive that one URL SIMULTANEOUSLY** (reuses fan-out
+  orchestration; all N+1 reclaimed by id). Honest attribution under concurrency: per-persona
+  outcomes + harness-clocked `laneWindows` proving real overlap + a `stateSeries` of the shared
+  world under load; causation is structurally inexpressible (independent series, no
+  per-delta→actor field). `done`
+- A new `attributionClass: isolated | shared-world` honesty axis + verify FAIL-CLOSED on the
+  required/forbidden `attributionLimits` sets + a concurrency-on-pass gate (a passed concurrent
+  run must show real overlap AND a state delta coincident with it). `getHost` URLs are
+  internet-reachable → the route is gated (verify) to synthetic+seeded subjects; the raw URL is
+  digest-only in evidence. `done`
+- **LIVE-PROVEN (0.10.1):** a kept live receipt ran 3 personas concurrently against ONE
+  getHost-exposed synthetic plane — all 3 passed, all 3 lane-windows overlapped on the real clock,
+  the shared stateSeries evolved under load, N+1=4 sandboxes reclaimed by id, verify ok
+  (`docs/goals/shared-world-topology/receipts/concurrent-live-rung-2026-06-17.md`). One trial =
+  phase-change proof, not scale. The next step is the real downstream sim migration (a
+  synthetic-seeded multi-role app in the adopter's domain). Per-action causation,
+  cross-sandbox concurrency beyond getHost, and #108 PII/PHI remain out of scope.
+- shared-world (sequential AND concurrent) now also accepts `subject.source: local-tree` alongside
+  `clone`: the ONE subject sandbox packs the operator's own working tree instead of cloning,
+  reusing `provisionLocalTreeSubject` from the local-tree keystone (0.14.0). Provenance carries
+  `archiveSha256` (the pin - one archive per run, so no per-lane unanimity math applies) plus
+  host-side commit/dirty when the packed root is a git work tree; local-tree has no repo/publicRepo
+  field. The N actor desktops on the concurrent route still drive the harness-minted getHost URL
+  exactly as before; only the subject's provisioning + provenance source changed. The multi-origin
+  design (`docs/goals/multi-origin-shared-world/design.md`) remains a separate, still-held
+  downstream slice. `next patch`
+
+Adopter-driven engine features (0.11.0; surfaced by real bespoke-sim migrations):
+
+- `execution.desktop.template` — run a lab on a CUSTOM E2B desktop image (name/ID) instead of the
+  stock `desktop` template, threaded to `Sandbox.create(template, opts)` via one
+  `createDesktopSandbox` seam across every desktop route (cua single+fan-out, sequential +
+  concurrent shared-world subject+actors). Absent == the byte-stable stock-template call; recorded
+  as `RunBundle.desktopTemplate`. Lets a Node/bun/DB-bearing adopter image run without
+  installing the runtime per lane. `done`
+- `humanish observe --run <id>` — serves a run's Observer over `http://127.0.0.1:<port>` (loopback
+  only, path-traversal-guarded to the run dir, `/`->`/observer/index.html`) instead of `file://`,
+  so browsers/automation can open it and artifact links resolve. `done`
+
+Patch hardening (0.11.1):
+
+- concurrent shared-world review now fails closed when any actor lane records a failed terminal
+  trace; a lane can remain evidence without making the aggregate review green. `done`
+- scripted-browser labs can provision a single cloned synthetic subject, expose it through a
+  tokenless sandbox host, and drive deterministic scripted steps while persisting only public-safe
+  provenance and host digests. `done`
+
+Adopter-driven roster/readback ergonomics (0.12.0):
+
+- Lane grouping metadata (`actorType`, `surface`, `caseGroup`) is adapter-owned and projected into
+  Observer `laneGroups[]` plus stream labels, so downstream projects can group simulated users
+  without teaching Humanish private role names. `done`
+- `actors[0].roster[]` is compact authoring sugar for repeated lane groups. The parser expands it
+  into deterministic `lanes[]` (`<group.id>-01`, `<group.id>-02`, ...) before the engine runs, so
+  the runtime and run bundle keep one normalized lane shape. `done`
+
+Provenance hardening (0.12.1):
+
+- Clone-subject provenance now refreshes after successful provisioning phases, so `subject.commit`
+  records the served subject HEAD rather than only the initial clone HEAD. This preserves truthful
+  run-bundle provenance when an adopter's install/provisioning step checks out the exact revision to
+  test. `done`
+
+Adapter artifact evidence (0.12.15):
+
+- Browser/shared-world adapter hooks may now write product/state proof files under the ignored run
+  directory and return namespaced `humanish.adapter-artifact.v1` references. Core validates only the
+  generic reference shape and local-path safety, Observer links the artifacts, and `verify` fails
+  closed if a referenced file disappears. The payload schema and product nouns stay in the adapter's
+  namespace. `done`
+
+Evidence hygiene and readback polish (0.12.16):
+
+- Browser-backed lanes launch Chromium with shared evidence-hygiene defaults (first-run/update
+  background surfaces suppressed, extensions/sync/component update disabled, password/autofill
+  profile prompts disabled) so screenshots prefer product pixels over browser chrome. `done`
+- Run-bundle producers now use percent-scale simulation progress consistently: terminal states
+  serialize as `100`, and only true in-progress shared-world snapshots serialize partial progress.
+  This keeps Observer status pills from rendering completed runs as low-percentage complete states.
+  `done`
+- Verify results now separate valid local evidence from public-promotable evidence with
+  `shareSafety.status`. Raw full-fidelity screenshot runs remain valid local proof
+  (`local_only`), while feedback draft/issue commands require `share_ready` and fail
+  closed with structured reasons. `done`
+
+Attached CUA live Observer (next patch):
+
+- Plain computer-use labs now honor the same attached `onObserverReady` lifecycle as shared-world
+  labs: a live CUA run writes an in-progress bundle before actor sessions complete, loopback
+  `serveObserver` can hydrate desktop stream iframes while actors are still running, and stream auth
+  URLs remain runtime-only through the Observer WeakMap rather than persisted into `run.json` or
+  `observer-data.json`. `done`
+
+Local working-tree subject + operator observability (0.14.0):
+
+- `subject.source: local-tree` packs the lab resolution cwd on the host (git-aware
+  enumeration honoring `.gitignore` and including uncommitted work, an always-on
+  non-overridable secrets denylist, symlinks stored never dereferenced, one
+  enumeration driving both the tar file list and the digest), uploads the
+  once-per-run archive into each lane's desktop sandbox, extracts into the subject
+  dir, and reuses the clone route's install/build/state/start/probe pipeline
+  unchanged. Provenance pins the tree by `archiveSha256` (a dirty tree cannot be
+  commit-pinned) plus host-side commit/dirty; `verify` fails closed on a live
+  local-tree bundle without a well-formed pin. Live-proven twice with kept
+  receipts: a dirty synthetic fixture and this repo packing itself
+  (`docs/goals/local-tree-subject/receipts/`). `done`
+- Subject provisioning phase events: started/completed boundaries for
+  clone/upload/extract/install/build/serve/readiness/seed-step phases stream to
+  stderr by default (injectable via `CuaActorLabHooks.onPhase` /
+  `SharedWorldLabHooks.onPhase`) and the completed trail persists into
+  `bundle.events`; a single-lane provisioned boot is never silent again. `done`
+- Truthful CLI envelopes at the command boundary: any uncaught action error emits
+  one structured `humanish.cli-response.v1` envelope (never a raw stack trace under
+  `--json`, never a second stdout document after a flushed envelope), `humanish runs`
+  gained a real failure branch, and `doctor` failure now exits 2 like every other
+  structured command (behavioral change). `done`
+
+### 6. Lab Manifest Shape
+
+Make reusable simulations feel like source artifacts, not hardcoded command
+branches.
+
+Minimum acceptance:
+
+- `humanish/labs/*.yaml` is the committed lab source convention;
+- `.humanish/labs/*.yaml` and `.humanish/local/labs/*.yaml` are ignored local
+  overlays;
+- `humanish watch [lab]`, `humanish lab list`, `humanish lab inspect <lab>`, and
+  `humanish lab run <lab>` are supported;
+- `--env-file <path>` loads local values for the current command without
+  persisting values into artifacts;
+- maintainer dogfood labs such as `oss` are examples, not the canonical
+  consumer taxonomy.
+
+### 7. OSS Lab Health Readback
+
+Make the maintainer `oss` lab report nested lane health back into the
+top-level Observer instead of relying on a human watching the desktops.
+
+Minimum acceptance:
+
+- each lane records setup status; `done`
+- each lane records target app status/URL or blocker; `done`
+- each lane records nested Observer presence; `done`
+- each lane records nested verification status or blocker; `done`
+- each lane records setup-quality filesystem evidence and Observer can inspect
+  it; `done`
+- top-level Observer updates lane verdicts from evidence; `done`
+- feedback candidates are derived from setup-quality/actor evidence; `done`
+- Codex app-server actor telemetry is persisted as redacted trace, event, and
+  transcript artifacts; `done`
+- each lane receives a meaningful-use score over setup, filesystem, nested
+  Humanish proof, actor activity, product surface, and feedback; `done`
+- provider-backed nested app-url proof now drives a bounded two-step
+  desktop/mobile browser persona journey in a headed E2B lane; `done`
+- app-specific executable browser steps can now be authored under
+  `humanish/scenarios/*.yaml` and are summarized into top-level nested proof
+  evidence; `done`
+- repeated public app/tool headed proofs with app-specific manifests have passed
+  against two public targets; `done`
+- next gap: richer multi-step product journeys and broader multi-persona
+  matrices.
+
+## Non-Goals
+
+Do not make these default behavior:
+
+- live provider spend;
+- GitHub API mutation;
+- hosted queues, databases, or webhooks;
+- production deploys;
+- real customer/user/patient data;
+- private screenshots or raw transcripts;
+- private upstream artifacts.
+
+Maintainer-only tooling can exist later, but it must be opt-in, token-explicit,
+and dry-run-first.
+
+## Drift Alarms
+
+Stop and correct course if:
+
+- docs start depending on chat memory;
+- Observer gets prettier without stronger evidence;
+- feedback drafts imply product proof from synthetic contract proof;
+- tests pass while generated artifacts are not inspectable;
+- actor setup/use trials produce findings that never become feedback candidates;
+- live labs require private infrastructure to look impressive;
+- package docs link to files that are not shipped;
+- public-safety gates become optional.
+
+## Best Next Work
+
+The next most useful engineering slice is repeated agent dogfood against real
+apps and tools, while preserving the public-safety boundary:
+
+- public/open-source fixture proof for publishable examples;
+- private maintainer dogfood through the repo-only public-safe packet, which is
+  intentionally not part of the npm payload, at
+  [`docs/goals/private-repo-agent-dogfood/goal.md`](https://github.com/danielgwilson/humanish/blob/main/docs/goals/private-repo-agent-dogfood/goal.md);
+- then richer provider-backed app-specific browser persona manifests.
+
+That sequence keeps the package honest: first prove a new maintainer or agent
+can start, then prove Humanish can observe real product behavior, then use the
+failures to improve the harness.

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

@@ -0,0 +1,135 @@
+# 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.
+
+## Invariants
+
+True on every route, enforced in code, never overridable by config. A feature that cannot
+satisfy these does not ship; a third-party extension that cannot satisfy these does not
+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
+   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
+   PUBLISH/VERIFY boundary, not capture: a local run's text artifacts are scrubbed of
+   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
+   protection is the init-scaffolded `.gitignore` plus their own review. To share a bundle
+   as-is, set `policies.redactScreenshots: true` (blurs
+   at capture); a redact-on-export step for already-captured raw bundles is planned, not yet
+   shipped. (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
+     (gitignored) regardless.
+2. **Actors only drive harness-minted URLs.** A model with input control (mouse, keyboard,
+   terminal) is only ever pointed at a URL the harness itself issued or validated under a
+   declared policy (loopback entry, provisioned subject, declared external target). Never an
+   arbitrary URL from unvalidated input.
+3. **Live spend is explicit.** No configuration default, omission, or fallback may cause
+   provider or sandbox spend. Spend requires an affirmative declaration (`scenario.mode:
+   live`, an env opt-in gate for spend-bearing tests).
+4. **Evidence verifies fail-closed.** A run bundle that cannot pass verification (schema,
+   redaction status, artifact presence, public-safety scan) is a failed run, even when the
+   session "worked." The gate applies to the harness's own error reports.
+5. **Provenance is recorded or its absence is declared.** Every bundle states what the
+   subject was (commit, image, fixture, or an explicit "unpinned" marker). Evidence that
+   cannot say what it measured cannot support a decision.
+6. **Claims match mechanism.** A config field that is parsed but not consumed warns; a
+   document that overstates behavior is a defect; an evidence artifact never claims a
+   stronger evidence class than its actor and scenario can support.
+7. **Reclamation is by exact created id, never account-wide enumeration.** A route that
+   creates a provider resource (an E2B sandbox, for example) tracks the exact id it created and
+   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.
+   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.
+
+## Defaults
+
+Right most of the time, overridable with declared friction (an explicit config field, an
+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` |
+| 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. |
+| 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) |
+| 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 |
+
+## 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
+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
+> never. Blast radius is bounded by key scoping and budgets, not by hoping.**
+
+Consequences:
+
+- A computer-use provider loop runs outside → forwarding env into its sandbox is rejected.
+- 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.
+
+Placement is registry metadata per actor type, enforced by the engine — not a vibe.
+
+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
+  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.
+
+## The capture-vs-publish rule (worked example)
+
+"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 +
+the `.humanish/` gitignore + the binary-asset scan. Two routes, opposite policies, identical
+threat. The corrected principle:
+
+> **A default's enforcement point belongs at the PUBLISH/VERIFY boundary, never at
+> CAPTURE/RUNTIME — unless capture-time is the only physically possible point.**
+
+Consequences:
+
+- Screenshots are retained **raw and full-fidelity** by default, in gitignored `.humanish/`.
+  `policies.redactScreenshots: true` blurs at capture for a share-as-is bundle; a
+  redact-on-export step for already-captured raw bundles is planned (not yet shipped). The
+  frame sent to the provider is always raw regardless — 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.
+
+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?"