humanish 0.96.1 → 0.98.0

package/docs/goals/current.md

@@ -1,9 +1,9 @@
 # Current Goals
 
-Status date: 2026-09-21. Release baseline: `0.96.1`.
+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.96.1-browser-navigation.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.96.1`)
+## Current Program Truth (source `0.98.0`)
 
 | Surface | Available in merged source | Remaining boundary |
 | --- | --- | --- |
@@ -99,7 +99,7 @@ substitute for it.
 | Shared state | Sequential and concurrent single-origin shared-world studies with retained evidence | Multi-origin implementation remains gated; concurrent state change does not establish per-action causation |
 | Observer | Live/recorded views, shared grid and participant playback, participant assignments, action-specific links, saved moments, zoom, comparison and phone-width review | Sparse captures cannot prove every action's effect; visual comparison alone is not a controlled experiment |
 | Review and feedback | Verification grades, feedback drafts, portable HTML, redacted bundle derivatives and computer-use completion-source labels | Sharing requires the appropriate grade; participant reports and condition matches still need task adjudication |
-| Study findings | Default post-run analysis on supported live routes with a separate disclosed $3 admission estimate limit and opt-out; explicit `analyze`, fairer evidence selection, concern review and versioned findings with exact source links | Model interpretation needs review; bounded selection and source truncation limit coverage; opening Observer never dispatches analysis |
+| Study findings | Default post-run analysis on supported live routes with a separate disclosed $3 admission estimate limit and opt-out; explicit `analyze`, fairer evidence selection, concern review and versioned findings with exact source links; explicit restricted Codex account analysis on the qualified Linux profile | Account dollars/output-token caps are unavailable; Mac/keychain/other CLI profiles are unqualified. Model interpretation needs review; selection limits coverage; opening Observer never dispatches analysis |
 | TUI and serving | Detached starts, run stopping, reclamation, Observer attachment, loopback serving, run library and AgentMail setup, authentication and lab configuration | Stopping a process does not itself prove sandbox cleanup; TUI views over CLI `stats`/`export` remain follow-ups |
 | Off-app communication | Recipient-scoped local capture and fresh real AgentMail receiving, supported inline raster images, bounded collection and host-owned recovery | Real mail uses isolated participant surfaces and remains local-only for publication. Hosted mail/model processing, bounded fidelity and interrupted-run recovery are explicit; local-agent, borrowed inboxes and SMS are unsupported |
 | Mobile and media | Hosted viewport/emulation, desktop geometry checks, bounded dwell and declared camera feed; a synthetic video-only call with separate hosted peers is proven | Audio, TURN, provider-specific rooms, physical-device and touch fidelity remain unproven; unsupported media declarations are rejected |
@@ -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/automatic-analysis.md

@@ -22,7 +22,7 @@ review:
 
 Omitting `review.analysis` uses these defaults. Set `review.analysis: false` to
 run participants without the additional analysis request. An explicit analysis
-mapping requires `maxCostUsd`. This limits an admission estimate, not the
+mapping using the default OpenAI API provider requires `maxCostUsd`. This limits an admission estimate, not the
 provider's final bill, and is separate from participant spending limits. Analysis
 can decline a large study before dispatch when its conservative estimate exceeds
 that limit. Use `analyze --dry-run --max-cost <usd>` on retained evidence to inspect
@@ -37,6 +37,27 @@ its existing authentication boundary. Review the separate analysis budget before
 zero-dollar cap does not cap post-run analysis. The bundled first-contact
 zero-spend product fixture explicitly disables analysis.
 
+To explicitly use your Codex ChatGPT account for the separate analyst:
+
+```yaml
+review:
+  analysis:
+    provider: codex
+    model: gpt-6-astra
+    timeoutMs: 600000
+```
+
+This requires Linux x64, qualified Codex CLI `0.154.0`, and a file-backed ChatGPT account login; the analyst
+uses low reasoning effort and remote inference. Dollar cost and a provider
+enforced output-token ceiling are unknown, so omit `maxCostUsd` and
+`maxOutputTokens`. Numeric values are rejected before participant resources are
+allocated. There is no API fallback. Missing or unsupported account setup leaves
+an explicit failed analysis state and the original recording intact. Use
+`humanish doctor --lab <lab>` for setup checks; account allowance and model access
+remain untested until a request. An omitted provider still means OpenAI, including
+hosted studies whose participant uses a local Codex or Claude login. This setting
+does not enable managed local desktops.
+
 The same configuration works through `humanish run <lab>`, `lab run <lab>`,
 `watch <lab>`, and TUI live starts. Direct library calls to the five recording
 producers honor it too. Supported routes are computer-use, scripted-browser,
@@ -53,7 +74,7 @@ Default analysis also skips recordings containing only setup or failure records
 with no retained participant activity. A desktop startup failure does not start
 an analysis request. The original failure remains visible.
 
-CLI live starts disclose the separate admission estimate limit before execution.
+CLI live starts disclose the selected analyst and its separate admission estimate limit or unknown account dollars before execution.
 `humanish lab preflight <lab> --json` and the TUI lab screen also expose the
 resolved budget without dispatching analysis. Library callers can inspect
 `resolveAutomaticAnalysis` or `automaticAnalysisBudget` before running.
@@ -64,7 +85,7 @@ existing job and does not start another request. Concurrent or repeated automati
 invocations cannot silently retry a paid attempt. If a process disappears while
 an attempt is in flight, its state can be unknown rather than falsely complete.
 Use manual `humanish analyze --run <exact-run-id> --max-cost 3` for an intentional
-follow-up after inspecting the existing attempt and its accounting.
+follow-up after inspecting the existing attempt and its accounting. For the account branch, use `humanish analyze --run <exact-run-id> --provider codex --rerun` without a dollar limit.
 
 Stopping participant execution does not start a fresh automatic analysis. A
 recorded harness cancellation is skipped; ordinary time limits and participant

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.96.1` (2026-09-21). 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,16 @@ 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.
+Existing API defaults remain unchanged; managed local desktops and Mac account
+analysis are not qualified by this release.
+
 The [0.96.1 release note](../release/0.96.1-browser-navigation.md) describes
 accurate physical browser measurements and bounded fitting that preserves normal
 browser controls when they fit. Narrow screens retain the fullscreen fallback.

