cowork-harness 0.12.0 → 0.14.0

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

@@ -1,5 +1,5 @@
 {
-  "$comment": "GENERATED from the Zod Assertion schema (src/types.ts) by scripts/gen-schema.ts — do not edit; run `npm run schema`.",
+  "$comment": "GENERATED from the Zod schemas (src/types.ts) by scripts/gen-schema.ts — do not edit; run `npm run schema`.",
   "keys": [
     "allow_l0_plugin_divergence",
     "allow_missing_capability",
@@ -32,6 +32,19 @@
     "transcript_not_matches",
     "user_visible_artifact"
   ],
+  "topLevelKeys": [
+    "answers",
+    "assert",
+    "baseline",
+    "expect_denied",
+    "fidelity",
+    "name",
+    "on_unanswered",
+    "prompt",
+    "requires_capabilities",
+    "session",
+    "skills"
+  ],
   "verdictModifierKeys": [
     "allow_l0_plugin_divergence",
     "allow_missing_capability",

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

@@ -116,8 +116,11 @@ if UNCLASSIFIED_KEYS:
         "— add them to the linter's CONTENT/GATE/MANIFEST/LIVE_ONLY/VERDICT_MODIFIER sets.",
         file=sys.stderr,
     )
-# every valid top-level scenario key
-TOP_LEVEL_KEYS = {
+# Embedded fallback for the top-level scenario keys — kept EQUAL to the generated `topLevelKeys`
+# (test-enforced, like _CLASSIFIED_KEYS for assert keys) so a missing assertion-keys.json can't silently
+# reintroduce key drift. `profile`/`assertions` are NOT here — they are deprecated aliases handled by the
+# special-cases in the unknown-key check below (`k != "assertions" and k != "profile"`).
+_EMBEDDED_TOP_LEVEL_KEYS = {
     "name",
     "baseline",
     "session",
@@ -128,7 +131,32 @@ TOP_LEVEL_KEYS = {
     "expect_denied",
     "assert",
     "skills",  # F-6: opt-in skill-staleness hash scope
+    "requires_capabilities",  # Fix 4b: scenario-level required-capability declaration (pre-flight gate)
 }
+
+
+def _load_top_level_keys():
+    """The authoritative top-level scenario-key set, generated from the Zod ScenarioObject schema into
+    `assertion-keys.json` (so the unknown-key check can't drift and false-flag a valid key). Falls back to
+    the embedded `_EMBEDDED_TOP_LEVEL_KEYS` (kept equal to the generated list) with a loud warning if the
+    file is missing or predates the `topLevelKeys` field."""
+    p = Path(__file__).resolve().parent / "assertion-keys.json"
+    try:
+        keys = json.loads(p.read_text(encoding="utf-8")).get("topLevelKeys")
+        if not keys:
+            raise KeyError("topLevelKeys")
+        return set(keys)
+    except Exception:
+        print(
+            f"::warning:: assertion-keys.json missing or has no topLevelKeys next to scenario.py ({p}) — "
+            "using a built-in top-level-key list that may be stale (run `npm run schema`).",
+            file=sys.stderr,
+        )
+        return set(_EMBEDDED_TOP_LEVEL_KEYS)
+
+
+# every valid top-level scenario key (generated from the zod ScenarioObject schema; see _load_top_level_keys)
+TOP_LEVEL_KEYS = _load_top_level_keys()
 REGEX_KEYS = {
     "transcript_matches",
     "transcript_not_matches",

package/CHANGELOG.md

@@ -4,6 +4,87 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). The project uses
 [Semantic Versioning](https://semver.org/); pre-1.0 minor versions may include breaking changes.
 
+## [Unreleased]
+
+## [0.14.0] — 2026-06-25
+
+### Added
+
+- **`replay` surfaces staleness + skipped assertions in JSON.** Each `--output-format json` result now carries
+  `staleness[]` (class-tagged: `baseline` / `skill` / `shared-root` / `format` / `unverifiable-baseline` /
+  `unverifiable-skill`) and `skippedAssertions` (`{full, partial}`), so a token-free CI gate can see a stale
+  cassette or live-only assertions it didn't evaluate WITHOUT the verdict changing — a stale but otherwise
+  passing replay stays `ok:true` by default. Previously these were stderr-only `::warning::` lines invisible
+  to a JSON consumer.
+- **`replay --fail-on-skill-drift`.** A narrower release gate than `--strict`: fails only on skill-source drift
+  (`skill` / `shared-root` / `unverifiable-skill` — "can't verify the skill ⇒ not green"), while baseline /
+  format / environment-level staleness stays a non-failing warning. `--strict` remains the superset (fails on
+  every class).
+
+### Fixed
+
+- **Linter no longer false-flags `requires_capabilities`.** `cowork-harness lint` warned `unknown-top-key` on
+  the valid scenario field `requires_capabilities` (its hand-maintained top-level-key list had drifted from the
+  schema). The list is now generated from the Zod `ScenarioObject` schema (like the assertion-key list), so it
+  can't drift; a parity test guards it.
+- **SKILL.md capability pre-flight wording corrected.** It described `requires_capabilities` as skill-declared
+  and said the harness "warns before the run"; it is a **scenario field** and the harness **aborts before the
+  paid run (exit 3)** when the image omits a required capability (unless `allow_missing_capability: true`). The
+  authoritative `docs/scenario.md` was already correct.
+
+## [0.13.0] — 2026-06-25
+
+### Added
+
+- **`inspect <run-id | run-dir>` — see what a run produced.** Lists the run's artifacts and prints a shallow
+  field preview of each JSON artifact (scalars inline, arrays as a count, nested objects collapsed), so
+  "did it do the job?" is a first-class check instead of hand-parsing `…/mnt/outputs/...`. `--output-format
+  json` emits a structured digest. When the work dir was torn down (a non-`--keep` container/microvm run),
+  the artifact manifest still prints from `result.json` and the preview notes it's unavailable.
+- **A whiffed gate no longer discards the paid run.** When a run exits on an unanswered gate
+  (`on_unanswered: fail`), the harness now salvages a **PARTIAL** `result.json` (+ `run.jsonl`/`trace.json`)
+  with the artifacts the agent wrote before the whiff, then still exits 2. The run dir is printed so you can
+  `inspect` it. `partial` and `unansweredGate` are new `RunResult` fields; `verify-run` and `scaffold`
+  refuse to treat a partial run's half-finished output as a passing result (scaffold still emits the gates,
+  drops the artifact/result asserts, and warns loudly).
+- **Capability pre-flight — fail fast.** A skill that declares `requires_capabilities` against an image that
+  provably omits them now **aborts before the (paid) run** (`exit 3`) instead of running ~12 min to a verdict
+  that's already known — unless the scenario asserts `allow_missing_capability: true`, which downgrades it to
+  a notice and proceeds. `doctor` also surfaces the full-parity remedy on its agent-image line.
+
+### Changed
+
+- **LLM decider tolerates a near-miss label.** `--decider-llm` now binds a reply like `Confirmed.` or
+  `"Confirmed"` to the label `Confirmed` (trailing sentence punctuation / surrounding quotes trimmed before
+  matching) instead of failing loud — common on binary confirm gates. The `:` of the `OTHER:` free-text
+  sentinel is never stripped, and fuzzy substring matching stays off, so the change can't mis-bind. The
+  tolerance lives in `matchLabel` itself, so the web_fetch-approval path gets it too (a `Deny.` reply now
+  binds `Deny`).
+- **`runs gc` → top-level `prune`; the `runs` namespace is dropped.** Pruning accumulated run dirs is now
+  `cowork-harness prune [--keep-last <n>] [--dry-run] [<runs-dir>]` (same flags). `runs` was a namespace with
+  a single member and collided confusingly with `run` (execute); removing it leaves `run` = execute,
+  inspection verbs (`trace`/`inspect`/`verify-run`/`scaffold`) top-level, and `prune` for cleanup.
+
+### Fixed
+
+- **Session-protocol over-cap test no longer flakes.** The over-cap control-out test read
+  `control-out.jsonl` synchronously, but the stream opens it asynchronously (`createWriteStream`, flags
+  `"a"`), so under load the file may not exist yet at the read — a flaky ENOENT. The over-cap frame is
+  rejected before any write, so a missing file means nothing was written; the test now treats absence as
+  empty.
+
+### Docs
+
+- **Documented the LLM-decider free-text path.** `--decider-llm` supplies free text via `OTHER: <value>`
+  on an options-bearing gate; a bare out-of-set answer (no matching label, no `OTHER:`) fails loud
+  (`UnansweredError` → exit 2), never stalling or guessing, and open-ended (no-option) gates need no
+  prefix. Noted in the decider section of `fidelity-and-answers.md` and cross-referenced from the lone
+  `OTHER:` mention in `SKILL.md` so the two don't drift.
+- **Documented the live real-document validation workflow.** A new SKILL.md section covers driving a skill
+  against real input documents (not recording a cassette): explore with `--decider-llm --intent`, script the
+  load-bearing and binary-confirm gates, budget ~1 re-run per file (a whiffed gate now salvages a partial
+  run), and `inspect` the outputs to judge correctness.
+
 ## [0.12.0] — 2026-06-24
 
 ### Added

package/README.md

@@ -93,10 +93,11 @@ Skill testing is the headline use, but the tool is a general harness over the Co
 | `skill <folder> "<prompt>"` | Run a local skill/plugin folder once against the staged agent | ad-hoc "is the skill alive / does it do X?" — the fast inner loop |
 | `run <scenario.yaml \| dir/>` | Run authored scenarios with `assert:` + a CI-ready exit code | you want a repeatable, **asserted regression test** |
 | `chat <folder> [prompt]` | Interactive multi-turn REPL against a skill (TTY); optional seed prompt is sent as the first turn. `--upload <file>` / `--folder <dir>` (repeatable) attach files/project folders; `--verbose` / `-V` shows thinking blocks + tool inputs; `--fidelity protocol\|container\|hostloop` | debugging a multi-turn flow by hand |
-| `record` / `replay` | `record` saves a control-protocol cassette (one scenario, or batch a `dir/`; `--rerecord-stale` refreshes only drifted ones; `--concurrency <N>` records a batch N at a time — runs are fully isolated, so it just bounds Docker/API pressure; `--max-artifact-bytes` raises the 64 KiB inline-body cap; `--dry-run` previews the scenarios + token/binary checks without recording; answer gates **live during the recording** with `--decider-dir`/`--decider-llm`/`--on-unanswered first` instead of pre-scripting them — a live decider flags the cassette non-deterministic but it still replays deterministically); `replay <file.cassette.json \| dir/>` runs a cassette **file or a `dir/` of `*.cassette.json`** deterministically (`--strict` fails on a stale one; exits on the worst verdict) | **token-free, Docker-free CI** from a once-recorded run |
+| `record` / `replay` | `record` saves a control-protocol cassette (one scenario, or batch a `dir/`; `--rerecord-stale` refreshes only drifted ones; `--concurrency <N>` records a batch N at a time — runs are fully isolated, so it just bounds Docker/API pressure; `--max-artifact-bytes` raises the 64 KiB inline-body cap; `--dry-run` previews the scenarios + token/binary checks without recording; answer gates **live during the recording** with `--decider-dir`/`--decider-llm`/`--on-unanswered first` instead of pre-scripting them — a live decider flags the cassette non-deterministic but it still replays deterministically); `replay <file.cassette.json \| dir/>` runs a cassette **file or a `dir/` of `*.cassette.json`** deterministically (`--strict` fails on any stale one, `--fail-on-skill-drift` only on skill-source drift; staleness is also reported per-result in `staleness[]` for a JSON gate; exits on the worst verdict) | **token-free, Docker-free CI** from a once-recorded run |
 | `verify-cassettes <file\|dir>` | Token-free CI gate over committed cassettes: a privacy scan (email/currency/domain → exit 1; whole-token allows via `--allow` / class-scoped `--allow-domain` / `--allow-email` / `--allow-file`) + a staleness check (`--skip-privacy` or `--skip-staleness` to run only one half). A dir argument scans `*.cassette.json` in that dir only (**non-recursive**) | gating **committed cassettes** against PII leaks + "edited the skill, forgot to re-record" |
 | `verify-run <run-dir> <scenario.yaml>` | Re-evaluate a scenario's `assert:` (and, when the scenario declares `answers:`, whether they still match the run's actual gates) against an already-kept run dir — **no live agent, no tokens, no Docker** (~1s) | iterating on a wrong assertion or a drifted `answer` without a full live re-record |
 | `trace <run-id>` | Digest a run's `events.jsonl` (`--view tools\|questions\|dispatches`; legacy `--tools` / `--gates` / `--dispatches` aliases still accepted) | "how many sub-agents *actually* dispatched, and which?" |
+| `inspect <run-id>` | Show what a run **produced**: the artifacts + a shallow field preview of each JSON artifact (`--output-format json` for a digest). Works on a salvaged partial run too | "did it do the job?" — without hand-parsing `…/mnt/outputs/…` |
 | `scaffold <run-id>` | Turn a kept run into a starter scenario YAML (gates→answers, artifacts→`file_exists`); `--from-run <id>` is a deprecated alias for the positional | authoring a scenario from a real run instead of guessing |
 | `python3 …/scenario.py scaffold --name <name> --skill <dir>` | Generate a starter scenario skeleton from scratch (the `…` is `.claude/skills/cowork-harness/scripts/`) | starting a new scenario when you have no prior run |
 | `lint <scenario.yaml \| dir/>…` | Check scenarios for silent false-greens — assertions placed on the wrong CI lane, mixed content/live keys, missing `controlOut`-required keys (files or a directory of `*.yaml`/`*.yml`; bundled `scenario.py`; needs python3 — PyYAML is bundled) | before committing a new scenario or after changing assertions |
@@ -106,7 +107,7 @@ Skill testing is the headline use, but the tool is a general harness over the Co
 | `boundary-check [baseline] [--session <file>]` | Prove the sandbox enforces Cowork's limitations; `--session` folds a session's `egress.extra_allow` into the probe allowlist | verifying the harness's own fidelity |
 | `sync` / `list` | Derive/refresh & list platform baselines from the Desktop install | after Claude Desktop updates (baselines ship, so it's optional otherwise) |
 | `doctor [--tier <t>]` | Read-only prerequisite check, per tier (Docker + agent image for `container`/`hostloop`; **Lima** for `microvm`; plus staged agent, token, baseline); prints the exact `docker build` line if the agent image is missing | "can I run the live tiers — what's missing?" before a first live run |
-| `runs gc [--keep-last <n>]` | Prune accumulated run dirs (keeps the N most recent per scenario; pinned `--session-id` runs are never pruned); `--dry-run` | the machine-global runs root has grown and you want space back |
+| `prune [--keep-last <n>]` | Prune accumulated run dirs (keeps the N most recent per scenario; pinned `--session-id` runs are never pruned); `--dry-run` | the machine-global runs root has grown and you want space back |
 | `rehash <dir/>` | Migrate cassette fingerprints to the current format version when the content is provably unchanged (`--dry-run`); no re-record needed | a cassette-format bump flagged committed fixtures as stale |
 | `vm <init\|status\|delete\|prune>` | Manage the L2 Apple-VZ / Lima microVM (`prune` removes orphaned VMs left by config/agent-version changes) | running `--fidelity microvm` |
 
@@ -207,7 +208,7 @@ This repo ships a **companion skill** (`.claude/skills/cowork-harness/`) that te
 /plugin install cowork-harness@cowork-harness
 ```
 
-The skill **self-bootstraps the CLI**: if `cowork-harness` isn't on your PATH it falls back to `npx cowork-harness@>=0.12.0` (a version floor that fails loud rather than silently fetching a too-old CLI; Node ≥ 20). Tiers above `protocol` still need Docker/Lima and a Claude Desktop agent binary — see the prerequisites below.
+The skill **self-bootstraps the CLI**: if `cowork-harness` isn't on your PATH it falls back to `npx cowork-harness@>=0.14.0` (a version floor that fails loud rather than silently fetching a too-old CLI; Node ≥ 20). Tiers above `protocol` still need Docker/Lima and a Claude Desktop agent binary — see the prerequisites below.
 
 It also follows the open [Agent Skills](https://github.com/vercel-labs/skills) spec, so it installs cross-editor (Cursor, Codex, OpenCode, …) by pointing the `npx skills` CLI at `.claude/skills/cowork-harness` in this repo. (Working *inside* this repo, the skill auto-loads as a project skill — no install needed.)
 
@@ -473,7 +474,7 @@ Unit tests cover the scripted-answer logic, the egress allowlist matcher, the se
 - `COWORK_AGENT_IMAGE=<tag>` — override the agent image name (default `cowork-agent-base:2`); `COWORK_AGENT_BINARY=<path>` — override the auto-detected staged agent ELF.
 - `COWORK_SKIP_CAPABILITY_PROBE=1` — skip the per-run capability probe (the harness otherwise probes the agent image/VM for the document/OCR/Office capabilities the real Cowork rootfs ships and **fails a run that uses one the image omits** — a likely false negative; suppress per-scenario with `allow_missing_capability: true`, or rebuild full parity).
 - `COWORK_HARNESS_DECIDER_DIR_POLL_MS` / `_TIMEOUT_MS` — tune the `--decider-dir` rendezvous poll/backstop; `COWORK_HARNESS_DECIDER_CMD_TIMEOUT_MS` / `COWORK_HARNESS_LLM_TIMEOUT_MS` — backstop a hung `--decider-cmd` helper / `--decider-llm` model call (default 600 s, fail loud); `COWORK_HARNESS_DIALOG_TIMEOUT_MS` — override the 6 s dialog auto-cancel.
-- `COWORK_HARNESS_RUNS_DIR` (or the `--run-dir <path>` flag) — override the default run-output root `~/.cowork-harness/runs` (kept out of any working tree so sensitive skill inputs/outputs don't land in a repo). Precedence: `--run-dir` > env > default. The root is flat and machine-global (shared across projects); pinned `--session-id` runs are guarded against cross-project overwrite, and `runs gc` never prunes them. In CI, set it to a workspace path (e.g. `runs`) so artifact upload can collect the runs. `COWORK_HARNESS_ALLOW_FOREIGN_RESUME=1` overrides the guard that blocks `--resume` onto another project's pinned session.
+- `COWORK_HARNESS_RUNS_DIR` (or the `--run-dir <path>` flag) — override the default run-output root `~/.cowork-harness/runs` (kept out of any working tree so sensitive skill inputs/outputs don't land in a repo). Precedence: `--run-dir` > env > default. The root is flat and machine-global (shared across projects); pinned `--session-id` runs are guarded against cross-project overwrite, and `prune` never prunes them. In CI, set it to a workspace path (e.g. `runs`) so artifact upload can collect the runs. `COWORK_HARNESS_ALLOW_FOREIGN_RESUME=1` overrides the guard that blocks `--resume` onto another project's pinned session.
 - **Networking / loop:** `COWORK_EGRESS_PROXY` overrides the egress-proxy URL injected into the sandbox; `COWORK_PROXY_IMAGE` overrides the egress proxy Docker image name (default `cowork-egress-proxy:1`); `COWORK_DOCKER_NETWORK` pins the Docker network the agent container joins; `CLAUDE_FORCE_HOST_LOOP=1` forces the host-loop path regardless of the baseline's loop decision (the `cowork` tier's auto-pick). `COWORK_LIMACTL` overrides the `limactl` binary path (default `/opt/homebrew/bin/limactl`).
 - **Strictness escape hatches** (the harness fails loud by default): `COWORK_HARNESS_SOFT_MISSING=1` downgrades a missing mount source from a hard error to warn-and-exclude; `COWORK_HARNESS_ALLOW_CONFIG_DIR_WRITE=1` permits writing into an existing pinned `plugins.config_dir` (otherwise refused, to avoid clobbering a real Claude config).
 - **Staleness boundary:** the cassette-staleness skill hash uses the **git-tracked** file set of each skill/plugin source dir by default (a non-repo dir falls back to a raw walk; OS-junk like `.DS_Store` is always excluded). `COWORK_HARNESS_GITSET=0` opts out to the legacy raw walk for every dir. `COWORK_HARNESS_DEBUG_SKILLHASH=1` dumps the exact file set feeding the hash on a staleness mismatch (and flags OS-junk) so a drift source is one line. Declare per-plugin non-runtime paths in a `.cowork-hashignore` file (or the session `staleness.hash_ignore`). `COWORK_HARNESS_AGENT_SCOPE=skill` (opt-in) refines a scenario's `skills:` scope so a **skill-named** `agents/<name>.md` re-stales only that skill's cassettes instead of the whole fleet (generic agents stay shared; stamped into the fingerprint, so flipping it is a one-time re-record like `GITSET`).

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { readFileSync, writeFileSync, mkdirSync, readdirSync, writeSync, existsSync } from "node:fs";
-import { join, basename, resolve, isAbsolute } from "node:path";
+import { join, basename, resolve, isAbsolute, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parse as parseYaml } from "yaml";
 import { Scenario, AnswerRule, Assertion } from "./types.js";
@@ -24,6 +24,7 @@ import { loadDotenv } from "./dotenv.js";
 import { makeRenderer, renderStart, renderFooter, startHeartbeat } from "./run/renderer.js";
 import { resolveEventsFile, buildTrace, formatTrace, buildGateTrace, formatGateTrace, buildDispatchTree, formatDispatchTree, noteRunsLocation, } from "./run/trace-view.js";
 import { buildScaffold } from "./run/scaffold.js";
+import { buildInspectView } from "./run/inspect-view.js";
 import { pkgVersion, jsonEnvelope, jsonError, parseOutputFormat } from "./run/envelope.js";
 import { computeVerdict } from "./run/verdict.js";
 import { evaluate, hostMatches } from "./assert.js";
@@ -71,13 +72,14 @@ const HELP = `cowork-harness <command>   (v${"$VERSION"})
       [--decider-llm [--intent "…"]] | [--on-unanswered fail|first]   answer live via a model / auto-pick
                                (a live decider flags the cassette non-deterministic; it still replays deterministically)
   replay <file|dir>            deterministic protocol-replay of a cassette or a dir of them (no token, no Docker)
-      [--strict]               fail (exit 1) on a stale cassette instead of warning
+      [--strict]               fail (exit 1) on ANY stale cassette instead of warning
+      [--fail-on-skill-drift]  fail only on skill-source drift (skill/shared-root); baseline drift stays a warning
       [--output-format json]
   verify-cassettes <file|dir>  CI gate (no token): privacy scan + staleness — exit 1 on finding or drift
       [--skip-privacy|--skip-staleness]  skip one check
       [--allow <regex>]... [--allow-domain/-email <regex>]... [--allow-file <path>]... [--output-format json]
   rehash <dir/>                migrate cassette fingerprints to current version when content is provably unchanged (requires contentSig from v3+)
-  runs gc [--keep-last <n>]    prune accumulated run dirs, keeping N most recent per scenario (default: 5)
+  prune [--keep-last <n>]      prune accumulated run dirs, keeping N most recent per scenario (default: 5)
 
 ── CI lint + assertion reference ──────────────────────────────────────────────
   lint <scenario.yaml | dir/>…  check scenarios for silent false-greens (bundled scenario.py; needs python3 — PyYAML is bundled)
@@ -92,6 +94,8 @@ const HELP = `cowork-harness <command>   (v${"$VERSION"})
       [--output-format json]   structured rows
   verify-run <run-dir> <scenario.yaml>   re-evaluate assert: against a kept run dir (no live agent, ~1s)
       [--output-format json]
+  inspect <run-id | run-dir>   show what a run produced: artifacts + a shallow field preview of each JSON artifact
+      [--output-format json]   structured digest
   scaffold <run-id | run-dir>  turn a kept run into a starter scenario YAML (gates→answers, artifacts→file_exists)
       [--out <file.yaml>]      write to a file (default: stdout)
 
@@ -259,18 +263,19 @@ const SUBCOMMAND_USAGE = {
         '       answer gates LIVE: [--decider-dir <dir>] (single scenario only) | [--decider-llm [--intent "<one line>"]] | [--on-unanswered fail|first]\n' +
         "       (a live decider flags the cassette non-deterministic — re-recording may drift; replay stays deterministic. --rerecord-stale rejects these flags.)\n" +
         "       NOTE: --allow-failing only relaxes the post-run VERDICT gate; it does NOT salvage an unanswered gate (that throws before any cassette is written — use --on-unanswered first / a decider).",
-    replay: "usage: replay <file.cassette.json | dir/> [--strict] [--output-format text|json]",
+    replay: "usage: replay <file.cassette.json | dir/> [--strict] [--fail-on-skill-drift] [--output-format text|json]",
     "verify-cassettes": "usage: verify-cassettes <file|dir> [--skip-privacy|--skip-staleness] [--allow <regex>]... [--allow-domain <regex>]... [--allow-email <regex>]... [--allow-file <path>]... [--output-format json]",
-    trace: "usage: trace <run-id | run-dir | events.jsonl> [--view tools|questions|dispatches] [--output-format json]\n       --view tools       tool call / result rows\n       --view questions   gate lifecycle (question → answer → delivered)\n       --view dispatches  sub-agent dispatch tree + dispatch_count_max\n       (default: all views)",
+    trace: "usage: trace <run-id | run-dir | events.jsonl> [--view tools|questions|dispatches] [--output-format json]\n       --view tools       tool call / result rows\n       --view questions   gate lifecycle (question → answer → delivered)\n       --view dispatches  sub-agent dispatch tree + dispatch_count_max\n       (default: all views)\n       (for what the run PRODUCED — artifacts — use `inspect`)",
     assertions: "usage: assertions --list [--output-format json]",
     scaffold: "usage: scaffold <run-id | run-dir> [--out <file.yaml>]\n       Turns a kept run into a starter scenario YAML (gates→answers, artifacts→file_exists).\n       Positional <run-id | run-dir> is the canonical form.",
     decide: 'usage: decide [--question <q>] [--option <o>]... [--decider-cmd <cmd> | --decider-llm] [--answer "<q>=<label>"]... [--answer-policy <p>] [--intent <s>] [--output-format json]',
     gates: "usage: gates <dir> [--follow]   (stream pending in-band gates as JSON lines; pair with --decider-dir)",
     answer: 'usage: answer <dir> --gate <N> (--choose <label> [--choose <label>…] | --answer "<q>=<label>")   (write an in-band gate reply atomically; repeat --choose for a multiSelect gate)',
     "verify-run": "usage: verify-run <run-dir> <scenario.yaml> [--output-format json]   (re-evaluate a scenario's assert: against a kept run dir; no live agent)",
+    inspect: "usage: inspect <run-id | run-dir> [--output-format json]   (show what a run PRODUCED: artifacts + a shallow preview of each JSON artifact's fields; for what HAPPENED — tools/decisions — use `trace`)",
     doctor: "usage: doctor [--tier protocol|container|microvm|hostloop|cowork] [--output-format json]   (read-only prerequisite check)",
     rehash: "usage: rehash <dir/> [--dry-run] [--output-format text|json]   (migrate cassettes across format bumps using contentSig verification; no re-record needed)",
-    runs: "usage: runs gc [--keep-last <n>] [--dry-run] [<runs-dir>]   (prune accumulated run dirs; default --keep-last 5)",
+    prune: "usage: prune [--keep-last <n>] [--dry-run] [<runs-dir>]   (prune accumulated run dirs; default --keep-last 5)",
 };
 // Known subcommands — used by the global value-flag parsers (`--dotenv`, `--run-dir`) to reject a command
 // name mistaken as the flag's value (`--dotenv run x.yaml` would otherwise swallow `run`).
@@ -283,6 +288,7 @@ const COMMANDS = [
     "verify-cassettes",
     "verify-run",
     "trace",
+    "inspect",
     "assertions",
     "scaffold",
     "decide",
@@ -295,7 +301,7 @@ const COMMANDS = [
     "lint",
     "doctor",
     "rehash",
-    "runs",
+    "prune",
 ];
 async function main() {
     const argv = process.argv.slice(2);
@@ -414,6 +420,8 @@ async function main() {
             return cmdVerifyRun(rest);
         case "trace":
             return cmdTrace(rest);
+        case "inspect":
+            return cmdInspect(rest);
         case "assertions":
             return cmdAssert(rest);
         case "scaffold":
@@ -424,13 +432,8 @@ async function main() {
             return cmdGates(rest);
         case "answer":
             return cmdAnswer(rest);
-        case "runs": {
-            const sub = rest[0];
-            if (sub === "gc")
-                return cmdRunsGc(rest.slice(1));
-            log(`runs: unknown subcommand "${sub ?? ""}" — available: gc`);
-            return process.exit(2);
-        }
+        case "prune":
+            return cmdRunsGc(rest); // top-level: no `gc` token to strip, so pass `rest` whole (NOT rest.slice(1))
         default:
             log(`unknown command: ${cmd}\n`);
             printHelp();
@@ -656,7 +659,7 @@ function resolveExternal(command, flags) {
     }
     return flags.deciderCmd != null ? spawnChannel(flags.deciderCmd) : undefined;
 }
-/** The single error exit used by commands + the top-level catch. Every category → exit 2. */
+/** The single error exit used by commands + the top-level catch. boundary → exit 3, every other category → exit 2. */
 function fail(command, category, message, hint, json) {
     if (json)
         out(jsonError(command, category, message, hint));
@@ -1828,6 +1831,14 @@ async function cmdVerifyRun(args) {
         log(`verify-run: cannot read ${resultPath}: ${e.message}`);
         return process.exit(2);
     }
+    // A partial run did NOT complete (it exited on an unanswered gate). Its assertion outcome is empty and its
+    // artifacts are pre-failure, so re-evaluating asserts against it would vouch for a run that never finished.
+    // Refuse rather than false-fail or false-pass.
+    if (result.partial) {
+        log(`verify-run: ${runDir} is a PARTIAL run — it did not complete (exited on an unanswered gate). ` +
+            `Re-run to completion before verifying. (can't verify ⇒ not green)`);
+        return process.exit(2);
+    }
     let scenario;
     try {
         scenario = parseScenarioFile(scenarioFile);
@@ -2086,6 +2097,32 @@ function cmdTrace(args) {
     else
         out(formatTrace(rows));
 }
+function cmdInspect(args) {
+    if (hasHelp(args))
+        return void log(SUBCOMMAND_USAGE.inspect);
+    ensureOutputFormat("inspect", args);
+    const json = isJsonOutput(args);
+    rejectUnknownFlags("inspect", args, ["--output-format", "--output-format=json", "--output-format=text"], json);
+    const allPositionals = positionals(args, ["--output-format"]);
+    if (allPositionals.length !== 1)
+        return void fail("inspect", "usage", SUBCOMMAND_USAGE.inspect, undefined, json);
+    // Resolve a run-id or run-dir to its dir. A run dir already holding result.json is used directly; otherwise
+    // reuse trace's resolver (run-id → events.jsonl) and take the parent.
+    const target = allPositionals[0];
+    let runDir;
+    try {
+        runDir = existsSync(join(target, "result.json")) ? target : dirname(resolveEventsFile(target));
+    }
+    catch (e) {
+        return void fail("inspect", "usage", String(e.message), undefined, json);
+    }
+    try {
+        out(buildInspectView(runDir, { json }));
+    }
+    catch (e) {
+        return void fail("inspect", "usage", String(e.message), undefined, json);
+    }
+}
 function diff(a, b, path) {
     const keys = new Set([...Object.keys(a ?? {}), ...Object.keys(b ?? {})]);
     for (const k of keys) {

package/dist/decide/decider.js

@@ -256,8 +256,9 @@ export class FirstOptionDecider {
         return ABSTAIN;
     }
 }
-/** Strict label match: exact → case-insensitive. NULL on no match (caller fails loud — we deliberately
- *  do NOT fall back to option 1 like `coerceLabel`, which would silently mis-answer).
+/** Strict label match: exact → case-insensitive → near-miss (surrounding quotes / trailing sentence
+ *  punctuation trimmed). NULL on no match (caller fails loud — we deliberately do NOT fall back to option 1
+ *  like `coerceLabel`, which would silently mis-answer).
  *  When `fuzzy` is true, also accept a substring match (ONLY when exactly one label appears in the reply
  *  to avoid ambiguity). Callers that consume human or LLM output should leave `fuzzy` at its default
  *  (false) to require an exact answer — the substring heuristic is opt-in only. */
@@ -266,6 +267,19 @@ export function matchLabel(raw, labels, fuzzy = false) {
     const exact = labels.find((l) => l === r) ?? labels.find((l) => l.toLowerCase() === r.toLowerCase());
     if (exact)
         return exact;
+    // Near-miss tier: a model (or human) often replies `Confirmed.` or `"Confirmed"` for the label
+    // `Confirmed`, especially on binary confirm gates. Strip surrounding quotes + trailing `.!,;`/whitespace
+    // and re-run the exact/ci match. NEVER strip `:` — it is the `OTHER:` free-text sentinel callers rely on,
+    // and the trim must not let a near-miss swallow it. Strict (not fuzzy), so it can't mis-bind a substring.
+    const norm = r
+        .replace(/^["'`]+/, "")
+        .replace(/["'`]+$/, "")
+        .replace(/[.!,;\s]+$/, "");
+    if (norm && norm !== r) {
+        const near = labels.find((l) => l === norm) ?? labels.find((l) => l.toLowerCase() === norm.toLowerCase());
+        if (near)
+            return near;
+    }
     if (!fuzzy)
         return null;
     // fuzzy=true: the substring tier fires ONLY when EXACTLY ONE label is contained in the reply. With
@@ -351,8 +365,10 @@ export class LlmDecider {
                 continue;
             }
             const raw = await this.complete(this.prompt(text, q.options, ctx), this.model);
-            // Match a LABEL first (matchLabel is fuzzy=false): keeps the common path unchanged and means a real
-            // option literally named "OTHER: …" is selected as a label, not hijacked by the free-text branch.
+            // Match a LABEL first (matchLabel is fuzzy=false, but tolerates a quoted / trailing-punctuation
+            // near-miss): keeps the common path unchanged and means a real option literally named "OTHER: …" is
+            // selected as a label (exact match wins; the trim never strips `:`), not hijacked by the free-text
+            // branch below.
             const pick = matchLabel(raw, labels);
             if (pick) {
                 process.stderr.write(`[llm-decider] "${text}" → "${pick}"${this.intent ? ` (intent: ${this.intent})` : ""}\n`);

package/dist/io.js

@@ -1,11 +1,12 @@
 /**
  * Emit a structured warning to stderr with the GitHub-actions `::warning::` annotation prefix — the one
- * place warning formatting/severity lives, so call sites pass only the message body. Accepts a string
- * that already carries the prefix (written as-is) so migrating existing `::warning:: …` writes is a
- * no-op on content. Uses `process.stderr.write` (the mechanism the warnings always used) so test spies
- * on it still observe warnings and the output is byte-identical.
+ * place warning formatting/severity lives, so call sites pass only the message body. A message that ALREADY
+ * carries a GitHub annotation prefix (`::warning::`, `::notice::`, or `::error::`) is written as-is, so a
+ * call site that wants a softer/harder severity (e.g. `::notice:: …`) gets exactly that — NOT a doubled
+ * `::warning:: ::notice:: …`. Uses `process.stderr.write` (the mechanism the warnings always used) so test
+ * spies on it still observe warnings and the output is byte-identical for plain `::warning::` content.
  */
 export function warn(message) {
-    const line = message.startsWith("::warning::") ? message : `::warning:: ${message}`;
+    const line = /^::(warning|notice|error)::/.test(message) ? message : `::warning:: ${message}`;
     process.stderr.write(line.endsWith("\n") ? line : line + "\n");
 }

package/dist/run/cassette.js

@@ -1520,7 +1520,7 @@ export async function cmdReplay(args) {
     try {
         p = parseArgs(args, {
             // --quiet/--verbose accepted for flag consistency but currently no-op in replay (renderer plan is fixed).
-            booleans: ["--strict", "--quiet", "--verbose"],
+            booleans: ["--strict", "--fail-on-skill-drift", "--quiet", "--verbose"],
             values: ["--output-format"],
             enums: { "--output-format": ["text", "json"] },
             aliases: { "-q": "--quiet", "-V": "--verbose" },
@@ -1532,7 +1532,7 @@ export async function cmdReplay(args) {
     }
     const target = p.positionals[0];
     if (!target) {
-        log("usage: replay <file.cassette.json | dir/> [--strict] [--output-format text|json]");
+        log("usage: replay <file.cassette.json | dir/> [--strict] [--fail-on-skill-drift] [--output-format text|json]");
         return process.exit(2);
     }
     if (p.positionals.length > 1) {
@@ -1540,7 +1540,10 @@ export async function cmdReplay(args) {
         return process.exit(2);
     }
     const json = p.options["--output-format"] === "json";
-    const strict = p.flags["--strict"] ?? false; // #1b: escalate staleness warnings to failures (release gate)
+    const strict = p.flags["--strict"] ?? false; // #1b: escalate ALL staleness findings to failures (release gate)
+    const failOnSkillDrift = p.flags["--fail-on-skill-drift"] ?? false; // narrower gate: only skill-source drift fails
+    if (strict && failOnSkillDrift)
+        warn("::notice:: [replay] --strict and --fail-on-skill-drift both passed — --strict is the superset (fails on every class), so --fail-on-skill-drift is redundant here\n");
     const resolved = resolveInputs(target, ".cassette.json");
     if ("error" in resolved) {
         log(`replay: ${resolved.error}`);
@@ -1564,7 +1567,7 @@ export async function cmdReplay(args) {
         // fine" (false-green by abort). Wrap per-file: turn an unexpected throw into a tallied error result.
         let result;
         try {
-            result = await replayCassette(rc.cassette, renderer ? [renderer] : [], { strict, cassetteDir: dirname(f) });
+            result = await replayCassette(rc.cassette, renderer ? [renderer] : [], { strict, failOnSkillDrift, cassetteDir: dirname(f) });
         }
         catch (e) {
             log(`replay: ${f}: ${e?.message ?? String(e)}`);
@@ -1860,7 +1863,10 @@ export function cmdRehash(args) {
 }
 /** Replay a cassette through Run and re-evaluate the content assertions. With a `cassette.artifacts`
  *  manifest (#1), filesystem assertions (file_exists/user_visible_artifact/artifact_json) ALSO run, against
- *  the materialized snapshot. `opts.strict` (#1b) escalates staleness warnings to failing assertions. */
+ *  the materialized snapshot. `opts.strict` (#1b) escalates ALL staleness findings to failing assertions;
+ *  `opts.failOnSkillDrift` escalates only the skill-source classes (`skill`/`shared-root`/`unverifiable-skill`),
+ *  leaving baseline drift a non-failing warning. Either way the findings are always surfaced in
+ *  `RunResult.staleness` for JSON consumers. */
 export async function replayCassette(cassette, hooks = [], opts = {}) {
     // Cassette format version: ABSENT = legacy (0); a FUTURE version means this harness may misread fields
     // it doesn't know about. in strict mode this is a hard failure (future semantics may not be
@@ -1884,6 +1890,11 @@ export async function replayCassette(cassette, hooks = [], opts = {}) {
     // unchanged (frozen-structure limit). The skill-hash recompute needs the local skill dirs to be resolvable
     // from the cassette's session path; when they aren't (a moved/committed cassette), we say so rather than
     // silently skipping.
+    // Findings are pushed UNCONDITIONALLY (class-tagged) so they're surfaced in JSON (RunResult.staleness) even
+    // on the default gate — a token-free consumer can then distinguish "verified clean" from "couldn't verify"
+    // (the `unverifiable-*` classes) WITHOUT the verdict changing. The `--strict` / `--fail-on-skill-drift`
+    // gates below are the ONLY place a finding becomes a failing assertion. The single `warn()` loop at the end
+    // is the lone stderr emitter — no per-branch `warn()`, so a non-strict run never double-warns one cause.
     const staleness = [];
     if (cassette.fingerprint) {
         const fp = cassette.fingerprint;
@@ -1894,48 +1905,54 @@ export async function replayCassette(cassette, hooks = [], opts = {}) {
         }
         catch {
             baselineLoadFailed = true;
-            if (opts.strict) {
-                staleness.push("baseline could not be loaded — cannot verify staleness (--strict: treating as stale)");
-            }
-            else {
-                warn("cowork-harness: strict staleness check skipped — baseline could not be loaded\n");
-            }
+            staleness.push({
+                class: "unverifiable-baseline",
+                message: "baseline could not be loaded — cannot verify staleness (env/platform, not skill drift)",
+            });
         }
         if (!baselineLoadFailed && liveBaseline && liveBaseline !== fp.baseline)
-            staleness.push(`baseline moved ${fp.baseline} → ${liveBaseline} since record — re-record before trusting this replay`);
+            staleness.push({
+                class: "baseline",
+                message: `baseline moved ${fp.baseline} → ${liveBaseline} since record — re-record before trusting this replay`,
+            });
         if (fp.skillHash) {
             const live = buildFingerprint(cassette.scenario.session, fp.baseline, opts.cassetteDir, cassette.scenario.skills);
             if (live.skillHash === undefined) {
-                // under --strict, unresolvable skill dirs are a failure (can't verify ⇒ not green).
-                // Without --strict, warn but continue (the baseline check still applies).
-                if (opts.strict) {
-                    staleness.push("skill dirs not resolvable from this cassette location — cannot verify skill staleness (--strict: treating as stale)");
-                }
-                else {
-                    warn("::warning:: [replay] skill fingerprint not re-checkable (local skill dirs not resolvable from this cassette location) — baseline check still applies\n");
-                }
+                staleness.push({
+                    class: "unverifiable-skill",
+                    message: "skill dirs not resolvable from this cassette location — cannot verify skill staleness (the baseline check still applies)",
+                });
             }
             else if (live.skillHash !== fp.skillHash) {
                 const recordedVersion = cassette.cassetteVersion ?? 0;
                 if (recordedVersion < CASSETTE_VERSION) {
-                    staleness.push(`recorded under an older hash format (v${recordedVersion} → v${CASSETTE_VERSION}) — re-record once after upgrading`);
+                    staleness.push({
+                        class: "format",
+                        message: `recorded under an older hash format (v${recordedVersion} → v${CASSETTE_VERSION}) — re-record once after upgrading`,
+                    });
                 }
                 else if (fp.sharedHash !== undefined && live.sharedHash !== undefined) {
                     const scope = fp.skillScope?.length ? fp.skillScope.map((s) => `skills/${s}`).join(", ") : "skill";
                     if (live.sharedHash !== fp.sharedHash) {
-                        staleness.push(`shared root changed since record (scope: ${scope}) — re-record before trusting this replay`);
+                        staleness.push({
+                            class: "shared-root",
+                            message: `shared root changed since record (scope: ${scope}) — re-record before trusting this replay`,
+                        });
                     }
                     else {
-                        staleness.push(`${scope} changed since record — re-record before trusting this replay`);
+                        staleness.push({ class: "skill", message: `${scope} changed since record — re-record before trusting this replay` });
                     }
                 }
                 else {
-                    staleness.push("local skill/plugin dir contents changed since record — re-record before trusting this replay");
+                    staleness.push({
+                        class: "skill",
+                        message: "local skill/plugin dir contents changed since record — re-record before trusting this replay",
+                    });
                 }
             }
         }
         for (const s of staleness)
-            warn(`::warning:: [replay] cassette stale: ${s}\n`);
+            warn(`::warning:: [replay] cassette stale: ${s.message}\n`);
     }
     // §2.5 backward compat: warn loudly when controlOut is absent so the user knows question/gate
     // assertions are being EXCLUDED (not vacuously evaluated) from this run.
@@ -2085,10 +2102,17 @@ export async function replayCassette(cassette, hooks = [], opts = {}) {
         toolResultTexts: rec.toolResults.map((r) => r.assertText ?? r.text),
         truncatedPaths: replayTruncatedPaths,
     });
-    // #1b: under --strict, a staleness mismatch is a failing assertion (non-zero exit), not just a warning.
+    // #1b: under --strict, EVERY staleness finding becomes a failing assertion (non-zero exit), not just a
+    // warning. --fail-on-skill-drift is the narrower gate: only the skill-source classes fail (incl.
+    // `unverifiable-skill` — can't verify skill staleness ⇒ not green), while baseline / format / env-level
+    // findings stay non-failing. `else if` makes --strict the superset when both are passed.
+    const SKILL_DRIFT_CLASSES = new Set(["skill", "shared-root", "unverifiable-skill"]);
     if (opts.strict)
         for (const s of staleness)
-            assertions.push({ assertion: {}, pass: false, message: `cassette stale (--strict): ${s}` });
+            assertions.push({ assertion: {}, pass: false, message: `cassette stale (--strict): ${s.message}` });
+    else if (opts.failOnSkillDrift)
+        for (const s of staleness.filter((s) => SKILL_DRIFT_CLASSES.has(s.class)))
+            assertions.push({ assertion: {}, pass: false, message: `skill-source drift (--fail-on-skill-drift): ${s.message}` });
     // future cassette version — hard failure under --strict (forward semantics may not be
     // correctly interpreted here, so a green replay would be a false-green).
     if (futureVersionMsg && opts.strict)
@@ -2175,6 +2199,10 @@ export async function replayCassette(cassette, hooks = [], opts = {}) {
         subagents: rec.subagents,
         unanswered: rec.unanswered,
         outDir: "(replay)",
+        // Class-tagged staleness + skip counts, surfaced to JSON callers (the gate decision already happened
+        // above via failing assertions; these fields are pure data so a green stays green by default).
+        staleness: staleness.length ? staleness : undefined,
+        skippedAssertions: { full: fullSkipCount, partial: partialSkipCount },
         // A cassette freezes the answer path: the replay itself is deterministic regardless of how the
         // original run was answered. Always explicit (never undefined) so renderer.ts:146 treats it
         // correctly — undefined would silently render as "deterministic" (#47 C1 [review-2]).

package/dist/run/doctor.js

@@ -174,7 +174,11 @@ export function runDoctorChecks(tier, probe = realProbe) {
             id: "image",
             title: "Agent image",
             status: present ? "ok" : up ? "fail" : "skip",
-            detail: present ? `${image} present` : up ? `${image} missing` : `(skipped — ${runtime} not reachable)`,
+            detail: present
+                ? `${image} present — lean core; OCR / PDF-table skills need the full-parity image (--build-arg COWORK_FULL_PARITY=1)`
+                : up
+                    ? `${image} missing`
+                    : `(skipped — ${runtime} not reachable)`,
             remedy: present || !up ? undefined : `build it: ${agentBuildLine(runtime, image)}`,
             required: up, // only gate on the image once the runtime is actually reachable
         });

package/dist/run/execute.js

@@ -17,7 +17,7 @@ import { spawnProtocol } from "../runtime/protocol.js";
 import { spawnContainer } from "../runtime/container.js";
 import { spawnHostLoop } from "../runtime/hostloop.js";
 import { spawnMicroVm } from "../runtime/microvm.js";
-import { probeImageOmitted, probeMicrovmOmitted, detectCapabilityUse, CAPABILITY_FAMILIES } from "../runtime/image-capabilities.js";
+import { probeImageOmitted, probeMicrovmOmitted, detectCapabilityUse, capabilityPreflightDecision, CAPABILITY_FAMILIES, } from "../runtime/image-capabilities.js";
 import { instanceName } from "../runtime/lima.js";
 import { decideLoopFromBaseline, readGateFlag } from "../loop-decision.js";
 import { startEgressSidecar, registerCleanup } from "../egress/sidecar.js";
@@ -258,6 +258,7 @@ export async function executeScenario(scenario, opts = {}) {
     let hostProxy;
     let microvmProxyPort;
     let record;
+    let unansweredErr; // set when a gate whiffs — drives the salvage branch below
     let child; // hoisted so the finally can reap a crashed/orphaned container (F1)
     let containerName;
     let deregisterContainerReap; // 2a: Ctrl-C cleanup for the agent container
@@ -270,6 +271,29 @@ export async function executeScenario(scenario, opts = {}) {
     const viaApiOn = readGateFlag(baseline, "1978029737", "coworkWebFetchViaApi");
     const promptGateOn = readGateFlag(baseline, "1978029737", "coworkWebFetchPrompt");
     const provenanceRef = {};
+    // Pre-flight: if the skill DECLARES required capabilities and the image provably omits one, FAIL FAST here
+    // — before any paid agent run — instead of burning ~12 min to reach a verdict the post-run guard already
+    // knows. The author can opt out with `allow_missing_capability: true` (the fallback is equivalent), which
+    // downgrades to a notice. The image probe is digest-cached, so it's shared with the post-run check (no
+    // second container spawn), and it spawns a throwaway `--network none` container with no model — zero tokens.
+    const declaredCaps = scenario.requires_capabilities ?? [];
+    if (declaredCaps.length &&
+        (effectiveFidelity === "container" || effectiveFidelity === "hostloop" || effectiveFidelity === "microvm") &&
+        process.env.COWORK_SKIP_CAPABILITY_PROBE !== "1") {
+        const omitted = effectiveFidelity === "microvm"
+            ? probeMicrovmOmitted(instanceName(baseline))
+            : probeImageOmitted({
+                runtime: process.env.COWORK_CONTAINER_RUNTIME ?? "docker",
+                image: process.env.COWORK_AGENT_IMAGE ?? "cowork-agent-base:2",
+                tier: effectiveFidelity,
+            });
+        const allowMissing = scenario.assert.some((a) => a.allow_missing_capability === true);
+        const { abort, message } = capabilityPreflightDecision(declaredCaps, omitted, allowMissing);
+        if (abort)
+            throw new BoundaryError(`[capability] ${message}`);
+        if (message)
+            warn(`::notice:: [capability] (pre-flight) ${message} (allow_missing_capability asserted — proceeding)\n`);
+    }
     try {
         // acquire the egress sidecar / host proxy INSIDE the protected try so a throw in resource
         // acquisition OR in renderPrompts below can't leak a Docker network / a bound proxy port — the `finally`
@@ -365,10 +389,22 @@ export async function executeScenario(scenario, opts = {}) {
                 permissiveMode: plan.permissionMode === "bypassPermissions",
             };
         }
-        record = await run.drive(scenario.prompt, {
-            subagentAppend: prompts.subagentAppend,
-            sdkMcp,
-        });
+        try {
+            record = await run.drive(scenario.prompt, {
+                subagentAppend: prompts.subagentAppend,
+                sdkMcp,
+            });
+        }
+        catch (e) {
+            // An unanswered gate is recoverable: grab the in-progress record so the work done before the whiff can
+            // be salvaged to disk below. Any other error is a genuine fault — keep today's fail-fast behavior.
+            if (e instanceof UnansweredError) {
+                unansweredErr = e;
+                record = run.partial();
+            }
+            else
+                throw e;
+        }
     }
     finally {
         // Reap the agent container FIRST (before the sidecar networks), so a crashed/unanswered run can't
@@ -402,6 +438,36 @@ export async function executeScenario(scenario, opts = {}) {
     // are read-only inputs and are NOT visible roots. Persisted to RunResult so the plan-less lanes
     // (verify reads result.json; replay reads the cassette) match this without rebuilding a LaunchPlan.
     const userVisibleRoots = ["outputs", ...plan.mounts.filter((m) => m.kind === "folder").map((m) => m.mountPath)];
+    // Salvage path: the run exited on an unanswered gate. Persist a PARTIAL result.json (+ run.jsonl/trace) so
+    // the artifacts the agent wrote before the whiff survive for inspection, then re-throw so the CLI still
+    // exits 2. Skip assertion eval and the capability probe (a real container spawn) — a partial run has no
+    // meaningful assertion or verdict outcome.
+    if (unansweredErr) {
+        const partialResult = buildPartialResult({
+            scenarioName: scenario.name,
+            prompt: scenario.prompt,
+            fidelity: scenario.fidelity,
+            baseline: baseline.appVersion,
+            record,
+            outDir,
+            workRoot,
+            userVisibleRoots,
+            effectiveFidelity,
+            egress,
+            durationMs: Date.now() - startedAt,
+            unanswered: { message: unansweredErr.message, hint: unansweredErr.hint },
+            fingerprint: buildFingerprint(scenario.session, baseline.appVersion, undefined, scenario.skills),
+        });
+        writeFileSync(join(outDir, "result.json"), scrub(JSON.stringify(partialResult, null, 2), secrets));
+        writeRunJsonl(outDir, scenario, effectiveFidelity, record, egress, secrets);
+        writeTrace(outDir, record, egress, secrets, partialResult.durationMs);
+        scrubFileInPlace(join(outDir, "events.jsonl"), secrets);
+        scrubFileInPlace(join(outDir, "control-out.jsonl"), secrets);
+        // Loud PARTIAL marker so the populated artifacts are never misread as success (the no-false-green rule).
+        warn(`::notice:: [partial] run did NOT complete (unanswered gate) — salvaged the pre-failure work to:\n` +
+            `  ${outDir}\n  inspect it: cowork-harness inspect ${outDir}\n`);
+        throw unansweredErr;
+    }
     const assertions = evaluate(scenario.assert, {
         transcript: record.transcript,
         toolsCalled: record.toolsCalled,
@@ -632,6 +698,51 @@ function writeRunJsonl(outDir, scenario, fidelity, rec, egress, secrets) {
     ];
     writeFileSync(join(outDir, "run.jsonl"), scrub(lines.map((l) => JSON.stringify(l)).join("\n"), secrets));
 }
+/** Assemble a RunResult for a run that did NOT complete — it exited on an unanswered gate. The work the
+ *  agent did before the whiff (artifacts on disk, the partial transcript, decisions/tool counts so far) is
+ *  salvaged so the paid run is still inspectable instead of vanishing. Deliberately reduced: no assertion
+ *  outcome (a partial run has none) and no capability/verdict fields (those would need a probe we skip).
+ *  `partial:true` is the signal that lets consumers (verify-run, scaffold, the footer) refuse to read its
+ *  populated `artifacts[]` as a passing run. */
+export function buildPartialResult(args) {
+    const { record } = args;
+    return {
+        $schema: RUN_RESULT_SCHEMA_URL,
+        generator: "cowork-harness",
+        scenario: args.scenarioName,
+        prompt: args.prompt,
+        fidelity: args.fidelity,
+        baseline: args.baseline,
+        result: "error",
+        partial: true,
+        unansweredGate: { message: args.unanswered.message, ...(args.unanswered.hint ? { hint: args.unanswered.hint } : {}) },
+        decisions: record.decisions.map((d) => ({
+            kind: d.kind,
+            name: d.name,
+            decision: d.decision,
+            by: d.by,
+            detail: d.detail,
+            rationale: d.rationale,
+        })),
+        toolCounts: record.toolCounts,
+        gateDeliveries: record.gateDeliveries,
+        egress: args.egress,
+        assertions: [],
+        toolResults: record.toolResults,
+        subagents: record.subagents,
+        unanswered: record.unanswered,
+        usage: record.usage,
+        cost: record.cost,
+        durationMs: args.durationMs,
+        outDir: args.outDir,
+        workDir: args.workRoot,
+        outputsDir: join(args.workRoot, "outputs"),
+        userVisibleRoots: args.userVisibleRoots,
+        artifacts: collectArtifacts(args.workRoot, args.userVisibleRoots),
+        effectiveFidelity: args.effectiveFidelity,
+        ...(args.fingerprint ? { fingerprint: args.fingerprint } : {}),
+    };
+}
 /** B3: the structured run trace. */
 /** ENV-MANIFEST: recursively list files under each user-visible prefix (relative path + byte size).
  *  Paths only — NO content snapshot (that is the cassette manifest, #1).

package/dist/run/inspect-view.js

@@ -0,0 +1,95 @@
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+/** A compact, depth-1 preview of a JSON artifact: scalars kept inline, arrays shown as a count, nested
+ *  objects collapsed to `{…}` — enough to answer "did it produce the right fields?" without dumping blobs. */
+function shallowPreview(doc) {
+    if (Array.isArray(doc))
+        return `[${doc.length} items]`;
+    if (!doc || typeof doc !== "object")
+        return { value: doc };
+    const out = {};
+    for (const [k, v] of Object.entries(doc)) {
+        if (Array.isArray(v))
+            out[k] = `[${v.length} items]`;
+        else if (v && typeof v === "object")
+            out[k] = "{…}";
+        else
+            out[k] = v;
+    }
+    return out;
+}
+function humanMs(ms) {
+    if (!ms && ms !== 0)
+        return "?";
+    if (ms < 1000)
+        return `${ms}ms`;
+    return `${(ms / 1000).toFixed(1)}s`;
+}
+/** Build the digest for one kept run dir: header facts + the artifacts manifest, with a shallow field
+ *  preview for each JSON artifact (read from the work dir, which result.json records). The manifest
+ *  (paths + sizes) lives in result.json and always survives; the content preview needs the work dir, which
+ *  a non-`--keep` container/microvm run tears down. */
+function digestFor(runDir) {
+    const resultPath = join(runDir, "result.json");
+    if (!existsSync(resultPath))
+        throw new Error(`no result.json under ${runDir} (is this a kept run dir? e.g. runs/<scenario>/<sessionId>/)`);
+    const result = JSON.parse(readFileSync(resultPath, "utf8"));
+    const workDir = result.workDir ?? "";
+    const workDirAvailable = !!workDir && existsSync(workDir);
+    const artifacts = (result.artifacts ?? []).map((a) => {
+        const entry = { path: a.path, bytes: a.bytes };
+        if (workDirAvailable && a.path.endsWith(".json")) {
+            const abs = join(workDir, a.path);
+            if (existsSync(abs)) {
+                try {
+                    entry.preview = shallowPreview(JSON.parse(readFileSync(abs, "utf8")));
+                }
+                catch {
+                    /* not valid JSON after all — leave preview off */
+                }
+            }
+        }
+        return entry;
+    });
+    return {
+        scenario: result.scenario,
+        fidelity: result.fidelity,
+        result: result.result,
+        ...(result.partial ? { partial: true } : {}),
+        ...(result.unansweredGate ? { unansweredGate: result.unansweredGate } : {}),
+        durationMs: result.durationMs,
+        ...(result.cost ? { cost: result.cost } : {}),
+        workDirAvailable,
+        artifacts,
+    };
+}
+/** Render a run dir for the `inspect` command. `json` mode returns the structured digest; text mode returns
+ *  a human summary: header, a PARTIAL banner if the run didn't complete, and each artifact with a shallow
+ *  field preview (or a "work dir torn down" note when content can't be read). */
+export function buildInspectView(runDir, opts = {}) {
+    const d = digestFor(runDir);
+    if (opts.json)
+        return JSON.stringify(d, null, 2);
+    const lines = [];
+    lines.push(`run: ${d.scenario}  (${d.fidelity})  result: ${d.result}  ${humanMs(d.durationMs)}`);
+    if (d.partial) {
+        lines.push(`⚠ PARTIAL — this run did NOT complete (exited on an unanswered gate); artifacts below are pre-failure.`);
+        if (d.unansweredGate)
+            lines.push(`  gate: ${d.unansweredGate.message.split("\n")[0]}`);
+    }
+    lines.push(`artifacts (${d.artifacts.length}):`);
+    for (const a of d.artifacts) {
+        lines.push(`  ${a.path}  (${a.bytes} B)`);
+        if (a.preview && typeof a.preview === "object") {
+            for (const [k, v] of Object.entries(a.preview))
+                lines.push(`    ${k}: ${typeof v === "string" ? v : JSON.stringify(v)}`);
+        }
+        else if (typeof a.preview === "string") {
+            lines.push(`    ${a.preview}`);
+        }
+    }
+    if (!d.workDirAvailable && d.artifacts.some((a) => a.path.endsWith(".json"))) {
+        lines.push(`  (work dir torn down — re-run with --keep to preview artifact contents)`);
+    }
+    return lines.join("\n");
+}

package/dist/run/run.js

@@ -73,6 +73,14 @@ export class Run {
     ctx() {
         return { task: this.rec.transcript, transcript: () => this.rec.transcript, toolLog: () => this.toolLog, runId: this.rec.runId };
     }
+    /** The in-progress record. When `drive()` throws on an unanswered gate, this holds everything accumulated
+     *  up to the whiff (transcript, decisions, tool counts, artifacts-on-disk are separate) — the caller uses
+     *  it to salvage a partial run instead of discarding the work. Fully initialized in the constructor, so
+     *  it's a usable shell even on a very-early throw. The post-loop gate-delivery pairing has NOT run on the
+     *  throw path, so `gateDeliveries` is empty here. */
+    partial() {
+        return this.rec;
+    }
     /** Drive one-shot (string) or multi-turn (async iterable) and return the record. */
     async drive(turns, startOpts) {
         const turnIter = typeof turns === "string" ? oneShot(turns) : turns[Symbol.asyncIterator]();

package/dist/run/runs-gc.js

@@ -10,16 +10,16 @@ const DEFAULT_KEEP_LAST = 5;
  *  dir has neither → it is what GC should drop first. `events.jsonl` exists from session start, so an
  *  in-flight run is protected without a wall-clock guard. */
 const isRealRun = (dir) => existsSync(join(dir, "result.json")) || existsSync(join(dir, "events.jsonl"));
-/** `cowork-harness runs gc [--keep-last <n>] [--dry-run] [<runs-dir>]`
+/** `cowork-harness prune [--keep-last <n>] [--dry-run] [<runs-dir>]`
  *
  *  For each scenario directory under the runs root, ranks EPHEMERAL run dirs by (1) real-run first (has
  *  result.json OR events.jsonl), (2) mtime descending, (3) name — then keeps the N most recent of that order
  *  and removes the rest. So an older COMPLETED run beats a newer empty scaffold dir for a keep slot, but
  *  `--keep-last` stays a HARD CAP (the ranking only decides WHICH N survive — never grows the kept count).
- *  Do NOT run `runs gc` against an actively-writing runs root.
+ *  Do NOT run `prune` against an actively-writing runs root.
  *  Pinned `sess-*` dirs (persisted, resumable `--session-id` sessions) are retained unconditionally.
  *  The default root is the flat, machine-global `~/.cowork-harness/runs` (shared across projects), so a
- *  bare `runs gc` prunes ephemeral runs from ALL projects; pass an explicit <runs-dir> to scope it.
+ *  bare `prune` prunes ephemeral runs from ALL projects; pass an explicit <runs-dir> to scope it.
  *  Safe by default (dry-run-able). */
 export function cmdRunsGc(args) {
     let p;
@@ -34,19 +34,19 @@ export function cmdRunsGc(args) {
         return process.exit(2);
     }
     if (p.positionals.length > 1) {
-        log(`runs gc takes an optional <runs-dir> (got ${p.positionals.length}: ${p.positionals.join(", ")})`);
+        log(`prune takes an optional <runs-dir> (got ${p.positionals.length}: ${p.positionals.join(", ")})`);
         return process.exit(2);
     }
     const rawKeep = p.options["--keep-last"];
     const keepLast = rawKeep !== undefined ? Number(rawKeep) : DEFAULT_KEEP_LAST;
     if (!Number.isInteger(keepLast) || keepLast < 1) {
-        log(`runs gc: --keep-last must be a positive integer (got ${rawKeep})`);
+        log(`prune: --keep-last must be a positive integer (got ${rawKeep})`);
         return process.exit(2);
     }
     const dryRun = p.flags["--dry-run"] ?? false;
     const runsRoot = p.positionals[0] ?? runsWriteRoot();
     if (!existsSync(runsRoot)) {
-        log(`✓ runs gc: ${runsRoot} does not exist — nothing to prune`);
+        log(`✓ prune: ${runsRoot} does not exist — nothing to prune`);
         return process.exit(0);
     }
     let deleted = 0;
@@ -115,7 +115,7 @@ export function cmdRunsGc(args) {
         }
     }
     log(deleted > 0
-        ? `✓ runs gc: pruned ${deleted} run dir(s), kept ${kept}${dryRun ? " (dry-run — nothing deleted)" : ""}`
-        : `✓ runs gc: nothing to prune (${kept} run dir(s) within --keep-last ${keepLast})`);
+        ? `✓ prune: pruned ${deleted} run dir(s), kept ${kept}${dryRun ? " (dry-run — nothing deleted)" : ""}`
+        : `✓ prune: nothing to prune (${kept} run dir(s) within --keep-last ${keepLast})`);
     return process.exit(0);
 }

package/dist/run/scaffold.js

@@ -46,13 +46,20 @@ export function buildScaffold(eventsFile) {
             answers.push({ when_question: escapeRx(q), choose: val });
         }
     }
+    // A partial run did NOT complete (it exited on an unanswered gate). Its artifacts are pre-failure and its
+    // result is "error", so neither should become an assertion the author trusts — that would scaffold a
+    // scenario asserting the half-finished output. Keep the gate answers (still worth locking) but drop the
+    // artifact/result asserts and warn loudly.
+    const partial = result.partial === true;
     // Observed artifacts → file_exists; sub-agent count → dispatch_count_max; final result.
     const assert = [];
-    for (const art of result.artifacts ?? [])
-        assert.push({ file_exists: art.path });
-    if ((result.subagents ?? []).length)
-        assert.push({ dispatch_count_max: (result.subagents ?? []).length });
-    assert.push({ result: result.result ?? "success" });
+    if (!partial) {
+        for (const art of result.artifacts ?? [])
+            assert.push({ file_exists: art.path });
+        if ((result.subagents ?? []).length)
+            assert.push({ dispatch_count_max: (result.subagents ?? []).length });
+        assert.push({ result: result.result ?? "success" });
+    }
     const scenario = {
         // `result.baseline` is the recorded appVersion; a scenario pins `latest` (or a `desktop-<ver>`) — default
         // to latest and let the author pin if they need a specific release.
@@ -70,8 +77,13 @@ export function buildScaffold(eventsFile) {
     // Provenance signature — mirrors the cassette's `generator`/`cassetteVersion` fields. The scenario
     // schema is `additionalProperties:false`, so it rides as a YAML comment (survives parse + re-serialize)
     // rather than a structured field. Tool + version let a reader trace a committed scenario to its origin.
+    const partialMarker = partial
+        ? `# PARTIAL run — this run did NOT complete (it exited on an unanswered gate). The artifact and result\n` +
+            `# assertions were omitted (the outputs are pre-failure). Re-run to completion and re-scaffold before trusting.\n`
+        : "";
     return (`# generated by cowork-harness v${pkgVersion()} (scaffold) from ${runDir}\n` +
         `# REVIEW before committing: tighten the when_question regexes to stable fragments, prune asserts you don't need.\n` +
+        partialMarker +
         multiSelectMarker +
         stringify(scenario));
 }

package/dist/run/trace-view.js

@@ -9,7 +9,7 @@ import { parseMessage } from "../agent/session.js";
  * convention used by the VM work dir (`lima.ts` `VM_WORK_HOST`). FLAT (shared across all projects on the
  * machine): ephemeral `local_*` run dirs carry a unique hrtime id so they never path-collide; pinned
  * `sess-*` dirs are deterministic, so a cross-project collision is guarded in `execute.ts` (the writer
- * errors rather than overwriting another project's session) and `runs gc` never prunes them.
+ * errors rather than overwriting another project's session) and `prune` never prunes them.
  */
 export function defaultRunsHome() {
     return join(homedir(), ".cowork-harness", "runs");

package/dist/runtime/image-capabilities.js

@@ -210,6 +210,29 @@ function readWorkspaceScript(workRoot, rel) {
  * error (the module may simply be present, or the script may swallow the failure). Script reads are
  * read-only, containment-checked, and bounded; missing files are skipped.
  */
+/** Pre-run check: a skill that DECLARES the capability families its core path needs, run against an image
+ *  that OMITS one, will hard-fail only after the (paid, ~12-min) run. Surface the build remedy up front so
+ *  the operator fixes it before paying. Returns null when nothing is declared, all caps are present, or the
+ *  probe could not run (`omitted` null) — i.e. only warns on a definite, actionable mismatch. */
+export function capabilityPreflightWarning(declared, omitted) {
+    if (!declared.length || !omitted)
+        return null;
+    const missing = declared.filter((c) => omitted.includes(c));
+    if (!missing.length)
+        return null;
+    // State the gap + remedy only; the caller frames the consequence (abort pre-run, or a notice when
+    // allow_missing_capability is asserted) — so this string stays accurate in both contexts.
+    return (`skill declares requires_capabilities [${missing.join(", ")}] but the agent image omits them — ` +
+        `rebuild full parity (--build-arg COWORK_FULL_PARITY=1) and point COWORK_AGENT_IMAGE at it.`);
+}
+/** The pre-run capability decision: a DEFINITE gap (a declared family the image omits) **fails fast** before
+ *  the paid run, unless the scenario opted out with `allow_missing_capability: true` (then it's a notice and
+ *  the run proceeds — the author has declared the fallback equivalent). No gap / indefinite probe → no
+ *  action. Keeping this a pure function makes the fail-fast-by-default policy unit-testable. */
+export function capabilityPreflightDecision(declared, omitted, allowMissing) {
+    const message = capabilityPreflightWarning(declared, omitted);
+    return { abort: message !== null && !allowMissing, message };
+}
 export function detectCapabilityUse(eventsFile, omitted, workRoot) {
     if (!omitted.length)
         return [];

package/docs/cassette.md

@@ -211,8 +211,9 @@ with `record --max-artifact-bytes <n>` (or `COWORK_HARNESS_MAX_ARTIFACT_BYTES`)
 stays replay-checkable, and `record` fails fast if an `artifact_json` targets an artifact it had to truncate (that
 would pass at record but fail at replay). Without a manifest (older
 cassettes), these are skipped. A green replay re-confirms *record-time* artifacts, **not** that the current
-skill still produces them — `replay --strict` fails the run when the `fingerprint` shows the skill/baseline
-drifted.
+skill still produces them — `replay --strict` fails the run when the `fingerprint` shows ANY skill/baseline
+drift, or `replay --fail-on-skill-drift` fails only on skill-source drift (leaving baseline drift a warning).
+Either way, every replay result also reports the drift in `staleness[]` (class-tagged) for a JSON gate to read.
 
 ### Still skipped on replay (no filesystem/network in a cassette)
 

package/docs/scenario.md

@@ -261,6 +261,13 @@ fires even when the skill's fallback masks the gap. The check is computed at run
 `verify-run`/`replay` honor the recorded outcome — a clean full-parity run records nothing and never
 false-fails later. Opt out with `allow_missing_capability: true` when the fallback is genuinely equivalent.
 
+When `requires_capabilities` is declared, the harness probes the image **before** driving and, if a declared
+family is omitted, **fails fast — it aborts the run (exit 3) before spending a single token**, instead of
+running ~12 min to a post-run hard-fail that's already known. Rebuild full parity
+(`--build-arg COWORK_FULL_PARITY=1`) and point `COWORK_AGENT_IMAGE` at it, or assert
+`allow_missing_capability: true` (which downgrades the abort to a notice and proceeds, same as it opts out of
+the post-run check).
+
 ```yaml
 requires_capabilities: [office_convert, pdf_tables]   # fail unless the tier provides (and can verify) these
 ```
@@ -333,7 +340,9 @@ small JSON bodies) into the cassette, and `replay` materializes that snapshot to
 `artifact_json` needs the JSON body inlined (small files); a hash-only (oversized) entry still satisfies
 `file_exists` but not `artifact_json`. Without a manifest (older cassettes), they are **skipped** (loud).
 A green `replay` re-confirms *record-time* artifacts, **not** that the current skill still produces them —
-that needs a live `run` (the cassette's `--strict` staleness fingerprint warns when the skill/baseline drifted).
+that needs a live `run` (the cassette's staleness fingerprint warns when the skill/baseline drifted; `replay
+--strict` fails on any drift, `--fail-on-skill-drift` on skill-source drift only, and every result reports it
+in `staleness[]` for a JSON gate).
 
 **Egress + other filesystem** assertions (`no_delete_in_outputs`, `self_heal_ran`,
 `transcript_no_host_path`, `egress_*`/`expect_denied`) are still **skipped** on `replay` — they only run on
@@ -382,7 +391,8 @@ are) or need a real predicate over a skill's **structured JSON output**:
 full Python callable with autocomplete and `print(d)`, strictly richer than anything a YAML string can
 express. **If you're checking structured JSON content and already write Python, prefer the pytest lambda**
 (a YAML content-predicate would be equal power with worse tooling). Find an artifact's real field paths by
-running once with `--keep` and inspecting the JSON under the run's `…/mnt/artifacts/…`.
+running once with `--keep`, then `cowork-harness inspect <run-dir>` (a shallow field preview of each JSON
+artifact) or by reading the JSON under the run's `…/mnt/outputs/…` directly.
 
 ## Output
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-harness",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Scriptable, CI-friendly harness for Claude Cowork's runtime contract for testing skills across scenarios — same agent, mounts, egress allowlist, permission protocol, and sandbox limitations.",
   "license": "MIT",
   "type": "module",

package/schema/run-result.json

@@ -49,6 +49,8 @@
     "workDir": { "type": "string" },
     "outputsDir": { "type": "string" },
     "artifacts": { "type": "array" },
+    "partial": { "type": "boolean" },
+    "unansweredGate": { "type": "object" },
     "nonDeterministic": { "type": "boolean" },
     "nonDeterministicTerminal": { "type": "boolean" },
     "permissiveAutoAllow": {

package/scripts/gen-schema.ts

@@ -19,14 +19,21 @@ export const SCHEMA_DIR = join(REPO_ROOT, "schema");
  *  is. Writer + the drift-guard test both reference this one constant. */
 export const ASSERTION_KEYS_PATH = join(REPO_ROOT, ".claude/skills/cowork-harness/scripts/assertion-keys.json");
 
-/** The authoritative assertion-key list, derived from the Zod `Assertion` schema (the same source
- *  `assert --list` reads). Generating it keeps `scenario.py`'s unknown-key check from drifting. */
+/** The authoritative key lists `scenario.py` reads — derived from the Zod schemas (the same source
+ *  `assert --list` reads). Generating them keeps the linter's unknown-key checks from drifting: `keys` is
+ *  the `assert:` catalog, `topLevelKeys` the scenario top-level catalog (an earlier hand-maintained copy
+ *  drifted and false-flagged the valid `requires_capabilities`). `profile`/`assertions` are NOT here — they
+ *  are deprecated aliases handled by scenario.py's special-cases (the Zod `Scenario` preprocess remaps
+ *  `profile`; `assertions` is a hard error), so they are intentionally absent from the schema shape. */
 export function buildAssertionKeys(): string {
   return (
     JSON.stringify(
       {
-        $comment: "GENERATED from the Zod Assertion schema (src/types.ts) by scripts/gen-schema.ts — do not edit; run `npm run schema`.",
+        $comment: "GENERATED from the Zod schemas (src/types.ts) by scripts/gen-schema.ts — do not edit; run `npm run schema`.",
         keys: Object.keys(Assertion.shape).sort(),
+        // Every valid top-level scenario key, from the ScenarioObject strictObject shape (NOT the `Scenario`
+        // preprocess wrapper). scenario.py keeps an embedded fallback parity-tested against this.
+        topLevelKeys: Object.keys(ScenarioObject.shape).sort(),
         // The verdict-modifier subset (no-op assertions that suppress a default-fail). scenario.py keeps a
         // hardcoded copy parity-tested against this; see VERDICT_MODIFIER_KEYS in src/types.ts.
         verdictModifierKeys: [...VERDICT_MODIFIER_KEYS].sort(),