cowork-harness 0.24.0 → 0.25.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. 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: 0.24.0
-  tracks-harness: cowork-harness 0.24.0 (baseline desktop-1.18286.0)
+  version: 0.25.0
+  tracks-harness: cowork-harness 0.25.0 (baseline desktop-1.18286.0)
 ---
 
 # cowork-harness
@@ -22,7 +22,7 @@ flagged with a loud `::warning::`, not silent — auto-answer a gate, observe an
 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 0.24.0` (baseline
+> **Version note:** the facts and `file:line` pointers here track `cowork-harness 0.25.0` (baseline
 > `desktop-1.18286.0`). If your checkout is newer, prefer the live `--help`, `SPEC.md`, and
 > `docs/*.md` over this snapshot, and re-run the bundled linter.
 
@@ -38,7 +38,7 @@ cowork-harness skill ./my-skill "do X"      # run the skill once against the sta
 Before the first command, confirm the CLI is reachable and **fail loud** (never fake a pass) when a tier's dependencies are missing:
 
 - **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).
-- **CLI on PATH, recent enough?** Run `cowork-harness --version` — this skill needs **≥ 0.24.0**. If it's missing or older, prefix every command with the version floor `npx "cowork-harness@>=0.24.0" <cmd>` (Node ≥ 20), or install once with `npm i -g "cowork-harness@>=0.24.0"`. **Pin `@>=0.24.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. (≥ 0.24.0 is what gates the commands/assertions this skill teaches: `assertions --list`, `scaffold <run-id>`, `trace --view dispatches`, `artifact_json` incl. the `in:` operator, `verify-cassettes`, batch `record <dir>`/`--rerecord-stale`, `record --concurrency <N>`, record-time redaction, multiSelect/`answer:`, `verify-run` answer-coverage, `record --max-artifact-bytes`, live record-time deciders, `verify-cassettes --allow-domain`/`--allow-email`/`--allow-path`/`--allow-file` (`path` — local absolute filesystem paths — is the scanner's 4th class, new in 0.21.0), scenario `skills:` staleness scoping with `COWORK_HARNESS_AGENT_SCOPE=skill`, `chat --plugin`, `/help` in the REPL, `hostloop`'s native host/VM process split with its `allow_host_writes:` consent field, and `computer_links_resolve` (new in 0.22.0).)
+- **CLI on PATH, recent enough?** Run `cowork-harness --version` — this skill needs **≥ 0.25.0**. If it's missing or older, prefix every command with the version floor `npx "cowork-harness@>=0.25.0" <cmd>` (Node ≥ 20), or install once with `npm i -g "cowork-harness@>=0.25.0"`. **Pin `@>=0.25.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. (≥ 0.25.0 is what gates the commands/assertions this skill teaches: `assertions --list`, `scaffold <run-id>`, `trace --view dispatches`, `artifact_json` incl. the `in:` operator, `verify-cassettes`, batch `record <dir>`/`--rerecord-stale`, `record --concurrency <N>`, record-time redaction, multiSelect/`answer:`, `verify-run` answer-coverage, `record --max-artifact-bytes`, live record-time deciders, `verify-cassettes --allow-domain`/`--allow-email`/`--allow-path`/`--allow-patterns-file` (`path` — local absolute filesystem paths — is the scanner's 4th class, new in 0.21.0; `--allow-patterns-file <path>` is a FILE of patterns, one regex per line — not a path to allow, unlike `--allow <regex>`), scenario `skills:` staleness scoping with `COWORK_HARNESS_AGENT_SCOPE=skill`, `chat --plugin`, `/help` in the REPL, `hostloop`'s native host/VM process split with its `allow_host_writes:` consent field, and `computer_links_resolve` (new in 0.22.0).)
 - **Agent binary (sandboxed live tiers — `container`/`microvm`/`hostloop`/`cowork`).** The staged Claude Code agent is **bind-mounted** from a local Claude Desktop install, or point `COWORK_AGENT_BINARY` at a `claude-code-vm/<ver>/claude` ELF. Nothing is bundled. `protocol` (L0) and `replay` need no staged agent; for the sandboxed tiers, no agent → no run; report that, don't skip silently.
 - **Docker / Lima.** Only `--fidelity protocol` (L0) runs without them. `container` / `microvm` / `hostloop` / `cowork` need Docker (Lima for L2). If they're absent, drop to `--fidelity protocol` and **say so** — a green that never exercised the sandbox is not a sandbox pass.
 - **Auth.** `CLAUDE_CODE_OAUTH_TOKEN` (preferred) or `ANTHROPIC_API_KEY`, via env or `.env`. Minting an OAuth token needs the **`claude` CLI** (`npm i -g @anthropic-ai/claude-code`, then `claude setup-token`).
@@ -458,6 +458,27 @@ are the ones that bite hardest.
     and re-assert is undetected — the notice flags this; re-record if the session changed. `verify-run` reads
     on-disk `assert:` against a kept *run dir*; `replay --assert-from` is the equivalent for a *cassette*.
 
+18. **`questions_count_max` counts sub-questions, not gates.** One `AskUserQuestion` tool call can
+    bundle several sub-questions into a single gate; the assertion counts each sub-question, so a
+    3-sub-question bundle counts as 3, not 1. `trace --view questions` shows the same per-gate
+    sub-question count and a matching footer total — read that off instead of the tool-call count when
+    sizing the budget.
+
+19. **`gate_answers_delivered` passes vacuously when no gate fires — use `gate_answer_count_min: 1` to
+    also require a gate.** Whether a gate fires is model-dependent, so `gate_answers_delivered: true`
+    alone can't catch "the gate never fired at all"; pair it with `gate_answer_count_min` when
+    presence matters, not just delivery.
+
+20. **A `mode: r` connected folder's contents are recorded body-less, not excluded.** `record` captures a
+    read-only folder's files as path + hash only (`truncated: true`, no `body`) — it's an input the agent
+    read, not a deliverable it wrote. `file_exists`/`computer_links_resolve` still pass against it on replay
+    (the hash-only entry still materializes a placeholder); `artifact_json` reports a clear
+    evidence-unavailable on every lane (live/verify-run/replay agree — no green-record/red-replay). This is
+    also why a `mode: r` input never trips the `binary` privacy finding or needs `--allow` — only a
+    *committed* body is scanned. `scaffold` won't emit `file_exists` for one either (it's not in
+    `RunResult.artifacts`). A `mode: rw`/`rwd` folder's contents are captured with a full body, same as
+    `outputs/`.
+
 For the complete gotcha list, the assertion catalog, the YAML schema, the fidelity/answer tables,
 and the CI recipe, read the files in `references/`.
 

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 0.24.0` (baseline `desktop-1.18286.0`).
+Self-contained reference. Tracks `cowork-harness 0.25.0` (baseline `desktop-1.18286.0`).
 
 **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):
@@ -53,7 +53,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@>=0.24.0"
+- run: npm i -g "cowork-harness@>=0.25.0"
 - run: cowork-harness lint scenarios/*.yaml          # no silent false-greens
 - run: cowork-harness verify-cassettes cassettes/    # privacy + staleness
 - run: cowork-harness replay cassettes/              # token-free content/structure
@@ -187,7 +187,7 @@ jobs:
         with: { node-version: '20' }
       - uses: actions/setup-python@v5
         with: { python-version: '3.x' }                                       # python3 only — PyYAML is bundled with the linter
-      - run: npm i -g "cowork-harness@>=0.24.0"
+      - run: npm i -g "cowork-harness@>=0.25.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
@@ -216,7 +216,7 @@ jobs:
             echo "live=true" >> "$GITHUB_OUTPUT"
           fi
       - if: steps.guard.outputs.live == 'true'
-        run: npm i -g "cowork-harness@>=0.24.0"
+        run: npm i -g "cowork-harness@>=0.25.0"
       - if: steps.guard.outputs.live == 'true'
         run: cowork-harness run scenarios/ --output-format json
         env:

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

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

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

@@ -1,6 +1,6 @@
 # Scenario & session schema, assertion catalog, web_fetch, full gotchas
 
-Self-contained reference for authoring `cowork-harness` scenarios. Tracks `cowork-harness 0.24.0`
+Self-contained reference for authoring `cowork-harness` scenarios. Tracks `cowork-harness 0.25.0`
 (baseline `desktop-1.18286.0`). If your checkout is newer, prefer the live `docs/scenario.md`,
 `docs/session.md`, and `SPEC.md`.
 
@@ -237,9 +237,10 @@ passes only if every key passes. Keep one concern per item unless you mean conju
 | `tool_calls_max: <N>` | total top-level tool calls (sum of `toolCounts`) ≤ N — meaningfully replay-checkable (re-drive recomputes `toolCounts` deterministically) |
 | `max_turns: <N>` | the SDK-reported (or fallback-counted) turn count ≤ N — meaningfully replay-checkable (re-drive recounts turns deterministically, same as `tool_calls_max`) |
 | `question_asked: <regex>` | the agent asked an AskUserQuestion whose text matches |
-| `questions_count_max: <N>` | the agent asked at most N questions |
-| `gate_answers_delivered: true` | every answered gate's answer reached the model (observed `tool_result`; unobserved = fail) |
+| `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` to also require a gate |
 | `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 |
+| `gate_answer_count_min: <N>` | at least N AskUserQuestion gates fired AND were delivered non-error — presence companion to `gate_answers_delivered`'s vacuous-pass |
 | `allow_permissive_auto_allow: true` | verdict modifier — suppresses the default-fail when the run recorded a cowork-parity permissive auto-allow; for tests that deliberately assert Cowork's permissive behavior |
 | `allow_missing_capability: true` | verdict modifier — suppresses the default-fail when the (partial "core") agent image omits a capability the skill used but real Cowork ships (OCR/LibreOffice/markitdown/opencv/PDF-tables). Assert only when the skill's fallback is genuinely equivalent; otherwise rebuild full parity (`--build-arg COWORK_FULL_PARITY=1`). Also opts out of the `requires_capabilities` declared-need check. Live tiers only |
 | `allow_l0_plugin_divergence: true` | verdict modifier — opt into L0/protocol plugin divergence: suppresses the default-fail when a plugin behaves differently at `protocol` (L0) fidelity than under a sandboxed tier. Live tiers only |
@@ -293,8 +294,10 @@ modifiers `allow_permissive_auto_allow` / `allow_missing_capability` / `allow_l0
 `allow_stall` are also kept on replay, evaluated as no-op passes.
 
 **Gate keys — replay only with a `controlOut` cassette:** `question_asked`, `questions_count_max`,
-`gate_answers_delivered`. With `controlOut` present they evaluate; on an old cassette without it, a
-**loud warning** fires and they are **excluded** (not vacuously passed). Re-record to enable them.
+`gate_answers_delivered`, `gate_answer_count_min`. With `controlOut` present they evaluate; on an old
+cassette without it, a **loud warning** fires and they are **excluded** (not vacuously passed). Re-record to enable them.
+`questions_count_max` counts sub-questions, not gates/tool-calls — see the catalog row above and
+`trace --view questions`.
 
 **Filesystem — replay-checkable WITH an artifact manifest:** `file_exists`, `user_visible_artifact`,
 `artifact_json`, `computer_links_resolve` run on replay when the cassette carries an `artifacts` snapshot
@@ -374,10 +377,12 @@ at the top of this file.
    concern per item; run the linter. (`contentKeys` in `src/run/cassette.ts`.)
 
 2. **Gate keys need a `controlOut` cassette.** `question_asked`, `questions_count_max`,
-   `gate_answers_delivered` only evaluate on replay with `controlOut`; on an old cassette they warn
-   and are excluded (not passed). `gate_answers_delivered` **fails on unobserved delivery**
-   (`delivered: null`) — absence of evidence is failure. A **header-only gate** (empty `question`,
-   only `header`) can never be keyed and is rejected loudly — every gate needs a non-empty `question`.
+   `gate_answers_delivered`, `gate_answer_count_min` only evaluate on replay with `controlOut`; on an
+   old cassette they warn and are excluded (not passed). `gate_answers_delivered` **fails on
+   unobserved delivery** (`delivered: null`) — absence of evidence is failure — but **passes
+   vacuously when zero gates fired**; use `gate_answer_count_min: 1` to also require a gate to have
+   fired. A **header-only gate** (empty `question`, only `header`) can never be keyed and is rejected
+   loudly — every gate needs a non-empty `question`.
    (`contentKeys` in `src/run/cassette.ts`; `src/assert.ts`.)
 
 3. **The LLM-decider's two spellings.** Scripted answers + `on_unanswered: fail` is deterministic;
@@ -455,3 +460,14 @@ at the top of this file.
     Consequence: artifact assertions (`artifact_json`) over fields that were redacted will fail at replay
     — the harness emits `::warning::` at record time when this occurs. (`src/secrets.ts:scrubField`;
     `src/run/cassette.ts`.)
+
+21. **A `mode: r` connected folder's contents are recorded body-less, not excluded.** `record` captures a
+    read-only folder's files as `path` + `bytes` + `sha256` only (`truncated: true`, no `body`) — it's an
+    input the agent read, not a deliverable it wrote. `file_exists`/`computer_links_resolve` still pass
+    against it on replay (the hash-only entry still materializes a 0-byte placeholder); `artifact_json`
+    reports a clear evidence-unavailable on every lane (live/verify-run/replay agree). This is also why a
+    `mode: r` input never trips the `binary` privacy finding
+    or needs `--allow` in `verify-cassettes` — only a *committed* body is scanned. `scaffold` won't emit
+    `file_exists` for one either, since it isn't in `RunResult.artifacts`. A `mode: rw`/`rwd` folder's
+    contents are captured with a full body, same as `outputs/`. (`src/run/cassette.ts:buildManifest`'s
+    `bodyLessPrefixes`; `src/session.ts:readonlyFolderRootsFromPlan`.)

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

@@ -59,6 +59,7 @@ Top-level fields of a `*.cassette.json` (schema `schema/cassette.v7.json`):
 | `artifacts` | Output-file manifest (paths + hashes + small inlined bodies) — unlocks `file_exists`/`artifact_json` on replay |
 | `fingerprint` | Skill/baseline staleness tripwire |
 | `userVisibleRoots` | The user-visible mount roots captured at record time |
+| `readonlyFolderRoots` | The read-only (`mode: r`) subset of `userVisibleRoots` — captured body-less; lets replay give `artifact_json` the precise remedy for a body-less input |
 | `preRunPaths` | Pre-run file-path baseline for `no_unexpected_files` (workRoot-relative; co-present with `userVisibleRoots`) |
 | `scenarioSource` | Relative path to the authored YAML this was recorded from |
 | `authoring` | Present iff a live decider answered ≥1 gate during recording (`nonDeterministic: true`) |
@@ -83,10 +84,11 @@ record — retrofitting means re-recording:
    redaction missed.
 5. **Scoping idioms for scanner findings you've reviewed and accepted:** prefer the class-scoped
    flags — `--allow-domain 'api\.example\.com'`, `--allow-email '.*@yourco\.com'`,
-   `--allow-path '/opt/ci-runner/.*'` — over bare `--allow` (which applies to every class and can
-   let a domain allow swallow an email leak). For a version-controlled allowlist use
-   `--allow-file <path>`: bare all-class patterns, one regex per line, `#` comments and blank
-   lines ignored.
+   `--allow-path '/opt/ci-runner/.*'` — over bare `--allow <regex>` (a single pattern, which
+   applies to every class and can let a domain allow swallow an email leak). For a
+   version-controlled allowlist use `--allow-patterns-file <path>`: a FILE of bare all-class
+   patterns, one regex per line, `#` comments and blank lines ignored — note the flag name is the
+   FILE of patterns, not a path to allow.
 
 ## Recipe 4 — Budget assertions without a two-pass record
 

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

@@ -11,6 +11,7 @@
     "egress_allowed",
     "egress_denied",
     "file_exists",
+    "gate_answer_count_min",
     "gate_answers_delivered",
     "max_cost_usd",
     "max_tokens",

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

@@ -72,7 +72,7 @@ CONTENT_KEYS = {
     "max_turns",
 }
 # content keys, but only evaluated on replay when the cassette carries controlOut
-GATE_KEYS = {"question_asked", "questions_count_max", "gate_answers_delivered"}
+GATE_KEYS = {"question_asked", "questions_count_max", "gate_answers_delivered", "gate_answer_count_min"}
 # manifest-backed: replay-checkable when the cassette carries an `artifacts` manifest (record snapshots one);
 # a manifest-less cassette skips them. Since the 0.3.0 artifact-manifest these are NOT always live-only.
 # computer_links_resolve joins this bucket (not CONTENT_KEYS): resolving a non-empty link set needs
@@ -716,7 +716,15 @@ def build_scenario(args):
     if gates:
         for rx, _ in gates:
             content_lines.append(f"  - question_asked: {_sq(rx)}   # gate key: replay only with a controlOut cassette")
-        content_lines.append(f"  - questions_count_max: {len(gates)}")
+        # questions_count_max counts SUB-questions at runtime (assert.ts/trace-view.ts), but this
+        # scaffold is STATIC — it only knows the number of --gate rules (per-tool-call), never how many
+        # sub-questions each gate bundles. Any number emitted here would be a guess: too low false-reds
+        # on the first run, too high is a dead tripwire. A budget must come from observation, not
+        # fabrication — so emit it COMMENTED OUT with the calibration path, not a made-up value.
+        content_lines.append(
+            "  # - questions_count_max: <N>   # BUDGET — calibrate from a real run: `trace --view "
+            "questions` prints the SUB-question total (what this asserts); set N to that + headroom."
+        )
         content_lines.append("  - gate_answers_delivered: true   # the steered answers actually reached the model")
 
     live_lines = []

package/CHANGELOG.md

@@ -6,6 +6,77 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.25.0] — 2026-07-05
+
+> **Upgrade notes.**
+> - **`verify-cassettes --allow-file` was renamed to `--allow-patterns-file`** and the old spelling is
+>   removed (exits 2). Update any CI step or allowlist wiring that passed `--allow-file`.
+> - **`gate_answers_delivered: true` now passes vacuously when zero gates fired.** If you relied on it
+>   as an implicit "a gate must fire" check, add `gate_answer_count_min: 1` alongside it.
+> - **Read-only (`mode: r`) connected-folder inputs are now captured body-less.** Re-record affected
+>   cassettes to drop the `--allow` entries they previously required and shrink them; an `artifact_json`
+>   assertion pointed at a read-only input now reports evidence-unavailable (assert on a deliverable).
+>   This changes committed cassette *contents* (not the staleness hash) — a re-record is cosmetic, not
+>   required for correctness.
+
+### Added
+
+- **`gate_answer_count_min: <N>` assertion** — the presence companion to `gate_answers_delivered`:
+  fails unless at least N `AskUserQuestion` gates fired AND were delivered non-error. Pairs with
+  `gate_answers_delivered`'s new zero-gate vacuous-pass (below) the way `transcript_contains` pairs
+  with `computer_links_resolve`'s zero-link vacuous-pass. Evaluated on replay only with a `controlOut`
+  cassette, like the other gate keys; fails as evidence-unavailable (not vacuous-pass) when
+  gate-delivery telemetry is absent from `result.json`.
+
+### Changed
+
+- **`gate_answers_delivered: true` now passes vacuously when zero `AskUserQuestion` gates fired**,
+  instead of hard-failing. Whether a gate fires is model-dependent, so any skill with optional gating
+  could not use the assertion under the old hard-fail. The bad-delivery check (an answered gate whose
+  answer wasn't confirmed delivered) is unchanged — it only ever mattered when gates fired. Missing
+  gate-delivery telemetry (an old/partial `result.json` on the verify-run lane) still fails loud as
+  evidence-unavailable, never vacuous-pass — this is NOT the same as "no gate fired" and preserves the
+  bug-#33 false-green fix. Pair with the new `gate_answer_count_min` (below) to also require presence.
+- **`verify-cassettes --allow-file <path>` renamed to `--allow-patterns-file <path>`.** The old name
+  read as "allow this file" and was routinely confused with `--allow <regex>` (a pattern matched
+  against a finding) — reaching for `--allow-file <artifact-path>` failed with an ENOENT/invalid-regex
+  error instead of doing what the user meant. `--allow-patterns-file <path>` is self-documenting: the
+  path names a **file of patterns** (one regex per line), not a path to allow. Pre-1.0 rename with **no
+  deprecation window** — the old `--allow-file` spelling is hard-removed and now exits 2 with an
+  unknown-flag error. The binary-finding recourse message and both `--help` texts now spell out the
+  distinction between the two flags.
+
+### Fixed
+
+- **Read-only (`mode: r`) connected-folder inputs are captured body-less (path + hash) instead of as
+  full binary bodies.** `record` used to sweep a `mode: r` folder's files into the cassette
+  `artifacts[]` as full base64 bodies — an input the agent only reads, not a deliverable — causing
+  cassette bloat and a hard `binary` privacy finding that forced `--allow`. The manifest entry now
+  carries `path` + `bytes` + `sha256` with `truncated: true` and no `body`, reusing the same
+  representation the 64-KiB inline cap already produces. The entry still survives in the manifest (it
+  is NOT excluded), so `computer_links_resolve`/`file_exists` resolve identically on live and replay.
+  `artifact_json` against a body-less target (a read-only input, or any artifact over the body cap)
+  reports a clear **evidence-unavailable** on every lane — live, verify-run, and replay all agree, so
+  a cassette can't record green and replay red. The cassette persists the read-only-folder set
+  (`readonlyFolderRoots`, a subset of `userVisibleRoots`), so replay knows *why* an entry is body-less
+  and gives the **precise** remedy — "assert on a deliverable" for a read-only input, "raise
+  `--max-artifact-bytes`" for an over-cap artifact — instead of a cryptic JSON parse error or a
+  guessed hint. A `mode: rw`/`rwd` folder's contents are unaffected and keep their full body.
+- **`trace --view questions` and the `scaffold` helper disagreed with `questions_count_max` on what
+  "a question" counts.** The assertion counts **sub-questions** (one `AskUserQuestion` bundling K
+  sub-questions counts as K — the better spam/burden budget, since per-tool-call counting would miss
+  a 10-in-1 bundle), but `trace --view questions` collapsed a bundle into one row with no count, and
+  the scaffold helper emitted `questions_count_max: <gate count>` — a budget that could start BELOW
+  what the assertion computes and false-red on the first real run. No behavior change to the
+  assertion itself: `trace --view questions` now annotates each gate row with its sub-question count
+  and prints a footer total (`N gate(s), M sub-question(s) total`) that matches what
+  `questions_count_max` compares against. The static `scaffold` helper can't know the sub-question
+  count offline, so instead of fabricating a value it now emits `questions_count_max` **commented
+  out** as a calibration TODO pointing at `trace --view questions` (a budget must come from
+  observation, not a guess — a fabricated one either false-reds or is a dead tripwire). The count
+  definition is now documented in `docs/scenario.md`, `docs/cassette.md`, `SPEC.md`, and the skill's
+  `references/scenario-schema.md` / `SKILL.md` gotcha list.
+
 ## [0.24.0] — 2026-07-05
 
 ### Added

package/README.md

@@ -84,7 +84,7 @@ Only the committed-cassette `replay` above is fully self-contained. Live `run`/`
 > - **Replay only (zero setup):** `cowork-harness replay <cassette>` — no token, no Docker, no agent. The command above.
 > - **`protocol` (real model, no Docker):** needs only the auth token (item 3 below).
 > - **Live `container` / `microvm` / `hostloop` / `cowork`:** needs Docker (or Lima for `microvm`), a staged agent, and the token — run `cowork-harness doctor` first.
-> - **Invocation:** from a source checkout, `node dist/cli.js <cmd>` (or `npm link` to get the `cowork-harness` command); from a global install, `cowork-harness <cmd>`; the companion skill falls back to `npx cowork-harness@>=0.24.0`.
+> - **Invocation:** from a source checkout, `node dist/cli.js <cmd>` (or `npm link` to get the `cowork-harness` command); from a global install, `cowork-harness <cmd>`; the companion skill falls back to `npx cowork-harness@>=0.25.0`.
 >
 > *(One project, three names: the repo folder is `claude-cowork-headless-emulator`; the npm package, the CLI command, and the GitHub repo are all `cowork-harness`.)*
 
@@ -104,7 +104,7 @@ This repo ships a **companion skill** (`.claude/skills/cowork-harness/`) that te
 /plugin install cowork-harness@cowork-harness
 ```
 
-The skill **self-bootstraps the CLI**: if `cowork-harness` isn't on your PATH it falls back to `npx cowork-harness@>=0.24.0` (a version floor that fails loud rather than silently fetching a too-old CLI; Node ≥ 20). Tiers above `protocol` still need Docker/Lima and a Claude Desktop agent binary — see the prerequisites below.
+The skill **self-bootstraps the CLI**: if `cowork-harness` isn't on your PATH it falls back to `npx cowork-harness@>=0.25.0` (a version floor that fails loud rather than silently fetching a too-old CLI; Node ≥ 20). Tiers above `protocol` still need Docker/Lima and a Claude Desktop agent binary — see the prerequisites below.
 
 It also follows the open [Agent Skills](https://github.com/vercel-labs/skills) spec, so it installs cross-editor (Cursor, Codex, OpenCode, …) by pointing the `npx skills` CLI at `.claude/skills/cowork-harness` in this repo. (Working *inside* this repo, the skill auto-loads as a project skill — no install needed.)
 
@@ -119,7 +119,7 @@ A global install is enough for CI `lint`, reading the teaching skill, and replay
 To `run` the worked examples live or copy them as a starting point, use a source checkout. (The marketplace
 skill install itself only pulls `.claude/skills/cowork-harness/` — SKILL.md + `references/` + `scenario.py`/
 assertion keys, per `.claude-plugin/marketplace.json`'s `source` — not the rest of this table; the full set
-above becomes available once the skill's first command self-bootstraps `npx cowork-harness@>=0.24.0` — see
+above becomes available once the skill's first command self-bootstraps `npx cowork-harness@>=0.25.0` — see
 [above](#drive-it-from-claude-code-companion-skill) — which pulls the same npm package as the global-install row.)
 
 ### Prerequisites for anything above `protocol` fidelity
@@ -179,7 +179,7 @@ cowork-harness lint examples/scenarios/*.yaml
 > `tool_calls_max`/`max_turns`, `result`, the verdict modifiers) always — note `max_cost_usd`/`max_tokens`
 > assert the *frozen recording's* spend on replay, not fresh spend; a real budget regression is caught by a
 > live `run` — plus `question_asked`/
-> `questions_count_max`/`gate_answers_delivered` when the cassette carries `controlOut`, and
+> `questions_count_max`/`gate_answers_delivered`/`gate_answer_count_min` when the cassette carries `controlOut`, and
 > **filesystem assertions** (`file_exists`, `user_visible_artifact`, `artifact_json`,
 > `computer_links_resolve`) when it carries an
 > `artifacts` manifest. Genuinely live-only keys (`egress_*`, `expect_denied`, `no_delete_in_outputs`,
@@ -307,7 +307,7 @@ Skill testing is the headline use, but the tool is a general harness over the Co
 | `run <scenario.yaml \| dir/>` | Run authored scenarios with `assert:` + a CI-ready exit code; a decider (`--decider-cmd`/`--decider-dir`, or a scenario's `on_unanswered: llm`) can answer unscripted gates. `--repeat N` (2-100) runs each scenario N times and aggregates a variance rollup instead of a single pass/fail — `--min-pass-rate`, `--stop-on-diverge`, `--max-budget-usd` tune the batch verdict/loop. `--matrix <matrix.yaml>` runs ONE scenario across the cross-product of baseline/model/skill_dir axes (worked example: `examples/matrices/csv-metrics-matrix.yaml`) — `--max-cells`/`--concurrency` tune the cap/pool; any cell failing (assertion or infra) fails the run; `--compact`/`--demo` trim output for shareable screenshots/GIFs (shared with `skill`, below) | you want a repeatable, **asserted regression test** — to **measure flakiness** instead of trusting one green — or to **test a compatibility matrix** (multiple baselines/models/skill variants) in one run |
 | `chat <folder> [prompt]` | Interactive multi-turn REPL against a skill (TTY); optional seed prompt is sent as the first turn. `--upload <file>` / `--folder <dir>` (repeatable) attach files/project folders; `--verbose` shows thinking blocks + tool inputs; `--fidelity protocol\|container\|hostloop` (no `microvm`/`cowork` in the REPL) | debugging a multi-turn flow by hand |
 | `record` / `replay` | **Record a live run once → replay it token-free, Docker-free thereafter.** Key flags: `--decider-llm`/`--decider-dir` (answer gates live during recording), `--rerecord-stale`/`--concurrency <N>` (batch re-recording), `--assert-from <scenario.yaml>`/`--reassert` (re-check the on-disk `assert:` instead of the frozen one), `--strict`/`--fail-on-skill-drift` (staleness handling on replay), `--no-redact` (skip record-time redaction), `--allow-failing` (relax the post-run verdict gate), `--dry-run` (resolve without recording). Full flag list: `cowork-harness record --help` / `replay --help`. | **token-free, Docker-free CI** from a once-recorded run |
-| `verify-cassettes <file\|dir>` | Token-free CI gate over committed cassettes: a privacy scan (email/currency/domain/path/machine-inventory → exit 1; whole-token allows via `--allow` / class-scoped `--allow-domain` / `--allow-email` / `--allow-path` / `--allow-machine-inventory` / `--allow-file`) + a staleness check (`--skip-privacy` or `--skip-staleness` to run only one half). A dir argument scans `*.cassette.json` in that dir only (**non-recursive**) | gating **committed cassettes** against PII leaks + "edited the skill, forgot to re-record" |
+| `verify-cassettes <file\|dir>` | Token-free CI gate over committed cassettes: a privacy scan (email/currency/domain/path/machine-inventory → exit 1; whole-token allows via `--allow <regex>` (a pattern) / class-scoped `--allow-domain` / `--allow-email` / `--allow-path` / `--allow-machine-inventory` / `--allow-patterns-file <path>` (a **file** of patterns, one regex per line)) + a staleness check (`--skip-privacy` or `--skip-staleness` to run only one half). A dir argument scans `*.cassette.json` in that dir only (**non-recursive**) | gating **committed cassettes** against PII leaks + "edited the skill, forgot to re-record" |
 | `verify-run <run-dir> <scenario.yaml>` | Re-evaluate a scenario's `assert:` (and, when the scenario declares `answers:`, whether they still match the run's actual gates) against an already-kept run dir — **no live agent, no tokens, no Docker** (~1s) | iterating on a wrong assertion or a drifted `answer` without a full live re-record |
 | `trace <run-id>` | Digest a run's `events.jsonl` (`--view tools\|questions\|dispatches`; legacy `--tools` / `--gates` / `--dispatches` aliases still accepted) | "how many sub-agents *actually* dispatched, and which?" |
 | `inspect <run-id>` | Show what a run **produced**: the artifacts + a shallow field preview of each JSON artifact (`--output-format json` for a digest). Works on a salvaged partial run too | "did it do the job?" — without hand-parsing `…/mnt/outputs/…` |

package/SPEC.md

@@ -384,7 +384,7 @@ states in `baseline.provenance.gates`). A skill that ignores these behaves diffe
   `tool_*`, `subagent_*`, `dispatch_count_max`, `skill_triggered`, `no_skill_triggered`, `max_cost_usd`,
   `max_tokens`, `tool_calls_max`, `max_turns`, `result`, the verdict modifiers (`allow_permissive_auto_allow`,
   `allow_missing_capability`, `allow_l0_plugin_divergence`, `allow_stall`), and (when `controlOut` is present)
-  `question_asked`, `questions_count_max`, `gate_answers_delivered`. `max_cost_usd`/`max_tokens` are
+  `question_asked`, `questions_count_max`, `gate_answers_delivered`, `gate_answer_count_min`. `max_cost_usd`/`max_tokens` are
   evaluated against the *frozen recording's* usage/cost on replay, not fresh spend; `tool_calls_max`/
   `max_turns` are meaningfully replay-checkable (the re-drive recomputes both deterministically).
 - **Filesystem assertions** (`file_exists`, `user_visible_artifact`, `artifact_json`, `computer_links_resolve`,
@@ -405,10 +405,21 @@ green replay does not imply the recording is still valid. Each finding is surfac
 `RunResult.staleness[]` for a token-free gate to act on. `replay --strict` fails on any class;
 `replay --fail-on-skill-drift` fails only on skill-source classes (`skill` / `shared-root` /
 `unverifiable-skill`). Both realize the gate as failing `assertions[]` entries (so `ok`/exit stay consistent).
-- **`question_asked` / `questions_count_max` / `gate_answers_delivered`** additionally require
-  `controlOut`. Without it, a loud `::warning::` fires and these keys are excluded (not vacuously
-  passed). The authoritative list is `contentKeys` in `src/run/cassette.ts`; `docs/cassette.md` mirrors
-  it — consult it for the full table.
+- **`question_asked` / `questions_count_max` / `gate_answers_delivered` / `gate_answer_count_min`**
+  additionally require `controlOut`. Without it, a loud `::warning::` fires and these keys are
+  excluded (not vacuously passed). The authoritative list is `contentKeys` in `src/run/cassette.ts`;
+  `docs/cassette.md` mirrors it — consult it for the full table.
+- **`gate_answers_delivered: true` passes vacuously when zero `AskUserQuestion` gates fired** (gate
+  firing is model-dependent). Pair it with `gate_answer_count_min: <N>` to also require that at least
+  N gates fired AND were delivered non-error — the presence companion, mirroring
+  `computer_links_resolve` (zero-passes) paired with `transcript_contains` (presence). Both keys fail
+  evidence-unavailable, never vacuous-pass, when gate-delivery telemetry itself is absent from
+  `result.json` (an old/partial run on the verify-run lane).
+- **`questions_count_max` counts sub-questions, not `AskUserQuestion` tool calls/gates.** A bundled
+  gate with K sub-questions counts as K (`src/run/run.ts`'s recorder pushes one `rec.questions` entry
+  per sub-question; `src/assert.ts` compares against that count). `trace --view questions` shows the
+  same per-gate sub-question count and a matching footer total, so the two surfaces agree — see
+  `docs/cassette.md` / `docs/scenario.md`'s `questions_count_max` row.
 
 **Assertion source (replay):** by default `replay` evaluates the `assert:` block **frozen in the cassette**
 — byte-deterministic and independent of the working tree. When a sibling scenario resolves and its `assert:`

package/dist/assert.js

@@ -471,10 +471,13 @@ function check(a, ctx) {
         // run/cassette, an unobserved delivery (delivered=null) is NOT neutral — it is absence of the
         // evidence the assertion requires, so it fails loud ("no silent false-greens"). `delivered:
         // false` is a real errored tool_result; `null` is "no tool_result observed for this gate".
-        if (a.gate_answers_delivered) {
-            if (ctx.gateDeliveries.length === 0) {
-                results.push(fail("gate_answers_delivered: no gates were recorded during this run — either no gate fired, or gate delivery tracking is not wired. Expected at least one delivered gate."));
-            }
+        // Zero gates fired passes vacuously (whether a gate fires is model-dependent) — pair with
+        // gate_answer_count_min to also require presence. Missing telemetry (gateDeliveriesMissing)
+        // is NOT the same as zero gates and must fail evidence-unavailable, not vacuous-pass.
+        if (ctx.gateDeliveriesMissing) {
+            results.push(fail(`evidence unavailable: gate-delivery telemetry absent from result.json — cannot evaluate gate_answers_delivered`));
+        }
+        else if (a.gate_answers_delivered) {
             const bad = ctx.gateDeliveries.filter((g) => g.delivered !== true);
             results.push(bad.length === 0
                 ? ok()
@@ -492,6 +495,17 @@ function check(a, ctx) {
             results.push(failedConfirmed.length > 0 ? ok() : fail(`expected a confirmed gate-delivery failure but none was observed`));
         }
     }
+    if (a.gate_answer_count_min !== undefined) {
+        if (ctx.gateDeliveriesMissing) {
+            results.push(fail(`evidence unavailable: gate-delivery telemetry absent from result.json — cannot evaluate gate_answer_count_min`));
+        }
+        else {
+            const delivered = ctx.gateDeliveries.filter((g) => g.delivered === true).length;
+            results.push(delivered >= a.gate_answer_count_min
+                ? ok()
+                : fail(`only ${delivered} gate answer(s) confirmed delivered, need ≥ ${a.gate_answer_count_min}`));
+        }
+    }
     if (a.artifact_json !== undefined) {
         const aj = a.artifact_json;
         const file = containedPath(ctx.workRoot, aj.artifact);
@@ -500,12 +514,33 @@ function check(a, ctx) {
         else {
             // verify the real path (after symlink resolution) is still under workRoot.
             const realFile = containedRealPath(ctx.workRoot, file);
+            // A body-less manifest entry (a read-only connected-folder input, or an artifact over the body
+            // cap) has no content in the cassette — artifact_json cannot be evaluated on replay (the 0-byte
+            // placeholder isn't parseable). To keep record/verify-run/replay SYMMETRIC (no green-record →
+            // red-replay), treat such a target as evidence-unavailable on EVERY lane: `truncatedPaths` flags
+            // it on replay; `readonlyFolderRoots` flags the read-only-input case on the live/verify-run lanes
+            // where the real file is still on disk. (Existence keys stay green — existence is provable from
+            // the recorded hash — but content is genuinely absent, so this fails loud, never vacuous.)
+            const rel = relative(resolve(ctx.workRoot), file);
+            const isReadonlyInput = (ctx.readonlyFolderRoots ?? []).some((pre) => rel === pre || rel.startsWith(pre + "/"));
+            const bodyLess = truncated.has(rel) || isReadonlyInput;
             if (!realFile) {
                 results.push(fail(`unsafe artifact_json path "${aj.artifact}" — symlink target escapes the work root`));
             }
             else if (!existsSync(realFile)) {
                 results.push(fail(`artifact_json: file not found: ${aj.artifact} (under ${ctx.workRoot})`));
             }
+            else if (bodyLess) {
+                // Every lane knows WHY the entry is body-less, so the remedy is always precise: live/verify-run
+                // derive `readonlyFolderRoots` from the plan; replay reads the set persisted on the cassette
+                // (v7). A read-only input can't be captured (assert on a deliverable); an over-cap artifact can
+                // (raise the cap). `isReadonlyInput` distinguishes them on all three lanes.
+                results.push(fail(`evidence unavailable: artifact_json target "${aj.artifact}" was captured body-less ` +
+                    (isReadonlyInput
+                        ? `(read-only connected-folder input — its content is never captured; assert artifact_json on a deliverable instead)`
+                        : `(larger than the artifact-body cap — raise --max-artifact-bytes to capture it)`) +
+                    ` — content is not in the cassette, so it cannot be evaluated on replay`));
+            }
             else {
                 let doc;
                 let parsed = true;

package/dist/cli.js

@@ -91,7 +91,8 @@ const HELP = `cowork-harness <command>   (v${"$VERSION"})
       [--output-format json]
   verify-cassettes <file|dir>  CI gate (no token): privacy scan + staleness — exit 1 on finding or drift
       [--skip-privacy|--skip-staleness]  skip one check
-      [--allow <regex>]... [--allow-domain <regex>]... [--allow-email <regex>]... [--allow-path <regex>]... [--allow-machine-inventory <regex>]... [--allow-file <path>]... [--output-format json]
+      [--allow <regex>]... [--allow-domain <regex>]... [--allow-email <regex>]... [--allow-path <regex>]... [--allow-machine-inventory <regex>]... [--allow-patterns-file <path>]... [--output-format json]
+      --allow <regex> is a PATTERN (matched against a finding); --allow-patterns-file <path> is a FILE of patterns, one regex per line — not a path to allow
   rehash <dir/>                migrate cassette fingerprints to current version when content is provably unchanged (requires contentSig from v3+)
   init-redact [--force]        copy the packaged reference .cowork-redact.json into the cwd (redaction starter
                                for hostloop/protocol recordings; review + tailor the patterns before recording)
@@ -342,7 +343,8 @@ const SUBCOMMAND_USAGE = {
     replay: "usage: replay <file.cassette.json | dir/> [--strict] [--fail-on-skill-drift] [--assert-from <scenario.yaml> | --reassert] [--output-format text|json]\n" +
         "       by default the assertions FROZEN in the cassette drive the verdict (deterministic); a sibling scenario whose assert: differs only prints a notice.\n" +
         "       --assert-from <file> / --reassert: token-free re-check against the on-disk assert:/expect_denied: — recording-shaping drift (prompt/answers/baseline/skills) and skill staleness HARD-FAIL.",
-    "verify-cassettes": "usage: verify-cassettes <file|dir> [--skip-privacy|--skip-staleness] [--allow <regex>]... [--allow-domain <regex>]... [--allow-email <regex>]... [--allow-path <regex>]... [--allow-machine-inventory <regex>]... [--allow-file <path>]... [--output-format json]",
+    "verify-cassettes": "usage: verify-cassettes <file|dir> [--skip-privacy|--skip-staleness] [--allow <regex>]... [--allow-domain <regex>]... [--allow-email <regex>]... [--allow-path <regex>]... [--allow-machine-inventory <regex>]... [--allow-patterns-file <path>]... [--output-format json]\n" +
+        "       --allow <regex> is a PATTERN (matched against a finding); --allow-patterns-file <path> is a FILE of patterns, one regex per line — not a path to allow.",
     trace: "usage: trace <run-id | run-dir | events.jsonl> [--view tools|questions|dispatches] [--translate-paths] [--output-format json]\n       --view tools       tool call / result rows\n       --view questions   gate lifecycle (question → answer → delivered)\n       --view dispatches  sub-agent dispatch tree + dispatch_count_max\n       --translate-paths  rewrite VM paths to host paths in the tools/default TEXT views only (needs a sibling mounts.json + an effective hostloop run; questions/dispatches views and --output-format json are unaffected)\n       (default: all views)\n       (for what the run PRODUCED — artifacts — use `inspect`)",
     assertions: "usage: assertions --list [--output-format json]",
     scaffold: "usage: scaffold <run-id | run-dir> [--out <file.yaml>] [--output-format text|json]\n       Turns a kept run into a starter scenario YAML (gates→answers, artifacts→file_exists).\n       Positional <run-id | run-dir> is the canonical form.",
@@ -2788,6 +2790,9 @@ async function cmdVerifyRun(args) {
         // Read the roots persisted at run time (folder mount names are dynamic/gated, not a fixed prefix).
         // Fall back to the legacy prefix for old result.json that predates the field.
         userVisiblePrefixes: result.userVisibleRoots ?? ["outputs", ".projects"],
+        // Read-only folder inputs are captured body-less; keep artifact_json's verdict identical to the
+        // replay lane (evidence-unavailable) instead of parsing the real on-disk input here.
+        readonlyFolderRoots: result.readonlyFolderRoots ?? [],
         // result.json is the single source: every writer populates the field from the run's own
         // pre-run-manifest.json, so a missing field means the baseline genuinely doesn't exist
         // (pre-field run, or the run never captured) — evidence-unavailable, loud.
@@ -2798,6 +2803,7 @@ async function cmdVerifyRun(args) {
         selfHealRan: scan.selfHealRan,
         subagents: result.subagents ?? [],
         gateDeliveries: result.gateDeliveries ?? [],
+        gateDeliveriesMissing: result.gateDeliveries === undefined,
         toolResultTexts: (result.toolResults ?? []).map((r) => r.assertText ?? r.text),
         toolResultsTruncated: (result.toolResults ?? []).map((r) => r.assertText === undefined),
         transcriptMissing: sidecarTranscript === null,

package/dist/run/cassette.js

@@ -133,8 +133,14 @@ function isLosslessUtf8(buf) {
 }
 /** Snapshot the user-visible artifacts under `workRoot` into manifest entries.
  *  Exported for token-free record→replay round-trip tests. */
