cowork-harness 3.0.0 → 3.1.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.0
-  tracks-harness: cowork-harness 3.0.0 (baseline desktop-1.40609.0)
+  version: 3.1.0
+  tracks-harness: cowork-harness 3.1.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.0` (baseline
+> **Version note:** the facts and `file:line` pointers here track `cowork-harness 3.1.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.0**. If it's missing or older, prefix every command with the version floor `npx "cowork-harness@^3.0.0" <cmd>` (Node ≥ 22), or install once with `npm i -g "cowork-harness@^3.0.0"`. **Pin `@^3.0.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.
+- **CLI on PATH, recent enough?** Run `cowork-harness --version` — this skill needs **≥ 3.1.0**. If it's missing or older, prefix every command with the version floor `npx "cowork-harness@^3.1.0" <cmd>` (Node ≥ 22), or install once with `npm i -g "cowork-harness@^3.1.0"`. **Pin `@^3.1.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)
@@ -568,6 +568,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

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.0` (baseline `desktop-1.40609.0`).
+Self-contained reference. Tracks `cowork-harness 3.1.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.0"`) instead when you want byte-reproducible CI.
+(e.g. `version: "3.1.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.0"
+- run: npm i -g "cowork-harness@^3.1.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.
@@ -342,7 +342,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.0"
+      - run: npm i -g "cowork-harness@^3.1.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 +371,7 @@ jobs:
             echo "live=true" >> "$GITHUB_OUTPUT"
           fi
       - if: steps.guard.outputs.live == 'true'
-        run: npm i -g "cowork-harness@^3.0.0"
+        run: npm i -g "cowork-harness@^3.1.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.0` (baseline `desktop-1.40609.0`). This is **not** a trim of the full
+Tracks `cowork-harness 3.1.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.0` (baseline `desktop-1.40609.0`).
+Self-contained reference. Tracks `cowork-harness 3.1.0` (baseline `desktop-1.40609.0`).
 
 ## Fidelity tiers (`fidelity:` in the scenario)
 
@@ -20,7 +20,8 @@ Self-contained reference. Tracks `cowork-harness 3.0.0` (baseline `desktop-1.406
 - A `hostloop` scenario with a **writable** connected folder (`mode: rw`/`rwd`) needs `allow_host_writes:
   true` — with no container around the native file tools, that combination gives the agent genuine,
   software-checked-only host filesystem access. Read-only folders and folder-less runs need no opt-in.
-- A `protocol` scenario staging a plugin that declares runnable hooks needs `allow_host_hooks: true`
+- A `protocol` scenario staging a plugin that declares runnable hooks — in `<plugin>/hooks/hooks.json`
+  or the plugin manifest's `hooks` key, both live — needs `allow_host_hooks: true`
   (`--allow-host-hooks` on `chat`/`skill`). L0 passes `--plugin-dir`, so the CLI runs those
   hooks as native host processes under your account with no sandbox. Plugins without hooks need no opt-in.
   Needs cowork-harness >= 3.0.0 — an older CLI rejects the key outright (`Unrecognized key`, exit 2), it
@@ -155,6 +156,60 @@ hands `fn` exactly this dict.
 - `agent` is **retired** — `on_unanswered: agent` is rejected by the schema. The enum is
   `["fail", "prompt", "llm", "first"]`.
 
+### A script-running skill trips `permissive_auto_allow` — at `protocol` specifically
+
+The default `permission_parity: cowork` auto-allows an unscripted, off-registry tool ask — and records
+it, because real Cowork would have BLOCKED for the user. `computeVerdict` then FAILS the run: a green
+carrying one would not be a faithful pass. Only `Read`, `Glob` and `Grep` are default-allow; **`Bash` is
+off-registry**.
+
+Two things decide whether you ever see it, and neither is obvious. The harness only decides how to
+ANSWER a permission ask; whether the agent ASKS is the agent binary's own logic, and that varies by
+both the command and the tier. All rows below are measured, same scenario shape, same session:
+
+| Tier | Bash command | tool used | ask | verdict |
+|---|---|---|---|---|
+| `protocol` | `echo hello` | `Bash` | none | ✓ green |
+| `protocol` | `python3 -c "print(42)"` | `Bash` | **one** | ✗ `permissive_auto_allow` |
+| `container` | `python3 -c "print(42)"` | `Bash` | none | ✓ green |
+| `hostloop` | `python3 -c "print(42)"` | `mcp__workspace__bash` | none | ✓ green |
+
+So the guard is **not** a general hazard for script-running skills — it is a `protocol` one. The host
+CLI that L0 spawns asks for a command like `python3 -c …` and not for `echo`; the staged agent at
+`container` asks for neither, and `hostloop` routes shell through `mcp__workspace__bash` and so is not
+even the same tool. A skill that runs `python3 ${CLAUDE_SKILL_DIR}/scripts/…` therefore goes red at
+`protocol` on an otherwise-correct run, while the same skill is green on the sandboxed tiers — and a
+hello-world probe is green everywhere and teaches the wrong expectation.
+
+Three ways through, in preference order: script the gate (`--answer` / `answers:`), which is what the
+warning tells you and keeps the run deterministic; set `permission_parity: strict` to deny instead of
+allow, if refusal is what you want to test; or assert `allow_permissive_auto_allow: true` when the
+permissive behaviour is deliberately what the scenario is about.
+
+> **What is NOT established.** Why the host CLI asks for one command and not another was observed, not
+> traced — do not infer a rule for which commands ask from these rows. `microvm` was not measured.
+
+### `baseline agent binary not found` — a Desktop update pruned the pinned ELF
+
+A Desktop update deletes the prior version's staged agent while often leaving an empty version dir, so
+a scenario pinning that agent version resolves to nothing. `doctor` validates the agent for its own
+current baseline, not what each scenario pins, so it can report ready seconds before the run fails.
+
+Prefer **repinning `baseline:` to an installed version** for anything
+reproducibility-bound — you keep an exact pin and move it deliberately. `baseline: latest` never rots
+but silently drifts, so two runs weeks apart are not comparable; a pin and `latest` have opposite
+failure modes.
+
+To find which versions you actually have, do NOT use `cowork-harness list` — it enumerates the baseline
+definitions shipped with the harness, which are present regardless of what Desktop pruned from this
+machine, so a pruned pin lists as healthy. Test the staged binary: read `agentBinary.stagedPath` from
+the baseline JSON, expand the leading `~`, and check it is a FILE — the pruned case leaves the empty
+directory behind, so a directory test passes on exactly the case that fails.
+
+`COWORK_HARNESS_ALLOW_AGENT_FALLBACK=1` runs the newest sibling instead of the pinned
+binary and downgrades the sha check to advisory — that is the substitution the hard failure exists to
+prevent, so use it to unblock once, never in CI.
+
 ### Determinism contract
 
 - `fail` — the default for `run`. On an unscripted gate it hard-errors; the error names the exact

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 3.0.0`
+Self-contained reference for authoring `cowork-harness` scenarios. Tracks `cowork-harness 3.1.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`.
 
@@ -100,7 +100,8 @@ allow_host_writes: true             # OPTIONAL — required to run `hostloop` fi
                                     # Read-only folders and folder-less runs need no opt-in.
 
 allow_host_hooks: true              # OPTIONAL — required to run `protocol` fidelity when a staged plugin
-                                    # declares runnable hooks (`<plugin>/hooks/hooks.json`): L0 passes
+                                    # declares runnable hooks — either `<plugin>/hooks/hooks.json` OR
+                                    # the manifest's `hooks` key: L0 passes
                                     # --plugin-dir, so the CLI executes those hooks as NATIVE HOST
                                     # processes under your account, with no container sandbox. A plugin
                                     # that declares no hooks needs no opt-in, and a misplaced root-level
@@ -420,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` |

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.0` (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.1.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/AGENTS.md

@@ -22,7 +22,7 @@ protocol layer or run-loop bookkeeping in the CLI.
   Don't add a test that needs a live model or Docker to the default suite; that's the `pytest -m cowork` /
   `npm run test:live` lane. Python fast lane (from `python/`): `pytest -m 'not cowork'`.
 - CLI binary `cowork-harness`; env vars `COWORK_HARNESS_*` (+ `COWORK_AGENT_BINARY` / `COWORK_AGENT_IMAGE`) —
-  see README's [Reproducibility knobs](./README.md#reproducibility-knobs) for the full env-var list.
+  see README's [Reproducibility knobs](./docs/cli.md#reproducibility-knobs) for the full env-var list.
   Node ≥ 22.
 - `cowork-harness sync` is **local-only** (needs Desktop + `app.asar`; not on CI). The committed
   `baselines/*.json` are CI's source of truth — never hand-edit release facts into source; they come from

package/CHANGELOG.md

@@ -6,6 +6,165 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [3.1.0] — 2026-08-31
+
+### Fixed
+
+- **The pre-coverage cassette note was a paragraph repeated per file.** It fires on every cassette
+  recorded before `model` joined the session shape — for a consumer with a dozen, a dozen identical
+  paragraphs burying the findings that are genuinely per-file. Cut to one line (370 chars to 157), matching
+  the prompt-assets note beside it; the reasoning stays in `docs/fidelity-gaps.md`. Notes are deliberately
+  **not** aggregated in `verify-cassettes` — it is a per-file audit, and collapsing them would destroy the
+  attribution — so length was the part to fix. The note has always been non-failing: a pre-coverage
+  cassette stays clean, and `replay --strict` exits 0.
+- **The unpinned-model warning told `run` users the flag lived on other lanes.** It named the `skill`,
+  `probe-dispatch` and `chat` lanes for a flag `run` and `record` now accept — caught by running it, not
+  by reading it.
+
+- **`run --model ""` started a spending run instead of failing.** SPEC §CB-2 requires an empty or
+  whitespace model value to be a usage error, never a silently-propagated empty string. `record` inherits
+  that from the shared flag parser; `run` hand-rolls its own loop (the session-less lanes take `--model`
+  out of the leftovers themselves, so the shared parser cannot consume it) and did not enforce it.
+
+### Added
+
+- **`--model <id>` on `run` and `record`.** The `skill`, `probe-dispatch` and `chat` lanes already had it;
+  the two lanes that produce cassettes and CI verdicts did not, so the only way to pin them was editing the
+  session file. Precedence is explicit: an `--model` flag or a `--matrix` `models:` axis (a per-invocation
+  act) outranks the session's `model:`, while `COWORK_HARNESS_MODEL` only fills a gap — a machine-scoped
+  variable must never silently outrank a model the scenario declares, or the run's model becomes a
+  property of the shell it was launched from.
+- **Model provenance on every run, and a warning when nothing pins the model.** `--model` reaches the
+  agent only when a session declares `model:`, so an unset session inherits whatever the local CLI would
+  pick — and because the agent selects part of its system prompt by model capability, that moves the
+  *instructions* it is given, not just answer quality. `--effort` is not symmetric: it is always emitted
+  from the baseline's `spawn.effortDefault`, so an unset session pinned the effort and left the model it
+  applies to floating. Runs now warn when no model resolves (`chat` in its own words), naming the key and
+  the flag. Omitting it is deprecated and becomes an error in the next major — the same path
+  `Scenario.fidelity` took, and deliberately not a hard fail today: the repo chose deprecation for a
+  default with a larger blast radius, and a harder gate for a lesser field would be incoherent with that.
+- **A family pin is checked as family membership, not equality.** `--model opus` is resolved by the agent
+  to a concrete id (`claude-opus-5`), never echoed back, and which member an account resolves it to is not
+  something the harness can know — so comparing the two as strings would report a pinned-and-honored run as
+  `modelPinHonored: false`. `opus`/`sonnet`/`haiku`/`fable` now compare by family and still fail on a
+  wrong-family model; `best` and `opusplan` name no comparable model and stay unverifiable.
+- **`RunResult.modelFallbacks`, `modelPinHonored` and `modelSource`.** Fallbacks come from the agent's own
+  `system`/`model_fallback` event rather than a diff of `models[]` — the event names the trigger, which is
+  what separates a retired or blocked pin (every run falls back the same way until the id changes) from a
+  transient overload. A new `model_fallback` warn signal surfaces it in the verdict; it cannot fire on a
+  healthy run, so it adds no volume to a currently-green one. `modelPinHonored` is three-state on purpose:
+  `true`, `false`, and **absent for unverifiable** — nothing pinned, or no live model evidence. The
+  natural two-state shape reports "we could not tell" as "the pin held", which is a false green, so the
+  no-evidence cases are asserted explicitly rather than left to a truthiness check.
+- **A cassette records the model it was recorded with**, in its `environment` block: the id the agent
+  reported (so it survives a mid-run fallback) plus the source. A cassette recorded with nothing pinned
+  says `unresolved`, which is the difference between "recorded on opus-5 by choice" and "on whatever that
+  laptop happened to pick".
+- **The session fingerprint now covers the pinned model.** Editing `model:` after recording previously
+  moved nothing and `verify-cassettes` said nothing, even though the edit changes what the agent was told.
+  A cassette recorded before this coverage reports **unverifiable** rather than clean — its hash cannot
+  tell "the field was never covered" from "the pin changed since", and claiming otherwise in the remedy
+  would reintroduce the false green the coverage exists to close.
+
+## [3.0.1] — 2026-08-30
+
+### Changed
+
+- **The README now shows the product, not just the argument for it.** Three independent reviews found
+  the same gap: for a test harness, the file a user authors is the most persuasive thing the project
+  owns, and the router split had left it with zero examples. Adds a worked scenario (prompt, scripted
+  answers, assertions) with its verdict output — the scenario is extracted and linted in place, so it is
+  a real file rather than plausible-looking YAML — plus a "What that catches" section built from an
+  actual run where a named skill was offered, declined, and the green answer looked fine anyway
+  (`skillsInvoked: []`, `toolCounts: {}`) — framed as a closed loop, since the author fixed and re-verified
+  it with the same instrument roughly ninety minutes later. An outcome example is a claim about a MOMENT;
+  the better the tool works the faster its own examples get fixed out from under it, so it needs a tense. Also names two things the docs asserted but never taught:
+  diffing the same scenario across two fidelity tiers as a discovery technique, and proving an assertion
+  can fail before trusting it. The requirements block moves below the `claude -p` argument — three
+  reviewers independently reported reading install prerequisites before any reason to want them.
+
+- **The README is now a router, not the whole manual.** It was 975 lines carrying three unrelated
+  audiences at once; it is now **282** and branches to per-audience pages: **`docs/cli.md`** (install,
+  prerequisites, commands, the two files, run output, env knobs), **`docs/companion-skill.md`** (install
+  + orientation; usage stays in `SKILL.md`), and **`docs/ci.md`** (the token-free gate, the packaged
+  Action, the live lane — written to stand alone). The harness's own pipeline and contributor suite moved
+  to `CONTRIBUTING.md`, which keeps `docs/ci.md` about *consuming* the Action rather than about this repo.
+  README keeps what all three audiences share: the fidelity-tier vocabulary, architecture, limitations,
+  the docs index, and versioning. Content moved verbatim — this is a relocation, not a rewrite.
+
+  Nothing is dropped: `Sandboxing` folded into `docs/boundary.md` and `Maintenance` into
+  `docs/maintenance.md`; `Discovery` was already covered in `docs/discovery.md`, so it was deleted rather
+  than duplicated. Every moved relative link was rewritten for its new depth, and every deep link into a
+  moved section was repointed across `docs/`, `examples/README.md`, `llms.txt` and the docs index.
+
+### Fixed
+
+- **`bump-version` did not know about the router-split pages.** `docs/cli.md`, `docs/ci.md` and
+  `docs/companion-skill.md` carry `cowork-harness@^X.Y.Z` install floors that `check:versions` enforces,
+  but the bump tool's target list predated them — so `npm run bump` rewrote every other floor and then
+  failed its own post-write lockstep check. Caught at release time by that self-check rather than
+  shipping a repo with mismatched floors. All three are now registered, and the test pinning that list
+  carries the reason.
+
+
+- **22 dead anchor links introduced by the README router split, and the guard gap that let them ship.**
+  Moving 11 `##` sections out of README left every `](#slug)` link pointing at them dangling — 19 in
+  README (including two badges and the two nav lines the page opened with), plus one each in `AGENTS.md`,
+  `docs/ci.md` and `docs/companion-skill.md`. GitHub fails these silently: the page simply does not
+  scroll. Every file-path link still resolved and every existing guard stayed green, because the anchor
+  suite validated links *into* README and *into* sibling docs but never a page's links to its **own**
+  headings. `test/repo-docs-anchors.test.ts` now covers that third case across root pages and `docs/`,
+  with a canary against a checker that extracts nothing, and was confirmed to fail against the exact
+  regression that shipped. The two nav lines are deleted rather than repointed — they were a
+  table-of-contents for a 975-line page, and "Pick your path" plus the Documentation table now do that job.
+
+  Found by two independent reviewers; the second caught the three non-README instances a README-scoped
+  fix would have missed.
+
+  Follow-up from the same review: three cross-page links still read "…\[Prerequisites](./docs/cli.md#…)
+  **below**" — resolving correctly while the sentence lied, because Prerequisites had moved to another
+  page. Reworded, and guarded: a cross-page link followed closely by "below"/"above" now fails the suite.
+  This half is the nastier one — the link works, so every link checker stays green forever.
+
+- **The `protocol` host-hook consent gate was defeatable by a spelling choice.** `allow_host_hooks`
+  (3.0.0) refuses a spawn until the operator consents to a staged plugin's hooks running as native host
+  processes — but detection keyed only on a file named `hooks.json`, and a plugin may equally declare its
+  hooks in the manifest's `hooks` key (`.claude-plugin/plugin.json`, or a bare `plugin.json`), which is
+  the more common spelling. Such a plugin sailed past the gate: reproduced end-to-end, the hook executed
+  under the operator's own account while the run went green, no consent was asked and no disclosure
+  printed. The same blind predicate feeds the tier-independent disclosure, so those hooks also ran
+  unannounced at `hostloop`. Detection now returns the UNION of both channels, which fixes the gate and
+  the disclosure together since both call through it. The `hooks/hooks.json` placement carve-out is
+  deliberately NOT extended to the manifest — that carve-out exists because a misplaced `hooks.json` is
+  inert, and a manifest-declared hook is live wherever the manifest sits.
+
+  Reported by a consumer during a 3.0.0 adoption pass, with the defect proven from committed cassettes:
+  10 of theirs carried a `SessionStart:startup` hook_started/hook_response pair from a manifest-only
+  declaration, including one recorded at `container`.
+
+### Documentation
+
+- **The pruned-agent-binary failure now has a documented remedy, with the tradeoffs named.** A Desktop
+  update deletes the prior version's staged ELF while often leaving an empty version directory, so a
+  scenario pinning that agent version dies with `baseline agent binary not found`. The code anticipates
+  this by name, but the remedy appeared in no skill surface at all — and an installed companion skill
+  ships without repo `docs/`, so the agent most likely to hit it had nothing to read. Now in
+  `docs/gotchas.md` and the skill's own reference, stating that the three remedies are NOT equivalent:
+  repin for a reproducibility-bound suite, `latest` for a one-off (a pin rots silently, `latest` drifts
+  silently — opposite failure modes), and `COWORK_HARNESS_ALLOW_AGENT_FALLBACK=1` only to unblock once,
+  never in CI, since it runs the newest sibling and downgrades the sha check to advisory.
+
+- **`permissive_auto_allow` and script-running skills is a `protocol`-specific hazard, not a general one.**
+  `Bash` is off-registry (only `Read`/`Glob`/`Grep` are default-allow), but the harness only decides how to
+  ANSWER a permission ask — whether the agent ASKS varies by command AND tier. Measured: at `protocol`, `echo
+  hello` produces no ask (green) while `python3 -c "print(42)"` produces one and fails the guard; the
+  identical command at `container` produces no ask (green), and `hostloop` routes shell through
+  `mcp__workspace__bash` entirely. So a skill running `python3 ${CLAUDE_SKILL_DIR}/scripts/…` goes red at L0
+  and green on the sandboxed tiers, while a hello-world probe is green everywhere and teaches the wrong
+  expectation. `references/fidelity-and-answers.md` carries the measured table and the three ways through; why
+  the host CLI asks for one command and not another is explicitly left untraced, and `microvm` is named as
+  unmeasured.
+
 ## [3.0.0] — 2026-08-29
 
 ### Breaking

package/CONTRIBUTING.md

@@ -108,3 +108,38 @@ When a Desktop release moves something `sync` doesn't read, it reports an `unkno
 ## Reporting issues
 
 Use the issue templates. For anything security/sandbox related, see [SECURITY.md](./SECURITY.md).
+
+## This repo's own CI pipeline
+
+Contributor-facing. For *consuming* the harness in your own CI — the token-free gate and the packaged
+Action — see [docs/ci.md](./docs/ci.md).
+
+The provided [GitHub Actions workflow](https://github.com/yaniv-golan/cowork-harness/blob/main/.github/workflows/ci.yml) runs a **nine-stage pipeline**. The **build** + **test** stages are the token-free gate you can copy into your skill repo; the `floor`, `action-self-test`, `python`, `image-recipe`, `boundary`, `scenarios`, and `parity-drift` stages are this repo's own fidelity self-tests and are not directly portable (they build the harness's Docker image and run harness-specific e2e scenarios — see [`ci-recipe.md`](./.claude/skills/cowork-harness/references/ci-recipe.md) for the skill-repo template):
+
+| Stage | Runs | Needs | Gates |
+|---|---|---|---|
+| **build** | format check · version-lockstep guard · typecheck · source guards · build · CLI smoke · token-free `replay` · `verify-cassettes` · `lint` | nothing | every push/PR |
+| **test** | the unit suite (vitest), sharded 4-way | nothing | every push/PR |
+| **floor** | the unit suite once, unsharded, on Node 22 — the version `engines.node` declares — so the floor is exercised rather than asserted (other jobs run Node 24, the Active LTS line) | nothing | every push/PR; gates the merge context |
+| **action-self-test** | packs this commit and runs the packaged `uses: ./` Action across its full case set — pass (committed example cassette), usage-error fail (nonexistent path), assertion fail (checks the reporter renders a ❌ row), `lint`, and `analyze-skill`; `ci.yml` currently carries 11 `command:` invocations, so re-count here rather than trusting this sentence | nothing | every push/PR |
+| **python** | `pytest` helper self-checks (`python/`, run with `-m 'not cowork'` — the token-free subset; the Docker/token `@pytest.mark.cowork` tests are excluded) | nothing (token-free assertions only) | every push/PR |
+| **boundary** | builds the pinned agent image, brings up the default-deny network, runs `boundary-check`, then `npm run test:live` (live contract tests that guard the binary-resolution assumptions, no token needed) | Docker, arm64 runner | proves the sandbox enforces Cowork's limits — **no API key** |
+| **image-recipe** | compiles `docker/Dockerfile.agent` in **both** variants (lean/core and `COWORK_FULL_PARITY=1`) on an arm64 runner, so a recipe change cannot reach the merge gate uncompiled | Docker, arm64 runner | every push/PR; gates the merge context |
+| **scenarios** | the live scenario suite (mixed `protocol` + `container` fidelity across `examples/scenarios/`), plus the `e2e/scenarios/*.yaml` smoke set (this repo's own L0/L1/hostloop self-tests, `microvm` excluded — needs a real VM); uploads transcripts/egress logs as artifacts; relies on a runner-local staged agent binary (no in-workflow download step). | `ANTHROPIC_API_KEY` | fork PRs: the whole job is skipped (`if:` guard); same-repo without a key: warns and exits 0 |
+| **parity-drift** | reminder to re-`sync` when Desktop updates | nothing | **goes red** if the newest committed baseline is > 90 days old, but sits outside `ci-green`'s `needs:` list, so a red run does not block a merge |
+
+This ordering means cheap checks fail fast, the **boundary parity gate runs without secrets** (so forks get it too), and expensive live runs only happen when a key is present.
+
+
+## The harness's own suite
+
+```bash
+npm run ci            # typecheck + build + test (run format:check separately; NOT the same set as CI's `build` job — see CONTRIBUTING.md)
+npm test              # vitest: decider, egress allowlist, launch plan, example validation
+cowork-harness boundary-check   # self-verify the sandbox (needs Docker; not part of `npm run ci`)
+```
+
+Unit tests cover the scripted-answer logic, the egress allowlist matcher, the session→launch-plan materialization (mounts + discovery settings + env-strip), and a **schema guard** that fails if any shipped baseline/session/scenario stops validating. Add a test alongside any new schema field or `Decider` rule — see [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+> Copy your starting scenarios/sessions from **`examples/`**. The **`e2e/`** directory is the harness's *own* fidelity self-tests (smoke scenarios per tier) — not a template to copy.
+