humanish 0.97.0 → 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/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

@@ -34,8 +34,10 @@ 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).
 
-There is one active analyst/readiness session per Humanish process, across all
-provider factories. One fresh thread receives one turn. Evidence is not silently
+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

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.97.0`; 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/goals/current.md

@@ -1,9 +1,9 @@
 # Current Goals
 
-Status date: 2026-09-23. Release baseline: `0.97.0`.
+Status date: 2026-09-24. Release baseline: `0.98.0`.
 
 This page guides work on current merged source. Published behavior is described
-in the [release notes](../release/0.97.0-codex-account-analysis.md).
+in the [release notes](../release/0.98.0-local-browser-studies.md).
 The [September 9 history](https://github.com/danielgwilson/humanish/blob/main/docs/goals/current-history-2026-09-09.md)
 preserves the former status log; its queues do not supersede this page.
 
@@ -88,7 +88,7 @@ requires decision-equivalent retained evidence and a real deletion branch.
 No first-party deletion branch has met that gate. Public demonstrations do not
 substitute for it.
 
-## Current Program Truth (source `0.97.0`)
+## Current Program Truth (source `0.98.0`)
 
 | Surface | Available in merged source | Remaining boundary |
 | --- | --- | --- |
@@ -107,13 +107,24 @@ substitute for it.
 Use the [task support matrix](../architecture/task-protocol-support.md),
 [actor registry](https://github.com/danielgwilson/humanish/blob/main/src/actor-registry.ts)
 and [CLI reference](https://humanish.dev/docs/cli) when choosing a concrete path.
-Source behavior and required tests outrank stale status prose.
+Source and tests establish observed behavior. Resolve conflicts with requirements
+explicitly; neither stale status prose nor a passing test makes a bug correct.
 
 The library-assisted `local-app` route now includes a
 [runnable npm example](../architecture/examples/state-driven-local-app/README.md).
 Its deterministic provider demonstrates the integration with a real loopback
 app; it does not establish persona effectiveness or independent adoption.
 
+The [local browser runtime](../architecture/local-browser-runtime.md)
+runs isolated Linux browser participants through the same scheduler, recordings
+and automatic analysis as hosted studies. It uses Docker-owned resources and
+ordinary TAP/NAT networking. Continue managed-local work from this complete study
+path; the earlier offline owner/service qualification experiments are historical
+fixtures, not an installation architecture or a prerequisite queue. Explicit
+Linux local labs now use the installed CLI/TUI, with a verified runtime download
+before the first live run. Mac support, inbox integration and optional media
+remain unfinished. Existing hosted labs retain their behavior.
+
 ## Gates And Deferred Work
 
 - Live OSS meta-lab execution remains disabled until repository-derived
@@ -135,10 +146,12 @@ app; it does not establish persona effectiveness or independent adoption.
 Follow [AGENTS.md](../../AGENTS.md), the [invariants](../principles/invariants-and-defaults.md)
 and the [public-readiness standard](../release/public-readiness-standard.md).
 
-- Keep `main` clean and work on scoped branches/worktrees. Substantial work
-  needs an issue with scope, authority, required proof and stop conditions.
+- Keep `main` clean and work on scoped branches/worktrees. Keep the task's scope,
+  authority, relevant checks and material failure boundaries in its issue, PR or
+  current handoff; do not create a separate packet for routine work.
 - Existing explicit shipping authority governs implementation and merge;
-  otherwise issue readiness does not create authority by itself.
+  otherwise issue readiness does not create authority by itself. Machine-readiness
+  fields gate automated queue pickup, not directly assigned interactive work.
 - Never commit secrets, private transcripts/screenshots, customer data or
   private project context. Keep generated proof in ignored `.humanish/` and
   retain needed evidence before removing a worktree.
@@ -153,7 +166,10 @@ and the [public-readiness standard](../release/public-readiness-standard.md).
 
 ## Proof Before Shipping
 
-From a clean contributor worktree:
+Use the [verification guidance](../../AGENTS.md#verification): check the changed
+behavior and material risks, then stop unless new evidence warrants more work.
+Required CI remains the merge gate. For a release, run the full release gates
+from a clean contributor worktree:
 
 ```bash
 pnpm install --frozen-lockfile

package/docs/product/open-source-install-experience.md

@@ -235,3 +235,10 @@ them should install `@e2b/desktop` explicitly instead of receiving that
 substrate as part of the default Humanish package install. When a GitHub token is
 present, repo labels are redacted in durable artifacts by default; live stream
 auth URLs are used only by the attached watch server and are not persisted.
+
+An explicitly selected [local browser lab](../architecture/local-browser-runtime.md)
+can instead use Linux x64, Docker/KVM and an existing Codex ChatGPT login for
+participants and findings. The installed CLI prepares its pinned image before
+the first live run. It does not install host prerequisites, and Mac, inbox and
+media integration remain separate follow-ups. Existing hosted lab configuration
+is preserved.

package/docs/ramp/README.md

