humanish 0.0.1 → 0.15.1

package/docs/architecture/oss-lab-poc.md

@@ -0,0 +1,250 @@
+# Maintainer OSS Meta-Lab
+
+Date: 2026-06-01
+
+Status: implemented as an experimental repo-owned lab manifest plus
+compatibility aliases.
+
+Safety amendment (2026-07-14): beginning with `0.15.1`, the bundled `oss`
+manifest is a contract-only dry-run. A direct live OSS meta-lab request fails
+with `HUMANISH_OSS_META_LIVE_ISOLATION_REQUIRED` before callbacks, filesystem
+or network side effects, credential forwarding, or provider launch. The
+historical design and evidence description below is preserved as a record; it
+is not current execution guidance. The separate `oss-smoke` clone/discard lane
+remains available for public repositories.
+
+## Decision
+
+`humanish/labs/oss.yaml` is this repo's authorized-repo meta-simulation
+dogfood loop. It is intentionally a lab manifest, not the canonical consumer
+shape. Consumer projects should author their own `humanish/labs/*.yaml` files
+and run them with `humanish watch <lab>` or `humanish lab run <lab>`.
+
+The lab should feel like `humanish watch`: it opens the Observer and, for human
+output, keeps the shell attached. Its top-level Observer is an
+Observer-of-Observers: each lane represents a headed E2B desktop assigned to a
+GitHub `owner/repo` slug. Inside each desktop, the bootstrap clones the repo,
+gets it into local dev mode where feasible, installs and initializes Humanish,
+runs nested Humanish proof commands, starts the target app when a runnable
+script is present, opens desktop/mobile app windows plus the nested Observer in
+the E2B browser, and starts a nonblocking Codex actor attempt.
+
+The previous clone/discard proof loop remains useful, but it is now explicitly
+named `humanish/labs/oss-smoke.yaml`.
+
+## Commands
+
+Main operator path:
+
+```bash
+humanish watch oss
+humanish lab run oss
+humanish lab run oss --repos CorentinTh/it-tools,drawdb-io/drawdb,maciekt07/TodoApp,lissy93/dashy
+humanish lab run oss --repo CorentinTh/it-tools --repo drawdb-io/drawdb --count 4
+```
+
+Agent/CI contract path:
+
+```bash
+humanish lab run oss --dry-run --json --no-open
+```
+
+Disposable clone smoke path:
+
+```bash
+humanish lab run oss-smoke
+humanish lab run oss-smoke --limit 1 --keep
+```
+
+Local dogfood shortcuts:
+
+```bash
+pnpm humanish:lab:oss
+pnpm humanish:lab:oss:ci
+pnpm humanish:lab:oss:smoke
+```
+
+## Repo Selection
+
+The default public targets are product-like, locally runnable apps/tools:
+
+- `CorentinTh/it-tools`
+- `drawdb-io/drawdb`
+- `maciekt07/TodoApp`
+- `lissy93/dashy`
+
+Target selection should minimize distance from a real user-facing journey.
+Good defaults expose an app, CLI, or agent-facing tool that can be tried out of
+the box, preferably with a local dev script and no account setup. Libraries,
+frameworks, starters, and infrastructure packages belong only in scenarios that
+explicitly test developer experience. They are poor defaults for proving
+Humanish as a user-simulation harness because they add another abstract setup
+layer before any product behavior is visible.
+
+`--repos` accepts a comma-separated list. Repeated `--repo` is also supported.
+If `--count` is larger than the repo list, assignments cycle through the repo
+pool. Inputs must be GitHub `owner/repo` slugs. Arbitrary URLs, local paths,
+tokens, and SSH remotes are rejected. Private repos are maintainer-only and
+require an authorized `GH_TOKEN` or `GITHUB_TOKEN` at runtime; no token value is
+written to committed source or public issue text.
+
+## Private Product Labs
+
+Private products can be used for local maintainer dogfood, but they must stay
+out of the public package surface. Do not commit private repo names as defaults,
+fixtures, screenshots, README examples, npm assets, skill examples, or issue
+draft text.
+
+The safe local shape is:
+
+```bash
+humanish watch .humanish/labs/private-app.yaml --env-file .humanish/local/provider.env
+```
+
+with an authorized runtime GitHub token and default repo redaction enabled.
+Do not pass `--no-redact-repos` for a private target. Public receipts for
+those runs should say `authorized private app target` and point only to ignored
+local artifact paths, redacted statuses, and verifier results. Never publish
+private screenshots, logs, app URLs, source snippets, branch names, issue
+names, stream URLs, or operational details.
+
+## Runtime Shape
+
+The meta-lab writes ignored local Observer evidence:
+
+```text
+.humanish/
+  runs/<oss-meta-run-id>/
+    run.json
+    review.json
+    review.md
+    events.ndjson
+    observer/
+      index.html
+      observer-data.json
+```
+
+Each stream lane records:
+
+- assigned repo slug for public runs, or a redacted lane label for token-backed
+  maintainer/private runs;
+- whether a live E2B desktop stream exists; auth-bearing stream URLs are
+  runtime-only for the attached Observer server and are not persisted;
+- target app URL/status when a runnable script becomes HTTP-ready inside the
+  sandbox;
+- nested Observer presence and nested verification status;
+- headed desktop visual-window status and browser window count;
+- Codex actor status, optionally moved before deterministic setup with
+  `HUMANISH_OSS_META_ACTOR_FIRST=1` and required through
+  `HUMANISH_OSS_META_REQUIRE_ACTOR=1`;
+- setup-quality filesystem evidence: shallow tree, Humanish setup checks,
+  package scripts, study-quality rating, and allowlisted previews for public
+  runs;
+- public-safe remote bootstrap log tail;
+- public-safe gaps and events.
+
+The current implementation launches live E2B desktop streams when
+`E2B_API_KEY` and `OPENAI_API_KEY` are present, overlays those stream URLs only
+in the attached Observer server, and marks missing key or launch failures
+in-lane. It also packs the local Humanish package, uploads it into each sandbox,
+raises a visible bootstrap terminal, clones the assigned repo, runs nested
+Humanish setup and proof commands, starts the target app, opens desktop/mobile
+app windows, opens the nested Observer in the sandbox browser, arranges visible
+browser windows for screenshot proof, and starts the Codex actor attempt. By
+default the actor remains nonblocking and runs after deterministic readback; with
+`HUMANISH_OSS_META_ACTOR_FIRST=1`, the actor attempts setup/use before
+deterministic validation; with `HUMANISH_OSS_META_REQUIRE_ACTOR=1`, the bootstrap
+waits up to `HUMANISH_OSS_META_ACTOR_TIMEOUT_MS` for terminal actor readback and
+will not mark the lane passed unless the actor exits cleanly.
+
+When the remote bootstrap completes, the host persists a local
+`setup-quality/<stream>-setup-quality.json` artifact. The Observer Files tab can
+render it inline from the served Observer. Static `file://` observers keep the
+artifact link openable but do not hydrate it inline. Token-backed/private runs
+suppress raw file previews by default while preserving the setup checks and
+tree shape. They also preserve `studyQuality` structural signals so an actor
+that merely installs Humanish receives a `ceremonial` rating instead of being
+treated as successful user-study leverage.
+
+The live desktop substrate is an optional peer dependency. Install it in the
+project that runs live labs:
+
+```bash
+npm i -D @e2b/desktop
+```
+
+Remaining substrate work: upgrade the nested `--app-url` browser proof into
+provider-backed personas that actually drive multi-step target-app journeys,
+and live-prove actor-first setup/use, not only deterministic bootstrap readback.
+
+## Smoke Harness Runtime
+
+`humanish lab run oss-smoke` shallow clones lightweight public GitHub repos into
+ignored runtime state, applies Humanish setup inside each throwaway clone, runs
+the synthetic four-lane proof path, verifies the generated bundle, records
+git-status evidence, writes an ignored report, and removes cloned repos by
+default.
+
+```text
+.humanish/
+  lab/oss/<run-id>/
+    report.json
+    report.md
+  tmp/oss-lab/<run-id>/
+    repos...      # removed by default
+```
+
+Each cloned repo receives disposable uncommitted changes:
+
+- `humanish/` source starter files;
+- `.humanish/` runtime state;
+- `.gitignore` updates;
+- `package.json` script updates;
+- synthetic run/Observer evidence under the clone's ignored `.humanish/`.
+
+The clone is removed unless `--keep` is passed. The host report remains under
+ignored `.humanish/lab/oss/<run-id>/`.
+
+## Safety Rules
+
+- GitHub `owner/repo` slugs only.
+- Private repos require an authorized runtime token. Token-backed runs redact
+  repo labels in durable artifacts by default and must not appear in committed
+  fixtures, docs examples, public issue text, or published media.
+- pnpm dependency build scripts may be allowed only inside the disposable E2B
+  lab so target app surfaces can start. Never use this as a host install
+  default.
+- No credential prompts; smoke clone calls set `GIT_TERMINAL_PROMPT=0`.
+- No commits, pushes, branches, tags, GitHub API mutation, deploys, or issue
+  filing.
+- Do not write key values into committed `humanish/` source.
+- Do not emit PII, PHI, raw private transcripts, private screenshots, secrets,
+  keys, or private upstream artifacts.
+
+## What This Proves
+
+The meta-lab proves the operator control surface and artifact contract for
+watching multiple Codex/E2B setup attempts at once. The live path now detects
+E2B desktop fanout, visible bootstrap terminals, local-package upload,
+disposable authorized-repo setup, target app HTTP readiness when a runnable
+script is present, headed browser-window layout, nested live `--app-url`
+desktop/mobile browser proof when the target app runs, nested Observer opening,
+and top-level lane completion from remote evidence. It does not yet prove a
+general provider-backed multi-step target-app persona runtime.
+
+The smoke harness proves first-run Humanish package compatibility against
+arbitrary public JavaScript repositories:
+
+- setup can patch real package.json files without committing;
+- generated `humanish/` source can coexist with external repo layout;
+- ignored `.humanish/` runtime proof can be generated;
+- the Observer can render from those disposable proofs;
+- verification passes before the clone is discarded.
+
+Neither path may claim private product behavior proof without live, redacted,
+public-safe evidence.
+
+Feedback candidates are derived from this evidence when a lane records concrete
+setup-quality gaps, ceremonial/absent study quality, or actor-reported Humanish
+CLI blockers. `humanish feedback` uses those candidates before falling back to
+generic dry-run follow-up drafts.

