cowork-harness 3.0.0 → 3.0.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, or asserting artifacts, egress, or sub-agent dispatch. Especially when a harness run no-ops an assertion, fails on an unanswered gate, false-greens, a steered answer never reaches the model, or a web_fetch is unexpectedly denied or gated. Also when iterating or hardening a skill across fixes, or grounding a skill's self-critique against its own run evidence — including a document-analysis skill (cap table, deck, financial model, transcript) that needs an uploaded file attached to be critiqued at all. NOT for generic unit testing (pytest/vitest of your own scripts) or non-Cowork CI. Covers the skill / run / chat / record / replay / trace / decide / assertions / scaffold commands and the session-vs-scenario split.
 metadata:
   author: cowork-harness
-  version: 3.0.0
-  tracks-harness: cowork-harness 3.0.0 (baseline desktop-1.40609.0)
+  version: 3.0.1
+  tracks-harness: cowork-harness 3.0.1 (baseline desktop-1.40609.0)
 ---
 
 # cowork-harness
@@ -25,7 +25,7 @@ flagged with a loud `::warning::`, not silent — auto-answer a gate, observe an
 allowlist). This skill exists mostly to keep you out of those traps — the Gotchas section below is
 the highest-value part. Read it.
 
-> **Version note:** the facts and `file:line` pointers here track `cowork-harness 3.0.0` (baseline
+> **Version note:** the facts and `file:line` pointers here track `cowork-harness 3.0.1` (baseline
 > `desktop-1.40609.0`). If your checkout is newer, prefer the live `--help` and — in a repo checkout —
 > `SPEC.md` / `docs/*.md` over this snapshot, and re-run the bundled linter.
 
@@ -42,7 +42,7 @@ Before the first command, confirm the CLI is reachable and **fail loud** (never
 
 - **One-shot check.** Run `cowork-harness doctor [--tier <tier>]` first — a read-only prerequisite check that inspects Docker, the staged agent, the token, and the baseline in one pass. The bullets below explain each thing it checks (and how to fix it).
 - **Replay-only? Skip `doctor`.** Replaying committed cassettes needs no Docker, no staged agent, and no token — and every tier's `doctor` validates the auth token (the live tiers also Docker + the staged agent), so a ✗ there is expected, not a blocker. Go straight to `cowork-harness replay <cassette>`.
-- **CLI on PATH, recent enough?** Run `cowork-harness --version` — this skill needs **≥ 3.0.0**. If it's missing or older, prefix every command with the version floor `npx "cowork-harness@^3.0.0" <cmd>` (Node ≥ 22), or install once with `npm i -g "cowork-harness@^3.0.0"`. **Pin `@^3.0.0`, never `@latest`** — `@latest` can silently fetch an older CLI and the new commands fail as "unknown command", whereas the floor **fails loud** if no compatible version is published.
+- **CLI on PATH, recent enough?** Run `cowork-harness --version` — this skill needs **≥ 3.0.1**. If it's missing or older, prefix every command with the version floor `npx "cowork-harness@^3.0.1" <cmd>` (Node ≥ 22), or install once with `npm i -g "cowork-harness@^3.0.1"`. **Pin `@^3.0.1`, never `@latest`** — `@latest` can silently fetch an older CLI and the new commands fail as "unknown command", whereas the floor **fails loud** if no compatible version is published.
 
   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/ci-recipe.md

@@ -1,6 +1,6 @@
 # CI recipe — replay vs live lanes
 
-Self-contained reference. Tracks `cowork-harness 3.0.0` (baseline `desktop-1.40609.0`).
+Self-contained reference. Tracks `cowork-harness 3.0.1` (baseline `desktop-1.40609.0`).
 
 **Fastest path: the packaged Action.** One step gets you `replay`/`lint`/`verify-cassettes` plus a PR
 job-summary reporter (verdict table, staleness findings, cost/turns when available):
@@ -17,7 +17,7 @@ job-summary reporter (verdict table, staleness findings, cost/turns when availab
 CLI major reaches your workflow the moment it is promoted even though your `uses:` ref never changed — so a
 copy-pasted recipe that omits the input takes a major bump with no say in it. `^2` holds the major, needs no
 patch number to remember, and only wants a human decision at the next major. Pin an exact version
-(e.g. `version: "3.0.0"`) instead when you want byte-reproducible CI.
+(e.g. `version: "3.0.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
@@ -67,7 +67,7 @@ sha256-*checked* but not hard-blocking on mismatch — it's advisory for an inte
 GitHub-hosted runners, no token/Docker/agent:
 
 ```yaml
-- run: npm i -g "cowork-harness@^3.0.0"
+- run: npm i -g "cowork-harness@^3.0.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.
@@ -342,7 +342,7 @@ jobs:
         with: { node-version: '24' }
       - uses: actions/setup-python@v5
         with: { python-version: '3.x' }                                       # python3 only — PyYAML is bundled with the linter
-      - run: npm i -g "cowork-harness@^3.0.0"
+      - run: npm i -g "cowork-harness@^3.0.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
@@ -371,7 +371,7 @@ jobs:
             echo "live=true" >> "$GITHUB_OUTPUT"
           fi
       - if: steps.guard.outputs.live == 'true'
-        run: npm i -g "cowork-harness@^3.0.0"
+        run: npm i -g "cowork-harness@^3.0.1"
       - if: steps.guard.outputs.live == 'true'
         run: cowork-harness run scenarios/ --output-format json
         env:

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

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

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

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

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

@@ -1,6 +1,6 @@
 # Scenario & session schema, assertion catalog, web_fetch, full gotchas
 
-Self-contained reference for authoring `cowork-harness` scenarios. Tracks `cowork-harness 3.0.0`
+Self-contained reference for authoring `cowork-harness` scenarios. Tracks `cowork-harness 3.0.1`
 (baseline `desktop-1.40609.0`). If your checkout is newer, prefer the live [`docs/scenario.md`](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/scenario.md),
 [`docs/session.md`](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/session.md), and `SPEC.md`.
 
@@ -100,7 +100,8 @@ allow_host_writes: true             # OPTIONAL — required to run `hostloop` fi
                                     # Read-only folders and folder-less runs need no opt-in.
 
 allow_host_hooks: true              # OPTIONAL — required to run `protocol` fidelity when a staged plugin
-                                    # declares runnable hooks (`<plugin>/hooks/hooks.json`): L0 passes
+                                    # declares runnable hooks — either `<plugin>/hooks/hooks.json` OR
+                                    # the manifest's `hooks` key: L0 passes
                                     # --plugin-dir, so the CLI executes those hooks as NATIVE HOST
                                     # processes under your account, with no container sandbox. A plugin
                                     # that declares no hooks needs no opt-in, and a misplaced root-level

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

@@ -2,7 +2,7 @@
 
 Each recipe composes facts that live scattered across SKILL.md and the other references into one
 decision path. Every one answers a question a real fleet owner had to work out the hard way.
-Tracks `cowork-harness 3.0.0` (baseline `desktop-1.40609.0`), same as SKILL.md's front-matter. Recipe 2's `resolved-tier`/`unverifiable-tier` staleness classes and
+Tracks `cowork-harness 3.0.1` (baseline `desktop-1.40609.0`), same as SKILL.md's front-matter. Recipe 2's `resolved-tier`/`unverifiable-tier` staleness classes and
 Recipe 3's `init-redact` shipped in 0.24.0 and are part of the current feature set — no version gate
 needed if your CLI meets SKILL.md's version floor.
 

package/AGENTS.md

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

package/CHANGELOG.md

@@ -6,6 +6,105 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [3.0.1] — 2026-08-30
+
+### Changed
+
+- **The README now shows the product, not just the argument for it.** Three independent reviews found
+  the same gap: for a test harness, the file a user authors is the most persuasive thing the project
+  owns, and the router split had left it with zero examples. Adds a worked scenario (prompt, scripted
+  answers, assertions) with its verdict output — the scenario is extracted and linted in place, so it is
+  a real file rather than plausible-looking YAML — plus a "What that catches" section built from an
+  actual run where a named skill was offered, declined, and the green answer looked fine anyway
+  (`skillsInvoked: []`, `toolCounts: {}`) — framed as a closed loop, since the author fixed and re-verified
+  it with the same instrument roughly ninety minutes later. An outcome example is a claim about a MOMENT;
+  the better the tool works the faster its own examples get fixed out from under it, so it needs a tense. Also names two things the docs asserted but never taught:
+  diffing the same scenario across two fidelity tiers as a discovery technique, and proving an assertion
+  can fail before trusting it. The requirements block moves below the `claude -p` argument — three
+  reviewers independently reported reading install prerequisites before any reason to want them.
+
+- **The README is now a router, not the whole manual.** It was 975 lines carrying three unrelated
+  audiences at once; it is now **282** and branches to per-audience pages: **`docs/cli.md`** (install,
+  prerequisites, commands, the two files, run output, env knobs), **`docs/companion-skill.md`** (install
+  + orientation; usage stays in `SKILL.md`), and **`docs/ci.md`** (the token-free gate, the packaged
+  Action, the live lane — written to stand alone). The harness's own pipeline and contributor suite moved
+  to `CONTRIBUTING.md`, which keeps `docs/ci.md` about *consuming* the Action rather than about this repo.
+  README keeps what all three audiences share: the fidelity-tier vocabulary, architecture, limitations,
+  the docs index, and versioning. Content moved verbatim — this is a relocation, not a rewrite.
+
+  Nothing is dropped: `Sandboxing` folded into `docs/boundary.md` and `Maintenance` into
+  `docs/maintenance.md`; `Discovery` was already covered in `docs/discovery.md`, so it was deleted rather
+  than duplicated. Every moved relative link was rewritten for its new depth, and every deep link into a
+  moved section was repointed across `docs/`, `examples/README.md`, `llms.txt` and the docs index.
+
+### Fixed
+
+- **`bump-version` did not know about the router-split pages.** `docs/cli.md`, `docs/ci.md` and
+  `docs/companion-skill.md` carry `cowork-harness@^X.Y.Z` install floors that `check:versions` enforces,
+  but the bump tool's target list predated them — so `npm run bump` rewrote every other floor and then
+  failed its own post-write lockstep check. Caught at release time by that self-check rather than
+  shipping a repo with mismatched floors. All three are now registered, and the test pinning that list
+  carries the reason.
+
+
+- **22 dead anchor links introduced by the README router split, and the guard gap that let them ship.**
+  Moving 11 `##` sections out of README left every `](#slug)` link pointing at them dangling — 19 in
+  README (including two badges and the two nav lines the page opened with), plus one each in `AGENTS.md`,
+  `docs/ci.md` and `docs/companion-skill.md`. GitHub fails these silently: the page simply does not
+  scroll. Every file-path link still resolved and every existing guard stayed green, because the anchor
+  suite validated links *into* README and *into* sibling docs but never a page's links to its **own**
+  headings. `test/repo-docs-anchors.test.ts` now covers that third case across root pages and `docs/`,
+  with a canary against a checker that extracts nothing, and was confirmed to fail against the exact
+  regression that shipped. The two nav lines are deleted rather than repointed — they were a
+  table-of-contents for a 975-line page, and "Pick your path" plus the Documentation table now do that job.
+
+  Found by two independent reviewers; the second caught the three non-README instances a README-scoped
+  fix would have missed.
+
+  Follow-up from the same review: three cross-page links still read "…\[Prerequisites](./docs/cli.md#…)
+  **below**" — resolving correctly while the sentence lied, because Prerequisites had moved to another
+  page. Reworded, and guarded: a cross-page link followed closely by "below"/"above" now fails the suite.
+  This half is the nastier one — the link works, so every link checker stays green forever.
+
+- **The `protocol` host-hook consent gate was defeatable by a spelling choice.** `allow_host_hooks`
+  (3.0.0) refuses a spawn until the operator consents to a staged plugin's hooks running as native host
+  processes — but detection keyed only on a file named `hooks.json`, and a plugin may equally declare its
+  hooks in the manifest's `hooks` key (`.claude-plugin/plugin.json`, or a bare `plugin.json`), which is
+  the more common spelling. Such a plugin sailed past the gate: reproduced end-to-end, the hook executed
+  under the operator's own account while the run went green, no consent was asked and no disclosure
+  printed. The same blind predicate feeds the tier-independent disclosure, so those hooks also ran
+  unannounced at `hostloop`. Detection now returns the UNION of both channels, which fixes the gate and
+  the disclosure together since both call through it. The `hooks/hooks.json` placement carve-out is
+  deliberately NOT extended to the manifest — that carve-out exists because a misplaced `hooks.json` is
+  inert, and a manifest-declared hook is live wherever the manifest sits.
+
+  Reported by a consumer during a 3.0.0 adoption pass, with the defect proven from committed cassettes:
+  10 of theirs carried a `SessionStart:startup` hook_started/hook_response pair from a manifest-only
+  declaration, including one recorded at `container`.
+
+### Documentation
+
+- **The pruned-agent-binary failure now has a documented remedy, with the tradeoffs named.** A Desktop
+  update deletes the prior version's staged ELF while often leaving an empty version directory, so a
+  scenario pinning that agent version dies with `baseline agent binary not found`. The code anticipates
+  this by name, but the remedy appeared in no skill surface at all — and an installed companion skill
+  ships without repo `docs/`, so the agent most likely to hit it had nothing to read. Now in
+  `docs/gotchas.md` and the skill's own reference, stating that the three remedies are NOT equivalent:
+  repin for a reproducibility-bound suite, `latest` for a one-off (a pin rots silently, `latest` drifts
+  silently — opposite failure modes), and `COWORK_HARNESS_ALLOW_AGENT_FALLBACK=1` only to unblock once,
+  never in CI, since it runs the newest sibling and downgrades the sha check to advisory.
+
+- **`permissive_auto_allow` and script-running skills is a `protocol`-specific hazard, not a general one.**
+  `Bash` is off-registry (only `Read`/`Glob`/`Grep` are default-allow), but the harness only decides how to
+  ANSWER a permission ask — whether the agent ASKS varies by command AND tier. Measured: at `protocol`, `echo
+  hello` produces no ask (green) while `python3 -c "print(42)"` produces one and fails the guard; the
+  identical command at `container` produces no ask (green), and `hostloop` routes shell through
+  `mcp__workspace__bash` entirely. So a skill running `python3 ${CLAUDE_SKILL_DIR}/scripts/…` goes red at L0
+  and green on the sandboxed tiers, while a hello-world probe is green everywhere and teaches the wrong
+  expectation. `references/fidelity-and-answers.md` carries the measured table and the three ways through; why
+  the host CLI asks for one command and not another is explicitly left untraced, and `microvm` is named as
+  unmeasured.
+
 ## [3.0.0] — 2026-08-29
 
 ### Breaking

package/CONTRIBUTING.md

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