cowork-harness 2.3.0 → 2.5.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.3.0
-  tracks-harness: cowork-harness 2.3.0 (baseline desktop-1.37937.1)
+  version: 2.5.0
+  tracks-harness: cowork-harness 2.5.0 (baseline desktop-1.37937.1)
 ---
 
 # 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 2.3.0` (baseline
+> **Version note:** the facts and `file:line` pointers here track `cowork-harness 2.5.0` (baseline
 > `desktop-1.37937.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.
 
@@ -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 **≥ 2.3.0**. If it's missing or older, prefix every command with the version floor `npx "cowork-harness@^2.3.0" <cmd>` (Node ≥ 22), or install once with `npm i -g "cowork-harness@^2.3.0"`. **Pin `@^2.3.0`, never `@latest`** — `@latest` can silently fetch an older CLI and the new commands fail as "unknown command", whereas the floor **fails loud** if no compatible version is published.
+- **CLI on PATH, recent enough?** Run `cowork-harness --version` — this skill needs **≥ 2.5.0**. If it's missing or older, prefix every command with the version floor `npx "cowork-harness@^2.5.0" <cmd>` (Node ≥ 22), or install once with `npm i -g "cowork-harness@^2.5.0"`. **Pin `@^2.5.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)
@@ -147,9 +147,9 @@ the folder basename (collision-resolved); there is no `to:` override. See `refer
 | Tier | What it gives you | Use when |
 |---|---|---|
 | `protocol` | Fastest; no sandbox, no egress | Pure protocol/answer-shape tests. **Rejected** if the scenario asserts egress. |
-| `container` | Real sandbox + real default-deny egress (**default**) | Most functional + boundary tests. |
-| `microvm` | VM-grade escape **isolation** (macOS arm64). Egress transport is the *same allowlist proxy as `container`* — not better network fidelity | Testing untrusted code escape, not network behavior. |
-| `hostloop` / `cowork` | Production split-exec: the agent loop is a **native process on the host** (no container around the file tools — matching production), with native Bash/WebFetch disabled and routed host-side via the workspace SDK-MCP server into a Docker VM sidecar | Highest-fidelity / parity runs. A writable connected folder needs `allow_host_writes: true` (see scenario-schema.md). |
+| `container` | Real sandbox + real default-deny egress (**default**). Models the **VM loop**: keeps the built-in `Bash`, but `WebFetch` is replaced by `mcp__workspace__web_fetch` — assert on that name, not `WebFetch`. (`run`/`record` only; `chat --fidelity container` still offers the built-in.) **The name is tier-specific**: `microvm` never offers it and `protocol` serves the operator's own host registry. A `tool_not_called`/`subagent_tool_absent` naming a tool its tier does not serve is **REFUSED at scenario load** (the message names what to write instead), so moving a scenario between tiers now errors rather than silently voiding the assertion — except at `protocol`, which is never judged | Most functional + boundary tests. |
+| `microvm` | VM-grade escape **isolation** (macOS arm64). Egress transport is the *same allowlist proxy as `container`* — not better network fidelity. Unlike `container`, still offers the built-in `WebFetch` | Testing untrusted code escape, not network behavior. |
+| `hostloop` / `cowork` | Production split-exec: the agent loop is a **native process on the host** (no container around the file tools — matching production), with **both** native `Bash` and `WebFetch` disabled and routed host-side via the workspace SDK-MCP server into a Docker VM sidecar (the VM loop replaces web_fetch only) | Highest-fidelity / parity runs. A writable connected folder needs `allow_host_writes: true` (see scenario-schema.md). |
 
 Set the tier in the **scenario's `fidelity:` field**, not a flag — `run` rejects `--fidelity`
 (it's a `skill`/`chat` flag; `run` takes fidelity only from the scenario). See
@@ -550,8 +550,15 @@ Recognize these before "fixing" a non-bug:
   only when you thought to ask for it, and the runs that most need this are the ones where nobody did.
   **Silent when the evidence cannot answer the question** (no workspace walk, or a tier that runs no
   scratchpad walk, absent delivery telemetry, or a resumed turn) — "cannot tell" never reads as "clean".
-  **The fix is lane-dependent.** On `lane: local`, write deliverables under `outputs/` or a connected
-  folder, or deliver them explicitly. **On `lane: remote`, moving a file under `outputs/` does NOT help** —
+  **The fix is lane-dependent — and so is the PATH.** On `lane: local`, write deliverables where the user
+  can see them, but do **not** hardcode the literal prefix `outputs/`: on the desktop-local host-loop lane
+  (what production runs) the file tools are ALREADY rooted at `outputs/`, so `outputs/x.md` doubles to
+  `outputs/outputs/x.md` and the user never sees it — a **bare filename** is correct there. At
+  `fidelity: container`/`microvm` (VM-loop, the harness default) the base is the session root instead, so a
+  bare name lands in the scratchpad and you want `{{workspaceFolder}}` or an explicit delivery. Addressing
+  a connected folder by name (`<folder>/x.md`) never reaches it on either lane — it builds a same-named
+  decoy inside `outputs`, reports success, and gives no signal. Measured 2026-08-27; see
+  [docs/scenario.md](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/scenario.md), "Where a relative path actually lands". **On `lane: remote`, moving a file under `outputs/` does NOT help** —
   nothing is delivered by location there, so only an explicit delivery counts. Assert
   **`allow_undelivered_deliverables: true`** when the leftovers are intentional (intermediates, caches,
   downloaded inputs) rather than a delivery gap.

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 2.3.0` (baseline `desktop-1.37937.1`).
+Self-contained reference. Tracks `cowork-harness 2.5.0` (baseline `desktop-1.37937.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):
@@ -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: "2.3.0"`) instead when you want byte-reproducible CI.
+(e.g. `version: "2.5.0"`) instead when you want byte-reproducible CI.
 
 Reach for the manual multi-step form below only when you need per-step control the Action's inputs don't
 cover (a custom flag combination, a different runner matrix per step, or `lint`/`verify-cassettes` gated
@@ -67,7 +67,7 @@ sha256-*checked* but not hard-blocking on mismatch — it's advisory for an inte
 GitHub-hosted runners, no token/Docker/agent:
 
 ```yaml
-- run: npm i -g "cowork-harness@^2.3.0"
+- run: npm i -g "cowork-harness@^2.5.0"
 - run: cowork-harness lint scenarios/*.yaml --strict --min-severity WARN
                                                     # no silent false-greens. WITHOUT --strict this
                                                     # step cannot fail on a WARN-class rule (e.g.
@@ -342,7 +342,7 @@ jobs:
         with: { node-version: '24' }
       - uses: actions/setup-python@v5
         with: { python-version: '3.x' }                                       # python3 only — PyYAML is bundled with the linter
-      - run: npm i -g "cowork-harness@^2.3.0"
+      - run: npm i -g "cowork-harness@^2.5.0"
       - run: cowork-harness lint scenarios/*.yaml                              # no-silent-false-green (needs python3; PyYAML bundled)
       - run: cowork-harness verify-cassettes cassettes/ --output-format json   # privacy + staleness gate
       - run: cowork-harness replay cassettes/ --output-format json             # token-free content/structure
@@ -371,7 +371,7 @@ jobs:
             echo "live=true" >> "$GITHUB_OUTPUT"
           fi
       - if: steps.guard.outputs.live == 'true'
-        run: npm i -g "cowork-harness@^2.3.0"
+        run: npm i -g "cowork-harness@^2.5.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.3.0` (baseline `desktop-1.37937.1`). This is **not** a trim of the full
+Tracks `cowork-harness 2.5.0` (baseline `desktop-1.37937.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
@@ -34,6 +34,63 @@ computed over raw rows** — that exclusion also governs `stats --group-by skill
 **total spend** still needs the raw rows (only the roll-up carries the evaluator passes); and a roll-up with `result:"error"` had an unpriced workload, so its totals
 UNDERCOUNT. The index is the only cost record that survives run-dir pruning.
 
+## An exit-2 report — which turn failed, and whether it was really infrastructure
+
+Exit 2 means no findings were produced, so the report's only job is to say what went wrong. Three fields
+carry that; read all three before touching anything.
+
+| Field | Meaning |
+|---|---|
+| `infraFailure` | the reason |
+| `infraFailurePhase` | `task turn` (the graded run) or `reflection turn` (critique's own protocol turn) |
+| `infraFailureKind` | why it failed — a harness `ErrCategory` (error envelope, exit 2/3) **or** a `resultErrorKind` (`usage_limit`/`transport`/`agent`) from a turn that RAN and errored (exit 1, top-level `error: null`). **Absent** = killed, or no envelope |
+| `gradedErrorReason` | on a `taskResult: "error"` run (still gradeable, exit 0): why the GRADED turn errored, so a quota exhaustion is not read as a skill defect |
+
+**Do NOT read "has a kind" as "the instrument is fine".** The CLI's top-level catch turns every
+unexpected throw into category **`internal`** — Docker down, container start failure, missing staged
+agent, harness bug — and `runtime` carries a refused run dir. Only **`unanswered`, `usage`, `boundary`**
+and, from the result-row taxonomy, **`usage_limit`** (quota exhausted — retry after reset) and
+**`transport`** (a tail-end drop) are the caller's problem. `agent` is not: for critique's own protocol
+turn that IS the instrument breaking. The header encodes exactly that split and fails closed (an
+unrecognized kind renders as infrastructure):
+
+- `RUN FAILED (<turn>, <kind>): …` → ordinary, actionable, instrument healthy.
+- `INFRASTRUCTURE/PROTOCOL FAILURE (<turn>): …` → `internal`/`runtime`/`agent`/unknown/killed/no-envelope.
+
+**A turn that exits 1 is not a crash.** It RAN and reported an errored result, with `error: null` and a
+full `results[0]` — an exit-code-only reading of that path is what leaves an exhausted quota looking like
+a broken instrument.
+
+**Read the reason, not the category.** The reason carries the failed turn's own message *and* hint
+verbatim. That matters most for `unanswered`, which is 36 distinct throw sites and only ONE of them is
+"the skill asked an unscripted question" — the others are a mis-typed `--answer` label, malformed
+`--answer-policy` YAML, a crashed or bad-JSON `--decider-cmd` helper, an out-of-set `--decider-llm`
+reply, an unanswered dialog/elicit, even a self-declared harness bug. A remedy picked from the category
+is wrong for nearly all of them; each site's own hint is written for its case. (Also note `--on-unanswered`
+*conflicts* with `--decider-dir`/`--decider-cmd`, so it is not a blanket fallback.)
+
+For the genuine unscripted-gate case: script it (`--answer`, `--answer-policy`), or, when the skill's
+gates are LLM-authored and reworded every run so a literal regex will not match twice, use `--decider-llm`
+(or the scenario's `on_unanswered: llm`).
+
+## Which model was graded — `gradedModels`
+
+**The two turns are a SUBPROCESS.** They inherit no model from whatever invoked `critique` — not your
+session, not a project setting. With no `--model`, the graded run uses the spawned agent's own default,
+which may not be the model you are otherwise working under, and nothing about the run announces it.
+
+`gradedModels` (text header: `graded model(s):`) is read back from the graded turn's own `result.json` and
+is the only record of which model produced the behaviour being graded — distinct from the evaluator's
+resolved model, which is a **different workload with its own default** (`claude-opus-4-8`), reported
+separately. An evaluator line naming a model you did not pass is therefore expected, not evidence your
+`--model` was ignored. Pin with `--model <id>` whenever a critique will be compared against another, and
+read `gradedModels` back to confirm it took.
+
+It is **observed, not requested** — the ids come from the model stamped on the graded turn's assistant
+messages, never from the flag. So `graded model(s): unknown` means no assistant message reached the run
+(crash, kill, or a gate before the first reply); passing `--model` does not change that line. Past runs
+can be checked without re-running: the same ids are in each kept run dir's `turns/1/result.json`.
+
 ## The report's item shape — no `title`, no `summary`
 
 Each `items[]` entry's prose fields are **`idea`** and **`recommendedAction`** — there is no `title` field
@@ -80,6 +137,20 @@ false `already-covered` verdict. It is named in `corpusExcluded` instead, and an
 specifically reports `skillMdStatus: "untracked"`, forcing the mechanical `already-covered` →
 `not-adjudicable` downgrade. `git add` it (or commit before critiquing) if it should count as evidence.
 
+## Read `referencesAccessed`, not `referencesRead`
+
+`referencesRead` counts the **`Read` tool only**. An agent that reaches a reference with a `Bash cat`, a
+`Grep` or a `Glob` leaves nothing in it, so its emptiness is **not** evidence the content went unread.
+`referencesAccessed` is the wide signal — every file reached, with the channel each was reached through
+(`read` / `grep` / `bash`) — and it is what the critique headline is computed from.
+
+Two properties to carry: only the `read` channel is strong evidence the agent opened the file (a `bash`
+entry means a command named the path); and detection **under-approximates** — a `cd` into the skill dir
+then a bare relative `cat`, a heredoc body and a `$VAR`-built path are all invisible. So an absent path is
+weak evidence, never proof. **Presence is the cannot-verify channel:** `[]` means the drive ran and saw
+nothing (a real negative); an ABSENT field means there was no observable drive, and must never be read as
+"none".
+
 ## `referencesRead` is main-agent-only — `noSkillFilesRead` is not
 
 `result.json`'s top-level `referencesRead` lists **main-agent Reads only**. A dispatcher-style skill does

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.3.0` (baseline `desktop-1.37937.1`).
+Self-contained reference. Tracks `cowork-harness 2.5.0` (baseline `desktop-1.37937.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.3.0`
+Self-contained reference for authoring `cowork-harness` scenarios. Tracks `cowork-harness 2.5.0`
 (baseline `desktop-1.37937.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`.
 
@@ -305,6 +305,10 @@ same set live from the schema.
 | `no_lost_write_back: true` | fails if the run authored an interactive HTML artifact (or a `.py`/`.js` generator of one) whose **relative** Submit/POST write-back is lost under Cowork (served from Cowork's own origin → resolves non-ok, a "Saved!" is silently false). Runs the shipped **static Tier A** analyzer over the files the run authored (diffed vs the pre-run manifest). A lost write-back on an **added** agent-authored source (`outputs/`, scratchpad) **fails**; a **pre-existing** file the skill only modified on a read-write mount is **advisory**; `-suspect` findings surface but pass. **Only `true` is valid**. **Live/verify-run only** — skipped-loud on replay; runs on every live sandbox tier including **microvm** (its outputs are snapshotted from the VM into the run dir); could-not-verify (fail-closed) on a `--resume` scratchpad or an unanalyzable candidate |
 | `tool_called: <glob>` | a tool the agent ran matched this **glob** — `*` = any run, `?` = one char, exact when literal, anchored + case-sensitive. Exact name (`Write`) matches only that tool; `mcp__workspace__*` matches any workspace tool. GLOB, not regex (`.` is literal) — an empty glob, or one containing a regex/brace-expansion metacharacter (`.*`, `.+`, `\|`, `()`, `[]`, `+`, `^`, `$`, `{}`, `\d`/`\w`/`\s`/`\b`), is **rejected at load** (a hard schema error, not a runtime warning) — it would match no real tool name and pass a `_not_`/`_absent` assert vacuously. Applies whether the glob comes from an authored scenario or a recorded cassette's frozen assert. The bundled `scenario.py lint` does NOT perform this check — only the harness enforces it, at actual load (`run`/`skill`/`record`) |
 | `tool_not_called: <glob>` | NO tool the agent ran matched this glob (`mcp__*` = "no MCP tool ran"). Same glob semantics as `tool_called`, including the empty/regex-ish rejection |
+| **legacy tool names** | The agent binary canonicalizes legacy spellings (`Task`→`Agent`, `KillShell`/`KillBash`→`TaskStop`, …) while the spawn tool list still declares the LEGACY one — so the init inventory shows `Task` and every call is emitted as `Agent`. `tool_called`/`tool_not_called`/`subagent_tool_used`/`subagent_tool_absent` match EITHER spelling, globs included. Before this, `tool_called: "Task"` could never pass and `tool_not_called: "Task"` always did. |
+| **tier vacuity — now REFUSED** | `tool_not_called` **and `subagent_tool_absent`** naming a tool the tier does not serve is rejected at scenario load (`Bash`/`WebFetch`/`NotebookEdit` at `hostloop`; `mcp__workspace__bash` at `container`/`microvm`), because it could never be violated. `scenario.py lint` WARNs on the same set before any run. The table is CLOSED to tools the harness itself removes or registers — `--tools` gates only the built-in set while every tier separately passes `--mcp-config`, so a session-MCP tool name is offered without appearing in any tool list and is never refused. Globs are never refused. `subagent_tool_absent` is covered because it reads the tools sub-agents actually USED, not a per-dispatch declared list. Under-approximates on purpose: `REPL` at hostloop is vacuous too and is not caught, which is the right side to err on for a hard refusal. |
+| `reference_read: <regex>` | a skill `references/`/`scripts/` file whose path matches this **regex** was ACCESSED — main agent or sub-agents, via `Read`, `Grep`/`Glob` (`path` input), or a `Bash`/`mcp__workspace__bash` command naming the path. Regex is **unanchored + case-insensitive** (the shared helper every regex key uses). **Under-approximates by design:** the path must be rooted in the mounted plugin, so a `cd` into the skill dir then a bare `cat references/x.md`, a heredoc body, and a `$VAR`-built path are invisible. Fails **evidence unavailable** when the run recorded no observable tool stream. Replay-capable (cassettes freeze whole tool inputs) |
+| `no_observed_reference_access: <regex>` | no OBSERVED access matched the regex — the progressive-disclosure check: a reference the skill's routing never reaches. Named `observed` because detection under-approximates (see above), so it is **not proof the file went unread** — an agent that `cd`s and `cat`s it passes. Fails **evidence unavailable** rather than passing vacuously when no observable tool stream was recorded |
 | `tool_result_contains: <str>` | a tool result includes the literal string (content / replay-checkable — substring match) |
 | `tool_result_not_contains: <str>` | no tool result includes the literal string (content / replay-checkable; fails loud when tool results are absent) |
 | `tool_result_matches: <regex>` | the regex sibling of `tool_result_contains` — case-insensitive regex matches at least one tool result; use for an error-signature family, not just one literal string |

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.3.0` (baseline `desktop-1.37937.1`), same as SKILL.md's front-matter. Recipe 2's `resolved-tier`/`unverifiable-tier` staleness classes and
+Tracks `cowork-harness 2.5.0` (baseline `desktop-1.37937.1`), same as SKILL.md's front-matter. Recipe 2's `resolved-tier`/`unverifiable-tier` staleness classes and
 Recipe 3's `init-redact` shipped in 0.24.0 and are part of the current feature set — no version gate
 needed if your CLI meets SKILL.md's version floor.
 

package/.claude/skills/cowork-harness/scripts/assertion-keys.json

@@ -35,6 +35,7 @@
     "no_hook_blocked",
     "no_lost_write_back",
     "no_mcp_error",
+    "no_observed_reference_access",
     "no_path_denied",
     "no_scratchpad_leak",
     "no_skill_triggered",
@@ -46,6 +47,7 @@
     "question_context",
     "question_options",
     "questions_count_max",
+    "reference_read",
     "replay_protocol_fidelity",
     "result",
     "self_heal_ran",

package/.claude/skills/cowork-harness/scripts/scenario.py

@@ -80,6 +80,10 @@ CONTENT_KEYS = {
     "tool_result_not_matches",
     "tool_called",
     "tool_not_called",
+    # Replay re-derives these from the SAME frozen tool inputs the live run used (a cassette stores whole
+    # tool inputs), so they are content keys, not live-only.
+    "reference_read",
+    "no_observed_reference_access",
     "subagent_tool_used",
     "subagent_tool_absent",
     "subagent_dispatched",
@@ -294,6 +298,8 @@ REGEX_KEYS = {
     "hook_blocked",
     "tool_result_matches",
     "tool_result_not_matches",
+    "reference_read",
+    "no_observed_reference_access",
 }
 VALID_ON_UNANSWERED = {"fail", "prompt", "first", "llm"}
 VALID_TIERS = ("protocol", "container", "microvm", "hostloop", "cowork")
@@ -488,6 +494,30 @@ def lint_doc(doc, path, raw_lines):
 
     fidelity = (doc.get("fidelity") or "container")
     lane = (doc.get("lane") or "local")
+
+    # W: no `fidelity:` — the default models the WRONG LANE.
+    # `container` (the schema default) models VM-loop; production runs HOST-LOOP, gate 1143815894 is
+    # force-ON in every shipped baseline. So an omitted key measures the scenario against a lane real
+    # users are not on: the file tools resolve a bare relative path differently, the shell starts
+    # somewhere else, and the offered tool set differs (measured 2026-08-27).
+    # Read the KEY, not the resolved value: `fidelity: container` is a deliberate choice and must not warn.
+    # DEPRECATION — `fidelity:` becomes REQUIRED in the next major; this is the warning window.
+    if "fidelity" not in doc:
+        findings.append(
+            Finding(
+                "WARN",
+                "fidelity-defaulted",
+                "no `fidelity:` — defaulting to `container`, which models the VM-LOOP lane. Production "
+                "runs HOST-LOOP by default (gate 1143815894), so this scenario is likely measured "
+                "against a lane your users are not on.",
+                "Name a tier: `fidelity: hostloop` to match production, `fidelity: cowork` to auto-pick "
+                "the way Cowork does, or `fidelity: container` to keep today's behaviour deliberately. "
+                "Switching tiers can COST you assertions: `no_scratchpad_leak` is container-only (an "
+                "error elsewhere) and `transcript_no_host_path` fails by design at hostloop/protocol. "
+                "The default is being removed — `fidelity:` becomes REQUIRED in the next major.",
+                path,
+            )
+        )
     items = _assert_items(doc)
     assert_keys = _all_assert_keys(items)
     has_expect_denied = bool(doc.get("expect_denied"))
@@ -559,6 +589,44 @@ def lint_doc(doc, path, raw_lines):
     # warns at run start, after authoring). Lint is deliberately STRICTER than the runtime: the docs
     # declare the combination incompatible, so authoring it is a bug even if a tool-free run could
     # accidentally pass. `cowork` gets a WARN naming the baseline-gate resolution dependency (the
+    # `tool_not_called` naming a tool the TIER does not serve can never be violated — it passes
+    # vacuously and verifies nothing. Expressible offline because the mapping is a harness constant
+    # (WORKSPACE_TOOL_ALIASES / VM_LOOP_TOOL_ALIASES), NOT a baseline read. Deliberately literals only,
+    # and deliberately a closed table: `--tools` gates the BUILT-IN set alone while every tier separately
+    # passes --mcp-config, so a session-MCP tool name is offered without appearing in any tool list and
+    # must never be flagged here. The harness refuses these at load; this catches them before any run.
+    _TIER_VACUOUS = {
+        "hostloop": {"Bash": "mcp__workspace__bash", "WebFetch": "mcp__workspace__web_fetch", "NotebookEdit": None},
+        "container": {"mcp__workspace__bash": "Bash"},
+        "microvm": {"mcp__workspace__bash": "Bash", "mcp__workspace__web_fetch": "WebFetch"},
+        # `protocol` absent on purpose: it passes no tool flags, so its surface is the operator's own
+        # host CLI registry — machine-dependent and about a different product.
+    }
+    # BOTH negative tool keys: `subagent_tool_absent` is judged against the tools sub-agents actually
+    # USED, not a per-dispatch declared list, so a tool the tier never serves makes it equally vacuous.
+    for _key in ("tool_not_called", "subagent_tool_absent"):
+        for _v in _assert_values(items, _key):
+            if not isinstance(_v, str) or "*" in _v or "?" in _v:
+                continue  # a glob is not a literal claim about one tool
+            _repl = _TIER_VACUOUS.get(fidelity, {})
+            if _v not in _repl:
+                continue
+            _instead = _repl[_v]
+            findings.append(
+                Finding(
+                    "WARN",
+                    "tool-not-called-tier-vacuous",
+                    f"`{_key}: {_v}` on `fidelity: {fidelity}` — that tier does not serve "
+                    f"`{_v}` at all, so this can never be violated and verifies nothing.",
+                    (
+                        f"Assert `{_key}: {_instead}` instead — that is what the tier serves in its place."
+                        if _instead
+                        else f"The {fidelity} tier removes `{_v}` outright; drop this assertion."
+                    ),
+                    path,
+                )
+            )
+
     # linter stays offline — the message carries the gate fact instead of reading a baseline).
     if "transcript_no_host_path" in assert_keys:
         if fidelity in ("hostloop", "protocol"):
@@ -992,6 +1060,26 @@ def lint_doc(doc, path, raw_lines):
             )
         )
 
+    # Same shape for the reference-access pair: `reference_read: R` and `no_observed_reference_access: R`
+    # with the IDENTICAL regex cannot both hold. Compared as raw pattern strings — two different regexes
+    # that happen to match the same path are NOT a contradiction (the linter cannot know the paths), so
+    # this only fires on the case that is unambiguously self-defeating.
+    read_pats = {v for v in _assert_values(items, "reference_read") if isinstance(v, str)}
+    unread_pats = {v for v in _assert_values(items, "no_observed_reference_access") if isinstance(v, str)}
+    both_refs = sorted(read_pats & unread_pats)
+    if both_refs:
+        findings.append(
+            Finding(
+                "ERROR",
+                "reference-access-contradiction",
+                f"assert requires {both_refs} to be both accessed (`reference_read`) and never observed "
+                "(`no_observed_reference_access`) — no run can satisfy that, so this would spend a run to fail.",
+                "Drop whichever half the scenario does not mean. To check that ONE reference is reached while "
+                "another is not, give the two keys different patterns.",
+                path,
+            )
+        )
+
     # W: double-quoted regex with a backslash (raw-text scan — the parser already ate it)
     findings.extend(_lint_regex_quoting(path, raw_lines))