package/docs/architecture/project-layout.md

@@ -0,0 +1,166 @@
+# Project Layout Contract
+
+Date: 2026-06-01
+
+Status: target layout for apps that install `humanish`.
+
+## Decision
+
+Use two roots:
+
+```text
+humanish/   # committed source of simulation intent
+.humanish/  # ignored runtime state, evidence, local overlays, and secrets
+```
+
+Do not gitignore all Humanish state. Labs, personas, scenarios, policies,
+adapters, coverage maps, and review vocabulary are the harness. They must be
+versioned, reviewed, and reproducible from a clean clone.
+
+Do not commit run bundles, raw screenshots, browser traces, transcripts,
+draft issue bodies before verification, local auth, local overrides, or secrets.
+
+## Committed Source Plane
+
+`humanish/` is the project-owned simulation contract:
+
+```text
+humanish/
+  README.md
+  config.ts
+  personas/
+    synthetic-new-user.yaml
+    skeptical-power-user.yaml
+  scenarios/
+    first-run-smoke.yaml
+    onboarding-regression.yaml
+  labs/
+    first-run.yaml
+  policies/
+    redaction.yaml
+    network.yaml
+    credentials.example.yaml
+  adapters/
+    app.ts
+  review/
+    vocabulary.yaml
+    milestones.yaml
+  coverage-map.md
+  coverage-matrix.md
+  fixtures/
+    synthetic-login-state.json
+```
+
+## Humanish Format Stack
+
+Use formats based on who edits the file and how it is consumed:
+
+- `.yaml` for human-authored Humanish source: personas, scenarios, policies,
+  labs, review vocabulary, and review milestones. Prefer `.yaml` over `.yml`
+  for Humanish-owned source files.
+- `.ts` for executable project integration: `humanish/config.ts`, adapters,
+  route catalogs, app launch plans, and logic that benefits from imports or
+  type checking.
+- `.json` for generated machine artifacts and synthetic fixtures: run bundles,
+  observer data, review JSON, latest/history pointers, and fixture records.
+- `.ndjson` for appendable event or transcript streams.
+- `.yml` is acceptable for ecosystem files that conventionally use it, such as
+  `.github/workflows/*.yml`; do not use `.yml` for Humanish-owned authored
+  source.
+
+Do not convert personas or scenarios to JSON because parser implementation is
+easier. Keep authored simulation intent readable, then validate it through
+schemas and CLI checks. TOML is not part of the current Humanish stack; add it
+only if a concrete scalar global-config need appears that is better served by
+TOML than YAML, TypeScript, or JSON.
+
+Committed files must be public-safe:
+
+- synthetic personas only;
+- synthetic or redacted fixtures only;
+- env var names only, never values;
+- no PHI, PII, keys, tokens, raw private transcripts, real screenshots, real
+  customer data, or real patient data.
+
+Changing a scenario or persona is equivalent to changing a test. It should be
+visible in PR review.
+
+## Ignored Runtime Plane
+
+`.humanish/` is local/generated state:
+
+```text
+.humanish/
+  runs/
+    <run-id>/
+      run.json
+      review.md
+      review.json
+      observer/
+      screenshots/
+      traces/
+      terminal/
+      feedback/
+  cache/
+  tmp/
+  logs/
+  labs/
+  local/
+    labs/
+    personas/
+    policies/
+  secrets/
+```
+
+Default `.gitignore` entry:
+
+```gitignore
+.humanish/
+.env*
+```
+
+If a target repo already uses `.env.example`, preserve its existing exception.
+
+## Local Overrides
+
+When a team needs private local personas or credentials, use ignored overlays:
+
+```text
+.humanish/local/personas/*.yaml
+.humanish/local/policies/*.yaml
+.humanish/local/labs/*.yaml
+.humanish/labs/*.yaml
+.humanish/secrets/*
+```
+
+Committed `humanish/labs/*.yaml` should be useful to anyone with a clean clone.
+Ignored `.humanish/labs/*.yaml` and `.humanish/local/labs/*.yaml` are for
+machine-specific or private dogfood labs. The CLI should warn that local
+overlays cannot be used for reproducible CI or public issue drafts unless
+redacted into committed synthetic equivalents.
+
+## CI And Reproducibility
+
+CI should reproduce proof from committed inputs:
+
+- app commit;
+- `humanish` version;
+- `humanish/config.ts`;
+- scenario and persona catalog;
+- lab manifest;
+- policy files;
+- synthetic fixtures;
+- declared env var names.
+
+CI should store generated run bundles as artifacts, not commit them.
+
+## Why Not `.humanish/` For Everything?
+
+A fully ignored `.humanish/` makes setup feel tidy, but it hides the product
+contract. Future agents and contributors cannot see what the harness is meant
+to prove, CI cannot validate it from a clean clone, and PR review cannot catch
+weakened personas or dropped hard paths.
+
+A partially tracked dotdir is possible but worse UX. Dotdirs read as local,
+editors hide them, and negated gitignore rules are easy to break. A visible
+`humanish/` source root plus ignored `.humanish/` runtime root is clearer.

