cowork-harness 0.8.0 → 0.9.0

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

@@ -30,5 +30,10 @@
     "transcript_not_contains",
     "transcript_not_matches",
     "user_visible_artifact"
+  ],
+  "verdictModifierKeys": [
+    "allow_l0_plugin_divergence",
+    "allow_missing_capability",
+    "allow_permissive_auto_allow"
   ]
 }

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

@@ -38,7 +38,11 @@ import re
 import sys
 from pathlib import Path
 
-# --- the replay-class taxonomy (mirrors `contentKeys` in src/run/cassette.ts) ---
+# --- the replay-class taxonomy ---
+# NB: this is NOT a 1:1 mirror of `contentKeys` in src/run/cassette.ts. cassette.ts keeps the verdict
+# modifiers (VERDICT_MODIFIER_KEYS) in its content set so they replay as no-op passes; the linter
+# deliberately keeps them OUT of CONTENT_KEYS so a modifier-only scenario still trips the `replay-noop`
+# warning below (a no-op pass verifies nothing real — exactly what that warning is for).
 CONTENT_KEYS = {
     "result",
     "transcript_contains",
@@ -286,8 +290,9 @@ def lint_doc(doc, path, raw_lines):
                     "WARN",
                     "replay-noop",
                     "every assertion is live-only (egress / no_delete_in_outputs / self_heal_ran / "
-                    "transcript_no_host_path) — on the token-free `replay` lane they are ALL silently "
-                    "skipped, so a replay PR gate would verify nothing.",
+                    "transcript_no_host_path) or a verdict modifier (allow_*, a no-op pass) — on the "
+                    "token-free `replay` lane the live-only ones are silently skipped and the verdict "
+                    "modifiers verify nothing, so a replay PR gate would verify nothing.",
                     "Add a content assertion (result / transcript_* / tool_* / subagent_*) or a "
                     "manifest-backed one (file_exists / user_visible_artifact / artifact_json), or run this "
                     "scenario only on the live (run/record) lane.",
@@ -423,6 +428,30 @@ def _print_findings(findings, n_files):
 
 def cmd_lint(args):
     all_findings = []
+    # Expand directory args to their scenario files — mirrors src/run/inputs.ts `resolveInputs`: a SINGLE
+    # combined-sorted `*.yaml` + `*.yml` listing (non-recursive), a single file kept as-is, and an EMPTY dir
+    # as a loud ERROR (never a vacuous "0 files = clean"). Done in place so the lint loop AND the count below
+    # both see the expanded list.
+    expanded = []
+    for arg in args.files:
+        p = Path(arg)
+        if p.is_dir():
+            matches = sorted(str(q) for q in (list(p.glob("*.yaml")) + list(p.glob("*.yml"))))
+            if matches:
+                expanded.extend(matches)
+            else:
+                all_findings.append(
+                    Finding(
+                        "ERROR",
+                        "no-scenarios",
+                        f"no .yaml/.yml files under {arg} — nothing to do (loud non-zero, not a vacuous pass)",
+                        "Point lint at a scenario file or a directory containing *.yaml / *.yml scenarios.",
+                        arg,
+                    )
+                )
+        else:
+            expanded.append(arg)
+    args.files = expanded
     # Linter self-check (B3): a valid schema key the replay-class sets don't classify can't be linted
     # correctly — surface it as a hard ERROR so it fails the gate (and --strict) until someone classifies it.
     if UNCLASSIFIED_KEYS:
@@ -602,7 +631,7 @@ def main(argv=None):
     sub = ap.add_subparsers(dest="command", required=True)
 
     lp = sub.add_parser("lint", help="lint scenario(s) for silent-false-green invariants")
-    lp.add_argument("files", nargs="+", help="scenario YAML file(s) to lint")
+    lp.add_argument("files", nargs="+", help="scenario YAML file(s) or director(ies) of *.yaml/*.yml to lint")
     lp.add_argument("--json", action="store_true", help="emit findings as JSON")
     lp.add_argument("--strict", action="store_true", help="exit non-zero on WARN/INFO too, not just ERROR")
     lp.set_defaults(func=cmd_lint)

package/CHANGELOG.md

@@ -6,6 +6,88 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.9.0] — 2026-06-22
+
+### Breaking changes
+
+- **Cassette staleness fingerprint bumped to format v6 (re-record once).** The skill-hash boundary changed,
+  so committed cassettes recorded before this release report `recorded under an older hash format — re-record
+  once`. Drivers: (1) **OS-junk** files (`.DS_Store` / `Thumbs.db` / `desktop.ini`) are excluded from
+  `skillHash` — an out-of-band OS metadata touch can no longer re-stale a cassette (the "fresh cassette is
+  immediately stale" bug); (2) **`contentSig` is unified onto the same walk as `skillHash`** (same file set,
+  plugin.json `version` stripped, in-tree symlinks hashed by target) — `rehash` cannot bridge this algorithm
+  change, so a pre-v6 cassette gets an honest *"algorithm changed — re-record"* (not "content changed"); (3)
+  the **git-tracked file set is the default boundary** (see Added).
+- **Git-tracked staleness/mount boundary is now the DEFAULT.** When a skill/plugin source dir is in a git
+  work tree, both the staleness hash and the sandbox mount use only its **git-tracked** files (untracked
+  scratch / build output / OS-junk are excluded from both, so they can't drift the hash or leak into the
+  sandbox). A dir that isn't a git repo falls back to the raw walk automatically. Opt out with
+  `COWORK_HARNESS_GITSET=0`.
+- **Removed the legacy CLI aliases.** `assert` → use `assertions`; `replay --cassette <file>` → pass the
+  path positionally (`replay <file | dir/>`); `verify-cassettes --privacy-only` / `--staleness-only` →
+  `--skip-privacy` / `--skip-staleness`. (0.8.0 had documented the latter two groups as renamed/removed but
+  the code still accepted the old forms; they are now gone. Each removed alias exits `2` if used.)
+- **`assertions --list --output-format json` now reports `command: "assertions"`** (was the stale
+  `"assert"`) — a JSON-envelope contract fix for anything keying on the `command` field.
+- **`decide` exits `2` (not `1`) on a runtime error**, matching the documented "usage / runtime → `2`"
+  contract. No-match / abstain still exits `1`.
+
+### Added
+
+- **`cowork-harness/secrets` package export** — `scrubField` and `collectSecrets` are now importable as a
+  declared subpath (`import { scrubField, collectSecrets } from "cowork-harness/secrets"`) for custom
+  redaction pipelines, with the documented usage corrected to `scrubField(value, collectSecrets())` (a bare
+  `[token]` array misses secrets embedded in encoded fields). Adding the `exports` map also **bounds the
+  package's public surface to this one subpath** — deep imports into `dist/` (`cowork-harness/dist/...`),
+  previously resolvable by accident, are now private. The CLI (`bin`) is unaffected.
+- **`lint` accepts a directory** — it expands to the directory's `*.yaml` / `*.yml` scenarios
+  (non-recursive, sorted), the same file-or-dir ergonomics as `replay` / `verify-cassettes`. An empty
+  directory is a loud error, never a vacuous "0 files = clean" pass.
+- **Staleness now names the EXACT changed file.** A per-file manifest (`fileSigs`) in the cassette fingerprint
+  lets `verify-cassettes` report e.g. `skill files changed since record — 1 changed (skills/x/SKILL.md)`
+  instead of a coarse bucket message (appended to the existing shared-vs-scoped diagnosis). Manifest paths are
+  root-relative and are scanned + redacted with the same privacy layer as `skillSources`. Omitted (with a
+  loud `fileSigsOmitted`) above an internal size cap.
+- **`COWORK_HARNESS_DEBUG_SKILLHASH=1`** — on a staleness mismatch, dumps the exact file set feeding the hash
+  to stderr and flags OS-junk, so a drift source is one line instead of a black-box hunt (a one-line hint
+  points to it when the flag is off).
+- **`COWORK_HARNESS_GITSET=0`** — opt out of the new default git-tracked boundary (see Breaking) back to the
+  legacy raw filesystem walk for every dir.
+- **`requires_capabilities` scenario assertion** — fail a scenario unless the running tier provides *and can
+  verify* the declared capability families (e.g. `office_convert`, `pdf_tables`). The unmet set is persisted
+  in the run result (`requiresCapabilityUnmet`), so `verify-run` can't false-fail; opt out with the
+  `allow_missing_capability` verdict modifier when the skill's fallback is genuinely equivalent.
+- **LLM decider `OTHER:` free-text directive** — on an options-bearing gate, a decider answer of
+  `OTHER: <text>` is matched to a label first, else passed through as free text; a bare out-of-set value
+  still fails loud.
+
+### Fixed
+
+- **`doctor --tier microvm` now checks the right prerequisites.** It previously probed the Docker daemon +
+  agent image + egress-proxy image for every live tier, but the `microvm` (L2) tier runs on **Lima / Apple
+  Virtualization.framework**, not Docker — so it could report "not ready" on a Lima-only host, or "ready"
+  with no Lima installed. `microvm` now checks `limactl` (honoring `COWORK_LIMACTL`) + the staged agent
+  binary, and skips the Docker checks; `container`/`hostloop`/`cowork` are unchanged.
+- **A freshly recorded cassette no longer reports `[stale]` immediately** because the OS rewrote a `.DS_Store`
+  (or other OS-junk) in the skill tree — OS-junk is excluded from the skill hash. A chronic false-positive
+  that pushed consumers to WARN-only (which then masked real drift).
+- A standalone verdict-modifier assertion (e.g. `allow_l0_plugin_divergence: true`) no longer false-fails
+  as "empty assertion", and verdict modifiers no longer trigger a misleading "filesystem/egress skipped"
+  warning on the replay lane. The verdict modifiers are now single-sourced from one list (`assert.ts`,
+  `cassette.ts`, and the Python linter all derive from / are checked against it), guarded by a convention
+  test against drift.
+- **A tail-end transport drop is no longer conflated with an agent failure.** A connection closed *after* a
+  clean result is classified as `resultErrorKind: "transport"` (vs `"agent"`) and surfaced as a
+  lane/assertion-aware `transport_error` verdict — still a failure (no false-green), but distinguishable from
+  a genuine skill error; a non-matching envelope falls back to the agent classification.
+- **Clearer guard / capability legibility.** The run footer lists only guards that actually ran this lane
+  (`capabilityProbe: definitive | unverified | skipped`) — never a false check-mark for a guard that didn't
+  run; capability notices state their own safety net + all-clear with verdict-impact tags; the unbuilt `max`
+  tier is dropped from capability hints; and Docker pool-exhaustion is reframed as a concurrency limit, not a
+  leak.
+- **Ordered interrupt cleanup.** A `SIGINT` / `SIGTERM` during a live run reaps in-flight egress resources in
+  order (container thunks before network thunks) and announces itself, instead of leaving them dangling.
+
 ## [0.8.0] — 2026-06-21
 
 ### Breaking changes

