humanish 0.87.0 → 0.88.1

package/docs/release/0.88.0-study-diagnostics.md

@@ -0,0 +1,43 @@
+# Humanish 0.88.0: see what ended a study
+
+When a computer-use study stops before the task is done, `humanish lab run` now
+shows its diagnostic category and recorded stop cause. Fan-out results retain
+each participant's ending. Different endings remain mixed. Older generic budget
+stops retain an unspecified limit. Successful dry-runs are reported as contract
+previews.
+
+New review packets and feedback participant summaries use recorded interruption
+labels. Previously saved review packets keep their original wording.
+
+An adapter can use the new `CuaAdmissionLimitError` to declare that its local
+limit refused a request before dispatch. Humanish records **adapter admission
+limit** and ends the interaction without another retry, action or closing
+report. Earlier actions and measured usage remain available. A refusal of an
+optional closing report preserves the already observed task outcome. See the
+[adapter contract](../contracts/adapter-admission.md) for when this signal applies.
+
+If an earlier request stalled or had an ambiguous transport outcome, a later
+success or local refusal does not make its missing usage known. The cost summary
+keeps measured token estimates and an explicit unmeasured line. With a spending
+cap, Humanish skips the optional closing report while that usage is uncertain.
+
+Install with `npm install -g humanish@0.88.0`. CLI JSON adds optional diagnostics
+without changing the existing status or exit-code contract. Usage telemetry,
+enabled by default, adds two fields with fixed allowed values: diagnostic
+category and stop cause. See [TELEMETRY.md](https://github.com/danielgwilson/humanish/blob/main/TELEMETRY.md)
+for their scope and opt-out controls.
+
+## Verification and limits
+
+[Admission-limit checks](https://github.com/danielgwilson/humanish/pull/759)
+cover refusal before and after activity, sanitized error handling, preserved
+outcomes and unknown usage after both successful and refused retries.
+[CLI diagnostic checks](https://github.com/danielgwilson/humanish/pull/758)
+cover previews, mixed endings, missing causes, invalid evidence and telemetry
+allowlists. The required release checks also cover package installation,
+Observer rendering and the website.
+
+The admission signal depends on an accurate adapter declaration; it is not a
+provider billing receipt. Existing generic failures keep their recorded
+outcomes. This release does not infer causes from participant prose or establish
+why an older study failed.

package/docs/release/0.88.1-completion-evidence-and-local-app.md

@@ -0,0 +1,79 @@
+# Humanish 0.88.1: distinguish reported completion from condition matches
+
+When a computer-use participant says it finished, review and Observer now
+label that completion as **participant-reported**. A recorded `stopWhen` match
+or completed dwell window identifies a **recorded completion condition** instead.
+Missing, malformed or conflicting completion evidence is labeled unavailable.
+Zero-completion counts use **0/N recorded completions**, and aggregate stats use
+**recorded goal completions**.
+
+A matched condition establishes only that condition, not every aspect of the
+mission. The run gate and share-safety verification remain separate from task
+adjudication. This release adds no automatic semantic evaluator.
+
+Existing actor statuses, `participants.reachedGoal`, verdict values and
+denominators stay unchanged. Current review commands, Observer rendering and
+newly generated feedback drafts apply these labels to older runs while
+preserving original bundles and actor traces. Existing HTML exports keep their
+original renderer. Other actor routes retain their own completion semantics.
+
+## Run a local app from npm
+
+To connect your local app's state and actions to Humanish, start with the
+[complete npm example](../architecture/examples/state-driven-local-app/README.md):
+
+```bash
+npm install humanish@0.88.1
+node node_modules/humanish/docs/architecture/examples/state-driven-local-app/runner.mjs
+```
+
+It starts a synthetic loopback app, reads its state, sends a greeting through
+its HTTP action endpoint and verifies the recorded run. A `finally` block closes
+the app. The provider follows a deterministic rule, so the example needs no
+model credentials or E2B desktop. Use Node.js 20.3 or later.
+
+The runner supplies both `CuaExecutor` and `CuaProvider`, passes a decoded object
+to `parseLabConfig`, and checks the config and backend discriminants. The
+existing `stableProgressKey` utility is now exported from `humanish`, so callers
+can use the same bounded state projection as the loop. Replace the two ports
+with your app bridge and provider; the example guide explains the responsibilities
+that remain with them.
+
+## Clipboard fallback returns after the write
+
+When direct desktop typing fails, Humanish can write the text to the X clipboard
+and paste it. `xclip` and `xsel` fork a process to keep the selection available;
+inherited output pipes could leave the command runner waiting until timeout.
+Both clipboard-write commands now detach their output while preserving the
+existing exit checks, temporary-file cleanup and paste dispatch.
+
+Custom desktop images still need a working `xclip` or `xsel`. Missing utilities
+continue to report `clipboard-utility-missing`. This patch adds no typing retry,
+and recovery after a primary write inserted an unknown partial prefix remains
+unproven. [Issue #340](https://github.com/danielgwilson/humanish/issues/340) remains
+open for that broader typing problem.
+
+## Verification and limits
+
+[Completion label checks](https://github.com/danielgwilson/humanish/pull/765)
+cover participant reports, recorded condition matches, zero completions and
+unavailable legacy detail. They preserve recorded counts and statuses while
+refreshing historical review and feedback projections. Existing adapter
+narrative remains available.
+
+[The packaged example](https://github.com/danielgwilson/humanish/pull/762) completed
+two independent local runs on Node 20.20.2 and 24.12.0. Each made two HTTP state
+reads and one state-changing request, reached `goal_satisfied`, verified as
+`share_ready` and closed its server. These checks used locally packed candidate
+source labeled 0.88.0, distinct from the registry release with that version.
+
+[The clipboard correction](https://github.com/danielgwilson/humanish/pull/761)
+passed two real desktop conformance cases, one with explicitly installed `xclip`
+and one with `xsel`. Each preserved the exact Unicode/newline/quoted text with
+one paste and removed its transfer file. Both cases refused the primary write
+before it could type anything. They do not establish default-image clipboard
+availability or recovery from partial typing.
+
+Both checks were model-free. They establish the tested integration and executor
+behavior; persona effectiveness and independent maintainer adoption remain
+separate questions.

package/package.json

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