cowork-harness 0.30.0 → 0.31.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: 0.30.0
-  tracks-harness: cowork-harness 0.30.0 (baseline desktop-1.20186.1)
+  version: 0.31.0
+  tracks-harness: cowork-harness 0.31.0 (baseline desktop-1.20186.1)
 ---
 
 # cowork-harness
@@ -22,8 +22,8 @@ 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 0.30.0` (baseline
-> `desktop-1.20186.0`). If your checkout is newer, prefer the live `--help` and — in a repo checkout —
+> **Version note:** the facts and `file:line` pointers here track `cowork-harness 0.31.0` (baseline
+> `desktop-1.20186.1`). 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.
 
 ## Preflight — make sure the harness can actually run
@@ -38,7 +38,7 @@ cowork-harness skill ./my-skill "do X"      # run the skill once against the sta
 Before the first command, confirm the CLI is reachable and **fail loud** (never fake a pass) when a tier's dependencies are missing:
 
 - **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).
-- **CLI on PATH, recent enough?** Run `cowork-harness --version` — this skill needs **≥ 0.30.0**. If it's missing or older, prefix every command with the version floor `npx "cowork-harness@>=0.30.0" <cmd>` (Node ≥ 20), or install once with `npm i -g "cowork-harness@>=0.30.0"`. **Pin `@>=0.30.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. (≥ 0.30.0 is what gates the commands/assertions this skill teaches: `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`, 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, `verify-cassettes --allow-domain`/`--allow-email`/`--allow-path`/`--allow-patterns-file` (`path` — local absolute filesystem paths — is the scanner's 4th class, new in 0.21.0; `--allow-patterns-file <path>` is a FILE of patterns, one regex per line — not a path to allow, unlike `--allow <regex>`), scenario `skills:` staleness scoping with `COWORK_HARNESS_AGENT_SCOPE=skill`, `chat --plugin`, `/help` in the REPL, `hostloop`'s native host/VM process split with its `allow_host_writes:` consent field, `computer_links_resolve` (new in 0.22.0), `semantic_matches` (an LLM judge grades a fixed `rubric` of claims against the run's answer — **live-only**, so it is evidence-unavailable / skipped-loud on replay, never a vacuous pass; new in 0.27.0), **glob-matched** `tool_called`/`tool_not_called`/`subagent_tool_used`/`subagent_tool_absent` (a pattern like `mcp__workspace__*` matches any tool in the family; exact names match exactly; new in 0.28.0), the five path-gate assertion keys `no_vm_path_file_op`/`vm_path_denied`/`path_denied`/`no_path_denied`/`subagent_file_write`, the session-level `agent_env` knob, and resolved sub-agent identity on dispatch records (`resolvedAgentType`/`resolvedModel`; new in 0.30.0).)
+- **CLI on PATH, recent enough?** Run `cowork-harness --version` — this skill needs **≥ 0.31.0**. If it's missing or older, prefix every command with the version floor `npx "cowork-harness@>=0.31.0" <cmd>` (Node ≥ 20), or install once with `npm i -g "cowork-harness@>=0.31.0"`. **Pin `@>=0.31.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. (≥ 0.31.0 is what gates the commands/assertions this skill teaches: `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`, 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, `verify-cassettes --allow-domain`/`--allow-email`/`--allow-path`/`--allow-patterns-file` (`path` — local absolute filesystem paths — is the scanner's 4th class, new in 0.21.0; `--allow-patterns-file <path>` is a FILE of patterns, one regex per line — not a path to allow, unlike `--allow <regex>`), scenario `skills:` staleness scoping with `COWORK_HARNESS_AGENT_SCOPE=skill`, `chat --plugin`, `/help` in the REPL, `hostloop`'s native host/VM process split with its `allow_host_writes:` consent field, `computer_links_resolve` (new in 0.22.0), `semantic_matches` (an LLM judge grades a fixed `rubric` of claims against the run's answer — **live-only**, so it is evidence-unavailable / skipped-loud on replay, never a vacuous pass; new in 0.27.0), **glob-matched** `tool_called`/`tool_not_called`/`subagent_tool_used`/`subagent_tool_absent` (a pattern like `mcp__workspace__*` matches any tool in the family; exact names match exactly; new in 0.28.0), the five path-gate assertion keys `no_vm_path_file_op`/`vm_path_denied`/`path_denied`/`no_path_denied`/`subagent_file_write`, the session-level `agent_env` knob, and resolved sub-agent identity on dispatch records (`resolvedAgentType`/`resolvedModel`; new in 0.30.0), the `lint-skill` (static host-loop footgun + `subagent_type` resolution linter) / `analyze-skill` (advisory `/sessions`-path static scan, `--strict`, `analyze-skill: ignore` marker) / `probe-dispatch` (single-dispatch mechanics probe) commands, `status --latest-for` (resolve a scenario's newest run dir by run time, not directory mtime), the `subagent_dispatch_healthy` composite assertion, and the persisted `result.json` fields `verdict`, `subagents[].referencesRead`/`subagents[].reasoning`, plus the `toolCounts`/`toolErrors`/`toolDurations` shape distinction (all new in 0.31.0).)
 - **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`, via env or `.env`. Minting an OAuth token needs the **`claude` CLI** (`npm i -g @anthropic-ai/claude-code`, then `claude setup-token`).
@@ -63,13 +63,14 @@ reproducible regression (Part II), and **debug** a run that misbehaved or greene
   the path, `trace <run-id>` finds it). **Localize the failure post-hoc** from that evidence:
   `cowork-harness trace <run-dir>`'s views + the emitted `result.json` to see what the run actually did,
   then `verify-run` to re-check a suspect assertion — all token-free, no Docker, no re-record. This is
-  the loop 0.30.0's observability is built for; the *Triage* and *Inspecting a run's observability
+  the loop 0.31.0's observability is built for; the *Triage* and *Inspecting a run's observability
   output* sections in **Part III — Debug** are the detail (the fuller human-facing map lives in
   `docs/debugging.md` — repo-only, not shipped with the installed skill).
 - **Multi-turn / interactive reproduction** → `cowork-harness chat` (interactive; gates answered at the
   TTY, **not** an asserted test — see *Debugging with `chat`* in **Part III — Debug**).
 
 Full command set: `skill · run · chat · record · replay · verify-cassettes · rehash · prune · lint ·
+lint-skill · analyze-skill · probe-dispatch ·
 verify-run · trace · inspect · diff · stats · decide · gates · answer · scaffold · assertions --list · sync ·
 list · boundary-check · status · vm <init|status|delete|prune> · doctor · init-redact`. Always check `cowork-harness <cmd> --help`.
 
@@ -421,9 +422,10 @@ decide which assertions from *Assertions: two orthogonal axes* are worth adding)
   the current list rather than relying on a fixed enumeration here.
 - **`cowork-harness stats [--metric <m>]`** — aggregate across the run index: `cost`, `duration`,
   `tokens`, `cache-tokens`, `model-cost`, `turns`, `pass-rate`.
-- **`result.json` carries the raw fields** the assertions read: `toolDurations`, `models`, `toolErrors`,
+- **`result.json` carries the raw fields** the assertions read: `verdict`, `toolDurations`, `models`, `toolErrors`,
   `redundantToolCalls`, `modelUsage`, `thinking`, `skillActivity`, `subagents[]` (prompt/`dispatchModel`/
-  `resolvedModel`/output/`attributedSkillId`, `outputTruncated`), `context` (tools/mcpServers/availableSkills), `tasks`,
+  `resolvedModel`/output/`attributedSkillId`, `outputTruncated`, `referencesRead`, `reasoning`/`reasoningElided`),
+  `context` (tools/mcpServers/availableSkills), `tasks`,
   `workspaceFiles`, `presentedFiles`, `hookEvents`, `mcpErrors`, `contextEvents`, `resources`
   (`probeFailures` distinguishes a failed sample from a tier that was never sampleable). Provenance/
   evidence-health fields: `command` (`run`/`skill`/`record`/`chat`/`replay` — finer than `mode`),
@@ -431,8 +433,11 @@ decide which assertions from *Assertions: two orthogonal axes* are worth adding)
   `bySource` histogram), `evidenceErrors` (dropped/malformed telemetry lines per stream, incl.
   `egressParse`), `fingerprint.frozen` (replay only — marks the shown staleness fingerprint as the
   cassette's record-time value, not a fresh recompute), and `assertTextTruncated` (companion to
-  `outputTruncated` on a matched tool result). (Full per-field semantics: the README's "Observability
-  fields" section — repo-only; `schema/run-result.json` is the machine source.)
+  `outputTruncated` on a matched tool result). Three separately-shaped rollups, easy to conflate in a
+  `jq` recipe: `toolCounts` is a flat `{tool: number}` call-count map, `toolErrors` is
+  `{tool: {calls, errors}}`, and `toolDurations` is `{tool: {calls, totalMs, maxMs}}`. (Full per-field
+  semantics: the README's "Observability fields" section — repo-only; `schema/run-result.json` is the
+  machine source.)
 - **Opaque failure?** A failed run also records **`errorSource`** (where the failure originated) and
   **`stderrLogPath`** (the captured agent stderr) — read those and `trace <run-dir>` *before* re-running;
   a re-record rarely tells you more than the captured stderr already does. Also check
@@ -674,8 +679,9 @@ assertion/replay-relevant ones).
 - `references/fidelity-and-answers.md` — fidelity tiers, answer paths, the determinism contract.
 - `references/ci-recipe.md` — the packaged GitHub Action, replay-vs-live lane split, and the four-stage
   GitHub Actions pipeline.
-- `scripts/scenario.py` — `scaffold` a valid scenario skeleton and `lint` scenarios for the
-  no-silent-false-green invariants (both usable as CI steps).
+- `scripts/scenario.py` — `scaffold` a valid scenario skeleton, `lint` scenarios for the
+  no-silent-false-green invariants (both usable as CI steps), and `resolve-agent-types <plugin-dir>`
+  (validates a pinned `subagent_type` against the plugin's own `plugin.json` + `agents/*.md`).
 - Checking a background run's status without `ps aux` — covered in *Checking whether a background run is
   alive* (Part II) above; the fuller recipe is in `docs/run-status.md` (repo-only, not shipped with the
   installed skill).

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 0.30.0` (baseline `desktop-1.20186.0`).
+Self-contained reference. Tracks `cowork-harness 0.31.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):
@@ -54,7 +54,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@>=0.30.0"
+- run: npm i -g "cowork-harness@>=0.31.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
@@ -139,13 +139,19 @@ dollar figures). In a skill repo these cassettes get **committed**. So:
   universal net (container-tier recordings can trip it too).
 - **Always-on scan gate** — `verify-cassettes` flags email / currency / bare-domain / local-path /
   machine-inventory matches it finds in the committed cassettes and **exits non-zero**, so "no leak" is
-  a gate, not discipline.
+  a gate, not discipline. Non-zero is not one thing, though: exit `1` means verification RAN and found a
+  real finding (a PII match, a genuine staleness drift, or scenario-prompt drift); exit `3` means
+  verification could NOT complete (an `unverifiable-*`-class staleness finding, a cassette written by a
+  newer harness than this one understands, or a malformed/unreadable cassette). A plain `|| true` or `[
+  $? -ne 0 ]` tripwire treats both the same — if you need to tell "the gate caught something" apart from
+  "the gate couldn't run", branch on the exit code (or parse `--output-format json`'s per-file
+  `findings`/`staleness` vs `unverifiable`/`version`/`error` buckets).
   Suppress synthetic / public reference names (NVCA, Cooley GO, …) with `--allow <regex>`. (Multi-word
   proper names are NOT a default class — too noisy to gate on; add a pattern via config if your corpus
   needs it.)
 
 ```bash
-cowork-harness verify-cassettes cassettes/                       # privacy scan + staleness, exit 1 on a finding
+cowork-harness verify-cassettes cassettes/                       # privacy scan + staleness — exit 1 = verified & failed, exit 3 = could not verify
 cowork-harness verify-cassettes cassettes/ --allow 'NVCA|Cooley GO|Acme'
 cowork-harness verify-cassettes cassettes/ --skip-privacy        # staleness only (skip the privacy scan); both run by default
 ```
@@ -188,7 +194,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@>=0.30.0"
+      - run: npm i -g "cowork-harness@>=0.31.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
@@ -217,7 +223,7 @@ jobs:
             echo "live=true" >> "$GITHUB_OUTPUT"
           fi
       - if: steps.guard.outputs.live == 'true'
-        run: npm i -g "cowork-harness@>=0.30.0"
+        run: npm i -g "cowork-harness@>=0.31.0"
       - if: steps.guard.outputs.live == 'true'
         run: cowork-harness run scenarios/ --output-format json
         env:
@@ -245,9 +251,12 @@ fails or a run errors, so a plain `cowork-harness run scenarios/` is already CI-
 JSON.
 
 `verify-cassettes` emits its **own** envelope (`{command, ok, coverage, results[]}` with per-file
-`findings`/`staleness`/`notes`/`version`/`error`), published as `schema/verify-cassettes.json` in the
-npm package. Both envelope schemas are covered 1.0 contract surfaces (SPEC §12) — parse the JSON, not
-the human-readable text (which is explicitly NOT stable).
+`findings`/`staleness`/`unverifiable`/`notes`/`version`/`error`), published as
+`schema/verify-cassettes.json` in the npm package. `ok:false` doesn't say *why* — read the buckets, or
+the exit code (`1` = `findings`/`staleness`/`scenarioDrift` populated, a real problem verified & found;
+`3` = `unverifiable`/`version`/`error` populated, verification could not complete; a real finding wins
+`1` if both are present). Both envelope schemas are covered 1.0 contract surfaces (SPEC §12) — parse the
+JSON, not the human-readable text (which is explicitly NOT stable).
 
 A run writes to `~/.cowork-harness/runs/<name>/<sessionId>/` by default — outside any working tree. In CI,
 set `COWORK_HARNESS_RUNS_DIR` (or pass `--run-dir`) to a workspace-relative path (e.g. `runs`) so an
@@ -280,8 +289,11 @@ does **not** imply the recording is still valid. Each replay result carries `sta
 
 (A pre-`effectiveFidelity` cassette with an **explicit** tier is statically knowable — it passes the tier
 check with a non-failing informational note in the `verify-cassettes` envelope's per-file `notes[]`, a
-`·`-prefixed row in text output. On `verify-cassettes` every staleness *finding* above is a hard fail —
-the gate is class-blind; notes never fail it.)
+`·`-prefixed row in text output. On `verify-cassettes` every staleness *finding* above still fails the
+gate (`ok:false`) — but it's no longer class-blind on the EXIT CODE: a `baseline`/`skill`/`shared-root`/
+`format`/`resolved-tier` class lands in the envelope's `staleness[]` (verified & failed — exit `1`),
+while an `unverifiable-*` class lands in `unverifiable[]` (could not verify — exit `3`). Notes never
+fail it either way.)
 
 To gate in CI, pick the severity you want:
 

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

@@ -1,6 +1,6 @@
 # Fidelity tiers & answer paths
 
-Self-contained reference. Tracks `cowork-harness 0.30.0` (baseline `desktop-1.20186.0`).
+Self-contained reference. Tracks `cowork-harness 0.31.0` (baseline `desktop-1.20186.1`).
 
 ## Fidelity tiers (`fidelity:` in the scenario)
 

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

@@ -1,7 +1,7 @@
 # Scenario & session schema, assertion catalog, web_fetch, full gotchas
 
-Self-contained reference for authoring `cowork-harness` scenarios. Tracks `cowork-harness 0.30.0`
-(baseline `desktop-1.20186.0`). If your checkout is newer, prefer the live `docs/scenario.md`,
+Self-contained reference for authoring `cowork-harness` scenarios. Tracks `cowork-harness 0.31.0`
+(baseline `desktop-1.20186.1`). If your checkout is newer, prefer the live `docs/scenario.md`,
 `docs/session.md`, and `SPEC.md`.
 
 **Minimal scenario** — `prompt` is the only required field:
@@ -262,6 +262,7 @@ same set live from the schema.
 | `subagent_tool_absent: <glob>` | no sub-agent used a tool matching this glob (same rejection) |
 | `no_vm_path_file_op: true` | **`fidelity: hostloop` only** — NO gated file tool attempted a `/sessions`(-prefixed) path (`RunResult.fileToolAttempts`) — content-class, replay-checkable without `controlOut`; any other tier FAILS "cannot verify" (`/sessions/...` is valid there). **Only `true` is valid** |
 | `subagent_file_write: {path?, path_suffix?, tool?}` | a sub-agent-origin write attempt whose raw path equals `path` (exact) or ends with `path_suffix` has a paired non-error tool_result — the causal half of a delivery probe; requires one of `path`/`path_suffix`; `tool` defaults to Write/Edit/MultiEdit; content-class; tier-agnostic |
+| `subagent_dispatch_healthy: {type?, delivered?, path?, path_suffix?, no_vm_paths?}` | **`fidelity: hostloop` only** — composite: selects dispatch(es) via `type` (same matching as `subagent_dispatched`; omit to require every dispatch) and, for EACH selected dispatch, checks it (not just any sub-agent) delivered a paired non-error write (`delivered`, default true — narrowed by `path`/`path_suffix`, same exact-vs-suffix precedence as `subagent_file_write`) and made no `/sessions` VM-path attempt (`no_vm_paths`, default true) — both scoped to that dispatch's OWN `parentToolUseId`, the per-dispatch correlation `subagent_file_write` (which matches ANY sub-agent write) cannot express; a `type` that matches no dispatch FAILS; content-class (`RunResult.fileToolAttempts` + `RunResult.toolResults`); any non-hostloop tier FAILS "cannot verify" |
 | `subagent_dispatched: <regex>` | a sub-agent whose `dispatchAgentType`, binary-*resolved* `resolvedAgentType`, **or dispatch description** matches |
 | `subagent_declared_but_unused: <Tool>` | a sub-agent declared the tool but never used **that** tool (even if it used others) |
 | `subagent_output_contains: {match?, contains}` | a dispatched sub-agent's own output contains the substring `contains` — `match` (optional regex over `dispatchAgentType`/`resolvedAgentType`/`description`) narrows to specific dispatch(es); omitted, checks whether ANY dispatch's output contains it (existence check, not "all"); a miss against an output that was **truncated at the assert cap** reports evidence-unavailable instead of a proven absence — the substring could lie past the cut |

package/.claude/skills/cowork-harness/references/task-recipes.md

@@ -2,7 +2,7 @@
 
 Each recipe composes facts that live scattered across SKILL.md and the other references into one
 decision path. Every one answers a question a real fleet owner had to work out the hard way. Facts track the harness version in SKILL.md's
-front-matter (currently 0.29.0). Recipe 2's `resolved-tier`/`unverifiable-tier` staleness classes and
+front-matter (currently 0.31.0). Recipe 2's `resolved-tier`/`unverifiable-tier` staleness classes and
 Recipe 3's `init-redact` shipped in 0.24.0 and are part of the current feature set — no version gate
 needed if your CLI meets SKILL.md's version floor.
 

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

@@ -45,6 +45,7 @@
     "skill_tool_used",
     "skill_triggered",
     "subagent_declared_but_unused",
+    "subagent_dispatch_healthy",
     "subagent_dispatched",
     "subagent_file_write",
     "subagent_output_contains",

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

@@ -39,6 +39,7 @@ system PyYAML is preferred when present.
 from __future__ import annotations
 
 import argparse
+import functools
 import json
 import re
 import sys
@@ -66,6 +67,7 @@ CONTENT_KEYS = {
     "subagent_output_contains",
     "no_vm_path_file_op",
     "subagent_file_write",
+    "subagent_dispatch_healthy",
     "dispatch_count_max",
     "skill_triggered",
     "no_skill_triggered",
@@ -741,6 +743,53 @@ def _finding_plugin_root_guarded(path, line, ctx_label):
     )
 
 
+# A self-heal `find`'s `-path '<glob>'` / `-path "<glob>"` value (same-quote char, non-greedy so a
+# quote inside the glob — unlikely in practice — doesn't get swallowed).
+_FIND_PATH_VALUE = re.compile(r"""-path\s+(['"])(.*?)\1""")
+# The skill segment out of a `*/skills/<name>/...` glob.
+_FIND_PATH_SKILLS_SEG = re.compile(r"/skills/([A-Za-z0-9_.-]+)/")
+# The plugin segment out of a `*/plugins/<name>/...` glob.
+_FIND_PATH_PLUGINS_SEG = re.compile(r"/plugins/([A-Za-z0-9_.-]+)/")
+# A generic `*/<name>/scripts` glob (no `skills/`/`plugins/` literal prefix) — the segment right
+# before a `/scripts` path component. This is what a plugin-level self-heal targeting its own
+# `<plugin>/scripts/...` layout looks like once the real mount path (e.g. `mnt/.local-plugins/...`)
+# is glob-abbreviated to `*/<plugin>/scripts`.
+_FIND_PATH_SCRIPTS_SEG = re.compile(r"/([A-Za-z0-9_.-]+)/scripts\b")
+
+
+def _extract_find_path_token(find_cmd_line):
+    """Pull the skill/plugin-naming token out of a self-heal `find`'s `-path` glob (on the SAME
+    line as the `find`, matching how `_SELF_HEAL` itself is line-scoped), or None if there's no
+    `-path` clause or none of the recognized glob shapes match. A bare glob wildcard segment (e.g.
+    `*/scripts/*`, no name between the slashes) intentionally does not match the `[A-Za-z0-9_.-]+`
+    character class — that's a real absence of an extractable token, not a token, so it stays
+    conservative (INFO) rather than manufacturing a bogus `*` token to compare."""
+    m = _FIND_PATH_VALUE.search(find_cmd_line)
+    if not m:
+        return None
+    glob = m.group(2)
+    for pat in (_FIND_PATH_SKILLS_SEG, _FIND_PATH_PLUGINS_SEG, _FIND_PATH_SCRIPTS_SEG):
+        seg = pat.search(glob)
+        if seg:
+            return seg.group(1)
+    return None
+
+
+def _finding_guard_pattern_mismatch(path, line, ctx_label, token, skill_name, plugin_name):
+    plugin_part = f" (plugin `{plugin_name}`)" if plugin_name else ""
+    return Finding(
+        "WARN",
+        "guard-pattern-mismatch",
+        f"`${{CLAUDE_PLUGIN_ROOT}}` used in an in-VM bash context ({ctx_label}); the block's self-heal "
+        f"`find` targets `{token}`, but this skill is `{skill_name}`{plugin_part} — the guard won't "
+        "discover THIS skill's mount (likely a copy-pasted self-heal).",
+        f"Fix the `find` pattern's `-path` to match this skill/plugin's own layout (`{skill_name}`"
+        f"{plugin_part}), not `{token}`.",
+        path,
+        line,
+    )
+
+
 def _finding_hook_host_write(path, line, what):
     return Finding(
         "WARN",
@@ -778,15 +827,46 @@ def _lint_skill_text(path, raw_lines, force_json=False):
     bash_token_lines = []
     bash_block_text = []
 
+    # Self-heal find-pattern guard: identity of the skill/plugin under lint, used to check a self-heal `find -path`
+    # actually names THIS skill or its enclosing plugin (not a copy-pasted mismatch). Only
+    # meaningful when linting an actual SKILL.md (force_json=False is exactly that case here — a
+    # hooks.json body never enters the "bash" ctx below, so this is otherwise unused).
+    skill_name = None
+    plugin_name = None
+    self_plugin_tokens = set()
+    if not force_json:
+        dir_name = Path(path).resolve().parent.name
+        fm_name = _agent_name_from_frontmatter(path, _require_yaml())
+        # Prefer the frontmatter `name:` (the skill's declared identity) for display when present;
+        # the parent-dir name is always in the match set as a cross-check (both count as "this
+        # skill" — a self-heal naming either is not a mismatch).
+        skill_name = fm_name or dir_name
+        self_plugin_tokens.add(dir_name)
+        if fm_name:
+            self_plugin_tokens.add(fm_name)
+        plugin_dir = _find_enclosing_plugin_dir(path)
+        if plugin_dir is not None:
+            plugin_name = _read_plugin_name(plugin_dir)
+            if plugin_name:
+                self_plugin_tokens.add(plugin_name)
+            self_plugin_tokens.add(Path(plugin_dir).name)
+
     def flush_bash():
         if bash_token_lines:
-            healed = _SELF_HEAL.search("\n".join(bash_block_text)) is not None
+            self_heal_line = next((bl for bl in bash_block_text if _SELF_HEAL.search(bl)), None)
+            healed = self_heal_line is not None
+            token = _extract_find_path_token(self_heal_line) if healed else None
             for ln in bash_token_lines:
-                findings.append(
-                    _finding_plugin_root_guarded(path, ln, "```bash block")
-                    if healed
-                    else _finding_plugin_root(path, ln, "```bash block")
-                )
+                if not healed:
+                    findings.append(_finding_plugin_root(path, ln, "```bash block"))
+                elif token is not None and token not in self_plugin_tokens:
+                    findings.append(
+                        _finding_guard_pattern_mismatch(
+                            path, ln, "```bash block", token, skill_name, plugin_name
+                        )
+                    )
+                else:
+                    findings.append(_finding_plugin_root_guarded(path, ln, "```bash block"))
         bash_token_lines.clear()
         bash_block_text.clear()
 
@@ -838,6 +918,210 @@ def _lint_skill_text(path, raw_lines, force_json=False):
     return findings
 
 
+# --------------------------------------------------------------------------- #
+# subagent_type static resolution
+# --------------------------------------------------------------------------- #
+#
+# A pinned `subagent_type:` value that doesn't resolve to a real agent fails a definition lookup at
+# dispatch time — but that's only discoverable via a live dispatch today. Resolve it statically from
+# a plugin's own `.claude-plugin/plugin.json` (or `plugin.json`) + `agents/*.md` frontmatter instead.
+#
+# HONEST LIMIT: there is no harness registry of built-in agent types (the built-in set is
+# agent-binary-version-dependent) — only `general-purpose` is harness-known. So an unresolved bare
+# value is surfaced as INFO, never failed as WARN/ERROR; the linter can't disprove it's a real
+# built-in. Do NOT add a committed built-in agent-type list here — that would silently go stale and
+# either false-warn a real built-in or false-clear a typo.
+
+_SUBAGENT_TYPE_RE = re.compile(r"subagent_type\s*[:=]\s*['\"]?([A-Za-z0-9_.:/-]+)['\"]?")
+
+
+def _read_plugin_name(plugin_dir):
+    """Return the `name` field from `<plugin_dir>/.claude-plugin/plugin.json` (fallback
+    `<plugin_dir>/plugin.json`), or None if neither file exists or is parsable. Never raises."""
+    p = Path(plugin_dir)
+    for candidate in (p / ".claude-plugin" / "plugin.json", p / "plugin.json"):
+        if candidate.is_file():
+            try:
+                data = json.loads(candidate.read_text(encoding="utf-8"))
+            except Exception:
+                return None
+            name = data.get("name") if isinstance(data, dict) else None
+            return name if isinstance(name, str) and name.strip() else None
+    return None
+
+
+_AGENT_FRONTMATTER = re.compile(r"^---\s*\n(.*?\n)---\s*(?:\n|$)", re.DOTALL)
+
+
+def _agent_name_from_frontmatter(md_path, yaml_mod):
+    """Return a markdown file's `name:` frontmatter value, or None if there's no frontmatter, no
+    `name:` field, or it fails to parse. Originally for `agents/*.md` (caller falls back to the
+    filename stem there); also reused by the self-heal find-pattern guard for a SKILL.md, whose frontmatter has the same
+    `---\\nname: ...\\n---` shape — the parser itself is generic, only the name is agent-specific."""
+    try:
+        text = Path(md_path).read_text(encoding="utf-8")
+    except Exception:
+        return None
+    m = _AGENT_FRONTMATTER.match(text)
+    if not m:
+        return None
+    try:
+        data = yaml_mod.safe_load(m.group(1))
+    except Exception:
+        return None
+    if isinstance(data, dict):
+        name = data.get("name")
+        if isinstance(name, str) and name.strip():
+            return name.strip()
+    return None
+
+
+def _resolve_plugin_agents(plugin_dir):
+    """Resolve in-plugin agent types: return the set of valid `<plugin>:<agent>` subagent types defined WITHIN plugin_dir.
+    Reads the plugin name from plugin.json and each agents/*.md's `name:` frontmatter (filename stem
+    fallback). Returns an empty set (never crashes) when no plugin.json is found — a bare SKILL.md
+    dir with no plugin manifest has nothing to resolve against."""
+    plugin_name = _read_plugin_name(plugin_dir)
+    if not plugin_name:
+        return set()
+    agents_dir = Path(plugin_dir) / "agents"
+    if not agents_dir.is_dir():
+        return set()
+    yaml = _require_yaml()
+    types = set()
+    for md in sorted(agents_dir.glob("*.md")):
+        agent_name = _agent_name_from_frontmatter(md, yaml) or md.stem
+        types.add(f"{plugin_name}:{agent_name}")
+    return types
+
+
+def cmd_resolve_agent_types(args):
+    types = sorted(_resolve_plugin_agents(args.plugin_dir))
+    if args.json:
+        print(json.dumps(types))
+    else:
+        for t in types:
+            print(t)
+    return 0
+
+
+def _find_enclosing_plugin_dir(skill_md_path):
+    """Resolve the enclosing plugin: walk up from a SKILL.md to the nearest ancestor dir containing
+    `.claude-plugin/plugin.json` or `plugin.json` — that's the enclosing plugin. None if no ancestor
+    has one (a bare SKILL.md dir with no plugin manifest anywhere above it)."""
+    start = Path(skill_md_path).resolve().parent
+    for anc in [start, *start.parents]:
+        if (anc / ".claude-plugin" / "plugin.json").is_file() or (anc / "plugin.json").is_file():
+            return anc
+    return None
+
+
+def _finding_subagent_unresolvable(path, line, value):
+    return Finding(
+        "INFO",
+        "subagent-type-unresolvable",
+        f"pinned type `{value}` belongs to another plugin — can't confirm it resolves from here",
+        "Verify it resolves in that plugin's own agents/ dir (e.g. `scenario.py resolve-agent-types "
+        "<that-plugin-dir>`), or dispatch without pinning a cross-plugin type.",
+        path,
+        line,
+    )
+
+
+def _finding_subagent_unknown(path, line, value):
+    return Finding(
+        "INFO",
+        "subagent-type-unknown",
+        f"pinned type `{value}` is not defined in this plugin and is not the `general-purpose` "
+        "built-in — can't confirm statically (may be an agent-binary built-in)",
+        "If it's meant to be an in-plugin agent, add `agents/<name>.md` with a `name:` frontmatter "
+        "matching the pinned value (or rely on the filename-stem fallback). If it's a real built-in "
+        "agent type, this INFO is expected — the linter has no built-in registry to check it against.",
+        path,
+        line,
+    )
+
+
+def _finding_subagent_not_found_in_plugin(path, line, value, plugin_name, agent, sorted_agents):
+    """A pinned `<this-plugin>:<agent>` value whose prefix names the RESOLVED plugin (this SKILL.md's
+    own enclosing plugin) but whose agent isn't in its enumerated agents/*.md set. Unlike
+    `subagent-type-unknown`, this can never be another binary's built-in — the namespace prefix
+    already commits it to this plugin, and the plugin's agent set was fully enumerable — so it's a
+    provable typo, not an unconfirmable unknown."""
+    return Finding(
+        "INFO",
+        "subagent-type-not-found-in-plugin",
+        f"pinned type `{value}` names this plugin (`{plugin_name}`) but `{agent}` is not among its "
+        f"agents [{', '.join(sorted_agents)}] — likely a typo.",
+        "Fix the agent name to match one of the listed agents, or add `agents/<agent>.md` with a "
+        "`name:` frontmatter matching the pinned value (or rely on the filename-stem fallback) if it "
+        "was meant to exist. Check `scenario.py resolve-agent-types <plugin-dir>` to confirm.",
+        path,
+        line,
+    )
+
+
+def _classify_subagent_type(value, plugin_name, plugin_agent_types):
+    """subagent_type severity ladder. Returns a Finding-builder (path, line, value) -> Finding, or None if
+    clean. Severity is ALWAYS INFO — see the HONEST LIMIT note above this section; never WARN/ERROR.
+
+    Precedence:
+      1. Resolves in-plugin, or is `general-purpose` -> clean (None).
+      2. Has a `<prefix>:<agent>` shape whose prefix EQUALS the resolved plugin's own name AND the
+         plugin's agent set was non-empty (i.e. enumerable) -> `subagent-type-not-found-in-plugin`.
+         A value namespaced under this plugin's own name can never be another binary's built-in, so
+         once the plugin is fully enumerated a miss here is a provable typo, not an unconfirmable
+         unknown.
+      3. Has a `<prefix>:<agent>` shape whose prefix does NOT equal the resolved plugin's name (or
+         there's no resolved plugin at all) -> `subagent-type-unresolvable` (belongs to another
+         plugin, or an empty plugin_name means we truly can't tell whose namespace it is).
+      4. Otherwise (no colon, or same-plugin prefix but the plugin set was empty/unenumerable) ->
+         `subagent-type-unknown` — genuinely can't confirm statically.
+    """
+    if value == "general-purpose" or value in plugin_agent_types:
+        return None
+    if ":" in value:
+        prefix, agent = value.split(":", 1)
+        if plugin_name is not None and prefix == plugin_name:
+            if plugin_agent_types:
+                sorted_agents = sorted(
+                    t.split(":", 1)[1] for t in plugin_agent_types if t.split(":", 1)[0] == plugin_name
+                )
+                return functools.partial(
+                    _finding_subagent_not_found_in_plugin,
+                    plugin_name=plugin_name,
+                    agent=agent,
+                    sorted_agents=sorted_agents,
+                )
+            # Plugin set is empty — couldn't enumerate (e.g. no agents/ dir) — genuinely can't confirm.
+            return _finding_subagent_unknown
+        return _finding_subagent_unresolvable
+    return _finding_subagent_unknown
+
+
+def _lint_subagent_types(path, raw_lines):
+    """Scan a SKILL.md's raw text (not limited to fenced blocks — a pinned `subagent_type`
+    can appear in prose or YAML frontmatter) for pinned `subagent_type` values and classify each
+    against the enclosing plugin's in-plugin agent set."""
+    matches = []
+    for i, line in enumerate(raw_lines, start=1):
+        for m in _SUBAGENT_TYPE_RE.finditer(line):
+            matches.append((i, m.group(1)))
+    if not matches:
+        return []
+
+    plugin_dir = _find_enclosing_plugin_dir(path)
+    plugin_name = _read_plugin_name(plugin_dir) if plugin_dir else None
+    plugin_agent_types = _resolve_plugin_agents(plugin_dir) if plugin_dir else set()
+
+    findings = []
+    for line_no, value in matches:
+        builder = _classify_subagent_type(value, plugin_name, plugin_agent_types)
+        if builder is not None:
+            findings.append(builder(path, line_no, value))
+    return findings
+
+
 def _resolve_skill_targets(arg):
     """Return (skill_md_path_or_None, [hooks.json paths]) for a directory or file arg."""
     p = Path(arg)
@@ -872,7 +1156,9 @@ def cmd_lint_skill(args):
             continue
         if md is not None:
             n_files += 1
-            all_findings.extend(_lint_skill_text(md, Path(md).read_text(encoding="utf-8").splitlines()))
+            md_lines = Path(md).read_text(encoding="utf-8").splitlines()
+            all_findings.extend(_lint_skill_text(md, md_lines))
+            all_findings.extend(_lint_subagent_types(md, md_lines))
         for hp in hooks:
             n_files += 1
             all_findings.extend(
@@ -883,7 +1169,13 @@ def cmd_lint_skill(args):
     else:
         _print_findings(all_findings, n_files, kind="skill file", clean_suffix=" — no Cowork host-loop footguns.")
     has_error = any(x.severity == "ERROR" for x in all_findings)
-    if has_error or (args.strict and all_findings):
+    # --strict fails on WARN too, per its own --help text ("exit non-zero on WARN too, not just ERROR")
+    # — but NEVER on INFO. The subagent_type ladder (subagent-type-unresolvable /
+    # -not-found-in-plugin / -unknown) and plugin-root-guarded are always INFO by design (there is no
+    # harness registry to disprove an unknown value against — see the subparser help above), so they
+    # must always be surfaced, never failed, even under --strict.
+    has_warn = any(x.severity == "WARN" for x in all_findings)
+    if has_error or (args.strict and has_warn):
         return 1
     return 0
 
@@ -1057,7 +1349,7 @@ def main(argv=None):
 
     lsp = sub.add_parser(
         "lint-skill",
-        help="lint SKILL.md bodies for two Cowork host-loop footguns (WARN-only, v1 narrow)",
+        help="lint SKILL.md bodies for Cowork host-loop footguns + static subagent_type resolution",
         description=(
             "Inspect skill bodies (SKILL.md + any sibling hooks.json) for two antipatterns a paid "
             "Cowork host-loop run would expose:\n"
@@ -1068,7 +1360,15 @@ def main(argv=None):
             "ONLY a fenced ```bash/```sh/```shell block, a hooks-config JSON \"command\" value, or a "
             "Bash(...) directive. Host-side prose and Read/Grep directives (the correct way to read a "
             "reference via ${CLAUDE_PLUGIN_ROOT}/...) are left alone. False negatives are expected: a token "
-            "in an indented/unfenced shell snippet won't be caught."
+            "in an indented/unfenced shell snippet won't be caught.\n\n"
+            "Also statically resolves any pinned `subagent_type` value in the SKILL.md against the "
+            "enclosing plugin's `agents/*.md` (see `resolve-agent-types`): a value that resolves in-plugin "
+            "or is `general-purpose` is clean; a `<this-plugin>:<agent>` whose agent is missing from an "
+            "enumerable plugin is a provable typo, reported as `subagent-type-not-found-in-plugin`; a "
+            "`<other-plugin>:<agent>` is reported as `subagent-type-unresolvable`; any other unresolved "
+            "value (including a same-plugin prefix the linter couldn't enumerate) is "
+            "`subagent-type-unknown` — all three are always INFO, never WARN, since there is no harness "
+            "registry of built-in agent types to disprove an unknown value against."
         ),
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
@@ -1077,6 +1377,24 @@ def main(argv=None):
     lsp.add_argument("--strict", action="store_true", help="exit non-zero on WARN too, not just ERROR")
     lsp.set_defaults(func=cmd_lint_skill)
 
+    rap = sub.add_parser(
+        "resolve-agent-types",
+        help="print a plugin's valid <plugin>:<agent> subagent types (from plugin.json + agents/*.md)",
+        description=(
+            "Statically resolve the set of `<plugin>:<agent>` subagent types defined WITHIN a plugin "
+            "dir: the plugin name comes from `.claude-plugin/plugin.json` (fallback `plugin.json`), "
+            "each agent name comes from `agents/*.md`'s `name:` frontmatter (filename-stem fallback "
+            "when a file has no `name:`). Prints an empty result (exit 0) for a dir with no "
+            "plugin.json — nothing to resolve against. This is the token-free 'does "
+            "`<plugin>:<agent>` resolve within this plugin?' answer that backs the `subagent_type` "
+            "check folded into `lint-skill`."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    rap.add_argument("plugin_dir", help="plugin directory (containing .claude-plugin/plugin.json or plugin.json)")
+    rap.add_argument("--json", action="store_true", help="emit the resolved types as a JSON array instead of one per line")
+    rap.set_defaults(func=cmd_resolve_agent_types)
+
     sp = sub.add_parser("scaffold", help="emit a valid scenario skeleton (self-linted)")
     sp.add_argument("--name", default="my-scenario", help="scenario name (default: my-scenario)")
     sp.add_argument("--prompt", help="the user turn (the prompt: block)")