cowork-harness 3.0.1 → 3.2.0

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

@@ -3,8 +3,8 @@ name: cowork-harness
 description: Test or debug a Claude Code skill/plugin under Claude Cowork's runtime — sandboxed agent, default-deny egress, the can_use_tool permission/question protocol — using the cowork-harness CLI. Use when validating or regression-testing a skill, authoring or debugging a scenario YAML (prompt + scripted answers + assert:), choosing a fidelity tier, scripting AskUserQuestion / tool-permission answers, or asserting artifacts, egress, or sub-agent dispatch. Especially when a harness run no-ops an assertion, fails on an unanswered gate, false-greens, a steered answer never reaches the model, or a web_fetch is unexpectedly denied or gated. Also when iterating or hardening a skill across fixes, or grounding a skill's self-critique against its own run evidence — including a document-analysis skill (cap table, deck, financial model, transcript) that needs an uploaded file attached to be critiqued at all. NOT for generic unit testing (pytest/vitest of your own scripts) or non-Cowork CI. Covers the skill / run / chat / record / replay / trace / decide / assertions / scaffold commands and the session-vs-scenario split.
 metadata:
   author: cowork-harness
-  version: 3.0.1
-  tracks-harness: cowork-harness 3.0.1 (baseline desktop-1.40609.0)
+  version: 3.2.0
+  tracks-harness: cowork-harness 3.2.0 (baseline desktop-1.40609.0)
 ---
 
 # cowork-harness
