humanish 0.110.0 → 0.110.2

package/docs/contracts/schemas.md

@@ -37,6 +37,7 @@ workflow without leaking private upstream truth into core.
 | Review                            | `humanish.review.v1`                                                                                                                                                           | `contract-proof-review`                                                             |
 | Study analysis                    | `humanish.study-analysis.v1`                                                                                                                                                   | see [study analysis](study-analysis.md) and synthetic analysis fixtures in `tests/` |
 | Study analysis correction         | `humanish.study-analysis-correction.v1`                                                                                                                                        | see [study analysis](study-analysis.md#human-review-and-sharing)                    |
+| Analysis findings view            | `humanish.analysis-findings.v1` (`review --json` field `analysis`; read-only projection of the selected analysis)                                                              | see [study analysis](study-analysis.md#reading-findings)                            |
 | Analysis execution receipt        | `humanish.analysis-execution.v1`                                                                                                                                               | see [study analysis](study-analysis.md#durable-records)                             |
 | Analysis execution start          | `humanish.analysis-execution-start.v1`                                                                                                                                         | see [study analysis](study-analysis.md#durable-records)                             |
 | Verification                      | `humanish.verify-result.v1`                                                                                                                                                    | `five-check-verify`                                                                 |
@@ -278,7 +279,7 @@ instruction?, target?, entry?, host?, reasoningEffort?, stopWhen?, dwell? }` bec
   an interactive PTY would overstate the mechanism (a duplex PTY
   transport does not ship). `terminal.stdin` defaults to `disabled`
   (`sent`/assisted input is rejected until the interventions ledger + a
-  non-comparable marker exist). `runtimeAuth` (`openai-env`, the default, or `openai-egress`)
+  non-comparable marker exist). `runtimeAuth` (`openai-egress`, the default, or `openai-env`)
   declares the agent's runtime-auth channel, recorded as names only. On a live run, the engine
   resolves the registered terminal descriptor and requires
   `keyPlacement: in-sandbox-command-scoped` before creating a sandbox. With `openai-env`
@@ -300,10 +301,11 @@ instruction?, target?, entry?, host?, reasoningEffort?, stopWhen?, dwell? }` bec
   wall-clock kill; `maxUsd`/`maxJobs` are enforced fail-closed against the cost
   ledger after the session (a run whose known spend exceeds the cap fails closed,
   `HUMANISH_TERMINAL_CAPS_EXCEEDED`). Core records Codex provider spend as
-  unpriced tokens, so without a cost probe no line can trip a positive `maxUsd`:
-  a live run refuses `maxUsd > 0` before creating a sandbox
-  (`HUMANISH_TERMINAL_UNPRICED_CAP`) unless the caller passes a `costProbe`
-  hook. The sandbox's server-side timeout is the steps before the
+  unpriced tokens and measures no product, media or payment spend, so no line can trip a
+  positive `maxUsd`: a live run refuses `maxUsd > 0` before creating a sandbox
+  (`HUMANISH_TERMINAL_UNPRICED_CAP`). A terminal `maxUsd` cap has no adopter cost source
+  until [issue 347](https://github.com/danielgwilson/humanish/issues/347) lands;
+  `StudyDeps.costProbe` is a test seam. The sandbox's server-side timeout is the steps before the
   codex command (Node bootstrap, runtime version check, and product setup when
   `subject.product.install` is declared) plus `maxMinutes` plus a 5-minute
   teardown buffer; a live run refuses a `maxMinutes` that would take it past
@@ -1066,9 +1068,9 @@ contract.
 ## Terminal Cost Ledger And No-Spend Proof
 
 The terminal-product route (`src/routes/terminal/route.ts`), under the default
-`runtimeAuth: openai-env`, passes a real provider key only to the in-sandbox agent
-command; `openai-egress` gives the command a placeholder and keeps the key in an
-external E2B header transform. Neither mode puts it in sandbox-global env or
+`runtimeAuth: openai-egress`, gives the in-sandbox agent command a placeholder and
+keeps the key in an external E2B header transform; `openai-env` passes a real
+provider key only to that command. Neither mode puts it in sandbox-global env or
 metadata, so the no-spend claim must be derived from a ledger, never asserted. The
 live run writes both to `terminal-ledgers.json` (a `cost` block + a
 `noSpendProof` block, additive to `humanish.terminal-ledgers.v1`).
@@ -1088,8 +1090,8 @@ discipline** that distinguishes three states and never conflates them:
 and is never coerced to `0`); `fullyMeasured` is true only when no line is null.
 Core meters only the `provider` line, populated from the actor trace's
 `tokenUsage.costUsd` when present (else `null`); `product`/`media`/`payment`
-remain `null` unless an adapter supplies those signals through the shipped
-cost-probe seam. The terminal route records the model as `codex` and does not pin Codex's
+remain `null`, because no adopter can supply those signals until
+[issue 347](https://github.com/danielgwilson/humanish/issues/347) lands. The terminal route records the model as `codex` and does not pin Codex's
 model, so a measured token count stays `usd: null` with `source: unpriced-token-usage`, and
 `knownTotalUsd: 0` with `fullyMeasured: false` means no line of this ledger was priced. E2B
 time for the terminal sandbox is not a line of this ledger, whose lines are checked against
@@ -1149,9 +1151,13 @@ finished | interrupted, mode, study?, pid, startedAt, updatedAt, completedAt?,
 signal?, outcome? }`. A record written by 0.108 or earlier also has `lab`, with the same value as
 `study`, and readers accept it.
 `outcome` carries the bundle's `verdict`, `participants`, `estimatedCostUsd` and
-`estimatedCostComplete` when the run finishes, then the result's `ok` and `execution: { succeeded,
-failures: [{ kind, message }], warnings? }` once the Observer has rendered. The
-verdict is what the participants experienced; `execution` is whether the run
+`estimatedCostComplete` when the run finishes, with `ok` and `execution: { succeeded,
+failures: [{ kind, message }], warnings? }` copied from `run.json`'s `outcome`
+([Run Outcome](run-bundle.md#run-outcome)) in the same publication. An Observer
+that does not render adds its `evidence` failure to both files. A record written
+before `run.json` carried an outcome got `ok` and `execution` after the Observer
+rendered and is the only copy of that run's `ok`; readers use it for such a run
+only. The verdict is what the participants experienced; `execution` is whether the run
 worked as an execution (`kind` is `harness`, `provider-cleanup`,
 `provider-policy`, `sandbox-cleanup`, `evidence`, `cap` or `run`), and `ok`
 reads both under the route's policy (`OUTCOME_POLICIES` in `src/run/judge.ts`).
@@ -1177,10 +1183,14 @@ and the estimate is a lower bound. A record without it, as every record before
 
 `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 then kills the E2B sandboxes the run's `sandbox-receipts.ndjson`
-names, writes `reclaim-receipt.json` as `humanish reclaim` does, and exits
-128+n. The bundle is not finished: run.json keeps its last live flush, and no
-`outcome` is written. A `running` record that stopped refreshing still reads as
+analysis. It first prints one line saying it is stopping and refuses any further sandbox
+create. It then kills the E2B sandboxes the run's `sandbox-receipts.ndjson` names, each sandbox
+a create in flight reports as its id arrives, and each one E2B lists with the run's owner tags,
+writes `reclaim-receipt.json` as `humanish reclaim` does, rewrites each run file that names one of
+the run's raw sandbox ids with the marker and digest, as a finished run's publish does, and exits
+128+n. The bundle is not finished: run.json keeps its last live flush, with
+`outcome: { state: interrupted, ok: false, signal, at }` when the run had
+flushed one, and status.json gets no `outcome`. A `running` record that stopped refreshing still reads as
 interrupted once stale. A library caller of `runStudy` gets no signal handling. A
 humanish older than this field rejects the state and falls back to the bundle's
 own liveness.
@@ -1192,8 +1202,10 @@ nothing at all until they completed.
 
 It is a derived index, not evidence. `run.json` remains the evidence-of-record;
 `verify` never gates on `status.json`, nothing in it is a claim about what a
-participant did, and when the two disagree the bundle wins and the record is
-rebuildable from it. A `running` record whose `updatedAt` is older than three
+participant did, and when the two disagree the bundle wins. Fields that cannot be
+rebuilt from `run.json`: `pid`, `startedAt`, `updatedAt` and `completedAt`, which
+no bundle records, and, on a record written before `run.json` carried an
+`outcome`, `outcome.ok` and `outcome.execution`. A `running` record whose `updatedAt` is older than three
 touch intervals is interrupted, not alive. A dropped connection or a killed
 terminal leaves exactly that shape, so the record reads as interrupted
 (`classifyRunStatus` is the one shared definition). Fields are
@@ -1210,16 +1222,20 @@ them is a claim about what a participant did.
 `humanish.run-index.v1` is the listing projection. One entry per run, read
 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?,
-participants?, estimatedCostUsd?, estimatedCostComplete?, analysisCost?,
-durationMs? }`. The point is cost: walking
+mode?, pid?, study?, startedAt?, updatedAt?, completedAt?, verdict?, ok?,
+failure?, participants?, estimatedCostUsd?, estimatedCostComplete?,
+analysisCost?, durationMs? }`. `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
 every run tree and parsing every bundle measured 167ms on a 25-run project,
 against 16ms cold and 2.8ms warm here, which is what makes a surface that
 refreshes on a cadence affordable. `derivedFrom` is reported so a surprising row
 can be traced to the file it came from. A run with receipts and no outcome is
 `interrupted` (the shape a dropped connection leaves), and so is an
 in-progress bundle reached without a status record: there is no freshness to
-judge, and nothing in it says the run finished.
+judge, and nothing in it says the run finished. A bundle with an `outcome` reached
+without a status record takes its liveness from `outcome.state`.
 
 `estimatedCostUsd` is the participants-and-desktops figure from the status
 record or bundle and excludes analysis. `estimatedCostComplete` says whether that
@@ -1378,7 +1394,7 @@ usage is known or bounded:
 - A request lost without a reply (it stalled, or the OpenAI provider's
   transport threw) is booked at its worst case before it is sent again: the
   latest reported request's input at the model's highest input rate plus
-  `actors[].maxOutputTokens` at its output rate, both from `src/run/pricing.ts`.
+  `actor.maxOutputTokens` at its output rate, both from `src/run/pricing.ts`.
   The reply to the resent request replaces that input with its own. The
   request is sent again only when the estimate with that charge stays within
   `maxUsd` and the study budget. Otherwise the session ends `budget_reached`
@@ -1566,7 +1582,7 @@ of it fails.
 | `SubjectPhaseEvent`                                                                                                                            | the `subject-phase` `StudyEvent` through `onEvent`. Its `type` is `"subject-phase"`; the phase that was `type` is `name`, and `target` is `{ kind: "subject" }` or `{ kind: "participant", participant }`. `message`, `at`, `ok` and `durationMs` are unchanged                                                                                |
 | `StudyOutcome.backend`, `LabBackend`                                                                                                           | `outcome.route`                                                                                                                                                                                                                                                                                                                                |
 | `selectLabBackend`, the `routesTo*` predicates, `actorResolvesToTerminal`                                                                      | `routeOf(config)`                                                                                                                                                                                                                                                                                                                              |
-| `resolveStudyDryRun`                                                                                                                           | `RunStudyOptions.dryRun`; without it, `scenario.mode` decides                                                                                                                                                                                                                                                                                  |
+| `resolveStudyDryRun`                                                                                                                           | `RunStudyOptions.dryRun`; without it, `mode` decides                                                                                                                                                                                                                                                                                           |
 | `cuaLaneCount`                                                                                                                                 | the `plan` `StudyEvent`, which lists every participant                                                                                                                                                                                                                                                                                         |
 | `resolveSeatUrl`                                                                                                                               | `parseStudy`, which refuses a participant entry that is not same-origin loopback; build the URL with `new URL(entry, serveUrl)`                                                                                                                                                                                                                |
 | `cuaLaneValidationReason`, `sharedWorldValidationReason`, `concurrentSharedWorldValidationReason`, `externalPublicSharedWorldValidationReason` | `parseStudy`, which returns the same reason                                                                                                                                                                                                                                                                                                    |
@@ -1682,7 +1698,9 @@ the stream shape, the meaningful-use rubric, and hard-failure rules.
 Review summarizes whether evidence supports the claim. It does not replace
 verification or maintainer acceptance.
 
-`verdict` is the run gate result. `participants.reachedGoal` retains the count of
+`verdict` is what the participants experienced, collapsed to one word. Whether
+the run passed also reads `run.json`'s `outcome.ok` ([Run Outcome](run-bundle.md#run-outcome)):
+a run whose execution failed shows as failed beside a `pass` verdict. `participants.reachedGoal` retains the count of
 recorded successful sessions; it is not an independent adjudication of their
 claims. Computer-use review and Observer labels distinguish a participant's
 reported completion from a recorded `stopWhen` or dwell condition match. A

package/docs/contracts/study-analysis.md

@@ -288,6 +288,51 @@ companion project validated records; generic HTTP serving of producer-owned raw
 analysis/correction JSON, execution receipts, atomic write temporaries and locks
 is disabled. Existing adapter captures and logs retain their contained routes.
 
+## Reading findings
+
+`humanish review` prints a run's analysis findings after its participant review, and
+`humanish analyze show` prints them alone. Each finding shows its title, impact, confidence and
+recovery, the participants it affected out of those exposed, the frames its evidence cites with
+their time since the first retained capture, the capture files, its next step and the latest
+human review note. A live run's human output ends with up to three findings, one line each, and
+the `review` command that prints all of them. `analyze show --json` prints the validated
+analysis record and its corrections, as before. Reading findings never starts an analysis.
+
+`review --json` carries the same view as its `analysis` field, schema
+`humanish.analysis-findings.v1`, built in `src/cli/findings.ts`:
+
+| Field                                                                          | Meaning                                                                                                                                                                                                                                                                                                                                       |
+| ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `schema`                                                                       | `humanish.analysis-findings.v1`.                                                                                                                                                                                                                                                                                                              |
+| `runId`                                                                        | The run the view reads.                                                                                                                                                                                                                                                                                                                       |
+| `state`                                                                        | `ready`, `stale`, `running`, `none`, `skipped`, `failed`, `dry_run` or `unavailable`. Only `ready` and `stale` carry findings.                                                                                                                                                                                                                |
+| `reason`                                                                       | The stable code behind a state other than `ready`, or null: an automatic analysis reason such as `AUTOMATIC_ANALYSIS_KEY_MISSING`, a failed attempt's error code, or a load warning such as `ANALYSIS_SOURCE_CHANGED`.                                                                                                                        |
+| `message`                                                                      | What happened, in words.                                                                                                                                                                                                                                                                                                                      |
+| `next`                                                                         | The command that gets findings for this run, or null when no command can, as for a dry run or a run whose participants left no evidence.                                                                                                                                                                                                      |
+| `analysisId`, `status`, `provider`, `model`, `completedAt`, `estimatedCostUsd` | The analysis version `analyze show` selects: the newest ready one, else the newest stale one. Null without one.                                                                                                                                                                                                                               |
+| `runPath`, `path`                                                              | The run directory and the version's `analysis.json`, relative to the project directory.                                                                                                                                                                                                                                                       |
+| `summary`, `limitations`                                                       | The analysis's own summary and limitations.                                                                                                                                                                                                                                                                                                   |
+| `findings[]`                                                                   | Highest priority first: `id`, `title`, `summary`, `impact` (`blocked_task`, `friction`, `recovery`, `uncertain`), `confidence` (`low`, `medium`, `high`), `recovery` (`recovered`, `not_observed`, `unknown`), `affected[]` (`streamId`, `label`), `exposedCount`, `evidence[]`, `nextStep` and `correction`.                                 |
+| `findings[].evidence[]`                                                        | Each cited item once: `id`, `streamId`, `kind`, `bases` (how the observations used it), `frame` (the latest retained capture's index from 0, null before any capture), `elapsedMs` (time since the first retained capture, not a video offset), `at` and `capture` (the file relative to the project directory, null for nonvisual evidence). |
+| `findings[].correction`                                                        | The latest `analyze correct` note on that finding version (`status`, `reason`, `replacementClaim`), or null.                                                                                                                                                                                                                                  |
+| `warnings`                                                                     | Load warnings for the selected version.                                                                                                                                                                                                                                                                                                       |
+
+The states without findings:
+
+- `running`: the automatic analysis is queued or running. `next` is `review` again.
+- `skipped`: the automatic analysis was skipped or refused, for example without
+  `OPENAI_API_KEY`. `next` is `analyze --max-cost 3`.
+- `failed`: the latest attempt failed or was cancelled and no usable version exists. `next`
+  reruns it with the same analyst, `--provider codex` for the Codex account analyst.
+- `none`: no analysis ran for this live run, for example with `review.analysis: false`.
+- `dry_run`: a dry run has no participant evidence to analyze.
+- `unavailable`: the run or its analysis records could not be read or checked, or the analysis
+  text matched a sensitive-text pattern (`ANALYSIS_SENSITIVE_TEXT_QUARANTINED`), which the
+  Observer withholds too.
+
+`stale` lists the findings with a warning: the run's evidence changed after the analysis, and
+`next` requests a new one. `analyze show` without `--json` exits 2 when the JSON form would.
+
 ## Human review and sharing
 
 ```bash

package/docs/contracts/study-costs.md

@@ -29,6 +29,14 @@ They do not suddenly include a separate analysis request. The bundle's
 `cost.estimatedTotalUsd`, `status.json`'s `outcome.estimatedCostUsd` and the run
 index's `estimatedCostUsd` stay participants and desktops only.
 
+Each study's `passed` counts the runs that show as passed on every surface
+(`runDisplay` in `src/run/display.ts`): a `pass` verdict and a run whose own `ok`
+is not false. `passRate` divides it by `judged`, the runs with a verdict.
+`totals.verdicts` counts the participants' verdicts; `totals.outcomes` counts
+every selected run by its display state (`passed`, `failed`, `blocked`,
+`timed_out`, `no_verdict`, `dry_run`, `interrupted`, `running`, `unknown`), and
+the human output prints that line.
+
 ## One run's cost
 
 A run's analysis spend has one reader, `readAnalysisAccounting` in

package/docs/decisions/0001-run-bundle-is-the-source-of-truth.md

@@ -18,6 +18,9 @@ the evidence. Everything else is a projection rebuilt from them:
 - `status.json` (`humanish.run-status.v1`) is a liveness index. When it disagrees with `run.json`,
   `run.json` wins. `verify` reads it, with the sandbox and reclaim receipts, only to say a run
   did not finish (`RUN_NOT_FINISHED`). That warning changes no check and no grade.
+- A run's `ok` and execution outcome are in `run.json`'s `outcome`, and `status.json` copies them.
+  A `status.json` written before `run.json` carried an outcome holds the only copy of that run's
+  `ok`, so readers fall back to it for such a run only.
 - Analysis findings cite turns and artifacts in the bundle.
 
 ## Consequences

package/docs/decisions/0003-contained-paths-and-cleanup-authority.md

@@ -1,6 +1,7 @@
 # 0003: Managed paths bind to physical identities; cleanup uses create-time receipts
 
-Accepted in 0.15.1, extended in 0.36.0 (`humanish reclaim`).
+Accepted in 0.15.1, extended in 0.36.0 (`humanish reclaim`) and after 0.110.0 (search by owner
+tags).
 
 ## Context
 
@@ -18,11 +19,16 @@ Separately, an account-wide provider operation once destroyed unrelated infrastr
 - The process that creates a resource cleans it up with the handle it holds. After a crash,
   `humanish reclaim` kills sandboxes by the exact ids journaled at create time in the run's
   `sandbox-receipts.ndjson`, and reports each outcome.
-- No route lists an account's resources to find or verify its own.
+- Nothing lists an account's resources unfiltered. Every sandbox carries its run's owner tags
+  (`tool`, `runId`, `runKey`), and reclaim lists only the sandboxes E2B matches to all three,
+  checks each tag again before it acts, and stops after three pages. A sandbox whose id never
+  reached a receipt, from a create that threw after E2B allocated or a process that died
+  mid-create, is otherwise unreachable until its timeout.
 
 ## Consequences
 
-- A shared operator key is safe to use: humanish reaches only resources it created.
+- A shared operator key is safe to use: humanish reaches only resources it created. `runKey` keeps
+  two projects that reuse a run id from matching each other's sandboxes.
 - An exported bundle does not carry cleanup authority; `export` omits the receipt journal.
 - Unverified git metadata (arbitrary `gitdir:` redirects) is reported as unavailable instead of
   followed.

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

@@ -66,14 +66,17 @@ certify (see the conformance suite).
 6. **Claims match mechanism.** A config field that is parsed but not consumed warns; a
    document that overstates behavior is a defect; an evidence artifact never claims a
    stronger evidence class than its actor and scenario can support.
-7. **Reclamation is by exact created id, never account-wide enumeration.** A route that
-   creates a provider resource (an E2B sandbox, for example) tracks the exact id it created and
-   reclaims and proves cleanup against that id alone (a returned found-and-killed boolean, a
-   getInfo-by-id NotFound check). No route ever calls a provider's list-everything endpoint to
-   discover or verify its own cleanup, because that endpoint enumerates the whole account/team,
-   including resources humanish did not create. This is what makes a single shared operator key
-   safe: humanish only ever reaches a resource it created, never anything else the key's owner
-   is running.
+7. **Reclamation is by exact created id or the run's exact owner tags, never account-wide
+   enumeration.** A route that creates a provider resource (an E2B sandbox, for example) tracks
+   the exact id it created and reclaims and proves cleanup against that id alone (a returned
+   found-and-killed boolean, a getInfo-by-id NotFound check). No route ever calls a provider's
+   list endpoint unfiltered to discover or verify its own cleanup, because that enumerates the
+   whole account/team, including resources humanish did not create. The one listing is reclaim's
+   search for a sandbox whose id never reached the run: every sandbox carries its run's owner
+   tags (`tool`, `runId`, `runKey`), E2B filters by all three, reclaim checks each tag again
+   before it acts, and it reads at most three pages. This is what makes a single shared operator
+   key safe: humanish only ever reaches a resource it created, never anything else the key's
+   owner is running.
    The one narrow exception is an explicit, maintainer-run orphan sweep (never a default, never
    reachable by a normal run) that is itself opt-in gated (an explicit flag or env var) and
    documented as such at its call site.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanish",
-  "version": "0.110.0",
+  "version": "0.110.2",
   "description": "Synthetic user research for apps, CLIs, and agent-facing product flows.",
   "keywords": [
     "cli",
@@ -56,10 +56,12 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json && pnpm --filter humanish-observer build && pnpm --filter humanish-tui build && node scripts/finish-build.mjs",
-    "check": "pnpm format:check && pnpm lint && pnpm knip && pnpm prose:check && pnpm vocabulary:check && pnpm site-css:check && pnpm typecheck && pnpm test && pnpm tui:test && pnpm build && pnpm guest-media:startup:proof && pnpm cli:startup:test && pnpm cli:preflight:test && pnpm cli:dotenv:test && pnpm tui:smoke",
+    "check": "pnpm format:check && pnpm lint && pnpm knip && pnpm prose:check && pnpm vocabulary:check && pnpm docs:check && pnpm site-css:check && pnpm typecheck && pnpm test && pnpm tui:test && pnpm build && pnpm guest-media:startup:proof && pnpm cli:startup:test && pnpm cli:preflight:test && pnpm cli:dotenv:test && pnpm cli:peer:test && pnpm cli:skill:test && pnpm tui:smoke",
     "cli:startup:test": "node scripts/terminal-startup-exit-proof.mjs",
     "cli:preflight:test": "node scripts/task-route-preflight-proof.mjs",
     "cli:dotenv:test": "node scripts/dotenv-proof.mjs",
+    "cli:peer:test": "node scripts/peer-install-proof.mjs",
+    "cli:skill:test": "node scripts/skill-first-run-proof.mjs",
     "humanish": "tsx src/cli.ts",
     "pack:dry-run": "npm pack --dry-run",
     "prepack": "pnpm build",
@@ -73,9 +75,10 @@
     "tui:smoke": "node scripts/tui-smoke.mjs",
     "tui:test": "pnpm --filter humanish-tui test",
     "release:dogfood": "node scripts/release-dogfood.mjs",
+    "bench": "tsx bench/run.ts",
     "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 && tsx scripts/check-doc-paths.ts && tsx scripts/check-doc-symbols.ts && tsx scripts/check-doc-comments.ts",
+    "docs:check": "tsx scripts/generate-cli-docs.ts --check && tsx scripts/check-doc-paths.ts && tsx scripts/check-doc-symbols.ts && tsx scripts/check-doc-comments.ts && tsx scripts/check-doc-study-fields.ts",
     "observer:browser:proof": "node scripts/observer-browser-proof.mjs",
     "observer:iframe:proof": "node --import tsx scripts/observer-iframe-proof.mjs",
     "observer:chrome:proof": "node scripts/observer-chrome-proof.mjs",

package/skills/humanish/SKILL.md

@@ -35,7 +35,7 @@ Everything it shows has a machine-readable equivalent, which is what you want:
 | browsing studies    | `npx humanish study list --json`                                                       |
 | browsing runs       | `npx humanish runs --json`                                                             |
 | starting a run      | `npx humanish run <study> --json --no-open`                                            |
-| a run's outcome     | `npx humanish review --run <id> --json`                                                |
+| a run's findings    | `npx humanish review --run <id> --json`                                                |
 | communication setup | `npx humanish comms providers --json` and `npx humanish comms connections list --json` |
 
 If a human asks you to "open the TUI", tell them the command to type; do not run
@@ -289,7 +289,6 @@ Useful commands:
 ```bash
 npx humanish study list
 npx humanish study show first-run
-npx humanish watch first-run
 npx humanish run first-run --json --no-open
 ```
 
@@ -377,25 +376,30 @@ inbox page. See `docs/contracts/schemas.md` for the full `comms:` shape and
 ## First Proof Run
 
 Run the no-credentials path first. It is a dry run: humanish writes a synthetic
-run bundle and tests no target app behavior:
+run bundle and tests no target app behavior. Every command in this block
+finishes and exits, needs no key and spends nothing; lines marked
+`# live only` need keys and spend money, so run them only when the user has
+approved a live run. `run` prints the run id; use it in place of `<id>`.
 
 ```bash
-npx humanish doctor
-npx humanish watch
-npx humanish verify --run latest --json
-npx humanish feedback issue --run latest --repo example/app --format markdown
-```
-
-For CI or non-interactive proof:
-
-```bash
-npx humanish watch --json --no-open
+npx humanish doctor --json
 npx humanish run first-run --json --no-open
+npx humanish verify --run <id> --json
+npx humanish review --run <id> --json
+npx humanish observe --run <id>
+npx humanish run try-live --json --no-open  # live only
+npx humanish feedback issue --run <id> --repo example/app --format markdown  # live only
 ```
 
-The feedback command prints a public-safe Markdown draft. It must not call the
-GitHub API, require a token, update Projects, use provider credits, or claim
-product behavior proof from a dry run.
+`observe` prints the path of the run's Observer page for the person you are
+working for. Without an interactive terminal, `observe` and `watch` print the
+result and exit; at a person's terminal they serve the Observer until Ctrl-C.
+
+`feedback issue` drafts from a live run only and refuses a dry run with
+`HUMANISH_FEEDBACK_REQUIRES_LIVE_RUN`. Its Markdown draft is checked for
+secret, key, token and local-path shapes; it is not checked for personal data. It
+must not call the GitHub API, require a token, update Projects, use provider
+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
@@ -414,8 +418,8 @@ no browser.
 # in another terminal, start the target app on 127.0.0.1 or localhost
 npx humanish study show <study> --json
 npx humanish run <study> --json --no-open
-npx humanish verify --run latest --json
-npx humanish observe --run latest --open   # for a person; it serves until Ctrl-C
+npx humanish verify --run <id> --json
+npx humanish observe --run <id> --open   # for a person; at their terminal it serves until Ctrl-C
 ```
 
 Do not use `humanish watch --count ...` as a substitute for a scripted-browser
@@ -442,7 +446,7 @@ Do not paste values into files, prompts, run bundles, issue drafts, or logs.
 Load local values only at invocation time:
 
 ```bash
-npx humanish watch .humanish/studies/local-live.yaml --dotenv .humanish/local/provider.env
+npx humanish run .humanish/studies/local-live.yaml --dotenv .humanish/local/provider.env --json --no-open
 ```
 
 When choosing dogfood targets, prefer apps, CLIs, or agent-facing tools with a
@@ -454,7 +458,21 @@ publish their names, screenshots, logs, source snippets, or operational details.
 
 ## Reporting Back
 
-Report:
+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:
 
 - files changed in the target repo;
 - exact proof commands run;