cowork-harness 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -4,6 +4,61 @@ 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.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

@@ -97,6 +97,7 @@ Skill testing is the headline use, but the tool is a general harness over the Co
 | `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.13.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";
@@ -77,7 +78,7 @@ const HELP = `cowork-harness <command>   (v${"$VERSION"})
       [--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 +93,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)
 
@@ -261,16 +264,17 @@ const SUBCOMMAND_USAGE = {
         "       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]",
     "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 +287,7 @@ const COMMANDS = [
     "verify-cassettes",
     "verify-run",
     "trace",
+    "inspect",
     "assertions",
     "scaffold",
     "decide",
@@ -295,7 +300,7 @@ const COMMANDS = [
     "lint",
     "doctor",
     "rehash",
-    "runs",
+    "prune",
 ];
 async function main() {
     const argv = process.argv.slice(2);
@@ -414,6 +419,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 +431,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 +658,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 +1830,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 +2096,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/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/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
 ```
@@ -382,7 +389,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.13.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": {