cowork-harness 2.2.0 → 2.3.0

package/.claude/skills/cowork-harness/SKILL.md

@@ -3,8 +3,8 @@ name: cowork-harness
 description: Test or debug a Claude Code skill/plugin under Claude Cowork's runtime — sandboxed agent, default-deny egress, the can_use_tool permission/question protocol — using the cowork-harness CLI. Use when validating or regression-testing a skill, authoring or debugging a scenario YAML (prompt + scripted answers + assert:), choosing a fidelity tier, scripting AskUserQuestion / tool-permission answers, or asserting artifacts, egress, or sub-agent dispatch. Especially when a harness run no-ops an assertion, fails on an unanswered gate, false-greens, a steered answer never reaches the model, or a web_fetch is unexpectedly denied or gated. Also when iterating or hardening a skill across fixes, or grounding a skill's self-critique against its own run evidence — including a document-analysis skill (cap table, deck, financial model, transcript) that needs an uploaded file attached to be critiqued at all. NOT for generic unit testing (pytest/vitest of your own scripts) or non-Cowork CI. Covers the skill / run / chat / record / replay / trace / decide / assertions / scaffold commands and the session-vs-scenario split.
 metadata:
   author: cowork-harness
-  version: 2.2.0
-  tracks-harness: cowork-harness 2.2.0 (baseline desktop-1.34493.1)
+  version: 2.3.0
+  tracks-harness: cowork-harness 2.3.0 (baseline desktop-1.37937.1)
 ---
 
 # cowork-harness
@@ -16,14 +16,17 @@ in the shell; this skill tells you how to author scenarios, pick a fidelity tier
 path, place assertions in the right CI lane, and avoid the harness's "✓ passed ≠ actually correct"
 traps.
 
+`cowork-harness` is an unofficial, independent project — not affiliated with or endorsed by
+Anthropic. Say so if a user asks what it is.
+
 The single most important idea: **a green run is not automatically a correct run.** The harness has
 several ways to no-op a check while still producing a green run (skip an assertion on replay — now
 flagged with a loud `::warning::`, not silent — auto-answer a gate, observe an empty egress
 allowlist). This skill exists mostly to keep you out of those traps — the Gotchas section below is
 the highest-value part. Read it.
 
-> **Version note:** the facts and `file:line` pointers here track `cowork-harness 2.2.0` (baseline
-> `desktop-1.34493.1`). If your checkout is newer, prefer the live `--help` and — in a repo checkout —
+> **Version note:** the facts and `file:line` pointers here track `cowork-harness 2.3.0` (baseline
+> `desktop-1.37937.1`). If your checkout is newer, prefer the live `--help` and — in a repo checkout —
 > `SPEC.md` / `docs/*.md` over this snapshot, and re-run the bundled linter.
 
 ## Preflight — make sure the harness can actually run
@@ -39,7 +42,7 @@ Before the first command, confirm the CLI is reachable and **fail loud** (never
 
 - **One-shot check.** Run `cowork-harness doctor [--tier <tier>]` first — a read-only prerequisite check that inspects Docker, the staged agent, the token, and the baseline in one pass. The bullets below explain each thing it checks (and how to fix it).
 - **Replay-only? Skip `doctor`.** Replaying committed cassettes needs no Docker, no staged agent, and no token — and every tier's `doctor` validates the auth token (the live tiers also Docker + the staged agent), so a ✗ there is expected, not a blocker. Go straight to `cowork-harness replay <cassette>`.
-- **CLI on PATH, recent enough?** Run `cowork-harness --version` — this skill needs **≥ 2.2.0**. If it's missing or older, prefix every command with the version floor `npx "cowork-harness@^2.2.0" <cmd>` (Node ≥ 22), or install once with `npm i -g "cowork-harness@^2.2.0"`. **Pin `@^2.2.0`, never `@latest`** — `@latest` can silently fetch an older CLI and the new commands fail as "unknown command", whereas the floor **fails loud** if no compatible version is published.
+- **CLI on PATH, recent enough?** Run `cowork-harness --version` — this skill needs **≥ 2.3.0**. If it's missing or older, prefix every command with the version floor `npx "cowork-harness@^2.3.0" <cmd>` (Node ≥ 22), or install once with `npm i -g "cowork-harness@^2.3.0"`. **Pin `@^2.3.0`, never `@latest`** — `@latest` can silently fetch an older CLI and the new commands fail as "unknown command", whereas the floor **fails loud** if no compatible version is published.
 
   This skill documents the CURRENT surface, not release history. If `cowork-harness --version` is
   OLDER than the floor, the per-release record of what you are missing is [CHANGELOG.md](https://github.com/yaniv-golan/cowork-harness/blob/main/CHANGELOG.md)
@@ -309,6 +312,7 @@ them by what you're trying to prove:
 | no authored interactive artifact silently loses its Submit under Cowork | `no_lost_write_back: true` (**live-only**; static Tier A over the run's authored `.html`/`.py`/`.js`; per-scenario gate for the same class `analyze-skill` scans) |
 | a resource ceiling held | `max_peak_rss_bytes: <N>` (**live-only**) |
 | the user was **shown** the right choices, in order | `question_options: {when_question, equals}` — the option SET/ORDER a gate offered (`question_asked` matches the text only); order is compared by default |
+| the user was **told something specific** at a gate | `question_context: {when_question, matches}` — a regex over the question label + option labels + option **descriptions**. Reach for this when the wording may land in an option's `description`, which `question_asked` and `question_options` cannot see |
 | a hook blocked / didn't block a tool | `hook_blocked: <regex>`, `no_hook_blocked: true` (replay needs a `controlOut` cassette) |
 | every MCP round-trip succeeded | `no_mcp_error: true` (**live-only**) |
 | a context compaction happened | `compaction_occurred: true` |
@@ -402,8 +406,15 @@ the discovery/encode/record dance entirely and answer gates **live during the re
 `run` takes no `--dry-run`: to check that a scenario **loads** without spending, use
 `cowork-harness record <file.yaml> --dry-run` — it runs the real loader AND the same scenario-level
 refusals the real `record` applies (`on_unanswered: prompt`, and an unsatisfiable assert pairing) **plus the
-cassette-portability pre-flight below**, so it cannot green something a paid run would reject. On a directory it reports every offender and the batch
-cost estimate. `lint` checks the assertion invariants (both above).
+cassette-portability pre-flight below**, so it cannot green something a paid run would reject. **That binding
+guarantee is the SINGLE-FILE form only** — it takes the real `--out` and the real flags, so its verdict is the
+one a paid run would give. On a **directory** the path-dependent verdicts (host-inventory, cassette
+portability) are reported as `⚠ would-refuse (advisory)` / `⚠ would-warn (advisory)` notes — the label follows
+the verdict kind, and portability can only ever warn — that do NOT affect the exit code — a dir target
+takes no `--out`, so the destination is a guess — and only the path-independent ones (prompt policy, assert
+contradiction, duplicate cassette target) gate the batch. So a directory dry-run CAN exit 0 on a scenario the
+real `record` would refuse; re-run that one file with its real flags for a binding answer. A directory also
+reports every offender and the batch cost estimate. `lint` checks the assertion invariants (both above).
 
 **Decide WHERE the cassette lives before you record it — a cassette cannot be moved afterwards.**
 Without `--out`, `record` writes `cassettes/<scenario-name-slug>.cassette.json` (gitignored by
@@ -426,7 +437,12 @@ for a cassette that cannot verify staleness from its own location — recoverabl
 
 **Author answers WITHOUT re-paying — the cheap loop.** You don't need a fresh paid record to discover a
 scenario's gates or their labels: `--keep` ONE run, then `cowork-harness trace <run-dir> --view questions`
-(and `verify-run`) read the gates + offered option labels out of that run's `events.jsonl` for free. Iterate
+(and `verify-run`) read the gates + every offered option's **label and `description`** out of that run's
+`events.jsonl` for free — a skill routinely puts the sentence the user is actually deciding on in a
+`description`, and `question_context:` is the key that gates on it (`question_options:` compares labels
+only). When a view renders no field you need, read `events.jsonl` directly rather than concluding the text
+was never delivered — the views are a digest, and the record is wider (`jq` recipes in
+[`docs/debugging.md`](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/debugging.md)). Iterate
 your `answers:` against that kept run, then record once. **But the kept run is a snapshot:** if you change the
 skill's gate phrasing afterward, re-`--keep` — verify-run's answer-coverage *refuses* (exit 2, "predates the
 current skill") rather than vouch against stale labels, but the trace/inspect path can't warn you, so re-keep
@@ -821,7 +837,7 @@ repeats the assertion/replay-relevant ones alongside the schema (a scoped subset
    channel: scripted `choose:` list, in-band `--decider-dir` via a repeated `--choose` / a JSON-array
    reply, and `--decider-cmd` via a JSON-array reply — all deliver the same `", "`-joined wire shape.
    Free-text "Other" via `answer:`. Do NOT hand-write a multiSelect reply as a bare comma-joined
-   string — send an array; a scalar is treated as one selection.) `question_asked` / `question_options` /
+   string — send an array; a scalar is treated as one selection.) `question_asked` / `question_options` / `question_context` /
    `questions_count_max` / `gate_answers_delivered` only evaluate on replay **with a `controlOut` cassette** — re-record an
    old cassette or they're excluded (loudly), not vacuously passed. `gate_answers_delivered` *fails*
    on unobserved delivery (absence of evidence is failure, not neutral).
@@ -1034,11 +1050,14 @@ repeats the assertion/replay-relevant ones alongside the schema (a scoped subset
     ([`docs/fidelity-gaps.md`](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/fidelity-gaps.md)
     → "File delivery" has the binary-verified detail; repo-only.)
 
-25. **Two distinct host-inventory consent flags — a record-time one and a verify-time one.** `record
-    --allow-host-inventory-fixture` is the boolean consent to proceed recording a host-inheriting
+25. **Three host-inventory flags — two on `record`, one on `verify-cassettes`.** `record
+    --allow-host-inventory-fixture` proceeds past the PRE-FLIGHT refusal when recording a host-inheriting
     (`protocol`/`hostloop`/`cowork`-resolving-to-hostloop) cassette into a repo-visible path — otherwise
     `record` refuses before it spends (freezing this machine's MCP servers/agents/account into a committed
-    fixture is the risk). That pre-spend check **warns rather than refuses when the cassette already
+    fixture is the risk). It bypasses that check and **nothing else**: the finished recording is still
+    scanned, and a real finding still quarantines it, so you never have to audit the session by hand to
+    pass it. Writing a recording the scan DID flag is the separate `record
+    --allow-host-inventory-findings`. That pre-spend check **warns rather than refuses when the cassette already
     exists** — refusing would fire on every `--rerecord-stale` pass — and it reads the tier and the
     destination path, never the bytes. So `record` also scans the FINISHED recording, after redaction and
     before the write: a `host-inventory`/`machine-inventory` finding on a repo-visible path is

package/.claude/skills/cowork-harness/references/ci-recipe.md

@@ -1,6 +1,6 @@
 # CI recipe — replay vs live lanes
 
-Self-contained reference. Tracks `cowork-harness 2.2.0` (baseline `desktop-1.34493.1`).
+Self-contained reference. Tracks `cowork-harness 2.3.0` (baseline `desktop-1.37937.1`).
 
 **Fastest path: the packaged Action.** One step gets you `replay`/`lint`/`verify-cassettes` plus a PR
 job-summary reporter (verdict table, staleness findings, cost/turns when available):
@@ -17,7 +17,7 @@ job-summary reporter (verdict table, staleness findings, cost/turns when availab
 CLI major reaches your workflow the moment it is promoted even though your `uses:` ref never changed — so a
 copy-pasted recipe that omits the input takes a major bump with no say in it. `^2` holds the major, needs no
 patch number to remember, and only wants a human decision at the next major. Pin an exact version
-(e.g. `version: "2.2.0"`) instead when you want byte-reproducible CI.
+(e.g. `version: "2.3.0"`) instead when you want byte-reproducible CI.
 
 Reach for the manual multi-step form below only when you need per-step control the Action's inputs don't
 cover (a custom flag combination, a different runner matrix per step, or `lint`/`verify-cassettes` gated
@@ -36,7 +36,7 @@ jobs:
       - uses: actions/checkout@v4
       - name: Stage the agent binary (official channel, sha256-verified against the pinned baseline)
         run: |
-          V=2.1.237   # match your scenario's pinned baseline's agentVersion
+          V=2.1.246   # match your scenario's pinned baseline's agentVersion
           # The expected digest is baselines/desktop-<ver>.json -> agentBinary.sha256. Paste it here, or
           # read it with jq if you vendor the baseline. An unverified download is an unverified agent:
           # this step FAILS rather than staging one, which is the whole point of naming it "verified".
@@ -67,7 +67,7 @@ sha256-*checked* but not hard-blocking on mismatch — it's advisory for an inte
 GitHub-hosted runners, no token/Docker/agent:
 
 ```yaml
-- run: npm i -g "cowork-harness@^2.2.0"
+- run: npm i -g "cowork-harness@^2.3.0"
 - run: cowork-harness lint scenarios/*.yaml --strict --min-severity WARN
                                                     # no silent false-greens. WITHOUT --strict this
                                                     # step cannot fail on a WARN-class rule (e.g.
@@ -149,7 +149,7 @@ The split is not just about tokens — it decides **where each lane can run**:
   `max_cost_usd`, `max_tokens`, `tool_calls_max`, `result`, and the verdict modifiers
   `allow_permissive_auto_allow` / `allow_missing_capability` / `allow_l0_plugin_divergence` /
   `allow_stall` (no-op passes); plus the gate keys `question_asked` / `question_options` /
-  `questions_count_max` / `gate_answers_delivered` **if** the cassette has `controlOut`, and the manifest keys
+  `question_context` / `questions_count_max` / `gate_answers_delivered` **if** the cassette has `controlOut`, and the manifest keys
   (`file_exists` / `user_visible_artifact` / `artifact_json` / `artifact_text`) **if** it carries an artifact
   manifest. `file_absent` is in neither class — it is live/verify-run only.
   **That list is illustrative, not the authoritative set** — more keys are replay-checkable than fit a
@@ -237,12 +237,14 @@ dollar figures). In a skill repo these cassettes get **committed**. So:
   (`hostloop`, `protocol`) has an **empty** redaction policy — that combination commits real host paths
   the `path` scanner then hard-fails at `verify-cassettes` time. The always-on scanner remains the
   universal net (container-tier recordings can trip it too).
-- **Host-inheriting record refused by default — `--allow-host-inventory-fixture` is the consent.** A
-  `protocol`/`hostloop`/`cowork`-resolving-to-hostloop record into a repo-visible cassette path would
-  freeze THIS machine's MCP server names, agents, and account metadata into a committed fixture, so
-  `record` refuses **before the paid spawn**. Pass `--allow-host-inventory-fixture` only when the
-  recording session genuinely has no personal MCP servers or plugins to leak — it is a per-record
-  boolean consent, not a pattern.
+- **Host-inheriting record refused by default — `--allow-host-inventory-fixture` bypasses the
+  PRE-FLIGHT, not the scan.** A `protocol`/`hostloop`/`cowork`-resolving-to-hostloop record into a
+  repo-visible cassette path would freeze THIS machine's MCP server names, agents, and account metadata
+  into a committed fixture, so `record` refuses **before the paid spawn**. `--allow-host-inventory-fixture`
+  proceeds past that check — and nothing more: the finished recording is still scanned, and a real finding
+  still refuses the write and quarantines it. **You do not need to audit the session by hand to pass this
+  flag**; that precondition was never decidable by the operator, and the scan is the real gate. Writing a
+  recording the scan DID flag is the separate `--allow-host-inventory-findings`.
 
   Two details that matter for a re-record loop. The pre-spend check **warns rather than refuses when the
   cassette already exists**, deliberately: refusing there would fire on every `--rerecord-stale` pass and
@@ -340,7 +342,7 @@ jobs:
         with: { node-version: '24' }
       - uses: actions/setup-python@v5
         with: { python-version: '3.x' }                                       # python3 only — PyYAML is bundled with the linter
-      - run: npm i -g "cowork-harness@^2.2.0"
+      - run: npm i -g "cowork-harness@^2.3.0"
       - run: cowork-harness lint scenarios/*.yaml                              # no-silent-false-green (needs python3; PyYAML bundled)
       - run: cowork-harness verify-cassettes cassettes/ --output-format json   # privacy + staleness gate
       - run: cowork-harness replay cassettes/ --output-format json             # token-free content/structure
@@ -369,7 +371,7 @@ jobs:
             echo "live=true" >> "$GITHUB_OUTPUT"
           fi
       - if: steps.guard.outputs.live == 'true'
-        run: npm i -g "cowork-harness@^2.2.0"
+        run: npm i -g "cowork-harness@^2.3.0"
       - if: steps.guard.outputs.live == 'true'
         run: cowork-harness run scenarios/ --output-format json
         env:

package/.claude/skills/cowork-harness/references/critique.md

@@ -1,6 +1,6 @@
 # Critique — the facts a plugin install can't otherwise reach
 
-Tracks `cowork-harness 2.2.0` (baseline `desktop-1.34493.1`). This is **not** a trim of the full
+Tracks `cowork-harness 2.3.0` (baseline `desktop-1.37937.1`). This is **not** a trim of the full
 [`docs/critique.md`](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/critique.md) (repo-only —
 flags, cost, reproduction discipline, known limitations all live there). This file covers exactly what a
 plugin install cannot otherwise discover: the run-dir artifact a harvester actually reads, the report's

package/.claude/skills/cowork-harness/references/fidelity-and-answers.md

@@ -1,6 +1,6 @@
 # Fidelity tiers & answer paths
 
-Self-contained reference. Tracks `cowork-harness 2.2.0` (baseline `desktop-1.34493.1`).
+Self-contained reference. Tracks `cowork-harness 2.3.0` (baseline `desktop-1.37937.1`).
 
 ## Fidelity tiers (`fidelity:` in the scenario)
 

package/.claude/skills/cowork-harness/references/scenario-schema.md

@@ -1,7 +1,7 @@
 # Scenario & session schema, assertion catalog, web_fetch, full gotchas
 
-Self-contained reference for authoring `cowork-harness` scenarios. Tracks `cowork-harness 2.2.0`
-(baseline `desktop-1.34493.1`). If your checkout is newer, prefer the live [`docs/scenario.md`](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/scenario.md),
+Self-contained reference for authoring `cowork-harness` scenarios. Tracks `cowork-harness 2.3.0`
+(baseline `desktop-1.37937.1`). If your checkout is newer, prefer the live [`docs/scenario.md`](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/scenario.md),
 [`docs/session.md`](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/session.md), and `SPEC.md`.
 
 **Minimal scenario** — `prompt` is the only required field:
@@ -289,10 +289,10 @@ same set live from the schema.
 | Assertion | Passes when |
 |---|---|
 | `result: success \| error` | the run ended with that status |
-| `transcript_contains: <str>` | the assistant transcript includes the literal string |
-| `transcript_not_contains: <str>` | it does not |
-| `transcript_matches: <regex>` | the transcript matches (case-insensitive) — for stochastic prose |
-| `transcript_not_matches: <regex>` | it does not match (e.g. no leaked stack trace) |
+| `transcript_contains: <str>` | the assistant transcript includes the literal string **Sees top-level `assistant_text` only — it excludes every `tool_use`/`tool_result`**, so text emitted inside a tool call (a gate question, an option label or description) can never match; use `question_context`/`question_asked` or `tool_result_contains` for those. |
+| `transcript_not_contains: <str>` | it does not **Sees top-level `assistant_text` only — it excludes every `tool_use`/`tool_result`**, so text emitted inside a tool call (a gate question, an option label or description) can never match; use `question_context`/`question_asked` or `tool_result_contains` for those. |
+| `transcript_matches: <regex>` | the transcript matches (case-insensitive) — for stochastic prose **Sees top-level `assistant_text` only — it excludes every `tool_use`/`tool_result`**, so text emitted inside a tool call (a gate question, an option label or description) can never match; use `question_context`/`question_asked` or `tool_result_contains` for those. |
+| `transcript_not_matches: <regex>` | it does not match (e.g. no leaked stack trace) **Sees top-level `assistant_text` only — it excludes every `tool_use`/`tool_result`**, so text emitted inside a tool call (a gate question, an option label or description) can never match; use `question_context`/`question_asked` or `tool_result_contains` for those. |
 | `file_exists: <path>` | the path exists under the run's `work/` (anchored at `mnt/`, e.g. `outputs/x.md`). For a user-facing deliverable prefer `user_visible_artifact` — with a connected folder the file lands in `mnt/<folder>` (= `{{workspaceFolder}}`), not `mnt/outputs`, so `file_exists: outputs/x.md` misses it |
 | `user_visible_artifact: <path>` | exists **and** under a user-visible root (`outputs/` + each connected folder's mount name) — the right primitive for a workspace deliverable when a folder is connected |
 | `no_delete_in_outputs: true` | no delete op touched `mnt/outputs` — **only `true` is valid**; `false` is rejected (omit to allow deletes) |
@@ -344,8 +344,9 @@ same set live from the schema.
 | `task_status: {match, status}` | a task whose `subject` OR `id` matches the regex `match` reached `status` — evidence-unavailable if tasks telemetry is absent; also fails **malformed** when a TaskCreate result was unparseable (corrupt task telemetry), mirroring the guard `all_tasks_completed`/`task_count_min` already had |
 | `no_scratchpad_leak: true` | every file presented via `present_files` that was in the scratchpad was successfully promoted to `mnt/outputs` (none left behind) — vacuously passes if nothing was presented (pair with a presence check to require a delivery); content-class: both the `present_files` tool_use and its own tool_result live in the ordinary events stream, so `RunResult.presentedFiles` re-derives on replay at container, where the agent's cwd IS the session root the live lane measures from; at hostloop the live lane measures from the session root while a re-drive has only the recorded cwd (`mnt/outputs`, inside it), so the promoted/leaked booleans there are not equivalent — immaterial to this key, which evaluates at container only (meaningfully replay-checkable, same as `skill_triggered`); evidence-unavailable if `presentedFiles` telemetry is absent (an older run predating the feature). **Container-only on the merits**: hostloop serves `present_files` but never promotes (its handler passes a validated path through), so there is no scratch→outputs copy that could leak. On microvm/protocol a scratchpad-delivered file is neither promoted to `mnt/outputs` nor detected there (a skill that delivers via write-to-cwd→`present_files` will false-red `user_visible_artifact` on those tiers; use `container`, or write directly to `outputs/`). Hostloop is not one of them: the agent's cwd there already *is* the outputs dir, so a write-to-cwd delivery is under a user-visible root from the start and `user_visible_artifact` passes. **The tool name is lane-specific:** `present_files` is the desktop-local lane's tool (the one this harness emulates); remote Cowork delivers via the agent-native `SendUserFile` instead, so a skill should describe the delivery outcome rather than naming either tool — this key asserts the harness-side delivery record either way. **Only `true` is valid** |
 | `present_files_called: true` | at least one file was actually delivered via the `present_files` tool (`RunResult.presentFilesCalls > 0` — the count of invocations that carried a well-formed `file_path`). Presence is read at the **invocation**, deliberately not off the classified `presentedFiles` list: that list drops any path it cannot resolve, and a host-path redaction policy makes that certain at `hostloop`, where a real host path redacts to `[REDACTED:…]/mnt/outputs/f`. So this key is safe to assert in a scenario you intend to `record` with redaction active — `record` refuses a cassette whose verdict redaction changed, and an invocation count cannot be changed by it. A run that called the tool but whose every call carried an unusable path reports **cannot verify**, never a claim of non-delivery. The presence companion to `no_scratchpad_leak` (which passes vacuously when nothing was presented). Pair them to require a delivery **and** require it not to leak. Content-class (re-derives identically on replay). **`fidelity: container` or `hostloop`** — the harness serves `present_files` at both (hostloop via a handler mirroring production's own host-loop branch: validate the path, pass it through, no promotion). `protocol` and `microvm` report cannot-verify. See the `no_scratchpad_leak` row, which stays container-only for a different reason; and see the lane note there — the tool name differs on remote Cowork. **Only `true` is valid** |
-| `question_asked: <regex>` | the agent asked an AskUserQuestion whose **question text** matches (`question`, falling back to `header`). Text only — for the options it offered, use `question_options` |
-| `question_options: {when_question?, equals?, contains?, order?}` | the option SET and ORDER a gate offered — what the user was actually SHOWN. `when_question` selects the sub-question by the same label `question_asked` matches (omit only if exactly one fired; ambiguity FAILS). Exactly one of `equals` (complete set) / `contains` (subset); `order: exact` is the default because a re-ordered list is the defect this exists for. Captured at ask time, so a gate that was shown then denied/stalled still counts; unreadable evidence fails evidence-unavailable |
+| `question_asked: <regex>` | the agent asked an AskUserQuestion whose **question text** matches (`question`, falling back to `header`). Text only — for the options it offered, use `question_options` ⚠️ **Model-composed text, reworded run to run** — pin a producer-authored constant, not model prose. |
+| `question_options: {when_question?, equals?, contains?, order?}` | the option SET and ORDER a gate offered, **by label** — descriptions are not compared (see `question_context`). `when_question` selects the sub-question by the same label `question_asked` matches (omit only if exactly one fired; ambiguity FAILS). Exactly one of `equals` (complete set) / `contains` (subset); `order: exact` is the default because a re-ordered list is the defect this exists for. Captured at ask time, so a gate that was shown then denied/stalled still counts; unreadable evidence fails evidence-unavailable ⚠️ **Model-composed text, reworded run to run** — pin a producer-authored constant, not model prose. |
+| `question_context: {when_question?, matches}` | a regex over **everything the gate showed the user** — question label + every option label + every option **description**. Use it when the sentence you need to prove reached the founder may land in any of those fields: `question_asked` sees only the question text, `question_options` compares only labels, so a phrase delivered in an option's `description` is invisible to both. `when_question` narrows; omitting it searches every gate (NOT ambiguous here — this key asks whether the text was shown, not which gate offered which set). Ask-time payload only, never a `tool_result` (a producer that also writes the phrase to its own gate-state file would otherwise false-green it). Zero gates FAILS ⚠️ **Model-composed text, reworded run to run** — pin a producer-authored constant, not model prose. |
 | `questions_count_max: <N>` | at most N **sub-questions** asked — a bundled `AskUserQuestion` with K sub-questions counts as K, not 1; `trace --view questions`'s footer total uses the same definition |
 | `gate_answers_delivered: true` | every answered gate's answer reached the model (observed `tool_result`; unobserved = fail); **zero gates fired passes vacuously** — pair with `gate_answer_count_min: >= 1` to also require a gate, or drop this key and declare `questions_count_max: 0` in a scenario that expects none |
 | `gate_answers_delivered: false` | asserts at least one answered gate's answer was **confirmed not delivered** (an observed delivery failure); an unobserved/null delivery does **not** satisfy this — for negative-path delivery tests. Requires a gate, so **mutually exclusive** with `questions_count_max: 0` (refused by `run`/`skill`/`record`) |
@@ -369,8 +370,8 @@ same set live from the schema.
 | `max_peak_rss_bytes: <N>` | peak sampled RSS of the agent sandbox ≤ N bytes (`RunResult.resources.peakRssBytes`) — live-only: replay never spawns a sandbox to sample, so evidence-unavailable on replay/protocol (never a vacuous pass); also evidence-unavailable when sampling captured no RSS value |
 | `semantic_matches: {rubric: [...], min_pass?, judge_model?, include_subagent_text?}` | a pinned LLM judge grades each fixed `rubric` claim against the run's answer — the **union of the agent's final result text (`RunResult.finalMessage`), the transcript, and the final on-disk content of any files the agent authored during the run** — so a claim about content the skill led the agent to *write to a file* grades as reliably as one about inlined prose. **"The transcript" is narrower than it reads: top-level `assistant_text` ONLY.** It excludes every `tool_use`/`tool_result` and **all sub-agent-originated text** (including fork-scoped `Skill`/`Agent(fork)` dispatches — the harness attributes their *tool* calls to the main agent, but not their text). ⚠️ **Consequence: a rubric claim about whether a tool was called can NEVER grade true** — the evidence is not in the judged document. Such a claim looks reasonable and silently caps your pass rate; assert tool use with `tool_called` / `present_files_called` / `subagent_dispatched` / `hook_blocked` instead. Sub-agent text is captured in `RunResult.subagents[].reasoning` and reaches the judge only via opt-in `include_subagent_text: true` (`kind:"text"` turns only — sub-agent *thinking* arrives empty with `redacted:true`, so it would pad the document with blanks) (authored-file evidence is captured on every live sandbox tier including **microvm** — its session tree is snapshotted from the VM into the run dir). When the authored-file evidence backing the judged document is **incomplete** — a file dropped at the capture-size cap, unreadable at read-back, or (on `--resume`) the scratchpad walk skipped — the assert fails evidence-unavailable rather than trusting a judge grade over a partial document; this is separate from the malformed-grade `judgeInvalid` path below. The assert passes iff ≥ `min_pass` claims pass (default: all — avoid for a gating scenario). Results align by claim index and are recorded per-claim in `RunResult.assertions[].semanticClaims` (`[{index, claim, pass}]`, so a consumer can diff the per-claim profile across runs); a rep whose grade can't be parsed (after one retry) is marked `RunResult.assertions[].judgeInvalid` and **never silently dropped** — it is excluded from the pass denominator, and the guard against a misleading score from that exclusion is the gate's minimum-valid-rep floor (`MIN_VALID` ≥ 4) plus this visibility, not a claim that denominator-shrinking inflation is impossible. Within a rep, a grade that's still unparseable after the retry **fails that assert outright** (evidence-unavailable, not a vacuous pass) — a persistently-flaky judge reds the run rather than silently passing. `judge_model` pins the grader (default when neither it nor `COWORK_HARNESS_JUDGE_MODEL` is set: `claude-opus-4-8`; a dated id keeps a before/after comparison reproducible). Live-only: the judge is a live model call, so evidence-unavailable / skipped-loud on replay (never a vacuous pass) |
 | `artifact_json: {artifact, path, …}` | assert a JSON artifact's contents — `equals`/`gt`/`in`/`exists`/`absent`/`is_null` over a dotted `path` (`in` = membership in a list, for a stochastic/LLM value; `absent` ≠ `is_null`; an unresolved intermediate fails loud) |
-| `computer_links_resolve: true` | every `computer://` link in the model-visible transcript resolves to an artifact that exists in the run's collected outputs/mounts — a dangling link fails, naming which target was checked (a live host path, the collected work tree, or the replay manifest). **Requires ≥1 link** (zero links fails — use `computer_links_resolve_if_present` for the presence-free variant). **Only `true` is valid** (`false` is rejected by the schema) |
-| `computer_links_resolve_if_present: true` | like `computer_links_resolve` but passes vacuously when the transcript has zero `computer://` links — the presence-free variant. **Only `true` is valid** |
+| `computer_links_resolve: true` | every `computer://` link in the model-visible transcript resolves to an artifact that exists in the run's collected outputs/mounts — a dangling link fails, naming which target was checked (a live host path, the collected work tree, or the replay manifest). **Requires ≥1 link** (zero links fails — use `computer_links_resolve_if_present` for the presence-free variant). **Only `true` is valid** (`false` is rejected by the schema) **Sees top-level `assistant_text` only — it excludes every `tool_use`/`tool_result`**, so a `computer://` link that appeared only inside a tool call or its result is invisible to it. |
+| `computer_links_resolve_if_present: true` | like `computer_links_resolve` but passes vacuously when the transcript has zero `computer://` links — the presence-free variant. **Only `true` is valid** **Sees top-level `assistant_text` only — it excludes every `tool_use`/`tool_result`**, so a `computer://` link that appeared only inside a tool call or its result is invisible to it. |
 
 `expect_denied: [host, …]` adds one `egress_denied` per host. Run `cowork-harness assertions --list` for this
 table from the live schema. Example: `artifact_json: { artifact: outputs/cap.json, path: me.run_id, equals: "r1" }`.
@@ -441,7 +442,7 @@ sourcing ≠ evaluation (replay warns when you edit one). `verify-run` is the on
 modifiers `allow_permissive_auto_allow` / `allow_missing_capability` / `allow_l0_plugin_divergence` /
 `allow_stall` are also kept on replay, evaluated as no-op passes.
 
-**Gate keys — replay only with a `controlOut` cassette:** `question_asked`, `question_options`, `questions_count_max`,
+**Gate keys — replay only with a `controlOut` cassette:** `question_asked`, `question_options`, `question_context`, `questions_count_max`,
 `gate_answers_delivered`, `gate_answer_count_min`, `hook_blocked`, `no_hook_blocked`, `vm_path_denied`,
 `path_denied`, `no_path_denied` (the latter three are also `fidelity: hostloop`-only — see the assertion
 table). With `controlOut` present they evaluate; on an old
@@ -545,7 +546,8 @@ reference omits). Neither list is a strict superset of the other — reach for t
    `egress_denied` is dropped. Both now warn loudly. → put egress/live-only checks on a live gate; one
    concern per item; run the linter. (`LIVE_ONLY_KEYS`/`MANIFEST_KEYS` in `src/run/cassette.ts`.)
 
-2. **Gate keys need a `controlOut` cassette.** `question_asked`, `questions_count_max`,
+2. **Gate keys need a `controlOut` cassette.** `question_asked`, `question_options`, `question_context`,
+   `questions_count_max`,
    `gate_answers_delivered`, `gate_answer_count_min`, `hook_blocked`, `no_hook_blocked` only evaluate on
    replay with `controlOut`; on an old cassette they warn and are excluded (not passed).
    `gate_answers_delivered` **fails on

package/.claude/skills/cowork-harness/references/task-recipes.md

@@ -2,7 +2,7 @@
 
 Each recipe composes facts that live scattered across SKILL.md and the other references into one
 decision path. Every one answers a question a real fleet owner had to work out the hard way.
-Tracks `cowork-harness 2.2.0` (baseline `desktop-1.34493.1`), same as SKILL.md's front-matter. Recipe 2's `resolved-tier`/`unverifiable-tier` staleness classes and
+Tracks `cowork-harness 2.3.0` (baseline `desktop-1.37937.1`), same as SKILL.md's front-matter. Recipe 2's `resolved-tier`/`unverifiable-tier` staleness classes and
 Recipe 3's `init-redact` shipped in 0.24.0 and are part of the current feature set — no version gate
 needed if your CLI meets SKILL.md's version floor.
 
@@ -17,7 +17,7 @@ a paid live re-record? Walk this tree — the answer is usually no:
    `cowork-harness replay <cassette> --assert-from <scenario.yaml>`. Token-free, no re-record.
    If the recording genuinely lacks the telemetry a key needs (very old cassettes), the key fails
    **loud** as `evidence-unavailable` — that is correct behavior, not a bug; only then re-record.
-2. **Gate keys** (`question_asked`, `question_options`, `questions_count_max`, `gate_answers_delivered`) on a cassette
+2. **Gate keys** (`question_asked`, `question_options`, `question_context`, `questions_count_max`, `gate_answers_delivered`) on a cassette
    **with `controlOut`** (any modern recording) → same token-free `--assert-from` path.
 3. **Gate keys** on a **pre-`controlOut`** cassette → one re-record unlocks gate asserts for that
    cassette permanently.

package/.claude/skills/cowork-harness/scripts/assertion-keys.json

@@ -43,6 +43,7 @@
     "path_denied",
     "present_files_called",
     "question_asked",
+    "question_context",
     "question_options",
     "questions_count_max",
     "replay_protocol_fidelity",

package/.claude/skills/cowork-harness/scripts/scenario.py

@@ -114,6 +114,7 @@ CONTENT_KEYS = {
 GATE_KEYS = {
     "question_asked",
     "question_options",
+    "question_context",
     "questions_count_max",
     "gate_answers_delivered",
     "gate_answer_count_min",
@@ -284,6 +285,7 @@ def _load_top_level_keys():
 # every valid top-level scenario key (generated from the zod ScenarioObject schema; see _load_top_level_keys)
 TOP_LEVEL_KEYS = _load_top_level_keys()
 REGEX_KEYS = {
+    "matches",
     "transcript_matches",
     "transcript_not_matches",
     "when_question",
@@ -754,7 +756,11 @@ def lint_doc(doc, path, raw_lines):
     # YAML 1.1 but are rejected by the loader as strings — see _numeric for the same dialect gap.)
     delivered_values = _assert_values(items, "gate_answers_delivered")
     if any(v is not False for v in delivered_values):
-        has_companion = "question_asked" in assert_keys or "question_options" in assert_keys or any(
+        has_companion = (
+            "question_asked" in assert_keys
+            or "question_options" in assert_keys
+            or "question_context" in assert_keys
+        ) or any(
             (n := _numeric(v)) is not None and n >= 1 for v in _assert_values(items, "gate_answer_count_min")
         )
         if not has_companion:
@@ -837,6 +843,7 @@ def lint_doc(doc, path, raw_lines):
                 ),
                 ("question_asked", "question_asked" in assert_keys),
                 ("question_options", "question_options" in assert_keys),
+                ("question_context", "question_context" in assert_keys),
                 ("gate_answers_delivered: false", any(v is False for v in _assert_values(items, "gate_answers_delivered"))),
             ],
             "a delivered gate records at least one question, so requiring a gate to be present contradicts requiring zero questions",

package/CHANGELOG.md

@@ -4,6 +4,242 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). The project uses
 [Semantic Versioning](https://semver.org/); as of 1.0.0, a backwards-incompatible change to a covered surface ([SPEC.md §12](./SPEC.md#12-versioning--the-10-compatibility-contract)) requires a major bump.
 
+## [Unreleased]
+
+## [2.3.0] — 2026-08-26
+
+### Parity
+
+- **Baseline `desktop-1.37937.1` (agent `2.1.246`).** `sync` had been refusing to write on three
+  `spawn.env` deltas; all three are now classified.
+
+  **Two new pinned keys.** The Cowork spawn sets `CLAUDE_CODE_PROMPT_CACHE_TTL="1h"` and
+  `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL="5m"` unconditionally — no gate, no session or deployment
+  branch — so every first-party session receives them. They are **additive**:
+  `ENABLE_PROMPT_CACHING_1H="1"` is still set alongside. They read zero times in agent `2.1.241` and six
+  times each in `2.1.246`, so the contract went live one agent release after Desktop began setting it.
+
+  **`MCP_TOOL_TIMEOUT` is now classified per SITE, not per key.** Its first-party construction is
+  unchanged (still resolving to `180000`), but the third-party-only branch gained a second, settings-
+  conditional construction of the same key whose value expression the const resolver cannot reach.
+  Allowlisting the key — the obvious fix — would have been a silent contract loss: the allowlist is
+  checked *before* the pin list, so the key would have vanished from the generated env entirely, and it
+  is not a `REQUIRED_SPAWN_KEYS` member, so nothing would have hard-failed. Instead the 3p-only branch is
+  located by content and its inner keys are classified by name without resolving their values, which is
+  what the branch already meant. A brand-new key there still hard-fails.
+
+  **`CLAUDE_PREVIEW_CLASSIFIER_FLOOR` is now inert on the shipping agent** — recorded, not changed. Agent
+  `2.1.246` renamed the flag it reads to `CLAUDE_CHROME_CLASSIFIER_FLOOR` (and its consumer field
+  `previewClassifierFloorEnabled` → `chromeClassifierFloorEnabled`) while Desktop still sets only the old
+  name, so the classifier floor now falls through to its GrowthBook default. The key stays pinned: the
+  baseline records what the spawn constructs, and a Desktop-side rename must surface as a diff line
+  rather than as silence. Nothing in the harness reads it behaviourally. Together with the cache-TTL keys
+  above this is the same lesson pointing both ways — Desktop and the agent version the spawn env
+  independently, so "Desktop sets X" and "the agent reads X" are separately-dated claims.
+
+  Also found in the same pass and recorded in [docs/fidelity-gaps.md](./docs/fidelity-gaps.md), with no
+  harness surface: the deliberately-unmodeled remote device-tool family gained `device_fs` and
+  `device_request_delete_permission` plus a folder-access announce mode — the Desktop half of the six
+  `cowork_*` risk categories that had appeared in agent `2.1.237`'s auto-mode rubric.
+
+  Also verified unchanged against the retained previous asar: the Cowork system prompt (the retained raw
+  files for 1.32885.1 through 1.37937.1 are byte-identical on disk), both sub-agent appends, `tools[]`,
+  the `canUseTool` chain, the mount modes, the egress contract, and the VM rootfs image.
+
+- **All three committed example cassettes re-recorded against this baseline** — `example-pdf-skill`
+  (`container`), `example-multiselect-gate` (`protocol`) and `hostloop-computer-links` (`hostloop`).
+  The container one shows no behavioural change (transcript wording only). `verify-cassettes` is clean,
+  and the recorded MCP inventory is the Cowork lane's own servers (`cowork`, `plugins`, `skills`,
+  `workspace`) — no host inventory reached the fixtures, checked independently of the built-in scan
+  because the 2026-08-04 leak hid from a `mcp__` grep and surfaced only through NAME fields.
+
+- **Live end-to-end pass re-run against this baseline.** `npm run test:live` — **4 suites, 19 assertions,
+  19 green, 0 skipped** — across `protocol`, `container` and `hostloop`, on agent `2.1.246`. Every
+  `describe` in that lane is `skipIf`-gated on Docker, the staged-binary version and the token, so a gated
+  case reports as skipped rather than passing vacuously; zero skips means the whole population executed.
+  `DESIGN.md`'s scope note is re-stamped accordingly and now records that no baseline is unverified for
+  want of a live run. Not claimed: the `boundary-check` sandbox proof and the example-scenario suite were
+  part of the previous stamp and were not run here.
+
+### Added
+
+- **`question_context: {when_question?, matches}` — assert what a gate actually put in front of the user.**
+  A regex tested against a gate's founder-visible payload FIELD BY FIELD — the question label, every option
+  **label**, and every option **description**, each as a separate string. Matching per field rather than over
+  one joined blob is deliberate and load-bearing: a pattern cannot straddle two fields, so
+  `invoicing[\s\S]*Audit logging` will not match by stitching one option's description to the next option's
+  label — a "sentence" nobody was shown. The neighbouring transcript keys' docs teach `[\s\S]` for spanning
+  turns, so that is the habit an author brings here. `matches` is required NON-EMPTY: an empty pattern
+  compiles to `//i` and would green any run that fired a gate at all. `question_asked` matches question text only and `question_options`
+  compares labels only, so a sentence the model delivered inside an option's `description` was invisible to
+  every assertion key — a false-negative generator for any skill that puts context there, which the tool's
+  own schema invites. Measured on a consumer's paid run: a producer-authored sentence arrived verbatim in
+  the question, reworded inside it, and relocated into the proceed option's `description` across three runs
+  of one scenario; the third redded a lane on a run where the founder had in fact been told.
+
+  Evidence is the **ask-time** `AskUserQuestion` payload, never a `tool_result` — a skill's producer
+  typically also writes the same sentence into its own gate-state file, so `tool_result_matches` on that
+  phrase grades true whether or not the model ever surfaced it. Unlike `question_options`, omitting
+  `when_question` on a multi-gate run is **not** ambiguous: this key asks whether the text was shown at all.
+  Zero gates recorded fails; unreadable gate evidence fails evidence-unavailable, never vacuously.
+
+### Changed
+
+- **`trace --view questions` now renders each gate's offered options — labels AND `description`s** — under
+  an `offered:` block, sub-question-labelled on a bundled gate. It previously printed the question label
+  alone, so the option `description` a skill routinely puts the deciding sentence in was reachable only by
+  hand-reading `events.jsonl`; a reader who found nothing in the view could reasonably conclude the text was
+  never delivered. The payload was always recorded — this was purely a rendering gap, and the same run dir
+  answers the question either way. The row (`--output-format json`) gains `subQuestions[]` carrying the
+  untruncated ask-time options; the text view caps each description at 240 chars, so nothing is lost, only
+  wrapped. This pairs with `question_context`: the view is how you *find* the text, that key is how you
+  *gate* on it.
+
+- **The `tool_use` blindness of `transcript_contains`/`_not_contains`/`_matches`/`_not_matches` and
+  `computer_links_resolve`/`_if_present` is now documented and guarded.** `semantic_matches` has carried a
+  ⚠️ spelling out that its corpus excludes every `tool_use` — "a rubric claim about whether a tool was
+  called is unassertable" — while the six keys with the identical blindness said only "the assistant
+  transcript". A consumer wrote a `transcript_matches` against text living in a gate question; it could not
+  have matched at any phrasing, and the recording fail-closed after the spend. The caveat is now a property
+  of an enumerable set (`TOOL_USE_BLIND_KEYS`) enforced across every surface that documents a key — the
+  docs tables, the zod `.describe()` behind `assertions --list` and the generated JSON schema, and the
+  packaged skill reference — so a newly-added blind key cannot ship without it.
+- **`question_asked`/`question_options`/`question_context` now warn that they match model-authored text.**
+  Gate question text and option labels are composed by the model and reworded run to run. The `choose:`
+  side already documented this (stable leading anchor, 1-based index); the assert side documented it
+  nowhere. Guarded by `MODEL_AUTHORED_TEXT_KEYS`.
+- **A bad regex in a NESTED assertion field is now caught at load, not after the paid spawn.** The pre-compile
+  pass reached only top-level string keys, so every regex one level down — `artifact_text.matches`,
+  `artifact_text.not_matches`, `path_denied.path_matches`, `skill_tool_used.skill`/`.tool`,
+  `subagent_dispatch_healthy.type`, `subagent_output_contains.match`, `task_status.match`,
+  `question_options.when_question`, and the new `question_context.*` — was first compiled inside the
+  evaluator. All eleven are now validated at load, and `test/nested-regex-leaves.test.ts` reads `assert.ts`
+  and fails if the evaluator compiles a nested leaf the load-time table does not carry, so the gap cannot
+  reopen silently. `lint`'s double-quoted-regex warning also now covers nested `matches:` leaves.
+- **`diff` with a single positional now names the missing operand** instead of printing bare usage. There is
+  deliberately no one-argument form: `diff` is polymorphic over baselines, run dirs and cassettes, so it
+  would need type dispatch plus a defined source for "the committed version".
+- **The two cost keys are cross-referenced.** `RunResult.cost.usd` is one invocation's SDK
+  `total_cost_usd`; the critique report's `costUsd.totalUsd` aggregates the task turn, the reflection turn
+  and both evaluator passes. Reading the wrong one returns `undefined` rather than erroring, which reads as
+  "no cost recorded". Kept as two shapes on purpose — collapsing them would destroy the per-phase split.
+
+### Fixed
+- **Two spawn-contract sentinels were weaker than their names implied; both now bite.**
+
+  `checkSpawnContractFacts` pinned the `allowedTools[]` built-in head and the built-in→`mcp__` boundary
+  but nothing between the boundary and the closing bracket — so `mcp__plugins__search_connectors` was
+  added to the array and both checks stayed green. The `mcp__` membership is now pinned as a set, and the
+  flag names the added and removed entries instead of reporting that something "moved". (That tool is
+  declared only on the third-party deployment, so the first-party inventory the harness serves is
+  unaffected — but the addition should not have been invisible.)
+
+  `checkMountModeFacts` asserted each read-only mount with a single `regex.test`, while `uploads`,
+  `.claude/skills` and `.projects/<uuid>` are each built at **two** sites — the VM-loop mount-set builder
+  and host-loop `computeBashMounts`. Either site satisfied the check, so a one-lane `ro`→`rw` flip — a
+  containment change on exactly one execution tier — passed green. It now compares the site count to the
+  count carrying `mode:"ro"` and names the lane count in the flag. Its fifth fact — the delete-deny
+  resolver `?"rwd":"rw"` — had the same shape and the same two-lane reality (it went 1 site to 2 in this
+  release) and now guards a floor on that count: a lane losing the resolver flags, a lane gaining one
+  does not.
+
+- **All eight asar sentinels now carry a committed mutation case.** They are green on the previous
+  release's asar too, so a green proves nothing on its own unless the checker is known to bite; five of
+  them (`checkCodeTripwires`, `checkWebFetchFacts`, `checkEgressContractFacts`, `checkSyspromptMapFacts`,
+  `checkNormalizationSanity`) had no such case. Each new one changes an **inner** character of its
+  anchor, because a suffix rename still satisfies a substring regex — a mutation that cannot fail is not
+  evidence — and asserts that the mutation actually applied.
+
+- **`record --dry-run <dir/>` no longer announces a WARN as a refusal.** The batch arm labelled every
+  advisory note `⚠ would-refuse (advisory)`, but `cassettePortabilityPreflight` can only ever return
+  `ok`/`warn` — it has no refuse path at all — and `hostInventoryPreflight` returns `warn` whenever the
+  target cassette already exists, which is every re-record corpus sitting at the default path. So the
+  preview told operators the real `record` would refuse runs it would in fact accept, on the one arm whose
+  design principle is that a guess must not gate. The label now follows the verdict kind
+  (`⚠ would-warn (advisory)`), the "ADVISORY, not this run's verdict" footer is unchanged, and exit codes
+  were never affected either way.
+
+- **The 3p-branch rule refuses to blank W1.** W1 is the window every modeled first-party key is derived
+  from, so a branch marker appearing there hard-fails instead of blanking; deleting real pinned keys from
+  the derived env with nothing failing is the worse of the two outcomes.
+
+- **`record --dry-run` now runs every pre-spend refusal the real record runs, and one refusal moved from
+  after the paid run to before it.** The rehearsal re-implemented the checks by hand, so it drifted:
+  `hostInventoryPreflight` shipped 2026-08-04 and the commit three days later titled *"make `--dry-run`
+  refuse what the real record refuses"* swept in the two checks returning `string | undefined` and missed
+  the one returning a `{kind}` verdict — for 19 days an operator could not discover that refusal without
+  spending. Separately, the slug-collision refusal (*"refusing to overwrite … it belongs to scenario X"*)
+  sat **after** `executeScenario`: you paid for the run and were then refused, though it is a pure function
+  of path + `--force` + the existing cassette's name. Both now run in one shared pre-spend block.
+
+  Refusals are also uniform now. `promptPolicyRejection` threw while `hostInventoryPreflight` called
+  `fail()`, which `process.exit`s — and the dir-batch loop catches a throw per item but cannot catch an
+  exit, so a host-inventory refusal mid-batch abandoned concurrent runs already paid for.
+
+  Under `--output-format json` a directory batch carries those advisory verdicts in a `notes[]` array, kept
+  separate from `refusals[]` so automation cannot read a guess as a binding verdict.
+
+  **On a directory, the path-dependent verdicts are ADVISORY (`⚠ would-refuse`) and do not affect the exit
+  code**, because a directory target takes no `--out`: the preview would have to guess the destination, and
+  a guess must not gate. Measured on a real consumer, gating on that guess would have refused 26 of 27
+  scenarios the real record accepts. Dry-run a single scenario file with the real flags for a binding
+  answer. `--quiet` suppresses the notes; it never suppresses a refusal.
+
+  Also new in the batch preview: the duplicate-cassette-path refusal the real batch already had.
+
+### Upgrade impact
+
+- **`--allow-host-inventory-fixture` no longer waives a MEASURED host-inventory finding.** It was one flag
+  doing two jobs: bypassing the pre-flight refusal (a precondition the operator cannot check — "use only
+  when the session has no personal MCP servers or plugins") *and* downgrading the write-time scan's refusal
+  to a warning. So an operator who passed it to get past the undecidable precondition also switched off the
+  scan that would have caught a real leak. It is now the pre-flight bypass only; the finished recording is
+  still scanned, and a finding still refuses the write and quarantines the recording. Writing a flagged
+  recording needs the new, narrower `--allow-host-inventory-findings`. **A batch recorder that passes the
+  old flag on a new-fixture path will now abort on a genuine finding where it previously warned and wrote.**
+
+  A `--dry-run` that reports what *would* be captured was considered and declined: the inventory does not
+  exist until the agent has run, so a preview would either re-implement the scanner against a hypothetical
+  (a second oracle free to disagree with the real one) or require the spend it was meant to avoid. Reasoning
+  is in [docs/cassette.md](./docs/cassette.md).
+
+  This does not break a covered surface ([SPEC.md §12](./SPEC.md#12-versioning--the-10-compatibility-contract)):
+  no command or flag is removed and no exit-code meaning changes — one flag's consent narrows, and the
+  capability it shed is reachable through the new one. So it ships in a minor.
+
+### Documentation
+
+Five gaps found by asking a consumer which harness properties actually changed an outcome on a real
+working day, then checking whether the docs said so. Four of the five were documented only as features,
+never as the failure they prevent — the sentence a reader needs to recognise their own situation.
+
+- **The blocking gate is now stated as a blocker.** `AskUserQuestion` *blocks*: it is a question to a
+  human and `claude -p` has no human, so a gated skill under a plain CLI run stalls or never reaches the
+  code behind the gate. That made half the skill untestable, not merely awkward to test — the README had
+  only "untestable headless unless something answers it", buried as the last of two afterthought bullets.
+- **"Assert on the run, not the output"** — a new README section naming the class of claim the harness
+  exists for (`subagent_tool_absent`, `dispatch_count_max`, `no_delete_in_outputs`, `subagent_file_write`)
+  and why no output diff can reach it: a correct run and one that quietly handed a restricted sub-agent
+  shell access produce byte-identical files. `subagent_tool_absent` did not appear in the README at all.
+- **The raw-`events.jsonl` escape hatch is documented**, with verified `jq` recipes, in
+  [docs/debugging.md](./docs/debugging.md). Every documented route into the event log went through
+  `trace`, whose views are a digest — so the run dir's *evidence* surface is wider than any view's
+  *observation* surface, and wider still than the assertion catalog. Concluding "it never happened" from
+  a view that doesn't render the field is a false negative, and the doc now says so and shows the read.
+- **Sub-agent delivery has a route.** The tier-qualified outputs contract — the reason a hand-off path
+  that works on one loop lands in sandbox scratch on the other — was correctly documented in
+  [docs/subagents.md](./docs/subagents.md) but filed under "read on demand", reachable only by someone
+  who already knew the answer. It now has a "Common tasks" row keyed to the symptom.
+- **Replay's cost claim carries a number.** "Zero spend" is the price; the wall-clock is what makes an
+  always-on per-PR gate obviously affordable, and no doc stated it (well under a second per cassette).
+
+- **The project's provenance is stated on every surface the framing travels to.** `README.md` (which
+  renders on the npm page), `llms.txt`, both `.claude-plugin/marketplace.json` descriptions and `SKILL.md`
+  now say the same thing: an independent project, not affiliated with, endorsed by, or supported by
+  Anthropic; it bundles no Anthropic code; it is not Cowork. `SKILL.md` additionally tells the agent to say
+  so when a user asks what it is. Nothing enforces the four staying in step, so an edit can still drop it
+  from one of them unnoticed.
+
 ## [2.2.0] — 2026-08-25
 
 ### Upgrade impact