@@ -25,7 +25,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 3.0.1` (baseline
+> **Version note:** the facts and `file:line` pointers here track `cowork-harness 3.2.0` (baseline
 > `desktop-1.40609.0`). If your checkout is newer, prefer the live `--help` and — in a repo checkout —
 > `SPEC.md` / `docs/*.md` over this snapshot, and re-run the bundled linter.
 
@@ -42,7 +42,7 @@ Before the first command, confirm the CLI is reachable and **fail loud** (never
 
 - **One-shot check.** Run `cowork-harness doctor [--tier <tier>]` first — a read-only prerequisite check that inspects Docker, the staged agent, the token, and the baseline in one pass. The bullets below explain each thing it checks (and how to fix it).
 - **Replay-only? Skip `doctor`.** Replaying committed cassettes needs no Docker, no staged agent, and no token — and every tier's `doctor` validates the auth token (the live tiers also Docker + the staged agent), so a ✗ there is expected, not a blocker. Go straight to `cowork-harness replay <cassette>`.
-- **CLI on PATH, recent enough?** Run `cowork-harness --version` — this skill needs **≥ 3.0.1**. If it's missing or older, prefix every command with the version floor `npx "cowork-harness@^3.0.1" <cmd>` (Node ≥ 22), or install once with `npm i -g "cowork-harness@^3.0.1"`. **Pin `@^3.0.1`, never `@latest`** — `@latest` can silently fetch an older CLI and the new commands fail as "unknown command", whereas the floor **fails loud** if no compatible version is published.
+- **CLI on PATH, recent enough?** Run `cowork-harness --version` — this skill needs **≥ 3.2.0**. If it's missing or older, prefix every command with the version floor `npx "cowork-harness@^3.2.0" <cmd>` (Node ≥ 22), or install once with `npm i -g "cowork-harness@^3.2.0"`. **Pin `@^3.2.0`, never `@latest`** — `@latest` can silently fetch an older CLI and the new commands fail as "unknown command", whereas the floor **fails loud** if no compatible version is published.
 
   This skill documents the CURRENT surface, not release history. If `cowork-harness --version` is
   OLDER than the floor, the per-release record of what you are missing is [CHANGELOG.md](https://github.com/yaniv-golan/cowork-harness/blob/main/CHANGELOG.md)
@@ -57,21 +57,15 @@ Before the first command, confirm the CLI is reachable and **fail loud** (never
 Everything you do with the harness is one of **three loops**, and the rest of this skill is organized
 into three Parts to match: **author** a scenario (Part I), **run / record / lock** it into a
 reproducible regression (Part II), and **debug** a run that misbehaved or greened when it shouldn't
-(Part III — reachable straight from here in one hop). Pick the loop you're in:
+(Part III — reachable straight from here in one hop).
+
+Pick the entry point you need. The first three are the everyday path — a quick liveness check, the
+CI-grade scenario, and the post-hoc debug loop; the rest are narrower tools that hang off them:
 
 - **"Is it even alive?"** (inner loop) → `cowork-harness skill <folder> "<prompt>"`. Fastest; no
   scenario file.
 - **Repeatable, asserted regression** → author a `scenarios/*.yaml` and run `cowork-harness run`.
   This is the CI-grade path and most of this skill.
-- **Regression-test your skill's ANSWER quality** (not just its behavior — does its guidance still lead to
-  correct answers after you edit it?) → author `semantic_matches` scenarios and gate on the per-claim
-  profile. See **Recipe 5** in `references/task-recipes.md` (validity, N≥3, discrimination — the traps).
-- **"What is WRONG with this skill?"** (a graded critique, not a pass/fail) → `cowork-harness critique
-  <folder> --prompt "<probe>"`. Four model workloads and 10–20 minutes; budget from
-  `report.costUsd.totalUsd`. Reach for it when you want **findings**. **For "what does this skill
-  **DO**" — routing, artifact location, narration — use `skill` instead**: no evaluator, a fraction of
-  the cost, and it answers that question directly. Report and evidence-package shapes:
-  `references/critique.md`.
 - **A run failed — or greened and you don't trust it** (the debugging loop) → don't re-run and hope.
   The run already wrote its evidence to a **kept run dir** (`~/.cowork-harness/runs/…`; `--keep` prints
   the path, `trace <run-id>` finds it). **Localize the failure post-hoc** from that evidence:
@@ -83,6 +77,15 @@ reproducible regression (Part II), and **debug** a run that misbehaved or greene
   **"Evidence" here means the RUN's own record** — events, trace, transcript. `critique`'s evaluator
   grades against a different artifact, `critique-evidence-package.txt`, which none of these tools
   surface; see `references/critique.md`.
+- **Regression-test your skill's ANSWER quality** (not just its behavior — does its guidance still lead to
+  correct answers after you edit it?) → author `semantic_matches` scenarios and gate on the per-claim
+  profile. See **Recipe 5** in `references/task-recipes.md` (validity, N≥3, discrimination — the traps).
+- **"What is WRONG with this skill?"** (a graded critique, not a pass/fail) → `cowork-harness critique
+  <folder> --prompt "<probe>"`. Four model workloads and 10–20 minutes; budget from
+  `report.costUsd.totalUsd`. Reach for it when you want **findings**. **For "what does this skill
+  **DO**" — routing, artifact location, narration — use `skill` instead**: no evaluator, a fraction of
+  the cost, and it answers that question directly. Report and evidence-package shapes:
+  `references/critique.md`.
 - **Multi-turn / interactive reproduction** → `cowork-harness chat` (interactive; gates answered at the
   TTY, **not** an asserted test — see *Debugging with `chat`* in **Part III — Debug**).
   **"Interactive" splits two ways — don't take the wrong branch.** Want to answer gates yourself *and*
@@ -380,7 +383,10 @@ emits a scenario `lint` would reject.
 `lint` (exit 0) but a **hard error** in the runtime (`Unrecognized key: "<k>"`, exit 2) — so a scenario
 that lints with warnings may still not run. To check whether a scenario actually loads, without spending:
 `cowork-harness record <file.yaml> --dry-run` (exit 2 on a schema error; a directory reports each
-`✗ broken:` file and exits 1). Corollary: **the loader** fails LOUD on an unknown key (never silently) —
+`✗ broken:` file and exits 1). **Read the exit code, not just its sign:** `record <file>` — with or without
+`--dry-run` — answers `2` for "did not load" and `1` for "loaded fine, but this record is refused" (a
+pre-spend policy refusal; `--max-budget-usd` is the one refusal that keeps exit 2). Treating any non-zero
+as "scenario broken" mis-reports every refused-but-valid scenario. Corollary: **the loader** fails LOUD on an unknown key (never silently) —
 but **`replay` does not**: a frozen top-level key it doesn't recognize (e.g. `lane:` recorded pre-1.16.0) is
 silently ignored and can flip a lane-sensitive verdict green; only frozen **assertion** keys stay
 hard-rejected there. Full split + the v11 version-regime:
@@ -416,6 +422,28 @@ contradiction, duplicate cassette target) gate the batch. So a directory dry-run
 real `record` would refuse; re-run that one file with its real flags for a binding answer. A directory also
 reports every offender and the batch cost estimate. `lint` checks the assertion invariants (both above).
 
+**Which arm to reach for.** They answer different questions, and picking the wrong one is why a consumer
+concluded the free pre-flight was unavailable:
+- **"Does my whole corpus still load?"** → the **directory** arm (`record scenarios/ --dry-run --quiet`,
+  the CI shape in `references/ci-recipe.md`). It reports every offender in one pass, and the
+  destination-policy verdict cannot red it: that arm knows no `--out`, so host-inventory and portability
+  are advisory `notes[]` at exit 0 while a file that cannot load is `✗ broken:` at exit 1. Limits worth
+  knowing: it is **non-recursive** (`readdirSync` — scenarios in subdirectories are never opened), a file
+  with no `prompt:` key reports as `· skipped:` rather than broken (so a renamed or mis-indented
+  `prompt:` reads as "not a scenario" and the batch still exits 0), exit 1 covers **refused**
+  (path-independent only — prompt policy, assert contradiction, duplicate target) as well as broken, and
+  `--quiet` suppresses the advisory notes entirely — it keeps `✗ broken:` / `✗ refused:` / `· skipped:`,
+  which is what you want in CI but means the notes are not a thing you will see there.
+- **"Would THIS record be refused?"** → the **single-file** arm **with the flags and `--out` the real
+  record will get**. The destination it evaluates is `--out` if given, else `cassettes/<slug>.cassette.json`
+  *relative to your cwd* — so previewing from the repo root a record that really runs from a subdirectory
+  asks about a path that may not even exist, and a scenario whose cassette IS committed can come back
+  refused. Point it at the real destination and the answer is binding.
+
+Neither question is answered by passing `--allow-host-inventory-fixture` to get past the refusal: that
+flag is consent for a recording you intend to make, and reaching for it as a load-check habit is how it
+stops meaning anything.
+
 **Decide WHERE the cassette lives before you record it — a cassette cannot be moved afterwards.**
 Without `--out`, `record` writes `cassettes/<scenario-name-slug>.cassette.json` (gitignored by
 default); pass `--out <path>` to put it somewhere tracked, e.g. `examples/replays/<name>.cassette.json`.
@@ -429,7 +457,7 @@ warns when the cassette would be written outside the scenario's tree, or when `s
 outside it (an absolute or `~` path: the mirror case, invisible to a check that only looks at where the
 cassette lands). A warning, not a refusal — an out-of-tree throwaway cassette is legitimate; what was
 missing was anything saying so while you could still act. Related: recording at a **host-inheriting** tier
-(`protocol`/`hostloop`/`cowork`→hostloop) into a repo-visible path is refused outright (gotcha 25).
+(`protocol`/`hostloop`/`cowork`→hostloop) into a repo-visible path is refused outright (gotcha 25 below).
 The clean answer there is `fidelity: container` (sealed, `HOME=/tmp`, nothing to leak) — **not**
 redirecting `--out` outside the repo and moving the file in afterwards, which trades a loud refusal
 for a cassette that cannot verify staleness from its own location — recoverable only by passing
@@ -568,6 +596,12 @@ Recognize these before "fixing" a non-bug:
   would claim more than the evidence supports, and staying silent would read as clean. Mutually exclusive
   with `undelivered_deliverables`, and quiet on a run that produced nothing to deliver. Not a skill defect —
   a harness coverage gap (see the *File delivery* section of fidelity-gaps).
+- **`model_fallback`** (`WARN`) — the agent switched off the requested model mid-run. Read the `trigger`:
+  `model_not_found` / `model_blocked` / `permission_denied` are properties of the **pin**, so every run of
+  this scenario falls back the same way until you change the pinned id; `overloaded` / `server_error` are
+  transient and a re-run may hold. The run's assertions still mean what they say — but they were produced
+  by a different model than the scenario names, so treat a green as evidence about the fallback model.
+
 - **`mount_delete`** (`WARN`) — a delete touched a **delete-denied mount other than `outputs`**: a `rw`
   connected folder. Production denies `unlink`/`rmdir` on *every* Cowork FUSE mount until per-mount
   approval, not just outputs — a connected folder shows the identical default — so this run diverged from
@@ -594,7 +628,7 @@ Recognize these before "fixing" a non-bug:
   `RunResult.scan` is undefined and the host-path + outputs-delete guards **did not run this run**. Not a
   pass or a defect — assert `no_delete_in_outputs` / `transcript_no_host_path` to hard-fail on it instead.
 
-The full 17-code signal table (severity + per-signal opt-out) is in
+The full 20-code signal table (severity + per-signal opt-out) is in
 [`references/scenario-schema.md`](./references/scenario-schema.md); [`docs/scenario.md`](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/scenario.md) (repo-only) carries
 the fuller narrative.
 
@@ -744,7 +778,8 @@ decide which assertions from *Assertions: two orthogonal axes* are worth adding)
   `tokens`, `cache-tokens`, `model-cost`, `turns`, `pass-rate`. Filters: `--since`/`--baseline`/`--branch`,
   plus `--skill-hash <prefix>`/`--label <tag>` to narrow to ONE skill generation and
   `--group-by scenario|skill-hash|label|fidelity` to split per generation — or per effective fidelity
-  tier — instead of aggregating across them (a window spanning >1 generation warns — see Gotcha 6;
+  tier — instead of aggregating across them (a window spanning >1 generation warns, so an un-split A/B
+  average announces itself rather than passing as one number;
   >1 tier warns too, independently, with `--group-by fidelity` as its own remedy). `--runs` lists the
   individual runs behind each summary with their `skillHash`/`runLabel`, so
   you can tell which arm a run belonged to without opening its `result.json`. `--last <n>` windows per group.
@@ -767,7 +802,7 @@ decide which assertions from *Assertions: two orthogonal axes* are worth adding)
   `outputTruncated` on a matched tool result). Three separately-shaped rollups, easy to conflate in a
   `jq` recipe: `toolCounts` is a flat `{tool: number}` call-count map, `toolErrors` is
   `{tool: {calls, errors}}`, and `toolDurations` is `{tool: {calls, totalMs, maxMs}}`. (Full per-field
-  semantics: the README's "Observability fields" section — repo-only; [`schema/run-result.json`](https://github.com/yaniv-golan/cowork-harness/blob/main/schema/run-result.json) is the
+  semantics: [`docs/cli.md` → What you get out](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/cli.md#what-you-get-out-inspectable-output) (repo-only); [`schema/run-result.json`](https://github.com/yaniv-golan/cowork-harness/blob/main/schema/run-result.json) is the
   machine source.)
 - **Opaque failure?** A failed run also records **`errorSource`** (where the failure originated) and
   **`stderrLogPath`** (the captured agent stderr) — read those and `trace <run-dir>` *before* re-running;
@@ -824,8 +859,12 @@ The startup banner now reads `type your message (/help for commands)` as a remin
 
 ## Gotchas — the "✓ passed ≠ correct" landmines
 
-Stated as *symptom → why → fix*. **This is the full landmine catalog;** `references/scenario-schema.md`
-repeats the assertion/replay-relevant ones alongside the schema (a scoped subset, not a fuller list).
+Stated as *symptom → why → fix*. This is the **workflow/record/answer-path** view — the broader of the
+two lists, but **not a strict superset**: `references/scenario-schema.md`'s *Authoring gotcha list*
+carries a few assertion-level landmines this one omits (`transcript_no_host_path`'s scan width,
+`egress.extra_allow`'s no-op on the provenanced `web_fetch` path, `replay_protocol_fidelity` not being
+authorable). Reach for this list when debugging a run's behavior, that one while authoring `assert:`.
+**The two lists are numbered independently** — a bare "gotcha N" means the list you are reading.
 
 1. **An assertion passed but tested nothing on the PR gate.** *Why:* on a manifest-less cassette
    `replay` skips filesystem/egress keys (`file_exists`, `user_visible_artifact`, `artifact_json`,
@@ -851,7 +890,7 @@ repeats the assertion/replay-relevant ones alongside the schema (a scoped subset
 
 3. **A multi-key `assert:` item is an AND.** A single list item with more than one key passes iff
    **every** key passes. *Fix:* one concern per item unless you genuinely mean conjunction (and a
-   mixed-class conjunction still loses its filesystem half on replay — see gotcha 1).
+   mixed-class conjunction still loses its filesystem half on replay — see gotcha 1 below).
 
 4. **`tool_called` doesn't mean "attempted".** Tool counts are authoritative and de-duped: a tool
    that was *requested then denied* does **not** register as called. *Fix:* don't assert `tool_called`

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 3.0.1` (baseline `desktop-1.40609.0`).
+Self-contained reference. Tracks `cowork-harness 3.2.0` (baseline `desktop-1.40609.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):
@@ -17,7 +17,7 @@ job-summary reporter (verdict table, staleness findings, cost/turns when availab
 CLI major reaches your workflow the moment it is promoted even though your `uses:` ref never changed — so a
 copy-pasted recipe that omits the input takes a major bump with no say in it. `^2` holds the major, needs no
 patch number to remember, and only wants a human decision at the next major. Pin an exact version
-(e.g. `version: "3.0.1"`) instead when you want byte-reproducible CI.
+(e.g. `version: "3.2.0"`) instead when you want byte-reproducible CI.
 
 Reach for the manual multi-step form below only when you need per-step control the Action's inputs don't
 cover (a custom flag combination, a different runner matrix per step, or `lint`/`verify-cassettes` gated
@@ -67,7 +67,7 @@ sha256-*checked* but not hard-blocking on mismatch — it's advisory for an inte
 GitHub-hosted runners, no token/Docker/agent:
 
 ```yaml
-- run: npm i -g "cowork-harness@^3.0.1"
+- run: npm i -g "cowork-harness@^3.2.0"
 - run: cowork-harness lint scenarios/*.yaml --strict --min-severity WARN
                                                     # no silent false-greens. WITHOUT --strict this
                                                     # step cannot fail on a WARN-class rule (e.g.
@@ -312,7 +312,9 @@ A typical skill repo runs four stages, fastest/cheapest first:
 
    This is the shape a CI step wants: **silent on success (no output, exit 0), loud and specific on
    failure** — `--quiet` suppresses the readiness preview but never the `✗ broken:` lines, which name the
-   offending file *and* the rejected key, and the step still exits 1. A scenario that lints with only
+   offending file *and* the rejected key, one line per file, and the step still exits 1. (Silent is
+   literal only when your scenarios name a `fidelity:`; one still in the deprecation window prints one
+   defaulted-fidelity notice per scenario.) A scenario that lints with only
    warnings can still be unloadable, so a green `lint` is not evidence the suite runs.
 3. **Scenarios (replay)** — `cowork-harness replay cassettes/` on every PR (the committed `*.cassette.json`).
    Token-free; content + structure + gate delivery.
@@ -342,7 +344,7 @@ jobs:
         with: { node-version: '24' }
       - uses: actions/setup-python@v5
         with: { python-version: '3.x' }                                       # python3 only — PyYAML is bundled with the linter
-      - run: npm i -g "cowork-harness@^3.0.1"
+      - run: npm i -g "cowork-harness@^3.2.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
@@ -371,7 +373,7 @@ jobs:
             echo "live=true" >> "$GITHUB_OUTPUT"
           fi
       - if: steps.guard.outputs.live == 'true'
-        run: npm i -g "cowork-harness@^3.0.1"
+        run: npm i -g "cowork-harness@^3.2.0"
       - if: steps.guard.outputs.live == 'true'
         run: cowork-harness run scenarios/ --output-format json
         env:

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

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

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

@@ -1,6 +1,6 @@
 # Fidelity tiers & answer paths
 
-Self-contained reference. Tracks `cowork-harness 3.0.1` (baseline `desktop-1.40609.0`).
+Self-contained reference. Tracks `cowork-harness 3.2.0` (baseline `desktop-1.40609.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
+# Scenario & session schema, assertion catalog, web_fetch, authoring gotchas
 
-Self-contained reference for authoring `cowork-harness` scenarios. Tracks `cowork-harness 3.0.1`
+Self-contained reference for authoring `cowork-harness` scenarios. Tracks `cowork-harness 3.2.0`
 (baseline `desktop-1.40609.0`). If your checkout is newer, prefer the live [`docs/scenario.md`](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/scenario.md),
 [`docs/session.md`](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/session.md), and `SPEC.md`.
 
@@ -22,7 +22,7 @@ Everything below is the full field + assertion catalog.
 - [Replay class — which assertions survive `replay`](#replay-class)
 - [The web_fetch model](#the-web_fetch-model)
 - [Scenario YAML vs the pytest lane](#scenario-yaml-vs-the-pytest-lane)
-- [Full gotcha list](#full-gotcha-list)
+- [Authoring gotcha list](#authoring-gotcha-list)
 
 ## Scenario YAML
 
@@ -307,7 +307,7 @@ same set live from the schema.
 | `transcript_not_matches: <regex>` | it does not match (e.g. no leaked stack trace) **Sees top-level `assistant_text` only — it excludes every `tool_use`/`tool_result`**, so text emitted inside a tool call (a gate question, an option label or description) can never match; use `question_context`/`question_asked` or `tool_result_contains` for those. |
 | `file_exists: <path>` | the path exists under the run's `work/` (anchored at `mnt/`, e.g. `outputs/x.md`). For a user-facing deliverable prefer `user_visible_artifact` — with a connected folder the file lands in `mnt/<folder>` (= `{{workspaceFolder}}`), not `mnt/outputs`, so `file_exists: outputs/x.md` misses it |
 | `user_visible_artifact: <path>` | exists **and** under a user-visible root (`outputs/` + each connected folder's mount name) — the right primitive for a workspace deliverable when a folder is connected |
-| `no_delete_in_outputs: true` | no delete op touched `mnt/outputs` — **only `true` is valid**; `false` is rejected (omit to allow deletes) |
+| `no_delete_in_outputs: true` | no delete op touched `mnt/outputs` — **only `true` is valid**; `false` is rejected. **Omitting it does NOT allow deletes** — a detected delete still fails via the `outputs_delete` verdict signal, which fires *because* the key was not authored; use `allow_outputs_delete: true` to accept an intended one. Detection is a post-run bash-command scan, not mount enforcement, so a green means none was *detected* |
 | `no_delete_in_mounts: true` | no delete op touched ANY delete-denied mount — `outputs` plus every `rw` connected folder — except those waived by `allow_delete_in`. Production denies `unlink`/`rmdir` on every such mount, so `no_delete_in_outputs` covers only part of the real rule. **only `true` is valid** |
 | `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); an **incomplete post-run filesystem walk** (an unreadable subtree — a permission/I-O error) also fails evidence-unavailable rather than reporting "no strays" over a partial tree — distinct from the missing-manifest case (a `--resume` run), which fails for a different reason; captured on every live sandbox tier including microvm (its outputs are snapshotted from the VM into the run dir); replay needs `cassette.preRunPaths` (≥0.24 recordings) — cassettes without it **exclude** the key with a loud warning. ⚠️ **Not a stand-in for "file X must not exist":** there is no negative-existence key, and inverting this one is a different claim — it is new-files-only (a pre-existing file is invisible to it) and needs a pre-run manifest. Assert the content-level consequence instead (`tool_not_called`, or the absent `artifact_json`) rather than widening an allowlist for every incidental lock/temp file |
 | `input_unmodified: <glob>` or `[<glob>, …]` | a single glob or a list; every **pre-existing** file (incl. uploaded files under `uploads/**`) whose workRoot-relative path matches ≥1 glob keeps an unchanged content hash after the run — the in-place-mutation companion to `no_unexpected_files`'s new-files check (`[]` is rejected by the schema — list at least one glob); a glob that matches **no** pre-run path fails loud (a typo or renamed mount would otherwise verify zero files and pass vacuously); a matched file that was deleted counts as a content change (fails); live/verify-run without a pre-run hash manifest ⇒ evidence-unavailable hard-fail (a `--resume` run); captured on every live sandbox tier including microvm; replay needs `cassette.preRunHashes` — cassettes without it **exclude** the key with a loud warning; on replay it compares against the manifest's recorded `sha256`, never a re-hash of the materialized tree |
@@ -401,9 +401,9 @@ paraphrases (that re-records red). Structured JSON → assert it in YAML with **
 `path` + operator); use the pytest lane (`assert_artifact_json`) only for predicates too complex for a
 dotted path.
 
-**VerdictSignals in `result.verdict.signals`:** `computeVerdict` pushes signals into `result.verdict.signals`; most
+**VerdictSignals in `result.verdict.signals`:** `computeVerdict` pushes signals into `result.verdict.signals`; eleven
 are **fail**-severity (they flip the run's pass/exit code even though `result.result` itself stays
-`"success"`) and only four are **warn**-severity (informational, never flip pass/fail). Current signal
+`"success"`) and nine are **warn**-severity (informational, never flip pass/fail). All twenty signal
 codes (`VerdictSignal["code"]` in `src/run/verdict.ts`):
 
 | Code | Severity | Meaning |
@@ -421,6 +421,7 @@ codes (`VerdictSignal["code"]` in `src/run/verdict.ts`):
 | `infra_error` | fail | A supervising process died mid-run (VM/egress sidecar) — the run's evidence is contaminated, not author-suppressible |
 | `stalled` | fail | The run ended on an unanswered question, or on a trailing-`?` final turn with no tool work after the last gate (opt out: `allow_stall`) |
 | `non_deterministic` | warn | The run was LLM/external/human-decided — not reproducible |
+| `model_fallback` | warn | The agent fell back off the requested model mid-run (SDK `model_fallback` event); a `model_not_found`/`model_blocked` trigger repeats every run until the pin changes |
 | `prompt_asset_missing` | warn | The run proceeded with a missing prompt asset (`COWORK_HARNESS_ALLOW_MISSING_PROMPT=1`); fidelity is degraded |
 | `scan_unavailable` | warn | Post-run scan evidence unavailable (`RunResult.scan` undefined) — the host-path and outputs-delete guards did not run this run |
 | `ended_with_question` | warn | Live-lane heuristic: the final answer contains a question and the run wrote no deliverable to `outputs/` — the lenient sibling of `stalled` (covers a mid-message `?`, or tool work after the last gate that still ended asking). Opt out: `allow_stall` |
@@ -430,7 +431,7 @@ codes (`VerdictSignal["code"]` in `src/run/verdict.ts`):
 
 A **fail**-severity signal does not change `result.result` (still `"success"`), but it DOES fail the
 overall run verdict and exit code — `assert result: success` alone won't catch it; check
-`result.verdict.signals[].severity` or the run's exit code. Only the five **warn** codes are truly benign.
+`result.verdict.signals[].severity` or the run's exit code. Only the nine **warn** codes are truly benign.
 
 ## Replay class
 
@@ -545,14 +546,14 @@ real predicate over a skill's **structured JSON output**:
 Find an artifact's real field paths by running once with `--keep`, then `cowork-harness inspect <run-dir>`
 (a shallow field preview of each JSON artifact) or by reading the JSON directly.
 
-## Full gotcha list
+## Authoring gotcha list
 
 The "✓ passed ≠ correct" landmines relevant to **scenario/assertion authoring**, as
 *symptom → why → fix*. `file:line` pointers track the version at the top of this file.
-**Scope note:** this is the assertion/replay-focused view; the **companion `SKILL.md`'s Gotchas
-section is the full landmine catalog** (it adds workflow/record/answer-path landmines this schema
-reference omits). Neither list is a strict superset of the other — reach for this one while authoring
-`assert:`, and SKILL's when debugging a run's behavior.
+**Scope note:** this is the assertion/replay-focused view; the companion `SKILL.md`'s Gotchas section
+is the broader one (it adds workflow/record/answer-path landmines this reference omits). **Neither list
+is a strict superset of the other** — reach for this one while authoring `assert:`, and SKILL's when
+debugging a run's behavior. The two are **numbered independently**: a bare "gotcha N" means this list.
 
 1. **Replay skips filesystem/egress assertions (two shapes) — with a loud warning.** *Full skip:* a pure
    live-only `egress_*`/`no_delete_in_outputs`/`self_heal_ran`/`transcript_no_host_path` item on a
@@ -590,7 +591,8 @@ reference omits). Neither list is a strict superset of the other — reach for t
    one concatenated string → use `[\s\S]`, not `.`. `transcript_matches` is case-insensitive.
 
 7. **Multi-key assertion item = AND.** Passes iff every key passes. One concern per item unless
-   conjunction is intended (and a mixed-class conjunction loses its filesystem half on replay — gotcha 1).
+   conjunction is intended (and a mixed-class conjunction loses its filesystem half on replay — gotcha 1
+   of THIS list; the two gotcha lists are numbered independently).
 
 8. **`tool_called` proves a tool ran, not that it was attempted.** Tool counts are authoritative and
    de-duped: a requested-then-denied tool does NOT register as called; the synthetic

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

@@ -2,7 +2,7 @@
 
 Each recipe composes facts that live scattered across SKILL.md and the other references into one
 decision path. Every one answers a question a real fleet owner had to work out the hard way.
-Tracks `cowork-harness 3.0.1` (baseline `desktop-1.40609.0`), same as SKILL.md's front-matter. Recipe 2's `resolved-tier`/`unverifiable-tier` staleness classes and
+Tracks `cowork-harness 3.2.0` (baseline `desktop-1.40609.0`), same as SKILL.md's front-matter. Recipe 2's `resolved-tier`/`unverifiable-tier` staleness classes and
 Recipe 3's `init-redact` shipped in 0.24.0 and are part of the current feature set — no version gate
 needed if your CLI meets SKILL.md's version floor.
 
@@ -46,6 +46,11 @@ what production would do. Two layers of defense:
   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.
+- **Do NOT re-record for a `[note]` alone.** A `·`/`[note]` row is informational and the run still exits
+  **0** — `session-fingerprint: predates \`model\` coverage` and `prompt-assets: cassette predates …` both
+  mean "this cassette was recorded before that field existed, and everything the hash *does* cover still
+  matches". Re-recording buys the new coverage and nothing else, so on a fleet of heavy cassettes it is a
+  real bill for no verdict change. Re-record when a `✗` says to (baseline moved, skill drift, tier moved).
 
 ### Cassette anatomy (what you're looking at when you open one)
 
@@ -66,7 +71,7 @@ Top-level fields of a `*.cassette.json` (schema [`schema/cassette.v12.json`](htt
 | `preRunOrigin` | How that pre-run baseline was obtained — `local-walk` (real), `remote-unavailable` or `local-unreadable`. Only `local-walk` supports a verdict: replay fails `no_unexpected_files` as evidence-unavailable on the other two rather than passing vacuously |
 | `scenarioSource` | Relative path to the authored YAML this was recorded from |
 | `authoring` | Present iff a live decider answered ≥1 gate during recording (`nonDeterministic: true`) |
-| `sessionFingerprint` | Optional even on v9+ (the minimum readable version): hash of the session's content-relevant SHAPE (folders/plugins/skills/mcp/egress/web_fetch, plus projects and agent_env when set). Checked ONLY by `verify-cassettes`, never the default replay verdict; absent → not checked |
+| `sessionFingerprint` | Optional even on v9+ (the minimum readable version): hash of the session's content-relevant SHAPE (model/folders/plugins/skills/mcp/egress/web_fetch, plus projects and agent_env when set). Checked ONLY by `verify-cassettes`, never the default replay verdict; absent → not checked |
 | `folderPrefixMap` | Optional even on v9+: the record-time connected-folder host-path → mount-name map. Replay's `computer_links_resolve` uses THIS (never the current session file); absent → the link is treated as evidence-unavailable, never reconstructed from the current session |
 | `timeline`, `timelineHeader` | The recorded per-event timeline (harness-observation timestamps for tool_use/tool_result/subagent_dispatch/thinking/decision/result, in total order) plus its header (`startedAtWall`/`startedAtMono` anchors); informational only — never affects the replay verdict. Absent on a cassette recorded before this field existed |
 | `environment` | Recording provenance: `location` (`"local"` on every cassette this harness produces), the resolved `tier`, `agentBinaryFormat`, and `harnessVersion` — the CLI that RECORDED the cassette (≥1.11.0). A harness-code change can shift recorded behaviour at an UNCHANGED baseline, which no staleness class keys off, so this is the only provenance for that class. **Absent** on pre-1.11.0 cassettes, and never backfilled — the absence is itself the signal |
@@ -241,10 +246,13 @@ Hardening a skill is a loop: run → read what it did → fix → run again. Two
    unrecoverable if skipped. `skillHash` is content-exact, so an edit mid-batch silently splits the
    dataset into two generations — `stats --group-by skill-hash` separates them afterwards, but a hash
    whose source was never committed names a generation that is unrecoverable, which makes the
-   comparison uninterpretable rather than merely noisy. And with no `model:` in the session (or
-   `--model` on the `skill` lane) each run uses whatever the staged agent binary defaults to, so a
-   before/after can silently straddle two models; read `result.json`'s `models` back to confirm —
-   ignoring any `<…>`-wrapped entry (`<synthetic>` marks a turn the agent fabricated locally, not a model).
+   comparison uninterpretable rather than merely noisy. And with no `model:` in the session and no
+   `--model` on the command (every lane takes it), each run uses whatever the staged agent binary
+   defaults to, so a before/after can silently straddle two models — the run warns when nothing pinned
+   one. Read `result.json` back to confirm: `modelSource` says whether anything pinned the model at all,
+   and `modelPinHonored` whether the pin survived (**absent means unverifiable, not "yes"**). `models`
+   lists what served the run — ignore any `<…>`-wrapped entry (`<synthetic>` marks a turn the agent
+   fabricated locally, not a model).
 3. **Don't cross-pair generations.** When you run the same skill across fixes, never pair a *pre-fix*
    `result.json` with a *post-fix* critique. The authoritative version key is `fingerprint.skillHash` —
    content-exact, on every live `run`/`skill` run that mounts a skill or plugin — **but only on ≥ 1.5.0; earlier CLIs emit

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

@@ -122,5 +122,58 @@
     "Stop",
     "SubagentStop",
     "UserPromptSubmit"
-  ]
+  ],
+  "enums": {
+    "answers.decide": [
+      "allow",
+      "deny"
+    ],
+    "answers.else": [
+      "allow",
+      "deny"
+    ],
+    "answers.grant": [
+      "once",
+      "domain"
+    ],
+    "assert.path_denied.agent_scope": [
+      "main",
+      "subagent",
+      "any"
+    ],
+    "assert.path_denied.source": [
+      "pretooluse",
+      "can_use_tool",
+      "permission_denied"
+    ],
+    "assert.question_options.order": [
+      "exact",
+      "any"
+    ],
+    "assert.result": [
+      "success",
+      "error"
+    ],
+    "execution": [
+      "local",
+      "cloud-describe"
+    ],
+    "fidelity": [
+      "protocol",
+      "container",
+      "microvm",
+      "hostloop",
+      "cowork"
+    ],
+    "lane": [
+      "local",
+      "remote"
+    ],
+    "on_unanswered": [
+      "fail",
+      "prompt",
+      "llm",
+      "first"
+    ]
+  }
 }