package/docs/release/0.97.0-codex-account-analysis.md

@@ -0,0 +1,45 @@
+# 0.97.0 — Codex account reports on Linux
+
+Saved studies can use an existing Codex ChatGPT login for their separate
+findings report. Select it explicitly:
+
+```bash
+humanish analyze --run latest --provider codex --dry-run
+humanish analyze --run latest --provider codex
+```
+
+For an automatic report after a live study, set:
+
+```yaml
+review:
+  analysis:
+    provider: codex
+```
+
+The initial qualification is Linux x64, Codex CLI 0.154.0, a file-backed
+ChatGPT login, and `gpt-6-astra` with low reasoning effort. Other platforms,
+CLI versions and keychain-only logins are refused. Selected evidence still goes
+to remote inference. Model access and account allowance depend on the account.
+
+Account dollars and the generated-token ceiling are unknown; numeric dollar or
+output-token caps are rejected. Time and byte limits still apply. Token counts
+are retained when available, and interrupted usage remains incomplete. Existing
+OpenAI API analysis defaults and participant setup requirements are unchanged.
+
+The analyst has its own conversation and restricted tool configuration.
+Evidence admission, exact source references, secret scrubbing, immutable attempt
+accounting and source-change checks apply to both providers. Cancellation
+preserves recordings and earlier valid findings. Unconfirmed process cleanup or
+unexpected replacement credentials produce a failed attempt and private recovery
+guidance. Historical reports remain readable as execution profiles evolve.
+
+Doctor checks the selected analyst's setup without a model turn. Dry-run checks
+local evidence and configuration only; it does not test CLI/login/model access.
+The CLI, TUI and Observer disclose account limits consistently. This release
+does not introduce managed local desktops or qualify Mac account analysis.
+
+The [qualification receipt](https://github.com/danielgwilson/humanish/blob/46330116726f74080fa18947c36da4fb4b333805/docs/goals/computer-use-actor/receipts/codex-account-analysis-2026-09-23.md)
+records real screenshot analysis, cache reuse, cancellation, automatic reports
+after desktop cleanup, desktop/phone evidence review, failures and proof limits.
+See [configuration](../product/automatic-analysis.md) and the
+[restricted launcher contract](../architecture/restricted-codex-analysis.md).

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.96.1",
+  "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

@@ -93,6 +93,45 @@ exact returned path, not a basename that could resolve to another manifest.
    - keep `.env.example` commit-safe and value-free;
    - never commit generated run bundles.
 
+## Choosing a findings 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
+[the analysis contract](../../docs/contracts/study-analysis.md) for the current
+CLI/model qualification and setup limits.
+
+Do not pass numeric `maxCostUsd`/`maxOutputTokens` or their CLI flags to the
+account branch. It cannot enforce those ceilings and rejects them. Account dollar
+cost remains unknown even when token usage is reported. There is no fallback to
+an API key or another provider. `analyze --dry-run --provider codex` validates
+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: