cowork-harness 0.4.3 → 0.5.0

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

@@ -115,6 +115,7 @@ TOP_LEVEL_KEYS = {
     "answers",
     "expect_denied",
     "assert",
+    "skills",  # F-6: opt-in skill-staleness hash scope
 }
 REGEX_KEYS = {
     "transcript_matches",

package/CHANGELOG.md

@@ -6,6 +6,61 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.5.0] — 2026-06-18
+
+### Added
+
+- **`verify-run <run-dir> <scenario.yaml>`** — re-evaluate a scenario's `assert:` block against an
+  already-kept run dir with **no live agent** (no tokens, no Docker). Fixing a wrong assertion was a full live
+  re-record (~17 min); this turns it into ~1s. Reconstructs the assert context from the run's `result.json` +
+  the `run.jsonl`/`trace.json` sidecars and routes the verdict through the same path as a real record. Refuses
+  (rather than false-passing) when a filesystem assertion needs a work dir that's already torn down.
+- **`record --max-artifact-bytes <n>` / `COWORK_HARNESS_MAX_ARTIFACT_BYTES`** — override the 64 KiB
+  inline-body cap so a large structured deliverable can be inlined instead of stored hash-only. Paired with a
+  **record-time guard**: if an `artifact_json` asserts an artifact that had to be truncated, record now fails
+  (or warns under `--allow-failing`) at the cause, instead of producing a green record that goes red at replay
+  (no committed body to parse).
+- **`verify-cassettes --allow-domain` / `--allow-email` / `--allow-file`** — class-scoped privacy allows, plus
+  a version-controlled allow file (one regex per line, `#` comments).
+- **Scoped cassette-staleness fingerprint** — scenario **`skills: [<name>]`** narrows the staleness hash to the
+  named skills' dirs plus the plugin's shared roots (fail-closed to whole-tree on an unknown name); session
+  **`staleness.hash_ignore`** globs and a plugin-local **`.cowork-hashignore`** file (composed) drop
+  non-runtime paths (`tests/`, `docs/`). Default behavior is unchanged (whole-tree, byte-identical). Cassette
+  format bumped to **v2** (an older reader warns rather than mis-flagging a scoped cassette as stale).
+- **Per-subcommand `--help`** — subcommands now print a usage line and exit 0 instead of answering `--help`
+  with `unknown flag` (exit 2).
+- **Cowork identity in the system-prompt append** — the emulated agent now self-identifies as "Claude, the
+  Cowork assistant" and is told it is **not** Claude Code (verified against the installed Claude Desktop app;
+  reconstructed, not bundled).
+
+### Fixed
+
+- **Privacy allows are whole-token + class-scoped.** A bare `--allow <regex>` previously substring-matched, so a
+  domain allow (`example\.com`) silently cleared an email finding (`alice@example.com`) whose domain it matched.
+  Allows are now anchored to the whole finding token, and `--allow-domain`/`--allow-email` can't bleed across
+  classes — the email tripwire stays live.
+- **Staleness hash no longer over-fires.** A pure `plugin.json` `version` bump (and, with the new scoping knobs,
+  unrelated skills/tests/docs) no longer re-stales every cassette in a multi-skill plugin. *Upgrade note:*
+  because the hash now ignores the `plugin.json` `version` field, cassettes recorded before this release
+  recompute to a new digest and are flagged **stale once** after upgrading — re-record them
+  (`record --rerecord-stale`). The cassette format is also bumped to **v2**.
+- **`chat` is pipe/script-safe.** A piped/non-interactive stdin reaching EOF mid-turn crashed the REPL with
+  `ERR_USE_AFTER_CLOSE`; it now exits cleanly.
+- **Outputs-delete findings show the `rm` itself.** A long `VAR=…` assignment prefix used to push the operative
+  delete past the truncation; the finding now isolates and variable-resolves the delete target.
+- **Clearer record/run messaging.** The record freeze-refusal separates the run *result* from the *verdict* and
+  names the failing signal; the run log states the unscripted-question *policy* instead of reading as a failure
+  on clean runs.
+- **`sync` warns when a synced baseline lacks its host-loop prompt asset** — previously host-loop records
+  silently ran with an empty shell-access section.
+
+### Internal
+
+- Corrected the system-prompt fidelity note in `docs/boundary.md` (Cowork appends onto the `claude_code` preset
+  by default rather than replacing it).
+- Assertion docs steer content checks to `artifact_json` / stable lexical markers (not paraphrasable prose).
+- `vitest` excludes `runs/` from test discovery (ephemeral live output could crash the walk with EACCES).
+
 ## [0.4.3] — 2026-06-18
 
 ### Fixed

