humanish 0.104.3 → 0.106.0

package/docs/architecture/terminal-product-lane.md

@@ -1,4 +1,4 @@
-# Terminal-product real-agent lane (issue #154)
+# Terminal-product real-agent route (issue #154)
 
 Date: 2026-06-16 (runtime-auth contract updated 2026-09-05)
 
@@ -8,45 +8,45 @@ cost/no-spend ledger, caps, and product scoring/feedback hooks are implemented;
 the kept 2026-07-09 live receipt verifies 15/15 checks and `share_ready` at a
 `$0` cap. That capability receipt is not adopter replacement: no deletion
 branch has yet removed the reference adopter's bespoke generic study harness.
-See the ratified goal packet
-([`docs/goals/terminal-product-lane/goal.md`](../goals/terminal-product-lane/goal.md))
+See the goal packet
+([`docs/goals/terminal-product-lane/goal.md`](https://github.com/danielgwilson/humanish/blob/main/docs/goals/terminal-product-lane/goal.md))
 for the full slice plan and the safety contract.
 
 ## What this is
 
-A lab lane for **terminal-product real-agent studies**: a real autonomous coding
+A lab route for **terminal-product real-agent studies**: a real autonomous coding
 agent (Codex) discovering and using a CLI/product from its **public surfaces
 only**, running **inside an E2B shell** with declared runtime-auth placement and
 spend/time caps, emitting durable terminal/substrate/cost/no-spend/cleanup/
 intervention proof that verifies fail-closed. This is distinct from the browser
-lanes: it is not testing whether a browser can click a local web app — it tests
-whether an autonomous agent can discover and use a CLI/product surface from
-public materials.
+routes. It tests whether an autonomous agent can discover and use a CLI/product
+surface from public materials. It does not test whether a browser can click a
+local web app.
 
-It rides the established lane-addition pattern (proven by the scripted-browser
-and local-app lanes): a new `subject.source` × `execution.target`, a routing
-predicate, a backend enum + dispatch, a registered actor with a capability lane,
+It rides the established route-addition pattern (proven by the scripted-browser
+and local-app routes): a new `subject.source` × `execution.target`, a routing
+predicate, a backend enum + dispatch, a registered actor that declares the run kind in its capabilities,
 fail-closed cross-validation, and forward-declared warnings.
 
 ## The composition
 
-| Axis | Value |
-| --- | --- |
-| `subject.source` | `terminal-product` |
-| `subject.product` | `{ name, publicSurfaces[] }` — the only world the agent sees |
-| `execution.target` | `e2b-terminal` (or absent → implied) |
-| `execution.terminal` | `{ transport: exec-stream, stdin: disabled }` |
-| `execution.runtimeAuth` | `openai-env` (default) or opt-in `openai-egress`; names-only durable evidence |
-| `execution.runtime.version` | Optional exact `@openai/codex` version; observed before keyed execution |
-| `actors[0].model` / `reasoningEffort` | Forwarded to Codex; retained as declarations, not observed provider identity |
-| `scenario.caps` | `{ maxUsd, maxJobs, maxMinutes }` — the blast-radius budget |
-| `policies` | `allowPrivateRepoAccess` / `allowProviderCredentials` / `allowPaymentCredentials` / `allowGitHubMutation`, all DEFAULT FALSE |
-| `actors[0].type` | `codex-exec` — a registered terminal actor (`keyPlacement: in-sandbox-command-scoped`) |
-| `LabBackend` | `terminal` → `runTerminalProductLab` ([`src/e2b-terminal-lab.ts`](../../src/e2b-terminal-lab.ts)) |
-
-Routing is `routesToTerminalProduct(config)` — the single source of truth that
-both `selectLabBackend` and the forward-declared-warning logic consume, mirroring
-`routesToComputerUse` / `routesToScriptedBrowser`.
+| Axis                                  | Value                                                                                                                                                     |
+| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `subject.source`                      | `terminal-product`                                                                                                                                        |
+| `subject.product`                     | `{ name, publicSurfaces[], install?, workdir?, upload? }`: the only world the agent sees                                                                  |
+| `execution.target`                    | `e2b-terminal` (or absent → implied)                                                                                                                      |
+| `execution.terminal`                  | `{ transport: exec-stream, stdin: disabled }`                                                                                                             |
+| `execution.runtimeAuth`               | `openai-env` (default) or opt-in `openai-egress`; names-only durable evidence                                                                             |
+| `execution.runtime.version`           | Optional exact `@openai/codex` version; observed before keyed execution                                                                                   |
+| `actors[0].model` / `reasoningEffort` | Forwarded to Codex; retained as declarations, not observed provider identity                                                                              |
+| `scenario.caps`                       | `{ maxUsd, maxJobs, maxMinutes }`: the blast-radius budget; `maxUsd > 0` is refused unless a `costProbe` measures spend                                   |
+| `policies`                            | `allowPrivateRepoAccess` / `allowProviderCredentials` / `allowPaymentCredentials` / `allowGitHubMutation`, all DEFAULT FALSE                              |
+| `actors[0].type`                      | `codex-exec`: a registered terminal actor (`keyPlacement: in-sandbox-command-scoped`)                                                                     |
+| `LabBackend`                          | `terminal` → `runTerminalProductLab` ([`src/routes/terminal/route.ts`](https://github.com/danielgwilson/humanish/blob/main/src/routes/terminal/route.ts)) |
+
+Routing is `routeOf` (`src/lab/plan.ts`). It sends every `terminal-product` subject to
+this route, even with an unregistered actor, so this route refuses the actor.
+`routesToTerminalProduct(config)` also feeds the forward-declared warnings.
 
 ## Repeating a terminal study with the same runtime
 
@@ -62,9 +62,9 @@ execution:
 ```
 
 An explicit version must be exact semver; tags, ranges, URLs, and extra runtime
-fields fail at parsing. Before the keyed actor command, Humanish runs an unkeyed
+fields fail at parsing. Before the keyed actor command, humanish runs an unkeyed
 `npx @openai/codex@<selector> --version` command with a 60-second deadline.
-A malformed result, nonzero exit, or requested/observed mismatch fails the lane
+A malformed result, nonzero exit, or requested/observed mismatch fails the participant
 and reclaims its owned sandbox. When the version is omitted, the probe resolves
 `latest` once and execution uses the exact version it reported.
 
@@ -72,12 +72,12 @@ and reclaims its owned sandbox. When the version is omitted, the probe resolves
 `humanish.actor-runtime.v1`: requested and observed versions, verification status,
 declared model/effort, and the usage granularity. The observed executable version
 also appears as `providerVersion`. An undeclared model stays explicitly
-`runtime_default_unobserved`; Humanish does not label the runtime name as a model.
+`runtime_default_unobserved`; humanish does not label the runtime name as a model.
 Dry runs record declarations only, in a `terminal-lab.runtime.declared` event.
 
 These settings make a study's request reproducible, but do not attest the actual
 provider model or add a provider spending limit. Codex `turn.completed` usage can
-aggregate several model requests, so Humanish does not use a declared model to
+aggregate several model requests, so humanish does not use a declared model to
 infer per-request pricing tiers or fill in unknown costs. Runtime-token costs
 and the studied product's no-spend boundary still need separate interpretation.
 
@@ -104,18 +104,18 @@ execution:
 Codex command receives the nonsecret value `humanish-egress-auth-placeholder`
 under `CODEX_API_KEY`, plus `CODEX_CA_CERTIFICATE` pointing at E2B's existing
 system CA bundle (`/etc/ssl/certs/ca-certificates.crt`) so TLS verification trusts
-the platform's proxy CA. Humanish does not disable TLS verification or download
+the platform's proxy CA. humanish does not disable TLS verification or download
 an unauthenticated CA. The sandbox receives no raw runtime key in command env, sandbox env,
 files, metadata, or captured evidence. The host still scrubs the actual key from
 output and errors, including errors during sandbox creation.
 
-This mode supports the default OpenAI endpoint only. Humanish explicitly sets
-Codex's built-in `openai` provider and `openai_base_url` to
-`https://api.openai.com/v1` for that invocation. It does not support a custom
-provider, proxy base URL, or regional endpoint under this mode. `openai-env`
-retains its existing command behavior. E2B header rules are a public-beta
-capability; the local contract is checked against the installed Desktop SDK
-(`@e2b/desktop` 2.3.3, resolving `e2b` 2.46.1).
+This mode supports the default OpenAI endpoint only. humanish explicitly sets Codex's
+built-in `openai` provider and `openai_base_url` to `https://api.openai.com/v1` for
+that invocation. It does not support a custom provider, proxy base URL, or regional
+endpoint under this mode. `openai-env` retains its existing command behavior. E2B
+header rules are a public-beta capability;
+`tests/routes/terminal/runtime-auth.test.ts` checks the local contract against the
+installed Desktop SDK (the lockfile has `@e2b/desktop` 2.4.0, resolving `e2b` 2.49.0).
 
 **The sandbox still has a spendable OpenAI proxy capability.** Every process can
 make authenticated requests to that host from sandbox creation until teardown,
@@ -146,7 +146,7 @@ and [E2B's CA installer](https://github.com/e2b-dev/infra/blob/main/packages/env
 E2B's installed
 SDK documents that transformed headers override request headers. Deterministic
 request/redaction tests do not establish live wire behavior. The [2026-09-05
-transport receipt](../goals/terminal-product-lane/receipts/2026-09-05-runtime-egress-auth.md)
+transport receipt](https://github.com/danielgwilson/humanish/blob/main/docs/goals/terminal-product-lane/receipts/2026-09-05-runtime-egress-auth.md)
 records the controlled live header/auth checks and their scope.
 
 ## Runtime prerequisite
@@ -171,7 +171,7 @@ checks Node/npm in both ordinary and sudo shells after installation. The existin
 runtime fast path preserves user-specific installations; a later sudo product
 install can still fail if that installation is absent from sudo's PATH.
 
-The [global executable receipt](../goals/terminal-product-lane/receipts/2026-09-05-global-npm-prefix.md)
+The [global executable receipt](https://github.com/danielgwilson/humanish/blob/main/docs/goals/terminal-product-lane/receipts/2026-09-05-global-npm-prefix.md)
 records the regression found after the initial runtime-only proof and its stock
 desktop checks. npm documents [global executable locations](https://docs.npmjs.com/cli/v10/configuring-npm/folders#executables)
 and the [distribution built-in configuration](https://docs.npmjs.com/cli/v10/configuring-npm/npmrc#built-in-config-file).
@@ -179,25 +179,27 @@ and the [distribution built-in configuration](https://docs.npmjs.com/cli/v10/con
 An egress allowlist must permit `nodejs.org` if the runtime needs installation,
 as well as the registries and product surfaces the study uses. Missing tools,
 unsupported architectures, a failed download or checksum, and a failed runtime
-check stop the lane before Codex. Downloads have finite connection, transfer, and
+check stop the participant before Codex. Downloads have finite connection, transfer, and
 retry bounds within the existing five-minute bootstrap deadline.
 
 The `desktop-cli` computer-use route uses this same Node/npm prerequisite when
-`subject.product.install` is omitted or declares a Node command. With install
-omitted, the participant arrives at an open terminal with Node/npm available;
-the product remains uninstalled for them to discover and install from its public
-surfaces. Runtime setup runs unkeyed and a failed bootstrap stops before the
-participant starts. A declared non-Node install keeps its existing runtime
-behavior. The desktop route retains its ten-minute runtime step deadline.
+`subject.product.install` is omitted or declares a Node command. With install omitted,
+the participant arrives at an open terminal with Node/npm available; the product
+remains uninstalled for them to discover and install from its public surfaces. Runtime
+setup runs unkeyed and a failed bootstrap stops before the participant starts. A
+declared non-Node install keeps its existing runtime behavior. The desktop route's
+runtime step has the same five-minute bootstrap deadline (`NODE_BOOTSTRAP_TIMEOUT_MS`,
+`src/subject/node-bootstrap.ts`); a declared install step keeps its ten-minute
+deadline.
 
 ## The original command-scoped safety contract
 
 The default mode **inverts** the credential-placement default of every other E2B route.
-On the computer-use route the model's key stays *outside* the sandbox; here the
-agent-under-test runs *inside* with a real `OPENAI_API_KEY`/`CODEX_API_KEY` and
-is **presumed exfiltratable**. The doctrine (invariants-and-defaults.md, the
-placement rule): *keys live where the keyed process runs — and nowhere else;
-blast radius is bounded by key scoping and budgets, not by hoping.*
+On the computer-use route the model's key stays _outside_ the sandbox; here the
+agent-under-test runs _inside_ with a real `OPENAI_API_KEY`/`CODEX_API_KEY` and
+is **presumed exfiltratable**. The placement rule in invariants-and-defaults.md
+applies: _keys live where the keyed process runs, and nowhere else;
+blast radius is bounded by key scoping and budgets, not by hoping._
 
 The inversion is declared as registry metadata, not a code convention: the
 terminal actor's capabilities carry `keyPlacement: "in-sandbox-command-scoped"`.
@@ -214,14 +216,14 @@ At SLICE 1, `runTerminalProductLab` implemented only the dry-run path: it built
 `humanish.run-bundle.v1` contract bundle, honestly labeled contract-only, with:
 
 - the subject declared as a terminal-product with its public surfaces, provenance
-  **UNPINNED** (the agent drives public surfaces, not a clone — invariant 5);
+  **UNPINNED** (the agent drives public surfaces, not a clone; invariant 5);
 - the author mission recorded as plaintext (public-safe committed lab text) + a
   **digest** of the full composed prompt (nothing beyond the author mission goes
   plaintext);
 - the caps / deny-by-default policies / runtime-auth channel recorded as
-  declarations (names only — invariant 1);
+  declarations (names only; invariant 1);
 - a terminal-kind stream that is an honest **contract placeholder**: stdin
-  disabled, empty tail, `transport: snapshot` — **not** `pty` (captured
+  disabled, empty tail, `transport: snapshot`, **not** `pty` (captured
   non-interactive exec output is never an interactive PTY; invariant 6 + the
   goal packet's PTY ruling). SLICE 2 later added redacted exec-stream capture;
 - empty/placeholder ledgers (substrate lifecycle, command log, terminal event
@@ -235,33 +237,37 @@ At SLICE 1, a non-dry-run call returned a structured
 `HUMANISH_TERMINAL_AGENT_NOT_IMPLEMENTED` failure before launch or spend.
 SLICE 2 implemented the real session.
 
-The DI seams SLICE 2 needs (`loadModule`, `buildSandbox`, `runtimeAuthEnv`,
-`detachedTimers`) are declared on `TerminalProductLabHooks` and threaded through
-`RunLabOptions.terminalHooks`, mirroring `cuaHooks` / `scriptedHooks`; only the
-dry-run path was implemented in that slice.
+SLICE 1 declared the DI seams SLICE 2 needed (`loadModule`, `buildSandbox`,
+`runtimeAuthEnv`, `detachedTimers`) on `TerminalProductLabHooks`; only the dry-run
+path was implemented in that slice. The hook bag now carries `loadModule`, `env`,
+`renderObserverFn`, `now`, `costProbe`, `score` and `deriveFeedback`
+(`src/routes/terminal/types.ts`), and `TerminalProductLabHooks` itself is deprecated
+in favor of `RunLabOptions`.
 
-## SLICE 4 — the product-adapter extension seam (layer 6)
+## SLICE 4: the product-adapter extension seam (layer 6)
 
-This lane is proof-roadmap **layer 6**: an adopter attaches product-specific
+This route is proof-roadmap **layer 6**: an adopter attaches product-specific
 scoring + feedback as a THIN in-repo extension WITHOUT forking core. SLICE 4
-ships the SEAM (not a built-in product scorer — the adopter's scorecard lives in
-the adopter's repo):
-
-- **Exported contract types** a thin adapter types against from the package
-  barrel (`humanish`) alone — never a deep `src/` import: `RunBundle`,
-  `RunFeedbackCandidate`, `RunAdapterScore`, `RunMeaningfulUseScore`
-  (+ `RunMeaningfulUseComponentId`), `ActorTrace`, and the terminal-lane
-  `TerminalProductScoringContext` / `TerminalLedgers` / `TerminalCostLedger` /
-  `NoSpendProof` / `CostLine` / record types. Before this slice these were not
-  exported — which FORCED a fork (a thin adapter could not type against the
-  bundle), the gap issue #154 acceptance #8 names.
-- **A registrable scorer / feedback DI hook** on `TerminalProductLabHooks`:
-  `score?(ctx: TerminalProductScoringContext) => RunAdapterScore | Promise<…>`
-  and `deriveFeedback?(ctx) => RunFeedbackCandidate[] | Promise<…>`. The lane
-  calls the hooks over the FULLY-ASSEMBLED, redacted evidence and attaches the
-  results (`bundle.adapterScore`, appended `bundle.feedbackCandidates`) WITHOUT
-  core knowing any product noun. Default (no hook) behavior is unchanged: the
-  mission-based verdict stands alone.
+ships the SEAM. Core ships no built-in product scorer; the adopter's scorecard
+lives in the adopter's repo:
+
+- **Exported contract types** a thin adapter types against from the package barrel
+  (`humanish`) alone, never through a deep `src/` import: `RunBundle`,
+  `RunFeedbackCandidate`, `RunAdapterScore`, `RunAdapterArtifact`, `ActorTrace`,
+  `AdapterScorerModule` and `TerminalProductScoringContext`. The ledger, cost and
+  no-spend shapes are reached through that context's fields, as
+  `TerminalProductScoringContext["ledgers"]`. Before this slice these were not
+  exported, which forced a fork (a thin adapter could not type against the bundle),
+  the gap issue #154 acceptance #8 names.
+- **A registrable scorer / feedback module**, `RunLabOptions.scorer` (an
+  `AdapterScorerModule`): `score?(ctx) => RunAdapterScore | Promise<…>` and
+  `deriveFeedback?(ctx) => RunFeedbackCandidate[] | Promise<…>`, where this route's
+  `ctx` is a `TerminalProductScoringContext`. The older `terminalHooks.score` and
+  `terminalHooks.deriveFeedback` still work and warn as deprecated. The route calls the
+  hooks over the FULLY-ASSEMBLED, redacted evidence and attaches the results
+  (`bundle.adapterScore`, appended `bundle.feedbackCandidates`) WITHOUT core knowing
+  any product noun. Default (no hook) behavior is unchanged: the mission-based verdict
+  stands alone.
 - **Adapter-namespaced product nouns.** Product-specific concepts (public
   CLI/product command observed, hosted product success-or-blocker, feedback
   id/draft, media/job/asset ids, no-media/no-provider-spend proof,
@@ -272,16 +278,16 @@ the adopter's repo):
   core enum (avoiding closed-taxonomy rot); `e2b-terminal` is added to the
   substrate enum so a terminal-agent candidate names its substrate honestly.
 
-The seam is fail-closed: the lane scrubs+redacts the returned payloads and DROPS
+The seam is fail-closed: the route scrubs+redacts the returned payloads and DROPS
 any malformed score/candidate with a warning, and `verifyRun` re-checks the
-surviving shapes — a bad extension never poisons a verifiable bundle. Proven by
-`tests/terminal-product-adapter-seam.test.ts` (a thin in-repo example adapter
+surviving shapes, so a bad extension never poisons a verifiable bundle. Proven by
+`tests/routes/terminal/product-adapter-seam.test.ts` (a thin in-repo example adapter
 typing against the barrel only, registering a scorer, attaching namespaced nouns,
 emitting a candidate; the bundle verifies). At SLICE 4 this was contract proof,
-not a live rung; the later end-to-end lane receipt is linked from the status
+not a live rung; the later end-to-end route receipt is linked from the status
 note.
 
-The adopter's real scorecard is its OWN thin extension. The end-to-end lane's
+The adopter's real scorecard is its OWN thin extension. The end-to-end route's
 live receipt is kept under the terminal-product goal, and true duplex PTY replay
 is deferred to SLICE 5.
 
@@ -290,7 +296,7 @@ is deferred to SLICE 5.
 The requesting adopter is a public creative-CLI product (see issue #154 for its
 concrete public surfaces). Committed source and docs here stay codename-neutral
 per the public-surface scan; the committed CI fixture
-([`humanish/labs/terminal-product-demo.yaml`](../../humanish/labs/terminal-product-demo.yaml))
+([`humanish/labs/terminal-product-demo.yaml`](https://github.com/danielgwilson/humanish/blob/main/humanish/labs/terminal-product-demo.yaml))
 uses a FICTIONAL mock CLI (`widgetsmith-cli`) with `example.com` surfaces. The
 adopter's real public surfaces appear only in operator-run docs and the GitHub
 issue, never in scanned committed text.

package/docs/contracts/adapter-admission.md

@@ -15,12 +15,12 @@ const provider = createOpenAiResponsesProvider({
       throw new CuaAdmissionLimitError();
     }
     return transport(url, init);
-  }
+  },
 });
 ```
 
 The example's admission check, local receipt and transport belong to the caller.
-The error accepts no message or payload. Import it from the same Humanish
+The error accepts no message or payload. Import it from the same humanish
 installation as the provider and loop: a plain error with the same name or text
 does not activate the contract. Do not use it for invalid configuration, a
 provider rejection, or an already dispatched request with unknown outcome or
@@ -30,7 +30,11 @@ A stalled interaction or an OpenAI transport retry may have consumed additional
 tokens without reporting usage. The trace then retains
 `interactionUsageIncomplete: true`; its cost summary keeps the known token
 estimate and adds an unmeasured `interaction_usage_unreported` line. A later
-successful retry or local refusal does not remove that uncertainty. Custom
+successful retry or local refusal does not remove that uncertainty. Under a
+declared dollar cap or study budget, the loop books such a request at its worst
+case before sending it again, and stops the session when that does not fit or
+when no `maxOutputTokens` bounds it (see the computer-use spend thresholds in
+[schemas.md](schemas.md)). Custom
 providers can expose a latched `interactionUsageIncomplete` boolean for hidden
 interactive attempts. Absence of the field does not attest complete billing.
 
@@ -47,7 +51,7 @@ is `skipped` and `debrief.usageReported` is absent, because this declaration say
 no provider request was sent. This does not invent zero usage or settle any
 earlier unknown cost.
 
-Humanish records the adapter's declaration; it does not independently attest
+humanish records the adapter's declaration; it does not independently attest
 transport behavior or provider billing. Retain local limit/admission receipts
 when auditing those facts. Keep credentials, request bodies and provider URLs
 out of such receipts. The contract does not add a manifest request-count cap,

package/docs/contracts/adapter-fixtures.md

@@ -8,7 +8,7 @@ live adopter integration or satisfy a deletion-branch depth phase.
 
 ## Purpose
 
-Adapter fixtures prove that Humanish can carry target-specific evidence without
+Adapter fixtures prove that humanish can carry target-specific evidence without
 moving target truth into core schemas. A fixture is not a product claim. It is a
 public-safe contract packet that shows the routes, personas, milestones,
 terminal evidence, feedback drafts, and policy decisions a real adapter must
@@ -27,9 +27,9 @@ The fixture contract keeps three boundaries explicit:
 
 The committed fixture set lives under `adapters/fixtures/`.
 
-| Fixture | Proves | Required artifacts |
-| --- | --- | --- |
-| `post-auth-return-dry-run` | A web-app adapter can keep upload, studio, and auth-return milestones adapter-owned while emitting a product-neutral dry-run bundle. | `adapter.json`, `persona.json`, `scenario.json`, `milestones.json`, `run-bundle.json` |
+| Fixture                       | Proves                                                                                                                                                                                            | Required artifacts                                                                                                                  |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `post-auth-return-dry-run`    | A web-app adapter can keep upload, studio, and auth-return milestones adapter-owned while emitting a product-neutral dry-run bundle.                                                              | `adapter.json`, `persona.json`, `scenario.json`, `milestones.json`, `run-bundle.json`                                               |
 | `terminal-feedback-lifecycle` | A terminal-first adapter can emit sanitized transcript evidence, issue-draft material, cost/redaction policy, verification checks, and feedback lifecycle proof without browser-only assumptions. | `adapter.json`, `policy.json`, `run-bundle.json`, `feedback-draft.json`, `verify-result.json`, `transcripts/sanitized-terminal.txt` |
 
 ## Promotion Gates
@@ -42,7 +42,7 @@ A fixture can be promoted only when:
 - credential policy records env var names only, never values;
 - adapter-owned nouns do not appear in core schema docs or core runtime code;
 - public feedback material states that GitHub mutation was not performed;
-- the fixture can be checked with `pnpm test tests/adapter-fixtures.test.ts`
+- the fixture can be checked with `pnpm test tests/lab/adapter-fixtures.test.ts`
   and `pnpm public-surface:scan`.
 
 ## Dry-Run Web-App Fixture Shape
@@ -77,6 +77,6 @@ This keeps terminal and feedback parity independent from browser screenshots.
 ## Proof Commands
 
 ```bash
-pnpm test tests/adapter-fixtures.test.ts
+pnpm test tests/lab/adapter-fixtures.test.ts
 pnpm public-surface:scan
 ```

package/docs/contracts/core.md

@@ -1,18 +1,19 @@
 # Core Contract
 
-Date: 2026-06-02 (current-state note updated 2026-07-14)
+Date: 2026-06-02 (current-state note updated 2026-09-30)
 
-Status: the listed primitives are shipped and tested. This document does not
-claim that every producer already uses one centralized store: run identity,
-history, and provider-resource lifecycle still span route-specific code and
-remain consolidation work.
+Status: each route mints its run id and builds its bundle, and starts the run
+through the run scope in `src/run/run.ts`. `startRun` creates
+`.humanish/runs/<id>` and begins `status.json`; the `Run` it returns publishes
+`run.json`, its projections and the latest pointer. `src/run/paths.ts` holds the
+shared path rules and `src/run/git-state.ts` captures git state. The table
+below lists the records current bundles write.
 
 ## Purpose
 
 Core is the reusable layer that makes a run bundle stable enough for agents,
-reviewers, and maintainers to trust. It owns generic run identity, artifact
-layout, source state summaries, lifecycle records, latest/history pointers, and
-timing summaries.
+reviewers, and maintainers to trust. It covers generic run identity, artifact
+layout, source state summaries, lifecycle records and the latest pointer.
 
 Core does not own product routes, personas, scenarios, app topology, provider
 setup, or repository-specific proof language.
@@ -22,25 +23,23 @@ setup, or repository-specific proof language.
 Core records must be safe to include in public run bundles by default:
 
 - artifact paths are relative;
-- ids produced by the core run-id builder contain only lowercase letters,
-  numbers, and dashes; runtime readers separately accept existing IDs that are
-  any safe single path segment;
+- route-built run ids join a route prefix, the ISO creation time with `:` and
+  `.` replaced by `-`, and random hex; runtime readers accept any id that is a
+  safe single path segment;
 - git state summarizes status without branch names, remotes, file names, file
   paths, or absolute working directories;
-- lifecycle and timing records are explicit inputs, not inferred prose;
-- latest/history pointers identify local artifacts, not hosted private logs.
+- lifecycle records are explicit inputs, not inferred prose;
+- the latest pointer identifies local artifacts, not hosted private logs.
 
 ## Primitive Set
 
-| Primitive | Contract |
-| --- | --- |
-| Run id | The core builder is deterministic from explicit prefix, timestamp, and entropy, and emits ids matching `^[a-z0-9][a-z0-9-]{0,127}$`. Runtime artifact binding uses the broader compatibility rule in `src/run-paths.ts`: one non-empty segment, excluding `.`, `..`, separators, and NUL. |
-| Artifact layout | Builds stable relative pointers under `.humanish/runs/<run-id>/` plus `.humanish/runs/latest.json`. |
-| Latest pointer | `{ schema, runId, path, updatedAt }` using `humanish.latest-run.v1`. |
-| History entry | `{ schema, runId, createdAt, mode, path }` using `humanish.run-history-entry.v1`. |
-| Lifecycle event | `{ at, event, message }`; event and message are required. |
-| Timing summary | `{ startedAt, endedAt, durationMs, status }`; running records have null end and duration. |
-| Git state | `{ schema, status, capturedAt, head, changes, note }` using `humanish.git-state.v1`. |
+| Primitive       | Contract                                                                                                                                                                                                                                                                    |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Run id          | Routes build `<prefix>-<timestamp>-<hex>` ids, for example `cua-2026-06-02T10-00-00-000Z-1a2b3c4d`. Runtime artifact binding uses the compatibility rule in `src/run/paths.ts`: one non-empty segment, excluding `.`, `..`, separators, and NUL. `latest.json` is reserved. |
+| Artifact layout | Run bundles live under `.humanish/runs/<run-id>/`, and the latest pointer is `.humanish/runs/latest.json`.                                                                                                                                                                  |
+| Latest pointer  | `{ schema, runId, path, updatedAt }` using `humanish.latest-run.v1`.                                                                                                                                                                                                        |
+| Lifecycle event | `{ at, event, message }` entries in `run.json` `lifecycle[]`; event and message are required.                                                                                                                                                                               |
+| Git state       | `{ schema, status, capturedAt, head, changes, note }` using `humanish.git-state.v1`, captured by `src/run/git-state.ts`.                                                                                                                                                    |
 
 ## Git State Boundary
 
@@ -72,5 +71,4 @@ Core work stops if:
 - a core primitive needs a product-specific noun to make sense;
 - an artifact path can escape the run root;
 - a public record includes a raw cwd, branch name, remote, file name, diff, or
-  credential-like value;
-- a run id cannot be reproduced from explicit inputs.
+  credential-like value.

package/docs/contracts/feedback.md

@@ -52,21 +52,20 @@ humanish feedback issue-url --run latest --repo owner/repo
 
 ### `list`
 
-Reads feedback candidates from the run bundle. Does not mutate. Candidates are
-generated by lab/adapters when actor evidence identifies a concrete
-setup-quality gap, ceremonial/absent study quality, target-app blocker, or
-Humanish CLI blocker. The OSS
-meta-lab is one maintainer dogfood example, not the only candidate source.
+Reads feedback candidates from the run bundle. Does not mutate. Candidates come
+from the computer-use route, when a participant reports friction or abandons the
+study goal, and from an adapter's `deriveFeedback` hook.
 
 The list also shows any saved draft. An empty `candidates` array means no usable
 candidate was recorded; it does not mean a run-summary draft is unavailable.
 Listing does not create a draft or check public-sharing eligibility.
 
 For completed computer-use sessions, participant-reported friction comes from
-the redacted closing report and observed-report clauses in earlier messages.
+the redacted closing report, a completed debrief's `frictionReports`, and
+observed-report clauses in earlier messages.
 Matching `stopWhen` or ending a dwell window does not discard an earlier
 report or change the successful completion verdict. Exact repeated reports
-appear once in the lane's candidate. Harness notices, reasoning, and observed
+appear once in the participant's candidate. Harness notices, reasoning, and observed
 page content do not become participant findings; quoted app copy and negated
 reports retain the existing exclusions. Code excerpts are treated as quoted
 material. Interim matching requires an observation-shaped clause and filters
@@ -101,6 +100,9 @@ does not create the issue.
 
 ## Schema
 
+`humanish feedback draft --json` returns a `humanish.feedback.v1` draft with these
+fields (`FeedbackDraft` in `src/feedback/draft.ts`):
+
 ```yaml
 humanish_feedback:
   schema: humanish.feedback.v1
@@ -114,37 +116,46 @@ humanish_feedback:
   summary: "<public-safe concrete summary>"
   expected: "<public-safe expected behavior>"
   actual: "<public-safe observed behavior>"
+  source_candidate_id: "<candidate-id>" # when drafted from a participant candidate
+  source_analysis: # when drafted from an analysis finding
+    id: "<analysis-id>"
+    sha256: "<analysis digest>"
+    finding_id: "<finding-id>"
+    finding_sha256: "<finding digest>"
+    correction_id: "<correction-id>|null"
   source_bundle: "<path-or-url>"
   evidence:
     - path: "<relative artifact pointer>"
       kind: "screenshot|state|review|trace|log|filesystem"
       note: "<public-safe note>"
   redaction:
-    status: "passed|failed|not_applicable"
+    status: "passed" # drafting is blocked otherwise
     notes: "<public-safe note>"
   idempotency_key: "<stable-key>"
   proposed_next_state: "watch|adapter-hardening|target-app-setup|actor-auth|setup-quality-review|study-quality-review"
   acceptance_proof:
     - "<command or artifact that would close this>"
-  adapter:
-    namespace: "<adapter namespace>"
-    data: {}
 ```
 
-`adapter` is optional and namespaced. Adapters may place product-specific
-concepts there (for example route groups, milestone ids, product acceptance
-details, or adopter-owned rubric data). Core validates only that `namespace` is
-non-empty and `data` is a record; keys inside `data` are never core enums.
+The issue body renders `summary`, `expected` and `actual` as markdown sections.
+The other fields, except `source_analysis`, go in a `humanish_feedback` YAML block.
+
+The `adapter` block rides on the run's feedback candidates
+(`RunFeedbackCandidate.adapter` in the run bundle), not on the draft. It is
+optional and namespaced. Adapters may place product-specific concepts there (for
+example route groups, milestone ids, product acceptance details, or
+adopter-owned rubric data). Core validates only that `namespace` is non-empty
+and `data` is a record; keys inside `data` are never core enums.
 
 ## Failure Owners
 
-| Owner | Meaning |
-| --- | --- |
-| `harness` | Humanish or adapter logic produced invalid evidence or execution. |
-| `target-app` | The target app setup, dev server, or local surface blocked the run. |
-| `actor` | The coding-agent/persona actor failed to complete a requested setup or usage path. |
-| `environment` | E2B, local browser, shell, filesystem, network, or dependency substrate failed. |
-| `unknown` | Evidence is useful but ownership is not yet clear. |
+| Owner         | Meaning                                                                            |
+| ------------- | ---------------------------------------------------------------------------------- |
+| `harness`     | humanish or adapter logic produced invalid evidence or execution.                  |
+| `target-app`  | The target app setup, dev server, or local surface blocked the run.                |
+| `actor`       | The coding-agent/persona actor failed to complete a requested setup or usage path. |
+| `environment` | E2B, local browser, shell, filesystem, network, or dependency substrate failed.    |
+| `unknown`     | Evidence is useful but ownership is not yet clear.                                 |
 
 ## Issue Draft Gates
 
@@ -156,7 +167,6 @@ Generating a public issue draft is blocked when:
 - redaction did not pass;
 - `shareSafety.status` is `local_only` or `blocked`;
 - any payload may contain PII, PHI, secrets, or private operational context;
-- proposed next state is `agent_ready` without a readiness block;
 - the feedback is a dry-run-only product claim;
 - idempotency key is missing.