humanish 0.36.1 → 0.38.0

package/docs/contracts/schemas.md

@@ -3,7 +3,7 @@
 Date: 2026-06-02 (current-state note updated 2026-07-14)
 
 Status: reference map for the major contracts shipped through source version
-`0.36.1`; it is not an exhaustive inventory of command/result envelopes. Exported types,
+`0.38.0`; it is not an exhaustive inventory of command/result envelopes. Exported types,
 schema constants, parsers, and validators in `src/` are authoritative. Rows
 marked "reserved" name layering intent only — no code emits or validates them
 yet. Do not emit a reserved schema.
@@ -46,6 +46,7 @@ workflow without leaking private upstream truth into core.
 | Pricing (operator-editable rates) | `humanish.pricing.v1` (`src/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 |
+| 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 |
@@ -257,7 +258,7 @@ A lab is a composition over code primitives, not a hardcoded kind:
   including app-url/operator-provided subjects and the sequential
   `concurrency: 1` shared world, neither of which has a catch to host): off-app
   email/SMS the app itself SENDS, made a persona-driven testable surface.
-  `comms.email` = `{ kind: fake, injectEnv, port?, recipients?, linkOrigin? }`.
+  `comms.email` = `{ kind: fake, injectEnv?, port?, recipients?, linkOrigin?, external? }`.
   `injectEnv` is the ADOPTER-NAMED env var the app reads for its email-API base
   URL (e.g. `RESEND_API_URL`); the harness sets it to an in-sandbox catch (so it
   is NOT declared in `subject.env`) that captures the app's sends without touching
@@ -273,7 +274,23 @@ A lab is a composition over code primitives, not a hardcoded kind:
   listing them, zero addressed lanes is a hard error, partial coverage warns
   with the uncovered lanes. Each addressed lane's actor prompt is extended with
   the full handoff: its address ("enter exactly that"), the inbox URL, and the
-  wait steering ("waiting for an email is normal, not a blocker"). `linkOrigin`
+  wait steering ("waiting for an email is normal, not a blocker").
+  `external` (#328) switches the funnel to an ADOPTER-HOSTED catch, which is what
+  makes comms work on planes humanish does not provision (app-url /
+  operator-provisioned): `{ catchBaseUrl, inboxBaseUrl?, authTokenEnv? }`. The
+  operator runs the catch — `humanish comms catch` runs the same implementation
+  humanish deploys in-sandbox, so the capture shape, inbox surface, and drain
+  contract cannot drift between the two planes — and points their own app's
+  email-API base URL at it. `injectEnv` is then absent and meaningless, since
+  there is no subject env for humanish to inject. humanish keeps every other
+  part: per-lane addresses, the injected inbox handoff, a fail-closed readiness
+  probe before any actor spend (GET /health must return the
+  `humanish-comms-catch` marker, so a proxy answering 200 for everything cannot
+  pass for a catch), the teardown drain over `GET /deliveries`, and the same
+  digest-only evidence. `authTokenEnv` names an env var holding a bearer token
+  for the drain read — the NAME is recorded as evidence, the value never
+  persists. Declaring `external` on a harness-provisioned subject warns: two
+  catches would exist and the app would point at humanish's own. `linkOrigin`
   is an optional operator-declared origin the app bakes into links when it
   differs from the serve origin; the harness rewrites captured links through it
   so a clicked link resolves to a reachable host. Captured mail is drained into a
@@ -708,6 +725,8 @@ Core-owned fields:
   distinct from `timed_out`, which stays reserved for a zero-progress deadline
   hit and remains a failure)
 - `ids`, `counts`, `items[]`, optional `tokenUsage`, `capabilities`
+- optional `affordanceUse` (`humanish.affordance-use.v1`): which KIND of route this
+  actor took (see Affordance Use below)
 - optional `estimatedCost` (`humanish.actor-estimated-cost.v1`): a token-derived
   cost ESTIMATE for this lane (see Run Cost Summary And Estimated Actor Cost).
   It is deliberately a DIFFERENT field from `tokenUsage.costUsd`: a bare
@@ -928,6 +947,46 @@ model `src/pricing.ts` cannot price is REFUSED at preflight
 (`HUMANISH_CUA_LAB_UNPRICED_CAP`) before any sandbox rather than run uncapped —
 an unenforceable cap is more dangerous than none.
 
+## Affordance Use
+
+`humanish.affordance-use.v1` (additive `ActorTrace.affordanceUse`) records WHICH
+KIND of route an actor took, per dispatched action, as counts by class:
+
+| Class | What it covers |
+| --- | --- |
+| `pointer` | click, double-click, drag, scroll — interaction with what is rendered |
+| `keyboard` | typed text and key presses into the page |
+| `url-navigation` | typing a URL (the `nav` subset) — a HUMAN affordance, see below |
+| `script-execution` | a `javascript:` or `data:` URL — not a human affordance |
+| `devtools` | developer tooling opened by keyboard chord |
+| `browser-internal` | `chrome://`, `about:`, `view-source:`, `file:` — the browser, not the product |
+| `observation` | screenshots, waits, bare pointer moves — the actor looking rather than acting |
+
+`counts` omits classes that never occurred; `total` is the denominator for any
+rate; `shortcutTotal` rolls up `script-execution` + `devtools` +
+`browser-internal`, and a value of `0` is a meaningful result rather than an
+absence.
+
+Direct URL navigation is deliberately its OWN class and is grouped with the
+naturalistic classes, not with script execution: `load(url)` appears in 99.4% of
+2,337 real human web demonstrations, so address-bar use is ordinary human
+behavior and classifying it as a shortcut would make an ordinary human lane look
+unfaithful. See [`docs/principles/actor-fidelity.md`](../principles/actor-fidelity.md)
+for the evidence and the scoping of what a fidelity claim can mean.
+
+The record carries a CLASS and at most a scheme-shaped signal (`javascript:`,
+`https:`, a devtools chord) — never the typed text, which can be a password, a
+session token, or an identifying URL path. Classification runs at dispatch
+because the text exists only there: the trace's own action label deliberately
+renders `type [N chars]`.
+
+The harness states NO verdict about a class. Whether an affordance invalidates a
+study depends on the population that study declares, which is product semantics
+and belongs to the adopter's scorer — which already receives the full trace, so
+`affordanceUse` needs no extra wiring to reach it. Present on computer-use lanes
+that dispatched at least one action; absent elsewhere and on every pre-existing
+bundle, and its absence is tolerated by verify.
+
 ## Product-Adapter Extension Seam
 
 The terminal-product and browser/computer-use lanes let an adopter attach

package/docs/goals/current.md

@@ -16,7 +16,7 @@ Humanish should be the open-source CLI that lets a maintainer ask:
 The answer should be observable, verifiable, public-safe, and easy to turn into
 actionable feedback.
 
-## Current Program Truth (source `0.36.1`)
+## Current Program Truth (source `0.38.0`)
 
 The package source and repository implementation in this tree agree on these
 points:

package/docs/principles/actor-fidelity.md

@@ -0,0 +1,165 @@
+# Actor Fidelity: whose behavior is this evidence about?
+
+Status: research digest + design position. Sources are public papers and open-source
+harnesses; every claim below carries its citation so it can be argued with rather
+than inherited.
+
+## The question
+
+A computer-use actor in a study of a consumer web app typed a `javascript:` URL into
+the browser address bar to get past a step. The run finished green.
+
+Whether that is a defect depends entirely on a question the harness never asked:
+**who is this study's user?**
+
+- If the declared users are **people**, it is a defect — and a costly one. The actor
+  routed around the friction the study existed to measure, so a passing run proves
+  nothing about the human experience. Worse, it is silent: nothing in the bundle
+  distinguishes that run from one where a person clicked through.
+- If the declared users are **agents** — as they are for an agent-facing CLI, API, or
+  MCP surface — the same act is faithful. It is the user population behaving normally,
+  and the fact that the agent had to reach for that affordance is itself a product
+  finding about how legible the surface is to its actual users.
+
+The proof roadmap already anticipated this: its strongest evidence class,
+`user-census`, is defined as "the users of the product ARE agents, and the lab runs
+real production harnesses." This page is the layer that makes the distinction
+operable.
+
+## What the evidence says
+
+### Direct URL navigation is a human affordance
+
+WebLINX built its action space from 2,337 real human demonstrations; `load(url)`
+appears in 2,324 of them — 99.4%, roughly 1.6 times per session
+([arXiv 2402.05930](https://arxiv.org/abs/2402.05930)). Treating address-bar
+navigation as non-human would make a human-declared lane *less* faithful, not more.
+The anomalous class is script execution and developer tooling, not URL entry.
+BrowserGym already factors these apart: its `nav` subset is exactly
+`{goto, go_back, go_forward}`, separate from everything else
+([arXiv 2412.05467](https://arxiv.org/abs/2412.05467)).
+
+### Prose instructions are a weak control for action modality
+
+- Tool-restriction constraints in realistic agentic prompts are honored 19.9–27.2% of
+  the time (AgentIF).
+- When a constraint conflicts with the task goal, obedience falls to 9.6–45.8%, and
+  models usually do not register the conflict ("Control Illusion").
+- Rule-file effects are largely content-independent: random rules tie with curated
+  ones, and shuffling changes little — measured specifically on agent skills and
+  persona definitions ([arXiv 2604.11088](https://arxiv.org/abs/2604.11088)). A
+  modality rule can therefore appear to work while doing nothing.
+- Persona adherence decays over a long trajectory rather than holding
+  ([arXiv 2512.12775](https://arxiv.org/abs/2512.12775)).
+
+The one large-scale prompt-level modality constraint in the literature —
+Online-Mind2Web instructing agents not to use search — was not trusted by its own
+authors, who published the measured constrained-vs-unconstrained delta (26% vs 31%)
+instead of asserting the instruction took effect
+([arXiv 2504.01382](https://arxiv.org/abs/2504.01382)). That is the discipline this
+project copies: where a constraint cannot be mechanically enforced, measure what it
+was worth.
+
+### Broad motivational reframes have backfired; narrow countable ones have worked
+
+Making realism the actor's stated objective is an appealing fix, and the nearest
+measured attempts went the wrong way. A findings-informed realism persona prompt
+lowered overall simulator fidelity (User-Sim Index 70.9 → 64.6) and worsened outcome
+calibration (0.18 → 0.29): "moving some behaviors closer to humans can move others
+further away" ([arXiv 2603.11245](https://arxiv.org/abs/2603.11245)). Explicitly
+licensing persona-faithful failure fixed the *marginal* rate five-fold but left the
+*conditional* structure nearly unchanged — it taught the simulator to disengage
+uniformly rather than to disengage when a real user would
+([arXiv 2606.20708](https://arxiv.org/abs/2606.20708)). By contrast, a narrow,
+countable instruction did produce a measured improvement
+([arXiv 2601.17087](https://arxiv.org/abs/2601.17087)).
+
+Two further cautions for prompt design: telling an actor it is being observed and
+scored is a documented behavior-changing cue whose effect grows with model scale
+([arXiv 2505.17815](https://arxiv.org/abs/2505.17815)), and stating the grading
+criterion to the actor invites optimization of the stated metric. Pre-action
+self-checks are worse than neutral: deliberation before acting degrades constraint
+adherence in most models measured ([arXiv 2505.11423](https://arxiv.org/abs/2505.11423)),
+and chain-of-thought is an unreliable report of what actually drove an action
+([arXiv 2505.05410](https://arxiv.org/abs/2505.05410)) — an actor that takes a
+shortcut and then narrates a plausible justification for it is the expected output,
+not an edge case.
+
+What does hold, in the same literature: periodic re-injection of a short persona
+contract (large, cheap, replicated), and grounding a persona in specifics rather
+than exhorting it to be faithful (interview-grounded personas measurably beat prose
+descriptions).
+
+### Outcome-only scoring cannot see modality
+
+WebArena's URL evaluator scores on the final page URL, so a single `goto` to the
+reference URL earns full credit ([arXiv 2307.13854](https://arxiv.org/abs/2307.13854)).
+τ-bench states the general form: a state-based reward is necessary but not
+sufficient, since it cannot see whether policy was followed
+([arXiv 2406.12045](https://arxiv.org/abs/2406.12045)). And the gradient is real —
+calling site APIs instead of driving the UI roughly doubles WebArena scores
+([arXiv 2410.16464](https://arxiv.org/abs/2410.16464)). Any harness that scores only
+outcomes should expect actors to find that gradient, and should not be surprised when
+a green run proves nothing.
+
+## The position this project takes
+
+**Declare, record, and let the adopter judge.**
+
+1. **Declared population is a property of a persona, not of a lab.** One study program
+   can legitimately run agents and people against the same surface; the comparison
+   between them is a finding, not a contradiction. Prior art runs both populations
+   through one instrument and reports the difference
+   ([SusBench](https://arxiv.org/abs/2510.11035); MAS-Bench's GUI/shortcut split,
+   [arXiv 2509.06477](https://arxiv.org/abs/2509.06477)).
+
+2. **Record which affordance class each action used.** Recording is the layer that
+   makes every other claim checkable, including whether the persona prompt worked at
+   all. It is also the only honest answer to a defect whose verdict depends on a
+   declaration the harness cannot verify.
+
+3. **Do not bake a verdict.** Whether an affordance invalidates a study is product
+   semantics, and product semantics belong to the adopter's scorer
+   (`review.scorer.ref`). The harness emits facts; the adopter decides what they mean.
+
+4. **Prompt guidance ships as a nudge whose take-rate is reported, never as the
+   mechanism.** The evidence above is what that sentence is standing on.
+
+5. **Fail closed only on harness integrity, never on product semantics** — a lane that
+   cannot report what it did is a broken instrument, which is a different thing from
+   an actor that behaved unexpectedly.
+
+## What this does not claim
+
+Fidelity here is scoped to **affordance and decision** level: which routes an actor
+took, and whether they belong to the declared population. It is not a claim of
+behavioral realism. At the kinematic level — pointer paths, timing, motor noise — the
+gap between agents and people is total and trivially detectable
+([arXiv 2604.09574](https://arxiv.org/abs/2604.09574)). Any claim beyond the
+affordance/decision level would be dishonest, and this project does not make one.
+
+Two further limits worth stating plainly. Restricting script execution and developer
+tooling for *fidelity* reasons has no precedent — where such restrictions exist
+elsewhere, the stated motive is code-execution safety — so this is new ground rather
+than an inherited convention. And nobody has yet measured whether affordance-class
+recording changes what adopters decide; that is the experiment this layer makes
+possible, not a result it can assume.
+
+## Vocabulary
+
+Terms are borrowed rather than coined, so results stay comparable with the
+surrounding literature:
+
+| Term | Source | Meaning here |
+| --- | --- | --- |
+| action space / action set | WebArena, BrowserGym, OSWorld | the set of actions an actor can express |
+| `nav` subset | BrowserGym | `goto`, `go_back`, `go_forward` — direct navigation, a human affordance |
+| naturalistic actions | AndroidWorld | the human-modality subset, contrasted with exposed function-calling APIs |
+| shortcut action | MAS-Bench | a non-UI route to the same outcome (API, deep link, script) |
+| algorithmic fidelity | Argyle et al., *Out of One, Many* | how well a conditioned model emulates a specific population |
+| Agent Experience (AX) | Biilmann (Netlify) | the experience of a product whose users are agents |
+
+Three collisions to avoid: "agent usability testing" already means an agent
+*simulating* a human, which is the opposite of the agent-population case; `cheat()` in
+BrowserGym means the reference solution, not misbehavior; and "reward hacking" refers
+to attacking a grader, which is a different failure from routing around a UI.

package/docs/ramp/README.md

@@ -2,7 +2,7 @@
 
 Status: public-safe contributor and agent ramp.
 
-Package/source version in this tree: `0.36.1` (2026-08-07). The containment boundary introduced in
+Package/source version in this tree: `0.38.0` (2026-08-07). The containment boundary introduced in
 `0.15.1` remains in force: managed run and output paths bind to validated
 physical filesystem identities, and stored provider IDs are evidence, not
 cleanup authority. The bundled OSS meta-lab is dry-run only until

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanish",
-  "version": "0.36.1",
+  "version": "0.38.0",
   "description": "Open-source-safe CLI for persona simulation, observer review, and public-safe feedback drafts.",
   "author": "Daniel G Wilson <daniel@danielgwilson.com>",
   "keywords": [