humanish 0.114.0 → 0.116.0

package/docs/contracts/schemas.md

@@ -169,7 +169,7 @@ The rest of this section names keys by their v3 spelling:
 - `subject.state` (clone or local-tree subjects, computer-use route): the
   subject's state story. `state.seed[]` declares ordered, bounded
   seed/migration/fixture steps (`{ name, command, when: before-build |
-before-start | after-ready, timeoutMs }`) executed in-sandbox around the
+  before-start | after-ready, timeoutMs }`) executed in-sandbox around the
   serve sequence; `state.external[]` declares env var names (each must also
   appear in `subject.env`) pointing at state the study does not control,
   recorded as unpinned in provenance. Commands persist in evidence as
@@ -189,7 +189,7 @@ before-start | after-ready, timeoutMs }`) executed in-sandbox around the
   single participant (no E2B to fan out);
 - a `participants` list (computer-use E2B route): a differentiated fan-out,
   each entry `{ id?, actorType?, surface?, caseGroup?, persona?, device?,
-instruction?, target?, entry?, host?, reasoningEffort?, stopWhen?, dwell? }` becoming one independent E2B desktop (or, on the
+  instruction?, target?, entry?, host?, reasoningEffort?, stopWhen?, dwell? }` becoming one independent E2B desktop (or, on the
   shared-world routes, one participant against the shared plane). `actorType`,
   `surface`, and `caseGroup` are adapter-owned public-safe labels for grouping
   simulated users; they are not core enums, and `actorType` is deliberately
@@ -317,9 +317,9 @@ instruction?, target?, entry?, host?, reasoningEffort?, stopWhen?, dwell? }` bec
   fail-closed cap in force. `maxMinutes` is the
   wall-clock kill; `maxUsd`/`maxJobs` are enforced fail-closed against the cost
   ledger after the session (a run whose known spend exceeds the cap fails closed,
-  `HUMANISH_TERMINAL_CAPS_EXCEEDED`). Core records Codex provider spend as
-  unpriced tokens and measures no product, media or payment spend, so no line can trip a
-  positive `maxUsd`: a live run refuses `maxUsd > 0` before creating a sandbox
+  `HUMANISH_TERMINAL_CAPS_EXCEEDED`). Core prices the Codex participant's tokens as an
+  estimate that the cap does not count, and measures no product, media or payment spend, so no
+  line can trip a positive `maxUsd`: a live run refuses `maxUsd > 0` before creating a sandbox
   (`HUMANISH_TERMINAL_UNPRICED_CAP`). A terminal `maxUsd` cap has no adopter cost source
   until [issue 347](https://github.com/danielgwilson/humanish/issues/347) lands;
   `StudyDeps.costProbe` is a test seam. The sandbox's server-side timeout is the steps before the
@@ -529,20 +529,23 @@ Core-owned fields:
   an older run, else `inferLegacyStudyId`, which reads the `persona.source` or `scenario.source`
   convention `study:<id>`, or `lab:<id>` from runs written before 0.108, and nothing else.
 - `subject` (optional, additive): structured subject provenance,
-  `{ source: clone | app-url | local-tree, repo?, commit?, archiveSha256?,
-dirty?, envNames?, state }` where `state` is `{ provenance: seeded |
-unpinned | declared-not-run | undeclared | external-public, seed?: [{ name, when,
-commandDigest, ok?, exitCode?, timedOut?, durationMs? }], externalEnvNames?
-}`. Emitted by the computer-use and shared-world routes and the clone
+  `{ source: clone | app-url | local-tree | desktop-cli, repo?, product?, commit?,
+  archiveSha256?, dirty?, envNames?, state }` where `state` is `{ provenance: seeded |
+  unpinned | declared-not-run | undeclared | external-public, seed?: [{ name, when,
+  commandDigest, ok?, exitCode?, timedOut?, durationMs? }], externalEnvNames?
+  }`. Emitted by the computer-use and shared-world routes and the clone
   scripted-browser route; absent on pre-existing and other bundles. `repo`/`commit` are clone-route fields; `archiveSha256`
   (64-hex sha256, the local-tree provenance pin) and `dirty` (host git
   porcelain status at pack time) are local-tree-route fields, additive under
   `humanish.run-bundle.v1`: a dirty working tree cannot be commit-pinned, so
-  the archive content digest stands in for it. `commandDigest` is the
+  the archive content digest stands in for it. `product` is the desktop-cli field: the
+  `subject.product.name` the study declares, with state `undeclared`. A computer-use
+  run of a desktop-cli study saved before this field existed records `app-url` with no
+  `product`. `commandDigest` is the
   sha256-16 of the exact seed command; command text and env values never
   appear. `humanish verify` fails closed when a live `local-tree` bundle carries
   no well-formed `archiveSha256`, in addition to the existing `subject state
-provenance` check.
+  provenance` check.
 - `desktopTemplate` (optional, additive): the custom E2B desktop template (image)
   the run's sandbox(es) launched on, from `execution.desktop.template`, so the
   evidence shows which image ran. Present only when a template was configured;
@@ -665,7 +668,7 @@ A shared-world bundle adds two additive, optional fields to `humanish.run-bundle
   0.106.0):
   - `sequence: [roleId, …]`: the role ids that actually took a turn, in declared order.
   - `skippedTail` (optional, live sequential only): `{ afterRoleId, roles,
-cause, maxTotalUsd?, estimatedTotalUsd? }`. Each ordered `roles` entry names
+    cause, maxTotalUsd?, estimatedTotalUsd? }`. Each ordered `roles` entry names
     `{ roleId, simId, streamId }` for an unstarted participant. Together with the
     executed prefix it must account for the full declared denominator. The
     predecessor must have a matching `harness_error`, explicit `session_error`,
@@ -700,7 +703,7 @@ cause, maxTotalUsd?, estimatedTotalUsd? }`. Each ordered `roles` entry names
     the internet-reachable getHost URL is synthetic seeded data (author-trust + a
     provenance gate, not a no-real-data guarantee).
   - `laneWindows: [{ roleId, simId, streamId, startedAt, endedAt, verdict, routeHostDigest,
-commit?, seedDigest }]`: one harness-clocked window per actor; overlapping windows
+    commit?, seedDigest }]`: one harness-clocked window per actor; overlapping windows
     prove ≥2 personas were active simultaneously. `routeHostDigest` == `plane.hostDigest`
     (every actor drove exactly the harness-minted host).
   - `stateSeries: [{ timestamp, digest }]`: cadence digests of the shared world under
@@ -1029,7 +1032,7 @@ Core-owned fields:
   (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_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
@@ -1142,15 +1145,20 @@ discipline** that distinguishes three states and never conflates them:
 
 `knownTotalUsd` sums only the non-null lines (a `null` line contributes nothing
 and is never coerced to `0`); `fullyMeasured` is true only when no line is null.
-Core meters only the `provider` line, populated from the actor trace's
-`tokenUsage.costUsd` when present (else `null`); `product`/`media`/`payment`
+Core meters only the `provider` line, from the actor trace's `tokenUsage.costUsd` when present
+(the Codex usage records the terminal route reads carry none today); `product`/`media`/`payment`
 remain `null`, because no adopter can supply those signals until
-[issue 347](https://github.com/danielgwilson/humanish/issues/347) lands. The terminal route records the model as `codex` and does not pin Codex's
-model, so a measured token count stays `usd: null` with `source: unpriced-token-usage`, and
-`knownTotalUsd: 0` with `fullyMeasured: false` means no line of this ledger was priced. E2B
-time for the terminal sandbox is not a line of this ledger, whose lines are checked against
-`caps.maxUsd`. The run bundle's `cost` summary prices it as a `desktop-minutes`
-line (see Run Cost Summary And Estimated Actor Cost below).
+[issue 347](https://github.com/danielgwilson/humanish/issues/347) lands. Without a measured
+charge the `provider` line keeps `usd: null` and counts the participant's tokens. The route
+passes Codex a model and prices the tokens once from it (the actor trace's `estimatedCost`); the
+line carries that price as `estimatedUsd` with `source: estimated-token-usage`, the same figure as
+the run bundle's `model-tokens` cost line. The estimate is not part of `knownTotalUsd`, so
+`caps.maxUsd` and the no-spend proof do not count it. Tokens of a model with no rate stay
+`source: unpriced-token-usage` with the model named in the note, and a run whose output had no
+usage record has `source: unmeasured`. `knownTotalUsd: 0` with `fullyMeasured: false` means no
+line of this ledger was measured. E2B time for the terminal sandbox is not a line of this ledger,
+whose lines are checked against `caps.maxUsd`. The run bundle's `cost` summary prices it as a
+`desktop-minutes` line (see Run Cost Summary And Estimated Actor Cost below).
 
 ```yaml
 schema: humanish.terminal-cost-ledger.v1
@@ -1159,7 +1167,8 @@ lines:
   product: { usd: null, count: null, source: unmeasured, note: "…no signal yet…" }
   media: { usd: null, count: null, source: unmeasured, note: "…no signal yet…" }
   payment: { usd: null, count: null, source: unmeasured, note: "…no signal yet…" }
-  provider: { usd: null, source: unmeasured, note: "…no tokenUsage.costUsd this run…" }
+  provider:
+    { usd: null, estimatedUsd: 0.37157, source: estimated-token-usage, note: "…estimated at…" }
 knownTotalUsd: 0
 fullyMeasured: false
 ```
@@ -1171,9 +1180,9 @@ it explicitly cannot vouch for). `satisfied` is true only when every known line
 is within `maxUsd` (for a no-spend run, `maxUsd: 0` ⇒ every known line is `0`).
 Unmeasured lines never break it, so a ledger whose lines are all `null` is
 `satisfied` with nothing proven. The `statement` says which case applies: it
-names the measured lines and their dollars, provider tokens that were counted
-but unpriced (with the counts), and the lines with no signal; when no line was
-measured it says the proof was not established. A proof never claims zero on a
+names the measured lines and their dollars, the provider tokens that were counted
+(with the counts, and their estimate or that they are unpriced), and the lines with
+no signal; when no line was measured it says the proof was not established. A proof never claims zero on a
 `null` line; verification fails closed if it does.
 
 ```yaml
