humanish 0.15.2 → 0.16.0

package/dist/terminal-agent-actor.d.ts

@@ -1,11 +1,15 @@
 import type { ActorPersonaRef, ActorStatus, ActorCompletionReason, ActorTrace } from "./actor-contract.js";
-/** The fail-closed marker a SLICE-1 live invocation surfaces (never a raw crash). */
+/**
+ * Backward-compatible fail-closed marker for the intentionally unsupported direct runner.
+ * The name is retained because it is already exported public API.
+ */
 export declare const TERMINAL_AGENT_NOT_IMPLEMENTED_CODE: "HUMANISH_TERMINAL_AGENT_NOT_IMPLEMENTED";
 /**
  * Options the engine hands the terminal agent session. The transport is the captured
  * non-interactive exec stream (stdin disabled), NOT an interactive PTY — see ActorProtocol
- * "terminal-exec" and the goal packet's PTY ruling. Fields here are the SLICE-1 contract; SLICE 2
- * consumes them to drive the in-sandbox `codex exec` and capture its redacted output.
+ * "terminal-exec" and the goal packet's PTY ruling. This compatibility shape documents the
+ * descriptor boundary; the route-owned live implementation composes equivalent inputs with the
+ * additional provider, policy, cap, and cleanup controls it needs.
  */
 export interface TerminalAgentSessionOptions {
     /** Where the session writes its native trace/transcript/event-stream artifacts. */
@@ -16,7 +20,7 @@ export interface TerminalAgentSessionOptions {
     persona: ActorPersonaRef;
     /** The product's declared PUBLIC surfaces (http(s) URLs / refs) — the only world the agent sees. */
     publicSurfaces: string[];
-    /** Session wall-clock budget (also bounded by scenario.caps.maxMinutes in SLICE 2). */
+    /** Session wall-clock budget (the route also requires scenario.caps.maxMinutes). */
     timeoutMs: number;
     /** Per-run verdict nonce: the agent must echo it so replayed text can't forge the verdict. */
     verdictNonce: string;
@@ -29,8 +33,9 @@ export interface TerminalAgentSessionResult {
     trace: ActorTrace;
 }
 /**
- * Registry-facing session entry. SLICE 1: NOT yet live — the dry-run lab path never calls this,
- * and a live engine call fails closed with a structured error before reaching here. Calling it
- * directly throws the same fail-closed marker rather than pretending to drive a real agent.
+ * Backward-compatible registry entry. Direct execution is intentionally unsupported: only the
+ * terminal-product lab route owns enough context to enforce command-scoped auth, caps, evidence
+ * capture, and by-id cleanup together. Fail closed instead of implying that the descriptor method
+ * itself runs the shipped live route.
  */
 export declare function runTerminalAgentSession(_options: TerminalAgentSessionOptions): Promise<TerminalAgentSessionResult>;

package/dist/terminal-agent-actor.js

@@ -1,23 +1,25 @@
-// The terminal agent actor: a real autonomous coding agent (Codex) discovering and using a
-// CLI/product from PUBLIC SURFACES ONLY, running INSIDE an E2B shell with command-scoped runtime
-// auth, capturing its non-interactive exec output (stdin disabled) as a redacted event stream +
-// normalized transcript. This is the registry seam for the terminal-product lane.
+// Registry contract for the terminal-product lane. The shipped live implementation is
+// intentionally route-owned by `runTerminalProductLab` in `e2b-terminal-lab.ts`: that route must
+// coordinate sandbox creation, command-scoped runtime auth, caps, evidence capture, and by-id
+// cleanup as one fail-closed lifecycle.
 //
-// SLICE 1 SCOPE (honest): this module declares the session CONTRACT — the option/result shapes
-// and the registry-facing `runTerminalAgentSession` entry — but the LIVE session is NOT
-// implemented here yet. The dry-run lab path (src/e2b-terminal-lab.ts) never invokes runSession;
-// it builds a contract-only bundle. A live (non-dry-run) call into the engine returns a
-// structured "not yet implemented in this slice" failure, and calling runSession directly throws
-// the same fail-closed marker. SLICE 2 implements the real create -> inject (command-scoped) ->
-// run `codex exec --json` -> capture -> teardown session on the @e2b/desktop commands.run surface.
-/** The fail-closed marker a SLICE-1 live invocation surfaces (never a raw crash). */
+// `runTerminalAgentSession` remains exported because it was part of the public actor-descriptor
+// shape before the route-owned lifecycle shipped. Its options cannot carry the host/provider
+// controls needed to enforce that lifecycle, so direct calls are intentionally unsupported and
+// fail closed. Use `runTerminalProductLab` (or `runLab` with a terminal-product config) for both
+// dry-run and live execution.
+/**
+ * Backward-compatible fail-closed marker for the intentionally unsupported direct runner.
+ * The name is retained because it is already exported public API.
+ */
 export const TERMINAL_AGENT_NOT_IMPLEMENTED_CODE = "HUMANISH_TERMINAL_AGENT_NOT_IMPLEMENTED";
 /**
- * Registry-facing session entry. SLICE 1: NOT yet live — the dry-run lab path never calls this,
- * and a live engine call fails closed with a structured error before reaching here. Calling it
- * directly throws the same fail-closed marker rather than pretending to drive a real agent.
+ * Backward-compatible registry entry. Direct execution is intentionally unsupported: only the
+ * terminal-product lab route owns enough context to enforce command-scoped auth, caps, evidence
+ * capture, and by-id cleanup together. Fail closed instead of implying that the descriptor method
+ * itself runs the shipped live route.
  */
 export async function runTerminalAgentSession(_options) {
-    throw new Error(`${TERMINAL_AGENT_NOT_IMPLEMENTED_CODE}: the live terminal-agent session (in-sandbox Codex exec + command-scoped runtime auth) is implemented in SLICE 2. SLICE 1 only produces the dry-run contract bundle.`);
+    throw new Error(`${TERMINAL_AGENT_NOT_IMPLEMENTED_CODE}: direct runTerminalAgentSession calls are intentionally unsupported. Terminal execution is route-owned so the lab can enforce command-scoped runtime auth, caps, evidence capture, and by-id cleanup together. Use runTerminalProductLab or runLab with a terminal-product config.`);
 }
 //# sourceMappingURL=terminal-agent-actor.js.map

package/dist/terminal-agent-actor.js.map

@@ -1 +1 @@
-{"version":3,"file":"terminal-agent-actor.js","sourceRoot":"","sources":["../src/terminal-agent-actor.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,iGAAiG;AACjG,gGAAgG;AAChG,kFAAkF;AAClF,EAAE;AACF,+FAA+F;AAC/F,wFAAwF;AACxF,iGAAiG;AACjG,wFAAwF;AACxF,iGAAiG;AACjG,gGAAgG;AAChG,mGAAmG;AAInG,qFAAqF;AACrF,MAAM,CAAC,MAAM,mCAAmC,GAAG,yCAAkD,CAAC;AA+BtG;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,QAAqC;IAErC,MAAM,IAAI,KAAK,CACb,GAAG,mCAAmC,uKAAuK,CAC9M,CAAC;AACJ,CAAC"}
+{"version":3,"file":"terminal-agent-actor.js","sourceRoot":"","sources":["../src/terminal-agent-actor.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,iGAAiG;AACjG,8FAA8F;AAC9F,wCAAwC;AACxC,EAAE;AACF,gGAAgG;AAChG,6FAA6F;AAC7F,+FAA+F;AAC/F,iGAAiG;AACjG,8BAA8B;AAI9B;;;GAGG;AACH,MAAM,CAAC,MAAM,mCAAmC,GAAG,yCAAkD,CAAC;AAgCtG;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,QAAqC;IAErC,MAAM,IAAI,KAAK,CACb,GAAG,mCAAmC,qRAAqR,CAC5T,CAAC;AACJ,CAAC"}

package/docs/architecture/actor-contract.md

@@ -1,27 +1,34 @@
 # Actor Contract
 
-Date: 2026-06-06 (updated 2026-06-11)
-
-Status: accepted design, partially implemented. Shipped: the evidence schema
-`humanish.actor-trace.v1` (`src/actor-contract.ts`) and a registry of five
-actors (`src/actor-registry.ts`: `codex-app-server`, `pi-agent-core`,
-`claude-agent-sdk`, `openai-computer-use`, `scripted-browser`), with
-`actors[0].type` a real dispatch key on the computer-use and scripted-browser
-lab routes. Not yet shipped (roadmap, not near-term claims): the full
-`Actor.run(input)` interface, `RedactionHooks` injection, `ApprovalPolicy`,
-`StagehandCuaActor`, and the `persona-fidelity` verify check. Decision 6's
-capture-time screenshot stance was recanted in 0.6.0; see the inline notes and
-the capture-vs-publish rule in
+Date: 2026-06-06 (current-state note updated 2026-07-14)
+
+Status: accepted contract with a partially open extension surface. Shipped:
+the evidence schema `humanish.actor-trace.v1` (`src/actor-contract.ts`) and a
+closed first-party registry of six descriptors (`src/actor-registry.ts`:
+`codex-app-server`, `pi-agent-core`, `claude-agent-sdk`,
+`openai-computer-use`, `scripted-browser`, `codex-exec`). `actors[0].type` is a
+real dispatch key on the computer-use, scripted-browser, and terminal-product
+routes. Product scoring, feedback, and artifact hooks are extension seams, but
+public out-of-tree actor registration and its conformance certification are not
+shipped. Also not shipped: the full `Actor.run(input)` interface,
+`RedactionHooks` injection, `ApprovalPolicy`, `StagehandCuaActor`, and the
+`persona-fidelity` verify check. Decision 6's capture-time screenshot stance
+was recanted in 0.6.0; see the inline notes and the capture-vs-publish rule in
 [`docs/principles/invariants-and-defaults.md`](../principles/invariants-and-defaults.md).
 
+`codex-exec` is a real dispatch key for terminal-product labs, but the exported
+descriptor `runSession` is a fail-closed compatibility entry. Live execution is
+owned by `runTerminalProductLab`, which coordinates sandbox creation,
+command-scoped runtime auth, evidence, caps, and by-id cleanup.
+
 ## Context
 
-> 2026-06-11: this section describes the world as it stood when the design was
-> accepted (one real actor, hardcoded dispatch). That ceiling has since been
-> removed — the registry now holds the four actors listed in the status note.
+> Historical context: this section describes the world as it stood when the
+> design was accepted (one real actor, hardcoded dispatch). The current state is
+> the six-descriptor first-party registry described in the status note above.
 
-An actor is the thing that drives a persona scenario and produces evidence. Today
-Humanish has exactly one real actor: the local Codex integration in
+An actor is the thing that drives a persona scenario and produces evidence. At
+design time Humanish had exactly one real actor: the local Codex integration in
 `src/codex-app-server.ts` (plus the `codex-exec` and `codex-tui` variants in
 `src/run.ts`). The actor selection is a hardcoded `if (actor === ...)` dispatch,
 `RunStream.codex` is Codex-shaped, and the evidence schema is
@@ -91,6 +98,9 @@ API surface.
 
 ## The contract
 
+The excerpt below shows the central contract fields; exported source types are
+authoritative.
+
 ```ts
 export const ACTOR_TRACE_SCHEMA = "humanish.actor-trace.v1";
 
@@ -127,20 +137,21 @@ export interface ActorTraceItem {
 export interface ActorCapabilities {
   headless: boolean;
   structuredTrace: boolean;
-  lanes: Array<"code" | "app" | "computer-use" | "scripted-browser">;
+  lanes: Array<"code" | "app" | "computer-use" | "scripted-browser" | "terminal">;
   producesScreenshots: boolean;
   byoModel: boolean;
   preGrantableApprovals: boolean;   // can run unattended without a human prompt
   inProcessTools: boolean;          // can inject product tools without a subprocess
   license: "open" | "source-available" | "proprietary";
+  keyPlacement?: "external" | "in-sandbox-command-scoped";
 }
 
 export interface ActorTrace {
   schema: typeof ACTOR_TRACE_SCHEMA;
-  provider: string;              // "codex-app-server" | "pi-agent-core" | "claude-agent-sdk" | "openai-responses-cu" | "browser-persona"
+  provider: string;              // e.g. "codex-app-server" | "pi-agent-core" | "claude-agent-sdk" | "openai-responses-cu" | "browser-persona" | "codex"
   providerVersion?: string;
-  protocol: "json-rpc" | "json-stream" | "in-process-sdk" | "cua-loop" | "scripted-steps";
-  lane: "code" | "app" | "computer-use" | "scripted-browser";
+  protocol: "json-rpc" | "json-stream" | "in-process-sdk" | "cua-loop" | "scripted-steps" | "terminal-exec";
+  lane: "code" | "app" | "computer-use" | "scripted-browser" | "terminal";
   persona: { id: string; traitsApplied: string[]; promptDigest: string };  // proves traits were threaded
   // "raw" = full-fidelity frames retained (valid for LOCAL use; redact before
   // publishing); "blurred"/"ocr_scrubbed" = publish-safe; "n/a" = none captured.

package/docs/architecture/observer.md

@@ -1,16 +1,22 @@
 # Observer Architecture
 
-Date: 2026-06-01
+Date: 2026-06-01 (current-state note updated 2026-07-14)
 
-Status: implemented for synthetic stream contracts and local `codex-exec`
-active-run Observer snapshots; broader live actor adapters next.
+Status: implemented for synthetic streams and persisted live browser,
+terminal-product, fan-out, and sequential/concurrent shared-world evidence.
+Plain computer-use and shared-world runs can publish an in-progress bundle to
+an attached loopback Observer without persisting runtime stream-auth URLs. The
+version-pinned README image is a synthetic technical sample, not real-application
+proof.
 
 ## Decision
 
 The Observer is a mission-control surface over durable run artifacts, not a
 static report page.
 
-Every run writes immutable local evidence under `.humanish/runs/<run-id>/`:
+Every run writes durable local evidence under `.humanish/runs/<run-id>/`. Active
+runs refresh their bundle and Observer projection; later review, feedback, or
+Observer commands may add derived artifacts:
 
 ```text
 .humanish/runs/<run-id>/
@@ -25,7 +31,7 @@ Every run writes immutable local evidence under `.humanish/runs/<run-id>/`:
 
 `run.json` remains the source bundle. `observer/observer-data.json` is the
 normalized view model consumed by the Observer. `events.ndjson` is the appendable
-event stream contract that live adapters will update while a run is active.
+event stream contract that live adapters update while a run is active.
 
 ## Stream Model
 
@@ -95,12 +101,12 @@ A host adapter may provide:
 If no embed URL exists, the Observer still renders the Codex-style timeline and
 session contract instead of failing the lane.
 
-## Current Gaps
+## Historical slice and remaining gaps
 
-This slice implemented the Observer substrate, synthetic stream contracts, and
-active-run Observer snapshots for local `codex-exec`.
+The original 2026-06-01 slice implemented the Observer substrate and synthetic
+stream contracts; local `codex-exec` active-run snapshots followed.
 
-Since shipped (updated 2026-06-11):
+Subsequent additions through 2026-06-11 included:
 
 - Playwright-backed browser proof with scripted, app-specific
   `browser.steps` authored in `humanish/scenarios/*.yaml` (`src/run.ts`);

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

@@ -134,9 +134,9 @@ import { runLab, parseLabConfig, type CuaExecutor, type CuaProvider } from "huma
 
 // local-app YAML (shareable; fails closed without hooks):
 //   schema: humanish.lab.v2
-//   id: pixel-bae-state
+//   id: downstream-local-app-state
 //   subject: { source: local-app, appUrl: http://localhost:5173 }
-//   actors: [{ type: openai-computer-use, persona: pixel-pat, mission: "…" }]
+//   actors: [{ type: openai-computer-use, persona: curious-tester, mission: "…" }]
 //   scenario: { mode: live }
 const parsed = parseLabConfig(yaml);
 if (!parsed.ok) throw new Error(parsed.error.message);
@@ -199,5 +199,5 @@ Read every optional field defensively, and spread-omit optional fields
   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
+  the validated library consumer does not need it: a caller builds the bridge in its own
   trusted code (entry point 2 above).

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

@@ -1,11 +1,14 @@
 # Terminal-product real-agent lane (issue #154)
 
-Date: 2026-06-16
-
-Status: SLICE 1 shipped — the config + routing skeleton, DRY-RUN only. The live
-in-sandbox backend, the command-scoped credential boundary, cleanup,
-interventions, the cost/no-spend ledger, and the product-adapter extension seam
-are later slices. See the ratified goal packet
+Date: 2026-06-16 (current-state note updated 2026-07-14)
+
+Status: live terminal-product route shipped in `0.8.0`. The in-sandbox backend,
+command-scoped credential placement, exact-id cleanup proof, an interventions ledger,
+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))
 for the full slice plan and the safety contract.
 
@@ -33,7 +36,7 @@ fail-closed cross-validation, and forward-declared warnings.
 | `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` (names-only evidence this slice) |
+| `execution.runtimeAuth` | `openai-env` (names-only durable evidence) |
 | `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`) |
@@ -54,16 +57,16 @@ 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"`.
-SLICE 1 ships the DECLARED field + value (the contract is honest about where the
-key would go); SLICE 2's engine enforces command-scoped injection (only into the
+SLICE 1 shipped the DECLARED field + value (the contract was honest about where
+the key would go); SLICE 2's engine added command-scoped injection (only into the
 per-command `envs` of the `codex` invocation, never `Sandbox.create({envs})`)
 keyed off that capability, plus the deny-by-default credential allowlist, the
 positive-allowlist sandbox metadata, the cleanup proof, the interventions ledger,
 and a minimal fail-closed cap.
 
-## SLICE 1 scope (DRY-RUN only — what is honest now)
+## Historical SLICE 1 scope (DRY-RUN only when shipped)
 
-`runTerminalProductLab` implements ONLY the dry-run path: it builds a valid
+At SLICE 1, `runTerminalProductLab` implemented only the dry-run path: it built a valid
 `humanish.run-bundle.v1` contract bundle, honestly labeled contract-only, with:
 
 - the subject declared as a terminal-product with its public surfaces, provenance
@@ -76,22 +79,22 @@ and a minimal fail-closed cap.
 - a terminal-kind stream that is an honest **contract placeholder**: stdin
   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 fills the redacted exec-stream capture;
+  goal packet's PTY ruling). SLICE 2 later added redacted exec-stream capture;
 - empty/placeholder ledgers (substrate lifecycle, command log, terminal event
-  stream, interventions, cost) that SLICE 2/3 fill.
+  stream, interventions, cost) that SLICE 2/3 later filled.
 
-The dry-run bundle passes the EXISTING `verifyRun`. Terminal-specific verifier
+The dry-run bundle passed the existing `verifyRun`. Terminal-specific verifier
 checks (terminal/transcript presence, lifecycle, cleanup, interventions,
-metadata allowlist, no-credential-in-artifacts, no-spend) are SLICE 2/3.
+metadata allowlist, no-credential-in-artifacts, no-spend) landed in SLICE 2/3.
 
-A non-dry-run (live) call returns a structured `HUMANISH_TERMINAL_AGENT_NOT_IMPLEMENTED`
-failure (fail-closed, clear code) — it never creates a sandbox, never injects a
-key, never spends. SLICE 2 implements the real session.
+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` — but only
-the dry-run path is implemented this slice.
+`RunLabOptions.terminalHooks`, mirroring `cuaHooks` / `scriptedHooks`; only the
+dry-run path was implemented in that slice.
 
 ## SLICE 4 — the product-adapter extension seam (layer 6)
 
@@ -130,12 +133,13 @@ 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
 typing against the barrel only, registering a scorer, attaching namespaced nouns,
-emitting a candidate; the bundle verifies). No live rung — the seam is contract,
-not spend.
+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
+note.
 
-The adopter's real scorecard is its OWN thin extension; the live receipt for the
-end-to-end lane is tracked under #159, and true duplex PTY replay is deferred to
-SLICE 5.
+The adopter's real scorecard is its OWN thin extension. The end-to-end lane's
+live receipt is kept under the terminal-product goal, and true duplex PTY replay
+is deferred to SLICE 5.
 
 ## The reference adopter (codename-neutral)
 

package/docs/contracts/adapter-fixtures.md

@@ -1,8 +1,10 @@
 # Adapter Fixture Parity Contract
 
-Date: 2026-06-02
+Date: 2026-06-02 (current-state note updated 2026-07-14)
 
-Status: v0 draft contract for public-safe adapter fixture parity.
+Status: committed contract fixtures with passing parity checks. A fixture
+proves that core can carry an adapter-owned evidence shape; it does not prove a
+live adopter integration or satisfy a deletion-branch depth phase.
 
 ## Purpose
 

package/docs/contracts/core.md

@@ -1,8 +1,11 @@
 # Core Contract
 
-Date: 2026-06-02
+Date: 2026-06-02 (current-state note updated 2026-07-14)
 
-Status: v0 draft contract with tested primitive helpers in `src/core`.
+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.
 
 ## Purpose
 
@@ -19,7 +22,9 @@ setup, or repository-specific proof language.
 Core records must be safe to include in public run bundles by default:
 
 - artifact paths are relative;
-- run ids contain only lowercase letters, numbers, and dashes;
+- 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;
 - 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;
@@ -29,7 +34,7 @@ Core records must be safe to include in public run bundles by default:
 
 | Primitive | Contract |
 | --- | --- |
-| Run id | Deterministic from explicit prefix, timestamp, and entropy; valid ids match `^[a-z0-9][a-z0-9-]{0,127}$`. |
+| 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`. |

package/docs/contracts/feedback.md

@@ -1,8 +1,10 @@
 # Feedback Contract
 
-Date: 2026-06-01
+Date: 2026-06-01 (current-state note updated 2026-07-14)
 
-Status: v0 local issue draft generation with run-candidate support.
+Status: local feedback candidate, draft, verification, Markdown, and issue-URL
+generation are shipped. These commands do not mutate GitHub, and public output
+fails closed unless the run verifies as `share_ready`.
 
 ## Purpose
 

package/docs/contracts/policy.md

@@ -1,9 +1,11 @@
 # Policy Contract
 
-Date: 2026-06-02
+Date: 2026-06-02 (current-state note updated 2026-07-14)
 
-Status: v0 draft contract for credential, network, spend, redaction, and
-assisted-run boundaries.
+Status: shipped policy reference for credential, network, spend, redaction,
+sharing, and assisted-run boundaries. Support remains route-specific; the
+parser, route validation, and verifier determine whether a declared field is
+consumed, rejected, or reported as a warning.
 
 Safety amendment (2026-07-14): beginning with `0.15.1`, stored provider IDs are
 evidence and never authorize core provider mutation. The bundled OSS meta-lab

package/docs/contracts/run-bundle.md

@@ -1,9 +1,11 @@
 # Run Bundle Contract
 
-Date: 2026-06-02
+Date: 2026-06-02 (current-state note updated 2026-07-14)
 
-Status: v0 draft contract for bundle identity, layout, source state, history,
-lifecycle, and timing primitives.
+Status: `humanish.run-bundle.v1` is the shipped evidence contract. The
+TypeScript shape and fail-closed verification in `src/run.ts` are
+authoritative; this document explains the stable public fields and extension
+rules rather than independently versioning the runtime.
 
 ## Purpose
 
@@ -77,6 +79,25 @@ Persisted `run.json` files must not contain absolute local target paths. Runtime
 commands may return the caller's working directory in process-local JSON
 responses, but durable run bundles use the public-safe `[target-cwd]` marker.
 
+## Hosted Desktop Geometry
+
+Hosted browser streams may carry additive `desktopGeometry` evidence. Its fields keep four
+different facts separate:
+
+- `screen.requested`: the E2B/X screen size requested by config;
+- `screen.verified`: the screen size measured in-sandbox with `xdpyinfo`;
+- `browserWindow`: outer browser bounds measured after the window-fill attempt;
+- `viewport`: the page's CSS layout viewport and device-pixel ratio measured through CDP on
+  Chromium-family hosted browsers.
+
+For new hosted-desktop computer-use bundles, `stream.viewport` mirrors the measured
+`desktopGeometry.viewport`; it is omitted when runtime measurement is unavailable. It is never
+filled from the requested screen size. Dry-run bundles therefore carry the requested screen but
+no verified screen, browser bounds, or viewport. Historical bundles remain loadable and may
+contain the older requested-screen `stream.viewport` shape without `desktopGeometry`.
+Deterministic Playwright-style adapters remain free to declare a viewport that they also render
+exactly; this hosted-desktop rule does not change that contract.
+
 ## Subject Provenance
 
 `subject` is an optional, additive top-level field: structured provenance for

package/docs/contracts/schemas.md

@@ -1,10 +1,12 @@
 # Contract Schema Index
 
-Date: 2026-06-02 (updated 2026-06-24)
+Date: 2026-06-02 (current-state note updated 2026-07-14)
 
-Status: schema map aligned to the shipped v0.6.x surface. Rows marked
-"reserved" name layering intent only — no code emits or validates them yet.
-Do not emit a reserved schema.
+Status: reference map for the major contracts shipped through source version
+`0.16.0`; it is not an exhaustive inventory of command/result envelopes. Exported types,
+schema constants, parsers, and validators in `src/` are authoritative. Rows
+marked "reserved" name layering intent only — no code emits or validates them
+yet. Do not emit a reserved schema.
 
 ## Purpose
 
@@ -110,9 +112,13 @@ A lab is a composition over code primitives, not a hardcoded kind:
   appear in `subject.env`) pointing at state the lab does not control,
   recorded as UNPINNED in provenance. Commands persist in evidence as
   sha256-16 digests only, never as text;
-- `actors`: who drives it. On the computer-use and scripted-browser routes
-  `actors[0].type` is a real dispatch key resolved against the actor registry;
-  elsewhere it is a descriptive label (e.g. `synthetic-persona`).
+- `actors`: who drives it. On computer-use (including shared-world),
+  scripted-browser, and terminal-product routes, `actors[0].type` is a real
+  dispatch key resolved against the actor registry. On synthetic and meta-lab
+  routes it remains a descriptive label (e.g. `synthetic-persona`). The
+  `codex-exec` descriptor's direct `runSession` member is a fail-closed
+  compatibility entry, not the live runner; the terminal-product lab route
+  owns the live sandbox, auth, cap, evidence, and cleanup lifecycle.
   `actors[0].count` carries route-specific meanings: synthetic route lane
   count (simCount); scripted-browser route surface roster (1 = desktop,
   2 = desktop + mobile, default 1); computer-use **E2B** route the HOMOGENEOUS
@@ -188,12 +194,14 @@ A lab is a composition over code primitives, not a hardcoded kind:
   `terminal.transport` is `exec-stream` — captured NON-interactive exec output
   (stdin disabled); `pty` is rejected because labeling captured exec output as
   an interactive PTY would overstate the mechanism (invariant 6; a true duplex
-  PTY transport is a deferred slice). `terminal.stdin` defaults to `disabled`
+  PTY transport does not ship). `terminal.stdin` defaults to `disabled`
   (`sent`/assisted input is rejected until the interventions ledger + a
   non-comparable marker exist). `runtimeAuth: openai-env` declares the agent's
-  runtime-auth channel — recorded as NAMES ONLY; the command-scoped injection
-  (`keyPlacement: in-sandbox-command-scoped`) is enforced by the engine in a
-  later slice;
+  runtime-auth channel — recorded as NAMES ONLY. On a live run, the engine
+  resolves the registered terminal descriptor and requires
+  `keyPlacement: in-sandbox-command-scoped` before creating a sandbox. The key
+  is passed only to the agent command, never to `Sandbox.create` or metadata;
+  a dry-run neither reads nor injects it;
 - `scenario`: `mode: dry-run` (contract evidence, no spend) or `live`.
   `scenario.ref` is CONSUMED (and REQUIRED) on the scripted-browser route: it
   resolves a committed scenario (`humanish/scenarios/<ref>.yaml` or a repo
@@ -483,9 +491,10 @@ world ("M of N"); PROVEN CONCURRENCY (overlapping windows); and system-state evo
 under load (the stateSeries) with best-effort temporal correlation. It CANNOT claim
 strict causal attribution of a delta to an actor (concurrent ⇒ ambiguous), determinism
 of exact state, per-action granularity, or concurrency-SAFETY (races are OBSERVED, never
-PROVEN absent). HONESTY: the deterministic $0 gate proves the plumbing + the attribution
-contract; the concurrency CAPABILITY at scale is backed only by a separately-authorized
-live receipt.
+PROVEN absent). HONESTY: the deterministic $0 gate proves the plumbing + the
+attribution contract. A kept 2026-06-17 live receipt separately proves one
+bounded three-persona trial against a synthetic plane. Neither the deterministic
+gate nor that receipt proves scale, repeatability, or adopter-harness replacement.
 
 ## Adapter
 
