humanish 0.97.0 → 0.99.0

package/docs/release/0.99.0-local-browser-mac.md

@@ -0,0 +1,34 @@
+# 0.99.0 — Local browser studies on Apple Silicon Macs
+
+Explicit local browser labs now run on M3-or-newer Macs through Lima/VZ and
+ARM64 Firecracker desktops. The same scheduler, Observer recordings and automatic
+analysis used on Linux remain in place. Codex and its file-backed ChatGPT login
+stay on the Mac; E2B and OpenAI API keys are unnecessary for the account route.
+Inference remains remote and uses account quota, with unknown dollar cost.
+
+Install Lima 2.2 or newer and use native ARM64 Node. `humanish runtime setup`
+creates a dedicated Linux host, installs Docker there and downloads the pinned
+ARM64 image with size/hash verification. Docker Desktop is not required. The
+first live local run can perform the same setup; status and doctor remain
+read-only. See the [setup guide](../architecture/local-browser-runtime.md).
+
+The host mounts no Mac directories. Standard OpenSSH forwards browser control
+and the selected loopback app port. Each participant retains its own VM and
+private state volume. Closing a study removes participant resources and keeps
+the reusable Lima host; `limactl stop humanish-runtime` stops it when idle.
+Native Codex discovery also handles hoisted npm packages correctly.
+
+An installed candidate on an M5 Max passed first-attempt public runtime setup,
+cache reuse and a two-participant study with distinct app-side saves, overlapping
+sessions, verified recordings and complete automatic analysis. Established Mac
+desktop close/cancel/controller-death cleanup passed. Focused real Linux checks
+of the shared lifecycle cover cancellation after creation and after start but before guest readiness, plus
+recovery when Docker creates a container but its reply is lost; Lima cleanup has
+separate regression coverage. These are scoped observations, not a capacity or
+cold-install performance benchmark.
+
+This remains browser-only with explicit lab configuration. Local inboxes,
+camera/microphone support and simpler default onboarding follow separately.
+Larger cohorts, smaller/Intel Macs, sleep/wake, keychain-only login, full-study
+cancellation and forced controller death during startup remain unqualified.
+Existing Linux and hosted labs retain their configuration and providers.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanish",
-  "version": "0.97.0",
+  "version": "0.99.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: