cowork-harness 2.0.1 → 2.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: 2.0.1
-  tracks-harness: cowork-harness 2.0.1 (baseline desktop-1.34493.1)
+  version: 2.1.0
+  tracks-harness: cowork-harness 2.1.0 (baseline desktop-1.34493.1)
 ---
 
 # cowork-harness
@@ -22,7 +22,7 @@ flagged with a loud `::warning::`, not silent — auto-answer a gate, observe an
 allowlist). This skill exists mostly to keep you out of those traps — the Gotchas section below is
 the highest-value part. Read it.
 
-> **Version note:** the facts and `file:line` pointers here track `cowork-harness 2.0.1` (baseline
+> **Version note:** the facts and `file:line` pointers here track `cowork-harness 2.1.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.
 
@@ -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 **≥ 2.0.1**. If it's missing or older, prefix every command with the version floor `npx "cowork-harness@^2.0.1" <cmd>` (Node ≥ 22), or install once with `npm i -g "cowork-harness@^2.0.1"`. **Pin `@^2.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 **≥ 2.1.0**. If it's missing or older, prefix every command with the version floor `npx "cowork-harness@^2.1.0" <cmd>` (Node ≥ 22), or install once with `npm i -g "cowork-harness@^2.1.0"`. **Pin `@^2.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)
@@ -656,7 +656,7 @@ than a stuck `"running"`.)
 ### Place assertions in the right CI lane
 
 CI placement: a **token-free `replay` PR gate** (content/structure only) + a **nightly live `run`**
-(filesystem/egress). Fastest setup: `uses: yaniv-golan/cowork-harness@main` (a packaged GitHub Action with a
+(filesystem/egress). Fastest setup: `uses: yaniv-golan/cowork-harness@v2` (a packaged GitHub Action with a
 PR job-summary reporter). See `references/ci-recipe.md` for the Action, the manual step-by-step form, and
 the four-stage pipeline.
 

package/.claude/skills/cowork-harness/references/ci-recipe.md

@@ -1,19 +1,23 @@
 # CI recipe — replay vs live lanes
 
-Self-contained reference. Tracks `cowork-harness 2.0.1` (baseline `desktop-1.34493.1`).
+Self-contained reference. Tracks `cowork-harness 2.1.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):
 
 ```yaml
-- uses: yaniv-golan/cowork-harness@main
+- uses: yaniv-golan/cowork-harness@v2
   with:
     command: replay
     path: cassettes/
+    version: "^2"              # hold the major; see below
 ```
 
-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: "2.0.1"`) for reproducible CI.
+**These recipes pin `version: "^2"`.** The Action's `version` input *defaults* to `latest`, which means a
+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: "2.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
@@ -43,10 +47,11 @@ jobs:
           echo "COWORK_AGENT_BINARY=$RUNNER_TEMP/claude-$V" >> "$GITHUB_ENV"
           # Background on the provenance chain: the "Agent-binary provenance" section of
           # https://github.com/yaniv-golan/cowork-harness/blob/main/docs/maintenance.md
-      - uses: yaniv-golan/cowork-harness@main
+      - uses: yaniv-golan/cowork-harness@v2
         with:
           command: run
           path: scenarios/
+          version: "^2"
           anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
 ```
 
@@ -62,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@^2.0.1"
+- run: npm i -g "cowork-harness@^2.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.
@@ -110,20 +115,28 @@ Action has no input for, and it creates a coupling nothing checks:
 
 > **If a flag in `extra-args` was added in release X, floor that step's `version` to `>=X`.**
 
-`version` defaults to `latest`, and accepts **any npm range** — not just an exact pin. So:
+`version` defaults to `latest`, and accepts **any npm range** — not just an exact pin. Leave it off unless
+you have a reason:
 
 ```yaml
-- uses: yaniv-golan/cowork-harness@main
+- uses: yaniv-golan/cowork-harness@v2
   with:
     command: lint
     path: scenarios/
-    version: ">=1.11.0"          # --min-severity landed in 1.11.0
-    extra-args: --min-severity WARN
+    version: "^2"                       # holds the major
+    extra-args: --min-severity WARN     # needs a CLI >= 1.11.0; any 2.x satisfies that
 ```
 
-Without the floor, an older CLI fails the step with `unrecognized arguments: --min-severity WARN` (exit 2,
-wrapped in an `ok:false` envelope) — it does **not** degrade gracefully. An exact pin is fine for
-reproducibility, but it rots the moment a recipe adopts a newer flag; a floor expresses the real dependency.
+**If a flag you pass in `extra-args` landed in a specific release, bound the range — don't write a bare
+floor.** `>=1.11.0` reads as "at least 1.11.0" and silently means "and every future major too", so a
+recipe written that way hands a copy-paster the next major with no say in it. Anchor it at the current
+major instead — `version: "^2"`, which is what the steps above use — keeping the floor's intent while
+stopping at the major boundary. An exact
+pin (`version: "2.0.1"`) is the right choice when you want byte-reproducible CI, at the cost of rotting the
+moment a recipe adopts a newer flag.
+
+Without a satisfied floor, an older CLI fails the step with `unrecognized arguments: --min-severity WARN`
+(exit 2, wrapped in an `ok:false` envelope) — it does **not** degrade gracefully.
 
 
 The harness has two execution lanes with different cost, coverage, AND infrastructure requirements.
@@ -307,7 +320,7 @@ A typical skill repo runs four stages, fastest/cheapest first:
 
 ## GitHub Actions sketch
 
-The PR gate below is the manual, step-by-step version of what `uses: yaniv-golan/cowork-harness@main` does
+The PR gate below is the manual, step-by-step version of what `uses: yaniv-golan/cowork-harness@v2` does
 in one step (see the top of this doc) — reach for this form when you need independent per-command
 gating/annotations rather than one action run per command. The nightly live job has no packaged-Action
 equivalent yet (the Action's `command: run` mode needs a self-hosted runner with Docker + the agent binary
@@ -327,7 +340,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@^2.0.1"
+      - run: npm i -g "cowork-harness@^2.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
@@ -356,7 +369,7 @@ jobs:
             echo "live=true" >> "$GITHUB_OUTPUT"
           fi
       - if: steps.guard.outputs.live == 'true'
-        run: npm i -g "cowork-harness@^2.0.1"
+        run: npm i -g "cowork-harness@^2.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 2.0.1` (baseline `desktop-1.34493.1`). This is **not** a trim of the full
+Tracks `cowork-harness 2.1.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 2.0.1` (baseline `desktop-1.34493.1`).
+Self-contained reference. Tracks `cowork-harness 2.1.0` (baseline `desktop-1.34493.1`).
 
 ## Fidelity tiers (`fidelity:` in the scenario)
 

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

@@ -1,6 +1,6 @@
 # Scenario & session schema, assertion catalog, web_fetch, full gotchas
 
-Self-contained reference for authoring `cowork-harness` scenarios. Tracks `cowork-harness 2.0.1`
+Self-contained reference for authoring `cowork-harness` scenarios. Tracks `cowork-harness 2.1.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`.
 

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

package/CHANGELOG.md

@@ -4,6 +4,261 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). The project uses
 [Semantic Versioning](https://semver.org/); as of 1.0.0, a backwards-incompatible change to a covered surface ([SPEC.md §12](./SPEC.md#12-versioning--the-10-compatibility-contract)) requires a major bump.
 
+## [2.1.0] — 2026-08-24
+
+### Changed
+
+- **`rehash` leads with the split, and PARTIAL success has its own exit code (`4`).** The summary used to
+  print last, after every per-file line had scrolled past — and those two counts *are* the decision:
+  commit what migrated and budget a re-record for the rest, versus nothing here is salvageable. It now
+  prints first, with the per-file lines as the detail behind it.
+
+  **`4 migrated, 18 failed` and `0 migrated, 22 failed` both exited `1`**, which made a shell consumer
+  unable to tell apart two situations demanding opposite responses. The JSON envelope always carried the
+  split as `migrated`/`skipped`/`errors`; a bare terminal run did not. `rehash` now exits `0` (all
+  migrated, or nothing needed migrating) / **`4`** (partial) / `1` (nothing migrated and at least one
+  could not) / `2` (usage).
+
+  **This is a behaviour change for anyone branching on `rehash`'s exit code** — a script testing
+  `rc == 1` for "something failed" will miss the partial case, though `rc != 0` is unaffected. It ships in
+  a minor deliberately: `rehash`'s codes were documented **nowhere** — zero mentions in its `--help`,
+  absent from SPEC §11 — so there was no published contract to break, and a consumer on `rc == 1` was
+  relying on observed behaviour. They are now documented in both places. `4` rather than `3` because the
+  code space is per-command and `3`'s "could not verify" meaning is load-bearing on `verify-cassettes`.
+
+- **The batch cost estimate now reports its basis instead of claiming authority.** `estimatedCostUsd` is
+  `sum(max(local run history))` — a max over whatever *this machine* has run. The line already qualified
+  the partially-priced case with `— LOWER BOUND`, but the fully-priced case said
+  `(all N scenario(s) priced from prior runs)`, which is an active claim of completeness and was the one
+  case that said nothing qualifying. At a new baseline or a new agent binary the history describes a
+  materially different configuration, so the estimate can **under**-predict exactly when it is most
+  consulted — a consumer wrote "that is the ceiling, not the scope" into a plan off this line and had to
+  retract it.
+
+  The line now carries `basis: N prior run(s) on THIS machine, thinnest scenario has M; a max over that
+  history, NOT a bound`, and the JSON payload gains `estimateBasis`
+  (`{source, pricedRuns, thinnestScenarioRuns}`). `thinnest` is the useful half: a scenario with one prior
+  run contributes a single sample, not a worst case. Wired through `pricedRunCount`, which had been
+  exported and doc-commented *"for messages that report their own basis"* with zero callers.
+
+- **Pre-epoch cassettes: we could report ordinary content drift, and chose not to.** When a cassette
+  recorded before the 2.0.0 hash-format epoch is read, `rehash` recomputes the **legacy** digest over the
+  current tree and compares it to the legacy digest in the cassette. On a mismatch that is a positive
+  determination of ordinary content drift — strictly more informative than `unverifiable-skill`, and the
+  same determination 1.25.0 reported as warn-only `skill` drift.
+
+  Replay does not report it, and that is a decision rather than a limit. Reporting it would require
+  keeping a fold of the retired hash algorithm alive in the replay path — the most-run lane — permanently,
+  to soften one release's migration; the population it would help shrinks with every re-record. The
+  runtime cost would be nil (both digests fold from one tree walk); the cost is code that could never be
+  deleted. **"We can compute this and chose not to report it, so the legacy fold can die" is a different
+  claim from "this cannot be known", and the earlier phrasing implied the latter.** The remedy for a
+  pre-epoch cassette is `rehash` where it can prove content unchanged, and a re-record where it cannot.
+
+### Fixed
+
+- **The fast test lane had no global timeout, so 93 subprocess-spawning test files inherited vitest's 5s
+  default.** They measure 167-888ms locally — a fine margin until you remember the lane runs 344 files in
+  parallel across every core, and a CI runner is ~3x slower again. That is how an 888ms test crosses 5s;
+  it cost two red CI runs on unrelated PRs before anyone looked at the failure rather than re-running it.
+  `vitest.config.ts` now sets `testTimeout: 30_000` — ~34x the slowest measured non-e2e case, while a
+  genuine hang still fails ~6x faster than in the live lane (which sets 180s). Per-test values still win.
+
+- **Redaction pattern ORDER is load-bearing, and now says so — plus a warning when it is wrong.** Patterns
+  apply in sequence over the accumulating output, so a bare catch-all placed ahead of a lookahead-anchored
+  rule for the same prefix matches first and eats the `/mnt/` tail the lookahead exists to preserve. The
+  shipped policy depends on that order: with it, a run-dir path redacts to
+  `[REDACTED:local-path:…]/mnt/outputs/report.md` and still resolves; without it the whole path is consumed
+  and `normalizeHostShapedForReplay` returns `null` — **every `computer://` structural-marker resolution
+  silently stops working, with no error and no finding.**
+
+  `loadRedactionPolicy` now warns, naming both pattern indices, when a policy is in the hazardous order.
+  Detection is deliberately conservative — it fires only when a later pattern's source is exactly an
+  earlier one's plus a trailing lookahead (modulo lazy quantifiers) — because regex subsumption is
+  undecidable in general and a false positive would train authors to ignore the warning.
+
+  The remainder is matched by **shape**, never by parsing the lookahead's body. A first cut used
+  `\(\?=[^()]*\)`, whose `[^()]*` silently skipped every lookahead containing a group — so
+  `(?=/mnt(?:/|$|[\s"'\\)\]]))`, the natural way to write "slash, end, or delimiter" and arguably more
+  correct than a bare `(?=/mnt/)`, went unflagged while being just as dangerous. Caught by a consumer
+  running it against their own policy, which is now a regression fixture. Not looking inside also sidesteps
+  escape- and char-class-awareness, since that policy carries an escaped `\)` inside a character class.
+
+  `docs/cassette.md` states the requirement next to the existing "stop before `/mnt/`" guidance, which had
+  the shape of the rule but not the ordering half. The new test pins the runtime consequence, not just the
+  detector: a reorder must make the link fail to normalize AND be flagged, so the syntactic check cannot
+  drift away from what it is standing in for.
+
+- **The copy-pasteable Action steps now pin `version: "^2"`, and a guard requires it.** Bounding every
+  published npm floor last release fixed the *form* of a floor (`>=1.11.0` reads as a bound and silently
+  means "and every future major too") but removed the input from the recipes rather than correcting it —
+  so the shipped snippets carried no `version:` at all and fell back to the input's `latest` default. That
+  reproduced the exact footgun `action.yml`'s own description warns about two lines earlier: a CLI major
+  reaches a workflow the moment it is promoted, even though the `uses:` ref never changed.
+
+  `^2` was not among the alternatives weighed at the time, and it is the form `action.yml` itself
+  recommends: it holds the major, needs no patch number to remember, and only wants a human decision at
+  the next major bump. **Five** steps were unpinned, not the three in the CI recipe — `README.md` carries
+  two more.
+
+  `action-docs-sync` now requires every copy-pasteable step (a `uses:` line inside a fenced block with a
+  `with:`) to pin `^<package major>`; inline prose mentions are excluded, since there is nothing to pin.
+  Verified by mutation: dropping one `version:`, regressing a pin to `^1`, and bumping the package major
+  each fail. The guard also asserts it found the steps at all, because a parser that matches nothing
+  passes every assertion after it. Guarding a floor's FORM does not guarantee a floor is PRESENT — this
+  pins the behaviour instead.
+
+- **The `sessionFingerprint` field set is now stated completely, and a guard discovers the sites that
+  state it.** The hash covers eight session fields; every place that enumerated them named six or fewer.
+  `web_fetch` was missing everywhere, `agent_env` was missing everywhere, and `docs/invariants.md`
+  also omitted `skills`. Fourteen sites carried the claim while the working assumption was three: **twelve
+  enumerated the set** — four in prose, two in the current cassette schema, six in the retained v9-v11
+  schemas — and **two denied it existed at all**. `SPEC.md` and `docs/scenario.md` both said the session
+  is "not drift-checked or fingerprinted". `model` genuinely is not hashed; connected folders and plugin/skill/MCP discovery are,
+  which is the half a reader would have trusted.
+
+  The `verify-cassettes` staleness message — the only enumeration a user ever sees — omitted `projects`,
+  and `docs/cassette.md` quoted it with `projects` present. Both are fixed and now pinned to each other
+  by test, so the doc cannot drift from the string again.
+
+  New **invariant 14** in `check:versions` derives the field set from `buildSessionFingerprint`'s shape
+  and **discovers** the enumeration sites rather than reading a list, so a new one is covered the day it
+  lands. Two deliberate limitations are recorded as tests rather than left to look covered: it cannot see
+  a flat denial (there is no enumeration to check — the coverage floor is what notices), and it cannot
+  see a deleted "only when set" qualifier. `schema/cassette.v{9,10,11}.json` are allowlisted as frozen
+  history: a retained schema documents the format as it shipped, and rewriting its description would make
+  it describe a shape its own consumers never saw.
+
+  Verified by mutation: run against the previous revision the guard flags all six then-existing sites
+  with the correct missing fields; renaming the shape literal makes it error rather than silently pass;
+  a ninth field invalidates a previously-complete site; and a whole-file token check — which would have
+  passed today and then never failed again — is rejected in favour of span-scoped matching.
+
+- **The documented Action ref is now `@v2`, not `@main`** — 7 references across `README.md`,
+  `SKILL.md` and `ci-recipe.md`. `@main` was right when it was written: no alias tag had ever been
+  published, so naming one would have sent a copy-pasting reader to a `uses:` that 404s, and the guard's
+  own note said to revisit "once 1.0.0 ships". Two things had to be true first, and now are — `v2`/`v2.0`
+  point at a real release, and `release.yml` moves them on every stable release rather than leaving it to a
+  checklist. Recommending a floating tag nobody remembers to move is worse than recommending `@main`; that
+  was the actual situation while `v1` sat at 1.24.0.
+
+  `action-docs-sync` now derives the expected ref from `package.json`'s major instead of hardcoding it, so
+  the next major forces these docs to move with it rather than silently pointing a reader at the previous
+  line. `@main` is deliberately no longer accepted there: permitting both would let the recommendation
+  drift back with nothing noticing. Verified by mutation — regressing one reference to `@main` fails, and
+  setting the package version to 3.0.0 fails all three files.
+
+  **This changes nothing about which CLI you get.** The ref selects the Action; the CLI still comes from the
+  `version:` input, which still defaults to `latest`. `@v2` looks more like a version pin than `@main` did,
+  so that distinction matters more now, not less — it is spelled out in `README.md`'s Action section and in
+  `action.yml`'s own input description.
+
+- **The CI recipe no longer teaches a bare version floor.** It
+  carried `version: ">=1.11.0"` — which reads as "at least 1.11.0" and silently means "and every future
+  major too", so a copy-paster gets the next major with no say in it. It was **not** broken today
+  (`--min-severity` still exists in 2.x, and `lint` reads no cassette, so 2.0.0's hash-format epoch never
+  applied to that step) — the defect was latent and in the FORM.
+
+  The bare floor was first dropped rather than corrected — `^1.11.0` would have frozen every new
+  copy-paster on the previous major, and `^2.0.1` needs remembering at each release — so the guidance moved
+  to prose. **That went one step too far, and the same release corrects it** (see the `version: "^2"` entry
+  above): dropping the input entirely falls back to `action.yml`'s `latest` default, which is the one
+  remaining unbounded form and the exact footgun the input's own description warns about two lines earlier.
+  `^2` was never among the alternatives weighed at the time, and it is what the recipes now carry. Reach for
+  an exact pin only when you want byte-reproducible CI. [`action.yml`](https://github.com/yaniv-golan/cowork-harness/blob/main/action.yml)'s own description stops offering `>=1.11.0` and
+  `^1.11.0` as interchangeable — they are not, and it had been recommending the unbounded one.
+
+  `check:versions` invariant 13 now covers the Action's `version:` input, which it could not see before:
+  it keys on `@>=`, and `version: ">=1.11.0"` has no `@` — the same defect in different syntax, with no
+  coverage. Only the **unbounded** floor is rejected; verified against each form, `>=1.11.0 <3`, `^2`,
+  `2.0.1` and `latest` all pass.
+
+- **`projects[].from` was missing from two places, and the second was a false green.** A connected project
+  is a host path exactly like a connected folder, and it was:
+  - **not resolved against the session file.** [`docs/session.md`](./docs/session.md) promises, without
+    qualification, that *"relative paths resolve from the session file's own directory"* — and it was true
+    of every path field except this one, which resolved against the **process CWD**. So the same session
+    file mounted different content depending on which directory you invoked from. The doc was right; the
+    resolver had simply skipped the field.
+  - **not part of the session fingerprint.** Swapping which directory is mounted at `.projects/<uuid>`
+    changed the run's inputs and `verify-cassettes` reported nothing — a false green in the gate whose job
+    is to notice that inputs moved. Folded in on the same **non-empty-only** terms as `agent_env`, so a
+    session with no `projects:` (and one with an explicit `projects: []`) hashes byte-identically to
+    before; only sessions that use the feature move. No committed cassette does.
+
+  **A cassette recorded before this is reported `unverifiable`, not clean.** Its hash contains nothing
+  about `projects[]`, so it cannot distinguish "the field was never covered" from "the mount changed since
+  record time" — and reporting the mismatch as a benign migration would put the same false green back in
+  the remedy. When everything else matches exactly, `verify-cassettes` says so and asks for a re-record to
+  gain the coverage. `sessionFingerprintDrift` remains `verify-cassettes`-only: none of this can change a
+  `replay` verdict, even under `--strict`.
+
+  Three enumerations of the covered fields gained `projects` — [`docs/cassette.md`](./docs/cassette.md),
+  [`docs/invariants.md`](./docs/invariants.md) and the shipped skill's `task-recipes.md`. `invariants.md`
+  also described this as a hash of the **resolved** session; it is the **authored, pre-resolution** shape,
+  deliberately, so the digest survives a different checkout — the function's own comment says so, and a
+  resolved hash could never match on another clone.
+
+- **The published control-protocol schema rejected five kinds of frame the harness sends and answers.**
+  `schema/protocol.v1.json` described four request subtypes; the harness has always answered **six** —
+  adding `request_user_dialog` and `elicitation`/`side_question` — and it also sends a fail-closed
+  `subtype:"error"` response envelope, whose payload is a *string* under `error` rather than an object
+  under `response`, so a validator that knew only the success envelope rejected every one. Measured
+  against the previous schema: all five representative frames **REJECT**; against the new one, all five
+  accept. Anyone validating real traffic was seeing failures on frames the harness handles correctly.
+
+  Added as new `oneOf`/`anyOf` branches plus one new top-level response shape — **111 insertions, zero
+  deletions** in the surface baseline, so nothing existing was narrowed and no frame the schema already
+  accepted is affected. Both spellings the parser accepts are admitted (`dialogKind`/`dialog_kind`,
+  `mcp_server_name`/`server`, `message`/`prompt`) rather than guessing which the agent sends.
+
+  The golden vector pack grew with it, generated from the **real** envelope builders rather than
+  hand-authored lookalikes. The existing lockstep test — every schema definition must be exercised by a
+  vector — caught all five additions immediately, which is what forced those vectors to exist. One of them
+  asserts the error envelope does **not** validate as a success envelope, so the two shapes cannot be
+  quietly conflated later.
+
+  [`SPEC.md`](./SPEC.md) §12 now states the additive latitude for this surface explicitly. Its silence had
+  read as a prohibition, which is plausibly why three subtypes went undescribed rather than added — while
+  [`docs/protocol.md`](./docs/protocol.md)'s own versioning policy had said all along that an additive
+  variant is a v1 minor note, which is where the dated entry now lives.
+
+- **The Marketplace alias tags are moved by the release workflow instead of by remembering.** `v1` sat at
+  1.24.0 through two releases because moving it was a checklist line. `release.yml`'s last step now points
+  `vX` and `vX.Y` at the release it just published, with two guards a hand-run `git tag -f` skips: a
+  **prerelease** tag moves nothing (the trigger accepts `v1.0.4-rc.1`, and pointing `v1` at an rc would
+  hand every `@v1` consumer a prerelease), and an alias **never moves backwards** — re-releasing an older
+  patch on a line moves `vX.Y` and leaves `vX` alone. Verified by executing the logic against a synthetic
+  tag set rather than by reading it: releasing `v1.20.5` while `v1.25.0` exists correctly skips `v1` and
+  still moves `v1.20`. It runs last, after publish and the GitHub Release, so a failure there cannot
+  half-publish anything.
+
+  Alongside it, the tags are now correct: **`v2` and `v2.0` created** (they did not exist, so nothing
+  pointed at the 2.x Action), and **`v1` moved 1.24.0 → 1.25.0**. Worth recording what that move did and
+  did not fix: the Action's whole surface — `action.yml` plus the `render.js` it loads — is **byte-identical
+  from 1.24.0 through 2.0.1** apart from three lines of input *description*. So a stale `v1` was a promise
+  the repo had stopped keeping, not a functional gap, and the one public `@v1` consumer pins `version:` on
+  every step and was never exposed to the `latest` default at all.
+
+### Documentation
+
+- **The invariants index said `check-versions.ts` has "no dedicated vitest file — it's a standalone script,
+  not a unit-testable module boundary".** Three exist, for the invariants whose logic is an exported pure
+  function: `check-cassette-version-claims`, `check-fingerprint-field-claims` and
+  `check-design-scope-note`. The claim had already been stale before this release.
+
+- **The `uses:` ref pins the Action; the `version:` input pins the CLI — and only the second one holds a
+  major.** Both are documented as if pinning `@v1` bounded what you install. It does not: they move
+  independently, and `version:` defaults to `latest`, so promoting a CLI major reaches a workflow whose
+  `uses:` ref has not changed in months. Measured at the time of writing — `v1` points at **1.24.0** and
+  has never been moved, yet an `@v1` workflow with no `version:` input installs **2.x**. `README.md`,
+  `action.yml` (the text GitHub Marketplace renders) and `RELEASING.md`'s alias-tag step now say so, and
+  name the fix: pin the **input** (`version: ^2`), not the ref. Crossing 1.x → 2.x this way means the
+  hash-format epoch, so pre-v12 cassettes need `cowork-harness rehash <dir/>`.
+
+  `RELEASING.md`'s "move the major/minor tags" step additionally records what moving `vX` does *not* do,
+  since that step reads as the thing that controls consumer upgrades and is not.
+
 ## [2.0.1] — 2026-08-23
 
 ### Added

package/README.md

@@ -115,7 +115,7 @@ node dist/cli.js replay examples/replays/example-pdf-skill.cassette.json
 
 > **Installed globally instead?** Once linked/installed, the same command is `cowork-harness replay
 > <cassette>` — but the relative path above only resolves from a source checkout's `examples/replays/`.
-> From a global install (`npm i -g "cowork-harness@^2.0.1"`), point at the package root instead:
+> From a global install (`npm i -g "cowork-harness@^2.1.0"`), point at the package root instead:
 > `cowork-harness replay "$(npm root -g)/cowork-harness/examples/replays/example-pdf-skill.cassette.json"`
 > (or copy the cassette into your own project and pass that path).
 
@@ -125,7 +125,7 @@ Live `run`/`skill` need the prerequisites in the next section — note the `prot
 > - **Replay only (zero setup):** `cowork-harness replay <cassette>` — no token, no Docker, no agent. The command above.
 > - **`protocol` (real model, no Docker):** needs only the auth token (item 3 below).
 > - **Live `container` / `microvm` / `hostloop` / `cowork`:** needs Docker (or Lima for `microvm`), a staged agent, and the token — run `cowork-harness doctor` first.
-> - **Invocation:** from a source checkout, `node dist/cli.js <cmd>` (or `npm link` to get the `cowork-harness` command); from a global install, `cowork-harness <cmd>`; the companion skill falls back to `npx "cowork-harness@^2.0.1"`.
+> - **Invocation:** from a source checkout, `node dist/cli.js <cmd>` (or `npm link` to get the `cowork-harness` command); from a global install, `cowork-harness <cmd>`; the companion skill falls back to `npx "cowork-harness@^2.1.0"`.
 
 Two more worked examples worth knowing about: `examples/scenarios/protocol-smoke.yaml` (zero-Docker smoke
 test) and `examples/scenarios/skill-loads.yaml` (container-tier acceptance check) — see
@@ -150,7 +150,7 @@ claude plugin marketplace add yaniv-golan/cowork-harness
 claude plugin install cowork-harness@cowork-harness
 ```
 
-The skill **self-bootstraps the CLI**: if `cowork-harness` isn't on your PATH it falls back to `npx "cowork-harness@^2.0.1"` (a version floor that fails loud rather than silently fetching a too-old CLI; Node ≥ 22). Tiers above `protocol` still need Docker/Lima and a Claude Desktop agent binary — see the prerequisites below.
+The skill **self-bootstraps the CLI**: if `cowork-harness` isn't on your PATH it falls back to `npx "cowork-harness@^2.1.0"` (a version floor that fails loud rather than silently fetching a too-old CLI; Node ≥ 22). Tiers above `protocol` still need Docker/Lima and a Claude Desktop agent binary — see the prerequisites below.
 
 It also follows the open [Agent Skills](https://agentskills.io) spec, so it installs cross-editor (Cursor, Codex, OpenCode, …) via [`npx skills`](https://github.com/vercel-labs/skills) (Vercel Labs' CLI implementation of that spec):
 
@@ -175,7 +175,7 @@ global install puts nothing in your working directory. The matrix, answer-policy
 ones that still need a source checkout. (The marketplace
 skill install itself only pulls `.claude/skills/cowork-harness/` — SKILL.md + `references/` + `scenario.py`/
 assertion keys, per `.claude-plugin/marketplace.json`'s `source` — not the rest of this table; the full set
-above becomes available once the skill's first command self-bootstraps `npx "cowork-harness@^2.0.1"` — see
+above becomes available once the skill's first command self-bootstraps `npx "cowork-harness@^2.1.0"` — see
 [above](#drive-it-from-claude-code-companion-skill) — which pulls the same npm package as the global-install row.)
 
 ### Prerequisites for anything above `protocol` fidelity
@@ -358,7 +358,11 @@ Exceptions worth knowing:
 
 - the `boundary-check` **command**'s own probe failures follow the assertion convention and exit `1` (see SPEC.md §11);
 - `verify-cassettes` reuses exit `3` with a different meaning — "could not verify" (vs. a verified failure's `1`); see the command table;
-- exit `4` is reserved on the `run`/`skill` family (SPEC §11).
+- `rehash` uses **exit `4` for PARTIAL success** — some cassettes migrated, some could not. That and a total
+  failure (`1`, nothing migrated) demand opposite responses, so they are separate codes; `0` means all
+  migrated or nothing needed migrating (SPEC §11);
+- exit `4` is otherwise reserved on the `run`/`skill` family, where it is still unused (SPEC §11) — the code
+  space is per-command, so `rehash`'s `4` above does not touch that reservation.
 
 After a run, the footer **echoes every auto-answered
 question as a copy-pasteable `--answer "<q>=<choice>"` line** — run once exploratorily, then paste them
@@ -719,11 +723,23 @@ cowork-harness run scenarios/            # your repo's scenarios; runs every *.y
 
 The fastest path to CI: a composite action wrapping the token-free lane, with a PR job-summary reporter.
 
+> **The `uses:` ref pins the Action, not the CLI.** `@main`, `@v1` and a commit SHA all select which
+> *Action* runs; which *CLI* it installs is the separate `version:` input below, which defaults to
+> `latest`. The two move independently — so a workflow whose `uses:` ref has not changed in months still
+> picks up a CLI **major** the moment one is promoted to `latest`. That is not hypothetical: `@v1` points
+> at 1.24.0 and has not moved, yet an `@v1` workflow without a `version:` input installs 2.x today.
+> **To hold a major, pin the input** — `version: ^2` (or `^1`) — not the `uses:` ref.
+>
+> Upgrading across the 1.x → 2.x boundary this way means the hash-format epoch: cassettes recorded before
+> format v12 need `cowork-harness rehash <dir/>` (no re-record). See the 2.0.0 entry in
+> [CHANGELOG.md](./CHANGELOG.md).
+
 ```yaml
-- uses: yaniv-golan/cowork-harness@main
+- uses: yaniv-golan/cowork-harness@v2
   with:
     command: replay              # replay | lint | lint-skill | analyze-skill | verify-cassettes | run
     path: cassettes/my-skill.cassette.json
+    version: "^2"                # hold the CLI major; the input defaults to `latest`
 ```
 
 | Lane | Commands | Runner requirements | What you get |
@@ -748,14 +764,15 @@ jobs:
           curl -fSL "https://downloads.claude.ai/claude-code-releases/$V/linux-arm64/claude" -o "$RUNNER_TEMP/claude-$V"
           chmod +x "$RUNNER_TEMP/claude-$V"
           echo "COWORK_AGENT_BINARY=$RUNNER_TEMP/claude-$V" >> "$GITHUB_ENV"
-      - uses: yaniv-golan/cowork-harness@main
+      - uses: yaniv-golan/cowork-harness@v2
         with:
           command: run
           path: scenarios/
+          version: "^2"
           anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
 ```
 
-Every run writes a Markdown verdict table (scenario, pass/fail, signals, cost/turns when available, staleness findings, and the replay-skipped-assertions honesty line) to the job summary. Inputs: `command`, `path` (required), `version` (npm dist-tag/version, default `latest` — intentional so recipes track the current release; pin an exact version for reproducible CI. The companion skill's `cowork-harness@^2.0.1` floor guidance applies to ad-hoc CLI installs, not this input), `strict` (applies to `replay` (staleness findings), `lint`/`lint-skill` (WARN/INFO), and `analyze-skill` (any **`error`**-severity finding — advisory findings are precisely the class that does NOT gate); IGNORED — not forwarded — for `verify-cassettes`/`run`, which don't accept the flag), `fail-on-skill-drift` (**`replay`-only** — never forwarded to the analyzers), `extra-args`, `summary` (default `true`), `anthropic-api-key` (live lane only). Outputs: `ok` (`"true"`/`"false"`, mirrors the exit code), `envelope-path` (path to the raw JSON envelope, for post-processing), `summary-md` (the rendered verdict table, exposed as an output — not just written to `$GITHUB_STEP_SUMMARY` — because that file is scoped to this action's own invocation and a caller's later step gets a fresh, empty one). See [`action.yml`](https://github.com/yaniv-golan/cowork-harness/blob/main/action.yml) for the full input/output reference.
+Every run writes a Markdown verdict table (scenario, pass/fail, signals, cost/turns when available, staleness findings, and the replay-skipped-assertions honesty line) to the job summary. Inputs: `command`, `path` (required), `version` (npm dist-tag/version, default `latest` — the recipes above pin `^2` instead, because leaving it at `latest` takes a CLI major the moment it is promoted even though your `uses:` ref never changed; pin an exact version for byte-reproducible CI. The companion skill's `cowork-harness@^2.1.0` floor guidance applies to ad-hoc CLI installs, not this input), `strict` (applies to `replay` (staleness findings), `lint`/`lint-skill` (WARN/INFO), and `analyze-skill` (any **`error`**-severity finding — advisory findings are precisely the class that does NOT gate); IGNORED — not forwarded — for `verify-cassettes`/`run`, which don't accept the flag), `fail-on-skill-drift` (**`replay`-only** — never forwarded to the analyzers), `extra-args`, `summary` (default `true`), `anthropic-api-key` (live lane only). Outputs: `ok` (`"true"`/`"false"`, mirrors the exit code), `envelope-path` (path to the raw JSON envelope, for post-processing), `summary-md` (the rendered verdict table, exposed as an output — not just written to `$GITHUB_STEP_SUMMARY` — because that file is scoped to this action's own invocation and a caller's later step gets a fresh, empty one). See [`action.yml`](https://github.com/yaniv-golan/cowork-harness/blob/main/action.yml) for the full input/output reference.
 
 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):
 

package/RELEASING.md

@@ -223,8 +223,13 @@ tagging `1.0.0`, deliberately review and freeze the surfaces with no machine-rea
       gh run watch $(gh run list --workflow=release.yml --limit 1 --json databaseId --jq '.[0].databaseId')
       ```
 - [ ] **Clean up**: `git push origin --delete release/X.Y.Z && git branch -d release/X.Y.Z`
-- [ ] **Move the major/minor tags** (so `uses: yaniv-golan/cowork-harness@v1` and `@v1.0` resolve to
-      this release — the packaged Action's Marketplace consumers pin those):
+- [x] **Move the major/minor tags** — **AUTOMATED** by `release.yml`'s last step, which points `vX` and
+      `vX.Y` at the release it just published. It skips a prerelease tag entirely, and never moves an alias
+      backwards (re-releasing an older patch on a line moves `vX.Y` but leaves `vX` where it is). Left as a
+      checklist item, it lapsed: `v1` sat at 1.24.0 through two releases. Note what these tags do NOT do:
+      they select the ACTION, never the CLI. A consumer who leaves the `version:` input at its `latest`
+      default already tracks CLI majors regardless of which alias they pin, so moving `vX` neither causes
+      nor prevents a cross-major CLI upgrade for them. Manual fallback, if the step ever needs redoing:
       ```
       git tag -f vX vX.Y.Z && git tag -f vX.Y vX.Y.Z   # e.g. v1 and v1.0 → v1.2.3
       git push -f origin vX vX.Y