humanish 0.96.1 → 0.98.0

package/docs/architecture/browser-control.md

@@ -0,0 +1,117 @@
+# Internal browser control
+
+The browser-control client implements the existing `CuaExecutor` over an
+already-owned Node `Duplex`. The matching dispatcher invokes an owner-supplied
+executor. This is a preparatory internal boundary, not a managed-local runtime,
+CLI mode, browser launcher, VM isolation claim, or installer.
+
+## Ownership and admission
+
+`createBrowserControlClient({ transport, identity, requestTimeoutMs? })` returns
+`{ executor, ready(), close() }`. `ready()` performs a lazy handshake; the first
+observation/action also performs it when needed. The owner closes the client
+when its session ends. The client never discovers endpoints, opens sockets,
+spawns processes, reconnects, retries, or replays a mutation.
+
+`attachBrowserControlDispatcher({ transport, identity, executor, isAuthorized,
+authoritySignal })` returns `{ close() }`. The authority signal is required.
+The owner establishes the channel and authority independently; the identity's
+`generation`, `challenge`, and `runtimeRevision` only check consistency.
+Each is a bounded ASCII token. A matching string does not prove a lease or
+authenticate executable bytes.
+
+The dispatcher checks current authorization immediately before invoking browser
+I/O. It passes a signal combining owner revocation, channel loss, and its request
+deadline to `execute`. The physical driver must check that signal immediately
+before **each actual input**, including after asynchronous preparation. Closing
+the channel cannot roll back already-dispatched input or prove the browser has
+stopped. The physical owner remains responsible for resource cleanup and the
+independent watchdog. Observation has no cancellation parameter in the existing
+executor interface; late observations are discarded after closure.
+
+One operation may be pending, including handshake and observation. Concurrent
+calls are rejected rather than queued. The client marks its executor with
+`stallRecovery: 'fail_closed'`, so an earlier computer-use loop deadline cannot
+trigger the legacy observation retry or idle-action skip behavior.
+
+## Wire contract
+
+Each frame is a four-byte unsigned big-endian length followed by strict UTF-8
+JSON. The parser allocates its bounded payload only after validating the length;
+it handles fragmented and coalesced input without repeatedly concatenating it.
+A partially received frame has a nonrenewing 35-second assembly deadline.
+
+Version 1 has only `HELLO`, `OBSERVE`, and `EXECUTE`. Both directions carry the
+version, operation, identity, strictly increasing sequence and `request-N`
+correlation ID. Execute additionally carries the distinct `action-N` ID.
+Unknown fields, methods, versions, stale identity, duplicates, missing or wrong
+correlation, malformed UTF-8/JSON and oversized frames close admission. There is
+no generic CDP, command, file, navigation-management, or runtime-management method.
+Initial target navigation remains an adapter-owned operation.
+
+Replies acknowledge completion or contain a finite `CuaExecutorError` code and
+`not_dispatched` / `outcome_uncertain` disposition. They never include raw
+exception prose, typed text, page URLs, or browser errors in their error fields.
+A generic driver exception after invocation is uncertain; only a genuine typed
+driver declaration can attest that input was never dispatched.
+
+The client resolves execute only after a matching completion acknowledgement and
+its write callback. Cancellation, deadline, explicit close, or channel loss after
+a possible write is uncertain and terminal. A later acknowledgement cannot reopen
+that channel. Pre-aborted signals and locally rejected input cause no write.
+Cancellation during the preliminary handshake remains a pre-dispatch action
+failure. No exactly-once or rollback guarantee is implied by sequence IDs.
+
+## Finite bounds
+
+| Input | Version 1 bound |
+| --- | --- |
+| Framed JSON | 12 MiB |
+| PNG bytes | 8 MiB |
+| Image dimensions | 4096 per side, at most 16,000,000 pixels |
+| Typed text and each observed string | 64 KiB UTF-8 |
+| Key chord | 16 keys, 64 characters per key |
+| Drag | 1–1024 points |
+| Coordinates, deltas, scroll position | Finite, within ±1,000,000; fractions preserved |
+| Wait | 0–30 seconds, fractions preserved |
+| Client request | 35 seconds by default; caller may choose 1–60 seconds |
+| Dispatcher request | 35 seconds including acknowledgement write |
+
+Observation requires a PNG and state signature. It may include bounded URL,
+title, text, and fractional scroll position; those remain runtime-only under the
+existing loop contract. Arbitrary `appState` is refused because v1 has no closed
+schema for it. The protocol does not truncate strings, round coordinates, or
+silently drop unsupported state.
+
+PNG admission checks signature, IHDR before decoder allocation, chunk framing,
+IDAT/IEND presence, no trailing bytes, CRCs and full decode. Version 1 admits
+8-bit, noninterlaced browser PNGs. Interlaced and 16-bit images are rejected:
+the current decoder has an unbounded interlaced inflation branch, so admitting
+those would require a separately bounded decoder. Image dimensions and the
+pixel product are checked before decoding, independently of compressed size.
+
+## Verification boundary
+
+`tests/browser-control-protocol.test.ts`, `browser-control-transport.test.ts`
+and `browser-control-client.test.ts` exercise production schemas and framing,
+all action kinds, image limits, correlation, malformed input, revocation,
+concurrency, lost acknowledgements, backpressure and cancellation. These use
+synthetic PNGs and inert paired byte streams, with no network, model or VM calls.
+They establish the protocol contract, not a real-browser or managed-runtime
+claim. The separate owned-child/browser conformance proof must retain real
+pixels and independently observed fixture mutations through the same modules.
+
+From a source checkout, run `pnpm build && pnpm browser-control:proof` with a
+Chromium installation that supports its sandbox. The proof uses a fresh profile,
+a private local socket, a separate controller process and a synthetic loopback
+page. It checks a normal save, a lost acknowledgement after one save, and owner
+revocation/cancellation during input preparation. Screenshots, loop traces,
+independent save counts and exact child/profile cleanup results are retained in
+`.humanish/browser-control-proof/`. Failed cleanup remains unconfirmed and keeps
+the private recovery directory; killing a controller alone does not prove its
+browser stopped.
+
+This is deterministic `runComputerUseLoop` conformance, not model perception,
+the study producer, a ready-desktop adapter, a durable local-study bundle or
+Observer qualification. Page request interception does not establish process-wide
+egress isolation. Those integration and runtime boundaries remain separate gates.

