humanish 0.113.0 → 0.114.0

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

@@ -1008,9 +1008,12 @@ 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

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
@@ -304,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
@@ -384,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.113.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