humanish 0.88.0 → 0.88.2

package/docs/architecture/examples/state-driven-local-app/app.mjs

@@ -0,0 +1,48 @@
+// @ts-check
+import { once } from "node:events";
+import { createServer } from "node:http";
+
+/** A synthetic app with a real loopback HTTP state/action contract. */
+export async function startLocalApp() {
+  let greeted = false;
+  let messages = 0;
+  let stateReads = 0;
+  const server = createServer(async (request, response) => {
+    if (request.method === "GET" && request.url === "/state") {
+      stateReads += 1;
+      response.writeHead(200, { "content-type": "application/json" });
+      response.end(JSON.stringify({ greeted, messages }));
+    } else if (request.method === "POST" && request.url === "/chat") {
+      // The demo accepts only a short synthetic message; it stores no raw text.
+      let text = "";
+      for await (const chunk of request) {
+        text += chunk.toString();
+        if (text.length > 1024) {
+          response.writeHead(413).end();
+          return;
+        }
+      }
+      messages += 1;
+      if (text.toLowerCase().includes("hello")) greeted = true;
+      response.writeHead(204).end();
+    } else {
+      response.writeHead(404).end();
+    }
+  });
+  server.listen(0, "127.0.0.1");
+  await once(server, "listening");
+  const address = server.address();
+  if (!address || typeof address === "string") throw new Error("No loopback port");
+
+  return {
+    appUrl: `http://127.0.0.1:${address.port}/`,
+    // These counters make real HTTP reads and state-changing writes inspectable.
+    getReceipt: () => ({ greeted, messages, stateReads, serverClosed: !server.listening }),
+    async close() {
+      await new Promise((resolve, reject) => {
+        server.close((error) => error ? reject(error) : resolve(undefined));
+        server.closeAllConnections();
+      });
+    }
+  };
+}

package/docs/architecture/examples/state-driven-local-app/runner.mjs

@@ -0,0 +1,104 @@
+// @ts-check
+import { LAB_CONFIG_SCHEMA, parseLabConfig, runLab, stableProgressKey, verifyRun } from "humanish";
+import { startLocalApp } from "./app.mjs";
+
+/** @param {string} appUrl @returns {import("humanish").CuaExecutor} */
+function createAppContractExecutor(appUrl) {
+  return {
+    async observe() {
+      const response = await fetch(new URL("state", appUrl), { signal: AbortSignal.timeout(5000) });
+      if (!response.ok) throw new Error(`State read failed: HTTP ${response.status}`);
+      const state = await response.json();
+      if (typeof state?.greeted !== "boolean" || !Number.isInteger(state?.messages)) {
+        throw new Error("Unexpected app state");
+      }
+      const appState = { greeted: state.greeted, messages: state.messages };
+      return { stateSignature: stableProgressKey(appState), appState };
+    },
+    async execute(action, signal) {
+      signal?.throwIfAborted();
+      if (action.kind !== "type") throw new Error(`Unsupported app action: ${action.kind}`);
+      const response = await fetch(new URL("chat", appUrl), {
+        method: "POST",
+        body: action.text,
+        signal: AbortSignal.any([AbortSignal.timeout(5000), ...(signal ? [signal] : [])])
+      });
+      if (!response.ok) throw new Error(`Chat write failed: HTTP ${response.status}`);
+    }
+  };
+}
+
+// A deterministic rule, not an AI participant: no model SDK, requests or credentials.
+/** @type {import("humanish").CuaProvider} */
+const provider = {
+  id: "local-app-deterministic-example",
+  version: "1.0.0",
+  requiresFrame: false,
+  capabilities: {
+    headless: true,
+    structuredTrace: true,
+    lanes: ["computer-use"],
+    producesScreenshots: false,
+    byoModel: true,
+    preGrantableApprovals: false,
+    inProcessTools: false,
+    license: "open"
+  },
+  async nextTurn(request, signal) {
+    signal.throwIfAborted();
+    const greeted = request.observation.appState?.greeted;
+    if (typeof greeted !== "boolean") throw new Error("Missing greeted observation");
+    return {
+      actions: greeted ? [] : [{ kind: "type", text: "hello there" }],
+      pendingSafetyChecks: [],
+      done: greeted,
+      message: greeted ? "The app accepted the greeting." : "Sending a greeting."
+    };
+  }
+};
+
+const app = await startLocalApp();
+try {
+  // parseLabConfig accepts a decoded OBJECT, not a YAML string.
+  const parsed = parseLabConfig({
+    schema: LAB_CONFIG_SCHEMA,
+    id: "state-driven-local-app-example",
+    title: "Deterministic local-app integration example",
+    subject: { source: "local-app", appUrl: app.appUrl },
+    // This registry id selects the CUA loop. buildProvider supplies the actual provider.
+    actors: [{ type: "openai-computer-use", persona: "pixel-pat", mission: "Greet the app." }],
+    scenario: { mode: "live" },
+    execution: { timeoutMs: 15_000 }
+  });
+  if (!parsed.ok) throw new Error(parsed.error.message);
+  const outcome = await runLab(parsed.config, {
+    cwd: process.cwd(),
+    dryRun: false,
+    cuaHooks: {
+      buildExecutor: async ({ appUrl }) => createAppContractExecutor(appUrl),
+      buildProvider: async () => provider
+    }
+  });
+  if (outcome.backend !== "cua") throw new Error(`Unexpected backend: ${outcome.backend}`);
+  const { result } = outcome;
+  const verified = await verifyRun(process.cwd(), result.runId);
+  console.log(JSON.stringify({
+    runId: result.runId,
+    ok: result.ok,
+    completionReason: result.session?.completionReason,
+    provider: provider.id,
+    sandboxCreated: result.sandbox !== undefined,
+    screenshots: result.session?.screenshots,
+    verification: verified,
+    app: app.getReceipt(),
+    // A mechanism statement, not an inference from missing provider usage/rates.
+    costBasis: "No model calls or hosted resources; only this process and loopback HTTP."
+  }, null, 2));
+  if (!result.ok || !verified.ok || result.session?.completionReason !== "goal_satisfied"
+    || result.sandbox !== undefined || !app.getReceipt().greeted) {
+    throw new Error(result.error?.message ?? "Local-app example did not complete and verify");
+  }
+} finally {
+  await app.close();
+  console.log(JSON.stringify({ cleanup: app.getReceipt() }));
+}