-export function buildManifest(workRoot, cap, roots = ["outputs", ".projects"]) {
+export function buildManifest(workRoot, cap, roots = ["outputs", ".projects"], bodyLessPrefixes = []) {
     const limit = cap ?? defaultBodyCap();
+    // Read-only connected-folder inputs (`bodyLessPrefixes`) are captured path+bytes+sha256 only, same as
+    // an over-cap entry — no body, so no bloat and no `binary` privacy finding (cassette.ts binary scan
+    // only fires on a committed base64 body). The manifest entry SURVIVES (unlike full exclusion) so
+    // `materializeManifest` writes a 0-byte placeholder and `computer_links_resolve` resolves identically
+    // on live and replay (see T3 in the pre-1.0 fix plan).
+    const isBodyLess = (path) => bodyLessPrefixes.some((prefix) => path === prefix || path.startsWith(prefix + "/"));
     return collectArtifacts(workRoot, roots).map(({ path, bytes }) => {
         // collectArtifacts paths are derived from a directory walk; even though it already skips symlinks,
         // an entry must not inline content outside the work root. Re-confirm containment before reading the body.
@@ -153,7 +159,7 @@ export function buildManifest(workRoot, cap, roots = ["outputs", ".projects"]) {
             return { path, bytes, sha256: "", truncated: true };
         }
         const sha256 = createHash("sha256").update(buf).digest("hex");
-        if (buf.length > limit)
+        if (buf.length > limit || isBodyLess(path))
             return { path, bytes, sha256, truncated: true };
         // store an encoding marker. UTF-8-safe bodies stay text (readable cassettes); binary bodies go
         // base64 so the record→replay round-trip is byte-exact and the sha256 verify stays valid.
@@ -379,11 +385,12 @@ export function scanCassette(cassette, allow) {
                     // zip/DEFLATE streams. Count a COMMITTED binary body as a real finding (cls "binary", NOT the
                     // benign "unscanned" used for a TRUNCATED/uncommitted entry below) so the gate can't greenlight
                     // raw recoverable PII. Recourse: after reviewing the deliverable, clear it with
-                    // `--allow <path-regex>` (matched on the artifact path above, since the body is unreadable).
+                    // `--allow <path-regex>` (a PATTERN matched on the artifact path above, since the body is
+                    // unreadable) — NOT `--allow-patterns-file`, which loads a FILE of patterns, not a path to allow.
                     findings.push({
                         where: `artifact ${a.path}`,
                         cls: "binary",
-                        sample: `(committed binary body — not text-scannable; review and clear with --allow ${a.path})`,
+                        sample: `(committed binary body — not text-scannable; review and clear with --allow ${a.path} (a pattern matched on this path); note --allow-patterns-file is a FILE of patterns, not this path)`,
                     });
                 }
             }
@@ -407,6 +414,9 @@ export function scanCassette(cassette, allow) {
     // cassettes`. Scan them too, prefixed `metadata:` so a reviewer knows redaction here ALSO rewrites
     // structural paths, distinct from free-text findings in the transcript/deliverable.
     (cassette.userVisibleRoots ?? []).forEach((r, i) => findings.push(...scanText(r, `metadata:userVisibleRoots[${i}]`, allow, FULL)));
+    // readonlyFolderRoots is a subset of userVisibleRoots (same strings), but it's a separately-persisted
+    // field — scan it too so a reviewer can't be surprised by an unscanned persisted string.
+    (cassette.readonlyFolderRoots ?? []).forEach((r, i) => findings.push(...scanText(r, `metadata:readonlyFolderRoots[${i}]`, allow, FULL)));
     findings.push(...scanText(cassette.scenario.name ?? "", "metadata:scenario.name", allow, FULL));
     findings.push(...scanText(cassette.scenario.session ?? "", "metadata:scenario.session", allow, FULL));
     if (cassette.scenarioSource)
@@ -1014,10 +1024,15 @@ export function redactCassette(cassette, policy) {
         }
     }
     const redactedPreRunPaths = cassette.preRunPaths?.map((p) => redactText(p, policy));
+    // readonlyFolderRoots is a subset of userVisibleRoots; redact it with the same context-free redactText
+    // so the prefix relationship with the (redacted) artifact paths is preserved. The `...cassette` spread
+    // would otherwise carry the UNREDACTED set through.
+    const redactedReadonly = cassette.readonlyFolderRoots?.map((r) => redactText(r, policy));
     return {
         ...cassette,
         scenario,
         userVisibleRoots: redactedRoots,
+        readonlyFolderRoots: redactedReadonly,
         artifacts: redactedArtifacts,
         preRunPaths: redactedPreRunPaths,
         events: cassette.events.map((l) => redactJsonLine(l, policy)),
@@ -1299,14 +1314,18 @@ export function redactionPreflightMessage(items) {
         `COWORK_HARNESS_REDACT_PATTERNS. (The always-on privacy scanner remains the universal net — ` +
         `container-tier recordings can trip it too.)\n`);
 }
-/** Return the `artifact_json.artifact` paths a scenario asserts that ended up TRUNCATED in the manifest
- *  (body >cap, hash-only). Such an assertion passes at record (evaluated on the live on-disk file) but FAILS
- *  at replay (the materialized body is empty → "not valid JSON"). Paths are normalized through `resolve` so
- *  `./outputs/x.json` and `outputs/x.json` join cleanly against the manifest's walk paths. */
-export function artifactJsonTargetsTruncated(scenario, workRoot, artifacts) {
+/** Return the `artifact_json.artifact` paths a scenario asserts that ended up truncated by SIZE (body
+ *  >cap, hash-only) — the genuine green-record/red-replay case whose remedy is "raise the cap". This
+ *  EXCLUDES read-only connected-folder inputs: those are body-less by policy (not size), raising the cap
+ *  can't capture them, and `artifact_json` against one already fails LOUD-and-symmetrically at record,
+ *  verify-run, and replay (evidence-unavailable, see assert.ts) — so they are neither an asymmetry nor a
+ *  "too large" problem. Paths are normalized through `resolve` so `./outputs/x.json` and `outputs/x.json`
+ *  join cleanly against the manifest's walk paths. */
+export function artifactJsonTargetsTruncated(scenario, workRoot, artifacts, readonlyFolderRoots = []) {
+    const isReadonly = (p) => readonlyFolderRoots.some((pre) => p === pre || p.startsWith(pre + "/"));
     const truncatedAbs = new Set();
     for (const a of artifacts)
-        if (a.truncated)
+        if (a.truncated && !isReadonly(a.path))
             truncatedAbs.add(resolve(workRoot, a.path));
     if (truncatedAbs.size === 0)
         return [];
@@ -1805,7 +1824,10 @@ async function recordScenarioObject(scenario, opts, extraPolicyDirs = []) {
     // Snapshot under the run's REAL user-visible roots (outputs + resolved folder mount names), persisted
     // below as cassette.userVisibleRoots so replay matches — not the legacy hardcoded `.projects/` prefix.
     const recordRoots = result.userVisibleRoots ?? ["outputs", ".projects"];
-    const artifacts = (result.workDir ? buildManifest(result.workDir, opts.maxArtifactBytes, recordRoots) : []).map((a) => {
+    // Read-only connected-folder inputs are captured body-less (path + sha256, no body) — see buildManifest's
+    // `bodyLessPrefixes` doc comment. `recordRoots`/`cassette.userVisibleRoots` stay the FULL set; only the
+    // captured bodies under these prefixes are stripped.
+    const artifacts = (result.workDir ? buildManifest(result.workDir, opts.maxArtifactBytes, recordRoots, result.readonlyFolderRoots ?? []) : []).map((a) => {
         if (a.body === undefined)
             return a;
         if (a.encoding === "base64") {
@@ -1846,7 +1868,7 @@ async function recordScenarioObject(scenario, opts, extraPolicyDirs = []) {
     // replay (no committed body). Surface that record→replay asymmetry NOW, at its cause, instead of letting a
     // green record produce a red replay in CI. Honor --allow-failing (warn, don't block) like the verdict gate.
     if (result.workDir) {
-        const truncatedAsserted = artifactJsonTargetsTruncated(scenario, result.workDir, artifacts);
+        const truncatedAsserted = artifactJsonTargetsTruncated(scenario, result.workDir, artifacts, result.readonlyFolderRoots ?? []);
         if (truncatedAsserted.length) {
             const cap = opts.maxArtifactBytes ?? defaultBodyCap();
             const msg = `artifact_json asserts artifact(s) too large to commit (>${cap} B, stored hash-only): ${truncatedAsserted.join(", ")} — ` +
@@ -1868,6 +1890,9 @@ async function recordScenarioObject(scenario, opts, extraPolicyDirs = []) {
         effectiveFidelity: result.effectiveFidelity,
         artifacts,
         userVisibleRoots: recordRoots,
+        // Persist the read-only subset ONLY when non-empty (keeps cassettes without connected folders
+        // clean); replay reads it to distinguish a body-less read-only input from an over-cap artifact.
+        ...(result.readonlyFolderRoots?.length ? { readonlyFolderRoots: result.readonlyFolderRoots } : {}),
         // co-present with userVisibleRoots by construction (see the Cassette field comment) — a cassette
         // carrying preRunPaths never hits replay's legacy-roots fallback.
         preRunPaths: result.preRunPaths,
@@ -1956,7 +1981,7 @@ function warnUncheckableOnDiskKeys(cassette, frozen, onDisk) {
     // Reuse the exported classification constant — this local copy drifted once already (it was
     // missing computer_links_resolve), silently suppressing the on-disk warning for that key.
     const manifestKeys = new Set(MANIFEST_KEYS);
-    const gateKeys = new Set(["question_asked", "questions_count_max", "gate_answers_delivered"]);
+    const gateKeys = new Set(["question_asked", "questions_count_max", "gate_answers_delivered", "gate_answer_count_min"]);
     const liveOnlyKeys = new Set([
         "egress_denied",
         "egress_allowed",
@@ -2179,9 +2204,9 @@ export function cmdVerifyCassettes(args) {
         p = parseArgs(args, {
             booleans: ["--skip-privacy", "--skip-staleness", "--quiet", "--verbose"],
             values: ["--output-format"],
-            repeated: ["--allow", "--allow-domain", "--allow-email", "--allow-path", "--allow-machine-inventory", "--allow-file"],
+            repeated: ["--allow", "--allow-domain", "--allow-email", "--allow-path", "--allow-machine-inventory", "--allow-patterns-file"],
             enums: { "--output-format": ["text", "json"] },
-            noDashValue: ["--allow-file"],
+            noDashValue: ["--allow-patterns-file"],
             aliases: { "-q": "--quiet" },
         });
     }
@@ -2198,10 +2223,13 @@ export function cmdVerifyCassettes(args) {
     }
     const doPrivacy = !skipPrivacy;
     const doStaleness = !skipStaleness;
-    // Allow model: each entry is whole-token anchored + class-scoped. A bare `--allow` applies to every
-    // class (back-compat); `--allow-domain`/`--allow-email`/`--allow-path`/`--allow-machine-inventory`
-    // scope to one class so a domain allow can't bleed into the email tripwire. `--allow-file` loads bare
-    // (all-class) patterns from a version-controlled file, one per line, `#` comments and blanks ignored.
+    // Allow model: each entry is whole-token anchored + class-scoped. A bare `--allow <regex>` is a single
+    // PATTERN applied to every class (back-compat); `--allow-domain`/`--allow-email`/`--allow-path`/
+    // `--allow-machine-inventory` scope a pattern to one class so a domain allow can't bleed into the
+    // email tripwire. `--allow-patterns-file <path>` is a different thing: it loads bare (all-class)
+    // patterns from a version-controlled FILE of patterns, one regex per line, `#` comments and blanks
+    // ignored — not "allow this file" (the flag does not accept a path to allow, it accepts a path to a
+    // patterns list).
     const allow = [];
     const addAllow = (src, cls, flag) => {
         try {
@@ -2222,24 +2250,25 @@ export function cmdVerifyCassettes(args) {
         addAllow(src, "path", "--allow-path");
     for (const src of p.repeated["--allow-machine-inventory"] ?? [])
         addAllow(src, "machine-inventory", "--allow-machine-inventory");
-    for (const file of p.repeated["--allow-file"] ?? []) {
+    for (const file of p.repeated["--allow-patterns-file"] ?? []) {
         let body;
         try {
             body = readFileSync(file, "utf8");
         }
         catch (e) {
-            log(`--allow-file: cannot read ${file}: ${e.message}`);
+            log(`--allow-patterns-file: cannot read ${file}: ${e.message}`);
             return process.exit(2);
         }
         for (const raw of body.split("\n")) {
             const line = raw.trim();
             if (line && !line.startsWith("#"))
-                addAllow(line, undefined, `--allow-file (${file})`);
+                addAllow(line, undefined, `--allow-patterns-file (${file})`);
         }
     }
     const target = p.positionals[0];
     if (!target) {
-        log("usage: verify-cassettes <file|dir> [--skip-privacy|--skip-staleness] [--allow <regex>]... [--allow-domain <regex>]... [--allow-email <regex>]... [--allow-path <regex>]... [--allow-machine-inventory <regex>]... [--allow-file <path>]... [--output-format json]");
+        log("usage: verify-cassettes <file|dir> [--skip-privacy|--skip-staleness] [--allow <regex>]... [--allow-domain <regex>]... [--allow-email <regex>]... [--allow-path <regex>]... [--allow-machine-inventory <regex>]... [--allow-patterns-file <path>]... [--output-format json]");
+        log("  --allow <regex> is a PATTERN (matched against a finding); --allow-patterns-file <path> is a FILE of patterns, one regex per line — not a path to allow.");
         return process.exit(2);
     }
     if (p.positionals.length > 1) {
@@ -2541,7 +2570,12 @@ export const ALWAYS_CONTENT_KEYS = [
     ...VERDICT_MODIFIER_KEYS,
 ];
 /** Assertion keys evaluated on replay only when `controlOut` (full-fidelity) is present. */
-export const QUESTION_GATE_KEYS = ["question_asked", "questions_count_max", "gate_answers_delivered"];
+export const QUESTION_GATE_KEYS = [
+    "question_asked",
+    "questions_count_max",
+    "gate_answers_delivered",
+    "gate_answer_count_min",
+];
 /** Assertion keys evaluated on replay only when the cassette carries an `artifacts` manifest.
  *  `computer_links_resolve` joins this bucket (NOT ALWAYS_CONTENT_KEYS): resolving a NON-empty link set
  *  needs either a live filesystem (not available on replay) or the cassette's `artifacts` manifest — the
@@ -2746,6 +2780,9 @@ export async function replayCassette(cassette, hooks = [], opts = {}) {
             result: rec.result,
             workRoot: replayWorkRoot,
             userVisiblePrefixes: replayPrefixes,
+            // Persisted on the cassette (v7 optional metadata) so replay tells a body-less read-only input
+            // apart from an over-cap artifact and gives the precise artifact_json remediation.
+            readonlyFolderRoots: cassette.readonlyFolderRoots ?? [],
             preRunPaths: cassette.preRunPaths,
             outputsDeletes: [],
             questions: rec.questions,

package/dist/run/execute.js

@@ -15,7 +15,7 @@ import { writeRunningStatus, startStatusTicker, registerRunForCrashSafety, statu
 // the cycle is intrinsic — kept runtime-only rather than refactored.
 import { buildFingerprint } from "./cassette.js";
 import { loadBaseline } from "../baseline.js";
-import { loadSession, resolveSessionPaths, buildLaunchPlan, userVisibleRootsFromPlan } from "../session.js";
+import { loadSession, resolveSessionPaths, buildLaunchPlan, userVisibleRootsFromPlan, readonlyFolderRootsFromPlan } from "../session.js";
 import { spawnProtocol } from "../runtime/protocol.js";
 import { spawnContainer } from "../runtime/container.js";
 import { spawnHostLoop } from "../runtime/hostloop.js";
@@ -588,6 +588,13 @@ export async function executeScenario(scenario, opts = {}) {
     // (verify reads result.json; replay reads the cassette) match this without rebuilding a LaunchPlan.
     // Shared with the pre-run baseline walk (userVisibleRootsFromPlan) — pre and post MUST agree.
     const userVisibleRoots = userVisibleRootsFromPlan(plan);
+    // Read-only (`mode: "r"`) connected-folder roots — inputs, not deliverables. Persisted so the cassette
+    // recorder strips their captured BODIES (fidelity/no-bloat) and `RunResult.artifacts` excludes them
+    // outright (an input is not a `file_exists` target). Does NOT change `userVisibleRoots` above.
+    const readonlyFolderRoots = readonlyFolderRootsFromPlan(plan);
+    // artifacts (the ENV-MANIFEST) excludes read-only inputs — a deliverable is something the agent wrote,
+    // not a pre-existing input it only read.
+    const captureRoots = userVisibleRoots.filter((r) => !readonlyFolderRoots.includes(r));
     // Read the pre-run baseline ONCE: the evaluate ctx and the persisted RunResult must see the same
     // value — two reads could disagree if the file were touched mid-run.
     const preRunPaths = readPreRunManifest(outDir);
@@ -605,6 +612,7 @@ export async function executeScenario(scenario, opts = {}) {
             outDir,
             workRoot,
             userVisibleRoots,
+            readonlyFolderRoots,
             effectiveFidelity,
             egress,
             durationMs: Date.now() - startedAt,
@@ -633,6 +641,9 @@ export async function executeScenario(scenario, opts = {}) {
         result: record.result,
         workRoot,
         userVisiblePrefixes: userVisibleRoots,
+        // Read-only folder inputs are captured body-less; artifact_json must reach the same
+        // evidence-unavailable verdict here as on replay (see AssertContext.readonlyFolderRoots).
+        readonlyFolderRoots,
         preRunPaths,
         outputsDeletes: scan.outputsDeletes,
         questions: record.questions,
@@ -779,7 +790,8 @@ export async function executeScenario(scenario, opts = {}) {
         workDir: workRoot,
         outputsDir: join(workRoot, "outputs"),
         userVisibleRoots,
-        artifacts: collectArtifacts(workRoot, userVisibleRoots), // ENV-MANIFEST: observed user-visible files
+        readonlyFolderRoots,
+        artifacts: collectArtifacts(workRoot, captureRoots), // ENV-MANIFEST: observed user-visible files (excl. read-only inputs)
         // The pre-spawn baseline no_unexpected_files diffs against (same single read the evaluate ctx got).
         // undefined = the run didn't capture (key not asserted, microvm, pre-seam) — the assertion then
         // fails evidence-unavailable, loud.
@@ -946,7 +958,8 @@ export function buildPartialResult(args) {
         workDir: args.workRoot,
         outputsDir: join(args.workRoot, "outputs"),
         userVisibleRoots: args.userVisibleRoots,
-        artifacts: collectArtifacts(args.workRoot, args.userVisibleRoots),
+        readonlyFolderRoots: args.readonlyFolderRoots,
+        artifacts: collectArtifacts(args.workRoot, args.userVisibleRoots.filter((r) => !args.readonlyFolderRoots.includes(r))),
         preRunPaths: readPreRunManifest(args.outDir),
         effectiveFidelity: args.effectiveFidelity,
         ...(() => {

package/dist/run/trace-view.js

@@ -261,6 +261,11 @@ export function buildTrace(file, opts = {}) {
  * differing keys: the gate's `decision` (events.jsonl) carries both the UUID `request_id` AND the `toolu_`
  * `toolUseId`; the injected answer lives in `control-out.jsonl` keyed by `request_id`; the delivered result
  * is a `tool_result` keyed by `toolUseId`.
+ *
+ * Each row is one gate (one AskUserQuestion tool call), which may bundle several sub-questions —
+ * `subQuestionCount` carries that count so a reader can reconcile this view against
+ * `questions_count_max`, which counts sub-questions, not gates/tool-calls (see `formatGateTrace`'s
+ * footer total and `docs/scenario.md`/`docs/cassette.md`'s `questions_count_max` row).
  */
 export function buildGateTrace(file) {
     const events = eventsOf(file);
@@ -297,6 +302,7 @@ export function buildGateTrace(file) {
         const tr = req.toolUseId ? results.get(req.toolUseId) : undefined;
         rows.push({
             question: req.questions.map((q) => q.question ?? q.header ?? "").join(" / "),
+            subQuestionCount: req.questions.length,
             injectedAnswer: answers.get(req.id),
             delivered: tr ? (tr.isError ? "error" : "ok") : "unobserved",
             ...(tr?.isError ? { error: tr.text.split("\n")[0].slice(0, 160) } : {}),
@@ -332,12 +338,16 @@ export function formatGateTrace(rows) {
     if (!rows.length)
         return "(no AskUserQuestion gates in this run)";
     const mark = { ok: "✓", error: "✗", unobserved: "?" };
-    return rows
-        .map((r) => {
+    const lines = rows.map((r) => {
         const prov = r.answeredBy ? `\n    by: ${labelSource(r.answeredBy)}${r.model ? ` (${r.model})` : ""}` : "";
-        return `${mark[r.delivered]} gate "${r.question}"\n    answered: ${r.injectedAnswer ?? "(none)"}\n    delivered: ${r.delivered}${r.error ? ` — ${r.error}` : ""}${prov}`;
-    })
-        .join("\n");
+        // sub-question count is shown only when the gate bundled more than one — reconciles this row
+        // against questions_count_max, which counts sub-questions, not gates.
+        const subCount = r.subQuestionCount > 1 ? ` (${r.subQuestionCount} sub-questions)` : "";
+        return `${mark[r.delivered]} gate "${r.question}"${subCount}\n    answered: ${r.injectedAnswer ?? "(none)"}\n    delivered: ${r.delivered}${r.error ? ` — ${r.error}` : ""}${prov}`;
+    });
+    const totalSubQuestions = rows.reduce((sum, r) => sum + r.subQuestionCount, 0);
+    lines.push(`\n${rows.length} gate(s), ${totalSubQuestions} sub-question(s) total — questions_count_max counts sub-questions (assert with \`questions_count_max: ${totalSubQuestions}\`)`);
+    return lines.join("\n");
 }
 /**
  * `trace --dispatches` — the sub-agent dispatch tree, so an author can read off the REAL total

package/dist/session.js

@@ -116,6 +116,14 @@ export const SessionConfig = z.strictObject({
 export function userVisibleRootsFromPlan(plan) {
     return ["outputs", ...plan.mounts.filter((m) => m.kind === "folder").map((m) => m.mountPath)];
 }
+/** The mount prefixes of read-only (`mode: "r"`) connected folders — inputs, not deliverables. Used to
+ *  strip captured BODIES from the cassette manifest (fidelity/no-bloat) and to exclude them from
+ *  `RunResult.artifacts` (an input is not something `scaffold`/`file_exists` should treat as output).
+ *  Does NOT change `userVisibleRootsFromPlan` — `no_unexpected_files` and `computer_links_resolve`
+ *  still enumerate these roots; only their captured content changes shape. */
+export function readonlyFolderRootsFromPlan(plan) {
+    return plan.mounts.filter((m) => m.kind === "folder" && m.mode === "r").map((m) => m.mountPath);
+}
 /**
  * Read a plugin's declared version from its `.claude-plugin/plugin.json`.
  *

package/dist/types.js

@@ -241,7 +241,13 @@ export const Assertion = z.object({
     gate_answers_delivered: z
         .boolean()
         .optional()
-        .describe("every answered AskUserQuestion gate's tool_result was non-error (the answer reached the model)"),
+        .describe("every answered AskUserQuestion gate's tool_result was non-error (the answer reached the model); zero gates fired passes vacuously — pair with gate_answer_count_min to also require a gate"),
+    gate_answer_count_min: z
+        .number()
+        .int()
+        .nonnegative()
+        .optional()
+        .describe("at least N AskUserQuestion gates fired AND were delivered non-error (presence companion to gate_answers_delivered)"),
     result: z.enum(["success", "error"]).optional().describe("the run's final result was success | error"),
     allow_permissive_auto_allow: z
         .boolean()

package/docs/cassette.md

@@ -53,9 +53,11 @@ re-record). `expect_denied`/filesystem/egress keys are sourced but stay live-onl
   "events": [ /* JSON lines from events.jsonl (child→driver stdout) */ ],
   "controlOut": [ /* JSON lines from control-out.jsonl (driver→child control_responses) */ ],
   "userVisibleRoots": ["outputs", "myproject"], // visible roots = outputs + each connected folder's mount name (its basename; `.projects` is the pre-1.14271.0 legacy fallback)
+  "readonlyFolderRoots": ["carta-folder"], // the mode:r subset of userVisibleRoots (body-less); lets replay give artifact_json the precise remedy. Optional; absent when no read-only folder
   "artifacts": [                         // snapshot of outputs/ + connected folders (optional)
     { "path": "outputs/x.json", "bytes": 24, "sha256": "…", "body": "{…}" }, // body inlined ≤ 64 KiB
-    { "path": "outputs/big.bin", "bytes": 9e6, "sha256": "…", "truncated": true } // oversized → hash-only
+    { "path": "outputs/big.bin", "bytes": 9e6, "sha256": "…", "truncated": true }, // oversized → hash-only
+    { "path": "carta-folder/input.xlsx", "bytes": 4096, "sha256": "…", "truncated": true } // mode:r connected-folder INPUT → body-less (see below), regardless of size
   ],
   "fingerprint": { "baseline": "1.15962.1", "skillHash": "…", "mode": "git", "contentSig": "…", "fileSigs": [["skills/x/SKILL.md", "…"]], "skillSources": ["…"] }, // staleness tripwire (v5: fileSigs only; v6: mode + git default; v7: NUL-delimited hash entries)
   "authoring": { "nonDeterministic": true, "channel": "decider-dir" } // present ONLY when a live decider answered ≥1 gate (see §Answering gates during recording); re-record may drift, replay is still deterministic
@@ -227,17 +229,18 @@ the rules and CI-placement rationale (why each category behaves this way), see
 | `tool_calls_max` | total top-level tool calls (sub-agent tools excluded) ≤ N — meaningfully replay-checkable; the re-drive recomputes `toolCounts` deterministically |
 | `max_turns` | SDK-reported (or fallback-counted) turn count ≤ N — replay-checkable, recounted deterministically same as `tool_calls_max` |
 | `question_asked` | agent asked an AskUserQuestion matching the regex |
-| `questions_count_max` | at most N questions asked |
-| `gate_answers_delivered` | answered gates' answers reached the model |
+| `questions_count_max` | 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` | answered gates' answers reached the model — **zero gates fired passes vacuously** (gate firing is model-dependent); pair with `gate_answer_count_min` to also require a gate |
+| `gate_answer_count_min` | at least N AskUserQuestion gates fired AND were delivered non-error — the presence companion to `gate_answers_delivered`'s vacuous-pass |
 | `result` | run ended with `success` or `error` |
 | `allow_permissive_auto_allow` | verdict modifier — kept on replay → no-op pass (the live signal it suppresses is zeroed) |
 | `allow_missing_capability` | verdict modifier — kept on replay → no-op pass (the live signal it suppresses is zeroed) |
 | `allow_l0_plugin_divergence` | verdict modifier — kept on replay → no-op pass (the live signal it suppresses is zeroed) |
 | `allow_stall` | verdict modifier — kept on replay → no-op pass (suppresses the `stalled` default-fail; the stall is re-derived on the replay re-drive) |
 
-**`question_asked`, `questions_count_max`, `gate_answers_delivered` require `controlOut`** (full-fidelity
-replay). On an old cassette without `controlOut` these three keys are excluded from evaluation — not
-vacuously passed — and a loud warning fires (see §Backward compatibility).
+**`question_asked`, `questions_count_max`, `gate_answers_delivered`, `gate_answer_count_min` require
+`controlOut`** (full-fidelity replay). On an old cassette without `controlOut` these keys are excluded
+from evaluation — not vacuously passed — and a loud warning fires (see §Backward compatibility).
 
 `file_exists`, `user_visible_artifact`, `artifact_json`, `computer_links_resolve`, and `no_unexpected_files` are **not** in the
 table above — see the next subsection; they're replay-checkable only when the cassette carries an
@@ -258,7 +261,19 @@ The inline cap is 64 KiB; raise it with `record --max-artifact-bytes <n>` (or
 fails fast if an `artifact_json` targets an artifact it had to truncate (that would pass at record but fail
 at replay). `computer_links_resolve` resolves every `computer://` link in the transcript against the same
 manifest, with host-shaped links normalized via the recorded session folders. Without a manifest (older
-cassettes), these are skipped. A green replay re-confirms *record-time* artifacts, **not** that the current
+cassettes), these are skipped.
+
+**Read-only (`mode: r`) connected-folder contents are captured body-less.** A folder mounted `mode: r` in
+`session:` holds pre-existing INPUTS the agent only reads, not deliverables — so `record` snapshots them
+the same way it snapshots an over-cap file: path + `bytes` + `sha256`, `truncated: true`, **no `body`**,
+regardless of size. The entry still lands in `artifacts[]` (unlike a fully-excluded path) so
+`materializeManifest` writes a 0-byte placeholder at replay and `computer_links_resolve`/`file_exists`
+resolve identically live and on replay; only `artifact_json` (which needs the inlined body) can't target
+one. Two side benefits: no cassette bloat from a large input file, and no `binary` privacy finding (the
+scanner only flags a *committed* binary body) — so a `mode: r` input never needs `--allow`. A `mode: rw`/`rwd`
+folder's contents are captured with a full body exactly as `outputs/` is.
+
+A green replay re-confirms *record-time* artifacts, **not** that the current
 skill still produces them — `replay --strict` fails the run when the `fingerprint` shows ANY skill/baseline
 drift, or `replay --fail-on-skill-drift` fails only on skill-source drift (leaving baseline drift a warning).
 Either way, every replay result also reports the drift in `staleness[]` (class-tagged) for a JSON gate to read.
@@ -303,12 +318,16 @@ On replay, the replay decider (built by `buildReplayDecider()`) indexes `control
 the decision pipeline instead of consulting a live decider or asking the user. This makes the full
 `Run.handleDecision` path execute on replay, which populates `rec.questions`, `rec.gateAnswers`, and
 `rec.gateDeliveries` — exactly as in a live run. Consequence: `question_asked`, `questions_count_max`,
-and `gate_answers_delivered` are now genuinely evaluated, not silently skipped or vacuously passed.
+`gate_answers_delivered`, and `gate_answer_count_min` are now genuinely evaluated, not silently skipped
+or vacuously passed.
 
 `gate_answers_delivered` accepts a boolean: `: true` asserts the answered gates' answers reached the
-model; `: false` is the **inverse** — it asserts a *confirmed delivery failure* (at least one gate whose
-`delivered === false`), for scenarios that deliberately exercise a non-delivery path. Unobserved delivery
-(`delivered: null`) satisfies neither — absence of evidence is a failure, not a pass.
+model, **passing vacuously when zero gates fired** (gate firing is model-dependent); `: false` is the
+**inverse** — it asserts a *confirmed delivery failure* (at least one gate whose `delivered === false`),
+for scenarios that deliberately exercise a non-delivery path. Unobserved delivery (`delivered: null`)
+satisfies neither — absence of evidence is a failure, not a pass. Pair `gate_answers_delivered: true`
+with `gate_answer_count_min: <N>` when a gate firing at all is part of what you're testing —
+`gate_answer_count_min` fails if fewer than N gates fired AND were delivered non-error.
 
 ### The O7 guard — `replay_protocol_fidelity`
 
@@ -337,8 +356,8 @@ regressing to the prior false-green behavior:
    ::warning:: [replay] cassette has no controlOut (pre-full-fidelity) — question/gate assertions
    are NOT checked; re-record to enable them
    ```
-2. **`question_asked`, `questions_count_max`, `gate_answers_delivered` are excluded** from the evaluated
-   assertion set for that run — not vacuously passed, absent.
+2. **`question_asked`, `questions_count_max`, `gate_answers_delivered`, `gate_answer_count_min` are
+   excluded** from the evaluated assertion set for that run — not vacuously passed, absent.
 3. All other content assertions (transcript, tool, subagent, result) evaluate normally.
 
 This preserves "skipped ≠ false-green." Re-record with a current harness to get the full-fidelity path.
@@ -477,10 +496,12 @@ counts) — committed PII surface. Two layers, distinct from secret-scrub (which
   live-enumerated app/process inventory sentinel (e.g. a computer-use tool schema's "Available applications on
   this machine: …") is never legitimate catalog boilerplate either; none of the three share the ambiguity that
   gets `currency`/`domain` excluded there. `--allow <regex>` suppresses synthetic / public reference names
-  (e.g. `NVCA`, `Cooley GO`, `Acme`); each allow must match the **whole** finding token (so a bare-domain allow
-  no longer silently clears an email whose domain it matches), and `--allow-domain` / `--allow-email` /
-  `--allow-path` / `--allow-machine-inventory` scope an allow to a single finding class, while `--allow-file
-  <path>` loads allows from a version-controlled file (one regex per line, `#` comments). Multi-word proper
+  (e.g. `NVCA`, `Cooley GO`, `Acme`) — each `--allow` value is a **pattern**, matched against a finding, not a
+  path to allow; each allow must match the **whole** finding token (so a bare-domain allow no longer silently
+  clears an email whose domain it matches), and `--allow-domain` / `--allow-email` / `--allow-path` /
+  `--allow-machine-inventory` scope an allow to a single finding class, while `--allow-patterns-file <path>` is a
+  different thing — it loads allows from a version-controlled **file of patterns** (one regex per line, `#`
+  comments), not a path to allow directly. Multi-word proper
   names are **not** a default class (too noisy). `verify-cassettes` also runs the **staleness**
   check (both checks run by default; scope to one with `--skip-privacy` or `--skip-staleness`): a drifted
   `skillHash` (you edited the skill but didn't re-record) fails the gate.

package/docs/scenario.md

@@ -277,9 +277,10 @@ if *every* key passes (don't rely on the first; keep one concern per item unless
 | `tool_calls_max: <N>` | total top-level tool calls (sum of `toolCounts`, sub-agent tools excluded) ≤ N — unlike the cost/token keys, this **is** meaningfully replay-checkable (the re-drive recomputes `toolCounts` deterministically from the recorded events) |
 | `max_turns: <N>` | the SDK-reported (or fallback-counted) turn count ≤ N — replay-checkable (the re-drive recounts turns deterministically, same as `tool_calls_max`) |
 | `question_asked: <regex>` | the agent asked an AskUserQuestion whose text matches |
-| `questions_count_max: <N>` | the agent asked at most N questions |
-| `gate_answers_delivered: true` | every answered AskUserQuestion gate's answer actually reached the model — requires a positive, observed `tool_result` (an **unobserved** delivery fails too, not only an errored one — no silent false-green) |
+| `questions_count_max: <N>` | at most N **sub-questions** asked — a bundled `AskUserQuestion` with K sub-questions counts as K, not 1 (this is a decision-load budget, not a per-tool-call count); `trace --view questions`'s footer total is computed the same way, so it always matches what this key compares against |
+| `gate_answers_delivered: true` | every answered AskUserQuestion gate's answer actually reached the model — requires a positive, observed `tool_result` (an **unobserved** delivery fails too, not only an errored one — no silent false-green); **zero gates fired passes vacuously** (gate firing is model-dependent) — pair with `gate_answer_count_min` to also require a gate |
 | `gate_answers_delivered: false` | asserts that at least one answered gate's answer was **confirmed not delivered** (an observed delivery failure); an unobserved/null delivery does **not** satisfy this — useful for negative-path tests of delivery failures |
+| `gate_answer_count_min: <N>` | at least N AskUserQuestion gates fired AND were delivered non-error — the presence companion to `gate_answers_delivered`'s vacuous-pass (mirrors `transcript_contains` pairing with `computer_links_resolve`) |
 | `allow_permissive_auto_allow: true` | verdict modifier — suppresses the default-fail when the run recorded a cowork-parity permissive auto-allow; use this for tests that **deliberately** assert Cowork's permissive behavior rather than strict scripted coverage |
 | `allow_missing_capability: true` | verdict modifier (**live tiers only**) — suppresses the default-fail when the lean/`core` agent image omits a capability the skill used but real Cowork ships (OCR/LibreOffice/markitdown/opencv/PDF-tables); assert only when the skill's fallback is genuinely equivalent, else rebuild full parity (`--build-arg COWORK_FULL_PARITY=1`). Also opts out of the `requires_capabilities` declared-need check below. |
 | `allow_l0_plugin_divergence: true` | verdict modifier — opts into L0/protocol plugin divergence, suppressing the plugin-fidelity default-fail |
@@ -380,10 +381,10 @@ and re-evaluates the **content** assertions. The authoritative list of content k
 `allow_l0_plugin_divergence` / `allow_stall` (kept on replay as no-op passes). `max_cost_usd`/`max_tokens`
 assert the *frozen recording's* spend on replay, not fresh spend — see their table entries above.
 
-**`question_asked`, `questions_count_max`, and `gate_answers_delivered`** are also content
-assertions, but they require the cassette to carry `controlOut` (full-fidelity replay). When
+**`question_asked`, `questions_count_max`, `gate_answers_delivered`, and `gate_answer_count_min`**
+are also content assertions, but they require the cassette to carry `controlOut` (full-fidelity replay). When
 `controlOut` is present, the decision pipeline runs on replay and populates `rec.questions` /
-`rec.gateDeliveries` — so these three keys are genuinely evaluated.
+`rec.gateDeliveries` — so these keys are genuinely evaluated.
 When `controlOut` is absent (old cassette), a **loud warning** fires and these keys are **excluded**
 from evaluation (not vacuously passed). Re-record with a current harness to enable them.
 
@@ -396,6 +397,15 @@ entry still satisfies `file_exists` but not `artifact_json`. `computer_links_res
 normalizes to a mount-relative path first (via the recorded connected-folder prefixes + the outputs/uploads
 mounts), since replay has no live filesystem to probe directly (that direct check only happens on a live
 `run`/`verify-run`). Without a manifest (older cassettes), all four are **skipped** (loud).
+
+A `mode: r` connected folder (see [session.md](./session.md)) holds pre-existing INPUTS, not deliverables —
+`record` captures its contents **body-less** (path + hash, `truncated: true`, no `body`): `file_exists` and
+`computer_links_resolve` still pass against it (the placeholder materializes on replay), while `artifact_json`
+against it reports a clear evidence-unavailable identically on live, verify-run, and replay (so a cassette
+can't record green and replay red). This keeps a read-only input out of the cassette's committed content
+(no bloat, no `binary` privacy finding) while `no_unexpected_files`/`computer_links_resolve` keep enumerating
+the folder as a user-visible root. A `mode: rw`/`rwd` folder's contents are captured with a full body, same
+as `outputs/`.
 A green `replay` re-confirms *record-time* artifacts, **not** that the current skill still produces them —
 that needs a live `run` (the cassette's staleness fingerprint warns when the skill/baseline drifted; `replay
 --strict` fails on any drift, `--fail-on-skill-drift` on skill-source drift only, and every result reports it

package/examples/replays/README.md

@@ -13,7 +13,7 @@ replay path end-to-end, including:
 
 Run it with:
 
-> Assumes the `cowork-harness` CLI is available — from a source checkout run `npm ci && npm run build && npm link` first, or `npm i -g cowork-harness@>=0.24.0`. (`replay` itself needs nothing else — no token, no Docker.)
+> Assumes the `cowork-harness` CLI is available — from a source checkout run `npm ci && npm run build && npm link` first, or `npm i -g cowork-harness@>=0.25.0`. (`replay` itself needs nothing else — no token, no Docker.)
 
 ```sh
 cowork-harness replay examples/replays/example-pdf-skill.cassette.json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-harness",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Scriptable, CI-friendly harness for Claude Cowork's runtime contract for testing skills across scenarios — same agent, mounts, egress allowlist, permission protocol, and sandbox limitations.",
   "license": "MIT",
   "type": "module",

package/schema/cassette.v7.json

@@ -54,6 +54,13 @@
       },
       "description": "v4+: the user-visible mount roots captured at record time (`outputs` + each connected folder's resolved mount name). Replay reads THIS instead of a hardcoded prefix. ABSENT on pre-v4 cassettes → replay falls back to the legacy prefix."
     },
+    "readonlyFolderRoots": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "The subset of `userVisibleRoots` that are read-only (`mode: r`) connected folders — captured body-less (path + hash, no body). Persisted so replay distinguishes a body-less read-only input from an over-cap artifact and gives the precise `artifact_json` remediation. Optional metadata (no cassetteVersion bump); ABSENT/empty ⇒ no read-only folder in the run. A subset of `userVisibleRoots` (no new privacy strings)."
+    },
     "preRunPaths": {
       "type": "array",
       "items": {

package/schema/scenario.schema.json

@@ -259,9 +259,15 @@
             "maximum": 9007199254740991
           },
           "gate_answers_delivered": {
-            "description": "every answered AskUserQuestion gate's tool_result was non-error (the answer reached the model)",
+            "description": "every answered AskUserQuestion gate's tool_result was non-error (the answer reached the model); zero gates fired passes vacuously — pair with gate_answer_count_min to also require a gate",
             "type": "boolean"
           },
+          "gate_answer_count_min": {
+            "description": "at least N AskUserQuestion gates fired AND were delivered non-error (presence companion to gate_answers_delivered)",
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991
+          },
           "result": {
             "description": "the run's final result was success | error",
             "type": "string",