package/README.md

@@ -15,6 +15,11 @@ Scriptable, CI-friendly test harness that reproduces **Claude Cowork's observabl
 
 **Contents:** [Why it works](#why-this-works-for-skill-testing) · [Fidelity tiers](#fidelity-tiers-pick-per-scenario--per-ci-job) · [Quick start](#quick-start) · [Session + scenario](#two-files-session--scenario) · [Boundary](#sandboxing-container-vs-the-real-vm) · [Discovery](#discovery-marketplaces-plugins-skills-mcp) · [Testing & CI/CD](#testing--cicd) · [Maintenance](#maintenance-parity-between-releases) · [Docs](#documentation)
 
+> **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.
+> - **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).
 
 > **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.
@@ -74,15 +79,18 @@ 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>` | Interactive multi-turn REPL against a skill (TTY) | 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); `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 |
-| `verify-cassettes <file\|dir>` | Token-free CI gate over committed cassettes: a privacy scan (email/currency/domain → exit 1) + a staleness check (`--staleness-only`). 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" |
+| `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 |
+| `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 (`--staleness-only`). 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` (`--tools`, `--gates`, `--dispatches` for the sub-agent dispatch tree + total) | "how many sub-agents *actually* dispatched, and which?" |
 | `scaffold --from-run <id>` | Turn a kept run into a starter scenario YAML (gates→answers, artifacts→`file_exists`) | authoring a scenario from a real run instead of guessing |
+| `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 |
 | `assert --list` | List the available scenario assertions (generated from the schema) | "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]` | Prove the sandbox enforces Cowork's limitations | verifying the harness's own fidelity |
+| `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 |
 | `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` |
 
 There's also a **Python `cowork` pytest lane** (`python/`) for driving any of this from `pytest` beside your normal tests — see [`python/README.md`](./python/README.md).
@@ -182,7 +190,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.3.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.5.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.)
 
@@ -209,14 +217,15 @@ cowork-harness run examples/scenarios/ --output-format json
 
 # 4. Record a cassette once, then replay it deterministically (no token, no Docker)
 #    (without --out, the cassette is named after the scenario — its `name:`, or the filename)
-cowork-harness record examples/scenarios/example-pdf-skill.yaml --out cassettes/example-pdf-skill.cassette.json
-cowork-harness replay --cassette cassettes/example-pdf-skill.cassette.json
+#    Commit cassettes under examples/replays/ (this repo) or cassettes/ (conventional skill-repo name).
+cowork-harness record examples/scenarios/example-pdf-skill.yaml --out examples/replays/example-pdf-skill.cassette.json
+cowork-harness replay --cassette examples/replays/example-pdf-skill.cassette.json
 
 # A committed synthetic fixture is ready to replay on a fresh clone (no record step needed):
 cowork-harness replay --cassette examples/replays/example-pdf-skill.cassette.json
 
 # Cassettes are COMMITTED fixtures — record against synthetic data, and gate them in CI:
-cowork-harness verify-cassettes cassettes/   # privacy scan (email/currency/domain) + staleness; exit 1 on a finding
+cowork-harness verify-cassettes examples/replays/   # privacy scan (email/currency/domain) + staleness; exit 1 on a finding
 ```
 
 > **Privacy:** a cassette snapshots the transcript and the `outputs/` JSON bodies, so it's committed PII
@@ -403,11 +412,11 @@ Author scenarios in your own `scenarios/` dir, run the lot, get a non-zero exit
 cowork-harness run scenarios/            # your repo's scenarios; runs every *.yaml, CI-ready exit code
 ```
 
-The provided [GitHub Actions workflow](.github/workflows/ci.yml) runs a **four-stage pipeline** you can copy into your skill repo:
+The provided [GitHub Actions workflow](.github/workflows/ci.yml) runs a **four-stage pipeline**. The **unit** stage is the token-free gate you can copy into your skill repo; the `boundary`, `scenarios`, and `parity-drift` stages are this repo's own fidelity self-tests and are not directly portable (they build the harness's Docker image and run harness-specific e2e scenarios — see [`ci-recipe.md`](./.claude/skills/cowork-harness/references/ci-recipe.md) for the skill-repo template):
 
 | Stage | Runs | Needs | Gates |
 |---|---|---|---|
-| **unit** | format check · typecheck · unit tests · build · CLI smoke · token-free `replay` + `verify-cassettes` gates | nothing | every push/PR |
+| **unit** | format check · typecheck · unit tests · build · CLI smoke · token-free `replay` · `verify-cassettes` · `lint` | nothing | every push/PR |
 | **boundary** | builds the pinned agent image, brings up the default-deny network, runs `boundary-check` | Docker, arm64 runner | proves the sandbox enforces Cowork's limits — **no API key** |
 | **scenarios** | the live scenario suite at `container` fidelity, uploads transcripts/egress logs as artifacts | `ANTHROPIC_API_KEY` (or `CLAUDE_CODE_OAUTH_TOKEN`) | fork PRs: the whole job is skipped (`if:` guard); same-repo without a key: warns and exits 0 |
 | **parity-drift** | reminder to re-`sync` when Desktop updates | nothing | informational, never blocks |
@@ -433,7 +442,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:1`); `COWORK_AGENT_BINARY=<path>` — override the auto-detected staged agent ELF.
 - `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` — relocate the `runs/` output root (so `trace` resolves runs from any directory).
-- **Networking / loop:** `COWORK_EGRESS_PROXY` overrides the egress-proxy URL injected into the sandbox; `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`).
+- **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).
 - **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.
@@ -508,7 +517,7 @@ This repo is built to be driven by agents, not just read by humans:
 
 ## Status
 
-**Verified end-to-end against the live staged agent (2.1.170 / asar 1.12603.1).**
+**Verified end-to-end against the live staged agent (2.1.177 / asar 1.13576.1).**
 
 - ✅ **Three isolation tiers (L0/L1/L2) + two loop-mode overlays** — `protocol` (L0 control loop), `container` (L1 sandboxed arm64 + per-run default-deny egress sidecar), `microvm` (L2 real Apple-VZ Linux microVM + guest firewall); plus the loop-mode overlays `hostloop` (production split-execution: agent loop on host, shell/web via the workspace SDK-MCP server) and `cowork` (auto-picks host-loop vs container the way Cowork does — gate `1143815894`). Egress enforced at container/microvm/hostloop; `boundary-check` reports **ALL CONSTRAINTS ENFORCED**.
 - ✅ **Three-seam driver** — `AgentSession` (control protocol) → `Decider` (scripted + `on_unanswered` policy, no silent false-greens) → `Run` (turn loop, sub-agent dispatch tree, `RunRecord`). Multi-turn `chat`, deterministic cassette `record`/`replay` (no token), `run.jsonl`/`trace.json` logging with secret-scrub.

package/baselines/prompts/desktop-1.12603.1/system-prompt-append.md

@@ -6,6 +6,18 @@
      `initialize` (appendSubagentSystemPrompt). Tokens substituted by src/prompt.ts
      mirroring the Desktop builder `y8r`. -->
 
+<!-- <application_details> reconstructed from the real Cowork prompt. Binary-confirmed in
+     Claude.app app.asar 1.13576.1 at byte offset ~6,971,088 as a STATIC module constant —
+     the default cowork prompt body, NOT gated behind a server-pushed spVariant — and
+     cross-checked against behavioral capture (2026-06-18). Real Cowork = claude_code preset
+     + this append; the base preset alone makes the agent say "I'm Claude Code", so the
+     identity correction must live in the append (layered after the preset via
+     --append-system-prompt). Paraphrased, NOT copied verbatim, per the repo's no-bundling
+     rule; model name comes from the <env> block, not hardcoded here. -->
+<application_details>
+You are Claude, an AI assistant made by Anthropic. You are powering Cowork mode, a feature of the Claude desktop app that is currently a research preview. You are implemented on top of Claude Code and the Claude Agent SDK, but you are not Claude Code and should not refer to yourself as such — refer to yourself as Claude. Do not mention implementation details like this (including Claude Code or the Claude Agent SDK) unless it is relevant to the user's request.
+</application_details>
+
 <high_level_computer_use_explanation>
 Claude runs in a lightweight Linux VM (Ubuntu 22) on the user's computer. This VM provides a secure sandbox for executing code while allowing controlled access to user files. The working directory is {{cwd}}; user-attached folders are mounted under {{cwd}}/mnt/.
 </high_level_computer_use_explanation>