package/docs/architecture/state-driven-executor.md

@@ -0,0 +1,203 @@
+# State-driven executor (the `CuaExecutor` port)
+
+Date: 2026-06-15
+
+Status: shipped (PR1 of issue #148). The library path (a custom executor + a
+non-vision provider, driven through the lab with NO E2B and NO vision) is
+implemented and proven. A config-only deterministic lane and a
+`subject.contract.ref` JS-module loader are deferred (see "Deferred", below).
+
+## What this is
+
+The computer-use (CUA) loop in [`src/computer-use.ts`](../../src/computer-use.ts)
+is provider- and substrate-agnostic by design: the model lives behind a
+`CuaProvider` port and the thing being driven lives behind a `CuaExecutor` port.
+You do not have to drive a screen with a vision model. You can point the loop at
+**an already-running local app** and drive it through that app's **in-process
+JavaScript automation contract** (e.g. `window.app.getState()`,
+`sendChat(text)`, `dispatch(action)`, `navigate(target)`), using `getState()` as
+the progress signal instead of a quantized screenshot — keeping humanish's
+composition (personas, the Observer, the normalized `ActorTrace` evidence
+bundle, redaction, and the friction / no-progress loop).
+
+This is the "plural harnesses / transport-agnostic" intent of
+[`actor-contract.md`](./actor-contract.md), made into a supported seam.
+
+## The port
+
+```ts
+interface CuaExecutor {
+  observe(): Promise<CuaObservation>;   // capture current state
+  execute(action: CuaAction): Promise<void>; // perform one action
+}
+
+interface CuaObservation {
+  screenshot?: Buffer;                  // OPTIONAL — a state executor omits it
+  stateSignature: string;              // REQUIRED — the fallback progress key
+  appState?: Record<string, unknown>;  // structured state; preferred for progress
+}
+```
+
+- **`screenshot` is optional.** A non-vision (state) executor omits it. The loop
+  persists no screenshot that turn; `counts.screenshots` stays 0, so the trace's
+  `redaction.screenshots` resolves to `"n/a"`. No fabricated `Buffer.alloc(0)`
+  ever reaches disk. (A vision executor still returns a frame, exactly as before.)
+- **`stateSignature` is still required.** Derive it from your own state — e.g.
+  `JSON.stringify({ route, turn, modal })`. It is the canonical fallback progress
+  key when `appState` is absent. It is never written to the trace as text.
+- **`appState` is the preferred progress input.** When present, the loop's
+  friction / no-progress detection keys off a deterministic, sorted-key,
+  depth/length-capped projection of it (`stableProgressKey`) rather than the
+  signature. So a route change drives "progress" even when a quantized signature
+  would not, and key insertion order can never fabricate a delta.
+
+### `stateSignature` vs `appState`
+
+Either is enough on its own. `appState` is preferred because `getState()` is a
+far more reliable progress signal than a quantized screenshot signature on a
+graphically dense (pixel-art) UI. `stableProgressKey(appState)`:
+
+- sorts object keys (order-independent — shuffled keys ARE NOT progress);
+- caps depth, key count, array length, string length, and total output;
+- never throws on a cyclic or huge `appState` — it degrades to a bounded value
+  (cycles become `"[Circular]"`, over-cap nodes become markers). This is
+  correctness-load-bearing: a hostile or merely large state blob cannot crash the
+  loop.
+
+## You need a NON-vision provider too
+
+Swapping the executor is not enough. The default OpenAI computer-use provider is
+**vision-based**: it sends the screenshot as the `computer_call_output`, so a
+screenshot-less observation would crash it. A genuinely non-vision flow swaps
+**both** the executor (the state contract) **and** the provider (a brain that
+reasons over app state).
+
+**Provider-authoring contract:**
+
+- A **vision** provider MUST set `requiresFrame: true` (the OpenAI provider does).
+  When a `requiresFrame: true` provider is handed a screenshot-less observation,
+  the loop fails closed with a structured `harness_error` per turn — not a silent
+  crash, not a false pass.
+- A **state-reasoning** provider omits `requiresFrame` (defaults falsey) and reads
+  `req.observation.appState`.
+
+`requiresFrame` defaulting to falsey is a known third-party-author footgun (a
+vision provider that forgets to set it would get a blank-frame crash instead of a
+clean verdict). This slice accepts it because only one vision provider exists
+today, and records it here.
+
+## `appState` is RUNTIME-ONLY (not evidence, in this slice)
+
+`appState` is an in-memory progress-comparison input, exactly like
+`stateSignature` (which is itself never written as text). It is **never** copied
+into any `ActorTraceItem`, reason, id, or count, and is **never** persisted to the
+trace. Only the derived progress key is computed in-memory and discarded.
+
+Why: the published-evidence scan catches only secret-*shaped* patterns. A
+structured app blob (ids, free-form state, possibly user chat or shapeless
+tokens) is exactly the "value has no shape" gap that pattern redaction cannot
+close. So this slice does not treat `appState` as an evidence surface at all.
+
+The bundle is self-describing about it (invariant 6): when a state executor
+surfaces `appState`, the trace's `redaction.notes` declares that app state was
+observed each turn to drive progress detection and was NOT written to the trace.
+
+A future "appState in evidence" slice MUST route a stringified projection through
+`redaction.redactText` (and the lab's `scrubText`) AND cap / whitelist fields
+before persisting — pattern + literal redaction alone cannot sanitize an
+arbitrary blob.
+
+## Provenance is honestly UNPINNED (invariant 5)
+
+An already-running local dev server cannot be commit-pinned. The bundle does not
+silently omit a subject block — it DECLARES the absence: `subject.source:
+app-url` with `state.provenance: "undeclared"` (the app-url "absence declared"
+marker), and a `cua-lab.subject.declared` event that states the entry is a local
+dev server driven in-process, caller-provisioned and UNPINNED, with no E2B
+desktop created.
+
+## Two entry points
+
+### 1. Bare `runComputerUseLoop` (lowest level)
+
+Implement `CuaExecutor.observe()/execute()`, derive `stateSignature`/`appState`
+from your own state, pair it with a non-vision `CuaProvider`, and call
+`runComputerUseLoop`. You own the bundle/redaction wiring.
+
+### 2. `runLab` + `buildExecutor` / `buildProvider` (keeps the composition)
+
+The supported library path. It keeps personas, the Observer, the evidence
+bundle, redaction, and the friction loop, while skipping E2B entirely:
+
+```ts
+import { runLab, parseLabConfig, type CuaExecutor, type CuaProvider } from "humanish";
+
+// local-app YAML (shareable; fails closed without hooks):
+//   schema: humanish.lab.v2
+//   id: pixel-bae-state
+//   subject: { source: local-app, appUrl: http://localhost:5173 }
+//   actors: [{ type: openai-computer-use, persona: pixel-pat, mission: "…" }]
+//   scenario: { mode: live }
+const parsed = parseLabConfig(yaml);
+if (!parsed.ok) throw new Error(parsed.error.message);
+
+const outcome = await runLab(parsed.config, {
+  cwd: process.cwd(),
+  dryRun: false,
+  cuaHooks: {
+    buildExecutor: async ({ appUrl }) => createAppContractExecutor(bridge, appUrl),
+    buildProvider: async () => createStateBrain(),
+  },
+});
+// outcome.backend === "cua"; outcome.result.sandbox === undefined (NO E2B); the
+// trace's provider id is the injected brain's id.
+```
+
+When `cuaHooks.buildExecutor` is set, `runCuaActorLab` takes a branch that NEVER
+loads the E2B module, creates a sandbox, runs `prepareDesktop`, provisions a
+clone, opens a browser, or starts a stream. `sandboxId`/`streamUrl` stay
+undefined, so `result.sandbox` is omitted — the verifiable "no E2B SDK call"
+proof.
+
+Two boot-time fail-closed guards (both BEFORE any key check, so a CLI invocation
+never sees a misleading `KEYS_MISSING` first):
+
+- `HUMANISH_CUA_LAB_EXECUTOR_NO_PROVIDER` — `buildExecutor` without `buildProvider`
+  (a state executor MUST be paired with a non-vision provider). `buildProvider`
+  ALONE is allowed — that is just a model swap on the normal E2B route.
+- `HUMANISH_CUA_LAB_LOCAL_APP_NO_EXECUTOR` — a `subject.source: local-app` config
+  run with no `buildExecutor` hook (there is no built-in in-process driver yet).
+  A structured error, never a desktop attempt.
+
+Key gating is route-aware: the in-process route uses the caller's OWN model and
+executor, so no `OPENAI_API_KEY`/`E2B_API_KEY` is required.
+
+## A note on `appState` typing
+
+`CuaObservation.appState` is `Record<string, unknown> | undefined` under the
+repo's strict flags (`exactOptionalPropertyTypes`, `noUncheckedIndexedAccess`).
+A value typed as an `interface` does NOT satisfy `Record<string, unknown>`
+(interfaces have no implicit index signature), and a direct `as Record<...>` cast
+on an interface-typed value is rejected. Use one of:
+
+- a `type` alias for your state shape (type aliases get the index signature);
+- a spread into a fresh object literal (`{ ...state }`); or
+- `as unknown as Record<string, unknown>`.
+
+Read every optional field defensively, and spread-omit optional fields
+(`...(x === undefined ? {} : { x })`) rather than assigning `undefined`.
+
+## Deferred (tracked, not shipped here)
+
+- **PR2 — a config-only deterministic `state-contract` lane.** A registered,
+  model-free lane driving a built-in `window.app.*` bridge over the existing
+  `ScriptedPageLike.evaluate` primitive + a YAML step program, `scenario.mode:
+  live` gating actuation. It would be deterministic step replay, NOT
+  `runComputerUseLoop`, and must not overclaim friction-loop reuse.
+- **PR3 — a `subject.contract.ref` JS-module loader.** A config-referenced module
+  loaded and run in-process with full harness privileges is a genuinely NEW trust
+  surface with no precedent in this repo (the scripted lane loads only declarative
+  YAML; serve commands run isolated inside the disposable E2B sandbox). It earns
+  its place only behind its own clamping / trust / digest-pinning design.
+  pixel-bae does not need it: a library caller builds the bridge in their own
+  trusted code (entry point 2 above).