package/README.md

@@ -17,10 +17,10 @@ Scriptable, CI-friendly test harness that reproduces **Claude Cowork's observabl
 
 > **Requirements at a glance**
 > - **Free demo (`replay`):** Node ≥ 20 — nothing else (no Docker, token, or Claude Desktop).
-> - **Live tiers** (`container` default / `microvm` / `hostloop`): **Docker (arm64)** · **Claude Desktop opened once** (stages the agent — nothing is bundled) · a **Claude token** (real per-run cost; runs take minutes). The `protocol` tier skips Docker + the staged agent but still calls a real model, so it needs the token.
+> - **Live tiers**: **Claude Desktop opened once** (stages the agent — nothing is bundled) · a **Claude token** (real per-run cost; runs take minutes) · plus a runtime — **Docker (arm64)** for `container` (default) / `hostloop`, or **Lima (Apple-VZ)** for `microvm`. The `protocol` tier skips the runtime + the staged agent but still calls a real model, so it needs the token. (`doctor --tier <t>` reports exactly what a given tier needs.)
 > - **Platform:** best on **macOS Apple Silicon**; **Windows is not supported** for the live tiers (use the token-free `replay`); `sync` and `microvm` are **macOS-arm64 only**. Full detail in [Quick start → prerequisites](#quick-start).
 
-> **New here?** Read [docs/boundary.md](./docs/boundary.md) (the limitations model) and [docs/session.md](./docs/session.md) (the file you'll author).
+> **New here?** Start by running a committed cassette `replay` and browsing [`examples/`](./examples/) (see [examples/README.md](./examples/README.md)) to see green runs before any setup — then read [docs/boundary.md](./docs/boundary.md) (the limitations model) and [docs/session.md](./docs/session.md) (the file you'll author).
 
 > **What this is and isn't.** This is an *emulator of the contract*, not the Desktop runtime. Cowork's real session control plane lives behind the Desktop renderer's IPC (per-build UUID + `senderFrame` origin checks) and the app ships with remote debugging disabled (verified: `--remote-debugging-port` opens no listener; Electron `EnableNodeCliInspectArguments` fuse is OFF). So you **cannot** drive the real Apple Virtualization.framework microVM from a script. What you *can* faithfully reproduce is everything that actually changes how a **skill** behaves: the same agent binary in **cowork mode** (`CLAUDE_CODE_IS_COWORK=1` — there is no `--cowork` flag), the same mount layout, the same egress allowlist, and the same permission/question protocol. That's what this project does.
 
@@ -54,7 +54,7 @@ The permission/question protocol is the backbone, and it's the *most stable* sur
 
 ```
 L0  protocol-only     claude -p stream-json on the host. No sandbox, no egress control.
-                      Fastest. Tests skill logic + scripted answers. CI default for unit-style.
+                      Fastest. Pure-logic / inner-loop assertions.
 
 L1  container parity  Pinned agent in cowork mode inside an arm64 Linux container with the real
    (recommended)      mount layout and a default-deny egress proxy enforcing the synced allowlist.
@@ -75,7 +75,7 @@ L2  microvm parity    Optional. Agent inside a real Linux microVM (Lima/Apple-VZ
                       gate 1143815894 decoded in the synced baseline. "Do what real Cowork does."
 ```
 
-Most skill testing runs **L1 (`container`)**. Use **L0 (`protocol`)** for fast inner-loop and pure-logic assertions; **L2 (`microvm`)** for VM-grade escape isolation of untrusted code (rare — it does **not** improve network-transport fidelity over L1); **`hostloop`/`cowork`** to reproduce Cowork's production split-execution model. Set the tier with `fidelity:` in a scenario or `--fidelity` on `skill`.
+Most skill testing runs **L1 (`container`)**. Use **L0 (`protocol`)** for fast inner-loop and pure-logic assertions; **L2 (`microvm`)** for VM-grade escape isolation of untrusted code (rare — it does **not** improve network-transport fidelity over L1); **`hostloop`/`cowork`** to reproduce Cowork's production split-execution model. Set the tier with `fidelity:` in a scenario or `--fidelity` on `skill` or `chat`.
 
 ---
 
@@ -88,19 +88,19 @@ 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; `--max-artifact-bytes` raises the 64 KiB inline-body cap); `replay` runs a cassette **file or a `dir/` of `*.cassette.json`** deterministically (`<file\|dir>`, `--cassette <file>` for the explicit single form; `--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; `--max-artifact-bytes` raises the 64 KiB inline-body cap); `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 |
 | `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:` against an already-kept run dir — **no live agent, no tokens, no Docker** (~1s) | iterating on a wrong assertion 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?" |
 | `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/`; `cowork-harness lint --help` shows the resolved path) | starting a new scenario when you have no prior run |
-| `lint <scenario.yaml>…` | Check scenarios for silent false-greens — assertions placed on the wrong CI lane, mixed content/live keys, missing `controlOut`-required keys (bundled `scenario.py`; needs python3 + PyYAML) | before committing a new scenario or after changing assertions |
+| `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) | before committing a new scenario or after changing assertions |
 | `assertions --list` | List the available scenario assertions (generated from the schema); `assert` is a deprecated alias | "what can I assert?" without grepping the source |
 | `decide` | Validate a decider against a sample question in ~2 s (no run) | sanity-check a `--decider-*` / `--answer` wiring before a long run |
 | `gates` / `answer` | Stream / answer in-band gates for `--decider-dir` | a **driving agent** answers live questions via a Monitor |
 | `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 (Docker, 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 |
+| `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 |
 | `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` |
@@ -202,20 +202,26 @@ 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.8.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.9.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.)
 
 > Note: `npm install -g cowork-harness` ships `scenario.py` and assertion keys (enough for `lint` in CI) but not the full SKILL.md teaching document; install via the marketplace command above to get the teaching skill.
 
-**Prerequisites for anything above `protocol` fidelity** (the `protocol` tier skips items 1–2 — no Docker, no staged agent — but still calls a real model via the host `claude`, so it needs item 3, the auth token; only a committed-cassette `replay` needs nothing at all):
+### Prerequisites for anything above `protocol` fidelity
+
+(The `protocol` tier skips items 1–2 — no Docker, no staged agent — but still calls a real model via the host `claude`, so it needs item 3, the auth token; only a committed-cassette `replay` needs nothing at all):
 1. **Claude Desktop, opened once.** The Cowork agent binary is **bind-mounted from your own install** at run time — nothing Anthropic-owned is bundled. Open Cowork once so the agent ELF is staged (`…/claude-code-vm/<ver>/claude`); the harness auto-detects it, or set `COWORK_AGENT_BINARY=<path>` to point at it. Without a staged agent, container/cowork runs fail with "Open Cowork once to stage it…".
-2. **Docker (arm64)** + the agent image: `docker build --platform linux/arm64 -t cowork-agent-base:2 -f docker/Dockerfile.agent .` (override the tag with `COWORK_AGENT_IMAGE`). This **core** image mirrors the real Cowork rootfs's document/data toolchain (Node 22, openpyxl/pandas/pdf/docx/pptx, …). For OCR / LibreOffice / markitdown / opencv / PDF-table skills, build the **full-parity** image instead: `docker build --platform linux/arm64 --build-arg COWORK_FULL_PARITY=1 -t cowork-agent-full:2 -f docker/Dockerfile.agent .` and point `COWORK_AGENT_IMAGE` at it. (A run on the core image that uses an omitted capability is flagged — see capability detection.) The `-f docker/Dockerfile.agent .` paths are **repo-relative** — run it from a source checkout, not a global `npm install -g`. (Global install? Run `cowork-harness doctor --tier container` — it prints the exact `docker build` command with the correct package-local Dockerfile path.)
+2. **Docker (arm64)** + the agent image: `docker build --platform linux/arm64 -t cowork-agent-base:2 -f docker/Dockerfile.agent .` (override the tag with `COWORK_AGENT_IMAGE`). This **core** image mirrors the real Cowork rootfs's document/data toolchain (Node 22, openpyxl/pandas/pdf/docx/pptx, …). For OCR / LibreOffice / markitdown / opencv / PDF-table skills, build the **full-parity** image instead: `docker build --platform linux/arm64 --build-arg COWORK_FULL_PARITY=1 -t cowork-agent-full:2 -f docker/Dockerfile.agent .` and point `COWORK_AGENT_IMAGE` at it. (A run on the core image that uses an omitted capability is flagged — see capability detection.) The `-f docker/Dockerfile.agent .` paths are **repo-relative** — run it from a source checkout, not a global `npm install -g`. (Global install? Run `cowork-harness doctor --tier container` — it prints the exact `docker build` command with the correct package-local Dockerfile path.) The **`microvm` (L2)** tier uses **Lima / Apple-VZ** instead of Docker (`brew install lima`; no agent image to build) — `doctor --tier microvm` checks for that, not Docker.
 3. **An auth token** — either `export CLAUDE_CODE_OAUTH_TOKEN=$(claude setup-token)` or a **`.env`** file (copy `.env.example` → `.env`; gitignored). The token resolves in priority order: exported env > `--dotenv <path>` > `./.env` (cwd) > `<install>/.env` (the package root), so a `npm link`ed install works from any directory. Keep `.env` at a working-dir or install root, never inside a mounted skill/project folder. (Use `--dotenv`, not `--env-file` — Node reserves the latter.)
 
 > `sync` (below) is **optional for a first run** — the repo ships `baselines/desktop-*.json`, so `baseline: latest` already resolves. Run `sync` only to refresh the platform baseline after Claude Desktop updates. (`sync` is **macOS-only** today; on Linux/Windows use the committed baselines — they work cross-platform.)
 
 ```bash
+# 0. Before the first live run: check prerequisites (Docker, staged agent, token, baseline).
+cowork-harness doctor                      # read-only: what's present, what's missing
+cowork-harness doctor --tier container     # scope the check to a specific tier
+
 # 1. (Optional · macOS-only) Sync a platform baseline from your installed Claude Desktop.
 #    Skippable on a first run — the repo ships baselines; `baseline: latest` already resolves.
 cowork-harness sync            # writes baselines/desktop-<appVersion>.json
@@ -253,7 +259,8 @@ cowork-harness lint scenarios/*.yaml
 > orchestration from both, re-evaluates the **content** assertions, and re-exercises
 > `serializeDecision` as a token-free O7 guard (the AskUserQuestion `{questions,answers}` answer-shape
 > invariant). Evaluated on replay: `transcript_*`, `tool_*`, `subagent_*`, `dispatch_count_max`,
-> `result`, `allow_permissive_auto_allow` (always-on Cowork-parity scan). **`question_asked`,
+> `result`, and the verdict modifiers `allow_permissive_auto_allow` / `allow_missing_capability` /
+`allow_l0_plugin_divergence` (no-op passes, kept on replay). **`question_asked`,
 > `questions_count_max`, and `gate_answers_delivered` are also evaluated —
 > but only when the cassette carries `controlOut` (full-fidelity)**; old cassettes without it get a
 > loud warning and those three keys are excluded (not vacuously passed). **Filesystem assertions
@@ -292,8 +299,10 @@ prompt: |
 
 # Scripted answers — the can_use_tool control channel, same as Desktop's question UI
 answers:
-  - when_question: "Which output format"   # substring/regex on AskUserQuestion
-    choose: "Markdown"
+  - when_question: "Which output format"   # regex (case-insensitive) on AskUserQuestion
+    choose: "Markdown"                      # by label; or choose: "2" for the 2nd option BY POSITION
+                                            # (index survives regenerated labels; ".*" matches any phrasing —
+                                            # last-resort, single gate/turn, after specific rules)
   - when_tool: Bash                        # tool-permission decisions
     allow_if: "!command.includes('rm -rf')"
     else: deny
@@ -460,6 +469,7 @@ Unit tests cover the scripted-answer logic, the egress allowlist matcher, the se
 - `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.
 - **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`).
 - **Secret scrubbing:** `COWORK_HARNESS_SCRUB_KEYS=<KEY1,KEY2>` adds extra env-var names whose values are redacted from logs (beyond the known auth tokens + `ANTHROPIC_CUSTOM_HEADERS`); `COWORK_HARNESS_SCRUB_VALUES=<v1,v2>` redacts literal values regardless of env. **Committed-cassette redaction:** `COWORK_HARNESS_REDACT_PATTERNS=<rx1,rx2>` / `COWORK_HARNESS_REDACT_KEYS=<k1,k2>` extend the privacy layer that scrubs recorded `controlOut` before a cassette is written for commit.
 - L2 microVM: `COWORK_VM_GATEWAY` overrides the Lima host-proxy gateway IP (default `192.168.5.2`); `COWORK_VM_PROXY_PORT` the proxy port. The Lima instance is named `cowork-vm-<config-hash>` (a config change → a fresh VM); `COWORK_LIMA_INSTANCE` pins a fixed name, and `vm prune` removes orphaned ones.
 - Pin `baseline: desktop-<ver>` and `model:` in a session for byte-stable runs; use `latest` to track.
@@ -474,7 +484,7 @@ When a new Claude Desktop ships:
 cowork-harness sync --diff
 ```
 
-`cowork-sync` reads your **live install** and the **app.asar** and re-derives the baseline:
+`cowork-harness sync` reads your **live install** and the **app.asar** and re-derives the baseline:
 
 | Baseline field | Source (auto-detected) |
 |---|---|
@@ -521,7 +531,9 @@ This repo is built to be driven by agents, not just read by humans:
 | [docs/boundary.md](./docs/boundary.md) | The limitations model — sealed FS, default-deny egress, MCP-only crossing; how each tier enforces it; how to verify. |
 | [docs/session.md](./docs/session.md) | Every `sessions/*.yaml` field and its Cowork mapping. |
 | [docs/scenario.md](./docs/scenario.md) | `scenarios/*.yaml` — prompt, scripted answers, assertions. |
+| [docs/chat.md](./docs/chat.md) | The interactive `chat` REPL — multi-turn debugging, flags, attaching files/folders. |
 | [docs/cassette.md](./docs/cassette.md) | `record`/`replay` cassettes — what replay checks, which assertions are skipped. |
+| [docs/fidelity-gaps.md](./docs/fidelity-gaps.md) | The known deltas vs. real Cowork — what the harness does and doesn't reproduce. |
 | [docs/decider-dir.md](./docs/decider-dir.md) | The `--decider-dir` recipe — a driving agent answers live gates in-band via `gates`/`answer` + a Monitor. |
 | [docs/discovery.md](./docs/discovery.md) | Where plugins/skills/MCP are found + overrides. |
 | [docs/maintenance.md](./docs/maintenance.md) | Parity across Desktop releases via `sync`. |
@@ -529,6 +541,7 @@ This repo is built to be driven by agents, not just read by humans:
 | [SPEC.md](./SPEC.md) | The authoritative testable contract (scenario/session schema, `RunResult`, exit codes). |
 | [CHANGELOG.md](./CHANGELOG.md) | Release history. |
 | [python/README.md](./python/README.md) | The `cowork` pytest lane for driving the harness from Python. |
+| [examples/README.md](./examples/README.md) | The worked examples to copy — sessions, scenarios, and skills you can run end-to-end. |
 | [SECURITY.md](./SECURITY.md) | Threat model — the sandbox is a fidelity fixture, not a security boundary. |
 
 ## Status

package/dist/agent/session.js

@@ -595,7 +595,15 @@ export function parseMessage(msg) {
             }
             break;
         case "result":
-            ev.push({ type: "result", isError: !!msg.is_error, usage: msg.usage });
+            ev.push({
+                type: "result",
+                isError: !!msg.is_error,
+                usage: msg.usage,
+                // Fix 5: preserve the SDK result payload + subtype so run.ts can tell a transport drop
+                // (e.g. "API Error: Connection closed", subtype error_during_execution) from a skill failure.
+                resultText: typeof msg.result === "string" ? msg.result : undefined,
+                subtype: typeof msg.subtype === "string" ? msg.subtype : undefined,
+            });
             break;
     }
     return ev;

package/dist/assert.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, statSync, realpathSync } from "node:fs";
 import { resolve, relative, isAbsolute, sep } from "node:path";
+import { VERDICT_MODIFIER_KEYS } from "./types.js";
 import { compileUserRegex } from "./regex.js";
 import { normalizeHost } from "./boundary-paths.js";
 /** Resolve a user-authored assertion path under `workRoot`, rejecting absolute paths and any `..` that
@@ -318,13 +319,12 @@ function check(a, ctx) {
             : ctx.selfHealRan === a.self_heal_ran
                 ? ok()
                 : fail(`self_heal_ran was ${ctx.selfHealRan}, expected ${a.self_heal_ran}`));
-    // Verdict modifier (consumed by computeVerdict, not here). It always "passes" as an assertion so a
-    // standalone `{allow_permissive_auto_allow: true}` is a valid non-empty assertion, not "empty assertion".
-    if (a.allow_permissive_auto_allow !== undefined)
-        results.push(ok());
-    // Verdict modifier (same pattern): standalone `{allow_missing_capability: true}` must not be "empty".
-    if (a.allow_missing_capability !== undefined)
-        results.push(ok());
+    // Verdict modifiers (consumed by computeVerdict, not here) each always "pass" as an assertion, so a
+    // standalone `{allow_*: true}` is a valid non-empty assertion, not "empty assertion". Derived from the
+    // single VERDICT_MODIFIER_KEYS list so a newly-added modifier can never miss this branch again.
+    for (const k of VERDICT_MODIFIER_KEYS)
+        if (a[k] !== undefined)
+            results.push(ok());
     if (a.transcript_no_host_path !== undefined)
         results.push(ctx.scanMissing
             ? fail(`evidence unavailable: post-run scan absent from result.json — cannot evaluate transcript_no_host_path`)

package/dist/cli.js

@@ -248,11 +248,10 @@ const SUBCOMMAND_USAGE = {
     vm: "usage: vm <init|status|delete|prune> [--output-format text|json]   (macOS arm64 only)\n  init    create the L2 Apple-VZ microVM\n  status  show running VM state\n  delete  remove a named VM\n  prune   drop all orphaned VMs",
     chat: "usage: chat <skill-folder> [prompt] [--fidelity protocol|container|hostloop] [--model <id>]\n              [--upload <file>]... [--folder <dir>]... [--plugin <dir>]... [--verbose] [--raw]\n       --raw: native cowork mode via docker run -it; egress sandbox NOT applied; rejects --upload/--folder/--plugin/--fidelity (only --model applies)\n       --fidelity: protocol/container/hostloop only (no microvm/cowork); protocol = no Docker, no sandbox",
     record: "usage: record <scenario.yaml | dir/> [--out <file>] [--output-format text|json] [--rerecord-stale] [--no-redact] [--allow-failing] [--max-artifact-bytes <n>] [--dry-run]",
-    replay: "usage: replay <file.cassette.json | dir/> [--strict] [--output-format text|json]\n       Positional path is the canonical form. --cassette <file> is a legacy alias (providing both is an error).",
+    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)",
     assertions: "usage: assertions --list [--output-format json]",
-    assert: "usage: assertions --list [--output-format json]   (use 'assertions' — 'assert' is the legacy name)",
     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)",
@@ -274,7 +273,6 @@ const COMMANDS = [
     "verify-run",
     "trace",
     "assertions",
-    "assert",
     "scaffold",
     "decide",
     "gates",
@@ -407,9 +405,6 @@ async function main() {
             return cmdTrace(rest);
         case "assertions":
             return cmdAssert(rest);
-        case "assert": // legacy alias — keep working, show deprecation notice
-            log("note: 'assert' has been renamed to 'assertions'; please update your scripts.\n");
-            return cmdAssert(rest);
         case "scaffold":
             return cmdScaffold(rest);
         case "decide":
@@ -1541,7 +1536,9 @@ async function cmdDecide(args) {
             out(jsonError("decide", "runtime", String(e.message)));
         else
             log(`✗ decider error: ${String(e.message)}`);
-        process.exit(1);
+        // Runtime failure → exit 2, matching the global "usage/runtime → 2" contract (SPEC §11). The JSON
+        // envelope already tags this category "runtime"; the exit code now agrees. No-match/ABSTAIN stays 1.
+        process.exit(2);
     }
 }
 /** `gates <dir> [--follow]` — the gate stream for the in-band `--decider-dir` path. Emits one clean
@@ -1857,24 +1854,24 @@ function cmdVerifyRun(args) {
     }
     return process.exit(verdict.exitCode);
 }
-/** `assert --list` (#8) — enumerate the available assertion keys + one-line semantics, generated from the
+/** `assertions --list` (#8) — enumerate the available assertion keys + one-line semantics, generated from the
  *  Zod `Assertion` schema (`Assertion.shape[k].description`) so the list can NEVER drift from the schema. */
 function cmdAssert(args) {
     const json = isJsonOutput(args);
     // validate --output-format is text|json (an invalid value was a silent text degrade).
-    ensureOutputFormat("assert", args);
+    ensureOutputFormat("assertions", args);
     if (!args.includes("--list"))
-        return void fail("assert", "usage", "usage: assert --list [--output-format json]", undefined, json);
-    // `assert --list` takes no positionals and no other flags; reject stray ones rather than
-    // silently ignoring them (e.g. `assert --list extra` or `assert --list --bogus`).
+        return void fail("assertions", "usage", "usage: assertions --list [--output-format json]", undefined, json);
+    // `assertions --list` takes no positionals and no other flags; reject stray ones rather than
+    // silently ignoring them (e.g. `assertions --list extra` or `assertions --list --bogus`).
     const stray = positionals(args, ["--output-format"]);
     if (stray.length)
-        return void fail("assert", "usage", `assert --list takes no positional arguments (got: ${stray.join(", ")})`, undefined, json);
-    rejectUnknownFlags("assert", args, ["--list", "--output-format", "--output-format=json", "--output-format=text"], json);
+        return void fail("assertions", "usage", `assertions --list takes no positional arguments (got: ${stray.join(", ")})`, undefined, json);
+    rejectUnknownFlags("assertions", args, ["--list", "--output-format", "--output-format=json", "--output-format=text"], json);
     const shape = Assertion.shape;
     const keys = Object.keys(shape).map((k) => ({ key: k, description: shape[k].description ?? "" }));
     if (json)
-        return void out(JSON.stringify({ tool: "cowork-harness", command: "assert", assertions: keys }));
+        return void out(JSON.stringify({ tool: "cowork-harness", command: "assertions", assertions: keys }));
     const width = Math.max(...keys.map((k) => k.key.length));
     out(`available assertions (${keys.length}) — use under a scenario's \`assert:\` list:\n`);
     for (const { key, description } of keys)

package/dist/decide/decider.js

@@ -316,11 +316,29 @@ 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.
             const pick = matchLabel(raw, labels);
-            if (!pick)
-                throw new UnansweredError(`LLM decider answer "${raw.trim().slice(0, 60)}" is not one of the options for "${text}"`, `options were: ${labels.join(" | ")}`);
-            process.stderr.write(`[llm-decider] "${text}" → "${pick}"${this.intent ? ` (intent: ${this.intent})` : ""}\n`);
-            answers[text] = pick;
+            if (pick) {
+                process.stderr.write(`[llm-decider] "${text}" → "${pick}"${this.intent ? ` (intent: ${this.intent})` : ""}\n`);
+                answers[text] = pick;
+                continue;
+            }
+            // No label matched. Cowork auto-provides a free-text "Other" path on EVERY gate (binary-verified), so
+            // accept an explicit `OTHER: <value>` directive as free text — symmetric with ScriptedDecider's
+            // `answer:` escape hatch — delivered verbatim. A reply that is neither a label nor the explicit OTHER
+            // channel stays a LOUD failure: we do NOT coerce an arbitrary string into free text, or we'd mask a
+            // model that picked a wrong/hallucinated option label.
+            const other = /^\s*OTHER:\s*([\s\S]+)/i.exec(raw);
+            if (other) {
+                const free = other[1].trim();
+                if (free === "")
+                    throw new UnansweredError(`LLM decider returned an empty OTHER answer for "${text}"`, "an OTHER free-text directive needs a non-empty value");
+                process.stderr.write(`[llm-decider] "${text}" → free-text (Other)${this.intent ? ` (intent: ${this.intent})` : ""}\n`);
+                answers[text] = free;
+                continue;
+            }
+            throw new UnansweredError(`LLM decider answer "${raw.trim().slice(0, 60)}" is not one of the options for "${text}"`, `options were: ${labels.join(" | ")}. For a free-text / name gate the model must reply \`OTHER: <value>\` (Cowork's auto-provided "Other" path) — a bare out-of-set value is rejected.`);
         }
         return { response: { kind: "question", answers }, by: "llm", rationale: this.intent ?? "LLM judgment", model: this.model };
     }
@@ -349,7 +367,9 @@ export class LlmDecider {
             tail ? `Recent context (transcript tail):\n${tail}` : "",
             `Question: ${question}`,
             `Options:\n${options.map((o) => `- ${o.label}${o.description ? `: ${o.description}` : ""}`).join("\n")}`,
-            `Reply with ONLY the exact label of the single best option. No explanation, no punctuation — just the label.`,
+            `Reply with ONLY the exact label of the single best option — no explanation, no punctuation. ` +
+                `If none of the options fits and the intent calls for a custom value (the gate always allows a ` +
+                `free-text "Other" entry), reply with exactly \`OTHER: <your value>\` instead.`,
         ]
             .filter(Boolean)
             .join("\n\n");

package/dist/egress/sidecar.js

@@ -4,6 +4,50 @@ import { mkdirSync, readFileSync, existsSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 const PROXY_IMAGE = process.env.COWORK_PROXY_IMAGE ?? "cowork-egress-proxy:1";
+const cleanupRegistry = new Set();
+let signalHandlerInstalled = false;
+/** Register a signal-time cleanup thunk; returns a de-register fn to call from the normal `finally` path
+ *  (so a clean exit doesn't double-run it — and `teardown()`/`rm -f` are idempotent regardless). */
+export function registerCleanup(entry) {
+    cleanupRegistry.add(entry);
+    installSignalHandlerOnce();
+    return () => cleanupRegistry.delete(entry);
+}
+/** Drain all registered cleanups in phase order — "container" thunks BEFORE "network" thunks (load-bearing:
+ *  `network rm` fails while a container is still attached). Returns the number of thunks run. Exported for
+ *  tests; the signal handler calls this then exits. */
+export function drainCleanups() {
+    const entries = [...cleanupRegistry];
+    for (const e of entries)
+        if (e.phase === "container")
+            tryRun(e.run);
+    for (const e of entries)
+        if (e.phase === "network")
+            tryRun(e.run);
+    return entries.length;
+}
+function installSignalHandlerOnce() {
+    if (signalHandlerInstalled)
+        return;
+    signalHandlerInstalled = true;
+    const handler = (sig) => {
+        const n = cleanupRegistry.size;
+        if (n)
+            warn(`::warning:: [cleanup] ${sig} — reaping ${n} in-flight egress resource(s) before exit\n`);
+        drainCleanups();
+        process.exit(sig === "SIGINT" ? 130 : 143);
+    };
+    process.on("SIGINT", handler);
+    process.on("SIGTERM", handler);
+}
+function tryRun(fn) {
+    try {
+        fn();
+    }
+    catch {
+        /* best-effort during signal teardown */
+    }
+}
 export function startEgressSidecar(allow, outDir, runId) {
     const runner = process.env.COWORK_CONTAINER_RUNTIME ?? "docker";
     const intNet = `cowork-int-${runId}`;
@@ -49,8 +93,19 @@ export function startEgressSidecar(allow, outDir, runId) {
     catch (e) {
         for (const undo of rollback.reverse())
             undo();
-        throw e;
+        // 6e: re-frame Docker's opaque address-pool-exhaustion error (which surfaces at create, connect, OR
+        // `run --network`) into an actionable diagnosis — it reads as a "leak" but is concurrency pressure;
+        // each run reaps its own networks on exit. Rollback above already ran, so this only changes the message.
+        throw reframeEgressError(e);
     }
+    const reap = () => {
+        d(runner, ["rm", "-f", proxyName], true); // proxy container before its networks (attached)
+        d(runner, ["network", "rm", intNet], true);
+        d(runner, ["network", "rm", outNet], true);
+    };
+    // 2a: cover Ctrl-C — reap this run's proxy+networks on a signal too. Registered as the "network" phase so a
+    // caller-registered agent-container reap ("container" phase) runs first (network rm needs the container gone).
+    const deregister = registerCleanup({ phase: "network", run: reap });
     return {
         proxyUrl: `http://${proxyName}:8080`,
         network: intNet,
@@ -65,9 +120,8 @@ export function startEgressSidecar(allow, outDir, runId) {
                 .filter((x) => x !== null);
         },
         teardown() {
-            d(runner, ["rm", "-f", proxyName], true);
-            d(runner, ["network", "rm", intNet], true);
-            d(runner, ["network", "rm", outNet], true);
+            deregister();
+            reap();
         },
     };
 }
@@ -126,6 +180,23 @@ function ensureProxyImage(runner) {
     if (build.status !== 0)
         throw new Error(`failed to build ${PROXY_IMAGE}`);
 }
+/** 6e: turn Docker's `all predefined address pools have been fully subnetted` (and its connect/run
+ *  variants) into a self-answering message — it is NOT a leak (each run reaps its own networks on exit),
+ *  it is concurrency pressure against the daemon's address pool. Any non-matching error passes through. */
+export function reframeEgressError(e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    // Match Docker's two canonical pool-exhaustion messages without over-matching unrelated docker errors:
+    //   "all predefined address pools have been fully subnetted"
+    //   "could not find an available, non-overlapping IPv4 address pool among the defaults to assign ..."
+    const poolExhausted = /address pool/i.test(msg) && /predefined|available|non-overlapping|subnet|defaults|exhaust/i.test(msg);
+    if (poolExhausted) {
+        return new Error("egress network create failed — Docker address pool exhausted. This is concurrency pressure " +
+            "(live runs × 2 networks each), NOT a leak: each run reaps its own networks on exit. Orphans only " +
+            "persist from SIGKILL'd runs → `docker network prune`. For higher parallelism, widen the daemon " +
+            `\`default-address-pools\`. (original: ${msg.slice(0, 200)})`);
+    }
+    return e;
+}
 function d(runner, args, ignoreError = false) {
     const r = spawnSync(runner, args, { encoding: "utf8" });
     if (r.status !== 0 && !ignoreError) {