package/baselines/prompts/desktop-1.13576.1/host-loop-append.md

@@ -0,0 +1,11 @@
+<!-- host-loop "Shell access" section. Carried forward from desktop-1.12603.1 (the shell-access
+     semantics — independent bash calls, {{vmMnt}} path translation, unmounted ${CLAUDE_PLUGIN_ROOT}
+     self-heal — are version-stable across this Desktop range). Re-verify against the desktop-1.13576.1
+     asar (D8r host branch) when an asar copy is available. Appended to the system prompt only in
+     host-loop. {{vmMnt}} substituted. -->
+
+## Shell access
+
+Shell commands use `mcp__workspace__bash` and run in an isolated Linux environment. Each call is independent — no cwd or env carryover between calls. Use absolute paths.
+
+Paths in bash differ from what file tools (Read/Write/Edit) see. Your connected folders are mounted in bash under {{vmMnt}}/. A file you Read at a host path is reached in bash under {{vmMnt}}/ — translate host paths to their {{vmMnt}} equivalent before using them in bash. In particular, `${CLAUDE_PLUGIN_ROOT}` is a host path; to run a plugin's scripts in bash, locate them under {{vmMnt}} (e.g. `find {{vmMnt}} -path '*/skills/*/scripts'`) rather than using the host path directly.

package/dist/cli.js

@@ -16,6 +16,7 @@ import { cmdChat } from "./run/chat.js";
 import { cmdRecord, cmdReplay, cmdVerifyCassettes } from "./run/cassette.js";
 import { resolveInputs } from "./run/inputs.js";
 import { cmdLint } from "./run/scenario-tool.js";
+import { cmdDoctor } from "./run/doctor.js";
 import { parseArgs } from "./cli-args.js";
 import { loadDotenv } from "./dotenv.js";
 import { makeRenderer, renderStart, renderFooter, startHeartbeat } from "./run/renderer.js";
@@ -23,6 +24,7 @@ import { resolveEventsFile, buildTrace, formatTrace, buildGateTrace, formatGateT
 import { buildScaffold } from "./run/scaffold.js";
 import { pkgVersion, jsonEnvelope, jsonError, parseOutputFormat } from "./run/envelope.js";
 import { computeVerdict } from "./run/verdict.js";
+import { evaluate, hostMatches } from "./assert.js";
 import { spawnChannel, fileChannel, streamGates, answerGate, readGate } from "./decide/external-channel.js";
 // Synchronous writes (fd 1/2): `process.stdout.write` + `process.exit()` truncates on a PIPE, which
 // would lose the json envelope for any agent/CI that pipes us. writeSync flushes before exit.
@@ -52,12 +54,15 @@ const HELP = `cowork-harness <command>   (v${"$VERSION"})
                                (--fidelity container|hostloop, default container; --model <id>)
   record <scenario.yaml>       run + save a control-protocol cassette
       [--out <file>]           cassette path (default: cassettes/<scenario-name>.cassette.json)
+      [--max-artifact-bytes <n>]  inline-body cap (default 65536 / $COWORK_HARNESS_MAX_ARTIFACT_BYTES)
   replay <file|dir>            deterministic protocol-replay of a cassette or a dir of them (no token)
       [--cassette <file>]      explicit single-cassette form   [--strict] [--output-format json]
   lint <scenario.yaml>…        check scenarios for silent false-greens (bundled scenario.py; needs python3 + PyYAML)
       [--strict]               escalate a cassette-staleness warning (baseline/skill drift) to a failure
   verify-cassettes <file|dir>  CI gate (no token): privacy scan + staleness — exit 1 on a PII finding or drift
-      [--privacy-only|--staleness-only] [--allow <regex>]... [--output-format json]
+      [--privacy-only|--staleness-only] [--allow <regex>]... [--allow-domain/-email <regex>]... [--allow-file <path>]... [--output-format json]
+  verify-run <run-dir> <scenario.yaml>   re-evaluate a scenario's assert: against a kept run dir (no live agent)
+      [--output-format json]   (fast assert iteration: fix an assertion + re-check in ~1s instead of a full re-record)
   trace <run-id | dir | path>  digest a run's events.jsonl (tools+result status, dispatches, decisions)
       [--tools]  tool/dispatch rows only   [--gates]  gate lifecycle (question→answer→delivered)
       [--dispatches]  sub-agent dispatch tree + the real total (read off dispatch_count_max)
@@ -76,6 +81,7 @@ const HELP = `cowork-harness <command>   (v${"$VERSION"})
   list                         list available platform baselines
   boundary-check [baseline]    prove the sandbox enforces Cowork's limitations
   vm <init|status|delete|prune>  manage the L2 Apple-VZ microVM (fidelity: microvm); prune drops orphaned VMs
+  doctor [--tier <tier>]       read-only prerequisite check (Docker, staged agent, token, baseline)
 
   Global:  --dotenv <path>     load a .env before the command (host-side creds; never mounted).
            Auth resolves from process.env > --dotenv > ./.env > <install>/.env.
@@ -185,6 +191,29 @@ function printHelp() {
 function hasHelp(args) {
     return args.includes("--help") || args.includes("-h");
 }
+// F-7: per-subcommand `--help`. `run`/`skill` already print their own help via hasHelp(); `lint` delegates
+// to the Python argparse path (which has its own --help). Every OTHER subcommand goes straight to parseArgs,
+// where `--help` was an "unknown flag" error — so you could only discover flags by triggering a bad
+// invocation. Intercept `--help`/`-h` at dispatch and print the command's usage (exit 0). One concise line
+// per command, kept in sync with each command's own bad-invocation `usage:` string.
+const SUBCOMMAND_USAGE = {
+    sync: "usage: sync [--diff]   (re-sync the platform baseline from the installed Cowork app)",
+    list: "usage: list   (list available platform baselines)",
+    "boundary-check": "usage: boundary-check [<baseline>] [--session <file>]",
+    vm: "usage: vm <init|status|delete|prune>",
+    chat: "usage: chat <skill-folder> [--raw] [--fidelity container|hostloop] [--model <id>]",
+    record: "usage: record <scenario.yaml | dir/> [--out <file>] [--output-format text|json] [--rerecord-stale] [--no-redact] [--allow-failing] [--max-artifact-bytes <n>]",
+    replay: "usage: replay <file.cassette.json | dir/> [--cassette <file>] [--strict] [--output-format text|json]",
+    "verify-cassettes": "usage: verify-cassettes <file|dir> [--privacy-only|--staleness-only] [--allow <regex>]... [--allow-domain <regex>]... [--allow-email <regex>]... [--allow-file <path>]... [--output-format json]",
+    trace: "usage: trace <run-id | run-dir | events.jsonl> [--tools | --gates | --dispatches] [--output-format json]",
+    assert: "usage: assert --list [--output-format json]",
+    scaffold: "usage: scaffold --from-run <run-id | run-dir> [--out <file.yaml>]",
+    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]",
+    answer: 'usage: answer <dir> --gate <N> (--choose <label> | --answer "<q>=<label>")',
+    "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)",
+    doctor: "usage: doctor [--tier protocol|container|microvm|hostloop|cowork] [--output-format json]   (read-only prerequisite check)",
+};
 async function main() {
     const argv = process.argv.slice(2);
     // `--dotenv <path>` is a GLOBAL flag — parse + strip it before command dispatch so a skill run from
@@ -218,6 +247,7 @@ async function main() {
             "record",
             "replay",
             "verify-cassettes",
+            "verify-run",
             "trace",
             "assert",
             "scaffold",
@@ -229,6 +259,7 @@ async function main() {
             "boundary-check",
             "vm",
             "lint",
+            "doctor",
         ];
         // The command-name footgun only applies to the space form (the equals form can't swallow the next
         // token as its value), but checking both is harmless and keeps the guard uniform.
@@ -264,6 +295,10 @@ async function main() {
         return void out(pkgVersion());
     if (cmd === undefined || cmd === "--help" || cmd === "-h" || cmd === "help")
         return printHelp();
+    // F-7: per-subcommand --help for the parseArgs-direct commands (run/skill/lint self-handle, so they're
+    // absent from the map and fall through to their own handling).
+    if (hasHelp(rest) && cmd in SUBCOMMAND_USAGE)
+        return void log(SUBCOMMAND_USAGE[cmd]);
     switch (cmd) {
         case "run":
             return cmdRun(rest);
@@ -271,6 +306,8 @@ async function main() {
             return cmdSync(rest);
         case "list":
             return cmdList();
+        case "doctor":
+            return cmdDoctor(rest);
         case "boundary-check":
             return cmdBoundary(rest);
         case "vm":
@@ -287,6 +324,8 @@ async function main() {
             return cmdLint(rest);
         case "verify-cassettes":
             return cmdVerifyCassettes(rest);
+        case "verify-run":
+            return cmdVerifyRun(rest);
         case "trace":
             return cmdTrace(rest);
         case "assert":
@@ -984,6 +1023,14 @@ function cmdSync(args) {
         mkdirSync(BASELINES_DIR, { recursive: true });
         writeFileSync(baselinePath, JSON.stringify(next, null, 2));
         log(`wrote ${baselinePath}`);
+        // F-3: the host-loop prompt asset is hand-authored (not extracted), so a new baseline silently lands
+        // WITHOUT it — and every host-loop record then runs with an EMPTY shell-access section. Warn loudly here,
+        // tying the missing asset to the baseline just synced (mirrors the agentBinary.stagedPath warn above).
+        const hostLoopAsset = join(BASELINES_DIR, "prompts", `desktop-${res.appVersion}`, "host-loop-append.md");
+        if (!existsSync(hostLoopAsset)) {
+            log(`WARNING: host-loop prompt asset missing for the synced baseline: ${hostLoopAsset} — host-loop records will run with an EMPTY shell-access section. ` +
+                `Author it (carry forward baselines/prompts/desktop-1.12603.1/host-loop-append.md and verify against the desktop-${res.appVersion} asar).`);
+        }
     }
 }
 function cmdList() {
@@ -1241,6 +1288,145 @@ function cmdScaffold(args) {
     else
         out(yaml);
 }
+/** Read the persisted transcript from a kept run's `run.jsonl` (the `{t:"transcript"}` line). */
+function readTranscriptSidecar(file) {
+    try {
+        for (const line of readFileSync(file, "utf8").split("\n")) {
+            if (!line.trim())
+                continue;
+            const o = JSON.parse(line);
+            if (o && o.t === "transcript")
+                return String(o.text ?? "");
+        }
+    }
+    catch {
+        /* sidecar absent/unreadable — empty transcript (content asserts over it simply won't match) */
+    }
+    return "";
+}
+/** Read the AskUserQuestion question texts from a kept run's `trace.json` (`questions` array). */
+function readQuestionsSidecar(file) {
+    try {
+        const t = JSON.parse(readFileSync(file, "utf8"));
+        if (Array.isArray(t.questions))
+            return t.questions.map(String);
+    }
+    catch {
+        /* sidecar absent/unreadable */
+    }
+    return [];
+}
+/**
+ * F-1: `verify-run <run-dir> <scenario.yaml>` — re-evaluate a scenario's `assert:` block against an
+ * already-kept run dir, WITHOUT a live agent (no tokens, no Docker). Fixing a wrong assertion was previously
+ * a full live re-record (~17 min); this turns it into ~1s. Reconstructs the AssertContext from the run dir's
+ * persisted `result.json` + the `run.jsonl`/`trace.json` sidecars (transcript + questions live there, not in
+ * result.json), reproduces the `expect_denied` expansion that `evaluate()` doesn't do, and routes the verdict
+ * through the same `computeVerdict(…, "live")` as a real record.
+ *
+ * Limits (vs a fresh live record): sidecars are SCRUBBED at record time, so an assertion over a redacted
+ * secret value is not faithfully re-checkable; and filesystem assertions (`file_exists`/`artifact_json`/
+ * `user_visible_artifact`) need the run's `workDir` to still exist on disk — if it's gone (container/microvm
+ * teardown), verify-run refuses rather than false-failing them.
+ */
+function cmdVerifyRun(args) {
+    let p;
+    try {
+        p = parseArgs(args, { values: ["--output-format"], enums: { "--output-format": ["text", "json"] } });
+    }
+    catch (e) {
+        log(e.message);
+        return process.exit(2);
+    }
+    const json = p.options["--output-format"] === "json";
+    const [runDir, scenarioFile] = p.positionals;
+    if (!runDir || !scenarioFile) {
+        log("usage: verify-run <run-dir> <scenario.yaml> [--output-format json]");
+        return process.exit(2);
+    }
+    if (p.positionals.length > 2) {
+        log(`verify-run takes <run-dir> <scenario.yaml> (got ${p.positionals.length}: ${p.positionals.join(", ")})`);
+        return process.exit(2);
+    }
+    const resultPath = join(runDir, "result.json");
+    if (!existsSync(resultPath)) {
+        log(`verify-run: no result.json under ${runDir} (is this a kept run dir? e.g. runs/<scenario>/<sessionId>/)`);
+        return process.exit(2);
+    }
+    let result;
+    try {
+        result = JSON.parse(readFileSync(resultPath, "utf8"));
+    }
+    catch (e) {
+        log(`verify-run: cannot read ${resultPath}: ${e.message}`);
+        return process.exit(2);
+    }
+    let scenario;
+    try {
+        scenario = parseScenarioFile(scenarioFile);
+    }
+    catch (e) {
+        log(`verify-run: cannot load scenario ${scenarioFile}: ${e.message}`);
+        return process.exit(2);
+    }
+    const workRoot = result.workDir ?? "";
+    const scan = result.scan ?? { outputsDeletes: [], hostPathLeaked: false, selfHealRan: false };
+    // FS-class assertions resolve under workRoot; if it's gone we can't faithfully re-check them — refuse
+    // rather than report a false fail. Content-only re-asserts stay valid without it.
+    const FS_KEYS = ["file_exists", "user_visible_artifact", "artifact_json"];
+    const hasFsAssert = scenario.assert.some((a) => FS_KEYS.some((k) => a[k] !== undefined));
+    if (hasFsAssert && !existsSync(workRoot)) {
+        log(`verify-run: work dir not found (${workRoot || "<unset>"}) — filesystem assertions ` +
+            `(file_exists/artifact_json/user_visible_artifact) cannot be re-evaluated from this run dir; re-record. (can't verify ⇒ not green)`);
+        return process.exit(2);
+    }
+    const ctx = {
+        transcript: readTranscriptSidecar(join(runDir, "run.jsonl")),
+        toolsCalled: new Set(Object.keys(result.toolCounts ?? {})),
+        subagentTools: new Set((result.subagents ?? []).flatMap((s) => s.toolsUsed ?? [])),
+        egress: result.egress ?? [],
+        result: result.result === "error" ? "error" : "success",
+        workRoot,
+        userVisiblePrefixes: ["outputs", ".projects"],
+        outputsDeletes: scan.outputsDeletes,
+        questions: readQuestionsSidecar(join(runDir, "trace.json")),
+        hostPathLeaked: scan.hostPathLeaked,
+        selfHealRan: scan.selfHealRan,
+        subagents: result.subagents ?? [],
+        gateDeliveries: result.gateDeliveries ?? [],
+    };
+    const assertions = evaluate(scenario.assert, ctx);
+    // Reproduce execute.ts's expect_denied → egress_denied expansion (evaluate() does not handle it).
+    for (const host of scenario.expect_denied) {
+        assertions.push({
+            assertion: { egress_denied: host },
+            pass: ctx.egress.some((e) => hostMatches(e.host, host) && e.decision === "deny"),
+            message: `expected ${host} to be denied`,
+        });
+    }
+    // Verdict via the SAME path as a live record (the run dir is a live run, so the "live" lane honors the
+    // scan/parity signals already persisted in result.json).
+    const verdict = computeVerdict({ ...result, assertions }, "live");
+    const failed = assertions.filter((a) => !a.pass);
+    if (json) {
+        out(JSON.stringify({
+            command: "verify-run",
+            pass: verdict.pass,
+            assertions: assertions.map((a) => ({ assertion: a.assertion, pass: a.pass, message: a.message })),
+            signals: verdict.signals,
+        }));
+    }
+    else {
+        for (const a of assertions)
+            log(`${a.pass ? "✓" : "✗"} ${Object.keys(a.assertion).join("+") || "(assertion)"}${a.message ? ` — ${a.message}` : ""}`);
+        for (const s of verdict.signals.filter((s) => s.code !== "assertion"))
+            log(`${s.severity === "fail" ? "✗" : "·"} ${s.code}: ${s.message}`);
+        log(verdict.pass
+            ? `✓ verify-run: all ${assertions.length} assertion(s) pass (no live agent)`
+            : `✗ verify-run: ${failed.length}/${assertions.length} assertion(s) failed`);
+    }
+    return process.exit(verdict.exitCode);
+}
 /** `assert --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) {