@@ -1374,7 +1383,7 @@ Three new `.v1` schema tags ship, all additive and optional so
   the E2B shell sandbox (its acquired-to-cleanup span and `e2b.getInfo` size) and
   one `model-tokens` line for the Codex participant, priced from the model the route passed
   to Codex (`gpt-5.6-sol` unless the study declares one) with `basis:
-aggregated_turns_base_rate`, or `null` with `no_token_usage`. Older terminal bundles record
+  aggregated_turns_base_rate`, or `null` with `no_token_usage`. Older terminal bundles record
   `no_rate_for_model` (model `codex`). The terminal trace records the same `estimatedCost`. The sandbox line is not part of the
   terminal cost ledger, whose lines are checked against `caps.maxUsd`.
 
@@ -1674,7 +1683,7 @@ record its own:
 
 - **Adapter score** (`humanish.adapter-score.v1`, `RunBundle.adapterScore`).
   A namespaced summary the adapter's `score` hook returns: `{ schema, namespace,
-status, score, summary, data? }`. Core never reads `data`, where the adopter's
+  status, score, summary, data? }`. Core never reads `data`, where the adopter's
   component rubric rides; `namespace` (an adopter slug) scopes the whole
   record so a future inert-field audit never misfires.
 - **Namespaced product-noun block** (`RunFeedbackCandidate.adapter`). The

package/docs/contracts/study-analysis.md

@@ -39,9 +39,11 @@ 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.
+`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.
 
@@ -203,9 +205,24 @@ analysis, and treats an analysis that breaks them as unavailable.
 
 The narrative scrub removes a run's known transient values, such as a received one-time code or
 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
+percent-encoded, JSON-escaped, base64, base64url and hex, and where escapes split it. Base64 and
+hex forms are searched from 6 characters. A value of 4 bytes, such as the code `7439`, is found
+in base64 written whole (`NzQzOQ` or `NzQzOQ==`) and not inside a longer base64 run, where 4 or 5
+characters of its encoding do not depend on the bytes around it;
+`tests/evidence/secret-scrub.test.ts` records the case. The cost of the short forms is
+over-redaction: an identifier that holds a short value's base64 loses that part, as
+`aMTIzNAz` becomes `a[REDACTED_SECRET]z` while the code `1234` (`MTIzNA`) is registered, since a
+match cannot tell whether the identifier came from the value. In the text of 9 real runs, no 6-
+or 7-character form of any 4-, 5- or 6-digit code occurred. Run evidence is scrubbed for the same
+forms. 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

package/docs/product/automatic-analysis.md

@@ -102,7 +102,9 @@ accepted. Known usage is retained; missing usage remains unknown.
 
 The CLI's JSON keeps `runOk` for the route's own result, `automaticAnalysis`
 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
+unknown analysis produces exit code 2 without discarding the recording. When the
+run's own result is ok, the first line of the human output reads
+`humanish run <study>: live run finished; the analysis did not complete`. A missing
 `OPENAI_API_KEY` skips default analysis and preserves a successful run exit;
 `automaticAnalysisTrigger: "default"` distinguishes that case in JSON. So does a
 default analysis whose expected cost, plus the margin, is over the default $3 cap:
@@ -144,5 +146,9 @@ outcomes and the deterministic review verdict are never rewritten by analysis.
 | `AUTOMATIC_ANALYSIS_CANCELLATION_UNAVAILABLE` | `unknown`                 | A cancellation could not be recorded                                  |
 | `AUTOMATIC_ANALYSIS_OUTCOME_UNKNOWN`          | `unknown`                 | The outcome could not be determined                                   |
 
+A run refused before it was created (`run: not-created`) prints no `analysis:` line, since there
+is no run to analyze and the refusal says why. Its JSON keeps the record, with
+`AUTOMATIC_ANALYSIS_SOURCE_UNAVAILABLE`, or `AUTOMATIC_ANALYSIS_DRY_RUN` for a dry run.
+
 See the [analysis contract](../contracts/study-analysis.md) for selection limits,
 evidence validation, actual usage, corrections and share-safe export behavior.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanish",
-  "version": "0.114.0",
+  "version": "0.116.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=439",
+    "lint": "node scripts/check-lint-cap.mjs --max-warnings=436",
     "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

@@ -342,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