cowork-harness 0.23.0 → 0.24.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.24.0
+  tracks-harness: cowork-harness 0.24.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.24.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.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).)
 - **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.
@@ -456,6 +463,10 @@ 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.24.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.24.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.24.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.24.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.24.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.24.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` |
@@ -302,7 +303,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.
@@ -410,9 +413,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.

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

@@ -0,0 +1,108 @@
+# 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 |
+| `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` (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.
+
+## 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

@@ -17,6 +17,7 @@
     "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)
@@ -72,7 +77,7 @@ GATE_KEYS = {"question_asked", "questions_count_max", "gate_answers_delivered"}
 # 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(

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" }
+  ]
+}

package/CHANGELOG.md

@@ -6,6 +6,134 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.24.0] — 2026-07-05
+
+### Added
+
+- **`no_unexpected_files` assertion** — per-scenario glob allowlist over **newly created** files under the
+  user-visible roots (workRoot-relative paths; `**` matches any depth). Post-hoc stray-file / fabricated-
+  artifact detection for the founder-skills hand-off contract (consumer ask, 2026-07-04); pairs with their
+  script-side `_produced_by` / `UNVALIDATED_ARTIFACT` check for overwrite-in-place bypasses this key cannot
+  see. Records a pre-run path baseline (`preRunPaths` on the cassette + `pre-run-manifest.json` on kept runs;
+  optional field, no cassetteVersion bump). **Live/verify-run** without a baseline ⇒ evidence-unavailable
+  hard-fail; **replay** without `preRunPaths` ⇒ loud exclude (pre-0.24 cassettes). **Microvm** does not
+  capture (existing artifact-tree gap) — use container/hostloop. Live runs capture the baseline when the
+  scenario asserts the key; recordings always capture it, so a later assert-add replays without re-record.
+
+- **Two new documented fidelity gaps: guest runtime identity and session-slug shape.**
+  Runtime forensics over a local install's Cowork VM disk images (coworkd's own logs) established
+  that production provisions a **dedicated Unix user per session** inside the VM (`useradd`,
+  name = session slug, uid=gid sequential ≥1014, `HOME=/sessions/<slug>`) and spawns the agent and
+  every bash call as that user via `oneshot-<uuid>` supervisor jobs — where the harness's
+  container/microvm tiers run static uid-1000 `ubuntu` with `HOME=/tmp`. Production's in-VM slugs
+  are Docker-style name triples (`beautiful-bold-planck`), not the harness's `local_<hrtime36>`;
+  the `local_<uuid>` shape exists in production only as Desktop's host-side session-record
+  filenames. Both are recorded in `docs/fidelity-gaps.md` with observable consequences (`whoami`,
+  `id -u`, `~`-relative writes, cwd shape); the `Dockerfile.agent` uid-1000 comment no longer
+  claims runtime parity. Initial lead credit: the founder-skills project's journald forensics,
+  independently re-verified here against this machine's own VM images before documenting.
+
+- **The `verify-cassettes` JSON envelope is now a published, 1.0-covered contract surface.**
+  SPEC §12's covered list previously named the RunResult envelope but was silent on §11.1's
+  `verify-cassettes` envelope — even though the CI recipe and the packaged GitHub Action steer
+  consumers to parse exactly that output, and an uncovered machine-output shape can rot a consumer's
+  `jq` gate silently (a renamed key yields `null`, and the gate stops gating). The envelope is now:
+  listed in §12 (rename/removal = MAJOR; additive growth stays MINOR), published as
+  `schema/verify-cassettes.json` in the npm package, and pinned by
+  `test/verify-envelope-schema.test.ts`, which validates real CLI output against the schema in both
+  directions (a required key the CLI stops emitting fails, and — via a strictened copy — a key the
+  CLI starts emitting without a schema update also fails). Writing the schema immediately caught one
+  doc drift: the per-file `version[]` channel (newer-harness cassette → hard fail) was emitted but
+  missing from §11.1's envelope block; the SPEC block, `ok` formula, and exit-code line now include it.
+
+- **Skill-effectiveness workstream.** Three deliverables, all targeting the same failure mode
+  observed in real skill adoption: the facts existed across the docs, but nothing composed them
+  into the task a scenario author actually faces:
+  - **`references/task-recipes.md`** — four end-to-end recipes that consumers previously had to
+    reverse-engineer from scattered reference docs: evolve a cassette's `assert:` block (usually token-free via
+    `replay --assert-from`; the recording-shaping-drift caveat spelled out), audit a fleet for tier
+    drift (`effectiveFidelity` + the new `resolved-tier`/`unverifiable-tier` classes + a cassette
+    anatomy table), set up redaction before the first hostloop/protocol record (`init-redact`,
+    search set, scanner relationship, `--allow-*` scoping idioms), and derive budget assertions
+    from an existing run instead of a two-pass record.
+  - **Four new eval cases** (`evals/evals.json` 5 → 9, ids 6–9), each a question a real consumer
+    hit, passing iff the agent reaches the cheap path: assert evolution without a
+    fleet re-record, reading a cassette's recorded tier (with a fixture cassette via `files[]`),
+    the exact `--allow-file` format (and its all-class scope trade-off), and batch `record`
+    atomicity semantics.
+  - **Doc-drift tripwire** (`test/skill-docs-sync.test.ts`), scoped to the kinds of drift that
+    actually happened (NOT a naive new-CLI-flag gate, which would have caught neither motivating
+    example): extends the `cassette-docs-sync` pattern to pin the skill's assertion catalog against
+    `schema/scenario.schema.json` and the skill docs against the current cassette schema's
+    top-level field list. Plus a CONTRIBUTING checklist line for consumer-visible workflow changes.
+
+### Fixed
+
+- **Gate `1648655587` was mislabeled as a Task-dispatch cap; it is the scheduled-task session
+  limiter.** A binary-verified forensic pass (asar 1.18286.0, `class L9t "[ScheduledTasks]"`) plus one
+  adversarial-review round established that gate `1648655587` (`{perTask:1, global:3}`) governs
+  Cowork's **scheduled/recurring (cron) task** session scheduler — ≤1 concurrent session per
+  scheduled task, ≤3 concurrent scheduled-task sessions globally — **not** the in-conversation
+  `Task` tool. The Desktop imposes **no** cap on `Task`-tool sub-agent fan-out at all (the `Task`
+  PreToolUse hook only blocks `run_in_background`). SPEC §10, `docs/fidelity-gaps.md`,
+  `docs/scenario.md`, the skill (SKILL.md gotcha 6 + `references/scenario-schema.md`), the
+  1.18286.0 baseline gate note, and `dispatch_count_max`'s failure message are all corrected;
+  `dispatch_count_max` is now described as an author-chosen budget assertion, not enforcement of a
+  (non-existent) production Task cap. The `PINNED_GATES` rename
+  (`taskDispatchLimiter → scheduledTaskSessionLimiter`) also landed, regenerated through `sync`
+  against the same Desktop 1.18286.0 install (never hand-edited): the 1.18286.0 baseline now
+  carries the corrected gate key, older baselines keep the historical label, and the sync
+  gate-merge now matches previous entries by gate **id** (not exact `name:id` key) so a rename
+  carries the note/state across and can't resurrect the old key as a stale duplicate. This
+  supersedes the earlier "faithful Task-dispatch runtime limiter is planned" language — there is
+  no production behavior to mirror.
+
+- **`schema/cassette.v7.json` was missing `userVisibleRoots` and `scenarioSource`** — both fields
+  are written by `record` (since format v4 / 0.8.0 and 0.20.0 respectively); `userVisibleRoots` was
+  even named in the schema's prose `description` while absent from `properties`. Found by the new
+  skill-docs tripwire while pinning the field list.
+
+- **Redaction preflight + `init-redact`.**
+  `record` now warns (`::warning::`) **before the agent spawns** when a scenario about to record at a
+  host-path-bearing tier (`hostloop`, or `protocol`) has an EMPTY assembled redaction policy — that
+  combination commits real host paths, which `verify-cassettes`' `path` scanner then hard-fails; the
+  empty-policy discovery used to happen only at the post-run policy load, after the run was paid for.
+  Batch `record <dir>` and `--rerecord-stale` preflight ONCE for the whole batch, before the first
+  spawn (never N interleaved duplicates). A malformed `.cowork-redact.json` now also fails pre-spawn.
+  The reference `.cowork-redact.json` (generic local-path prefixes + email regex) now ships in the npm
+  package, and the new `cowork-harness init-redact [--force]` copies it into the cwd — the copy is
+  load-bearing, since the policy search set (now documented in `docs/cassette.md` and the skill's
+  ci-recipe) is cwd → scenario dir → cassette dir (+ `COWORK_HARNESS_REDACT_*` env), never the package
+  dir. The always-on privacy scanner remains the universal net — container-tier recordings can trip it
+  too.
+
+- **Lint catches fidelity/assert combinations that fail by design.**
+  `scenario.py lint` (and the `cowork-harness lint` wrapper) now ERRORs on
+  `transcript_no_host_path` + `fidelity: hostloop` or `protocol` (the agent legitimately runs on real
+  host paths at those tiers — the assertion can never be a meaningful check there; lint is
+  deliberately stricter than the runtime's run-start warning), WARNs on `transcript_no_host_path` +
+  `fidelity: cowork` naming the host-loop gate-resolution dependency (the linter stays offline — the
+  message carries gate id `1143815894` instead of reading a baseline, pinned against the
+  `cowork-sync.ts` gate table by a sync test so a Desktop re-key can't rot it), and ERRORs on
+  non-empty `requires_capabilities` + `fidelity: protocol` without `allow_missing_capability` (the
+  capability probe can't run at protocol tier, so the run hard-fails as unverifiable).
+
+- **Resolved-tier staleness detection.** A
+  `fidelity: cowork` cassette records the tier the loop-decision gate resolved to
+  (`effectiveFidelity`); `verify-cassettes` / `replay` now detect when the current baseline resolves
+  that scenario differently (gate `1143815894` flipped since record) and emit a new `resolved-tier`
+  staleness finding — the recording exercises the wrong tier. Resolution is baseline-only (the
+  scenario's pinned `baseline:` when present, else `latest`; the `CLAUDE_FORCE_HOST_LOOP` env override
+  is suppressed) so verify results can't differ across machines. A `cowork` cassette whose tier can't
+  be verified (predates `effectiveFidelity`, or its pinned baseline fails to load) gets a loud
+  `unverifiable-tier` finding — never a silent skip, never an aborted sweep. Both classes hard-fail
+  `verify-cassettes` (class-blind gate) and warn-by-default on `replay` (`--strict` escalates;
+  `--fail-on-skill-drift` ignores them — they are not skill-source drift). A pre-`effectiveFidelity`
+  cassette with an *explicit* tier is statically knowable: it passes with a non-failing informational
+  note in the new per-file `notes[]` of the `verify-cassettes` envelope (a `·` row in text output).
+  `schema/run-result.json` now also declares `staleness` (full class enum) and `skippedAssertions`,
+  closing a pre-existing gap vs SPEC §11.
+
 ## [0.23.0] — 2026-07-04
 
 ### Added

package/CONTRIBUTING.md

@@ -66,6 +66,7 @@ Paths inside a scenario/session resolve relative to that file (see [docs/session
 - **Don't weaken the boundary.** Changes to `runtime/container.ts` or `docker/compose.yml` must keep the default-deny network + sealed FS. Run `cowork-harness boundary-check` and add/adjust a probe in `src/boundary.ts` if you change the model.
 - **Mark unverified code.** Anything not yet run end-to-end against a live agent gets a `// UNVERIFIED` comment so reviewers know.
 - **Add a test.** New schema fields, `Decider` rules, or egress logic need a unit test in `test/`. Examples must validate (`test/examples.test.ts`).
+- **Consumer-visible workflow changes update the skill.** A change a scenario author would act on — a new assertion key, cassette field, CLI command, or a changed record/replay/verify workflow — must land with a matching update to `.claude/skills/cowork-harness/` (SKILL.md or `references/`). The machine-checkable slices are enforced (`test/skill-docs-sync.test.ts` pins the skill against the assertion-key catalog and the cassette schema's field list; `test/cli-help.test.ts` pins the README command table); prose workflows are on you — this checklist line exists because `effectiveFidelity` shipped consumer-visible and stayed undocumented in the skill until an external consumer flagged it.
 - **Format.** `npm run format:check` must pass (`npx prettier --write "src/**/*.ts" "test/**/*.ts"` to fix).
 
 ## Extending the sync extractor