cowork-harness 0.23.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.23.0
-  tracks-harness: cowork-harness 0.23.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.23.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.23.0**. If it's missing or older, prefix every command with the version floor `npx "cowork-harness@>=0.23.0" <cmd>` (Node ≥ 20), or install once with `npm i -g "cowork-harness@>=0.23.0"`. **Pin `@>=0.23.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.23.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`).
@@ -288,10 +288,14 @@ cowork-harness lint scenarios/*.yaml
 ```
 
 `lint` flags: filesystem/egress-only assertions on a `replay` gate (silent no-op), bad regex
-quoting, an egress assert on `protocol` fidelity, a `controlOut`-gated key on a non-`controlOut`
-replay, mixed-class assertion items, and hallucinated schema (`assertions:` vs `assert:`, unknown
-keys). Exit code is non-zero on errors (CI-friendly). `scaffold` auto-upgrades the tier if you ask
-for egress on `protocol`, so it never emits a scenario `lint` would reject.
+quoting, an egress assert on `protocol` fidelity, `transcript_no_host_path` on `hostloop`/`protocol`
+(ERROR — fails by design at those tiers; WARN on `fidelity: cowork`, whose tier resolves per the
+baseline's host-loop gate), non-empty `requires_capabilities` on `protocol` without
+`allow_missing_capability` (ERROR — the capability probe can't run there, so the run hard-fails as
+unverifiable), a `controlOut`-gated key on a non-`controlOut` replay, mixed-class assertion items,
+and hallucinated schema (`assertions:` vs `assert:`, unknown keys). Exit code is non-zero on errors
+(CI-friendly). `scaffold` auto-upgrades the tier if you ask for egress on `protocol`, so it never
+emits a scenario `lint` would reject.
 
 CI placement: a **token-free `replay` PR gate** (content/structure only) + a **nightly live `run`**
 (filesystem/egress). Fastest setup: `uses: yaniv-golan/cowork-harness@v1` (a packaged GitHub Action with a
@@ -362,9 +366,12 @@ are the ones that bite hardest.
    sub-agent used other tools. And `subagent_dispatched` matches by dispatch **description** too —
    skills often dispatch with no `subagent_type` (`agentType:"unknown"`), so match the description.
 
-6. **`dispatch_count_max` asserts but does NOT enforce.** The harness records the count; it does not
-   reproduce Cowork's skip-on-cap (`{perTask:1, global:3}`, deferred). Passing means "happened to
-   dispatch ≤N this run," not "the harness capped it." Don't read enforcement into the assert.
+6. **`dispatch_count_max` is an author-chosen budget, not a production cap.** It's a post-hoc count
+   assertion: passing means "happened to dispatch ≤N this run," nothing more. Cowork imposes **no**
+   in-conversation `Task`-dispatch cap — gate `1648655587`'s `{perTask:1, global:3}` governs the
+   separate scheduled/cron-task session scheduler, not the `Task` tool (binary-verified; see SPEC
+   §10). So there is no "skip-on-cap" for the harness to reproduce; use this key only to catch a
+   fan-out you don't want.
 
 7. **`protocol` is rejected (not silently passed) if the scenario asserts egress** — boundary
    assertions need a sandboxed tier (`container`+). Good: this one fails loud by design.
@@ -451,11 +458,36 @@ 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/`.
 
 ## References
 
+- `references/task-recipes.md` — end-to-end recipes for the four jobs fleet owners actually hit:
+  evolve a cassette's `assert:` (usually no re-record), audit a fleet for tier drift, set up
+  redaction before the first hostloop/protocol record, derive budget assertions without a
+  two-pass record. Start here when the question is "how do I do X", not "what does flag Y mean".
 - `references/scenario-schema.md` — scenario/session YAML schema, full assertion catalog (with each
   key's replay class), the web_fetch model, and the complete gotcha list.
 - `references/fidelity-and-answers.md` — fidelity tiers, answer paths, the determinism contract.

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.23.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.23.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
@@ -125,9 +125,17 @@ dollar figures). In a skill repo these cassettes get **committed**. So:
   customer's cap table.
 - **Opt-in redaction** rewrites configured PII out of the cassette at record time. Drop a
   `.cowork-redact.json` next to your scenarios (or set `COWORK_HARNESS_REDACT_PATTERNS` /
-  `_KEYS`); empty by default. Redaction is **verdict-preserving** — `record` refuses to write if
+  `_KEYS`); empty by default. The policy is searched in **cwd → the scenario's dir → the cassette's
+  dir** (first file found per dir; env vars merge on top). `cowork-harness init-redact` copies the
+  packaged reference template (local-path prefixes + a generic email regex) into the cwd as a starting
+  point — review and tailor it. Redaction is **verdict-preserving** — `record` refuses to write if
   redaction would flip an assertion (a manufactured green). `--no-redact` skips it for known-synthetic
   inputs.
+- **Pre-spawn preflight**: `record` warns (`::warning::`, before the paid run starts — once per batch
+  for `record <dir>` / `--rerecord-stale`) when a scenario about to record at a host-path-bearing tier
+  (`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).
 - **Always-on scan gate** — `verify-cassettes` flags email / currency / bare-domain / local-path /
   machine-inventory matches it finds in the committed cassettes and **exits non-zero**, so "no leak" is
   a gate, not discipline.
@@ -179,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.23.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
@@ -208,7 +216,7 @@ jobs:
             echo "live=true" >> "$GITHUB_OUTPUT"
           fi
       - if: steps.guard.outputs.live == 'true'
-        run: npm i -g "cowork-harness@>=0.23.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:
@@ -235,6 +243,11 @@ scenario = `result === "success" && assertions.every(pass)`. Exit code is non-ze
 fails or a run errors, so a plain `cowork-harness run scenarios/` is already CI-ready without parsing
 JSON.
 
+`verify-cassettes` emits its **own** envelope (`{command, ok, coverage, results[]}` with per-file
+`findings`/`staleness`/`notes`/`version`/`error`), published as `schema/verify-cassettes.json` in the
+npm package. Both envelope schemas are covered 1.0 contract surfaces (SPEC §12) — parse the JSON, not
+the human-readable text (which is explicitly NOT stable).
+
 A run writes to `~/.cowork-harness/runs/<name>/<sessionId>/` by default — outside any working tree. In CI,
 set `COWORK_HARNESS_RUNS_DIR` (or pass `--run-dir`) to a workspace-relative path (e.g. `runs`) so an
 artifact-upload step can collect them. Each run dir holds `events.jsonl`, `control-out.jsonl`, `run.jsonl`,
@@ -261,6 +274,13 @@ does **not** imply the recording is still valid. Each replay result carries `sta
 | `format` | recorded under an older hash format | re-record once |
 | `unverifiable-baseline` | the latest baseline couldn't be loaded | couldn't verify (env, not skill) |
 | `unverifiable-skill` | skill dirs unresolvable — skill staleness couldn't be checked | couldn't verify the skill |
+| `resolved-tier` | a `fidelity: cowork` cassette's recorded `effectiveFidelity` no longer matches what the baseline resolves to today (the host-loop gate flipped) | **high** (the recording exercises the wrong tier) |
+| `unverifiable-tier` | tier check couldn't run for a `fidelity: cowork` cassette (no recorded `effectiveFidelity`, or its pinned baseline failed to load) | couldn't verify the tier — re-record |
+
+(A pre-`effectiveFidelity` cassette with an **explicit** tier is statically knowable — it passes the tier
+check with a non-failing informational note in the `verify-cassettes` envelope's per-file `notes[]`, a
+`·`-prefixed row in text output. On `verify-cassettes` every staleness *finding* above is a hard fail —
+the gate is class-blind; notes never fail it.)
 
 To gate in CI, pick the severity you want:
 

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.23.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.23.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`.
 
@@ -219,6 +219,7 @@ passes only if every key passes. Keep one concern per item unless you mean conju
 | `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) |
+| `no_unexpected_files: [<glob>, …]` | every **newly created** file under a user-visible root matches ≥1 glob (workRoot-relative paths; `**` = whole path segment for any depth — use `outputs/handoff/**` for per-run subdirs); `[]` = no new files; **new-files-only** — overwriting a pre-existing file in place is invisible (use content-level producer stamping); live/verify-run without a pre-run manifest ⇒ evidence-unavailable hard-fail (live runs capture the baseline only when this key is asserted; recordings always capture); **microvm cannot capture** (use container/hostloop); replay needs `cassette.preRunPaths` (≥0.24 container/hostloop recordings) — cassettes without it **exclude** the key with a loud warning |
 | `self_heal_ran: <bool>` | a plugin-root self-heal script was (not) invoked |
 | `tool_called: <Tool>` | the agent invoked the tool (actually ran it) |
 | `tool_not_called: <Tool>` | the agent never invoked it |
@@ -228,7 +229,7 @@ passes only if every key passes. Keep one concern per item unless you mean conju
 | `subagent_tool_absent: <Tool>` | no sub-agent used the tool |
 | `subagent_dispatched: <regex>` | a sub-agent whose `agentType` **or dispatch description** matches |
 | `subagent_declared_but_unused: <Tool>` | a sub-agent declared the tool but never used **that** tool (even if it used others) |
-| `dispatch_count_max: <N>` | at most N sub-agents dispatched (records only — does NOT enforce a cap) |
+| `dispatch_count_max: <N>` | at most N sub-agents dispatched — an author-chosen budget (Cowork imposes no in-conversation Task-dispatch cap; records only, enforces nothing — see gotcha 12) |
 | `skill_triggered: <regex>` | a skill matching the regex (invoked id, e.g. `"plugin:skill"`) was invoked via the `Skill` tool — evidence-unavailable (not a normal fail) if the agent's init tools have no `Skill` tool |
 | `no_skill_triggered: <regex>` | no invoked skill id matched — the negative-control / description-collision catcher; evidence-unavailable (never a vacuous pass) if invocation data is absent or the `Skill` tool is unobservable |
 | `max_cost_usd: <N>` | the run's SDK-reported cost is ≤ N USD — evidence-unavailable if cost telemetry is absent. **Replay asserts the frozen recording's cost, not fresh spend** — a real regression needs a live `run` |
@@ -236,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 |
@@ -292,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
@@ -302,7 +306,9 @@ small-file JSON `body` inlined; a hash-only entry still satisfies `file_exists`.
 resolves a `/sessions/…/mnt/…`-shaped link directly against the manifest, and a host-shaped (hostloop) link
 by first normalizing it to a mount-relative path (recorded connected-folder prefixes + the outputs/uploads
 mounts) — replay has no live filesystem to check a host path against directly (that only happens on a live
-`run`/`verify-run`). Without a manifest (older cassettes) all four are skipped. A green replay re-confirms
+`run`/`verify-run`). Without a manifest (older cassettes) all five are skipped; `no_unexpected_files` also
+needs `preRunPaths` (≥0.24 recordings) — without it the key is excluded with a loud warning (live/verify-run
+hard-fails evidence-unavailable instead). A green replay re-confirms
 *record-time* artifacts, not that the current skill still produces them — `replay --strict` fails when the
 staleness `fingerprint` shows ANY skill/baseline drift, or `replay --fail-on-skill-drift` only on
 skill-source drift; every replay result also reports it class-tagged in `staleness[]` for a JSON gate.
@@ -371,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;
@@ -410,9 +418,11 @@ at the top of this file.
 11. **`subagent_declared_but_unused` fires on declared-but-didn't-use-THAT-tool**, even if the
     sub-agent used other tools.
 
-12. **`dispatch_count_max` asserts but does NOT enforce.** It records the count; it does not
-    reproduce Cowork's skip-on-cap (`{perTask:1, global:3}`, deferred). Passing means "dispatched ≤N
-    this run," not "the harness capped it."
+12. **`dispatch_count_max` is an author-chosen budget, not a production cap.** It records the count
+    and asserts on it; passing means "dispatched ≤N this run," not "the harness capped it." Cowork
+    imposes no in-conversation Task-dispatch cap to reproduce — gate `1648655587`'s
+    `{perTask:1, global:3}` is the scheduled/cron-task session limiter, a different mechanism
+    (binary-verified; SPEC §10).
 
 13. **`protocol` is rejected (not silently passed) if the scenario asserts egress** — boundary
     assertions need `container`+. Fails loud by design.
@@ -450,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

@@ -0,0 +1,110 @@
+# Task recipes — end-to-end paths for the four jobs consumers actually reverse-engineer
+
+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. Facts track the harness version in SKILL.md's
+front-matter; the `resolved-tier`/`unverifiable-tier` staleness classes (Recipe 2) and
+`init-redact` (Recipe 3) are new in the release AFTER 0.23.0.
+
+## Recipe 1 — Evolve the `assert:` block of an existing cassette (usually NO re-record)
+
+You added or changed assertion keys in a scenario whose cassette is already committed. Do you need
+a paid live re-record? Walk this tree — the answer is usually no:
+
+1. **Content / always-replay keys** (`transcript_*`, `tool_called`/`tool_not_called`,
+   `tool_result_*`, `subagent_*`, `dispatch_count_max`, `skill_triggered`/`no_skill_triggered`,
+   `result`, `max_turns`, `tool_calls_max`, `max_cost_usd`, `max_tokens`) →
+   `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`, `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.
+4. **Filesystem / egress keys** (`file_exists` without an artifact manifest, `egress_allowed`,
+   `egress_denied`, `no_delete_in_outputs`) → live lane **by design**; replay skips them with a
+   loud `::warning::`. Keep them in the scenario, run them on the nightly live gate.
+
+**The one hard caveat:** `--assert-from` **hard-fails on recording-shaping drift** — if the
+scenario's `prompt:`, `answers:`, baseline, or skill content differ from what shaped the
+recording, re-asserting under them is meaningless and the harness refuses. The trap you'll
+actually hit is `answers:`: sequence your edits — land assert-only changes (token-free), and land
+answer changes separately (those DO force a re-record).
+
+## Recipe 2 — Audit a fleet for tier drift
+
+A `fidelity: cowork` scenario records at whatever tier the baseline's host-loop gate resolves to
+at record time. When Cowork flips that gate, your committed cassettes silently stop representing
+what production would do. Two layers of defense:
+
+- **Automated (preferred):** `cowork-harness verify-cassettes <dir>` raises a
+  **`resolved-tier`** staleness finding when a `fidelity: cowork` cassette's recorded
+  `effectiveFidelity` no longer matches what the current baseline resolves to, and
+  **`unverifiable-tier`** when a `fidelity: cowork` cassette predates `effectiveFidelity`
+  entirely (can't verify → re-record). Explicit-tier cassettes (`hostloop`, `container`, …) are
+  statically knowable and only produce a non-failing informational note.
+- **Manual (one-liner):** `grep -h '"effectiveFidelity"' cassettes/*.cassette.json | sort | uniq -c`
+  shows the tier distribution of the fleet at a glance.
+
+### Cassette anatomy (what you're looking at when you open one)
+
+Top-level fields of a `*.cassette.json` (schema `schema/cassette.v7.json`):
+
+| Field | What it is |
+|---|---|
+| `$schema`, `generator`, `cassetteVersion` | Provenance: schema URL, producing tool, format version (current: 7) |
+| `scenario` | The embedded scenario snapshot at record time |
+| `events` | The recorded agent event stream (the replay source) |
+| `controlOut` | Driver→agent control responses — presence unlocks gate asserts on replay |
+| `effectiveFidelity` | The tier the live record actually resolved to (the drift-audit key above) |
+| `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`) |
+
+## Recipe 3 — Set up redaction BEFORE your first hostloop/protocol record
+
+`hostloop` and `protocol` runs execute on the host, so real host paths (`/Users/you/…`) land in
+the transcript and would be committed inside the cassette. Set the policy up **before** the first
+record — retrofitting means re-recording:
+
+1. `cowork-harness init-redact` — copies the reference `.cowork-redact.json` (host-path +
+   email patterns) into the current directory. Version-control it.
+2. **Search set:** record looks for `.cowork-redact.json` in the **cwd, the scenario's directory,
+   and the cassette's output directory** — every distinct file found is MERGED (plus
+   `COWORK_HARNESS_REDACT_PATTERNS`/`_KEYS` from the env). Repo root (= cwd in CI) is the
+   conventional home.
+3. **Preflight backstop:** `record` on a host-path-bearing tier with NO effective policy emits a
+   loud pre-spawn `::warning::` (once per batch). If you see it, stop and do step 1.
+4. **Scanner relationship:** redaction (record-time, rewrites content) and the
+   `verify-cassettes` privacy scanner (CI-time, read-only tripwire over 4 classes: `domain`,
+   `email`, `path`, `machine-inventory`) are independent layers. The scanner catches what
+   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 <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
+
+`max_turns` / `tool_calls_max` / `questions_count_max` / `dispatch_count_max` need observed
+values, but you don't need a second paid run to get them — derive them from evidence you already
+have:
+
+1. **From the run you already did:** `run` always keeps its run dir. Read observed turns from
+   `result.json` (`usage.turns`), tool-call and question counts from
+   `cowork-harness trace <run-id> --view tools` / `--view questions`, and the dispatch count from
+   `--view dispatches`.
+2. **From history:** `cowork-harness stats <scenario> --metric turns` gives p50/p95 turns across
+   indexed runs — better than a single observation.
+3. **Set the budget with headroom:** observed × 1.5, rounded up (agentic run lengths vary run to
+   run; a budget at the observed value flakes).
+4. **Replay-class note:** `max_turns` / `tool_calls_max` / `dispatch_count_max` re-evaluate
+   token-free on replay; `questions_count_max` needs `controlOut` (Recipe 1's tree applies).
+   `max_cost_usd` / `max_tokens` on replay assert the FROZEN recording's spend — near-zero signal
+   as a regression gate; if you need a cost gate, put it on the live lane via `stats`.

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

@@ -11,12 +11,14 @@
     "egress_allowed",
     "egress_denied",
     "file_exists",
+    "gate_answer_count_min",
     "gate_answers_delivered",
     "max_cost_usd",
     "max_tokens",
     "max_turns",
     "no_delete_in_outputs",
     "no_skill_triggered",
+    "no_unexpected_files",
     "question_asked",
     "questions_count_max",
     "replay_protocol_fidelity",

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

@@ -16,9 +16,14 @@ Two subcommands:
 
 lint flags (see references/scenario-schema.md for the why of each):
   E  egress assertion on `fidelity: protocol`        (the harness rejects this run)
+  E  `transcript_no_host_path` on hostloop/protocol  (fails BY DESIGN at those tiers)
+  E  `requires_capabilities` on `fidelity: protocol` (probe can't run → hard-fails
+                                                      unless allow_missing_capability)
   E  on_unanswered: agent / invalid value            (schema rejects `agent`)
   E  authored `replay_protocol_fidelity` assertion   (replay-synthesized only)
   E  `assertions:` instead of `assert:`              (block ignored → every check no-ops)
+  W  `transcript_no_host_path` on `fidelity: cowork` (tier resolves per baseline gate —
+                                                      incompatible if it lands hostloop)
   W  no content assertion → no-op on a replay gate    (every assertion is fs/egress)
   W  mixed-class assert item → fs/egress half dropped on replay
   W  unknown top-level / assertion key                (typo or hallucinated schema)
@@ -67,12 +72,12 @@ 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
 # either a live filesystem or the cassette's artifacts manifest — see cassette.ts's manifestKeys comment.
-MANIFEST_KEYS = {"file_exists", "user_visible_artifact", "artifact_json", "computer_links_resolve"}
+MANIFEST_KEYS = {"file_exists", "user_visible_artifact", "artifact_json", "computer_links_resolve", "no_unexpected_files"}
 # live-only: ALWAYS skipped on replay, with a loud warning (no filesystem, no network on the token-free lane)
 LIVE_ONLY_KEYS = {
     "egress_denied",
@@ -139,7 +144,7 @@ _EMBEDDED_TOP_LEVEL_KEYS = {
     "answers",
     "expect_denied",
     "assert",
-    "skills",  # F-6: opt-in skill-staleness hash scope
+    "skills",  # opt-in skill-staleness hash scope
     "requires_capabilities",  # Fix 4b: scenario-level required-capability declaration (pre-flight gate)
     "allow_host_writes",  # hostloop native-split: consent for a writable connected folder (pre-run gate)
 }
@@ -177,6 +182,13 @@ REGEX_KEYS = {
 VALID_ON_UNANSWERED = {"fail", "prompt", "first", "llm"}
 VALID_TIERS = ("protocol", "container", "microvm", "hostloop", "cowork")
 
+# Gate-id tripwire: the `host-path-assert-cowork` WARN below embeds Cowork's
+# host-loop gate id in offline Python (the linter never reads a baseline). The
+# id is pinned by test/scenario-lint-gate-id.test.ts against the PINNED_GATES
+# entry in src/sync/cowork-sync.ts, so a Desktop gate re-key fails loud there
+# instead of silently rotting this message.
+HOST_LOOP_GATE_ID = "1143815894"
+
 
 class Finding:
     __slots__ = ("severity", "rule", "message", "fix", "file", "line")
@@ -300,6 +312,60 @@ def lint_doc(doc, path, raw_lines):
             )
         )
 
+    # E/W: transcript_no_host_path is tier-incompatible with hostloop/protocol — the agent
+    # legitimately runs on real host paths there, so the assertion fails BY DESIGN (the runtime only
+    # warns at run start, after authoring). Lint is deliberately STRICTER than the runtime: the docs
+    # declare the combination incompatible, so authoring it is a bug even if a tool-free run could
+    # accidentally pass. `cowork` gets a WARN naming the baseline-gate resolution dependency (the
+    # linter stays offline — the message carries the gate fact instead of reading a baseline).
+    if "transcript_no_host_path" in assert_keys:
+        if fidelity in ("hostloop", "protocol"):
+            findings.append(
+                Finding(
+                    "ERROR",
+                    "host-path-assert-tier",
+                    f"`transcript_no_host_path` on `fidelity: {fidelity}` — the agent runs on real "
+                    "host paths at this tier, so this assertion FAILS BY DESIGN (it can never be a "
+                    "meaningful check here).",
+                    "Run this assertion at fidelity: container (or microvm), or drop it for this tier.",
+                    path,
+                )
+            )
+        elif fidelity == "cowork":
+            findings.append(
+                Finding(
+                    "WARN",
+                    "host-path-assert-cowork",
+                    "`transcript_no_host_path` on `fidelity: cowork` — the tier resolves per the "
+                    f"baseline's host-loop gate ({HOST_LOOP_GATE_ID}); if it resolves to hostloop "
+                    "this assertion fails by design (and a later gate flip re-stales the cassette).",
+                    "Pin fidelity: container if the assertion is load-bearing; keep cowork only if "
+                    "you accept the gate-resolution dependency.",
+                    path,
+                )
+            )
+
+    # E: requires_capabilities on protocol — the capability probe cannot run at protocol tier
+    # (clause b of the requires_capabilities contract), so the run HARD-FAILS unless an assert item
+    # opts out via allow_missing_capability: true. Offline-detectable fails-by-design, same class as
+    # the tier/assert rules above.
+    req_caps = doc.get("requires_capabilities")
+    if req_caps and fidelity == "protocol":
+        opted_out = any(item.get("allow_missing_capability") is True for item in items)
+        if not opted_out:
+            findings.append(
+                Finding(
+                    "ERROR",
+                    "capabilities-on-protocol",
+                    "non-empty `requires_capabilities` on `fidelity: protocol` — the capability "
+                    "probe cannot run at protocol tier, so the run hard-fails as unverifiable "
+                    "(fails by design).",
+                    "Use a sandboxed tier (container/microvm/hostloop), or add "
+                    "`allow_missing_capability: true` to an assert item to opt out explicitly.",
+                    path,
+                )
+            )
+
     # E: retired/invalid on_unanswered
     ou = doc.get("on_unanswered")
     if ou is not None and ou not in VALID_ON_UNANSWERED:
@@ -543,7 +609,7 @@ def cmd_lint(args):
         else:
             expanded.append(arg)
     args.files = expanded
-    # Linter self-check (B3): a valid schema key the replay-class sets don't classify can't be linted
+    # Linter self-check: a valid schema key the replay-class sets don't classify can't be linted
     # correctly — surface it as a hard ERROR so it fails the gate (and --strict) until someone classifies it.
     if UNCLASSIFIED_KEYS:
         all_findings.append(
@@ -650,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/.cowork-redact.json

@@ -0,0 +1,11 @@
+{
+  "patterns": [
+    { "regex": "/Users/[^\\s\"'\\\\)\\]`]+?(?=/mnt/)", "label": "local-path", "flags": "g" },
+    { "regex": "/home/[^\\s\"'\\\\)\\]`]+?(?=/mnt/)", "label": "local-path", "flags": "g" },
+    { "regex": "/root/[^\\s\"'\\\\)\\]`]+?(?=/mnt/)", "label": "local-path", "flags": "g" },
+    { "regex": "/Users/[^\\s\"'\\\\)\\]`]+", "label": "local-path", "flags": "g" },
+    { "regex": "/home/[^\\s\"'\\\\)\\]`]+", "label": "local-path", "flags": "g" },
+    { "regex": "/root/[^\\s\"'\\\\)\\]`]+", "label": "local-path", "flags": "g" },
+    { "regex": "[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}", "label": "email", "flags": "g" }
+  ]
+}