humanish 0.139.1 → 0.141.0

package/docs/architecture/observer.md

@@ -159,9 +159,13 @@ allowlist, contained file reads, read-only routes and no-store security headers.
 Served data may also include `runtime` with `state`, `observedAt`, and
 `source: "local-run-status"`. This is a current observation of a contained,
 matching `status.json`; it never changes the run's recorded verdict or participant
-outcomes. A fresh heartbeat means running, an explicitly finalized record means
-finished, a record the CLI's signal handler wrote means interrupted, and stale or
-invalid timing means unknown. Missing, malformed, or mismatched records omit the
+outcomes. A fresh heartbeat means running, a record its process wrote as `finished` means
+finished, a record written as `interrupted` (by the CLI's signal handler, by a run that ended
+without publishing, or by `humanish reclaim`) means interrupted, and stale or
+invalid timing means unknown. While the run's own process analyzes it after the run ended,
+`runtime.analysis` is `{ startedAt }`: the status band reads **Writing findings** and the
+Findings view shows the analysis as pending, with how long ago it started, before the analysis
+job exists. Missing, malformed, or mismatched records omit the
 observation. A stale heartbeat alone does not prove interruption, and stored PIDs
 are neither probed nor returned. Static rendering and export do not create this
 served-only observation.

package/docs/contracts/schemas.md

@@ -1411,9 +1411,9 @@ proof claims zero on a `null` line, or when known spend exceeds the declared cap
 
 `humanish.run-status.v1` is `status.json`, written inside each run directory by
 every route at run start, refreshed on a fixed cadence while the run is
-alive, and finalized when it ends: `{ schema, runId, state: running |
+alive, and rewritten when the run ends: `{ schema, runId, state: running |
 finished | interrupted, mode, study?, sandboxes?, pid, startedAt, updatedAt, completedAt?,
-signal?, outcome? }`. A record written by 0.108 or earlier also has `lab`, with the same value as
+signal?, reason?, outcome?, analysis? }`. A record written by 0.108 or earlier also has `lab`, with the same value as
 `study`, and readers accept it. `sandboxes: none` is written at run start by a route that has no
 way to create a sandbox for the run: a scripted run against an `app-url` subject. A run that may
 create one has no `sandboxes` field. `humanish reclaim` reports such a run `clean` with
@@ -1453,6 +1453,24 @@ with it at publish: false means some participant or desktop usage has no price
 and the estimate is a lower bound. A record without it, as every record before
 0.109, says nothing about completeness, and readers treat it as unknown.
 
+`finished` means the run published its bundle. A process that leaves the run without publishing
+one, as a route that throws or returns a refusal after the run started does, writes
+`interrupted` with `reason: no-publish` and no `signal`; humanish 0.139.1 and earlier wrote
+`finished` with no `outcome` there. `humanish reclaim --run <id>` (not `--check`) rewrites a
+`running` record whose heartbeat is stale as `interrupted` with `reason: reclaimed` and
+`completedAt` set to its last `updatedAt`, and reports `markedInterrupted: true`. Either way the
+run is excluded from a study's duration and cost medians, which count only finished runs. Readers
+older than `reason` read such a record as interrupted.
+
+`analysis` is added to a `finished` record when automatic analysis starts in the run's own
+process: `{ startedAt, endedAt?, state? }`. While it runs, the heartbeat refreshes `updatedAt`
+again; `completedAt` stays when the participants ended, so a run's duration excludes its
+analysis. When analysis ends, `endedAt` and `state` (the automatic analysis outcome's state:
+`complete`, `partial`, `failed`, `cancelled`, `skipped` or `unknown`) are written. An `analysis`
+without `endedAt` whose `updatedAt` is older than three touch intervals belonged to a process that
+stopped during analysis. `runAnalysisPhase` (`src/run/status.ts`) reads it as `running`,
+`stopped` or `ended`. Readers that predate the field ignore it.
+
 `interrupted` with `signal` (`SIGINT`, `SIGTERM` or `SIGHUP`) is written by
 the CLI's run command when that signal stops a live run outside post-run
 analysis. It first prints one line saying it is stopping and refuses any further sandbox