package/docs/architecture/desktop-sessions.md

@@ -0,0 +1,80 @@
+# Owned desktop sessions
+
+Independent hosted computer-use lanes acquire an owned desktop allocation before
+subject setup, then bind its executor after browser setup. The participant loop
+still consumes `CuaExecutor`; provisioning commands stay in the hosted adapter.
+This internal interface is not a public runtime plugin API.
+
+`desktop-session.ts` holds the lifecycle contract. The allocation captures a
+resource ID and a release closure. Its ID is a record of acquisition, not
+authority to reconstruct or reclaim a resource from an arbitrary saved bundle.
+
+An allocation binds one participant executor. Closing it immediately rejects new
+observations and actions, forwards no further calls, and shares one release
+attempt across repeated or concurrent callers. Cancellation signals pass through
+unchanged. Closing does not wait for an already-dispatched backend operation;
+that operation may fail as the desktop stops.
+
+Cleanup has three outcomes:
+
+- `released`: the adapter confirmed termination or that the resource was already
+  gone;
+- `retained`: an existing debug-retention policy deliberately kept the desktop;
+- `unconfirmed`: release was unavailable, failed, or returned an invalid result.
+
+A closed allocation never implicitly retries cleanup or reopens input. Recovery
+needs its own authorized operation. Runtime exceptions remain untrusted and must
+pass the caller's existing redaction before entering warnings or artifacts.
+
+The E2B adapter preserves the existing create options, template overload, startup
+retry guard and kill-on-timeout policy. It captures the acquired ID and kill
+method before provisioning hooks can mutate the SDK object. E2B's boolean kill
+result confirms either termination (`true`) or prior absence (`false`, its 404
+case). Other values do not confirm cleanup. Account-wide enumeration is never
+part of release.
+
+Already-absent cleanup carries a warning: the exact termination time is unknown.
+As before, desktop cost is an estimate over the host's acquisition-to-cleanup
+span, not a provider billing measurement.
+
+`CuaDesktopLane` separates desktop preparation from the participant runner:
+
+1. `prepare()` acquires and prepares the desktop. Failures still leave cleanup
+   authority with the adapter.
+2. The runner starts its model session and signals the existing hosted pipeline
+   gate, preserving the current scheduling order.
+3. `openSession()` measures initial browser geometry, starts the optional live
+   stream, and supplies a `CuaExecutor` plus any participant inbox location.
+4. The runner executes the participant loop and closes its model session.
+5. `finalize()` collects final evidence and releases the desktop, including after
+   preparation or participant failure. Repeated calls share one finalization.
+6. `snapshot()` supplies the desktop facts for the existing lane outcome.
+
+The E2B implementation lives in `e2b-cua-desktop.ts`; its browser, media and
+subject provisioning primitives live in `e2b-cua-provisioning.ts`. Existing
+helper imports through `cua-actor-lab.ts` remain supported. The adapter never
+imports the lab runner at runtime.
+
+The runner owns instructions, model execution, spend guards, screenshots, trace
+persistence and participant outcome interpretation. It does not invoke desktop
+shell commands or manufacture E2B objects for an alternate executor. The internal
+`CuaLaneDeps.createDesktopLane` seam is for construction and contract testing;
+it does not add a user-facing runtime option or bypass CLI admission checks.
+
+Final evidence errors cannot skip desktop release. Existing bundle fields and
+desktop lifetime accounting retain their meanings; unconfirmed or retained
+desktops do not become confirmed cleanup. Provider facts remain absent when the
+adapter cannot establish them.
+
+This change supplies an internal boundary for future runtime adapters. Managed
+local execution, artifact installation, controller-death leases, capability
+admission and new media support require separate implementations and proofs.
+Independent hosted browser and terminal lanes, plus concurrent shared-world
+seats that use `runCuaLane`, use this boundary. Sequential shared-world lifecycle
+remains separate and uses the same re-exported provisioning helpers.
+
+The independent lane's `runSession` testing hook now receives a constructed
+`executor` instead of `desktop`/`executorOptions`. A hook should consume the
+normal `CuaActorSessionOptions` executor or delegate to `runCuaActorSession`.
+Library calls directly using `runCuaActorSession({ desktop, executorOptions })`
+remain supported; the custom in-process `buildExecutor` route is unchanged.