@@ -2,7 +2,7 @@
 
 Status: public-safe contributor and agent ramp.
 
-Package/source version in this tree: `0.97.0` (2026-09-23). The Observer is phone-usable as a stated requirement (observer/AGENTS.md); interactive primitives start from Base UI. The Observer renderer is the observer/ workspace artifact only; the legacy string-concat renderer was deleted at cutover (#426), and rollback is a version pin to 0.42.0. The containment boundary introduced in
+Package/source version in this tree: `0.98.0` (2026-09-24). The Observer is phone-usable as a stated requirement (observer/AGENTS.md); interactive primitives start from Base UI. The Observer renderer is the observer/ workspace artifact only; the legacy string-concat renderer was deleted at cutover (#426), and rollback is a version pin to 0.42.0. The containment boundary introduced in
 `0.15.1` remains in force: managed run and output paths bind to validated
 physical filesystem identities, and stored provider IDs are evidence, not
 cleanup authority. The bundled OSS meta-lab is dry-run only until
@@ -14,19 +14,26 @@ context.
 
 ## First Read
 
-Read these in order:
+Start with three things:
 
-1. [`AGENTS.md`](../../AGENTS.md) for public boundary and engineering rules.
-2. [`docs/principles/invariants-and-defaults.md`](../principles/invariants-and-defaults.md) — which rules are invariants and which are overridable defaults, each with the reason it exists and the check that enforces it. (The enforcement is what makes a rule real here — when a doc sentence and a test disagree, trust the test and say so.)
-3. [`README.md`](../../README.md) for install, commands, and package shape.
-4. [`docs/goals/current.md`](../goals/current.md) for the active product goal.
-5. [`docs/goals/proof-roadmap/goal.md`](https://github.com/danielgwilson/humanish/blob/main/docs/goals/proof-roadmap/goal.md) for the ratified proof architecture (repo-only; not shipped in the npm package, hence the absolute link).
-6. [`docs/product/open-source-install-experience.md`](../product/open-source-install-experience.md) for first-run UX.
-7. [`docs/roadmap/world-class-open-source-v0.md`](../roadmap/world-class-open-source-v0.md) for staged delivery history (historical; see its status banner).
-8. [`docs/architecture/observer.md`](../architecture/observer.md) for Observer architecture.
-9. [`docs/contracts/run-bundle.md`](../contracts/run-bundle.md) and [`docs/contracts/policy.md`](../contracts/policy.md) for proof contracts.
-10. [`docs/release/public-readiness-standard.md`](../release/public-readiness-standard.md) before deciding what must be scrubbed.
-11. [`docs/release/open-source-readiness.md`](../release/open-source-readiness.md) before touching public packaging or repository visibility.
+1. [`AGENTS.md`](../../AGENTS.md) for engineering judgment and public boundaries.
+2. The current task and [`docs/goals/current.md`](../goals/current.md) for current
+   product status. Explicit task direction takes precedence over historical queues.
+3. Instructions in the component being changed, then its relevant contracts.
+
+Use the references below as needed. Historical plans are context, not a backlog
+to resume automatically. Keep one concise current task handoff with the requested
+outcome, demonstrated behavior, next complete result, constraints and rejected or
+deferred approaches; link evidence rather than repeating its chronology.
+
+| When working on | Reference |
+| --- | --- |
+| Install, commands or first-run UX | [`README.md`](../../README.md), [install experience](../product/open-source-install-experience.md) |
+| Security, evidence handling or defaults | [Invariants and defaults](../principles/invariants-and-defaults.md) |
+| Observer | [Observer architecture](../architecture/observer.md) and its component instructions |
+| Bundle formats or policy | [Run bundle](../contracts/run-bundle.md), [policy](../contracts/policy.md) |
+| Public artifacts or packaging | [Public-readiness standard](../release/public-readiness-standard.md), [release procedure](../release/open-source-readiness.md) |
+| Proof architecture or historical decisions | [Proof roadmap](https://github.com/danielgwilson/humanish/blob/main/docs/goals/proof-roadmap/goal.md), [historical delivery roadmap](../roadmap/world-class-open-source-v0.md) |
 
 ## Mental Model
 
@@ -47,6 +54,10 @@ If a change does not improve one of those loops, it probably belongs elsewhere.
 
 ## Current State
 
+The [0.98.0 release note](../release/0.98.0-local-browser-studies.md) describes
+installed Linux browser studies with managed runtime images, Codex account
+participants and automatic analysis, and shared CLI/TUI setup checks.
+
 The [0.97.0 release note](../release/0.97.0-codex-account-analysis.md) describes
 explicit Codex account analysis on a qualified Linux CLI/login profile, with
 separate analyst authority, evidence-linked reports and unknown-dollar accounting.

package/docs/release/0.98.0-local-browser-studies.md

@@ -0,0 +1,31 @@
+# 0.98.0 — Local browser studies on Linux
+
+Explicit local browser labs now run from the installed CLI and TUI. On Linux
+x64 with Docker/KVM and a supported Codex ChatGPT login, isolated Firecracker
+participants use the normal scheduler, recordings, Observer and automatic
+analysis without E2B or OpenAI API keys. Codex inference remains remote and
+consumes account quota; dollar cost is unknown.
+
+`humanish runtime setup` prepares a pinned, verified runtime image. A live local
+lab also prepares it automatically before starting participants. `runtime status`
+and `doctor --lab` inspect readiness without downloading or launching a browser.
+The TUI shows that same runtime status. Existing hosted labs retain their
+configuration, and a missing local prerequisite never selects another provider.
+
+The [setup guide](../architecture/local-browser-runtime.md) includes a complete
+manifest and the current limits. This release supports loopback apps, fixed
+960×720 Chromium desktops, and optional OpenAI API participants. Mac/Lima,
+local inboxes and local camera/microphone integration remain follow-ups.
+
+Private state uses a Docker-owned anonymous volume, removed with its container
+on normal close or controller death. Runtime image downloads are checked for
+exact size and SHA-256 before loading; matching source archives and notices
+are distributed separately.
+
+Validation includes a packed installation outside the checkout: two concurrent
+Codex participants saved distinct notes in a local app, the app confirmed both
+saves, the recordings verified, and automatic analysis completed without model
+or desktop API keys. Separate checks cover controller death and state-volume
+removal, download integrity/cancellation, missing prerequisites and preserving
+existing hosted configurations. This is a small Linux integration proof, not
+a claim about Mac readiness, high concurrency or real conferencing apps.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanish",
-  "version": "0.97.0",
+  "version": "0.98.0",
   "description": "Open-source-safe CLI for persona simulation, observer review, and public-safe feedback drafts.",
   "author": "Daniel G Wilson <daniel@danielgwilson.com>",
   "keywords": [
@@ -76,13 +76,15 @@
     "tui:smoke": "node scripts/tui-smoke.mjs",
     "tui:test": "pnpm --filter humanish-tui test",
     "release:dogfood": "node scripts/release-dogfood.mjs",
+    "browser-control:proof": "node scripts/browser-control-proof.mjs",
     "docs:generate": "tsx scripts/generate-cli-docs.ts",
     "docs:check": "tsx scripts/generate-cli-docs.ts --check",
     "observer:browser:proof": "node scripts/observer-browser-proof.mjs",
     "observer:iframe:proof": "node scripts/observer-iframe-proof.mjs",
     "observer:chrome:proof": "node scripts/observer-chrome-proof.mjs",
     "observer:reliability:proof": "node scripts/observer-reliability-proof.mjs",
-    "tui:connections:proof": "python3 scripts/tui-connections-proof.py"
+    "tui:connections:proof": "python3 scripts/tui-connections-proof.py",
+    "guest-desktop:proof": "node scripts/guest-desktop-proof.mjs"
   },
   "repository": {
     "type": "git",

package/skills/humanish/SKILL.md

@@ -95,9 +95,10 @@ exact returned path, not a basename that could resolve to another manifest.
 
 ## Choosing a findings analyst
 
-Analysis is separate from the participant. Existing manual and automatic defaults
-use the OpenAI API with its own admission budget; a local-agent participant does
-not change that default. To use the restricted Codex ChatGPT account analyst,
+Analysis is separate from the participant. Hosted and manual defaults use the
+OpenAI API with its own admission budget. An explicitly local browser study with
+a Codex participant defaults to a separate Codex account analyst. To select that
+restricted Codex ChatGPT account analyst on other supported studies,
 set `review.analysis.provider: codex` or pass `analyze --provider codex` on a
 completed recording. This uses remote inference and the qualified CLI/login,
 not local inference or the participant's existing conversation. See
@@ -112,6 +113,25 @@ local evidence/configuration only; `doctor --lab` checks setup without a model
 request. Inspect a failed attempt before explicitly retrying `--provider codex
 --rerun`. Opening Observer never starts analysis.
 
+## Local browser setup
+
+On Linux x64 with a local rootful Docker Engine, KVM and TUN, an `app-url` lab can
+set `execution.target: local` and `actors[0].type: local-agent` with
+`localAgent: codex`. It uses the supported Codex ChatGPT login, not E2B or an
+OpenAI API key. Inference is remote and consumes account quota. Existing hosted
+labs stay hosted; never silently change their execution or billing provider.
+
+Use `humanish runtime status --json` and `humanish doctor --lab <path> --json`
+for read-only setup inspection. `humanish runtime setup` downloads and verifies
+the pinned runtime; a live local run also prepares it automatically. The normal
+`humanish lab run <path>` command and TUI use the same study runner and Observer.
+See [the complete example and limits](../../docs/architecture/local-browser-runtime.md).
+
+Local browsers currently require a loopback app URL with an explicit port above
+1023, use a 960×720 Chromium desktop, and reject inbox/media declarations. Mac
+setup is not integrated. Do not claim that installing the CLI also installs
+Docker or makes these prerequisites available.
+
 ## Format Stack
 
 When creating or editing Humanish files: