cowork-harness 1.25.0 → 2.0.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: 1.25.0
-  tracks-harness: cowork-harness 1.25.0 (baseline desktop-1.32885.1)
+  version: 2.0.0
+  tracks-harness: cowork-harness 2.0.0 (baseline desktop-1.34493.1)
 ---
 
 # cowork-harness
@@ -22,8 +22,8 @@ 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 1.25.0` (baseline
-> `desktop-1.32885.1`). If your checkout is newer, prefer the live `--help` and — in a repo checkout —
+> **Version note:** the facts and `file:line` pointers here track `cowork-harness 2.0.0` (baseline
+> `desktop-1.34493.1`). 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.
 
 ## Preflight — make sure the harness can actually run
@@ -39,7 +39,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 **≥ 1.25.0**. If it's missing or older, prefix every command with the version floor `npx "cowork-harness@>=1.25.0" <cmd>` (Node ≥ 22), or install once with `npm i -g "cowork-harness@>=1.25.0"`. **Pin `@>=1.25.0`, never `@latest`** — `@latest` can silently fetch an older CLI and the new commands fail as "unknown command", whereas the floor **fails loud** if no compatible version is published.
+- **CLI on PATH, recent enough?** Run `cowork-harness --version` — this skill needs **≥ 2.0.0**. If it's missing or older, prefix every command with the version floor `npx "cowork-harness@>=2.0.0" <cmd>` (Node ≥ 22), or install once with `npm i -g "cowork-harness@>=2.0.0"`. **Pin `@>=2.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.
 
   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)
@@ -407,7 +407,7 @@ That choice is permanent: the cassette rewrites `scenario.session` and `scenario
 its own directory** at record time, so moving the file later — a different `--out`, a `git mv`, a copy
 into another repo — leaves those unresolvable and
 `verify-cassettes` reports `unverifiable-skill` ("can't verify ⇒ not green", exit 3) until you
-re-record at the new location. **`record` now says so BEFORE it spends:** a pre-flight — at the same
+re-record at the new location — or point `replay`/`verify-cassettes` at the session with `--session <file>`, which resolves it without a re-record. Since 2.0.0 a bare `replay` FAILS on this class rather than warning. **`record` now says so BEFORE it spends:** a pre-flight — at the same
 pre-spend point as the host-inventory refusal, and in `record --dry-run`, so the rehearsal is free —
 warns when the cassette would be written outside the scenario's tree, or when `session:` itself lives
 outside it (an absolute or `~` path: the mirror case, invisible to a check that only looks at where the
@@ -1028,8 +1028,14 @@ repeats the assertion/replay-relevant ones alongside the schema (a scoped subset
 25. **Two distinct host-inventory consent flags — a record-time one and a verify-time one.** `record
     --allow-host-inventory-fixture` is the boolean consent to proceed recording a host-inheriting
     (`protocol`/`hostloop`/`cowork`-resolving-to-hostloop) cassette into a repo-visible path — otherwise
-    `record` refuses (freezing this machine's MCP servers/agents/account into a committed fixture is the
-    risk). `verify-cassettes --allow-host-inventory <regex>` is unrelated: a per-finding suppressor for the
+    `record` refuses before it spends (freezing this machine's MCP servers/agents/account into a committed
+    fixture is the risk). That pre-spend check **warns rather than refuses when the cassette already
+    exists** — refusing would fire on every `--rerecord-stale` pass — and it reads the tier and the
+    destination path, never the bytes. So `record` also scans the FINISHED recording, after redaction and
+    before the write: a `host-inventory`/`machine-inventory` finding on a repo-visible path is
+    **quarantined** to `<runs-root>/quarantine/` with a `.findings.txt` naming what leaked, and the command
+    fails without writing the path you asked for (the recording is not discarded — you paid for it).
+    `verify-cassettes --allow-host-inventory <regex>` is unrelated: a per-finding suppressor for the
     scanner's `host-inventory` class on an already-committed cassette. Passing one where the other command
     wants it fails as an unrecognized flag — they don't interchange. Depth: `references/ci-recipe.md`.
 

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 1.25.0` (baseline `desktop-1.32885.1`).
+Self-contained reference. Tracks `cowork-harness 2.0.0` (baseline `desktop-1.34493.1`).
 
 **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):
@@ -13,7 +13,7 @@ job-summary reporter (verdict table, staleness findings, cost/turns when availab
 ```
 
 The Action's `version` input defaults to `latest` — intentional so a copy-pasted recipe tracks the current
-release; pin an exact version (e.g. `version: "1.25.0"`) for reproducible CI.
+release; pin an exact version (e.g. `version: "2.0.0"`) for 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
@@ -32,7 +32,7 @@ jobs:
       - uses: actions/checkout@v4
       - name: Stage the agent binary (official channel, sha256-verified — see https://github.com/yaniv-golan/cowork-harness/blob/main/docs/maintenance.md)
         run: |
-          V=2.1.234   # match your scenario's pinned baseline's agentVersion
+          V=2.1.237   # match your scenario's pinned baseline's agentVersion
           curl -fSL "https://downloads.claude.ai/claude-code-releases/$V/linux-arm64/claude" -o "$RUNNER_TEMP/claude-$V"
           chmod +x "$RUNNER_TEMP/claude-$V"
           # verify against the committed baseline's sha256 (baselines/desktop-*.json → agentBinary.sha256)
@@ -58,7 +58,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@>=1.25.0"
+- run: npm i -g "cowork-harness@>=2.0.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.
@@ -77,7 +77,20 @@ GitHub-hosted runners, no token/Docker/agent:
 - run: cowork-harness replay cassettes/              # token-free content/structure
 ```
 
-Both lines matter: `replay` alone **warns** on a stale recording and exits 0, so dropping the
+If a cassette has MOVED (a `git mv`, a repo reorg, a copy between projects), staleness becomes
+unverifiable — `verify-cassettes` exits 3 and says the skill dirs are not resolvable. Recover with
+`--session <file>` on either command rather than re-recording:
+
+```yaml
+- run: cowork-harness verify-cassettes cassettes/moved.cassette.json --session sessions/default.yaml
+```
+
+It takes a session (not skill dirs) so `staleness.hash_ignore` survives, refuses a directory target,
+and echoes the dirs it resolved. Full contract:
+[docs/cassette.md](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/cassette.md).
+
+Both lines matter: for the CONTENT-drift classes (`skill`, `shared-root`) `replay` alone **warns** and
+exits 0, so dropping the
 `verify-cassettes` step means a skill edit silently stops being tested. (One command instead of two:
 `replay --fail-on-skill-drift`.)
 
@@ -210,9 +223,23 @@ dollar figures). In a skill repo these cassettes get **committed**. So:
 - **Host-inheriting record refused by default — `--allow-host-inventory-fixture` is the consent.** A
   `protocol`/`hostloop`/`cowork`-resolving-to-hostloop record into a repo-visible cassette path would
   freeze THIS machine's MCP server names, agents, and account metadata into a committed fixture, so
-  `record` refuses outright rather than warn. Pass `--allow-host-inventory-fixture` only when the
+  `record` refuses **before the paid spawn**. Pass `--allow-host-inventory-fixture` only when the
   recording session genuinely has no personal MCP servers or plugins to leak — it is a per-record
   boolean consent, not a pattern.
+
+  Two details that matter for a re-record loop. The pre-spend check **warns rather than refuses when the
+  cassette already exists**, deliberately: refusing there would fire on every `--rerecord-stale` pass and
+  make the escape flag reflexive. And it is a **prediction** — it reads the tier and the destination path,
+  never the resulting bytes, so it can be wrong in both directions.
+
+  So `record` also checks the **evidence**. After redaction and before the write, the finished cassette is
+  scanned; a `host-inventory` or `machine-inventory` finding on a repo-visible path is **quarantined** —
+  written to `<runs-root>/quarantine/` (honouring `--run-dir`/`COWORK_HARNESS_RUNS_DIR`) with a
+  `.findings.txt` sibling naming what leaked, and the command fails without writing the path you asked for.
+  The recording is not discarded; you paid for it. Only the machine-identity classes trigger this —
+  `email`/`currency`/`domain`/`path` are frequently legitimate scenario content, and a gate that fires on
+  those just teaches you to pass the escape flag. Outside a git repo it warns instead: nothing there
+  publishes the file by accident.
 - **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. Non-zero is not one thing, though: exit `1` means verification RAN and found a
@@ -222,6 +249,13 @@ dollar figures). In a skill repo these cassettes get **committed**. So:
   $? -ne 0 ]` tripwire treats both the same — if you need to tell "the gate caught something" apart from
   "the gate couldn't run", branch on the exit code (or parse `--output-format json`'s per-file
   `findings`/`staleness` vs `unverifiable`/`version`/`error` buckets).
+
+  **Do not read `error` as "this file was never scanned".** The privacy scan needs a readable *transcript*
+  (an `events` array of strings), not a *valid* cassette — so a file that fails shape validation is still
+  scanned, and reports its findings **and** its `error`. Each result carries **`privacyScanned`**, which
+  answers that question directly. A gate that must not treat "could not verify" as "verified clean" should
+  key on `privacyScanned === false`, where `findings: []` is an absence of evidence rather than evidence of
+  absence. `--skip-privacy` also reports `false`, for the same reason.
   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.)
@@ -289,7 +323,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@>=1.25.0"
+      - run: npm i -g "cowork-harness@>=2.0.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
@@ -318,7 +352,7 @@ jobs:
             echo "live=true" >> "$GITHUB_OUTPUT"
           fi
       - if: steps.guard.outputs.live == 'true'
-        run: npm i -g "cowork-harness@>=1.25.0"
+        run: npm i -g "cowork-harness@>=2.0.0"
       - if: steps.guard.outputs.live == 'true'
         run: cowork-harness run scenarios/ --output-format json
         env:
@@ -406,19 +440,21 @@ evaluation), not present-and-passing. A CI script that counts assertions will se
 on replay vs live — compare by assertion identity / pass-fail, not by total count. The count of
 skipped live-only assertions is reported on each replay result as `skippedAssertions: {full, partial}`.
 
-## Staleness does NOT fail a replay by default — read it from the JSON
+## Staleness mostly does NOT fail a replay — read it from the JSON
 
-A plain `replay` **warns** on a stale cassette (skill/baseline drift) but stays `ok:true` — a green replay
-does **not** imply the recording is still valid. Each replay result carries `staleness[]`, an array of
+A plain `replay` **warns** on a DRIFTED cassette (skill/baseline drift) but stays `ok:true` — a green
+replay does **not** imply the recording is still valid. **Since 2.0.0 there is one exception:**
+`unverifiable-skill` — staleness that could not be checked at all, most often a cassette that moved —
+FAILS a bare `replay`. Recover with `--session <file>` rather than re-recording. Each replay result carries `staleness[]`, an array of
 `{class, message}`, so a token-free gate can act on it without `ok` being the whole story:
 
 | `class` | meaning | concern |
 |---|---|---|
 | `baseline` | platform baseline moved since record | low (format-compatible) |
 | `skill` / `shared-root` | the skill source the assertions validate drifted | **high** (assertions may validate dead code) |
-| `format` | recorded under an older hash format | re-record once |
+| `format` | the git/raw file-set mode or agent-scope differs from the recording | re-record under the same setting (waivable) |
 | `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 |
+| `unverifiable-skill` | skill dirs unresolvable, **or** the cassette predates the hash-format epoch (v12) so its digest is not comparable | couldn't verify the skill. **Fails a bare `replay`.** For the epoch case try `rehash` first — it migrates without a re-record where it can prove the content unchanged (`rehash <file> --session <s.yaml>` if the cassette moved) |
 | `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 |
 
@@ -433,7 +469,7 @@ fail it either way.)
 To gate in CI, pick the severity you want:
 
 - `replay --strict` — fail (exit 1) on **any** staleness class.
-- `replay --fail-on-skill-drift` — fail only on skill-source drift (`skill` / `shared-root` / `unverifiable-skill`);
+- `replay --fail-on-skill-drift` — fail on the skill-source DRIFT classes (`skill` / `shared-root`); `unverifiable-skill` needs no flag, it fails the default verdict since 2.0.0;
   baseline / format / `unverifiable-baseline` stay non-failing warnings.
   Note `--allow-failing` waives this gate wholesale, including the copy `--assert-from` turns on for you:
   `replay --assert-from … --write --allow-failing` will persist an assert block validated against a

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 1.25.0` (baseline `desktop-1.32885.1`). This is **not** a trim of the full
+Tracks `cowork-harness 2.0.0` (baseline `desktop-1.34493.1`). 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 1.25.0` (baseline `desktop-1.32885.1`).
+Self-contained reference. Tracks `cowork-harness 2.0.0` (baseline `desktop-1.34493.1`).
 
 ## Fidelity tiers (`fidelity:` in the scenario)
 

package/.claude/skills/cowork-harness/references/scenario-schema.md

@@ -1,7 +1,7 @@
 # Scenario & session schema, assertion catalog, web_fetch, full gotchas
 
-Self-contained reference for authoring `cowork-harness` scenarios. Tracks `cowork-harness 1.25.0`
-(baseline `desktop-1.32885.1`). If your checkout is newer, prefer the live [`docs/scenario.md`](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/scenario.md),
+Self-contained reference for authoring `cowork-harness` scenarios. Tracks `cowork-harness 2.0.0`
+(baseline `desktop-1.34493.1`). 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`.
 
 **Minimal scenario** — `prompt` is the only required field:
@@ -107,7 +107,7 @@ form a relocatable bundle. `~` expands to home.
 > references relative to **its own** directory at record time (`scenario.session` and
 > `scenarioSource`), so moving it afterwards — a different `--out`, a
 > `git mv`, a copy into another repo — leaves them unresolvable and `verify-cassettes` reports
-> `unverifiable-skill` ("can't verify ⇒ not green", exit 3) until you re-record at the new location.
+> `unverifiable-skill` ("can't verify ⇒ not green", exit 3) until you re-record at the new location, or pass `--session <file>`.
 > Decide where a cassette will live *before* you record it.
 
 ## Session YAML

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 1.25.0` (baseline `desktop-1.32885.1`), same as SKILL.md's front-matter. Recipe 2's `resolved-tier`/`unverifiable-tier` staleness classes and
+Tracks `cowork-harness 2.0.0` (baseline `desktop-1.34493.1`), 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.
 

package/CHANGELOG.md

@@ -6,6 +6,302 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [2.0.0] — 2026-08-21
+
+### Changed — BREAKING (requires a major bump; see [SPEC.md §12](./SPEC.md#12-versioning--the-10-compatibility-contract))
+
+- **HASH-FORMAT EPOCH — `cassetteVersion` 12. Every cassette carrying a `skillHash` fails a bare `replay`
+  until it is migrated.** Read that sentence literally: this is not a warning you can defer.
+
+  **Migrate with one command.** `cowork-harness rehash <dir/>` proves each cassette's content unchanged and
+  relabels it in place — no re-record, no model calls, no cost. For a cassette that has MOVED (a `git mv`, a
+  repo reorg, a copy into another project) its skill sources cannot be resolved from its own directory, so
+  use `cowork-harness rehash <file.cassette.json> --session <session.yaml>`. Anything `rehash` cannot prove
+  is refused rather than migrated, and does need a real re-record.
+
+  **After a successful `rehash`, the epoch is cleared and you are done with it.** Migration does not touch
+  the other staleness classes, and it does not need to: `baseline`, `format` and `prompt-assets` behave
+  exactly as before — they surface in `staleness[]`, print a `::warning::`, and **exit 0**. Only
+  `unverifiable-skill` fails a bare `replay`, which is what the epoch produces and what `rehash` clears. So
+  a cassette that also carries, say, baseline drift migrates cleanly and then goes green with that drift
+  still reported as a warning, exactly as before this release. (Measured, not inferred: a cassette with a
+  deliberately wrong `fingerprint.baseline` replays `pass: true`, exit 0, with a non-failing `[baseline]`
+  finding.)
+
+  **`verify-cassettes` is stricter than `replay`, and that is not new.** It treats ANY staleness finding as
+  not-green, so a migrated cassette that still carries baseline drift replays green and reds the
+  verification gate — as it did before this release, for the same reason. Clear it by re-recording, or by
+  re-stamping `fingerprint.baseline` where the baseline moved without changing anything the recording
+  exercises; [docs/cassette.md](./docs/cassette.md#cassette-versioning) covers when that re-stamp is honest
+  and when it is not. This release also ships a new platform baseline, so expect that drift on cassettes
+  recorded against the previous one.
+
+  **What changed.** A plugin manifest now folds into `skillHash`/`contentSig` through canonical (JCS-style)
+  serialization instead of insertion-order `JSON.stringify`, so **reordering keys in `plugin.json` no longer
+  re-stales every cassette that hashes it** — semantically identical input now produces an identical digest.
+  `contentSig` additionally folds the directory markers `skillHash` has always folded, so an added or removed
+  **empty directory** is finally visible to it; `CONTENTSIG_ALGO` moves 4 → 5 to say so. A new
+  `fingerprint.hashFormat` records which transform produced the digests — **absent means the legacy
+  pre-v12 transform, never raw bytes**, since every cassette already on disk carries version-stripped
+  manifest digests.
+
+  **Why it fails rather than warns.** A pre-epoch digest and a post-epoch digest came from different
+  algorithms; they cannot be compared at all. That is `unverifiable-skill` — "this was not verified" — and
+  not `format`, which is waivable and exits 0. A warning everyone ignores for a release is exactly the
+  green-against-unverified state the strict-replay change below exists to end, and on the day of an epoch it
+  would apply to every cassette in existence.
+
+  **Some cassettes will migrate with an unchanged digest.** A manifest whose keys were already in canonical
+  order, or a tree with no manifest at all, hashes identically under both algorithms. Those are still
+  flagged and migrated, **by recorded version rather than by whether the number moved** — otherwise they
+  would pass unlabelled, and at the next epoch nobody could tell which algorithm produced them.
+
+  `cassetteVersion` now means the minimum reader for the **whole cassette**, not just for its `scenario`
+  keys: a v11 reader handed a v12 cassette would recompute legacy digests and report drift that is not
+  there. The scenario-aware differential still applies above that floor.
+
+- **A bare `replay` now FAILS when skill staleness cannot be verified** (`unverifiable-skill`), where it
+  previously warned on stderr, recorded the class in `staleness[]`, and exited `0`. "Could not be checked
+  at all" and "checked and unchanged" are different claims and only the second is green — a cassette that
+  had silently stopped proving anything kept passing the lane most people run, and green-against-unverified
+  is worse than a loud red because silence prompts a re-record while green does not. The major is required because a previously-green
+  input now exits non-zero — `verdict.pass` / `ok` and the per-command exit behaviour are covered surfaces
+  ([SPEC.md §12](./SPEC.md#12-versioning--the-10-compatibility-contract)). Note the *meaning* of exit 1 is
+  unchanged (still assertion-or-agent failure), so §11's exit-code table needs no edit; what changed is
+  which inputs reach it.
+
+  **Deliberately narrow.** The content-drift classes (`skill`, `shared-root`) still require
+  `--fail-on-skill-drift`, so that flag keeps its meaning and no inverse escape hatch is needed.
+
+  **One exception, and it exists to stop a false green:** under an explicit `--session`, the drift classes
+  are escalated too. Without that, pointing `--session` at a WRONG but resolvable tree would turn
+  `unverifiable-skill` (a hard fail) into ordinary `skill` drift (warn-only) — so the flag could be used,
+  accidentally, to silence the very gate it exists to help you escape. `--session` is an escape from
+  "cannot verify", never from "verified, and it changed".
+
+  **Migration.** The commonest cause is a cassette that MOVED — use the new `--session <file>` below
+  rather than re-recording. If you genuinely want the old behaviour for a lane, it was never expressible
+  as a flag and still isn't; fix the resolution instead.
+
+- **`verify-cassettes --output-format json` gained a REQUIRED `privacyScanned` field on every result.**
+  `schema/verify-cassettes.json` is a covered 1.0 surface ([SPEC.md §12](./SPEC.md#12-versioning--the-10-compatibility-contract)),
+  and `privacyScanned` is now in its `required` list — so a consumer validating this build's output against
+  an older copy of the schema is unaffected, but one validating an OLDER CLI's output against the NEW schema
+  will fail. It is emitted on every return path, so anything keying on it can rely on it.
+
+  The field exists because `error` became ambiguous. A cassette that fails SHAPE validation is now still
+  privacy-scanned (see Fixed, below), so `error` covers both "never scanned" and "scanned fine, just not
+  replayable" — and a gate cannot tell those apart from it. **If you have CI keyed on `error` meaning "this
+  file was not checked", that reading is now wrong; switch to `privacyScanned === false`,** where
+  `findings: []` is an absence of evidence rather than evidence of absence. `--skip-privacy` also reports
+  `false`, for the same reason.
+
+### Added
+
+- **`provenance.asarGateIds` — a gate-membership change is now nameable.** A baseline recorded
+  `provenance.fcache` as two aggregates and a timestamp, so when a sync moved `featureCount` **271 → 278**
+  nothing could say *which* seven arrived, a count-neutral membership swap was invisible entirely, and
+  `content16`'s diff line had to hedge "membership **and/or** values moved". The fcache is also
+  server-refreshed on its own schedule (3.7–20.8 min observed), so a count delta between two baselines is
+  a net over days of rollout rather than a fact about the Desktop release — and the previous payload is
+  overwritten in place, so the question goes unanswerable the moment you think to ask it.
+
+  Baselines now additionally record the gate ids **this release's own bundle references**, sorted. That is
+  a pure function of the shipped asar: reproducible by anyone, stable across the fcache's refetches, and
+  attributable to the release. Diffing two baselines names the delta outright (1.32885.1 → 1.34493.1:
+  **+14 / −1**), and `sync --diff` prints the ids rather than a count.
+
+  It is deliberately **not** intersected with the syncing machine's fcache. Gate membership varies by
+  account segment, so filtering through one machine would both leak which gates that operator is served
+  and drop DARK gates — 51 of the recorded ids are absent from the live fcache, `enableToolSearchAuto`
+  among them. To turn an id into a name, grep it as a quoted literal in the extracted bundle; the call
+  site names it, which is how `PINNED_GATES` was built in the first place.
+
+- **`record` now scans what it wrote, and quarantines a leaking recording instead of publishing it.**
+  `scanCassette` had exactly one production call site — `verify-cassettes` — which runs at commit time at
+  the earliest. `hostInventoryPreflight` does fire before the paid spawn, but it reads the tier and the
+  destination path, never the resulting bytes: it is a prediction, and it can be wrong in both directions.
+
+  After redaction and before the write, the finished cassette is scanned. A `host-inventory` or
+  `machine-inventory` finding on a repo-visible path writes the recording to `<runs-root>/quarantine/`
+  (honouring `--run-dir` / `COWORK_HARNESS_RUNS_DIR`) alongside a `.findings.txt` naming exactly what
+  leaked, then fails without writing the requested path.
+
+  Three things about that policy are deliberate. **Quarantine, not discard** — the tokens are already
+  spent, and throwing the recording away is both the most expensive answer and the one most likely to end
+  in "just commit it anyway". **Only the machine-identity classes trigger it** — `email` / `currency` /
+  `domain` / `path` findings are frequently legitimate scenario content, and a gate that fires on those
+  teaches the operator to pass the escape flag by reflex, which is how a safety gate becomes decoration.
+  **Outside a git repo it warns instead of quarantining** — nothing there publishes the file by accident,
+  so quarantining would be obstruction rather than protection. If the runs root is itself inside a working
+  tree, quarantine falls back to the OS temp dir and says so; moving a leak into another committable
+  location would be theatre.
+
+  `--allow-host-inventory-fixture` (the flag the preflight already honours) still writes the file, and now
+  reports what it is publishing rather than going quiet.
+
+  Coverage is labelled honestly: the policy (`classifyRecordLeak`) and the effect (`quarantineCassette`)
+  are pure, exported and mutation-tested; the *wiring* inside `recordScenarioObject` needs a live spawn to
+  reach, so it is guarded structurally — the same split this repo already uses for `buildCassette`.
+
+- **Corrected a standing inaccuracy in the record-consent docs.** `SKILL.md` and `ci-recipe.md` both said
+  the host-inventory preflight "refuses outright rather than warn". It refuses for a **new** cassette path
+  but **warns** for one that already exists — deliberately, since refusing there would fire on every
+  `--rerecord-stale` pass and make the escape flag reflexive. That warn path was the gap the record-time
+  quarantine above now covers, so both documents now say which is which.
+
+
+- **Platform baseline `desktop-1.34493.1` (agent `2.1.237`).** The Cowork system prompt, both sub-agent
+  append branches, all 28 pinned gate states, the VM egress policy and the 22-key spawn env are all
+  unchanged — re-derived from the new bundle rather than inferred from an absent diff row (only the
+  minified prompt constant id rotated). `sync` reports no unknown deltas.
+
+  The substantive change is in the **agent**, and an asar-only pass cannot see it: `2.1.237` adds six
+  Cowork-specific risk categories to the auto-mode permission rubric's vocabulary —
+  `cowork_delete_grant`, `cowork_folder_access`, `cowork_run_routine_now`,
+  `cowork_scheduled_task_delete`, `cowork_scheduled_task_write`, `cowork_skill_persistence` — in both the
+  native binary and the VM ELF. They are **inert for this harness**: the rubric is entered only on
+  `permissionMode === "auto"`, which no scenario can request and no baseline pins (now pinned by
+  `test/auto-mode-unreachable.test.ts`). They matter because the rubric's reach now names operations the
+  harness does model, so the existing "auto-mode permission rubric is not modeled" gap has moved from
+  generic infrastructure risk into Cowork territory. The agent's env-flag export table also moves
+  524 → 533; none of the additions are set by the Cowork spawn.
+
+  All three committed example cassettes are re-recorded against this baseline and stamp v12 /
+  `hashFormat: "jcs1"`.
+
+- **`--session <file>` on `replay` and `verify-cassettes`** — the escape hatch for a relocated cassette. A
+  cassette stores `session:` relative to its own directory, so any move (`git mv`, a repo reorganisation, a
+  copy into another project) made skill staleness permanently unverifiable with no way to say where the
+  tree went; the only remedies were moving the file back or re-recording. It takes a **session**, not skill
+  directories, because `staleness.hash_ignore` is a session-level field that is not stored in the cassette —
+  an override carrying only directories would silently change the hash boundary. Refused for a directory
+  target, for a path that is not a file, and for inline scenarios; the resolved session **and the dirs it
+  produced** are echoed on stderr, since an override that silently pinned the wrong tree would manufacture
+  false greens. An explicit override is trusted: a mismatch under it is reported as real drift rather than
+  downgraded.
+
+- **Duplicate manifest paths are now reported as ambiguous** instead of silently under-reported. Two mounts
+  can each contribute `skills/x/SKILL.md`, and every consumer keys `fileSigs` by path, so duplicates
+  collapsed to the last occurrence and the changed-file list could name the wrong file or none. Drift was
+  always still DETECTED — the hash folds every entry — so this is an attribution fix, not a false-green fix.
+  Exact attribution needs per-root identity in the digest, which is a hash-format epoch change.
+
+### Fixed
+
+- **A cassette that fails shape validation is now privacy-scanned.** `verify-cassettes` does two
+  independent jobs — a privacy scan and a staleness check — and both sat behind one strict `readCassette`.
+  Any document that failed shape validation returned early, so `scanCassette`, on the very next line, never
+  ran: the file was reported with zero findings, which reads in every summary as `0 PII finding(s)`. That is
+  a clean-looking number from an instrument that never ran, and a file too broken to replay is exactly the
+  kind of file a leak arrives in. Measured on a malformed fixture carrying MCP server names, an account org
+  and an agent roster: **0 findings and exit 3 before, 6 findings and exit 1 after.**
+
+  The fix is a read-boundary **split**, not a loosening: `readCassette` stays exactly as strict (replay,
+  staleness and the hash-format epoch's version/`hashFormat` invariant all depend on it). A separate
+  `readCassetteForScan` reads the transcript only, requiring nothing but `events: string[]`, and
+  `scanCassette`'s parameter type is narrowed to the fields it genuinely reads — so a future scan axis that
+  reaches for some other field is a compile error until the projection carries it, rather than silently
+  reading `undefined` off a partial document. Narrowing that type immediately turned up five fields the
+  scan reads that a hand audit had missed (`userVisibleRoots`, `scenario.name`, `scenario.session`,
+  `scenarioSource`, `environment.agentImage.ref`).
+
+  The projection also **fails closed on an unrecognized tier**. `scanCassette` exempts a positively-sealed
+  tier and scans everything else including `undefined`, but it tests set membership — so an arbitrary
+  string (`"garbage"`, a typo'd `"containerr"`) is neither, and would have skipped the structural
+  host-inventory scan entirely. The strict reader cannot produce that; this one can, because malformed
+  input is its whole job.
+
+- **The pre-commit cassette gate now fails CLOSED.** `.githooks/pre-commit` tested `hook_status` for `1`
+  (block) and `3` (warn) and let every other outcome through to a successful commit, so the guard switched
+  itself off — silently — on outcomes that ordinary refactors produce: exit `2` (`examples/replays/` renamed
+  or emptied, or any CLI flag renamed), exit `127` (`node` off `PATH`), and a missing `dist/cli.js`, which is
+  the state of a fresh clone, a `git clean -xdf`, a branch switch, and any tree with a failing typecheck
+  (`npm run build` does `rm -rf dist` first). None of those fail a test elsewhere. Anything that is not a
+  proven clean `0` now blocks.
+
+  This matters more than a local convenience: `ci.yml` triggers on `push: [main]` and `pull_request`, but the
+  documented workflow lands with `merge --ff-only` into `main` and pushes afterwards — so on that path the
+  hook is not one layer of two, it is the only gate, and what it waves through is already public when CI
+  reds.
+
+- **An unscannable cassette no longer commits unscanned.** Exit 3 folds together unverifiable *staleness*,
+  an unsupported `cassetteVersion`, and a per-file read error. Only the first means "we looked and could not
+  conclude"; the other two mean the privacy scan never ran, so there is no evidence either way about host
+  inventory — and a cassette recorded by a newer CLI than the committer's `dist/` committed with nothing
+  having checked it. The hook now splits exit 3 by cause (`--output-format json`) and blocks on the two that
+  are not staleness, in line with the `can't verify ⇒ not green` rule the CLI states everywhere else. A
+  payload it cannot interpret is treated as undetermined, not as staleness.
+
+- **The gate no longer misses cassettes by filename.** `record --out` accepts an arbitrary path and does not
+  validate the suffix, so a recording written to e.g. `notes/run.json` was invisible to the hook's trigger,
+  to CI's pathspec, and to `git ls-files '*.cassette.json'`. The hook trigger is now content-derived (any
+  staged `.json` whose staged blob carries the `"generator": "cowork-harness"` marker), and CI cross-checks
+  the suffix-derived set against the content-derived one. Separately, `resolveInputs` does not recurse, so
+  `examples/replays/sub/x.cassette.json` was reachable by neither the directory scan nor the per-file loop
+  (which excluded all of `examples/replays/`); the exclusion is now scoped to files *directly* in that
+  directory.
+
+- **CI scans every tracked cassette, not just one directory.** The sweep is derived from `git ls-files`
+  rather than a hard-coded path, fails loudly if the pathspec ever matches zero files (an `xargs -r` sweep
+  exits 0 on no matches and reads as success), and carries exactly one exclusion with its reason recorded:
+  `test/evals/files/report-check.cassette.json` is an eval *attachment*, not a recording — it has no
+  `scenario.session`, so `readCassette` rejects its shape before the scan can run. Measured rather than
+  assumed: adding a `session` field does not make it verifiable, it converts the exit 3 into an exit 1 on
+  baseline drift for a fixture that is never re-recorded.
+
+- **The local gate is no longer laxer than the CI gate on the same directory.** The hook passed
+  `--allow-email`/`--allow-domain` suppressions that `ci.yml` does not; the committed fixtures verify clean
+  without them, so they are gone. Its scratch file also moved from a predictable `/tmp` path to `mktemp`, and
+  a clean run now says so instead of passing in silence.
+
+- **`sync` derived the enforced egress allowlist from a bundle-wide regex, and Desktop 1.34493.1 made that
+  wrong.** `network.allowDomains` is the allowlist the harness ENFORCES (`boundaryAllowList` plus the
+  session egress plan), but it was built by matching every `*.anthropic.com` / `*.claude.ai` literal in the
+  whole app bundle. 1.34493.1 added a webview first-party-origin classifier — a navigation-trust tier naming
+  `www.claude.ai` and `staging.claude.ai` — and the sweep pulled both into the enforced list, which would
+  have permitted egress Cowork denies.
+
+  Narrowing the sweep was investigated and rejected: on the first-party deployment there is nothing to
+  narrow to. The 1p class returns `vmEgressPolicy(){return null}`, so `resolveVmAllowedDomains` falls
+  through to the session's **server-delivered** `egressAllowedDomains`, and the only host the bundle
+  contributes is the OTLP endpoint. `vmAllowedDomains`/`firewallAlso` are the 3p path and Desktop's own
+  renderer endpoints — neither is the VM allowlist. Any bundle scan is unsound both ways: blind to
+  server-delivered hosts, open to hosts that are not egress.
+
+  `network.allowDomains` is therefore a **pinned, hand-curated list carried forward** from the newest
+  committed baseline, and a new fail-closed `checkEgressContractFacts` guards the three constructions that
+  justify pinning (the 1p null policy, the resolver's fall-through to its caller-supplied argument, and the
+  OTLP-only augmentation) — so a real change in how Cowork computes egress hard-fails `sync` instead of
+  silently rewriting the list. The baseline's `network.$comment` now records that provenance and names the
+  entries that are unverified as VM egress; `network` became a `looseObject` so that note survives loading.
+
+- **Consumers of 1.25.0 were NOT affected by this** — it is recorded because the shape is worth knowing,
+  not because it shipped. While building `--session`, skill staleness, session-shape staleness, label
+  provenance and the skill-hash debug dump could each have resolved a different session. The cassette-relative join was duplicated byte-identically
+  in three functions and `sessionFingerprintDrift` accepted an override its only caller never passed, so
+  `--session` would have verified skill content against the override while session shape still resolved the
+  recorded path — reporting "clean" on an axis that hard-fails when used normally. All consumers now share
+  one resolver.
+
+- **An unresolvable session now says WHY** — missing file, unreadable/unparseable YAML, or declared mounts
+  that do not exist — instead of one undifferentiated message. Those point at different fixes, and only the
+  first looks like a relocation, so it also names the remedy.
+
+### Known limitations (documented, not fixed)
+
+- **Multi-root skill hashing is order-dependent.** `hashSkillDirs` folds roots sorted by absolute path
+  while deliberately excluding a root's own name from the digest, so identical content at differently
+  sorting directory names hashes differently. One axis (root ORDER) fails loudly as false drift. A second is
+  worse: roots fold into one digest with no root-boundary marker, so moving a file BETWEEN roots is
+  invisible — a genuine false green. Multi-root cassettes are still not refused, because none exists in
+  any reachable corpus and refusing would break input nobody has; instead replay now emits a note when a
+  cassette records two or more roots. Fixing it needs a hash-format epoch.
+  Not scheduled: no multi-root cassette exists in any reachable corpus (32 cassettes on the widest
+  denominator across three repos), and no session declares 2+ plugin/skill roots. Pinned by tests in
+  `test/skill-hash.test.ts` so the eventual fix is a deliberate change.
+
+
 ## [1.25.0] — 2026-08-20
 
 ### Added

package/CONTRIBUTING.md

@@ -88,6 +88,18 @@ When a Desktop release moves something `sync` doesn't read, it reports an `unkno
 
 ## Commit & PR
 
+- **A pre-commit hook gates cassettes, and it fails CLOSED.** `npm install` points `core.hooksPath` at
+  `.githooks/`. Staging a `baselines/desktop-*.json`, any `*.cassette.json`, or any `.json` whose staged
+  content carries the `"generator": "cowork-harness"` marker runs `verify-cassettes` — and **anything that
+  is not a proven clean exit `0` blocks the commit**, including a missing `dist/cli.js`. That last one
+  catches people out: `npm run build` does `rm -rf dist` first, so a tree with a failing typecheck has no
+  built CLI at all. Run `npm run build` and re-commit. The check is scoped to commits that stage one of
+  those files, so an ordinary source commit is unaffected.
+
+  It is deliberately strict because for a maintainer it is the *only* pre-publication gate: CI triggers on
+  `push: [main]` and `pull_request`, but the local flow lands with `merge --ff-only` and pushes afterwards,
+  so by the time CI reds, a leaked recording is already in public history. `git commit --no-verify`
+  bypasses it — if you need that for anything other than a broken hook, say so in the PR.
 - Conventional, imperative commit subjects (`add …`, `fix …`, `parity: sync to <ver>`).
 - Open PRs against `main`. CI runs a nine-stage pipeline (`build`, `test`, `action-self-test`, `python`, `image-recipe`, `boundary`, `scenarios`, `parity-drift`, `floor` — see `ci.yml`) on every PR including forks (no secrets needed) except `scenarios`; live scenarios only run on same-repo PRs/pushes with `ANTHROPIC_API_KEY` set.
 - **Which stages actually block a merge is narrower than the pipeline.** The branch ruleset requires status *contexts*, not jobs, and the `ci-green` aggregator that carries the `typecheck · test · build` context declares `needs: [build, test, floor, image-recipe]` — so `action-self-test`, `boundary`, `scenarios`, and `parity-drift` run and report but do **not** gate. (`python` **does** gate: its job name is the second required context, `pytest helper lane (-m 'not cowork')` — this line previously listed it as non-gating, which was wrong.) Read a red one as a real signal anyway: `boundary` in particular is the secrets-free proof that the sandbox enforces Cowork's limits. `ci.yml`'s comment above `ci-green` is the authority on the current wiring.