cowork-harness 4.1.0 → 4.1.1

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, asserting artifacts, egress, or sub-agent dispatch, measuring how long each tool call took (toolDurations / trace), or debugging a failed run or verdict from its result.json or transcript. 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: 4.1.0
-  tracks-harness: cowork-harness 4.1.0 (baseline desktop-2.9939.4)
+  version: 4.1.1
+  tracks-harness: cowork-harness 4.1.1 (baseline desktop-2.9939.4)
 ---
 
 # cowork-harness
@@ -26,7 +26,7 @@ allowlist). This skill exists mostly to keep you out of those traps — the *Inv
 full landmine catalog in [`references/gotchas.md`](references/gotchas.md) are the highest-value part.
 Read them.
 
-> **Version note:** the facts and `file:line` pointers here track `cowork-harness 4.1.0` (baseline
+> **Version note:** the facts and `file:line` pointers here track `cowork-harness 4.1.1` (baseline
 > `desktop-2.9939.4`). 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.
 
@@ -43,7 +43,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 **≥ 4.1.0**. If it's missing or older, prefix every command with the version floor `npx "cowork-harness@^4.1.0" <cmd>` (Node ≥ 22), or install once with `npm i -g "cowork-harness@^4.1.0"`. **Pin `@^4.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.
+- **CLI on PATH, recent enough?** Run `cowork-harness --version` — this skill needs **≥ 4.1.1**. If it's missing or older, prefix every command with the version floor `npx "cowork-harness@^4.1.1" <cmd>` (Node ≥ 22), or install once with `npm i -g "cowork-harness@^4.1.1"`. **Pin `@^4.1.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.
 
   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)

package/.claude/skills/cowork-harness/references/assertion-catalog.md

@@ -1,6 +1,6 @@
 # Assertion catalog
 
-Tracks `cowork-harness 4.1.0` (baseline `desktop-2.9939.4`). Every `assert:` key with its semantics, and the
+Tracks `cowork-harness 4.1.1` (baseline `desktop-2.9939.4`). Every `assert:` key with its semantics, and the
 verdict-signal table. Which keys survive `replay` is in [`scenario-schema.md`](./scenario-schema.md#replay-class);
 the scenario and session YAML fields are there too.
 

package/.claude/skills/cowork-harness/references/assertions-guide.md

@@ -1,6 +1,6 @@
 # Assertions guide
 
-Tracks `cowork-harness 4.1.0` (baseline `desktop-2.9939.4`). Read it when choosing assertion keys: the two orthogonal axes and the goal → key map. The full catalog is `assertion-catalog.md`.
+Tracks `cowork-harness 4.1.1` (baseline `desktop-2.9939.4`). Read it when choosing assertion keys: the two orthogonal axes and the goal → key map. The full catalog is `assertion-catalog.md`.
 
 ### Assertions: two orthogonal axes
 

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

@@ -1,6 +1,6 @@
 # Authoring a scenario
 
-Tracks `cowork-harness 4.1.0` (baseline `desktop-2.9939.4`). Read it when composing a `scenarios/*.yaml`: session vs scenario, discovery, the fidelity tier, the answer path, `web_fetch`, and scaffold + lint.
+Tracks `cowork-harness 4.1.1` (baseline `desktop-2.9939.4`). Read it when composing a `scenarios/*.yaml`: session vs scenario, discovery, the fidelity tier, the answer path, `web_fetch`, and scaffold + lint.
 
 ## Part I — AUTHOR a scenario
 
@@ -220,25 +220,75 @@ so a file `run`/`record` would refuse fails lint too (running `scenario.py lint`
 cowork-harness lint scenarios/*.yaml
 ```
 
-`lint` flags: filesystem/egress-only assertions on a `replay` gate (silent no-op), bad regex
-quoting, an egress assert on `protocol` fidelity, `transcript_no_host_path` on `hostloop`/`protocol`
-(ERROR — fails by design at those tiers; WARN on `fidelity: cowork`, whose tier resolves per the
-baseline's host-loop gate), non-empty `requires_capabilities` on `protocol` without
-`allow_missing_capability` (ERROR — the capability probe can't run there, so the run hard-fails as
-unverifiable), `no_scratchpad_leak` off `container` (ERROR on `protocol`/`microvm`/`hostloop` — hostloop's
-`present_files` passes a validated path through without promoting, so there is no scratch→outputs copy
-to leak; WARN on `cowork`, whose tier resolves per the baseline gate) or `present_files_called` on
-`protocol`/`microvm` (ERROR — served only at `container`/`hostloop`), or `present_files_called`/`no_scratchpad_leak`/`user_visible_artifact` on `lane: remote` (ERROR — the runtime rejects those at scenario load time, so the tier rules are suppressed there), a `controlOut`-gated key on a non-`controlOut` replay, mixed-class assertion items,
-and hallucinated schema (`assertions:` vs `assert:`, unknown keys). Exit code is non-zero on errors
-(CI-friendly). `scaffold` auto-upgrades the tier if you ask for egress on `protocol`, so it never
-emits a scenario `lint` would reject.
+`lint` exits non-zero on any ERROR (CI-friendly); `--strict` also fails on WARN. Every rule it reports:
+
+| Rule | Severity | Fires on |
+|---|---|---|
+| `assert-contradiction` | ERROR | assert items no single run can satisfy together |
+| `assertions-key` | ERROR | `assertions:` instead of `assert:` — none of the checks would run |
+| `authored-replay-fidelity` | ERROR | an authored `replay_protocol_fidelity` (only the replay lane synthesizes it) |
+| `capabilities-on-protocol` | ERROR | non-empty `requires_capabilities` on `protocol` without `allow_missing_capability` — the probe cannot run there, so the run fails as unverifiable |
+| `cassette-evidence-skipped` | INFO | with `--cassette-dir`: a cassette (or the directory) could not be read, so it cannot quiet replay-evidence advice |
+| `container-only-key-off-container` | ERROR | `no_scratchpad_leak` off `container` — hostloop's `present_files` never promotes, so there is nothing to leak (WARN on `cowork`, whose tier resolves per the baseline gate) |
+| `egress-on-protocol` | ERROR | an egress assertion (`egress_*` / `expect_denied`) on `protocol`, which enforces no egress |
+| `enum-value-invalid` | ERROR | a field value outside its allowed set |
+| `fidelity-missing` | ERROR | no `fidelity:` (required since 4.0.0) |
+| `file-absent-contradiction` | ERROR | one path under both `file_exists` and `file_absent` |
+| `gate-needs-controlout` | INFO | gate assertions, which evaluate on replay only when the cassette has `controlOut` |
+| `host-path-assert-cowork` | WARN | `transcript_no_host_path` on `cowork` — it fails by design if the tier resolves to hostloop |
+| `host-path-assert-tier` | ERROR | `transcript_no_host_path` on `hostloop` / `protocol`, where it fails by design |
+| `lane-remote-incompatible-key` | ERROR | `present_files_called` / `no_scratchpad_leak` / `user_visible_artifact` on `lane: remote` (the runtime rejects them at load, so the tier rules are suppressed there) |
+| `linter-extra-findings-invalid` | ERROR | the loader findings `cowork-harness lint` hands the linter could not be read |
+| `linter-unclassified-key` | ERROR | a valid assertion key this linter cannot classify (the linter is out of date) |
+| `manifest-needs-snapshot` | INFO | manifest-backed keys, which evaluate on replay only when the cassette carries an `artifacts` manifest |
+| `mixed-assert-item` | WARN | one assert item mixing replay-checkable and live-only keys (replay drops the live-only half) |
+| `no-scenarios` | ERROR | a linted directory with no `*.yaml` / `*.yml` |
+| `not-found` | ERROR | a named file that does not exist |
+| `parse` | ERROR | a file that is not YAML, or not a mapping |
+| `positional-choose-order` | INFO | an answer rule with a positional `choose` (first / index), which option re-ordering can move |
+| `present-files-key-off-tier` | ERROR | `present_files_called` on `protocol` / `microvm` (served only at `container` / `hostloop`) |
+| `prompt-slash-not-leading` | WARN | a `prompt:` that names `/<skill>` without starting with it, so it is never expanded |
+| `reference-access-contradiction` | ERROR | one reference under both `reference_read` and `no_observed_reference_access` |
+| `regex-double-quoted` | WARN | a double-quoted regex with an unescaped backslash (YAML strips it) |
+| `replay-noop` | WARN | every assertion is live-only or a verdict modifier, so a replay gate verifies nothing |
+| `tool-called-always-passes` | INFO | `tool_called` with `count: {min: 0}` and no `max` — it asserts nothing |
+| `tool-input-regex-redactable` | WARN | a `tool_not_called` input literal the redaction policy rewrites in the committed cassette (or a policy pattern it cannot check offline) |
+| `tool-input-shell-tier` | INFO | the object form with `tool: Bash` and a `command` on `hostloop` / `cowork`, where shell runs as `mcp__workspace__bash` — list both |
+| `tool-not-called-tier-vacuous` | WARN | `tool_not_called` / `subagent_tool_absent` naming a tool the tier never serves |
+| `transcript-command-shaped` | WARN | a `transcript_*` value shaped like a shell command — those keys read prose only, never a tool call |
+| `unknown-assert-key` | WARN | an assertion key not in the catalog (the loader rejects it) |
+| `unknown-top-key` | WARN | a scenario key not in the schema |
+| `vacuous-gate-assert` | WARN | `gate_answers_delivered` with no presence companion (zero gates passes it), or inert beside `questions_count_max: 0` |
+| `scenario-invalid` | ERROR | the harness's scenario loader refuses the file (via `cowork-harness lint` only — see below) |
+| `baseline-unknown` | ERROR | `baseline:` names no baseline this CLI ships (via `cowork-harness lint` only) |
+| `lint-loader-internal` | ERROR | the wrapper could not run its loader check on a file — a harness bug; it never falls back to a lint that skipped the loader |
+
+`scaffold` auto-upgrades the tier if you ask for egress on `protocol`, so it never emits a scenario `lint`
+would reject.
+
+**Lint the skill itself: `cowork-harness lint-skill <skill-dir>`.** It checks the skill, not a scenario:
+Cowork host-loop footguns (`${CLAUDE_PLUGIN_ROOT}` in a VM bash step, hook events, a misplaced
+`hooks.json`, an unresolvable `subagent_type`), the evidence corpus a `critique` can package
+(`references/critique.md`), and two size caps. `skill-body-over-reattach-cap` (WARN) fires when the
+`SKILL.md` body, frontmatter excluded, passes 19,000 B — after a compaction the agent re-attaches only the
+start of an invoked skill — and `skill-body-near-reattach-cap` (INFO) from 80% of that;
+`skill-reference-over-read-cap` (WARN) fires on a `references/**.md` over 60,000 B, past which a
+whole-file Read returns a partial view. `--strict` fails on WARN, never on INFO. To accept a reviewed
+judgement-call finding, pass `--ignore-rule <rule>[=<glob>]` (repeatable; the glob matches the finding's
+file) or fence the text in `SKILL.md` with `<!-- lint-skill: ignore-start <rule>[,<rule>…]: <reason> -->`
+… `<!-- lint-skill: ignore-end -->` (outside any code fence). A suppressed finding is still printed; it
+stops gating. A provable rule (an ERROR, a misplaced `hooks.json`, a missing pinned agent) cannot be
+suppressed: naming it, or an unknown rule, in `--ignore-rule` is a usage error (exit 2); in a marker it is
+WARN `lint-skill-ignore-invalid`, as is any other malformed marker. An unclosed marker is WARN
+`lint-skill-ignore-unclosed`, and one that suppresses nothing is INFO `lint-skill-ignore-unused`.
 
 **`cowork-harness lint` runs the loader: a file it calls clean is one `run`/`record` will load.** Anything
 the loader refuses — an unknown key, a wrong value type (a scalar `semantic_matches.rubric`), a bad regex,
 a reserved value — is ✗ ERROR `scenario-invalid` (exit 1, with or without `--strict`), and a `baseline:`
 naming no baseline this installed CLI ships is ✗ ERROR `baseline-unknown` (`latest` always resolves). It
 does not check what depends on the machine the run happens on (the session file and its mounts, an
-absolute `baseline:` path, environment variables). A session or matrix YAML in a linted directory is not
+absolute `baseline:` path that does not exist here — one that exists is checked (4.1.1 and later) —
+environment variables). A session or matrix YAML in a linted directory is not
 a scenario and is reported as one that does not load — keep those out of the linted set. `python3
 scenario.py lint` run directly stays offline and lenient: there an unknown key is only a ⚠ WARN (exit 0).
 `cowork-harness record <file.yaml> --dry-run` also runs the loader and adds the pre-spend refusals (exit 2

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 4.1.0` (baseline `desktop-2.9939.4`).
+Self-contained reference. Tracks `cowork-harness 4.1.1` (baseline `desktop-2.9939.4`).
 
 **Fastest path: the packaged Action.** One step gets you `replay`/`lint`/`verify-cassettes` plus a PR
 job-summary reporter (verdict table, staleness findings, cost/turns when available):
@@ -17,7 +17,7 @@ job-summary reporter (verdict table, staleness findings, cost/turns when availab
 CLI major reaches your workflow the moment it is promoted even though your `uses:` ref never changed — so a
 copy-pasted recipe that omits the input takes a major bump with no say in it. `^4` 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: "4.1.0"`) instead when you want byte-reproducible CI.
+(e.g. `version: "4.1.1"`) 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
@@ -82,7 +82,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@^4.1.0"
+- run: npm i -g "cowork-harness@^4.1.1"
 - 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.
@@ -241,7 +241,9 @@ cowork-harness replay cassettes/                   # replay every *.cassette.jso
 Re-record whenever the protocol or your scenario's expected content changes. An old cassette without
 `controlOut` excludes the gate keys (with a loud warning) — re-record to enable them. `record` **refuses
 to freeze a failing live run** into a cassette (pass `--allow-failing` to override) — a committed red
-cassette is a latent false-signal.
+cassette is a latent false-signal. An `--allow-failing` recording of a red run exits 0 with `ok: true`:
+`record`'s `ok` means a cassette was written, and the run's own verdict is `results[0].verdict.pass`
+(`items[].verdict` on `record <dir/>`).
 
 ## Privacy: cassettes are committed fixtures → record only against SYNTHETIC inputs
 
@@ -256,7 +258,9 @@ dollar figures). In a skill repo these cassettes get **committed**. So:
   dir** (first file found per dir; env vars merge on top). `cowork-harness init-redact` copies the
   packaged reference template (local-path prefixes, incl. macOS temp roots and slugged home segments
   like `-Users-<user>-…`, + a generic email regex) into the cwd as a starting point — review and tailor
-  it; a copy from an earlier release lacks the temp-root rules, so re-copy with `--force` or add them. Redaction is **verdict-preserving** — `record` refuses to write if
+  it; a copy from an earlier release lacks the temp-root rules, so re-copy with `--force` (without it
+  `init-redact` refuses to overwrite an existing policy; with it your tailoring is replaced — save and
+  re-apply it) or add them by hand. Redaction is **verdict-preserving** — `record` refuses to write if
   redaction would flip an assertion (a manufactured green). `--no-redact` skips it for known-synthetic
   inputs.
 - **Pre-spawn preflight**: `record` warns (`::warning::`, before the paid run starts — once per batch
@@ -342,8 +346,8 @@ A typical skill repo runs four stages, fastest/cheapest first:
    This is the shape a CI step wants: **silent on success (no output, exit 0), loud and specific on
    failure** — `--quiet` suppresses the readiness preview but never the `✗ broken:` lines, which name the
    offending file *and* the rejected key, one line per file, and the step still exits 1. It exits 0,
-   though, on an input the real record would refuse (a missing path, an unknown baseline name, a
-   tier-vacuous `tool_not_called`): that prints a `⚠ input error:` line and lands in `inputErrors[]`. To
+   though, on an input the real record would refuse (a `session:` file that cannot be read — 4.1.1 and
+   later — a missing path, an unknown baseline name, a tier-vacuous `tool_not_called`): that prints a `⚠ input error:` line and lands in `inputErrors[]`. To
    gate on those too, use the JSON form (4.1.0 and later):
 
    ```bash
@@ -391,7 +395,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@^4.1.0"
+      - run: npm i -g "cowork-harness@^4.1.1"
       - 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
@@ -420,7 +424,7 @@ jobs:
             echo "live=true" >> "$GITHUB_OUTPUT"
           fi
       - if: steps.guard.outputs.live == 'true'
-        run: npm i -g "cowork-harness@^4.1.0"
+        run: npm i -g "cowork-harness@^4.1.1"
       - if: steps.guard.outputs.live == 'true'
         run: cowork-harness run scenarios/ --output-format json
         env:
@@ -443,7 +447,8 @@ sandbox).
 
 `--output-format json` emits a machine envelope on stdout (human output goes to stderr):
 `{tool, version, command, ok, results[], error}` — one `RunResult` per scenario. **Overall pass for a
-scenario is `verdict.pass`** (envelope-wide: `ok`), and it is strictly stronger than
+scenario is `verdict.pass`** (envelope-wide: `ok`; on `record`, `ok` only means the command exited 0 —
+see below), and it is strictly stronger than
 `result === "success" && assertions.every(pass)`: the verdict also carries ~20 signal codes that fail a run
 with no failing assertion at all — `stalled`, `outputs_delete`, `mount_delete`, `host_path_leak`,
 `undelivered_deliverables`, `missing_capability`, `permissive_auto_allow`, `ended_with_question`,
@@ -477,6 +482,11 @@ Keep the `.results[]?` hop and the `?` operators. `.results[0]` silently ignores
 the first when you pass a directory, and a bare `.verdict` does not exist at the envelope root at all —
 both read as "no failures" against a run that failed.
 
+**`record` is shaped differently.** Its `ok` is the exit code's verdict (a cassette was written), not the
+run's: `record --allow-failing` on a red run is `ok: true`. The verdict is in `results[0].verdict` on
+`record <file>` and in `items[].verdict` on `record <dir/>` and `--rerecord-stale`, which carry no
+`results[]` — so `.results[]?` reads nothing there. Use `[.items[]? | .verdict.failures[]?]` on a batch.
+
 > **Do not filter on whether `assertion` is present.** That was the only discriminator before `kind`
 > existed and it never worked in both directions: `coverage` entries carry a key too (an internal
 > `answer_coverage` marker), so they read as authored asserts, while `guard`, `staleness` and
@@ -486,7 +496,9 @@ both read as "no failures" against a run that failed.
 `--output-format json`, `run` / `record` / `replay` / `verify-cassettes` / `status` write their whole
 human rendering — warnings, verdict, `status`'s summary line — to **stderr**, and stdout stays empty.
 A wrapper that captures only stdout gets an empty log and, if it greps that for a state, a silent false
-negative. Capture stderr for the human trail (`2> run.stderr.log`), or ask for JSON and parse stdout.
+negative. Capture stderr for the human trail (`2> run.stderr.log`), or ask for JSON and parse stdout —
+`COWORK_HARNESS_OUTPUT_FORMAT=json` makes JSON the default for every command that takes `--output-format`
+(an explicit flag still wins).
 (Commands whose whole job is to print a value — `--version`, `assertions --list`, `scaffold`, `gates`,
 `skill --dry-run` — write it to stdout by design. Under `--output-format json` the value rides inside the
 envelope: `scaffold`'s YAML is `.scenario`, `skill --dry-run`'s preview is the envelope's own fields;

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 4.1.0` (baseline `desktop-2.9939.4`). This is **not** a trim of the full
+Tracks `cowork-harness 4.1.1` (baseline `desktop-2.9939.4`). 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/debugging.md

@@ -1,6 +1,6 @@
 # Debugging a run
 
-Tracks `cowork-harness 4.1.0` (baseline `desktop-2.9939.4`). Read it when a run misbehaved or a green looks wrong: triage, the observability output, and `chat`.
+Tracks `cowork-harness 4.1.1` (baseline `desktop-2.9939.4`). Read it when a run misbehaved or a green looks wrong: triage, the observability output, and `chat`.
 
 ## Part III — Debug
 
@@ -37,7 +37,11 @@ already does.
 **microvm: "control-protocol write failed" with `env: 'claude': No such file or directory` in the agent
 stderr** usually means the VM never finished provisioning (the agent never reached PATH). Check
 `cowork-harness vm status` — a `provisioning` other than `ready` confirms it — and if a run does not
-recover it on its own, `cowork-harness vm delete` and retry.
+recover it on its own, `cowork-harness vm delete` and retry. A run on such a VM can also have cached an
+empty toolchain for it in the capability probe's cache: `vm delete` drops that VM's entry (`vm prune`
+forgets only the orphaned VMs it deletes, never the current one); otherwise delete `capability-cache.json`
+from the runs root (`~/.cowork-harness/runs/` unless
+`COWORK_HARNESS_RUNS_DIR` is set) so the next run probes again.
 
 **Is it your skill's bug, or a known harness gap?** Before deep-debugging a wrong behavior, rule out a
 **deliberate fidelity gap** — the harness intentionally does *not* reproduce a few real-Cowork behaviors,
@@ -80,7 +84,9 @@ decide which assertions from *Assertions: two orthogonal axes* in `assertions-gu
   walk observe this run — what distinguishes "nothing was left undelivered" from "cannot tell"), `cost` (`cost.usd` = the SDK's
   `total_cost_usd` for the run — the authoritative single-run spend of the agent session, which leaves out the `semantic_matches` judge and the LLM decider calls; NOT the same source as summing
   `modelUsage[].costUSD`, which is what `trace --view usage` reports, so the two can differ),
-  `usage` (`input_tokens`/`output_tokens`/`turns`), `toolDurations` (with `toolDurationsBasis`), `models`, `toolErrors`,
+  `usage` (`input_tokens`/`output_tokens`/`turns`), `toolDurations` (with `toolDurationsBasis`), `models`,
+  `toolCalls` (every tool call in stream order: `name`, top-level `input` fields each capped at 10 KB, and
+  `origin` `main`/`subagent`/`unknown` — what the object form of `tool_called`/`tool_not_called` reads), `toolErrors`,
   `redundantToolCalls`, `modelUsage`, `thinking`, `skillActivity`, `subagents[]` (prompt/`dispatchModel`/
   `resolvedModel`/output/`attributedSkillId`, `outputTruncated`, `referencesRead`, `reasoning`/`reasoningElided`),
   `context` (tools/mcpServers/availableSkills), `tasks`,

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

@@ -1,6 +1,6 @@
 # Fidelity tiers & answer paths
 
-Self-contained reference. Tracks `cowork-harness 4.1.0` (baseline `desktop-2.9939.4`).
+Self-contained reference. Tracks `cowork-harness 4.1.1` (baseline `desktop-2.9939.4`).
 
 > **This page vs. the repo docs.** This is the **offline snapshot** that ships inside the installed
 > plugin — it is self-contained on purpose. The repo carries four other fidelity views, each answering a

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

@@ -1,6 +1,6 @@
 # Gotchas
 
-Tracks `cowork-harness 4.1.0` (baseline `desktop-2.9939.4`). The full "✓ passed ≠ correct" landmine catalog.
+Tracks `cowork-harness 4.1.1` (baseline `desktop-2.9939.4`). The full "✓ passed ≠ correct" landmine catalog.
 
 ## Gotchas — the "✓ passed ≠ correct" landmines
 
@@ -175,9 +175,10 @@ authorable). Reach for this list when debugging a run's behavior, that one while
     `--reassert`). That opt-in path is safe by construction for the authored fields — it **hard-fails** if
     `prompt`/`answers`/`baseline`/`fidelity`/`lane`/`skills`/`requires_capabilities` or the skill content (when a
     fingerprint exists) drifted from the recording (re-record then), and `expect_denied`/filesystem/egress keys
-    are sourced but stay **live-only** (it warns; they don't move the replay verdict). **Caveat:** the `session`
-    (model / data mounts / discovery) is NOT drift-checked or fingerprinted, so a **model change** between record
-    and re-assert is undetected — the notice flags this; re-record if the session changed. `verify-run` reads
+    are sourced but stay **live-only** (it warns; they don't move the replay verdict). **Caveat:** the session's
+    `model:` IS in the cassette's `sessionFingerprint` (a `--model`/env model is not; `environment.model`
+    records what ran). `verify-cassettes` reports a changed session as staleness (exit 1); `replay` never
+    checks it — plain, `--strict` or `--assert-from` — so re-record if the session changed. `verify-run` reads
     on-disk `assert:` against a kept *run dir*; `replay --assert-from` is the equivalent for a *cassette*.
 
 18. **`questions_count_max` counts sub-questions, not gates.** One `AskUserQuestion` tool call can

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

@@ -1,6 +1,6 @@
 # Measurement
 
-Tracks `cowork-harness 4.1.0` (baseline `desktop-2.9939.4`). Read it before comparing runs: `--repeat`, `--ablate-skill`, and the hygiene that keeps a batch valid.
+Tracks `cowork-harness 4.1.1` (baseline `desktop-2.9939.4`). Read it before comparing runs: `--repeat`, `--ablate-skill`, and the hygiene that keeps a batch valid.
 
 ### Measure — before/after, with/without (`--repeat`, `--ablate-skill`)
 
@@ -40,7 +40,10 @@ Compare timings between runs of the same tier and model only.
 
 1. **Pin the model in the session.** A run that resolves no model is refused, but one pinned only by
    `COWORK_HARNESS_MODEL` takes its model from the machine, so two shells can run two models. Set
-   `model:` in the session (or pass the same `--model` on every `skill` run). Read `result.json`'s `models` back before believing any cross-run comparison — and when
+   `model:` in the session (or pass the same `--model` on every `skill` run). Adding `model:` to a session
+   that already has cassettes re-stales them (`verify-cassettes` exits 1 — the model is in the session
+   fingerprint); to pin without re-recording now, use `--model` or `COWORK_HARNESS_MODEL` and move the
+   pin into the session at the next re-record. Read `result.json`'s `models` back before believing any cross-run comparison — and when
    you do, **ignore any entry wrapped in angle brackets**: `<synthetic>` is the agent marking a turn it
    fabricated locally (no API call), not a model, so two runs of the same pinned model can differ on this
    array purely by whether such a turn occurred.

package/.claude/skills/cowork-harness/references/run-record-replay.md

@@ -1,6 +1,6 @@
 # Run, record and lock
 
-Tracks `cowork-harness 4.1.0` (baseline `desktop-2.9939.4`). Read it when running a scenario, recording or placing a cassette, reading verdict signals, checking a background run, or choosing CI lanes.
+Tracks `cowork-harness 4.1.1` (baseline `desktop-2.9939.4`). Read it when running a scenario, recording or placing a cassette, reading verdict signals, checking a background run, or choosing CI lanes.
 
 ## Part II — RUN, RECORD & LOCK
 
@@ -25,12 +25,14 @@ the discovery/encode/record dance entirely and answer gates **live during the re
 refusals the real `record` applies (`on_unanswered: prompt`, and an unsatisfiable assert pairing) **plus the
 cassette-portability pre-flight below**, so it cannot green something a paid run would reject. **That binding
 guarantee is the SINGLE-FILE form only** — it takes the real `--out` and the real flags, so its verdict is the
-one a paid run would give. On a **directory** the path-dependent verdicts (host-inventory, cassette
+one a paid run would give. Two inputs it reports rather than refuses, at exit 0 under `inputErrors[]` with a
+`⚠ input error:` line: a `session:` file that cannot be read (missing, a directory, not valid YAML — 4.1.1
+and later) and a `tool_not_called` the tier can never violate — `run` and the real `record` refuse both. On a **directory** the path-dependent verdicts (host-inventory, cassette
 portability) are reported as `⚠ would-refuse (advisory)` / `⚠ would-warn (advisory)` notes — the label follows
 the verdict kind, and portability can only ever warn — that do NOT affect the exit code — a dir target
 takes no `--out`, so the destination is a guess — and only the path-independent ones (prompt policy, assert
-contradiction, duplicate cassette target) gate the batch. An input the real record would refuse — a missing
-path, an unknown baseline name, a `tool_not_called` the tier can never violate — is listed under
+contradiction, duplicate cassette target) gate the batch. An input the real record would refuse — a
+`session:` file that cannot be read (4.1.1 and later), a missing path, an unknown baseline name, a `tool_not_called` the tier can never violate — is listed under
 `inputErrors[]` with a `⚠ input error:` line, also at exit 0. So a directory dry-run CAN exit 0 on a scenario the
 real `record` would refuse; re-run that one file with its real flags for a binding answer, or gate on
 `.ok and (.inputErrors == [])` in the JSON payload (4.1.0 and later). A directory also
@@ -68,7 +70,10 @@ finished: a failing verdict without `--allow-failing`, an assert on an artifact
 quarantined inventory finding, or any other error before the cassette is written. Only the after-the-run
 refusals report the run: under `--output-format json` they carry it in `results[0]` (verdict and
 cost) with `error.category: "runtime"`; every pre-spend refusal, and a run that throws before returning a
-result (an unanswered gate), has `results: []`.
+result (an unanswered gate), has `results: []`. The envelope's `ok` is the exit code (`ok` ⇔ exit 0, a
+cassette was written), not the verdict: an `--allow-failing` recording of a red run is `ok: true` with
+`results[0].verdict.pass: false`. `record <dir/>` reports per scenario under `items[]` (each with `status`,
+and `verdict`/`result` once its run finished), not `results[]`.
 
 **Decide WHERE the cassette lives before you record it — a cassette cannot be moved afterwards.**
 Without `--out`, `record` writes `cassettes/<scenario-name-slug>.cassette.json` (gitignored by
@@ -254,7 +259,9 @@ Recognize these before "fixing" a non-bug:
   run that lands on `container` is armed. Author `transcript_no_host_path` to enforce cleanliness where
   it's valid. A host path that came verbatim from the scenario's own uploads, connected folders or prompt
   is not a leak (whole-token match; a token cut short where the path goes on, or one naming a location the
-  harness created for the run, is never exempt); `scan.hostPathsFromInputs` counts the paths exempted.
+  harness created for the run, is never exempt); `scan.inputHostPathTokens` counts the host-path tokens the
+  inputs carried, `scan.hostPathsFromInputs` the ones exempted, and a non-zero exemption prints a
+  `::notice::` so a clean scan that relied on it is never silent.
 - **`exec_infra_error`** (`WARN`, host-loop) — one or more container `exec` calls failed for
   infrastructure reasons (daemon/container-level), so those tool calls returned an error to the agent
   rather than the command's own output. Warn-severity because the run's other evidence is intact — unlike

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

@@ -1,6 +1,6 @@
 # Scenario & session schema, replay class, web_fetch, authoring gotchas
 
-Self-contained reference for authoring `cowork-harness` scenarios. Tracks `cowork-harness 4.1.0`
+Self-contained reference for authoring `cowork-harness` scenarios. Tracks `cowork-harness 4.1.1`
 (baseline `desktop-2.9939.4`). 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`.
 
@@ -117,7 +117,8 @@ allow_host_hooks: true              # OPTIONAL — required to run `protocol` fi
 ```
 
 Relative paths resolve from the file's own directory, so a scenario + session + referenced files
-form a relocatable bundle. `~` expands to home.
+form a relocatable bundle. `~` expands to home (in a scenario's `session:` itself, 4.1.1 and later; a
+cassette stores such a `session:` as written).
 
 > **A recorded cassette is NOT part of that bundle and is NOT relocatable.** It rewrites its own
 > references relative to **its own** directory at record time (`scenario.session` and
@@ -143,6 +144,10 @@ model: claude-opus-4-8           # a run must resolve a model: --model (or a mat
                                   # fabricated locally, not a model id).
                                   # On the ad-hoc `skill` lane there is no session file, so `--model <id>`
                                   # (or COWORK_HARNESS_MODEL) is the ONLY way to pin it.
+                                  # Adding or changing this key re-stales every cassette recorded from
+                                  # the session (it is in the session fingerprint, so verify-cassettes
+                                  # exits 1). To pin without re-recording now, pass --model or set
+                                  # COWORK_HARNESS_MODEL; move it here at the next re-record.
 account_name: my-account         # OPTIONAL — display name rendered into {{accountName}} / the prompt's
                                     # "User name:" line; NOT a credential/identity selector (see src/prompt.ts,
                                     # https://github.com/yaniv-golan/cowork-harness/blob/main/docs/session.md)
@@ -219,7 +224,10 @@ staleness:
 The staleness hash uses each skill/plugin source dir's **git-tracked** file set by default (a non-repo dir
 falls back to a raw walk; `COWORK_HARNESS_GITSET=0` opts out). **OS-junk** (`.DS_Store`/`Thumbs.db`/
 `desktop.ini`) is always excluded, so a Finder touch can't re-stale a cassette; run-generated files a skill
-writes into its own dir should be declared in `hash_ignore` / `.cowork-hashignore`. On a mismatch,
+writes into its own dir should be declared in `hash_ignore` / `.cowork-hashignore` — and so should
+scenario or session YAMLs kept inside a mounted plugin dir: they are tracked files, so editing a scenario
+there re-stales every cassette recorded from that plugin (committed `*.cassette.json` files are excluded
+automatically). On a mismatch,
 `verify-cassettes` names the exact changed file; `COWORK_HARNESS_DEBUG_SKILLHASH=1` dumps the full hashed set.
 For a multi-skill plugin, scope a scenario's hash with `skills: [<name>]`; the opt-in
 `COWORK_HARNESS_AGENT_SCOPE=skill` further treats a skill-named `agents/<name>.md` as that skill's private
@@ -240,6 +248,10 @@ with no session file, the CLI flags `--folder <dir>` and `--upload <file>` are t
 (`.local-plugins/marketplaces/local-desktop-app-uploads/<plugin>`). The choice matters to a skill that
 locates its own files from the shell (at host-loop, Cowork's default, the braced `${CLAUDE_PLUGIN_ROOT}` is
 replaced with a HOST path and a bare `$CLAUDE_PLUGIN_ROOT` is empty in the VM shell).
+Do not derive the VM path from the substituted host path by keeping its `/mnt/…` tail: under `hostloop`
+the harness's staged host path happens to end in the same `/mnt/.local-plugins/…` suffix as the VM path,
+so that shortcut passes here and fails in real Cowork, whose host path has no such tail
+([fidelity gap](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/fidelity-gaps.md#hostloop-the-substituted-plugin-path-shares-the-vm-paths-suffix-real-coworks-does-not)).
 Search for the skill's own `SKILL.md`, not for a directory named after the plugin — that finds nothing
 under `.remote-plugins/plugin_<id>` — and set no `-maxdepth` that stops short of the deeper local layout:
 `find /sessions/*/mnt/.local-plugins /sessions/*/mnt/.remote-plugins -path '*/skills/<skill-name>/SKILL.md' 2>/dev/null | head -1`.

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 4.1.0` (baseline `desktop-2.9939.4`), same as SKILL.md's front-matter. Recipe 2's `resolved-tier`/`unverifiable-tier` staleness classes and
+Tracks `cowork-harness 4.1.1` (baseline `desktop-2.9939.4`), 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.
 
@@ -85,7 +85,8 @@ record — retrofitting means re-recording:
 
 1. `cowork-harness init-redact` — copies the reference `.cowork-redact.json` (host-path +
    email patterns) into the current directory. Version-control it. Re-run with `--force` after an
-   upgrade to pick up new rules (save your tailoring first).
+   upgrade to pick up new rules: without it `init-redact` refuses to overwrite an existing policy, and with
+   it your tailoring is replaced — save it first and merge it back.
 2. **Search set:** record looks for `.cowork-redact.json` in the **cwd, the scenario's directory,
    and the cassette's output directory** — every distinct file found is MERGED (plus
    `COWORK_HARNESS_REDACT_PATTERNS`/`_KEYS` from the env). Repo root (= cwd in CI) is the
@@ -217,7 +218,9 @@ degrade the advice. It is real work to calibrate; these steps are the traps that
 
 **Lane note:** `semantic_matches` is **live-only** (the judge is a live model call), so these scenarios
 run on the `run` lane, never token-free `replay` — the linter's "all assertions live-only" warning is
-expected and correct here.
+expected and correct here. It is a WARN (`replay-noop`), so a scenario whose only assertion is
+`semantic_matches` fails `lint --strict`: add a replay-checkable item (`- result: success` is enough), or
+keep these files out of the set a strict lint gate covers.
 
 ## Recipe 6 — Iterate a skill across fixes (ground findings, don't cross-pair generations)
 
@@ -267,7 +270,9 @@ Hardening a skill is a loop: run → read what it did → fix → run again. Two
    separates them afterwards, but a hash whose source was never frozen names a generation that is
    unrecoverable, which makes the comparison uninterpretable rather than merely noisy. And pin the model in the session (`model:`), not
    only through `COWORK_HARNESS_MODEL`: a run that resolves none is refused, but the env var is a property
-   of the machine, so a before/after run from two shells can silently straddle two models. Read `result.json` back to confirm: `modelSource` says whether anything pinned the model at all,
+   of the machine, so a before/after run from two shells can silently straddle two models. (Adding `model:`
+   to a session that already has cassettes re-stales them in `verify-cassettes`; until the next re-record,
+   pin with `--model` instead.) Read `result.json` back to confirm: `modelSource` says whether anything pinned the model at all,
    and `modelPinHonored` whether the pin survived (**absent means unverifiable, not "yes"**). `models`
    lists what served the run — ignore any `<…>`-wrapped entry (`<synthetic>` marks a turn the agent
    fabricated locally, not a model).

package/CHANGELOG.md

@@ -6,6 +6,77 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [4.1.1] — 2026-09-29
+
+### Upgrade notes
+
+- **Cassettes: no re-record needed.** Nothing under `src/runtime`, `src/hostloop`, `src/staging` or
+  `baselines/` changed, `src/session.ts` gained only a `~` path helper, and `CASSETTE_VERSION` is still
+  13. A committed cassette's recorded content and fingerprints are unchanged; `verify-cassettes` and
+  `replay --strict` pass on the bundled ones. The one new `verify-cassettes` finding (a home directory
+  hidden behind `../` in a cassette's path metadata) applies only to a cassette recorded from outside
+  the repository — see Fixed.
+
+### Fixed
+
+- **A scenario whose `session:` file is missing is a usage error, not a harness bug.** `run` answered a
+  missing session file with a raw `ENOENT` under error category `internal` (exit `2`); it now refuses it
+  as category `usage` (exit `2` unchanged) with `session file not found: <path>` and a hint that
+  `session:` resolves relative to the scenario file's directory, before a run directory is created. A
+  session path that is a directory, is not readable, is not valid YAML, or cannot be read for any other
+  reason gets the same treatment, each with its own one-line message. `run <dir/>` refuses the batch before its first scenario runs, naming
+  every such file; `run --matrix` prints the reason once instead of prefixing a second "failed to load
+  session". The real `record` already refused it (exit `1`) and now gives the same clean message.
+- **`record --dry-run` reports a session file that cannot be read.** Both the single-file and the
+  directory preview list it under `inputErrors[]` with a `⚠ input error:` line that survives `--quiet`;
+  the exit code and `ok` are unchanged. Before, the single-file preview exited `0` with a clean preview
+  and the directory preview listed the file nowhere.
+- **A `session:` path starting with `~/` now expands to your home directory**, as the session guide
+  already said. It was read as a literal `~` directory, so such a scenario could not run. A cassette
+  recorded from one stores the `~/…` reference as written — never a path that spells out your home
+  directory — and resolves it home-relative, `--rerecord-stale --from-embedded` included. A
+  `--session=~/…` override on `replay`, `verify-cassettes`, `rehash` and `boundary-check` expands too.
+  A `~<user>/…` path (another user's home) is an input error on every lane, never an internal crash.
+- **A scenario file that cannot be read is a usage error on `run`.** A scenario file that is not valid
+  YAML, is not readable, or is a directory matched by `run <dir/>` was reported under category
+  `internal` with the YAML parser's multi-line source excerpt; it is now category `usage` (exit `2`
+  unchanged) with a one-line message naming the file, the same message `record --dry-run` gives.
+- **A `baseline:` path to a file that does not load is a usage error.** An absolute `baseline:` path
+  that is a directory, is not valid JSON, or is not a platform baseline surfaced as a raw error under
+  category `internal`; it now fails like an unknown baseline name, with one line saying which (`record`
+  keeps its exit `1` for it, on `--dry-run` and the real record alike). `run <dir/>`
+  refuses it before the first scenario runs instead of failing on that scenario's turn, and `lint`
+  reports it as `baseline-unknown` when the path exists on the machine it runs on (a path that does not
+  exist there is still not checked). Committed baseline names are unchanged.
+- **`verify-cassettes` flags a home directory hidden behind `../`.** A cassette stores `scenario.session`
+  and `scenarioSource` relative to itself (the fingerprint's skill sources are relative to the session
+  file's directory, its file list to each skill directory), so a target under a home directory is written
+  `../../Users/<name>/…` and never started with the `/Users/` the path scan looks for. A relative climb
+  into `Users`, `home` or `root` in any of those fields is now a `path` finding (exit `1`). The check runs
+  at verify time: `record` still writes the relative path it computes, and no redaction rule rewrites these
+  fields. To clear it, record from inside the repo that holds the session and scenario, use a `~/…`
+  `session:` (stored as written), or accept it with `--allow-path '(\.\./)+Users/<name>.*'` — an
+  existing `--allow-path '/Users/<name>.*'` does not match the relative sample.
+- **A YAML syntax error in a `--matrix` or `--answer-policy` file is reported in one line** — the
+  parser's first line, which names the problem and its position — instead of its source excerpt.
+
+### Documentation
+
+- **The companion skill caught up with 4.x.** Corrected: the session's `model:` IS part of a cassette's
+  session fingerprint — `verify-cassettes` reports a changed session as stale, while `replay` never checks
+  it (plain, `--strict` or `--assert-from`) — so adding `model:` to a session re-stales its cassettes; pin
+  with `--model` or `COWORK_HARNESS_MODEL` until the next re-record. Added: `record`'s `ok` is the exit
+  code, not the verdict (`--allow-failing` on a red run is `ok: true`; the verdict is in `results[0]`, and
+  in `items[]` on `record <dir/>`); a scenario whose only assertion is `semantic_matches` fails
+  `lint --strict` on `replay-noop`; the hostloop plugin-path suffix trap; scenario YAMLs inside a mounted
+  plugin dir are part of the staleness hash; `scan.inputHostPathTokens` and its notice; the `toolCalls`
+  field; `COWORK_HARNESS_OUTPUT_FORMAT`; the microvm capability-cache reset; why `init-redact --force`
+  drops your tailoring.
+- **Every `lint` rule is documented.** The skill's `authoring.md` now carries a table of every rule id
+  `cowork-harness lint` can report, with its severity, and a section on linting the skill itself
+  (`lint-skill`'s size caps, `--ignore-rule`, suppression markers). A test keeps the table in step with
+  the rule registries in both directions.
+
 ## [4.1.0] — 2026-09-29
 
 ### Upgrade notes

package/README.md

@@ -36,7 +36,7 @@ npm ci && npm run build
 node dist/cli.js replay examples/replays/example-pdf-skill.cassette.json
 ```
 
-(Installing globally — `npm install -g "cowork-harness@^4.1.0"` — gives you the `cowork-harness` CLI for your own
+(Installing globally — `npm install -g "cowork-harness@^4.1.1"` — gives you the `cowork-harness` CLI for your own
 scenarios and cassettes; the bundled example above also replays from a global install — see the `$(npm root -g)` path below.)
 
 Full setup → [Quick start](./docs/cli.md#quick-start).
@@ -49,8 +49,8 @@ Three ways to use this project. Each row is the whole hook — follow the link f
 
 | I want to… | Start here | Needs |
 |---|---|---|
-| **Run scenarios myself** from a terminal | **[docs/cli.md](./docs/cli.md)**<br><br>`npm i -g "cowork-harness@^4.1.0"`<br>`cowork-harness replay examples/replays/example-pdf-skill.cassette.json` | Node ≥ 22. The replay demo above is token-free and needs nothing else; live tiers above `protocol` need Docker + a staged agent binary |
-| **Have Claude Code drive it** for me | **[docs/companion-skill.md](./docs/companion-skill.md)**<br><br>`/plugin marketplace add yaniv-golan/cowork-harness`<br>`/plugin install cowork-harness@cowork-harness` | Claude Code. The skill self-bootstraps the CLI via `npx "cowork-harness@^4.1.0"` |
+| **Run scenarios myself** from a terminal | **[docs/cli.md](./docs/cli.md)**<br><br>`npm i -g "cowork-harness@^4.1.1"`<br>`cowork-harness replay examples/replays/example-pdf-skill.cassette.json` | Node ≥ 22. The replay demo above is token-free and needs nothing else; live tiers above `protocol` need Docker + a staged agent binary |
+| **Have Claude Code drive it** for me | **[docs/companion-skill.md](./docs/companion-skill.md)**<br><br>`/plugin marketplace add yaniv-golan/cowork-harness`<br>`/plugin install cowork-harness@cowork-harness` | Claude Code. The skill self-bootstraps the CLI via `npx "cowork-harness@^4.1.1"` |
 | **Gate my skill in CI** | **[docs/ci.md](./docs/ci.md)**<br><br>`- uses: yaniv-golan/cowork-harness@v4`<br>`  with: { command: replay, path: cassettes/ }` | Nothing for the token-free gate; the live lane needs a self-hosted runner with Docker + an agent binary |
 
 **In short:** three ways in (the table above). Five `fidelity:` tiers — `protocol`, `container`, `microvm`, `hostloop`,