humanish 0.112.0 → 0.114.0

package/docs/architecture/actor-contract.md

@@ -350,22 +350,36 @@ this paragraph is the record of that decision.
 
 `ComputerUseProvider.debrief` is an optional read-only request after a structured
 `stopWhen` or dwell stop. It returns a `ComputerUseTurn` with `closingReport` containing
-`summary` and `frictionReports`; an empty friction list is valid. The loop rejects
+`summary`, `frictionReports` and `impressions`; an empty friction or impressions list is valid,
+and a report without `impressions` (an older provider) is still accepted. The loop rejects
 actions, pending safety checks, and invalid report shapes. It redacts accepted
 reports, records them in `ActorTrace.debrief`, and projects one readable message
-without invoking action or communication callbacks.
+without invoking action or communication callbacks. Each impression becomes its own message
+and goes to `ActorTrace.impressions`; a session without them records why in the same field.
+A turn that ends the session itself may carry `closingReport` too, and the loop keeps its
+impressions the same way without a second request.
+
+`ComputerUseProvider.requestImpressions` is the optional request after the participant ended
+the session itself without impressions. It asks for impressions only, returns them as
+`impressions` on the turn, and follows the debrief's rules and guards. The loop records it as
+`ActorTrace.debrief` with `trigger: "participant_end"` and no report, so the participant's
+reason, outcome and friction come from its final message as before. A failed, timed-out or
+cut-off request leaves `ActorTrace.impressions` as `not_collected` with the reason.
 
 This request uses the final observation and retained provider history. It does
 not expose the hidden stop criterion or change the original task outcome. It is
-skipped before any participant turn, after natural completion, without provider
-support, or without remaining time and known budget. An attempted request's
+skipped before any participant turn, after natural completion (apart from the impressions-only
+request), without provider support, or without remaining time and known budget. An attempted request's
 unreported usage remains an unknown cost line. `counts.debriefCalls` is separate
 from interaction turns, and reported usage contributes to aggregate cost.
 
 The OpenAI implementation makes one request with tools disabled and structured
-output; no HTTP or policy retries. Stateless/ZDR mode does not offer retrospective
+output; no HTTP or policy retries. Its output limit is 3072 tokens, or the declared
+`maxOutputTokens` when lower. Stateless/ZDR mode does not offer retrospective
 reporting: its client-carried conversation summarizes its oldest turns past a token
-budget, so it may not hold the whole session a retrospective report needs. The
+budget, so it may not hold the whole session a retrospective report needs. It does offer
+the impressions-only request, which reads the carried conversation: its newest
+exchanges whole and earlier turns as a text note. The
 [paired live receipt](https://github.com/danielgwilson/humanish/blob/main/docs/evidence/computer-use/structured-closing-report-2026-09-05.md)
 records both report recovery and control failures in the separate legacy parser.
 

package/docs/contracts/errors.md

@@ -46,8 +46,8 @@ Counts are the distinct quoted codes in `src/` on 2026-10-03.
 The lowercase families are values recorded inside artifacts and receipts, and an artifact keeps
 the code it was written with. Automatic analysis reads two of them back:
 `analysis_admission_estimate_exceeded` becomes the reason `AUTOMATIC_ANALYSIS_ADMISSION_EXCEEDED`,
-and `analysis_budget_exceeded` on a default analysis prints the hint to rerun with
-`humanish analyze --max-cost`. Validation also accepts a partial artifact whose error is
+and `analysis_budget_exceeded` records the expected cost, the worst case and the cap on the job,
+and prints them with the command that reruns it, `humanish analyze --run <id> --max-cost <n>`. Validation also accepts a partial artifact whose error is
 `analysis_admission_estimate_exceeded`.
 
 Share-safety reasons in `humanish verify` (`VERIFY_FAILED`, `RAW_SCREENSHOTS` and the rest) are

package/docs/contracts/feedback.md

@@ -66,7 +66,9 @@ Listing does not create a draft or check public-sharing eligibility.
 
 For completed computer-use and shared-world sessions, participant-reported
 friction comes from the redacted closing report, a completed debrief's
-`frictionReports`, and observed-report clauses in earlier messages.
+`frictionReports`, and observed-report clauses in earlier messages. The
+participant's closing impressions (`ActorTrace.impressions`) are opinions about
+the product and never count as friction.
 Matching `stopWhen` or ending a dwell window does not discard an earlier
 report or change the successful completion verdict. Exact repeated reports
 appear once in the participant's candidate. Harness notices, reasoning, and observed
@@ -84,6 +86,11 @@ was not repeated in the message trace.
 Builds structured feedback from the first usable run candidate, or the candidate
 selected with `--candidate`. With no candidate, a live run produces a summary of
 its recorded review; that fallback does not add a finding to the candidate list.
+With `--analysis` and `--finding`, the draft is built from that analysis finding
+instead. When the finding's observations cite a participant's closing impression,
+`actual` quotes it after the observations as
+`Participant <id> said at the end (<kind>): <text>`. An impression is quoted only
+when the cited evidence entry carries its text whole; uncited impressions stay out.
 A dry run tests no product behavior, so `draft`, `verify`, `issue` and
 `issue-url` refuse it with `HUMANISH_FEEDBACK_REQUIRES_LIVE_RUN`. All drafts
 require a verified `share_ready` live run and are written under the run bundle,

package/docs/contracts/run-bundle.md

@@ -576,6 +576,63 @@ updatedAt: "<ISO timestamp>"
 
 The latest pointer may move. Run bundle directories should not.
 
+## Reviewer notes
+
+Each note a person adds while reviewing a run is its own file in the run directory,
+`notes/<id>.json`, written by `humanish notes --add` and by an Observer served on loopback.
+`notes/` is absent until the first note.
+
+```json
+{
+  "schema": "humanish.run-note.v1",
+  "runId": "example-2026-06-02t10-00-00-000z-proof",
+  "id": "note-20260602t103000000z-000000000001",
+  "atMs": 151000,
+  "participant": "stream-001",
+  "nearest": { "participant": "stream-001", "itemId": "turn-07-call-01" },
+  "text": "They looked for the save button here.",
+  "author": "you",
+  "createdAt": "2026-06-02T10:30:00.000Z",
+  "editedAt": null
+}
+```
+
+- `id`: `note-`, the creation time as `yyyymmddthhmmssmmmz`, `-` and 12 hex digits of
+  random bits. The file is named `<id>.json`, so the files sort in the order they were
+  added.
+- `runId`: the run directory's name. A file whose `runId` or `id` does not match its run or
+  its file name is not read.
+- `atMs`: milliseconds from the run clock's start, the earliest timed capture or
+  desktop video of any participant. The Observer's study timeline shows that moment as
+  00:00. A participant's captures count only when every one is stamped and the stamps
+  never go back.
+- `participant`: the stream id the note belongs to, or `null` for the whole run.
+  `humanish notes --add --participant` and the Observer also take the participant's id from
+  the study (the stream's `laneId`) and record its stream id. A name that is one stream's id
+  and another stream's study id is refused.
+- `nearest`: the latest stamped trace item, a capture or an event, at or before the
+  moment, among the note's participant or every participant; `null` when there is none.
+- `text`: 1 to 2000 characters, after the run's known values, secret-shaped values and
+  local paths are replaced.
+- `author`: `"you"` in this version.
+- `createdAt`, `editedAt`: ISO-8601. Notes cannot be edited yet, so `editedAt` is `null`.
+
+A note file is written once and never rewritten: its bytes go to a temporary file inside
+`notes/`, which `link` gives the note's name only when no file has that name, and a taken name
+gets a new id. Adding a note reads no other note, so notes added at the same time from any
+process are all kept, and there is no lock. Readers list at most 1000 entries of `notes/` and
+read at most 500 notes, each within 16 KiB and refused before reading past that; any other
+entry, or a file that is not a note of the run, is skipped and named. The Observer servers serve
+any file under `notes/` only within 16 KiB. A run takes no note past 500.
+`verify` scans the note files with every other run file, so a secret-shaped value in a note
+keeps the run from `share_ready`. A bundle export copies them; an HTML export carries the notes
+read-only after checking the set it read.
+
+Threat model: forged web requests are refused, whether from a page on another site or through a
+name rebound to 127.0.0.1, by the token, Origin and Host checks on `POST /api/notes`. A local
+process with write access to the run directory is out of scope: it already has the user's
+privileges and can change any file in the run.
+
 ## Verify Result Share Safety
 
 `humanish.verify-result.v1` includes a machine-readable `shareSafety` block in

package/docs/contracts/schemas.md

@@ -24,38 +24,38 @@ workflow without leaking private upstream truth into core.
 
 ## Contract Index
 
-| Contract                          | Schema                                                                                                                                                                         | Public-safe fixture                                                                 |
-| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
-| Run bundle                        | `humanish.run-bundle.v1`                                                                                                                                                       | `synthetic-run-bundle`                                                              |
-| Adapter                           | `humanish.adapter.v1`                                                                                                                                                          | `synthetic-cli-adapter`                                                             |
-| Study file                        | `humanish.study.v3`                                                                                                                                                            | `first-run`                                                                         |
-| Persona                           | `humanish.persona.v1`                                                                                                                                                          | `synthetic-maintainer`                                                              |
-| Scenario                          | `humanish.scenario.v1`                                                                                                                                                         | `first-run-smoke`                                                                   |
-| Actor trace                       | `humanish.actor-trace.v1`                                                                                                                                                      | `synthetic-actor-trace`                                                             |
-| Substrate                         | reserved (never shipped)                                                                                                                                                       | none                                                                                |
-| Evidence stream                   | reserved (streams live inside the run bundle)                                                                                                                                  | see [`run-bundle.md`](run-bundle.md)                                                |
-| Review                            | `humanish.review.v1`                                                                                                                                                           | `contract-proof-review`                                                             |
-| Study analysis                    | `humanish.study-analysis.v1` (prompt `study-evidence-7` adds `findings[].headline`, `findings[].experience` and `designFindings[]`; older artifacts omit them)                 | 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`                                                                 |
-| Policy                            | `humanish.policy.v1` (fixture-only; not engine-validated)                                                                                                                      | `public-safety-policy`                                                              |
-| Feedback                          | `humanish.feedback.v1`                                                                                                                                                         | `public-safe-feedback`                                                              |
-| Terminal cost ledger              | `humanish.terminal-cost-ledger.v1`                                                                                                                                             | see Terminal Cost Ledger below                                                      |
-| Terminal no-spend proof           | `humanish.terminal-no-spend-proof.v1`                                                                                                                                          | see Terminal Cost Ledger below                                                      |
-| Pricing (operator-editable rates) | `humanish.pricing.v1` (`src/run/pricing.ts`; dated per-model + E2B desktop rates)                                                                                              | see Run Cost Summary And Estimated Actor Cost below                                 |
-| Run cost summary                  | `humanish.run-cost-summary.v1` (additive `RunBundle.cost`; estimate, never a charge)                                                                                           | see Run Cost Summary And Estimated Actor Cost below                                 |
-| Estimated actor cost              | `humanish.actor-estimated-cost.v1` (additive `ActorTrace.estimatedCost`)                                                                                                       | see Run Cost Summary And Estimated Actor Cost below                                 |
-| Model settings                    | `humanish.model-settings.v1` (additive `ActorTrace.modelSettings`; the reasoning effort the request carried)                                                                   | see Actor Trace below                                                               |
-| Affordance use                    | `humanish.affordance-use.v1` (additive `ActorTrace.affordanceUse`; per-class counts of the routes an actor took)                                                               | see Affordance Use below                                                            |
-| Adapter score                     | `humanish.adapter-score.v1` (`RunBundle.adapterScore`; namespaced; route-specific acceptance semantics)                                                                        | see Product-Adapter Extension Seam below                                            |
-| Adapter artifact                  | `humanish.adapter-artifact.v1` (`RunBundle.adapterArtifacts[]`; namespaced; local relative proof references)                                                                   | see Product-Adapter Extension Seam below                                            |
-| Shared-world evidence             | `humanish.shared-world.v1` (additive `RunBundle.sharedWorld` + `RunBundle.attributionClass`; `topologyMode: sequential \| concurrent`)                                         | see Shared-World Evidence below                                                     |
-| Comms thread                      | `humanish.comms-thread.v1` (off-app email/SMS the app sent, captured; a `kind: log` run-dir artifact of digests only: from/to/subject/link digests + one OTP count, never raw) | see `comms` under Study File                                                        |
-| Serve result                      | `humanish.serve-result.v1` (`src/observer/serve.ts` is authoritative)                                                                                                          | none (command result envelope; see Serve Result below)                              |
-| Serve control plane               | reserved (`/_humanish/api/*` answers `501` `HUMANISH_SERVE_CONTROL_PLANE_DISABLED` in v1)                                                                                      | none                                                                                |
+| Contract                          | Schema                                                                                                                                                                                                                                                    | Public-safe fixture                                                                 |
+| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| Run bundle                        | `humanish.run-bundle.v1`                                                                                                                                                                                                                                  | `synthetic-run-bundle`                                                              |
+| Adapter                           | `humanish.adapter.v1`                                                                                                                                                                                                                                     | `synthetic-cli-adapter`                                                             |
+| Study file                        | `humanish.study.v3`                                                                                                                                                                                                                                       | `first-run`                                                                         |
+| Persona                           | `humanish.persona.v1`                                                                                                                                                                                                                                     | `synthetic-maintainer`                                                              |
+| Scenario                          | `humanish.scenario.v1`                                                                                                                                                                                                                                    | `first-run-smoke`                                                                   |
+| Actor trace                       | `humanish.actor-trace.v1`                                                                                                                                                                                                                                 | `synthetic-actor-trace`                                                             |
+| Substrate                         | reserved (never shipped)                                                                                                                                                                                                                                  | none                                                                                |
+| Evidence stream                   | reserved (streams live inside the run bundle)                                                                                                                                                                                                             | see [`run-bundle.md`](run-bundle.md)                                                |
+| Review                            | `humanish.review.v1`                                                                                                                                                                                                                                      | `contract-proof-review`                                                             |
+| Study analysis                    | `humanish.study-analysis.v1` (prompt `study-evidence-7` adds `findings[].headline`, `findings[].experience` and `designFindings[]`; older artifacts omit them; `study-evidence-8` adds participant impressions to the instructions, with no field change) | 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`                                                                 |
+| Policy                            | `humanish.policy.v1` (fixture-only; not engine-validated)                                                                                                                                                                                                 | `public-safety-policy`                                                              |
+| Feedback                          | `humanish.feedback.v1`                                                                                                                                                                                                                                    | `public-safe-feedback`                                                              |
+| Terminal cost ledger              | `humanish.terminal-cost-ledger.v1`                                                                                                                                                                                                                        | see Terminal Cost Ledger below                                                      |
+| Terminal no-spend proof           | `humanish.terminal-no-spend-proof.v1`                                                                                                                                                                                                                     | see Terminal Cost Ledger below                                                      |
+| Pricing (operator-editable rates) | `humanish.pricing.v1` (`src/run/pricing.ts`; dated per-model + E2B desktop rates)                                                                                                                                                                         | see Run Cost Summary And Estimated Actor Cost below                                 |
+| Run cost summary                  | `humanish.run-cost-summary.v1` (additive `RunBundle.cost`; estimate, never a charge)                                                                                                                                                                      | see Run Cost Summary And Estimated Actor Cost below                                 |
+| Estimated actor cost              | `humanish.actor-estimated-cost.v1` (additive `ActorTrace.estimatedCost`)                                                                                                                                                                                  | see Run Cost Summary And Estimated Actor Cost below                                 |
+| Model settings                    | `humanish.model-settings.v1` (additive `ActorTrace.modelSettings`; the reasoning effort the request carried)                                                                                                                                              | see Actor Trace below                                                               |
+| Affordance use                    | `humanish.affordance-use.v1` (additive `ActorTrace.affordanceUse`; per-class counts of the routes an actor took)                                                                                                                                          | see Affordance Use below                                                            |
+| Adapter score                     | `humanish.adapter-score.v1` (`RunBundle.adapterScore`; namespaced; route-specific acceptance semantics)                                                                                                                                                   | see Product-Adapter Extension Seam below                                            |
+| Adapter artifact                  | `humanish.adapter-artifact.v1` (`RunBundle.adapterArtifacts[]`; namespaced; local relative proof references)                                                                                                                                              | see Product-Adapter Extension Seam below                                            |
+| Shared-world evidence             | `humanish.shared-world.v1` (additive `RunBundle.sharedWorld` + `RunBundle.attributionClass`; `topologyMode: sequential \| concurrent`)                                                                                                                    | see Shared-World Evidence below                                                     |
+| Comms thread                      | `humanish.comms-thread.v1` (off-app email/SMS the app sent, captured; a `kind: log` run-dir artifact of digests only: from/to/subject/link digests + one OTP count, never raw)                                                                            | see `comms` under Study File                                                        |
+| Serve result                      | `humanish.serve-result.v1` (`src/observer/serve.ts` is authoritative)                                                                                                                                                                                     | none (command result envelope; see Serve Result below)                              |
+| Serve control plane               | reserved (`/_humanish/api/*` answers `501` `HUMANISH_SERVE_CONTROL_PLANE_DISABLED` in v1)                                                                                                                                                                 | none                                                                                |
 
 ## Study File
 
@@ -970,8 +970,9 @@ Core-owned fields:
 - optional `modelSettings.maxOutputTokens`: the declared positive integer
   `actor.maxOutputTokens`, passed to every first-party OpenAI CUA response
   request, including reasoning output. Absent when undeclared. The first request
-  of a session and closing reports use `min(maxOutputTokens, 1024)`, or 1024 when
-  undeclared; the first request also carries the opening screenshot as an
+  of a session uses `min(maxOutputTokens, 1024)`, or 1024 when undeclared, and
+  closing requests use `min(maxOutputTokens, 3072)`, or 3072 when undeclared; the
+  first request also carries the opening screenshot as an
   `input_image` after the instructions. Unsupported routes,
   custom provider/session hooks, and per-participant overrides fail before allocation.
   This is an output-token limit, not an input-token, request-count or billing cap.
@@ -1007,13 +1008,38 @@ Core-owned fields:
   `cacheWriteInput`. `summarizedTurns` counts the earlier exchanges the latest
   `explicit_context` request no longer carried whole: lines of the note, or
   only counted once the note reached its cap.
-  `requests[]` has one entry per participant request: its `mode` and, in
+  `requests[]` has one entry per participant turn or impressions request: its `mode` and, in
   `explicit_context`, `carriedExchanges`, `carriedScreenshots` and
-  `estimatedInputTokens`. Billed input per request is in `tokenUsage.turns`. A
+  `estimatedInputTokens`. The impressions-only request has `kind: impressions`;
+  the optional `kind` field is absent on participant turns and in older bundles.
+  Impressions carry the context the next turn would carry, with the same budget
+  and summarization of older turns. Billed input per request is in `tokenUsage.turns`. A
   participant that ran in `explicit_context` gets a run warning. Absent on other
   providers and on earlier bundles
 - optional `affordanceUse` (`humanish.affordance-use.v1`): which kind of route this
   actor took (see Affordance Use below)
+- optional `impressions`: what a computer-use participant said about the product
+  at the end of its session. `status: collected` carries `items[]`, each a
+  `kind` (`unclear`, `unfinished`, `untrustworthy`, `liked`, `missing`,
+  `unlike_my_work`), a redacted first-person `text` of at most 500 characters
+  and the `messageId` of the trace `message` that quotes it as
+  `Impression (<kind>): <text>`. They are not counted in `counts.messages`. Up
+  to six come from the closing account: a completed debrief's report, the
+  participant's own final account when its provider writes a structured one
+  (the Codex participant), or, when the participant ended the session itself
+  without them, one impressions-only request (OpenAI computer-use, threaded or
+  `explicit_context`). That request is recorded as `debrief` with `trigger:
+participant_end` and never has a `report` or `messageId`; it leaves the
+  participant's `reason`, outcome and friction as they were. An empty `items`
+  list means the participant named none. `status: not_collected` carries a
+  `reason`: the closing report or impressions request was skipped or failed
+  (including a reply cut off by the output limit), the participant ended the
+  session without a structured closing account and its provider cannot ask for
+  impressions (the Claude local agent), the closing account had no
+  impressions, or the session stopped before a closing account. Every
+  computer-use loop trace records one; absent on other routes and on earlier
+  bundles. `debrief.report` keeps only `summary` and `frictionReports`.
+  Impression messages do not count as participant-reported friction
 - optional `estimatedCost` (`humanish.actor-estimated-cost.v1`): a token-derived
   cost estimate for this participant (see Run Cost Summary And Estimated Actor Cost).
   It is deliberately a different field from `tokenUsage.costUsd`: a bare

package/docs/contracts/study-analysis.md

@@ -4,7 +4,7 @@ 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 admission estimate limit. Set `review.analysis: false` to disable that request;
+$3 cap on its expected cost. Set `review.analysis: false` to disable that request;
 see [automatic analysis](../product/automatic-analysis.md).
 
 ## Invocation
@@ -20,16 +20,30 @@ humanish analyze show --run latest --json
 The source must be a verified, completed live run. A dry-run contract bundle is
 not a participant study. Here, `analyze --dry-run` means checking an existing
 study's input and admission estimate without credentials, a provider request,
-or a new analysis artifact.
+or a new analysis artifact. It prints the expected cost, the worst case and the
+cap; a refused dry run says why, and names the `--max-cost` that admits it.
 
 The default provider is `openai`; its default model is `gpt-6-astra`, with high reasoning effort. A request sends selected retained text and
 captures to OpenAI, without tools, redirects, provider-side response storage, or
 automatic retries. `--question` adds a reviewer question; it never changes the
 participant assignment. For OpenAI API analysis, `--max-cost` is required, including for dry-run
-admission. It bounds a conservative estimate, not an exact provider bill.
-`--timeout-ms` and `--max-output-tokens` bound the request. An exceeded admission
-estimate retains valid findings and usage but returns a partial result and a
-nonzero command exit, including when that version is reused.
+admission. Admission compares the expected cost plus a 10% margin with it; the
+provider bill is not limited by it.
+`--timeout-ms` and `--max-output-tokens` bound the request. A bill above the
+worst case or the cap retains valid findings and usage but returns a partial
+result and a nonzero command exit, including when that version is reused.
+
+The estimate counts the instructions, evidence packet and result schema at 3
+UTF-8 bytes per input token, adds 2,048 framing tokens and each capture's
+high-detail image tokens, and prices input at the model's highest input rate.
+The expected output is 12,000 tokens plus 1,000 per participant, at most the
+output allowance; the worst case spends the whole allowance. `admission` in
+`--json` output has `estimatedCostUsd` (the expected cost), `worstCaseCostUsd`,
+`maxCostUsd`, `inputTokenAllowance` (the input tokens priced) and
+`outputTokenAllowance`. On 148 billed gpt-6-astra analyses the expected cost was
+1.08 to 7.3 times the bill, and 1.08 to 1.32 times for those billed $1 or more.
+A refusal's message gives the expected cost, the worst case, the cap, and
+`humanish analyze --run <id> --max-cost <n>` with `n` the worst case rounded up.
 
 The default deadline is ten minutes. With no explicit output-token limit, analysis
 uses 32,768 tokens if admission fits the declared budget, or retains the prior
@@ -266,6 +280,21 @@ a finding opens. Exposure and remaining unique limits are one disclosure away;
 observation details retain each original claim and its specific limitation.
 This presentation does not rewrite the saved analysis or reviewer corrections.
 
+## Participant impressions
+
+A computer-use participant's closing impressions (`ActorTrace.impressions`) reach the packet as
+ordinary `message` entries of that participant's stream, one per impression, with text
+`Impression (<kind>): <text>`. They are quote-eligible and attributed by `streamId`, so feedback,
+participant_statement observations and design findings can cite them under the existing rules.
+Selection admits them right after the participant's last entry, ahead of the rest of its
+session. The evidence mapping and `captureVersion` are unchanged.
+
+The `study-evidence-8` prompt adds one paragraph: impressions are the participant's own opinions,
+used as participant statements, and an `unlike my work` impression together with a capture of
+that screen is a strong design finding. Validation is unchanged. A design finding still needs at
+least one cited capture, so an impression plus the capture of its screen makes a design finding,
+and an impression alone supports only a finding about what the participant said.
+
 ## Durable records
 
 The frozen `humanish.observer-data.v1` schema is unchanged. A companion
@@ -289,7 +318,9 @@ describes:
 The optional automatic job is separate from the immutable analysis. Its view
 binds terminal state to the exact execution receipt and report. A stale or
 unverifiable job remains unknown; reading or exporting it never dispatches.
-Automatic job metadata is omitted from shared derivatives. See
+Automatic job metadata is omitted from shared derivatives. A job refused for its
+cost also records `admission` (`expectedCostUsd`, `worstCaseCostUsd`,
+`maxCostUsd`), which `review` and the Observer read; other jobs omit it. See
 [automatic analysis](../product/automatic-analysis.md).
 
 Version and correction directories are claimed exclusively; publication is
@@ -369,7 +400,9 @@ 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.
+  `analyze --max-cost 3`, which runs an analysis anyway. 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`
   reruns it with the same analyst, `--provider codex` for the Codex account analyst.
 - `none`: no analysis ran for this live run and nothing records why, for example a run that

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

@@ -39,7 +39,7 @@ certify (see the conformance suite).
    turn a dry run, preview, reader or unsupported route into provider or sandbox
    spend. An explicitly live supported study includes the disclosed default
    post-run analysis budget unless `review.analysis: false` disables it. Analysis
-   has a separate admission estimate limit, not a provider billing cap or part of
+   has a separate cap on its expected cost, not a provider billing cap or part of
    the actor budget. Spend-bearing tests retain their explicit env gates.
 4. **Evidence verifies fail-closed.** A run bundle that cannot pass verification (schema,
    redaction status, artifact presence, public-safety scan) is a failed run, even when the
@@ -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 admission estimate limit 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 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                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | 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. Every participant runs at once: `execution.concurrency` must be two or more, and an omitted value fills to the number of participants. 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,10 +3,10 @@
 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 admission
-estimate limit and a 600-second timeout. When no output limit is specified,
-humanish selects 32,768 tokens if the exact input's admission estimate fits that
-budget; otherwise it keeps the established 16,384-token allowance. This preserves
+The default is `gpt-6-astra` with high reasoning effort, a separate $3 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
 previously admitted studies without increasing their spending limit. To customize it:
 
 ```yaml
@@ -22,11 +22,15 @@ review:
 
 Omitting `review.analysis` uses these defaults. Set `review.analysis: false` to
 run participants without the additional analysis request. An explicit analysis
-mapping using the default OpenAI API provider requires `maxCostUsd`. This limits an admission estimate, not the
-provider's final bill, and is separate from participant spending limits. Analysis
-can decline a large study before dispatch when its conservative estimate exceeds
-that limit. Use `analyze --dry-run --max-cost <usd>` on retained evidence to inspect
-the estimate and selected token allowance before deliberately choosing a larger budget. Explicit
+mapping using the default OpenAI API provider requires `maxCostUsd`. Admission
+compares the expected cost plus a 10% margin with it; it does not limit the
+provider's final bill, and it is separate from participant spending limits. The
+estimate gives two numbers: the expected cost, and the worst case if the analyst
+spends its whole output allowance. `humanish study check` gives the expected cost
+range for the study's participant count, from a run that keeps no evidence to one
+at the evidence limits. 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
 includes reasoning as well as the report; exhausting it does not produce a usable
 report and never starts an automatic retry. Analysis
@@ -74,7 +78,7 @@ Default analysis also skips recordings containing only setup or failure records
 with no retained participant activity. A desktop startup failure does not start
 an analysis request. The original failure remains visible.
 
-CLI live starts disclose the selected analyst and its separate admission estimate limit or unknown account dollars before execution.
+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
 resolved budget without dispatching analysis. Library callers can inspect
 `resolveAutomaticAnalysis` or `automaticAnalysisBudget` before running.
@@ -101,11 +105,13 @@ for post-run analysis, and `ok` for the overall request. Failed, cancelled or
 unknown analysis produces exit code 2 without discarding the recording. 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 conservative estimate is over the default $3 limit: it is
-skipped with `AUTOMATIC_ANALYSIS_ADMISSION_REFUSED`, the run exits 0, and the CLI
-prints the `humanish analyze --run <id> --max-cost <usd>` command that runs it.
-A missing key or an over-limit estimate for an explicitly configured analysis
-remains a failed overall request. Every skip is retained for review and does not
+default analysis whose expected cost, plus the margin, is over the default $3 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
+the `humanish analyze --run <id> --max-cost <n>` command that runs it, `n` being
+the worst case rounded up. A missing key or an over-cap estimate for an explicitly
+configured analysis remains a failed overall request. Every skip is retained for review and does not
 retry automatically. Partial
 findings remain visibly partial; a valid partial result can succeed, while a
 partial result with an analysis error still fails the command. Recorded task
@@ -119,7 +125,7 @@ outcomes and the deterministic review verdict are never rewritten by analysis.
 | none (`null`)                                 | `complete`                | Analysis completed                                                    |
 | `AUTOMATIC_ANALYSIS_REUSED`                   | that of the reused result | An earlier analysis of this run was reused                            |
 | `AUTOMATIC_ANALYSIS_LIMITATIONS`              | `partial`                 | Analysis completed with recorded limitations                          |
-| `AUTOMATIC_ANALYSIS_ADMISSION_EXCEEDED`       | `partial`                 | Usage passed the admission estimate                                   |
+| `AUTOMATIC_ANALYSIS_ADMISSION_EXCEEDED`       | `partial`                 | Usage passed the worst case or the cap                                |
 | `AUTOMATIC_ANALYSIS_FAILED`                   | `failed` or `partial`     | Analysis failed, or an unexpected error stopped it                    |
 | `AUTOMATIC_ANALYSIS_CANCELLED`                | `cancelled`               | Ctrl-C or the TUI's **Cancel analysis** stopped it                    |
 | `AUTOMATIC_ANALYSIS_DRY_RUN`                  | `skipped`                 | A dry run records no participant evidence                             |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanish",
-  "version": "0.112.0",
+  "version": "0.114.0",
   "description": "Synthetic user research for apps, CLIs, and agent-facing product flows.",
   "keywords": [
     "cli",
@@ -91,7 +91,7 @@
     "comms:agentmail:contract": "node --import tsx scripts/agentmail-contract-check.mjs",
     "format": "oxfmt",
     "format:check": "oxfmt --check",
-    "lint": "node scripts/check-lint-cap.mjs --max-warnings=440",
+    "lint": "node scripts/check-lint-cap.mjs --max-warnings=439",
     "knip": "knip",
     "prose:check": "node scripts/check-code-prose.mjs",
     "vocabulary:check": "tsx scripts/check-retired-words.ts",

package/skills/humanish/SKILL.md

@@ -105,6 +105,11 @@ not local inference or the participant's existing conversation. See
 [the analysis contract](../../docs/contracts/study-analysis.md) for the current
 CLI/model qualification and setup limits.
 
+When post-run analysis is refused for its cost, the run output and `humanish
+review` give its expected cost, its worst case and the command that runs it,
+`humanish analyze --run <id> --max-cost <n>`. Show the user those costs and run
+the command only once they agree to the spend.
+
 Do not pass numeric `maxCostUsd`/`maxOutputTokens` or their CLI flags to the
 account branch. It cannot enforce those ceilings and rejects them. Account dollar
 cost remains unknown even when token usage is reported. There is no fallback to
@@ -190,16 +195,6 @@ Legacy profiles without it retain medium defaults for missing patience and
 technical confidence. Avoid contradictory prose and traits; inspect the compiled
 brief with `humanish study show <study> --json` before running.
 
-For an autonomous participant study, use a computer-use/local-agent study and write
-its `mission` as a believable situation and desired outcome. Supply fixture facts
-needed to act, but do not supply selectors, click sequences, hidden success rules,
-expected defects or recovery tricks. For example: “Saturday's event needs two
-setup volunteers and one cleanup volunteer. See whether this app helps you
-organize the event and keep people informed.” Do not instruct a participant to
-find a specific UI control merely to make the study succeed. Allow discovery,
-recovery and stopping appropriate to the participant. Keep researcher criteria in
-`tasks[].success`, separate from participant-facing `tasks[].goal`.
-
 Scripted regression checks are a different use of scenarios. When the requested
 work is deterministic verification of a known path, a `browser.steps` manifest
 can drive it with explicit selectors and assertions. It does not establish
@@ -232,6 +227,27 @@ tokens into scenario files.
 
 ## Authoring Studies
 
+For an autonomous participant study, write `mission`, participant `instruction`
+and `tasks[].goal` as a believable situation and desired outcome. Supply fixture
+facts needed to act. Leave discovery, recovery and stopping to the participant.
+Keep researcher criteria in `tasks[].success`.
+
+| Bad: scripts the controls                                                              | Good: gives a situation                                                                                                                            |
+| -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Click "New event", type a title into the field, then press "Save" and open "Settings". | Saturday's event needs two setup volunteers and one cleanup volunteer. See whether this app helps you organize the event and keep people informed. |
+
+`humanish study check` and `humanish run` warn about step lists, chains of UI
+actions, quoted control labels, CSS selectors and URLs beyond the subject's entry
+point. They quote up to three matched lines and suggest a situation-style mission.
+The checks apply to computer-use and shared-world studies; scripted-browser and
+terminal studies and `tasks[].success` are excluded. These warnings never refuse
+a run, and the run records them in its bundle.
+
+Give each participant a persona with a short, fictional `background` describing
+their relevant experience and situation. A missing persona or background also
+warns. Use `humanish study show <study> --json` to see what the participant receives.
+Do not supply hidden success rules, expected defects or recovery tricks.
+
 Write reusable studies as `.yaml` study files (`humanish.study.v3`):
 
 ```yaml