humanish 0.139.1 → 0.140.0

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
@@ -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>`,
@@ -95,7 +104,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 +122,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 +139,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>)`:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanish",
-  "version": "0.139.1",
+  "version": "0.140.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
@@ -419,14 +423,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 +446,32 @@ 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.
+
 ## Optional Live E2B Study
 
 Live headed E2B desktop participants are optional. Add the substrate dependency only
@@ -473,21 +504,9 @@ publish their names, screenshots, logs, source snippets, or operational details.
 
 ## Reporting Back
 
-After a live run, read its findings before 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.
-
-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;