package/docs/architecture/guest-desktop.md

@@ -0,0 +1,87 @@
+# Headed browser guest components
+
+These internal components implement native input and full-desktop captures for a
+maintained browser-only guest. They do not enable a public local-runtime mode.
+The VM owner, control transport, app network policy, installed setup and complete
+study journey require separate qualification.
+
+The driver uses the existing `CuaExecutor` contract behind
+[browser control](browser-control.md). Coordinates refer to the complete Xvfb
+frame, including the browser's address bar. Invalid points are refused instead
+of moved to a different target. Captures must match the admitted geometry and
+pass the bounded PNG validator. Browser URL/title/DOM metadata is absent in this
+component; callers must not invent it from the screenshot or infer task matches.
+Progress detection uses the same coarse frame signature as the hosted desktop.
+
+## Input boundary
+
+The actor receives the existing finite action union. Native tool paths, display,
+Xauthority and guest temporary directory come from the owner. Key names map to a
+closed list before reaching xdotool, whose own command syntax must never receive
+arbitrary participant strings. A native wheel step is not an exact pixel-scroll
+promise; one action permits at most 100 wheel steps. The entire drag is checked
+before its first input.
+
+Each input checks the current authority after asynchronous preparation. A
+partial or unacknowledged input closes the executor; it is never automatically
+replayed. Releasing a held button can itself click or drop, so revocation does
+not inject a cleanup mouseup into the app. The owner must stop the private
+browser/display. A stopped helper alone does not establish desktop or VM absence.
+
+Text in a focused, editable top-level document uses Chromium's fixed
+`Input.insertText` command over the owner's private Playwright pipe. The actor
+receives no CDP, JavaScript, selector, or debugging endpoint. A separate isolated
+world checks actual document focus and binds preparation to the editable element;
+page changes, additional tabs, dialogs, iframe focus and ambiguous focus are
+refused. The owner acquires the one page and native window before untrusted
+navigation. The driver never chooses another tab or brings one to the front.
+Focus can change between protocol messages; this is not atomic element-targeted
+input or a general multi-window driver.
+
+Address-bar text is admitted only after an explicit Ctrl+L action, uses printable
+ASCII, and repeats that chord after checking the owned active window. Unicode
+or control characters in browser chrome are refused. Clicking an arbitrary
+chrome field does not authorize text entry there. Content insertion is browser
+text/IME insertion, not a stream of physical key presses; keyboard shortcuts
+remain native. There is no alternate-route fallback after a failed insertion.
+
+Direct native Unicode typing and a one-transfer clipboard helper were rejected
+by exact Chromium field readback. Successful process or clipboard transfer
+acknowledgements did not establish successful application input. The supported
+text paths likewise need application readback to establish task outcomes.
+
+Native children use fixed paths and a minimal explicit environment. Operator
+credentials and inherited Xauthority are not forwarded. Native address-bar text travels over the
+helper's stdin; web text travels over the private browser pipe, never a shell. Helpers have bounded deadlines and output;
+raw diagnostic text is never returned as an executor error. Only an acquired,
+still-live child handle authorizes termination. If capture-helper exit cannot
+be confirmed, its private files stay for runtime-owner reclamation.
+
+## Build and proof
+
+The source-only [guest recipe](https://github.com/danielgwilson/humanish/blob/main/runtime/browser-guest/README.md) builds a
+pinned Debian/Chromium/Xvfb development base with package/source references and
+notices. It is not a redistributed release image or a VM qualification receipt.
+A native ARM64 build and its exact browser behavior are separate from amd64.
+
+After building the development image and JavaScript, run the scoped native proof
+with its exact local image ID:
+
+```sh
+HUMANISH_GUEST_IMAGE=sha256:<image-id> pnpm guest-desktop:proof
+```
+
+This launches an ordinary disposable container with no network, host mounts or
+host devices. Chromium retains its sandbox. The harness downloads and verifies
+the hash-pinned upstream Playwright Docker seccomp profile, which permits the
+user namespaces needed by that sandbox. This container configuration is a test
+environment, not the proposed Firecracker boundary. The harness retains failed
+attempts, full-frame captures, synthetic app readback and exact-container cleanup
+under ignored `.humanish/guest-desktop-proof/`.
+
+The proof covers visible browser chrome, address-bar navigation, Unicode and
+rapid/large/stalled-renderer text insertion, page/focus rejection, pointer and
+keyboard input, native scrolling and cancellation. CI reruns this proof for
+changes to the guest driver, image recipe, protocol or dependency lockfile. Its deterministic fixture is not a model participant,
+a run bundle, a host network policy, an independent watchdog or a Linux/Mac
+installed study. Those remain separate gates before local runtime support.

package/docs/architecture/local-browser-runtime.md

@@ -0,0 +1,100 @@
+# Local browser studies
+
+Linux x64 users can run isolated Firecracker browser participants from the
+installed CLI or TUI. Docker manages their containers and private state volumes;
+the normal study runner supplies scheduling, recordings, Observer and findings.
+No separate host service is installed.
+
+## Start a study
+
+Prerequisites: a local, rootful Docker Engine; Linux KVM (`/dev/kvm`) and TUN
+(`/dev/net/tun`); and a signed-in, supported Codex CLI. See
+[Codex account setup](restricted-codex-analysis.md) for the qualified version
+and account restrictions. Docker access is an administrative capability.
+Humanish does not install Docker or change host permissions.
+
+Start your app on loopback, then save a lab such as
+`.humanish/labs/local-browser.yaml`:
+
+```yaml
+schema: humanish.lab.v2
+id: local-browser
+title: Review the note editor
+subject:
+  source: app-url
+  appUrl: http://127.0.0.1:3000
+actors:
+  - type: local-agent
+    localAgent: codex
+    count: 2
+    mission: Create a note and explain anything confusing about saving it.
+scenario:
+  mode: live
+execution:
+  target: local
+  concurrency: 2
+  timeoutMs: 120000
+```
+
+```sh
+npx humanish init --yes
+npx humanish runtime status --json
+npx humanish doctor --lab .humanish/labs/local-browser.yaml --json
+npx humanish lab run .humanish/labs/local-browser.yaml
+```
+
+The first live run downloads the pinned runtime archive (about 569 MiB), verifies
+its exact size and SHA-256, and loads it into Docker. Later runs reuse the image.
+`humanish runtime setup` prepares it in advance. Status, doctor and dry-run never
+download an image or launch a participant. Preparation does not consume the
+participant's task-time budget. The TUI lists the same lab and runtime readiness;
+starting it uses the same preparation and execution path.
+
+This configuration needs neither an E2B key nor an OpenAI API key. Participants
+and the separate post-run analyst use Codex account quota and **remote model
+inference**. It is not an offline model. The restricted participant has no host
+shell, checkout mount or credential files. Account dollar cost and output-token
+ceilings are unknown; numeric dollar/token caps are rejected. Set
+`review.analysis: false` to skip analysis.
+
+For API billing and its supported caps, use `type: openai-computer-use`, remove
+`localAgent`, and provide `OPENAI_API_KEY`. Its analysis retains the existing API
+default. Neither path silently falls back to another provider or hosted desktop.
+Existing labs without `execution.target: local` retain their previous behavior.
+
+## Current limits
+
+- Linux x64 only. Mac/Lima setup is a separate follow-up.
+- A local Docker Engine; remote contexts, rootless Docker and Docker Desktop
+  virtual machines are not supported by this host adapter.
+- Loopback HTTP(S) app URLs on explicit ports above 1023. Each participant can
+  reach its selected app port, plus public destinations over ordinary TCP/UDP.
+  Other private host/LAN destinations and cloud metadata are blocked.
+- Chromium at 960×720, 2 vCPUs and 2 GiB guest RAM per participant. Docker's
+  enclosing memory limit is 3 GiB. Start with a small concurrency for your host;
+  these allocations are not a promise of measured peak memory or capacity.
+- Browser-only. Inbox and camera/microphone declarations are rejected until
+  integrated. TAP/NAT networking preserves the path to optional media.
+- A 20-minute default and maximum participant session budget, within the runtime
+  image's 30-minute process lifetime. A shorter `execution.timeoutMs` is supported.
+- Codex participants currently use `gpt-6-astra` at low effort. Hosted templates,
+  device presets and hosted sandbox timeouts do not apply.
+
+Normal close removes the owned container and its private state volume. If the
+controller dies, the disconnected guest reboots, Firecracker exits and Docker
+removes both. A small host socket directory can remain after abrupt death.
+Run evidence remains in `.humanish/` under the normal local capture and sharing
+rules. An unconfirmed release is reported as such.
+
+## Runtime maintenance
+
+The npm build pins a release URL, byte count, SHA-256 and immutable Docker image
+ID in `src/local-runtime-release.ts`. It has no moving `latest` image dependency.
+Runtime releases include source archives and notices separately; study users do
+not download those archives. Updating a runtime requires a reviewed catalog
+change and a new CLI release.
+
+Source builders can use the
+[maintained recipes](../../runtime/local-firecracker/README.md) and set
+`HUMANISH_LOCAL_RUNTIME_IMAGE` to an already-built compatible local image. An
+invalid override fails; it does not cause an implicit registry pull.

package/docs/architecture/restricted-codex-analysis.md

@@ -0,0 +1,91 @@
+# Restricted Codex account analysis
+
+The optional account analyst uses a new Codex app-server process after participant
+execution, with a separate conversation, process and tool authority. It can use
+the same host Codex login as a local-agent participant. Existing API analysis
+remains a separate provider.
+
+The qualified launcher profile is **Codex CLI 0.154.0, Linux x64, file-backed
+ChatGPT login, `gpt-6-astra`, low reasoning effort**. Other versions/platforms,
+keychain-only logins and API-key Codex logins are refused before a model turn.
+Readiness validates the installation and effective profile without submitting a
+model turn; it does not guarantee current quota or model access.
+
+## Authority and request limits
+
+The host creates a private temporary Codex home and links only the existing
+`auth.json`. Humanish never reads or copies its values. The native CLI owns
+authentication and provider network traffic. Its environment excludes provider
+keys, target-app variables, alternate endpoints and operator configuration.
+The selected native binary is launched directly; npm wrappers are resolved to
+their native executable before launch.
+
+Before creating a thread, Humanish checks the effective config. Nonempty system
+settings, inherited instructions, MCP, plugins, hooks, alternate stores/endpoints
+and unsupported authority are rejected. The thread is ephemeral, has no runtime
+environments or workspace roots, and uses only the supplied text/images and
+closed output schema. No provider/model fallback is allowed.
+
+This profile is **not advertised as tool-free**. The CLI retains code-mode
+descriptions, but the qualified `features.code_mode_host=false` setting rejects
+their actual dispatch. `agents.enabled=false` removes delegation; the older
+feature toggle alone did not. Humanish also refuses raw tool calls, unexpected
+host RPCs and asynchronous question messages before accepting any report. The
+actual notification/denial captures and provenance are in
+[`tests/fixtures/restricted-codex`](https://github.com/danielgwilson/humanish/blob/46330116726f74080fa18947c36da4fb4b333805/tests/fixtures/restricted-codex/README.md).
+
+Each request owns a separate child process, temporary home and fresh thread;
+participant, analyst and readiness requests may run concurrently. An unresolved
+child process blocks new requests until its exit is confirmed. Each thread receives
+one turn. Evidence is not silently
+downselected: at most 128 images, 20 MiB decoded image data, and 32 MiB serialized
+request data are admitted. Generated report text is limited to 2 MiB. Raw input
+notifications echo image data URLs, so their frame budget is the larger of 2 MiB
+or the admitted serialized packet plus 1 MiB; total stdout is bounded separately
+at the larger of 8 MiB or twice that frame budget plus 4 MiB. Stderr is bounded at
+2 MiB and is not retained. Notifications are limited to 65,536; aggregate
+generated assistant-text deltas are independently limited to 2 MiB, regardless
+of the input-image wire budget. The request's
+deadline includes startup; individual RPCs also have a 15-second ceiling.
+
+Account analysis has unknown dollar cost and no supported generated-token cap.
+Numeric output-token caps are rejected. The integration must likewise reject
+numeric dollar caps for this provider. Known token usage is retained; missing or
+interrupted usage is unknown/partial, not zero. The ordinary analysis validator,
+source-integrity checks and narrative secret scrubber remain responsible for
+accepting and publishing the report.
+
+## Cancellation and auth recovery
+
+Cancellation interrupts the turn, then closes the directly owned native child
+and its stdio with bounded termination/kill waits. No stored PID or process group
+is signaled after exit. This proves the direct child's lifecycle, not arbitrary
+descendant-tree reclamation; process-spawning tools are outside this profile.
+If native closure cannot be confirmed, Humanish preserves its private state and
+blocks another session in the same process until that exact child closes.
+
+After confirmed closure, normal cleanup removes the owned auth symlink and
+temporary directory. It never deletes or overwrites the operator's original
+login. Unexpected replacement of the symlink is different: it might contain
+rotated auth state. Humanish preserves that private file with mode 0600 inside a
+0700 task home, removes other scratch/evidence, refuses the report, and returns
+`codex_cleanup_failed`. It does not copy the replacement into the original
+login, which could overwrite a newer concurrent login.
+
+Local recovery markers live under
+`$XDG_CACHE_HOME/humanish/codex-analysis-recovery/`, or
+`~/.cache/humanish/codex-analysis-recovery/`. A marker contains only the generated
+task directory name and fixed file names. Find that same directory under the
+system temporary directory (`$TMPDIR` when configured); retained login state is
+inside `home/auth.json`. Do not discard a retained replacement before recovering
+the login. Run `codex login` before retrying if the persistent login is no longer
+usable. Actual private paths and credentials are never included in an analysis
+artifact. An unconfirmed-process marker instead means the private directory is
+retained until the process lifecycle can be inspected safely.
+
+Qualification used short, existing-login calls; it did not force token refresh.
+The available Codex file-store source writes through the auth path, but matching
+binary refresh behavior and concurrency with unrelated Codex applications are
+not established by that proof. Recovery deliberately fails closed if storage
+behaves differently. Keychain/other-platform support and whole-process-tree
+leases require their own qualification.

package/docs/architecture/runtime-broker-core.md

@@ -0,0 +1,30 @@
+# Runtime broker authority core
+
+The source-only [broker core](https://github.com/danielgwilson/humanish/blob/main/runtime/broker/README.md)
+defines bounded requests and lease decisions for a future Linux runtime owner.
+It is not an installed service, resource controller, or public runtime mode.
+
+Requests cannot supply host paths, service names, commands, user identities,
+resource limits or cleanup claims. The future transport obtains the peer UID
+from the operating system and checks it against owner policy. A separate
+generation capability authorizes each study; default diagnostics and serialized
+ledgers omit the raw capability. Repeating an acquisition or allocation attempt
+does not mint a second resource.
+
+The model reserves capacity through uncertain creation and cleanup. Expiry,
+revocation, detected sleep and host-clock discontinuity cannot be undone by a
+late renewal. A saved launch plan is not dispatch authority: the owner must
+revalidate it immediately before starting a resource. Only a separate owner
+attestation that creation has settled and the acquired resources are absent can
+free a reservation. Recovery reads the ledger for reconciliation, never to resume
+a study or adopt resources by their names.
+
+The owner must persist intent before consuming effects, advance trusted time
+independently of requests, and bind every resource to actual acquired OS
+identities. The pure model does none of those OS operations. Its tests establish
+protocol and state transitions; they do not establish peer authentication,
+durable writes, process containment, watchdog timing, sleep detection or cleanup.
+
+Installation, root-owned storage, authenticated sockets, service supervision,
+artifact verification and VM/network control require separate implementation
+and privileged qualification. The existing npm execution routes are unchanged.

package/docs/contracts/schemas.md

@@ -3,7 +3,7 @@
 Date: 2026-06-02 (current-state note updated 2026-07-14)
 
 Status: reference map for the major contracts shipped through source version
-`0.96.1`; it is not an exhaustive inventory of command/result envelopes. Exported types,
+`0.98.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.

package/docs/contracts/study-analysis.md

@@ -22,10 +22,10 @@ not a participant study. Here, `analyze --dry-run` means checking an existing
 study's input and admission estimate without credentials, a provider request,
 or a new analysis artifact.
 
-The default model is `gpt-6-astra`, with high reasoning effort. A request sends selected retained text and
+The default provider is `openai`; its default model is `gpt-6-astra`, with high reasoning effort. A request sends selected retained text and
 captures to OpenAI, without tools, redirects, provider-side response storage, or
 automatic retries. `--question` adds a reviewer question; it never changes the
-participant assignment. `--max-cost` is required, including for dry-run
+participant assignment. For OpenAI API analysis, `--max-cost` is required, including for dry-run
 admission. It bounds a conservative estimate, not an exact provider bill.
 `--timeout-ms` and `--max-output-tokens` bound the request. An exceeded admission
 estimate retains valid findings and usage but returns a partial result and a
@@ -48,6 +48,48 @@ success. Findings keep reported concerns and observed recovery distinct across
 participants. Other supported models can be selected explicitly, but evidence
 reference validation does not certify their interpretation of small visual details.
 
+## Explicit Codex account analysis
+
+An existing completed recording can use a separate restricted Codex analyst:
+
+```bash
+humanish analyze --run latest --provider codex --dry-run --json
+humanish analyze --run latest --provider codex --json
+```
+
+This branch is qualified on Linux x64 with Codex CLI `0.154.0`, a file-backed
+ChatGPT account login, and `gpt-6-astra` with low reasoning effort. The participant conversation
+is never reused. Selected text and screenshots still go to remote inference;
+this is account authentication, not local inference. No API-key, alternate model
+or configured-provider fallback occurs. Model access and account allowance are
+not established by installation or login alone. Keychain-only login, other
+platforms and CLI versions are refused before a turn; they are not silently
+converted to API authentication.
+
+Omit `--max-cost` and `--max-output-tokens` for Codex. Numeric declarations are
+rejected because this transport does not enforce them. `maxCostUsd` and
+`maxOutputTokens` are stored as null. The existing evidence bounds, one analyst
+turn, bounded response bytes and whole-operation timeout still apply. One turn
+is not a claim of one upstream billed request; account limits apply. Reported
+tokens remain inspectable, but dollar estimates, admission dollars and rate dates
+remain null. Interrupted token observations remain explicitly incomplete.
+
+The dry-run validates only local evidence and configuration. It does not check
+the CLI, login, model access or quota and does not start a provider request.
+`doctor --lab <lab>` checks the selected analyst setup without a model call.
+Failures leave the recording available; inspect `analyze show` and the attempt's
+accounting before an explicit `analyze --provider codex --rerun`.
+
+The persisted identity is the required qualified execution profile: transport,
+authentication and billing class, requested and required resolved model, effort,
+tool-policy revision and CLI version. The launcher must confirm it before the
+turn. A failed pre-dispatch attempt does not prove the CLI or model was observed.
+These fields participate in the configuration digest, preventing reuse across
+providers or changed execution policies. Historical API configurations, hashes
+and corrections are read without inserting new defaults.
+
+## Evidence interpretation
+
 Analysis distinguishes participant actions from harness setup and accounting.
 Runtime credentials or model usage do not establish that a participant made an
 external call while performing their task. Observations with an action basis