cowork-harness 1.0.6 → 1.1.0

package/.claude/skills/cowork-harness/SKILL.md

@@ -3,8 +3,8 @@ name: cowork-harness
 description: Test or debug a Claude Code skill/plugin under Claude Cowork's runtime — sandboxed agent, default-deny egress, the can_use_tool permission/question protocol — using the cowork-harness CLI. Use when validating or regression-testing a skill, authoring or debugging a scenario YAML (prompt + scripted answers + assert:), choosing a fidelity tier, scripting AskUserQuestion / tool-permission answers, or asserting artifacts, egress, or sub-agent dispatch. Especially when a harness run no-ops an assertion, fails on an unanswered gate, false-greens, a steered answer never reaches the model, or a web_fetch is unexpectedly denied or gated. NOT for generic unit testing (pytest/vitest of your own scripts) or non-Cowork CI. Covers the skill / run / chat / record / replay / trace / decide / assertions / scaffold commands and the session-vs-scenario split.
 metadata:
   author: cowork-harness
-  version: 1.0.6
-  tracks-harness: cowork-harness 1.0.6 (baseline desktop-1.21459.0)
+  version: 1.1.0
+  tracks-harness: cowork-harness 1.1.0 (baseline desktop-1.21459.0)
 ---
 
 # cowork-harness
@@ -22,7 +22,7 @@ flagged with a loud `::warning::`, not silent — auto-answer a gate, observe an
 allowlist). This skill exists mostly to keep you out of those traps — the Gotchas section below is
 the highest-value part. Read it.
 
-> **Version note:** the facts and `file:line` pointers here track `cowork-harness 1.0.6` (baseline
+> **Version note:** the facts and `file:line` pointers here track `cowork-harness 1.1.0` (baseline
 > `desktop-1.21459.0`). If your checkout is newer, prefer the live `--help` and — in a repo checkout —
 > `SPEC.md` / `docs/*.md` over this snapshot, and re-run the bundled linter.
 
@@ -39,9 +39,9 @@ Before the first command, confirm the CLI is reachable and **fail loud** (never
 
 - **One-shot check.** Run `cowork-harness doctor [--tier <tier>]` first — a read-only prerequisite check that inspects Docker, the staged agent, the token, and the baseline in one pass. The bullets below explain each thing it checks (and how to fix it).
 - **Replay-only? Skip `doctor`.** Replaying committed cassettes needs no Docker, no staged agent, and no token — and every tier's `doctor` validates the auth token (the live tiers also Docker + the staged agent), so a ✗ there is expected, not a blocker. Go straight to `cowork-harness replay <cassette>`.
-- **CLI on PATH, recent enough?** Run `cowork-harness --version` — this skill needs **≥ 1.0.6**. If it's missing or older, prefix every command with the version floor `npx "cowork-harness@>=1.0.6" <cmd>` (Node ≥ 20), or install once with `npm i -g "cowork-harness@>=1.0.6"`. **Pin `@>=1.0.6`, never `@latest`** — `@latest` can silently fetch an older CLI and the new commands fail as "unknown command", whereas the floor **fails loud** if no compatible version is published.
+- **CLI on PATH, recent enough?** Run `cowork-harness --version` — this skill needs **≥ 1.1.0**. If it's missing or older, prefix every command with the version floor `npx "cowork-harness@>=1.1.0" <cmd>` (Node ≥ 20), or install once with `npm i -g "cowork-harness@>=1.1.0"`. **Pin `@>=1.1.0`, never `@latest`** — `@latest` can silently fetch an older CLI and the new commands fail as "unknown command", whereas the floor **fails loud** if no compatible version is published.
 
-  What the ≥ 1.0.6 floor gates, by release:
+  What the ≥ 1.1.0 floor gates, by release:
 
   - **core set (pre-0.21.0 vintage, or mixed):** `assertions --list`, `scaffold <run-id>`, `trace --view dispatches`, `artifact_json` incl. the `in:` operator (passes when the resolved value deep-equals one of the listed members — value ∈ your list, not the reverse), `verify-cassettes` incl. the `--allow-domain`/`--allow-email`/`--allow-patterns-file` allows (`--allow-patterns-file <path>` is a FILE of patterns, one regex per line — not a path to allow, unlike `--allow <regex>`), batch `record <dir>`/`--rerecord-stale`, `record --concurrency <N>`, record-time redaction, multiSelect/`answer:`, `verify-run` answer-coverage, `record --max-artifact-bytes`, live record-time deciders, scenario `skills:` staleness scoping with `COWORK_HARNESS_AGENT_SCOPE=skill`, `chat --plugin`, and `/help` in the REPL.
   - **0.21.0:** `verify-cassettes --allow-path` (`path` — local absolute filesystem paths — is the scanner's 4th class), and `hostloop`'s native host/VM process split with its `allow_host_writes:` consent field.
@@ -52,6 +52,7 @@ Before the first command, confirm the CLI is reachable and **fail loud** (never
   - **0.32.0:** `analyze-skill`'s directory scan now covering a skill/plugin's full contract surface (recursive `agents/`/`references/`/`commands/`, plugin-root-aware, symlink-following) with line/block-scoped `analyze-skill: ignore-next-line`/`ignore-start`/`ignore-end` markers and multi-path/glob input, and `lint-skill`'s provable in-plugin `subagent_type` typo now a WARN that gates under `--strict`.
   - **0.33.0:** the `redacted` marker on display-omitted reasoning — `subagents[].reasoning` and the top-level `thinking[]` now carry `{text:"", redacted:true}` when the model returns a signed-but-empty thought (so "reasoned, text omitted" is distinct from "no thought"), plus the fenced `debug.thinking_display` escape hatch.
   - **1.0.0:** first stable release — the SPEC §12 compatibility contract takes effect (covered CLI/schema/env/Action surfaces are now stable; breaking changes need a major bump). No new author-facing command; the floor simply tracks the 1.0 release.
+  - **1.1.0:** `analyze-skill` now also flags **interactive-artifact write-backs lost under Cowork** — a relative `fetch`/XHR/`sendBeacon`/`<form method=post>` in an emitted `.html` (or its `.py`/`.js` generator) that silently fails when the artifact is served from Cowork's own origin. `artifact-write-back-lost` gates under `--strict`; `artifact-write-back-suspect` is advisory; an unanalyzable candidate is a could-not-verify exit 3. An optional **`analyze-skill --runtime`** drives the artifact in a headless DOM (needs `jsdom`) to *observe* the lost write-back — enrichment only, never changes the exit code. Plus a `lint` check for a container-only assertion key (`no_scratchpad_leak`/`present_files_called`) used off the `container` tier, and the `doctor --output-format json` envelope frozen as a covered SPEC §12 surface (`schema/doctor.json`).
 - **Agent binary (sandboxed live tiers — `container`/`microvm`/`hostloop`/`cowork`).** The staged Claude Code agent is **bind-mounted** from a local Claude Desktop install, or point `COWORK_AGENT_BINARY` at a `claude-code-vm/<ver>/claude` ELF. Nothing is bundled. `protocol` (L0) and `replay` need no staged agent; for the sandboxed tiers, no agent → no run; report that, don't skip silently.
 - **Docker / Lima.** Only `--fidelity protocol` (L0) runs without them. `container` / `microvm` / `hostloop` / `cowork` need Docker (Lima for L2). If they're absent, drop to `--fidelity protocol` and **say so** — a green that never exercised the sandbox is not a sandbox pass.
 - **Auth.** `CLAUDE_CODE_OAUTH_TOKEN` (preferred), or `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN`, via env or `.env`. Minting an OAuth token needs the **`claude` CLI** (`npm i -g @anthropic-ai/claude-code`, then `claude setup-token`).
@@ -277,7 +278,8 @@ quoting, an egress assert on `protocol` fidelity, `transcript_no_host_path` on `
 (ERROR — fails by design at those tiers; WARN on `fidelity: cowork`, whose tier resolves per the
 baseline's host-loop gate), non-empty `requires_capabilities` on `protocol` without
 `allow_missing_capability` (ERROR — the capability probe can't run there, so the run hard-fails as
-unverifiable), a `controlOut`-gated key on a non-`controlOut` replay, mixed-class assertion items,
+unverifiable), a container-only assertion key (`no_scratchpad_leak`/`present_files_called`) off the
+`container` tier (ERROR on `protocol`/`microvm`/`hostloop`, WARN on `cowork`), a `controlOut`-gated key on a non-`controlOut` replay, mixed-class assertion items,
 and hallucinated schema (`assertions:` vs `assert:`, unknown keys). Exit code is non-zero on errors
 (CI-friendly). `scaffold` auto-upgrades the tier if you ask for egress on `protocol`, so it never
 emits a scenario `lint` would reject.

package/.claude/skills/cowork-harness/references/ci-recipe.md

@@ -1,6 +1,6 @@
 # CI recipe — replay vs live lanes
 
-Self-contained reference. Tracks `cowork-harness 1.0.6` (baseline `desktop-1.20186.1`).
+Self-contained reference. Tracks `cowork-harness 1.1.0` (baseline `desktop-1.20186.1`).
 
 **Fastest path: the packaged Action.** One step gets you `replay`/`lint`/`verify-cassettes` plus a PR
 job-summary reporter (verdict table, staleness findings, cost/turns when available):
@@ -13,7 +13,7 @@ job-summary reporter (verdict table, staleness findings, cost/turns when availab
 ```
 
 The Action's `version` input defaults to `latest` — intentional so a copy-pasted recipe tracks the current
-release; pin an exact version (e.g. `version: "1.0.6"`) for reproducible CI.
+release; pin an exact version (e.g. `version: "1.1.0"`) for reproducible CI.
 
 Reach for the manual multi-step form below only when you need per-step control the Action's inputs don't
 cover (a custom flag combination, a different runner matrix per step, or `lint`/`verify-cassettes` gated
@@ -57,7 +57,7 @@ sha256-*checked* but not hard-blocking on mismatch — it's advisory for an inte
 GitHub-hosted runners, no token/Docker/agent:
 
 ```yaml
-- run: npm i -g "cowork-harness@>=1.0.6"
+- run: npm i -g "cowork-harness@>=1.1.0"
 - run: cowork-harness lint scenarios/*.yaml          # no silent false-greens
 - run: cowork-harness verify-cassettes cassettes/    # privacy + staleness
 - run: cowork-harness replay cassettes/              # token-free content/structure
@@ -197,7 +197,7 @@ jobs:
         with: { node-version: '20' }
       - uses: actions/setup-python@v5
         with: { python-version: '3.x' }                                       # python3 only — PyYAML is bundled with the linter
-      - run: npm i -g "cowork-harness@>=1.0.6"
+      - run: npm i -g "cowork-harness@>=1.1.0"
       - run: cowork-harness lint scenarios/*.yaml                              # no-silent-false-green (needs python3; PyYAML bundled)
       - run: cowork-harness verify-cassettes cassettes/ --output-format json   # privacy + staleness gate
       - run: cowork-harness replay cassettes/ --output-format json             # token-free content/structure
@@ -226,7 +226,7 @@ jobs:
             echo "live=true" >> "$GITHUB_OUTPUT"
           fi
       - if: steps.guard.outputs.live == 'true'
-        run: npm i -g "cowork-harness@>=1.0.6"
+        run: npm i -g "cowork-harness@>=1.1.0"
       - if: steps.guard.outputs.live == 'true'
         run: cowork-harness run scenarios/ --output-format json
         env:

package/.claude/skills/cowork-harness/references/fidelity-and-answers.md

@@ -1,6 +1,6 @@
 # Fidelity tiers & answer paths
 
-Self-contained reference. Tracks `cowork-harness 1.0.6` (baseline `desktop-1.20186.1`).
+Self-contained reference. Tracks `cowork-harness 1.1.0` (baseline `desktop-1.20186.1`).
 
 ## Fidelity tiers (`fidelity:` in the scenario)
 
@@ -171,6 +171,36 @@ writes a `result.json` (marked `partial: true`) with the artifacts the agent pro
 the work isn't discarded — then exits 2. Inspect it with `cowork-harness inspect <run-dir>`. `verify-run`
 and `scaffold` refuse to treat a partial run's half-finished output as a passing result.
 
+## What a green does NOT prove
+
+A passing run is evidence for exactly what it checked, not a blanket certificate. Three gaps come
+up often enough to spell out:
+
+- **A green `replay` proves "same as when recorded," not "correct today."** `replay` never touches
+  a filesystem or network — it re-evaluates assertions from the frozen cassette. A fixed set of
+  keys is live-only and **skipped outright** on replay (absent from `assertions[]`, not vacuously
+  passed): `no_delete_in_outputs`, `self_heal_ran`, `transcript_no_host_path`, `egress_denied`,
+  `egress_allowed`, `no_mcp_error`, `max_peak_rss_bytes`, `semantic_matches`, and `expect_denied`.
+  Everything else that *is* evaluated is checked against the **recording**, not fresh behavior — a
+  green replay says the skill produced these events when it was recorded, not that it still does
+  (`staleness[]` flags skill/baseline drift as a hint; only a live `run` re-confirms current
+  behavior). See `docs/cassette.md` § "Still skipped on replay" and `docs/scenario.md` § "Which
+  assertions survive replay."
+- **Container-only assertions can't verify off the `container` tier.** `no_scratchpad_leak` and
+  `present_files_called` check the `present_files` delivery path, which is served **only** on
+  `container` — not `hostloop`/`microvm`. Asserting them off-container hard-fails at runtime (a red
+  run, not a false green), so you won't be fooled if you write the assertion. The quieter trap is a
+  scenario that runs at `hostloop`/`microvm`/`protocol` and simply omits these assertions: a green
+  run there proves **nothing** about scratchpad-leak safety or present_files delivery, because that
+  tier never exercises the delivery path the assertions would check. Use `fidelity: container` for
+  present_files/scratchpad-delivery coverage.
+- **The harness doesn't observe rendered-artifact interactions, browser downloads, or human
+  clicks.** It runs the agent headless — no webview, no browser, no person clicking "Submit." A
+  class of Cowork bug (a client-side write-back to a relative URL that resolves-but-fails against
+  Cowork's own origin, or a broken blob-download fallback) is invisible to any live run, however
+  faithfully sandboxed, because it only manifests in a rendered DOM a human is driving. See
+  `docs/fidelity-gaps.md` § "Browser↔webview↔human-interaction boundary."
+
 ## Relevant environment variables
 
 - `COWORK_HARNESS_RUNS_DIR` (or `--run-dir <path>`) — override the default run-output root `~/.cowork-harness/runs` (out of any working tree). flag > env > default.

package/.claude/skills/cowork-harness/references/scenario-schema.md

@@ -1,6 +1,6 @@
 # Scenario & session schema, assertion catalog, web_fetch, full gotchas
 
-Self-contained reference for authoring `cowork-harness` scenarios. Tracks `cowork-harness 1.0.6`
+Self-contained reference for authoring `cowork-harness` scenarios. Tracks `cowork-harness 1.1.0`
 (baseline `desktop-1.20186.1`). If your checkout is newer, prefer the live `docs/scenario.md`,
 `docs/session.md`, and `SPEC.md`.
 

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

@@ -17,6 +17,8 @@ Two subcommands:
 lint flags (see references/scenario-schema.md for the why of each):
   E  egress assertion on `fidelity: protocol`        (the harness rejects this run)
   E  `transcript_no_host_path` on hostloop/protocol  (fails BY DESIGN at those tiers)
+  E  `no_scratchpad_leak`/`present_files_called` off  (container-only: served only at fidelity:
+     protocol/microvm/hostloop                          container; off-container = cannot-verify)
   E  `requires_capabilities` on `fidelity: protocol` (probe can't run → hard-fails
                                                       unless allow_missing_capability)
   E  on_unanswered: agent / invalid value            (schema rejects `agent`)
@@ -24,6 +26,8 @@ lint flags (see references/scenario-schema.md for the why of each):
   E  `assertions:` instead of `assert:`              (block ignored → every check no-ops)
   W  `transcript_no_host_path` on `fidelity: cowork` (tier resolves per baseline gate —
                                                       incompatible if it lands hostloop)
+  W  `no_scratchpad_leak`/`present_files_called` on   (tier resolves per baseline gate — cannot-verify
+     `fidelity: cowork`                                if it resolves off-container)
   W  no content assertion → no-op on a replay gate    (every assertion is fs/egress)
   W  mixed-class assert item → fs/egress half dropped on replay
   W  unknown top-level / assertion key                (typo or hallucinated schema)
@@ -127,6 +131,10 @@ LIVE_ONLY_KEYS = {
     "semantic_matches",
 }
 EGRESS_KEYS = {"egress_denied", "egress_allowed"}
+# container-only: served only at fidelity: container (present_files / the scratchpad promotion path
+# it depends on). Off-container these report cannot-verify, not a meaningful pass/fail — same tier-fidelity
+# class as transcript_no_host_path below, just the opposite direction (container-only vs container-hostile).
+CONTAINER_ONLY_KEYS = {"no_scratchpad_leak", "present_files_called"}
 # verdict modifiers — don't verify anything themselves (e.g. suppress a default-fail)
 VERDICT_MODIFIER_KEYS = {
     "allow_permissive_auto_allow",
@@ -388,6 +396,41 @@ def lint_doc(doc, path, raw_lines):
                 )
             )
 
+    # E/W: CONTAINER_ONLY_KEYS (no_scratchpad_leak / present_files_called) are served only at
+    # fidelity: container — off-container they report cannot-verify, not a meaningful check. Mirrors
+    # the transcript_no_host_path tier check above, just the opposite direction: ERROR on the tiers
+    # where the runtime deterministically can't serve it, WARN on cowork (baseline-gate-resolution
+    # dependent — the linter stays offline, so the message names the dependency instead of resolving it).
+    container_only_present = sorted(assert_keys & CONTAINER_ONLY_KEYS)
+    if container_only_present:
+        if fidelity in ("protocol", "microvm", "hostloop"):
+            findings.append(
+                Finding(
+                    "ERROR",
+                    "container-only-key-off-container",
+                    f"{container_only_present} on `fidelity: {fidelity}` — container-only (present_files "
+                    "is served only there); off-container it reports cannot-verify. Use fidelity: "
+                    "container for present_files/scratchpad delivery.",
+                    "Use fidelity: container (or drop the assertion for this tier).",
+                    path,
+                )
+            )
+        elif fidelity == "cowork":
+            findings.append(
+                Finding(
+                    "WARN",
+                    "container-only-key-off-container",
+                    f"{container_only_present} on `fidelity: cowork` — container-only (present_files "
+                    "is served only there); off-container it reports cannot-verify. Use fidelity: "
+                    f"container for present_files/scratchpad delivery. (The tier resolves per the "
+                    f"baseline's host-loop gate ({HOST_LOOP_GATE_ID}); if it resolves off-container this "
+                    "assertion cannot verify anything.)",
+                    "Pin fidelity: container if the assertion is load-bearing; keep cowork only if "
+                    "you accept the gate-resolution dependency.",
+                    path,
+                )
+            )
+
     # E: requires_capabilities on protocol — the capability probe cannot run at protocol tier
     # (clause b of the requires_capabilities contract), so the run HARD-FAILS unless an assert item
     # opts out via allow_missing_capability: true. Offline-detectable fails-by-design, same class as

package/CHANGELOG.md

@@ -6,6 +6,34 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [1.1.0] — 2026-07-16
+
+Minor: `analyze-skill` gains interactive-artifact write-back detection (static + an optional `--runtime`
+headless-DOM confirmer), `lint` gains a container-only-key tier check, and the `doctor` JSON envelope is
+frozen as a covered SPEC §12 surface. All additive.
+
+### Added
+
+- **`analyze-skill` now detects interactive-artifact write-backs lost under Cowork.** Alongside the
+  existing `/sessions` path scan, it statically analyzes `.html/.htm/.js/.mjs/.ts/.jsx/.tsx/.py` sources
+  under the target for a relative `fetch`/XHR/`sendBeacon`/`<form method=post>` write-back that silently
+  fails under Cowork (the artifact is served from Cowork's own origin, so a relative write-back resolves
+  non-ok and a page that doesn't check `resp.ok` shows a false "Saved"). Findings: `artifact-write-back-lost`
+  (error — gates under `--strict`), `artifact-write-back-suspect` (advisory), and a separate top-level
+  `analysisFailures` **could-not-verify** channel (a candidate that couldn't be parsed/analyzed) that
+  always exits `3`, `--strict`-independent. A guard that isn't statically provable-truthy is `suspect`,
+  never silently clean; the blanket `analyze-skill: ignore` marker does not silence artifact rules.
+  Each `SkillFinding` now carries a `severity` (`error|advisory`); `--strict` gates on any error finding.
+- **`analyze-skill --runtime`** — an optional headless-DOM confirmation that drives a materialized `.html`
+  artifact in jsdom (stubbed network + synthetic user actions, run twice) to *observe* whether a relative
+  write-back fires and is lost. Enrichment only (never changes the exit code); trusted-source scope. `jsdom`
+  is an optional, dynamically-imported dependency — absent it reports "run `npm i jsdom` to enable".
+- **`schema/doctor.json`** — the `doctor --output-format json` envelope is now a covered SPEC §12 surface
+  (`oneOf` the completed-probe shape and the shared error envelope for every category). `doctor`'s normal
+  JSON output is standardized through the shared envelope frame.
+- **`lint` flags container-only assertion keys off-container** — `no_scratchpad_leak`/`present_files_called`
+  on `fidelity: protocol|microvm|hostloop` is an ERROR, on `fidelity: cowork` a WARN, clean on `container`.
+
 ## [1.0.6] — 2026-07-15
 
 Patch: platform baseline synced to Claude Desktop `1.21459.0`. The spawn contract and rendered system

package/README.md

@@ -91,7 +91,7 @@ node dist/cli.js replay examples/replays/example-pdf-skill.cassette.json
 
 > **Installed globally instead?** Once linked/installed, the same command is `cowork-harness replay
 > <cassette>` — but the relative path above only resolves from a source checkout's `examples/replays/`.
-> From a global install (`npm i -g "cowork-harness@>=1.0.6"`), point at the package root instead:
+> From a global install (`npm i -g "cowork-harness@>=1.1.0"`), point at the package root instead:
 > `cowork-harness replay "$(npm root -g)/cowork-harness/examples/replays/example-pdf-skill.cassette.json"`
 > (or copy the cassette into your own project and pass that path).
 
@@ -101,7 +101,7 @@ Live `run`/`skill` need the prerequisites in the next section — note the `prot
 > - **Replay only (zero setup):** `cowork-harness replay <cassette>` — no token, no Docker, no agent. The command above.
 > - **`protocol` (real model, no Docker):** needs only the auth token (item 3 below).
 > - **Live `container` / `microvm` / `hostloop` / `cowork`:** needs Docker (or Lima for `microvm`), a staged agent, and the token — run `cowork-harness doctor` first.
-> - **Invocation:** from a source checkout, `node dist/cli.js <cmd>` (or `npm link` to get the `cowork-harness` command); from a global install, `cowork-harness <cmd>`; the companion skill falls back to `npx "cowork-harness@>=1.0.6"`.
+> - **Invocation:** from a source checkout, `node dist/cli.js <cmd>` (or `npm link` to get the `cowork-harness` command); from a global install, `cowork-harness <cmd>`; the companion skill falls back to `npx "cowork-harness@>=1.1.0"`.
 
 Two more worked examples worth knowing about: `examples/scenarios/protocol-smoke.yaml` (zero-Docker smoke
 test) and `examples/scenarios/skill-loads.yaml` (container-tier acceptance check) — see
@@ -126,7 +126,7 @@ claude plugin marketplace add yaniv-golan/cowork-harness
 claude 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@>=1.0.6"` (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@>=1.1.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://agentskills.io) spec, so it installs cross-editor (Cursor, Codex, OpenCode, …) via [`npx skills`](https://github.com/vercel-labs/skills) (Vercel Labs' CLI implementation of that spec):
 
@@ -147,7 +147,7 @@ A global install is enough for CI `lint`, reading the teaching skill, and replay
 To `run` the worked examples live or copy them as a starting point, use a source checkout. (The marketplace
 skill install itself only pulls `.claude/skills/cowork-harness/` — SKILL.md + `references/` + `scenario.py`/
 assertion keys, per `.claude-plugin/marketplace.json`'s `source` — not the rest of this table; the full set
-above becomes available once the skill's first command self-bootstraps `npx "cowork-harness@>=1.0.6"` — see
+above becomes available once the skill's first command self-bootstraps `npx "cowork-harness@>=1.1.0"` — see
 [above](#drive-it-from-claude-code-companion-skill) — which pulls the same npm package as the global-install row.)
 
 ### Prerequisites for anything above `protocol` fidelity
@@ -401,7 +401,7 @@ Skill testing is the headline use, but the tool is a general harness over the Co
 | `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); `--json` emits findings as machine-readable JSON instead of the text report | before committing a new scenario or after changing assertions |
 | `lint-skill <SKILL.md \| skill-dir/>…` | Lint a skill body (and any sibling `hooks.json`) for two Cowork host-loop footguns — a `${CLAUDE_PLUGIN_ROOT}` path used in an in-VM bash context, and a hook command that exports an env var or writes into `/tmp` for the in-VM agent — plus static resolution of any pinned `subagent_type` against the enclosing plugin's `agents/*.md` (bundled `scenario.py`; needs python3); the two footguns are WARN-only, and of the three `subagent_type` outcomes, an in-plugin-prefixed agent missing from the enclosing plugin's fully-enumerated `agents/*.md` (`subagent-type-not-found-in-plugin`) is a **provable typo and is WARN too**, while a cross-plugin (`subagent-type-unresolvable`) or unknown-bare (`subagent-type-unknown`) value stays INFO (no built-in agent-type registry to disprove it against) — pass `--strict` (the CI-recommended invocation; plain `lint-skill` is advisory-only) to fail on any WARN, or `--json` for machine-readable findings | authoring or reviewing a skill before a paid Cowork host-loop run exposes the footgun, or before a pinned `subagent_type` typo breaks a `Task` dispatch |
 | `python3 …/scenario.py resolve-agent-types <plugin-dir> [--json]` | Token-free: print a plugin's valid `<plugin>:<agent>` subagent types, resolved from `.claude-plugin/plugin.json` + `agents/*.md` frontmatter (filename-stem fallback when an agent file has no `name:`); the `…` is `.claude/skills/cowork-harness/scripts/` | "does `founder-skills:deck-review` resolve within this plugin?" without a live dispatch |
-| `analyze-skill <SKILL.md \| skill-dir/ \| glob>…` | Token-free ADVISORY scan: flags a `/sessions/...` path handed to a file tool or used as a dispatch/sub-agent output path — that path class is DENIED on host-loop. Accepts multiple positionals (files, dirs, or a simple `*`/`**` glob), walked recursively across a plugin's `SKILL.md`/`agents/`/`references/`/`commands/`. Findings print but exit 0 by default; `--strict` (the CI-recommended invocation) fails on any unsuppressed finding. Three per-file ignore markers (`ignore-next-line`, `ignore-start`/`ignore-end`, file-wide `ignore`) and a `--output-format json` payload are supported — full reference, including the ignore-marker syntax, directory-walk rules, and JSON shape: [docs/subagents.md](./docs/subagents.md#static-path-fidelity-check-analyze-skill) | catching the exact "skill hands `/sessions/...` to a file tool" defect statically, across a whole plugin's contract surface (or several paths/globs in one call), before paying for a live host-loop run to discover it |
+| `analyze-skill <SKILL.md \| skill-dir/ \| glob>…` | Token-free ADVISORY scan: flags a `/sessions/...` path handed to a file tool or used as a dispatch/sub-agent output path — that path class is DENIED on host-loop. Accepts multiple positionals (files, dirs, or a simple `*`/`**` glob), walked recursively across a plugin's `SKILL.md`/`agents/`/`references/`/`commands/`. Findings print but exit 0 by default; `--strict` (the CI-recommended invocation) fails on any unsuppressed finding. Three per-file ignore markers (`ignore-next-line`, `ignore-start`/`ignore-end`, file-wide `ignore`) and a `--output-format json` payload are supported. **It also flags interactive-artifact write-backs lost under Cowork**: it statically analyzes `.html`/`.js`/`.ts`/`.py` sources under the target for a relative `fetch`/XHR/`sendBeacon`/`<form method=post>` write-back that silently fails when the artifact is served from Cowork's own origin (`artifact-write-back-lost` gates under `--strict`; `artifact-write-back-suspect` is advisory; a candidate that can't be parsed is a could-not-verify exit `3`). `--runtime` adds an optional headless-DOM confirmation (needs `jsdom`) that *observes* the lost write-back. Full reference — ignore-marker syntax, directory-walk rules, JSON shape, and the artifact detector: [docs/subagents.md](./docs/subagents.md#static-path-fidelity-check-analyze-skill) | catching the exact "skill hands `/sessions/...` to a file tool" defect — or an artifact whose Submit silently fails under Cowork — statically, before paying for a live run to discover it |
 | `probe-dispatch <skill-dir> "<prompt>"` | Cheap single-dispatch mechanics probe: a THIN wrapper over `skill` (fidelity `container`/`microvm`/`hostloop`, default `hostloop`) that scopes a prompt to trigger ONE `Task` dispatch, then prints just that dispatch's `{resolvedAgentType, pathDenials, delivered}` — no new data model, a pure projection of the same `RunResult` `skill` already produces; `--expect-write <suffix>` narrows `delivered`; "one dispatch" is prompt-scoped, not enforced (`--output-format json` for machine consumption) | "did THIS dispatch resolve to the type I expect, avoid a path denial, and actually deliver its write?" without hand-writing a scenario or reading `trace --view dispatches` |
 | `assertions --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 |
@@ -665,7 +665,7 @@ jobs:
           anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
 ```
 
-Every run writes a Markdown verdict table (scenario, pass/fail, signals, cost/turns when available, staleness findings, and the replay-skipped-assertions honesty line) to the job summary. Inputs: `command`, `path` (required), `version` (npm dist-tag/version, default `latest` — intentional so recipes track the current release; pin an exact version for reproducible CI. The companion skill's `cowork-harness@>=1.0.6` floor guidance applies to ad-hoc CLI installs, not this input), `strict` (applies to `replay` (staleness findings), `lint`/`lint-skill` (WARN/INFO), and `analyze-skill` (any advisory finding); IGNORED — not forwarded — for `verify-cassettes`/`run`, which don't accept the flag), `fail-on-skill-drift` (**`replay`-only** — never forwarded to the analyzers), `extra-args`, `summary` (default `true`), `anthropic-api-key` (live lane only). See [`action.yml`](./action.yml) for the full input reference.
+Every run writes a Markdown verdict table (scenario, pass/fail, signals, cost/turns when available, staleness findings, and the replay-skipped-assertions honesty line) to the job summary. Inputs: `command`, `path` (required), `version` (npm dist-tag/version, default `latest` — intentional so recipes track the current release; pin an exact version for reproducible CI. The companion skill's `cowork-harness@>=1.1.0` floor guidance applies to ad-hoc CLI installs, not this input), `strict` (applies to `replay` (staleness findings), `lint`/`lint-skill` (WARN/INFO), and `analyze-skill` (any advisory finding); IGNORED — not forwarded — for `verify-cassettes`/`run`, which don't accept the flag), `fail-on-skill-drift` (**`replay`-only** — never forwarded to the analyzers), `extra-args`, `summary` (default `true`), `anthropic-api-key` (live lane only). See [`action.yml`](./action.yml) for the full input reference.
 
 The provided [GitHub Actions workflow](.github/workflows/ci.yml) runs a **six-stage pipeline**. The **unit** stage is the token-free gate you can copy into your skill repo; the `action-self-test`, `python`, `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):
 

package/SPEC.md

@@ -674,6 +674,34 @@ already-redacted markers. The TLD list used by the domain scanner was also exten
 entries (CB-5), adding major European, Asian, and Latin American ccTLDs
 (`ch|nl|se|no|it|jp|br|nz|in|sg|kr|mx|es|pt|pl|be|at|dk|fi|ie|ru|cn|tw|hu|cz|ro|il|za|ar|cl|pe|tr`).
 
+### 11.2 `doctor` — dedicated envelope
+
+`doctor [--tier <t>]` is the read-only prerequisite check ("can I run the live tiers — what's
+missing?"). Its `--output-format json` output does **not** reuse the `run/skill/replay` envelope (no
+`RunResult` to judge) — it emits its own, published as **`schema/doctor.json`** (a §12-covered contract
+surface):
+
+```jsonc
+// Completed probe (normal path — routed through the shared jsonPayloadEnvelope, so error is always null):
+{ "tool": "cowork-harness", "version": "...", "command": "doctor",
+  "ok": true,                        // false iff any `required` check has status:"fail" for the selected tier
+  "error": null,
+  "tier": "container",               // protocol|container|microvm|hostloop|cowork
+  "checks": [ { "id": "node", "title": "Node ≥ 20", "status": "ok", "detail": "node 22.x.x",
+                "remedy?": "string", "required": true } ] }  // status: ok|fail|warn|skip
+
+// Shared error envelope (a thrown failure — bad flag, or the top-level catch):
+{ "tool": "cowork-harness", "version": "...", "command": "doctor", "ok": false, "results": [],
+  "error": { "category": "usage|unanswered|boundary|runtime|internal", "message": "string", "hint?": "string" } }
+```
+
+`ok = !checks.some(c => c.required && c.status === "fail")`. **Exit codes:** `0` all required checks
+pass · `1` a required check is `status:"fail"` for the selected tier (the completed-probe shape, still
+`error:null`) · `2` usage (bad `--tier`/unexpected args) or an unexpected internal failure caught by the
+top-level catch (`category:"internal"`). The `checks[].id` set is **not** enumerated as a closed
+contract — it grows as tiers/checks are added, the same way `trace` row shapes are excluded from §12's
+covered list.
+
 ## 12. Versioning & the 1.0 compatibility contract
 
 From `1.0.0` the project follows [semver](https://semver.org/). The surfaces below are the **covered
@@ -698,6 +726,12 @@ Covered-surface changes follow semver as of `1.0.0` — see [RELEASING.md](./REL
   `findings` / `staleness` / `unverifiable` / `notes` / `version` / `error` channels, and the exit-code
   split (`0`/`1`/`2`/`3`, §11) they map to. This is the machine output the CI recipes and the packaged
   Action steer consumers to parse; renaming or removing a key is breaking, adding one is not.
+- **`doctor` envelope** — `schema/doctor.json` under `--output-format json` (§11.2): the completed-probe
+  shape (`tool` / `version` / `command` / `ok` / `error:null` / `tier` / `checks[]`, each check's
+  `id` / `title` / `status` / `detail` / `required` / optional `remedy`) and the shared error-envelope
+  shape (`results:[]` / `error.category`) it falls back to on a thrown failure; renaming or removing a
+  key is breaking, adding one is not. The `checks[].id` set itself is NOT covered — it grows with new
+  tiers/checks.
 - **Cassette format** — the current `cassetteVersion` (**10**, `schema/cassette.v10.json`) and its
   verdict-modifier assertion keys. The minimum supported read version is **v9**
   (`MIN_SUPPORTED_CASSETTE_VERSION`): a cassette below the floor is refused at load time with a

package/dist/cli.js

@@ -406,7 +406,7 @@ const SUBCOMMAND_USAGE = {
     rehash: "usage: rehash <dir/> [--dry-run] [--output-format text|json]   (migrate cassettes across format bumps using contentSig verification; no re-record needed)",
     prune: "usage: prune [--keep-last <n>] [--pinned-older-than <N>d|h|m] [--dry-run] [<runs-dir>]   (prune accumulated run dirs; default --keep-last 5)",
     "init-redact": "usage: init-redact [--force] [--output-format json]   (copy the packaged reference .cowork-redact.json into the cwd; refuses to overwrite an existing one without --force)",
-    "analyze-skill": "usage: analyze-skill <SKILL.md | skill-dir/ | glob>… [--strict] [--output-format text|json]   (ADVISORY token-free scan: flags a /sessions/... path handed to a file tool or dispatch/sub-agent output — denied on host-loop)\n" +
+    "analyze-skill": "usage: analyze-skill <SKILL.md | skill-dir/ | glob>… [--strict] [--runtime] [--output-format text|json]   (ADVISORY token-free scan: flags a /sessions/... path handed to a file tool or dispatch/sub-agent output — denied on host-loop; AND interactive-artifact write-backs that are lost under Cowork)\n" +
         "       reuses the harness's own ported /sessions path-gate predicate (isVmSessionsPath) as the deny decision; only the EXTRACTION from SKILL.md text is heuristic.\n" +
         "       a DIRECTORY target scans the UNION of every contract-bearing markdown file present, not just SKILL.md — a plugin's dispatch/output contracts often live in agents/*.md or references/*.md:\n" +
         "         · top-level SKILL.md present → + top-level references/**/*.md\n" +
@@ -414,10 +414,11 @@ const SUBCOMMAND_USAGE = {
         "         · a skill dir INSIDE a plugin (SKILL.md present, walking up finds an enclosing plugin manifest) → + that plugin's root agents/*.md\n" +
         '       MULTIPLE positionals are accepted (matches lint-skill\'s nargs="+"), each resolved independently (file/dir via the rules above, or a `*`-bearing target via a small hand-rolled glob matcher — `dir/*.md` shallow, `dir/**/*.md` recursive; no dependency, no engines bump).\n' +
         "       every positional's file set is UNIONed and deduped by resolved absolute path across the WHOLE invocation (a file reached both directly and via a dir/glob is analyzed once). ZERO scannable files across ALL positionals is a USAGE ERROR (exit 2), never a silent clean pass; an unresolvable single positional (bad path, unrecognized glob shape) fails the whole invocation the same way.\n" +
-        "       findings are WARNINGS: exit 0 by default even when findings are printed. --strict fails (exit 1) if ANY scanned file (across ALL positionals) has an unsuppressed finding (mirrors lint-skill's --strict). exit 2 = usage error.\n" +
+        "       findings are WARNINGS: exit 0 by default even when findings are printed. --strict fails (exit 1) if ANY scanned file (across ALL positionals) has an unsuppressed error-severity finding (mirrors lint-skill's --strict). exit 2 = usage error. exit 3 = could-not-verify (an artifact candidate that couldn't be parsed/analyzed — always, --strict-independent; a strict error finding's exit 1 takes precedence).\n" +
+        "       interactive-artifact write-backs (Item 1): also scans .html/.js/.ts/.jsx/.tsx/.py sources under the target for a relative fetch/XHR/sendBeacon/<form method=post> write-back that is LOST under Cowork (the artifact is served from Cowork's own origin, so a relative write-back resolves non-ok and a page that doesn't check resp.ok shows a false 'Saved'). Rules: artifact-write-back-lost (error, gates under --strict), artifact-write-back-suspect (advisory), plus a could-not-verify channel. These are NOT silenced by the `analyze-skill: ignore` marker. --runtime adds an OPTIONAL headless-DOM confirmation (needs jsdom, dynamically imported; ENRICHMENT only — never changes the exit code; trusted-source scope).\n" +
         "       plain `analyze-skill` (no --strict) is ADVISORY ONLY — CI should invoke `analyze-skill ... --strict` to actually gate on findings, same as `lint-skill --strict`.\n" +
         "       a line containing `analyze-skill: ignore` (bare, or inside an HTML comment) anywhere in one of the scanned files silences EVERY path-fidelity finding for THAT file — even under --strict, even a genuine true positive (an explicit author override); it does not affect other scanned files.\n" +
-        "       --output-format json emits {tool,version,command,ok,files:[{file,findings,suppressed}],scanned,unscanned,strict,error} — NOT a bare array and NOT results[]; `scanned`/`unscanned` name the files analyzed and any contract dirs left out of scope (printed as a banner in text mode too).\n" +
+        "       --output-format json emits {tool,version,command,ok,files:[{file,findings,suppressed}],scanned,unscanned,analysisFailures,[runtimeConfirmations (only with --runtime)],strict,error} — NOT a bare array and NOT results[]; `scanned`/`unscanned` name the files analyzed and any contract dirs left out of scope (printed as a banner in text mode too); each finding now carries a `severity` (error|advisory).\n" +
         "       a clean/suppressed result is a PRE-FLIGHT signal only — the runtime no_vm_path_file_op / vm_path_denied asserts remain authoritative (see docs/subagents.md).",
 };
 // Known subcommands — used by the global value-flag parsers (`--dotenv`, `--run-dir`) to reject a command