package/docs/architecture/state-driven-executor.md

@@ -52,8 +52,9 @@ wait and does not cache a previous action's position.
   `redaction.screenshots` resolves to `"n/a"`. No fabricated `Buffer.alloc(0)`
   ever reaches disk. (A vision executor still returns a frame, exactly as before.)
 - **`stateSignature` is still required.** Derive it from your own state — e.g.
-  `JSON.stringify({ route, turn, modal })`. It is the canonical fallback progress
-  key when `appState` is absent. It is never written to the trace as text.
+  `stableProgressKey({ route, turn, modal })` (exported from `humanish`). It is the
+  canonical fallback progress key when `appState` is absent. It is never written
+  to the trace as text.
 - **`appState` is the preferred progress input.** When present, the loop's
   friction / no-progress detection keys off a deterministic, sorted-key,
   depth/length-capped projection of it (`stableProgressKey`) rather than the
@@ -168,33 +169,25 @@ from your own state, pair it with a non-vision `CuaProvider`, and call
 
 ### 2. `runLab` + `buildExecutor` / `buildProvider` (keeps the composition)
 
-The supported library path. It keeps personas, the Observer, the evidence
-bundle, redaction, and the friction loop, while skipping E2B entirely:
+The supported library path keeps personas, the Observer, the evidence bundle,
+redaction, and the friction loop, while skipping E2B entirely. Start with the
+[complete runnable example](examples/state-driven-local-app/README.md), which
+ships in the npm package:
 
-```ts
-import { runLab, parseLabConfig, type CuaExecutor, type CuaProvider } from "humanish";
-
-// local-app YAML (shareable; fails closed without hooks):
-//   schema: humanish.lab.v2
-//   id: downstream-local-app-state
-//   subject: { source: local-app, appUrl: http://localhost:5173 }
-//   actors: [{ type: openai-computer-use, persona: curious-tester, mission: "…" }]
-//   scenario: { mode: live }
-const parsed = parseLabConfig(yaml);
-if (!parsed.ok) throw new Error(parsed.error.message);
-
-const outcome = await runLab(parsed.config, {
-  cwd: process.cwd(),
-  dryRun: false,
-  cuaHooks: {
-    buildExecutor: async ({ appUrl }) => createAppContractExecutor(bridge, appUrl),
-    buildProvider: async () => createStateBrain(),
-  },
-});
-// outcome.backend === "cua"; outcome.result.sandbox === undefined (NO E2B); the
-// trace's provider id is the injected brain's id.
+```bash
+npm install humanish
+node node_modules/humanish/docs/architecture/examples/state-driven-local-app/runner.mjs
 ```
 
+The example includes a real loopback app, HTTP state/action bridge, full config
+object (`schema: LAB_CONFIG_SCHEMA`), deterministic non-vision provider,
+`stableProgressKey`, `runLab`, verification, a printed report and `finally`
+cleanup. It makes no model calls and does not demonstrate persona efficacy.
+`parseLabConfig` accepts a decoded object, not a YAML string; narrow its result
+on `.ok`, then narrow `runLab`'s result on `backend === "cua"` before accessing
+the CUA result. The example defines all helpers rather than requiring a consumer
+to reconstruct them.
+
 When `cuaHooks.buildExecutor` is set, `runCuaActorLab` takes a branch that NEVER
 loads the E2B module, creates a sandbox, runs `prepareDesktop`, provisions a
 clone, opens a browser, or starts a stream. `sandboxId`/`streamUrl` stay

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.0`; it is not an exhaustive inventory of command/result envelopes. Exported types,
+`0.88.2`; 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.
@@ -210,7 +210,11 @@ A lab is a composition over code primitives, not a hardcoded kind:
   template actually used is recorded in the run bundle as `desktopTemplate`
   (public-safe — a template name is not a secret). Inert (warned) on every route
   that creates no desktop, incl. the in-process `local-app` cua route and the