@@ -1496,7 +1514,10 @@ cheapest-source-first: the `status.json` record, else the bundle, else the run
 directory alone. `{ runId, derivedFrom: status | bundle | directory, liveness,
 mode?, pid?, study?, startedAt?, updatedAt?, completedAt?, verdict?, ok?,
 failure?, participants?, estimatedCostUsd?, estimatedCostComplete?,
-analysisCost?, durationMs? }`. `ok` and `failure` (the first execution failure)
+analysisCost?, durationMs?, analysis? }`. `analysis` is the status record's automatic analysis as
+`runAnalysisPhase` reads it, `{ state: running | stopped | ended, startedAt, endedAt?, outcome? }`;
+`humanish runs` and the TUI add `analyzing` or `analysis stopped` to the run's display from it, and
+`humanish runs --json` carries it on each run. `ok` and `failure` (the first execution failure)
 are the run's own outcome; `runDisplay` (`src/run/display.ts`) reads them with
 `liveness` and `verdict`, so the TUI and `humanish stats` show a run with
 `ok: false` as failed whatever its verdict. The point is cost: walking

package/docs/contracts/study-analysis.md

@@ -3,15 +3,16 @@
 Study analysis is an independent interpretation of retained participant evidence.
 It is separate from the participant's account, recorded outcome, and the run's
 deterministic review verdict. Opening an Observer never starts a provider request.
-Supported live runs request analysis on completion by default, with a separate
-$3 cap on its expected cost. Set `review.analysis: false` to disable that request;
-see [automatic analysis](../product/automatic-analysis.md).
+Supported live runs request analysis on completion by default. A study that declares no analyst
+gets the Codex account analyst when its participant is a Codex `local-agent`, and the OpenAI
+analyst with a separate $10 cap on its expected cost otherwise. Set `review.analysis: false` to
+disable that request; see [automatic analysis](../product/automatic-analysis.md).
 
 ## Invocation
 
 ```bash
-humanish analyze --run latest --max-cost 3 --dry-run --json
-humanish analyze --run latest --max-cost 3 --json
+humanish analyze --run latest --max-cost 10 --dry-run --json
+humanish analyze --run latest --max-cost 10 --json
 humanish observe --run latest
 humanish analyze list --run latest --json
 humanish analyze show --run latest --json
@@ -116,9 +117,11 @@ the current merge instructions, billed $1.92, most of its input served from the
 provider's prompt cache, and each of its 466 citations resolved. Two runs do not
 calibrate the merge request's estimate.
 
-## Explicit Codex account analysis
+## Codex account analysis
 