@@ -639,27 +648,29 @@ inside run bundles (per-stream transport and status) and lab execution config
 
 ## Terminal Cost Ledger And No-Spend Proof
 
-The terminal-product lane (`src/e2b-terminal-lab.ts`) places a real provider key
-INSIDE the sandbox, so the no-spend claim must be REAL — derived from a ledger,
-never asserted. The live run writes both to `terminal-ledgers.json` (a `cost`
-block + a `noSpendProof` block, additive to `humanish.terminal-ledgers.v1`).
+The terminal-product lane (`src/e2b-terminal-lab.ts`) passes a real provider key
+only to the in-sandbox agent command, never to sandbox-global env or metadata,
+so the no-spend claim must be REAL — derived from a ledger, never asserted. The
+live run writes both to `terminal-ledgers.json` (a `cost` block + a
+`noSpendProof` block, additive to `humanish.terminal-ledgers.v1`).
 
 The cost ledger (`humanish.terminal-cost-ledger.v1`) has one line per category —
 `product`, `media`, `payment`, `provider` — and follows a strict **null
 discipline** that distinguishes three states and never conflates them:
 
 - `usd: 0` — **known zero**: the category was metered and billed nothing.
-- `usd: null` — **not measured**: no spend signal exists for the category this
-  slice. `null` is written explicitly (never `undefined`-omitted, never guessed
+- `usd: null` — **not measured**: no spend signal exists for the category on
+  this run. `null` is written explicitly (never `undefined`-omitted, never guessed
   to `0`). A line with `null` says "this category exists but we did not measure
   it"; the no-spend proof reports it as unmeasured and does NOT claim it is zero.
 - line **absent** — **not applicable** (n/a) to the lane/run.
 
 `knownTotalUsd` sums ONLY the non-null lines (a `null` line contributes nothing
 and is never coerced to `0`); `fullyMeasured` is true only when no line is null.
-This slice meters only the `provider` line, populated from the actor trace's
-`tokenUsage.costUsd` when present (else `null`); `product`/`media`/`payment` are
-`null` until the SLICE-4 adapter supplies them.
+Core meters only the `provider` line, populated from the actor trace's
+`tokenUsage.costUsd` when present (else `null`); `product`/`media`/`payment`
+remain `null` unless an adapter supplies those signals through the shipped
+cost-probe seam.
 
 ```yaml
 schema: humanish.terminal-cost-ledger.v1