humanish 0.88.1 → 0.89.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.88.1`; it is not an exhaustive inventory of command/result envelopes. Exported types,
+`0.89.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.
@@ -38,6 +38,9 @@ workflow without leaking private upstream truth into core.
 | 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` | 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 execution receipt | `humanish.analysis-execution.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` |
@@ -513,6 +516,16 @@ shared-world bundle adds TWO additive, optional fields to `humanish.run-bundle.v
 
   SEQUENTIAL shape (`topologyMode: sequential`, #164 PR1):
   - `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
+    `{ 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`,
+    `usage_unreported`, or measured `study_spend_limit`. Only the last cause
+    carries budget figures, using the same per-participant estimates as the
+    tracker. Blocked seats need matching simulation, stream and blocked-event
+    evidence, with no actor, trace, screenshot or invented timeline turn.
+    Historical bundles without this field still require every role in the timeline.
   - `timeline: (checkpoint | turn)[]` — a harness-clocked, strictly alternating
     timeline that starts `cp-baseline`, alternates checkpoint → turn → checkpoint,
     and ends on a checkpoint:
@@ -1067,8 +1080,9 @@ request's worst-case cost. In-flight requests, retries, concurrent lanes, and
 unreported usage can exceed or escape these estimates. These thresholds are
 not hard provider billing caps and exclude desktop and target-app charges.
 
-A lane with material progress that crosses `maxUsd` ends `budget_reached` /
-`incomplete`; the existing zero-action guard ends `gave_up` / `abandoned`.
+Crossing `maxUsd` ends `budget_reached` / `incomplete`, including when no
+material action has executed. The recorded reason distinguishes prior progress
+from no material progress; a harness budget stop is not participant abandonment.
 Crossing the shared study threshold ends `budget_reached` / `incomplete`, with
 sibling lanes stopping when their next post-response check sees it. Reaching a
 threshold is not proof of task completion.
@@ -1081,6 +1095,41 @@ threshold on a model `src/pricing.ts` cannot price is refused at preflight
 (`HUMANISH_CUA_LAB_UNPRICED_CAP`) before sandbox allocation. This rate-availability
 check is separate from the post-response spend check.
 
+Sequential shared-world studies (`subject.topology: shared-world` with
+`execution.concurrency: 1`, using clone or local-tree subjects) enforce these
+same per-participant and shared model thresholds. Final reported usage,
+including a closing request, is reconciled before admitting the next participant.
+After the aggregate threshold is crossed, later participants are `blocked` with
+a recorded skip reason; they make no model requests and add no executed turn to
+the checkpoint timeline. An unpriced model with a declared threshold fails
+before allocation with `HUMANISH_SHARED_WORLD_LAB_INVALID`.
+
+On this sequential route, an otherwise completed capped interaction that returns
+missing or partial usage stops with `harness_error`, `stopCause: usage_unreported`, and the label
+“provider usage unavailable.” It is not recorded as a crossed threshold. A
+stalled or failed request with unknown spend is not retried by the CUA loop.
+The default OpenAI adapter also disables HTTP and policy-negotiation retries for
+these strict capped sessions. The loop cancels its owned request signal when a
+request ends or its timeout wins; injected providers must honor cancellation
+and remain responsible for their own internal dispatch. Known usage remains in the
+trace alongside an explicit unknown; subsequent participants do not start when
+the shared budget cannot be established. Reported zero input and output counts
+remain valid zero usage. This stricter unknown-usage policy is specific to
+sequential capped studies; other routes retain their existing behavior. An
+explicitly incomplete provider response retains its original interruption cause
+first, with any missing usage still recorded as unknown.
+
+Sequential traces persist dated model estimates. Their run cost summary marks
+desktop compute as unmeasured, so the displayed model subtotal is a lower bound.
+The sequential route does not provide a running Observer usage stream; its final
+CLI and Observer projections read these persisted estimates.
+
+A capped custom session must return the declared model identity on its trace.
+A mismatch fails orchestration and blocks later participants while preserving
+the participant's original outcome and the estimate for its returned model.
+This check does not establish which model an arbitrary custom runner actually
+called or retrospectively enforce a runner that ignored its cap options.
+
 These computer-use rules do not replace the terminal route's separate
 `scenario.caps` cost-ledger and product-spend rules described above.
 

package/docs/contracts/study-analysis.md

@@ -0,0 +1,150 @@
+# Study analysis
+
+Study analysis is an optional 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.
+
+## Invocation
+
+```bash
+humanish analyze --run latest --max-cost 3 --dry-run --json
+humanish analyze --run latest --max-cost 3 --json
+humanish observe --run latest
+humanish analyze list --run latest --json
+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.
+
+The 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. `--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.
+
+The defaults allow five minutes and 16,384 output tokens, including reasoning.
+The analysis checks the assigned requirements against the retained end state;
+an unverified essential result remains unknown even if the participant reported
+success. Findings keep reported concerns and observed recovery distinct across
+participants. Other supported models can be selected explicitly, but evidence
+reference validation does not certify their interpretation of small visual details.
+
+Analysis distinguishes participant actions from harness setup and accounting.
+Runtime credentials or model usage do not establish that a participant made an
+external call while performing their task. Observations with an action basis
+must cite an action-bearing source; invalid source bases are rejected with the
+attempt's status and known usage retained.
+
+Identical source input, configuration, and prompt version reuse a current valid
+analysis. `--rerun` creates another immutable version. Failed attempts do not
+hide earlier valid findings. Ctrl-C cancels the request; usage remains unknown
+when the provider did not report it. Cancellation cannot undo an already accepted
+provider request.
+
+Decoded participant context, evidence text, and the reviewer question are checked
+for known sensitive-text patterns before dispatch. JSON escaping cannot bypass
+that check. Image bytes are not treated as text for pattern matching.
+
+Only one analysis command can own a run's `.analysis-lock` directory. Interrupted
+locks are not stolen using stored PIDs. After confirming the owning command has
+stopped, an operator can remove the empty lock directory and retry.
+
+## Evidence and findings
+
+The packet currently admits up to 16 participants, 800 evidence items, 40 PNG
+captures, 160 KiB of text and 20 MiB of images. Individual source files, image
+dimensions and result sizes have separate limits. Selection follows retained
+source order; it is not a statistically representative sample. Selection
+omissions and unreadable or invalid capture files make declared coverage
+incomplete. Coverage records file availability and selection; it does not
+certify visual legibility, correct interpretation, or exhaustive issue discovery.
+
+The standard review covers session summary, apparent intent, observed outcome,
+friction, dead ends, recovery, and participant feedback. Findings are ordered by
+observed task impact, replication among exposed participants, and recovery.
+Impact and confidence remain separate. There is no numeric frustration or
+universal priority score.
+
+Every observation cites packet-local evidence IDs. The model cannot choose a
+filesystem path or fetch another resource. Validation checks participant
+membership, unique counts, quote fidelity, evidence type and reference
+integrity. Visual claims require retained captures; screenshot-free evidence
+opens its original event. These checks do not prove that every interpretation
+is correct or every consequential issue was found.
+
+Elapsed replay time starts at the first retained capture. It is not a video
+offset. Nonvisual events retain event identity without invented frame offsets.
+
+## Durable records
+
+The frozen `humanish.observer-data.v1` schema is unchanged. A companion
+`humanish.study-analysis.v1` artifact records source/config/input hashes,
+participant context, evidence manifest, coverage, provider/model/prompt version,
+status, usage and validated findings:
+
+```text
+.humanish/runs/<run>/
+  analysis/<analysis>/analysis.json
+  analysis/<analysis>/corrections/<correction>/correction.json
+  analysis-attempts/<analysis>/receipt.json
+  observer/study-analysis.json
+```
+
+Version and correction directories are claimed exclusively; publication is
+atomic. Source evidence is not rewritten. Minimal execution receipts retain
+model, budget, status and known usage even if source changes prevent report
+publication. They contain no question, participant text, images, or findings.
+`analyze list --json` includes these receipts.
+
+Analysis and execution-history directories each admit 256 entries, including
+interrupted writes; correction history admits 256 entries per analysis. A new
+attempt requires readable inventories with room for its records before dispatch.
+Valid reuse remains available at capacity. The command does not remove old
+versions automatically. A present correction that cannot be read or validated
+blocks sharing and feedback promotion until the history can be checked.
+
+States distinguish no analysis, complete with no findings, complete with
+findings, partial, failed, cancelled, stale and invalid. A copied or modified
+source cannot silently inherit a current analysis. Saved HTML and the HTTP
+companion project validated records; generic HTTP serving of producer-owned raw
+analysis/correction JSON, execution receipts, atomic write temporaries and locks
+is disabled. Existing adapter captures and logs retain their contained routes.
+
+## Human review and sharing
+
+```bash
+humanish analyze correct --run latest --analysis <id> --finding F1 \
+  --status confirmed --reason "The cited captures reproduce the blocker."
+humanish analyze correct --run latest --analysis <id> --finding F1 \
+  --status amended --reason "The claim was too broad." --claim "A narrower supported claim."
+humanish feedback issue --run latest --analysis <id> --finding F1 --repo owner/repo
+```
+
+Corrections append against exact analysis and finding hashes. Confirming one
+version does not approve a later claim. Dismissed findings cannot become feedback
+drafts; amendments preserve the original and record the replacement. Feedback
+drafts include source/version/evidence references and remain explicitly
+independent of participant-authored candidates. No command above posts to GitHub.
+Each analysis has room for 256 correction inventory entries, including interrupted
+writes. A full or unsafe inventory refuses a new correction before creating its
+entry; prior records remain unchanged. Analysis and correction commands share the
+run lock so concurrent writers cannot overrun that bound.
+
+The existing sharing gate scans source and derived text. Export and feedback
+also check the exact in-memory analysis snapshot they include. Sensitive derived
+text blocks sharing and is quarantined from Observer, while independently
+verified source recordings remain viewable. Filesystem containment failures
+still fail closed. Valid failed/cancelled history alone does not downgrade
+sharing.
+
+Redacted bundle export omits analysis, corrections and execution receipts and
+records that omission in derivation provenance. Changed source bytes require
+new analysis; old hashes and review approvals cannot survive redaction. Ordinary
+legacy evidence under `analysis/` remains part of the recording and follows the
+normal redaction and sharing checks.

package/docs/goals/current.md

@@ -1,9 +1,9 @@
 # Current Goals
 
-Status date: 2026-09-12. Published baseline: `0.88.1`.
+Status date: 2026-09-14. Release baseline: `0.89.0`.
 
 This page guides work on current merged source. Published behavior is described
-in the [release notes](../release/0.88.1-completion-evidence-and-local-app.md).
+in the [release notes](../release/0.89.0-study-findings.md).
 The [September 9 history](https://github.com/danielgwilson/humanish/blob/main/docs/goals/current-history-2026-09-09.md)
 preserves the former status log; its queues do not supersede this page.
 
@@ -88,7 +88,7 @@ requires decision-equivalent retained evidence and a real deletion branch.
 No first-party deletion branch has met that gate. Public demonstrations do not
 substitute for it.
 
-## Current Program Truth (source `0.88.1`)
+## Current Program Truth (source `0.89.0`)
 
 | Surface | Available in merged source | Remaining boundary |
 | --- | --- | --- |
@@ -99,6 +99,7 @@ substitute for it.
 | Shared state | Sequential and concurrent single-origin shared-world studies with retained evidence | Multi-origin implementation remains gated; concurrent state change does not establish per-action causation |
 | Observer | Live/recorded views, participant assignments, action-specific links, saved moments, zoom, comparison and phone-width review | Sparse captures cannot prove every action's effect; visual comparison alone is not a controlled experiment |
 | Review and feedback | Verification grades, feedback drafts, portable HTML, redacted bundle derivatives and computer-use completion-source labels | Sharing requires the appropriate grade; participant reports and condition matches still need task adjudication |
+| Study findings | Explicit `analyze`, bounded evidence selection, versioned findings, exact source links and append-only corrections within the Observer study shell | Model interpretation needs review; bounded selection and source truncation limit coverage; opening Observer never dispatches analysis |
 | TUI and serving | Detached starts, run stopping, reclamation, Observer attachment, loopback serving and run library | Stopping a process does not itself prove sandbox cleanup; TUI views over CLI `stats`/`export` remain follow-ups |
 | Off-app communication | In-sandbox email/SMS catch and digest-only thread evidence | This does not establish real-provider delivery |
 | Mobile and media | Hosted viewport/emulation, desktop geometry checks, bounded dwell and declared camera feed | Physical-device and touch fidelity remain unproven; unsupported microphone declarations are rejected |

package/docs/ramp/README.md

@@ -2,7 +2,7 @@
 
 Status: public-safe contributor and agent ramp.
 
-Package/source version in this tree: `0.88.1` (2026-09-12). The Observer is phone-usable as a stated requirement (observer/AGENTS.md); interactive primitives start from Base UI. The Observer renderer is the observer/ workspace artifact only; the legacy string-concat renderer was deleted at cutover (#426), and rollback is a version pin to 0.42.0. The containment boundary introduced in
+Package/source version in this tree: `0.89.0` (2026-09-14). The Observer is phone-usable as a stated requirement (observer/AGENTS.md); interactive primitives start from Base UI. The Observer renderer is the observer/ workspace artifact only; the legacy string-concat renderer was deleted at cutover (#426), and rollback is a version pin to 0.42.0. 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
@@ -47,6 +47,15 @@ If a change does not improve one of those loops, it probably belongs elsewhere.
 
 ## Current State
 
+The [0.89.0 release note](../release/0.89.0-study-findings.md) describes explicit
+analysis of completed studies, versioned findings and review corrections, exact
+evidence links, and Participants / Findings within one Observer shell. Analysis
+remains separate from participant feedback and recorded outcomes.
+
+The [0.88.2 release note](../release/0.88.2-sequential-study-budgets.md)
+describes model-spend thresholds on sequential shared-world studies, blocked
+later participants, and explicit unknown-usage accounting.
+
 The [0.88.1 release note](../release/0.88.1-completion-evidence-and-local-app.md)
 describes computer-use labels that distinguish participant reports from
 recorded condition matches. It also covers the complete npm local-app example
@@ -82,7 +91,9 @@ pnpm humanish -- verify --run latest --json
 Implemented:
 
 - `commander` CLI with stable command help;
-- `init`, `doctor`, `run`, `watch`, `verify`, `review`, `runs`, and `feedback`;
+- `init`, `doctor`, `run`, `watch`, `verify`, `review`, `runs`, `analyze`, and `feedback`;
+- opt-in study analysis with bounded provider admission, immutable findings,
+  source-bound corrections and evidence-linked Observer review;
 - synthetic run bundles;
 - public-safety verification with machine-readable `shareSafety.status`
   (`share_ready`, `local_only`, or `blocked`);

package/docs/release/0.88.2-sequential-study-budgets.md

@@ -0,0 +1,57 @@
+# Humanish 0.88.2: sequential studies honor model-spend thresholds
+
+Sequential shared-world studies now enforce the `execution.caps.maxUsd` and
+`maxTotalUsd` thresholds they previously accepted without applying. This covers
+computer-use participants sharing a clone or local-tree subject with
+`subject.topology: shared-world` and `execution.concurrency: 1`.
+
+Each participant's reported usage feeds the per-participant threshold and the
+shared study estimate. Final usage, including a closing report, is reconciled
+before the next participant starts. A participant interrupted by a threshold
+has `budget_reached` / `incomplete`; its reason distinguishes prior activity
+from no material progress. Later participants blocked by the shared threshold
+make no model requests and add no executed turn to the checkpoint timeline.
+A closing report that crosses the threshold preserves the already recorded
+completion condition while blocking subsequent participants.
+The bundle retains all declared participants and an explicit blocked suffix.
+Verification checks the suffix against its preceding interruption, participant
+records and unchanged executed timeline; absent participants cannot masquerade
+as budget-blocked seats.
+
+These checks happen after a model response and before its actions or another
+participant turn. The current request can overshoot a threshold. They estimate
+model spend; they do not reserve future requests or cap provider invoices,
+desktop compute, or target-app charges. A zero threshold can still allow the
+first model request. Use an explicit dry-run for a path without provider calls.
+
+An unpriced model with a declared threshold is refused before allocation. For
+an otherwise completed response, missing or partial usage ends capped sequential
+execution with `harness_error` and `usage_unreported` (“provider usage unavailable”).
+The CUA loop sends no further participant request, retry or closing request.
+An explicitly incomplete provider response retains its original interruption
+cause first; its missing usage remains unknown. For these strict capped sessions,
+the default OpenAI adapter makes one dispatch per requested turn, including
+HTTP errors and policy negotiation. The loop cancels the request signal when
+its timeout wins, so an outstanding transport cannot retry after the loop ends.
+Injected providers must honor that signal and control their own dispatches;
+cancellation cannot undo an already billed request. Known partial costs stay
+in the trace, and an unknown shared budget blocks later participants.
+
+Sequential traces now retain dated model estimates. The run total explicitly
+marks desktop compute as unmeasured, so the model subtotal is a lower bound.
+Observer labels a partial estimate as known cost with the total unknown.
+A custom session returning a different model identity fails orchestration and
+blocks later participants while preserving its original outcome and the
+estimate for its returned model. This does not retrospectively enforce an
+arbitrary custom runner that ignored its cap options.
+
+Existing bundles are not rewritten. Uncapped sessions and other execution
+routes retain their existing behavior. The stricter unknown-usage rule applies
+to sequential capped studies; the sequential route still has no running
+Observer usage stream.
+
+Verification covers the actual participant loop with captured provider usage,
+individual and shared thresholds, unstarted seats, zero and missing usage,
+closing requests, model mismatches, checkpoint evidence and cleanup. These
+contract checks establish the tested behavior; they do not establish persona
+effectiveness, independent adoption, or exact provider billing.

package/docs/release/0.89.0-study-findings.md

@@ -0,0 +1,79 @@
+# Humanish 0.89.0: evidence-linked study findings
+
+Completed studies can now produce ranked findings with links to the participant
+events and captures that support them. Observer keeps Participants and Findings
+inside the same study shell, with the recording grid, original participant
+feedback and playback controls available throughout the review.
+
+## Analyze a completed study
+
+```bash
+npm install humanish@0.89.0
+npx humanish analyze --run latest --max-cost 3 --dry-run --json
+npx humanish analyze --run latest --max-cost 3 --json
+npx humanish observe --run latest
+```
+
+Select a verified, completed live run. The first analysis command checks admission
+without credentials or a provider request; the second requires `OPENAI_API_KEY`
+and sends selected text and captures to OpenAI. The required cost ceiling bounds
+a conservative estimate, not the provider's invoice. Opening Observer never
+starts analysis.
+
+The standard analysis covers session summary, apparent intent, observed outcome,
+friction, dead ends and recovery. Findings explain task impact, affected and
+exposed participants, evidence and limitations. Participant reports, recorded
+completion conditions and independent analysis remain separate. Missing evidence
+can leave an outcome unknown even when the participant reported success.
+
+Identical source input, configuration and prompt version reuse a saved analysis.
+`--rerun` requests a new immutable version; `--question` adds a reviewer question.
+The default is `gpt-6-astra` with high reasoning, a five-minute timeout and 16,384
+output tokens including reasoning. Each attempt makes one stateless request,
+without tools or automatic retries, and retains known usage or explicit
+uncertainty.
+
+## Review findings against the recording
+
+Participants and Findings share the study library, header and available width.
+Ranked findings expand in place and open their exact source event. A screenshot
+shown only as context is labeled accordingly; nonvisual evidence opens its
+original event without inventing a frame. Playback links, return navigation and
+phone controls retain their source context. The scrubber thumb and track now
+share the same centerline, with component geometry checks at multiple sizes.
+
+Use `analyze list` and `analyze show` to inspect history. `analyze correct` appends
+a confirmed, dismissed or amended review against the exact analysis and finding
+hashes. Original claims and evidence remain intact. Full correction history
+refuses another write before existing records become unreadable; analysis and
+correction writers share the run lock.
+
+Feedback drafting and export validate the included analysis snapshot and retain
+the existing sharing gates. Redacted bundle derivatives omit analyses tied to
+the original source bytes. A local-only HTML export remains portable and clearly
+labeled. Feedback commands print drafts; they do not post to GitHub.
+
+## Compatibility and verification
+
+The Observer data v1 contract is unchanged. Older recordings remain readable,
+and absent, failed, stale or invalid analysis does not erase participant evidence.
+The CLI also explains empty participant-feedback candidates and the available
+run-summary drafting path.
+
+[The feature implementation and verification](https://github.com/danielgwilson/humanish/pull/773)
+cover analysis validation and storage, sharing boundaries, the existing Observer
+flows, mobile layout, component geometry and fresh-package review/export paths.
+Final source-first model review covered five exposed regression cases and two
+untouched controlled task families, with a separate hostile-evidence challenge.
+That is bounded validation, not a general accuracy benchmark. One conservative
+outcome required an explicit task-scope reconciliation; one accurate positive
+recovery item did not motivate a product change.
+
+Evidence selection follows source order and has size/count limits; upstream
+truncation also constrains what can be established. Schema and reference checks
+do not certify interpretation or exhaustive issue discovery. Review the cited
+evidence before acting. Browser proof uses Chromium desktop and phone emulation;
+physical-device and cross-browser behavior remain separate verification work.
+
+See the [study-analysis contract](../contracts/study-analysis.md) for limits,
+artifact layout, cancellation, corrections and sharing behavior.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanish",
-  "version": "0.88.1",
+  "version": "0.89.0",
   "description": "Open-source-safe CLI for persona simulation, observer review, and public-safe feedback drafts.",
   "author": "Daniel G Wilson <daniel@danielgwilson.com>",
   "keywords": [
@@ -93,7 +93,8 @@
     "commander": "^14.0.3",
     "playwright-core": "^1.60.0",
     "pngjs": "^7.0.0",
-    "yaml": "^2.9.0"
+    "yaml": "^2.9.0",
+    "zod": "^4.4.3"
   },
   "peerDependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.0",