cowork-harness 0.22.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.22.0
-  tracks-harness: cowork-harness 0.22.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.22.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.22.0**. If it's missing or older, prefix every command with the version floor `npx cowork-harness@>=0.22.0 <cmd>` (Node ≥ 20), or install once with `npm i -g cowork-harness@>=0.22.0`. **Pin `@>=0.22.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.22.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`).
@@ -55,7 +55,12 @@ Before the first command, confirm the CLI is reachable and **fail loud** (never
 
 Full command set: `skill · run · chat · record · replay · verify-cassettes · rehash · prune · lint ·
 verify-run · trace · inspect · diff · stats · decide · gates · answer · scaffold · assertions --list · sync ·
-list · boundary-check · vm <init|status|delete|prune> · doctor`. Always check `cowork-harness <cmd> --help`.
+list · boundary-check · status · vm <init|status|delete|prune> · doctor`. Always check `cowork-harness <cmd> --help`.
+
+**Two different `scaffold` tools — don't confuse them.** The native `cowork-harness scaffold <run-id>`
+above turns an already-*recorded* run into a scenario (needs a run to exist first). The bundled
+`scripts/scenario.py scaffold --name … --skill …` in §9 builds a scenario from flags alone, no run
+required. Passing §9's flag set to the native command fails with `unknown flag: --name` (exit 2).
 
 ## 2. Two files: session vs scenario
 
@@ -94,7 +99,8 @@ the folder basename (collision-resolved); there is no `to:` override. See `refer
 | `hostloop` / `cowork` | Production split-exec: the agent loop is a **native process on the host** (no container around the file tools — matching production), with native Bash/WebFetch disabled and routed host-side via the workspace SDK-MCP server into a Docker VM sidecar | Highest-fidelity / parity runs. A writable connected folder needs `allow_host_writes: true` (see scenario-schema.md). |
 
 Set the tier in the **scenario's `fidelity:` field**, not a flag — `run` rejects `--fidelity`
-(it's a `skill`-only flag). See `references/fidelity-and-answers.md`.
+(it's a `skill`/`chat` flag; `run` takes fidelity only from the scenario). See
+`references/fidelity-and-answers.md`.
 
 ## 5. Choose an answer path (gates: AskUserQuestion + tool-permission)
 
@@ -265,7 +271,7 @@ known-good skeleton (right tier, scripted `answers:` + `on_unanswered: fail`, co
 separated from live-only ones, one concern per item) and **self-lints its own output**:
 
 ```bash
-S="${CLAUDE_PLUGIN_ROOT}/skills/cowork-harness/scripts/scenario.py"
+S="${CLAUDE_PLUGIN_ROOT}/scripts/scenario.py"
 # Working from a repo checkout instead of an installed plugin?
 # S=".claude/skills/cowork-harness/scripts/scenario.py"
 python3 "$S" scaffold --name report-check --skill ./skills/report-gen \
@@ -282,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
@@ -356,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.
@@ -392,23 +405,29 @@ are the ones that bite hardest.
     prompt. *Fix:* treat `prompt_asset_missing` as a blocking error in CI by checking the signals
     array.
 13. **`result: success` means the agent didn't error, NOT that the task completed — always assert on
-    artifacts/content.** A turn that ends on a plain-text re-ask ("which file did you mean?") still
-    reports `result: success`. The harness catches a run that ends on a question and did **no productive
-    work after its last gate** — both the no-gate case ("which file?" with no tool calls) AND the
-    *answered-gate-then-re-ask* case (the agent answers an `AskUserQuestion`, then asks again in plain text
-    and stops) — with a **`stalled`** verdict signal (suppress with `allow_stall: true` if ending on a
-    question is intended). The signal is a **tool-position heuristic**, not deliverable detection, so it is
-    imprecise both ways: (a) a post-gate tool *call* clears the flag whether it **succeeded or errored** (false
-    negative — an agent that ran a tool after the gate and still stalled is not caught); and (b) a deliverable
-    written *before* a final confirmation gate does **not** clear it, so a write-then-confirm-then-question run
-    is flagged (false positive — use `allow_stall: true` for a deliberate confirm-terminal skill). The broad
-    guard is therefore YOUR assertions — assert the deliverable
-    (`file_exists` / `artifact_json` / `transcript_matches`), never just `result: success`. Note:
-    `on_unanswered` governs **unanswered** `AskUserQuestion` gates; the `stalled` signal covers stalling
-    *after* one is answered. A "type-it-in-notes" option has **no scripted deterministic answer** today (the
-    `OTHER:` directive works only on the LLM-decider path, not scripted `choose:`; on an options-bearing gate
-    a bare out-of-set LLM answer fails loud (exit 2) — see the LLM-decider free-text note in
-    `references/fidelity-and-answers.md`).
+    artifacts/content.**
+    - A turn that ends on a plain-text re-ask ("which file did you mean?") still reports
+      `result: success`.
+    - The harness catches this with a **`stalled`** verdict signal: a run that ends on a question and
+      did **no productive work after its last gate** — both the no-gate case ("which file?" with no
+      tool calls) AND the *answered-gate-then-re-ask* case (the agent answers an `AskUserQuestion`,
+      then asks again in plain text and stops). Suppress with `allow_stall: true` if ending on a
+      question is intended.
+    - The signal is a **tool-position heuristic**, not deliverable detection, so it is imprecise both
+      ways:
+      - **False negative:** a post-gate tool *call* clears the flag whether it **succeeded or
+        errored** — an agent that ran a tool after the gate and still stalled is not caught.
+      - **False positive:** a deliverable written *before* a final confirmation gate does **not**
+        clear it, so a write-then-confirm-then-question run is flagged — use `allow_stall: true` for a
+        deliberate confirm-terminal skill.
+    - The broad guard is therefore YOUR assertions — assert the deliverable (`file_exists` /
+      `artifact_json` / `transcript_matches`), never just `result: success`.
+    - `on_unanswered` governs **unanswered** `AskUserQuestion` gates; the `stalled` signal covers
+      stalling *after* one is answered — two different failure modes.
+    - **Free-text aside:** a "type-it-in-notes" option has **no scripted deterministic answer** today
+      (the `OTHER:` directive works only on the LLM-decider path, not scripted `choose:`; on an
+      options-bearing gate a bare out-of-set LLM answer fails loud (exit 2) — see the LLM-decider
+      free-text note in `references/fidelity-and-answers.md`).
 14. **A positional `choose` (`first` / index) is order-dependent.** `choose: "2"` survives label drift
     but NOT option *re-ordering* — if the gate presents its options in a different order run-to-run, the
     index lands on a different option (a silent re-record flake). Prefer an exact label when order is
@@ -444,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.22.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.22.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,11 +125,20 @@ 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.
-- **Always-on scan gate** — `verify-cassettes` flags email / currency / bare-domain / local-path matches
-  it finds in the committed cassettes and **exits non-zero**, so "no leak" is a gate, not discipline.
+- **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.
   Suppress synthetic / public reference names (NVCA, Cooley GO, …) with `--allow <regex>`. (Multi-word
   proper names are NOT a default class — too noisy to gate on; add a pattern via config if your corpus
   needs it.)
@@ -178,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.22.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
@@ -207,7 +216,7 @@ jobs:
             echo "live=true" >> "$GITHUB_OUTPUT"
           fi
       - if: steps.guard.outputs.live == 'true'
-        run: npm i -g cowork-harness@>=0.22.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:
@@ -234,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`,
@@ -260,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.22.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)
 
@@ -187,5 +187,6 @@ and `scaffold` refuse to treat a partial run's half-finished output as a passing
   redact from logs (beyond the auth tokens + `ANTHROPIC_CUSTOM_HEADERS`).
 - `COWORK_HARNESS_SOFT_MISSING` — downgrade a missing mount source from hard-error to warn-and-skip.
 - `COWORK_VM_GATEWAY` / `COWORK_VM_PROXY_PORT` / `COWORK_LIMA_INSTANCE` — L2 (microVM) knobs.
-- `COWORK_LOCKDOWN` — default `on`: **aborts loudly** if the L2 guest firewall fails to apply (no
-  silent unprotected run). Set `=off` to opt out and run without isolation deliberately.
+- `COWORK_LOCKDOWN` — default `on`: gates sandbox hardening on every isolated tier — **aborts loudly**
+  if the L2 guest firewall fails to apply (no silent unprotected run), and also gates the
+  `container`/`hostloop` Docker hardening. Set `=off` to opt out and run without isolation deliberately.

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.22.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`.
 
@@ -61,6 +61,12 @@ skills: [report-gen]                # OPTIONAL — scope the cassette-staleness
                                     # `skills/<name>` dir under a mounted plugin-root) + the plugin's shared
                                     # roots. Fail-closed to whole-tree on an unknown name. Omit = whole tree.
 
+requires_capabilities: [ocr]        # OPTIONAL — declare a capability the skill needs (e.g. office_convert,
+                                    # ocr, pdf_tables, opencv). If the running agent image provably omits
+                                    # one, the harness ABORTS before the paid run (exit 3) — unless the
+                                    # scenario also asserts `allow_missing_capability: true`, which downgrades
+                                    # the abort to a notice and proceeds. Live tiers only.
+
 allow_host_writes: true             # OPTIONAL — required to run `hostloop` fidelity with a WRITABLE
                                     # connected folder (session `mode: rw`/`rwd`): with no container
                                     # around hostloop's native file tools, that combination gives the
@@ -80,8 +86,10 @@ session = your setup.**
 ```yaml
 # model & reasoning
 model: claude-opus-4-8           # omit for the agent default
+account_name: my-account         # OPTIONAL — which configured account/credential set to run as
 effort: high                     # low | medium | high | xhigh
 max_thinking_tokens: 31999       # positive int, or per-model map {default, <model>: <n>}; default 31999
+extended_thinking: true          # INERT — not a real Cowork toggle; use max_thinking_tokens instead
 permission_mode: default         # default | acceptEdits | plan | bypassPermissions
 permission_parity: cowork        # cowork (unscripted tool calls allowed) | strict (deny unscripted)
 
@@ -97,8 +105,9 @@ plugins:
   marketplaces: []               # plugin_marketplaces (git URLs or local paths)
   local_marketplaces: []         # local marketplace dirs (each has a marketplace.json)
   enabled: [my-skill@local]      # enabledPlugins (name@marketplace)
-  local_plugins: [./skills/my-skill]   # host plugin dirs → mnt/.local-plugins/marketplaces/<marketplace>/<plugin>
-                                       #   (≥1.14271.0; older baselines use mnt/.local-plugins/cache)
+  local_plugins: [./skills/my-skill]   # host plugin dirs → mnt/.local-plugins/marketplaces/local-desktop-app-uploads/<plugin>
+                                       #   (the marketplace segment is that fixed synthetic name; ≥1.14271.0 —
+                                       #   older baselines use mnt/.local-plugins/cache)
   remote_plugins: []
 skills:
   local: []                      # extra host skill dirs
@@ -210,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 |
@@ -219,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` |
@@ -234,7 +244,7 @@ passes only if every key passes. Keep one concern per item unless you mean conju
 | `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 |
 | `allow_stall: true` | verdict modifier — suppresses the `stalled` default-fail when a run ends on a question having done no productive tool work after its last gate (the agent asked for input and stopped — incl. re-asking in plain text after answering an `AskUserQuestion`); assert only when ending on a question is intended, else script the answer (`answer:` / `--answer` / a decider) |
-| `transcript_no_host_path: true` | no host path (`/Users/`, `/opt/cowork/`, `/home/`, `/root/`) leaked into model-visible text — **incompatible with `hostloop`**: its native file tools legitimately expose real host paths, so this fails BY DESIGN there (the harness warns at run start if asserted anyway); use `container`/`microvm` for this check |
+| `transcript_no_host_path: true` | no host path (`/Users/`, `/opt/cowork/`, `/home/`, `/root/`) leaked into model-visible text — **incompatible with `hostloop` AND `protocol`**: hostloop's native file tools legitimately expose real host paths, and protocol (L0) runs the agent's file tools on the real host cwd with no sealed filesystem, so this fails BY DESIGN on both (the harness warns at run start if asserted anyway); use `container`/`microvm` for this check |
 | `egress_denied: <host>` | the host was blocked by the egress proxy |
 | `egress_allowed: <host>` | the host was allowed through |
 | `artifact_json: {artifact, path, …}` | assert a JSON artifact's contents — `equals`/`gt`/`in`/`exists`/`absent`/`is_null` over a dotted `path` (`in` = membership in a list, for a stochastic/LLM value; `absent` ≠ `is_null`; an unresolved intermediate fails loud) |
@@ -293,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.
@@ -372,7 +384,8 @@ at the top of this file.
    the stochastic path flags the run `nonDeterministic`. The LLM decider is one mechanism, two
    spellings: `on_unanswered: llm` (YAML) and `--decider-llm` (CLI). The bare `--on-unanswered llm`
    is rejected (use `--decider-llm`). `agent` is **retired** — `on_unanswered: agent` is rejected by
-   the schema. (`src/types.ts:276`; `src/cli.ts:652`.)
+   the schema. (`src/types.ts:365` — the `on_unanswered` enum; `src/cli.ts:899` — the CLI-side
+   `--on-unanswered` value check.)
 
 4. **`--on-unanswered first` is non-deterministic too** — it picks option 1 and is flagged
    `nonDeterministic`; not a deterministic substitute for scripted answers.
@@ -400,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",