-  meta route — never silently ignored (invariant 6);
+  meta route — never silently ignored (invariant 6). Custom images need the
+  Desktop SDK's `xdotool` input support and `xclip` or `xsel` on `PATH` for
+  clipboard recovery when direct typing fails. If both clipboard utilities are
+  absent, recovery fails with `clipboard-utility-missing`; a dry-run does not
+  inspect the image's installed tools;
 - `execution.desktop.browser` (e2b-desktop computer-use/fan-out routes, plus
   sequential and concurrent shared-world actor seats): optional browser family
   preference: `default`, `chrome`, `chromium`, or `firefox`. Absent/default
@@ -509,6 +513,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:
@@ -1063,8 +1077,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.
@@ -1077,6 +1092,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.
 
@@ -1228,6 +1278,16 @@ the stream shape, the meaningful-use rubric, and hard-failure rules.
 Review summarizes whether evidence supports the claim. It does not replace
 verification or maintainer acceptance.
 
+`verdict` is the run gate result. `participants.reachedGoal` retains the count of
+recorded successful sessions; it is not an independent adjudication of their
+claims. Computer-use review and Observer labels distinguish a participant's
+reported completion from a recorded `stopWhen` or dwell condition match. A
+condition match establishes that condition, not every aspect of the mission.
+Missing or malformed completion evidence is labeled unavailable. Other actor
+routes retain their own completion semantics. Re-reading a historical review
+refreshes these labels without rewriting the original bundle or actor trace.
+Share-safety verification does not establish task success.
+
 Core-owned fields:
 
 - `schema`

package/docs/goals/current.md

@@ -1,9 +1,9 @@
 # Current Goals
 
-Status date: 2026-09-11. Published baseline: `0.88.0`.
+Status date: 2026-09-13. Published baseline: `0.88.2`.
 
 This page guides work on current merged source. Published behavior is described
-in the [release notes](../release/0.88.0-study-diagnostics.md).
+in the [release notes](../release/0.88.2-sequential-study-budgets.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.0`)
+## Current Program Truth (source `0.88.2`)
 
 | Surface | Available in merged source | Remaining boundary |
 | --- | --- | --- |
@@ -98,7 +98,7 @@ substitute for it.
 | Task protocol | Hidden criteria and per-task outcomes on supported per-lane CUA paths, including local-agent and desktop-cli | Shared-world, terminal-product, scripted and synthetic routes reject `tasks` before execution |
 | 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 and redacted bundle derivatives | Sharing requires the appropriate grade; generated findings still need adjudication |
+| 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 |
 | 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 |
@@ -108,6 +108,11 @@ Use the [task support matrix](../architecture/task-protocol-support.md),
 and [CLI reference](https://humanish.dev/docs/cli) when choosing a concrete path.
 Source behavior and required tests outrank stale status prose.
 
+The library-assisted `local-app` route now includes a
+[runnable npm example](../architecture/examples/state-driven-local-app/README.md).
+Its deterministic provider demonstrates the integration with a real loopback
+app; it does not establish persona effectiveness or independent adoption.
+
 ## Gates And Deferred Work
 
 - Live OSS meta-lab execution remains disabled until repository-derived

package/docs/ramp/README.md

@@ -2,7 +2,7 @@
 
 Status: public-safe contributor and agent ramp.
 
-Package/source version in this tree: `0.88.0` (2026-09-11). 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.88.2` (2026-09-13). 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,16 @@ If a change does not improve one of those loops, it probably belongs elsewhere.
 
 ## Current State
 
+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
+and public `stableProgressKey` export, plus the clipboard fallback correction
+for inherited output pipes.
+
 The [0.88.0 release note](../release/0.88.0-study-diagnostics.md) describes
 computer-use CLI diagnostics, explicit local admission limits and retained
 uncertainty when an earlier provider request did not report usage.

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/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/package.json

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