humanish 0.112.0 → 0.113.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/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/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.
@@ -1014,6 +1015,28 @@ Core-owned fields:
   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

@@ -266,6 +266,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanish",
-  "version": "0.112.0",
+  "version": "0.113.0",
   "description": "Synthetic user research for apps, CLIs, and agent-facing product flows.",
   "keywords": [
     "cli",

package/skills/humanish/SKILL.md

@@ -190,16 +190,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 +222,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