-An existing completed recording can use a separate restricted Codex analyst:
+A study whose participant is a Codex `local-agent` uses this analyst unless it declares another,
+and any study can select it with `review.analysis.provider: codex`. An existing completed
+recording can use it too:
 
 ```bash
 humanish analyze --run latest --provider codex --dry-run --json
@@ -421,7 +424,7 @@ It contains only the attempt/run IDs, input/config/source digests, prompt versio
 and timestamp. The live caller retains a binding to that exact directory and
 publishes the final receipt once. A start without usable final accounting means
 dispatch and spend remain unresolved; it is not proof that a provider charged.
-A cancellation before transport can finalize with `usage.dispatched: false`.
+A cancellation before transport can end with `usage.dispatched: false`.
 Admission refusals, missing credentials and rejected dispatch guards do not
 create a potentially paid attempt. Reuse does not create a new start.
 
@@ -486,7 +489,10 @@ The states without findings:
 - `skipped`: the automatic analysis was skipped or refused, for example without
   `OPENAI_API_KEY`, or the run's study file sets `review.analysis: false`
   (`AUTOMATIC_ANALYSIS_DISABLED`, read from the file when the view is built). `next` is
-  `analyze --max-cost 3`, which runs an analysis anyway. For an analysis refused for its
+  `analyze --max-cost 10`, which runs an analysis anyway. For a skip without `OPENAI_API_KEY`
+  on a machine where Codex is signed in with a ChatGPT account (read when the view is built),
+  `next` is `analyze --provider codex` and the message names `review.analysis.provider: codex`
+  in the run's study file; otherwise the message says to set the key. For an analysis refused for its
   cost, the message gives the expected cost, the worst case and the cap, and `next` sets
   `--max-cost` to the worst case rounded up.
 - `failed`: the latest attempt failed or was cancelled and no usable version exists. `next`

package/docs/principles/invariants-and-defaults.md

@@ -90,7 +90,7 @@ silently drifting from one is not.
 | Default                                     | Why it is the default                                                                                                                                                                                                                                               | Legitimate override                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Dry-run                                     | Spend safety (the live-spend rule sets the floor; dry-run keeps it far away)                                                                                                                                                                                        | `mode: live`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| Post-run analysis on supported live studies | Findings accompany the recording; a separate $3 cap on its expected cost is visible before execution                                                                                                                                                                | `review.analysis: false` disables it; an explicit mapping sets another analysis budget. Dry-run and unsupported routes never dispatch; missing default credentials produce a recorded skip                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| Post-run analysis on supported live studies | Findings accompany the recording; a Codex participant's run is analyzed by the same account, and otherwise a separate $10 cap on its expected cost is visible before execution                                                                                      | `review.analysis: false` disables it; an explicit mapping sets another analysis budget. Dry-run and unsupported routes never dispatch; missing default credentials produce a recorded skip                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | Separate worlds (`per-lane-worlds`)         | Isolation, attribution, reproducibility                                                                                                                                                                                                                             | `route: shared-world`: N participants against one mutable plane for scenarios that are about interaction between participants. Participants run at once, as many as `execution.concurrency` (two or more) and the E2B plan's limit allow, unless the study declares when each one starts (`participants[].startAfterMs`). The plane is one getHost-exposed subject sandbox with synthetic seeded data, or an operator-owned public deployment (external-public), driven by N actor sandboxes. The bundle declares the weaker `attributionClass: shared-world` and a verify-enforced `attributionLimits` ceiling (`best-effort-causal-attribution` and the rest of the concurrent set). Sequential turns at `execution.concurrency: 1` were removed in 0.106.0. |
 | External key placement                      | Smallest blast radius: when the keyed process (e.g. a computer-use provider loop) runs outside the sandbox, its key never enters                                                                                                                                    | In-sandbox placement when the keyed process runs inside (an agent harness under test); declared per actor type, with a spend budget                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | Loopback entry URLs                         | Public-safety: never drive third-party sites unbidden                                                                                                                                                                                                               | `policies.allowPublicTargets` for an owner-declared deployment/preview (a Vercel preview of your own app). Multi-participant public/preview fan-out needs explicit `participants[].target` for every participant, so the adapter-owned topology is declared rather than inferred. Provisioned clone subjects always serve in-sandbox on loopback                                                                                                                                                                                                                                                                                                                                                                                                               |

package/docs/product/automatic-analysis.md

@@ -3,7 +3,14 @@
 Supported live studies automatically request analysis after each recording finishes. Findings remain
 separate from participant feedback and the recorded study verdict.
 
-The default is `gpt-6-astra` with high reasoning effort, a separate $3 cap on its
+A study that declares no `review.analysis` gets its analyst from its participant (`actor`). A
+Codex `local-agent` participant, on a local or hosted desktop, gets the Codex account analyst
+described below, so a study run on a signed-in Codex needs no OpenAI API key for its findings.
+Every other participant, including a Claude Code `local-agent` participant, gets the OpenAI
+analyst. humanish never moves a study to the other analyst because a key is missing: the account
+that pays for analysis is the one the study names or its participant implies.
+
+The OpenAI default is `gpt-6-astra` with high reasoning effort, a separate $10 cap on its
 expected cost and a 600-second timeout. When no output limit is specified,
 humanish selects 32,768 tokens if the exact input's expected cost still fits that
 cap; otherwise it keeps the established 16,384-token allowance. This preserves
@@ -12,7 +19,7 @@ previously admitted studies without increasing their spending limit. To customiz
 ```yaml
 review:
   analysis:
-    maxCostUsd: 3
+    maxCostUsd: 10
     # Optional overrides. Omit maxOutputTokens for budget-aware selection.
     model: gpt-6-astra
     timeoutMs: 600000
@@ -20,7 +27,8 @@ review:
     # question: Where did participants need to recover?
 ```
 
-Omitting `review.analysis` uses these defaults. Set `review.analysis: false` to
+Omitting `review.analysis` uses these defaults for any participant other than a Codex
+`local-agent`. Set `review.analysis: false` to
 run participants without the additional analysis request. An explicit analysis
 mapping using the default OpenAI API provider requires `maxCostUsd`. Admission
 refuses the request when both its worst case and its expected cost plus a 10% margin are over
@@ -33,9 +41,10 @@ the cap admits no analysis at all, it says so instead. A study of more than 16 p
 analysed in cohorts of at most 16, one request each, and one more request merges their reports;
 the range covers every request and the analysis line names them (see
 [runs with more than 16 participants](../contracts/study-analysis.md#runs-with-more-than-16-participants)).
-The default $3 cap refuses the analysis of 17 participants even for a run that keeps no evidence,
-so a default analysis of more than 16 participants is skipped with
-`AUTOMATIC_ANALYSIS_ADMISSION_REFUSED` unless `review.analysis.maxCostUsd` admits it. Use `analyze --dry-run --max-cost <usd>` on retained
+The default $10 cap admits a single request at the evidence limits ($3.79 expected for one
+participant, $4.54 for 16) and the analysis of 17 to 40 participants from $4.60 to $7.05 with no
+evidence; a run that keeps more evidence can still be refused, and its skip names the
+`--max-cost` that admits it. Use `analyze --dry-run --max-cost <usd>` on retained
 evidence to inspect the expected cost, the worst case and the selected token
 allowance before deliberately choosing a larger budget. Explicit
 `maxOutputTokens` and `--max-output-tokens` limits are honored exactly. The output allowance
@@ -65,8 +74,8 @@ enforced output-token ceiling are unknown, so omit `maxCostUsd` and
 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 --study <study>` 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
+remain untested until a request. An omitted provider means this analyst for a Codex
+`local-agent` participant on any target, and OpenAI for every other participant. This setting
 does not enable managed local desktops.
 
 The same configuration works through `humanish run <study>`,
@@ -77,13 +86,34 @@ never enables analysis by default and rejects an explicit analysis mapping
 before execution. `false` is accepted on every route. Dry runs show analysis
 as skipped, without reading analysis credentials or making a provider request.
 
-Participant execution finishes and its recording is finalized before analysis is
-queued. A participant who was blocked or interrupted can still have useful
-retained evidence; analysis requires a verified live recording, not a successful
-participant outcome. An active, missing or invalid recording is not analyzed.
-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.
+Automatic analysis starts when the run ends: every participant has stopped and the run has
+published its bundle (`run.json` with an outcome, and `status.json` state `finished`). It runs in
+the same process, so `humanish run` returns only after it. A participant who was blocked or
+interrupted can still have useful retained evidence; analysis requires a verified live recording
+whose participant streams all ended, not a successful participant outcome. An active, missing or
+invalid recording is not analyzed. 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.
+
+While analysis runs, the run reads as analyzing. `status.json` records `analysis.startedAt` and
+its heartbeat keeps refreshing `updatedAt`; `humanish runs` lists the run as `passed, analyzing`
+(or its other result); the TUI adds `analyzing` to the run; the served Observer shows **Writing
+findings** in its status band and the Findings tab in a pending state with how long ago analysis
+started; `humanish review` says the analysis is running and when it started. In a terminal, `run`
+prints `Participants finished. Writing findings; this usually takes 1 to 4 minutes.` to stderr,
+then `Still writing findings: <elapsed> elapsed.` every 20 seconds. With `--json` it prints only
+the first line, on stderr.
+
+A run whose process ended before it published (a crash, or a refusal after the run started) is
+recorded `interrupted` with `reason: no-publish`, and one whose process was killed is marked
+`interrupted` by `humanish reclaim`. `humanish analyze` accepts an interrupted run when every
+participant stream ended; when one was still running it refuses with
+`ANALYSIS_RUN_INCOMPLETE` and names `humanish run <study>`. It refuses a run that is still alive
+with `ANALYSIS_RUN_ACTIVE`, and a run whose heartbeat stopped while its pid is still in use with
+`ANALYSIS_RUN_UNCONFIRMED`, naming `humanish reclaim --run <id>`. When the process running an
+automatic analysis stops before it finishes, `review` says so and names the `analyze` command
+that runs it again. That command takes over the run's `.analysis-lock` when the process that
+held it is gone, and says so in a warning.
 
 CLI live starts disclose the selected analyst, its expected cost range and cap, or unknown account dollars before execution.
 `humanish study check <study> --json` and the TUI study screen also expose the
