humanish 0.113.0 → 0.115.0

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,32 @@ 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`,
+`admittedCostUsd` (the figure compared with the cap: the expected cost plus 10%,
+or the worst case when that is lower), `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
@@ -191,7 +207,13 @@ The narrative scrub removes a run's known transient values, such as a received o
 link, from every generated text field. It finds each value as written and in its encoded forms:
 percent-encoded, JSON-escaped, base64, base64url and hex, and where escapes split it. A field
 with a value is stored decoded with the value replaced; a field without one keeps its spelling. A
-known value in any of these forms in an ID, enum or reference refuses the response.
+value inside a bracketed span, such as `[REDACTED_373433393231]`, is found too: only the markers
+humanish writes (`[REDACTED_SECRET]`, `[REDACTED_LOCAL_PATH]`, `[REDACTED_RUNTIME_PATH]`,
+`[REDACTED_PROMPT_TEXT]`, `[REDACTED_LOBBY_CODE]`) are left as they are. If another reading of
+the stored field still holds a value (decoded once more, with percent escapes as UTF-8, with
+transfer escapes expanded, or with Latin-1 characters read as UTF-8 bytes), as for a value encoded
+twice, the whole field becomes `[REDACTED_SECRET]`. A known value in any of
+these forms in an ID, enum or reference refuses the response.
 
 When a reviewer amends a finding, its headline and experience describe the replaced claim.
 Text output, the Observer and feedback drafts show the reviewer's claim in their place and say the
@@ -304,7 +326,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 +408,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.115.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",
@@ -112,13 +112,14 @@
     "@e2b/desktop": "^2.4.0",
     "@types/node": "catalog:",
     "@types/pngjs": "^6.0.5",
-    "axe-core": "4.13.0",
-    "knip": "6.38.0",
+    "axe-core": "4.14.0",
+    "fast-check": "catalog:",
+    "knip": "6.40.0",
     "oxc-parser": "catalog:",
-    "oxfmt": "0.71.0",
-    "oxlint": "1.86.0",
+    "oxfmt": "0.72.0",
+    "oxlint": "1.87.0",
     "oxlint-tsgolint": "7.0.2003",
-    "skills": "1.7.0",
+    "skills": "1.7.1",
     "tsx": "^4.23.15",
     "typescript": "catalog:",
     "vitest": "catalog:"

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
@@ -337,8 +342,7 @@ The following configuration selects **local capture**:
 ```yaml
 comms:
   email:
-    injectEnv:
-      RESEND_API_URL # adopter-named: whatever env var YOUR app reads for its
+    injectEnv: RESEND_API_URL # adopter-named: whatever env var YOUR app reads for its
       # email-API base URL. The harness sets it to the in-sandbox catch — do NOT also
       # list it in subject.env. VERIFY the app actually reads this variable: a stock
       # email SDK does not honor a base-URL env unless the app passes it through, and