@@ -95,7 +125,7 @@ runner continues after the TUI closes; reopening the TUI or Observer reads the
 existing job and does not start another request. Concurrent or repeated automatic
 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
+Use manual `humanish analyze --run <exact-run-id> --max-cost 10` for an intentional
 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
@@ -113,8 +143,12 @@ unknown analysis produces exit code 2 without discarding the recording. When the
 run's own result is ok, the first line of the human output reads
 `humanish run <study>: live run finished; the analysis did not complete`. A missing
 `OPENAI_API_KEY` skips default analysis and preserves a successful run exit;
-`automaticAnalysisTrigger: "default"` distinguishes that case in JSON. So does a
-default analysis whose expected cost, plus the margin, is over the default $3 cap:
+`automaticAnalysisTrigger: "default"` distinguishes that case in JSON. The skip names the next
+command: with Codex signed in with a ChatGPT account it is `humanish analyze --run <id>
+--provider codex`, and the message names `review.analysis.provider: codex` as the setting that
+makes that analyst the study's; otherwise it says to set the key and names `humanish analyze
+--run <id> --max-cost 10`. So does a
+default analysis whose expected cost, plus the margin, is over the default $10 cap:
 it is skipped with `AUTOMATIC_ANALYSIS_ADMISSION_REFUSED` and the run exits 0. For
 any analysis refused for its cost, the job records the expected cost, the worst
 case and the cap, and the CLI, `humanish review` and the Observer give them with
@@ -126,6 +160,28 @@ findings remain visibly partial; a valid partial result can succeed, while a
 partial result with an analysis error still fails the command. Recorded task
 outcomes and the deterministic review verdict are never rewritten by analysis.
 
+After a live run the human output ends with the analysis line. When the analysis left findings,
+the line gives its state and the top three findings follow, with the `humanish review --run <id>`
+command that prints all of them. Otherwise the line says what happened and a `next:` line gives
+the command that gets findings, when one can. A dry run keeps its one line,
+`analysis: skipped for dry runs`.
+
+`run --json` and `watch --json` carry the same on `automaticAnalysis`: `message`, the sentence the
+human line is built from, and `nextCommand`, the command that gets findings or, when the analysis
+left them, the `review` command (null when no command can). When the analysis left findings the
+JSON also has `findings`:
+
+| Field                | Meaning                                                                                                                                            |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `analysisId`         | The analysis the findings come from                                                                                                                |
+| `status`             | `complete` or `partial`                                                                                                                            |
+| `count`              | How many findings the analysis made                                                                                                                |
+| `designFindingCount` | How many design findings it made; null for an analysis written before them                                                                         |
+| `top`                | At most five findings, highest priority first: `id`, `title`, `headline`, `impact`, `confidence` and `participants` (the affected participant ids) |
+| `review`             | `humanish review --run <id>`, which prints every finding with its evidence                                                                         |
+| `observer`           | The run's Observer page opened on the findings (`observer/index.html#/report`); null without an Observer                                           |
+| `path`               | analysis.json relative to the project directory                                                                                                    |
+
 `automaticAnalysis.reason` is one of these codes, in `--json` and in the human line
 `analysis: <state> (<reason>)`:
 
@@ -152,6 +208,7 @@ outcomes and the deterministic review verdict are never rewritten by analysis.
 | `AUTOMATIC_ANALYSIS_PUBLICATION_FAILED`       | `failed`                  | The analysis could not be published                                   |
 | `AUTOMATIC_ANALYSIS_CANCELLATION_UNAVAILABLE` | `unknown`                 | A cancellation could not be recorded                                  |
 | `AUTOMATIC_ANALYSIS_OUTCOME_UNKNOWN`          | `unknown`                 | The outcome could not be determined                                   |
+| `AUTOMATIC_ANALYSIS_STOPPED`                  | `unknown`                 | Read only: the process running it stopped refreshing its job record   |
 
 A run refused before it was created (`run: not-created`) prints no `analysis:` line, since there
 is no run to analyze and the refusal says why. Its JSON keeps the record, with

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanish",
-  "version": "0.139.1",
+  "version": "0.141.0",
   "description": "Synthetic user research for apps, CLIs, and agent-facing product flows.",
   "keywords": [
     "cli",

package/skills/humanish/SKILL.md

@@ -95,10 +95,13 @@ exact returned path, not a basename that could resolve to another manifest.
 
 ## 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,
+Analysis is separate from the participant. A study that declares no analyst
+gets one from its participant: a Codex `local-agent` participant, local or
+hosted, defaults to a separate Codex account analyst; every other participant,
+Claude Code included, defaults to the OpenAI API with a $10 admission budget.
+Without `OPENAI_API_KEY` that OpenAI analysis is skipped, and the run output
+names the next command: `analyze --provider codex` when Codex is signed in. To
+select the restricted Codex ChatGPT account analyst on any supported study,
 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
@@ -133,7 +136,8 @@ the pinned runtime; a live local run also prepares it automatically. The normal
 See [the complete example and limits](https://humanish.dev/docs/local-browser).
 
 Local browsers currently require a loopback app URL with an explicit port above
-1023 and use a 960×720 Chromium desktop. For email-gated local apps, start
+1023 and use a 960×720 Chromium desktop unless a device preset or
+`execution.desktop.resolution` sets each participant's screen. For email-gated local apps, start
 `humanish comms catch`, point the app's email sends at it, and declare
 `comms.email.external.catchBaseUrl`. Use `doctor --study` to check its recipient
 routes. This captures app sends without mailbox-provider credentials; it does
@@ -294,6 +298,63 @@ fails with `HUMANISH_STUDY_RETIRED_DIRECTORY`; move it to the matching `studies/
   run looks like idle tiles — another reason to leave the cap out unless you
   need it.
 
+### Phone, tablet and desktop in one study
+
+When the user asks to test several screen sizes, write one study with one
+`participants` entry per size and set `device` on each entry. The participants run
+at once, the Observer shows them side by side, and the findings compare them.
+
+```yaml
+schema: humanish.study.v3
+id: devices
+title: Phone, tablet and desktop
+route: computer-use
+mode: live
+subject:
+  source: app-url
+  appUrl: "http://127.0.0.1:3000"
+actor:
+  type: local-agent
+  localAgent: codex
+  persona: synthetic-new-user
+  mission: "Sign up and create your first project. Say what was hard to read or reach."
+participants:
+  - id: phone
+    device: mobile
+  - id: tablet
+    device: tablet
+  - id: desktop
+    device: desktop
+execution:
+  target: local
+  timeoutMs: 600000
+  desktop:
+    fidelity:
+      mobileEmulation: true
+```
+
+This runs on the local browser runtime with the user's Codex login. For a deployed
+app, set `execution.target: e2b-desktop`, put the public URL in `subject.appUrl`,
+add `policies.allowPublicTargets: true`, and give each entry a `target` (below).
+
+- `device` takes a preset: `mobile` (414×896), `small-mobile`, `narrow-mobile`,
+  `tablet` (820×1180), `desktop` (1440×950) or `wide` (1920×1080). The preset
+  sizes the participant's screen and browser window.
+- `fidelity.mobileEmulation: true` gives the phone participants a mobile viewport,
+  device pixel ratio, touch and a mobile user agent in Chromium. Tablet and
+  desktop participants are left as they are.
+- Do not run one study per size, draw a device frame inside the page, or resize
+  the browser from the mission. Those produce desktop-ratio evidence labelled as
+  a phone, and three runs the Observer cannot compare.
+- Participants on one public app (`policies.allowPublicTargets: true`) share its
+  data, so more than one is refused unless each entry sets `target`: a separate
+  test account, tenant or seeded URL per participant, or the same URL when the
+  task has each participant create its own account. A loopback or clone subject
+  needs no `target`.
+- On a local study, `doctor --study` fails its runtime row when the installed
+  local runtime predates per-participant screens; `humanish runtime setup`
+  installs the pinned one. Do not move the study to E2B without asking the user.
+
 Use committed `humanish/studies/*.yaml` for public-safe, reproducible studies. Use
 ignored `.humanish/studies/*.yaml` or `.humanish/local/studies/*.yaml` for private repo
 targets, local-only dogfood, or machine-specific settings. Never commit private
@@ -419,14 +480,15 @@ credits, or claim product behavior proof from a dry run.
 When the target app can run locally, prove a known browser path with a
 scripted-browser study after starting the app on loopback. The study replays a
 `browser.steps` scenario (see above) on a desktop surface, plus a mobile one
-with `count: 2`. The scripted steps make no model requests. Post-run analysis
-still runs by default when `OPENAI_API_KEY` is set, with a $3 cap; keep
-`review.analysis: false` to skip it. Copy the shape of
+with `count: 2`. The scripted steps make no model requests; the analysis after
+the run does, and it is what produces findings. Copy the shape of
 [`humanish/studies/scripted-demo.yaml`](https://github.com/danielgwilson/humanish/blob/main/humanish/studies/scripted-demo.yaml)
 or the example in the
-[study file reference](https://humanish.dev/docs/study-files#scripted-browser-scenarios):
-set `subject.appUrl` to the loopback URL, `scenario` to the scenario id,
-and `mode: live`. Without `mode: live` the study is a dry run that opens
+[study file reference](https://humanish.dev/docs/study-files#scripted-browser-scenarios),
+leaving out the demo's `review.analysis: false`, which keeps that zero-spend
+demo from requesting analysis: set `subject.appUrl` to the loopback URL,
+`scenario` to the scenario id, and `mode: live`. Set `review.analysis: false`
+only when the user has chosen a run with no findings. Without `mode: live` the study is a dry run that opens
 no browser.
 
 ```bash
@@ -441,6 +503,52 @@ Do not use `humanish watch --count ...` as a substitute for a scripted-browser
 study. `watch` without a study starts a preview run for the Observer; a live scripted-browser
 study captures desktop and mobile browser evidence against a running app.
 
+## After a Live Run, Read and Report Its Findings
+
+A live run ends with a separate analysis of its evidence, and `run --json`
+carries what that analysis left. `findings.count` is how many findings it made;
+`findings.top` holds at most five, each with its `title`, `headline`, `impact`,
+`confidence` and the ids of the `participants` it affected; `findings.review` is
+the command that prints every finding with its evidence; `findings.observer` is
+the Observer page that opens on the findings. When the analysis left no
+findings, `findings` is absent, `automaticAnalysis.message` says why, and
+`automaticAnalysis.nextCommand` is the command that gets them (null when no
+command can). Run that command, or tell the user to.
+
+Read the full findings before reporting anything else:
+
+```bash
+npx humanish review --run <id>          # the verdict, then each analysis finding
+npx humanish review --run <id> --json   # the same; findings are under `analysis`
+```
+
+Report each finding to the user: its title, impact, confidence and recovery, the participants it
+affected, and the capture files it cites. These come from the post-run analysis of the evidence.
+Label the participant's own report in the review summary as the participant's account. When
+`analysis.state` is not `ready`, report `analysis.message` and the `analysis.next` command in
+place of findings; `analysis.next` is null when no command can produce them. `latest` moves with
+every run, including dry runs, so use the run id the run printed.
+
+## Long Studies: `run` Blocks Until Its Findings
+
+`humanish run <study>` returns only after every participant has ended and the automatic analysis
+has finished. A participant with `endAfterMs` can keep a study running for up to 24 hours, and
+analysis usually adds 1 to 4 minutes after the last participant ends. A shell timeout that sends
+SIGTERM stops the run: humanish marks it interrupted and stops its sandboxes.
+
+- Start a study that can outlive your shell call in tmux, for example
+  `tmux new -d -s study 'npx humanish run <study> --json --no-open > run-result.json 2> run.log'`.
+  `--detach` only skips the Observer server at the end; it does not move the run to the background.
+- The first stderr line names the run: `Run <id> started. Follow it with humanish observe --run <id>`.
+  If you did not keep it, `npx humanish runs --json` lists runs newest first.
+- In `runs --json`, a run whose participants are working has `display.state: running`; once they
+  end, its `display` is their result and `analysis.state` is `running` while findings are written.
+- `npx humanish review --run <id> --json` says where the run is: participants running, analysis
+  running since a given time, or the findings.
+- If the run's process died, `npx humanish reclaim --run <id>` stops its sandboxes and marks it
+  interrupted. `npx humanish analyze --run <id>` then analyzes it if every participant had ended,
+  and otherwise names the command that runs the study again.
+
 ## Optional Live E2B Study
 
 Live headed E2B desktop participants are optional. Add the substrate dependency only
@@ -450,12 +558,18 @@ when the user explicitly wants live E2B execution:
 npm i -D @e2b/desktop
 ```
 
-Then confirm env var names are documented without values:
+Then confirm env var names are documented without values. Which keys a hosted
+study needs depends on its participant and analyst:
 
-```bash
-E2B_API_KEY
-OPENAI_API_KEY
-```
+| Participant                             | Keys                                                                                                                                                 |
+| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `openai-computer-use`                   | `E2B_API_KEY`, `OPENAI_API_KEY`                                                                                                                      |
+| `local-agent` with `localAgent: codex`  | `E2B_API_KEY` and `codex login`; the findings analysis uses the same Codex account                                                                   |
+| `local-agent` with `localAgent: claude` | `E2B_API_KEY` and `claude auth login`; `OPENAI_API_KEY` for findings; without it, a signed-in Codex can analyze the run (the run prints the command) |
+
+A hosted Codex participant does not need `OPENAI_API_KEY`. Do not report a missing
+`OPENAI_API_KEY` as the reason a Codex study on E2B fails; read the
+`doctor --study` row instead.
 
 Do not paste values into files, prompts, run bundles, issue drafts, or logs.
 Load local values only at invocation time:
@@ -471,23 +585,31 @@ declared scenario is developer-experience testing. Private repos are allowed
 only as explicit maintainer-authorized runs with repo redaction left on; never
 publish their names, screenshots, logs, source snippets, or operational details.
 
-## Reporting Back
-
-After a live run, read its findings before anything else:
+## Setup errors and what they mean
+
+Run `npx humanish doctor --study <id>` before the first live run and read every
+`missing` row. The common ones:
+
+- `codex_unsafe_configuration` on a hosted Codex participant: the row names the
+  setting humanish refused. Report it to the user; never edit, move or rename
+  their Codex, agent or skill config to make a run pass. An `AGENTS.md` in the
+  Codex home is admitted, and doctor notes that the participant also receives it.
+- `subject.appUrl` must be loopback: a non-loopback URL needs
+  `policies.allowPublicTargets: true`, and with more than one participant, a
+  `target` on each entry.
+- "Will be skipped: OPENAI_API_KEY is missing" on `post-run analysis` (an
+  `openai-computer-use` or Claude participant): the run works without findings,
+  and when Codex is signed in, its `next:` line gives the command that analyzes it with Codex.
+  `review.analysis.provider: codex` makes that the study's default.
+- A local browser study refuses a non-loopback URL, a port below 1024, hosted
+  templates and `sandboxTimeoutMs`. The message names the setting; do not switch the
+  study to a hosted target unless the user agrees to E2B usage.
 
-```bash
-npx humanish review --run <id>          # the verdict, then each analysis finding
-npx humanish review --run <id> --json   # the same; findings are under `analysis`
-```
-
-Report each finding to the user: its title, impact, confidence and recovery, the participants it
-affected, and the capture files it cites. These come from the post-run analysis of the evidence.
-Label the participant's own report in the review summary as the participant's account. When
-`analysis.state` is not `ready`, report `analysis.message` and the `analysis.next` command in
-place of findings; `analysis.next` is null when no command can produce them. `latest` moves with
-every run, including dry runs, so use the run id the run printed.
+## Reporting Back
 
-Then report:
+Report a live run's findings first, as
+[After a Live Run, Read and Report Its Findings](#after-a-live-run-read-and-report-its-findings)
+describes. Then report:
 
 - files changed in the target repo;
 - exact proof commands run;