cowork-harness 0.31.0 → 0.33.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.31.0
-  tracks-harness: cowork-harness 0.31.0 (baseline desktop-1.20186.1)
+  version: 0.33.0
+  tracks-harness: cowork-harness 0.33.0 (baseline desktop-1.20186.1)
 ---
 
 # 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 0.31.0` (baseline
+> **Version note:** the facts and `file:line` pointers here track `cowork-harness 0.33.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.
 
@@ -38,10 +38,22 @@ 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.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).)
+- **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 **≥ 0.33.0**. If it's missing or older, prefix every command with the version floor `npx "cowork-harness@>=0.33.0" <cmd>` (Node ≥ 20), or install once with `npm i -g "cowork-harness@>=0.33.0"`. **Pin `@>=0.33.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 ≥ 0.33.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.
+  - **0.22.0:** `computer_links_resolve`.
+  - **0.28.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), and **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).
+  - **0.30.0:** resolved sub-agent identity on dispatch records (`resolvedAgentType`/`resolvedModel`), the five path-gate assertion keys `no_vm_path_file_op`/`vm_path_denied`/`path_denied`/`no_path_denied`/`subagent_file_write`, and the session-level `agent_env` knob.
+  - **0.31.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.
+  - **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.
 - **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`).
+- **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`).
 - **`--dotenv` is a GLOBAL flag — put it BEFORE the subcommand.** `cowork-harness --dotenv .env record …`, never `cowork-harness record … --dotenv .env`. Every *other* flag is subcommand-level, so muscle memory fights this one; the harness rejects the misplaced form with an exact-fix error, but placing it first avoids the round-trip.
 
 ## Orient — the three loops
@@ -63,7 +75,7 @@ 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.31.0's observability is built for; the *Triage* and *Inspecting a run's observability
+  the loop 0.32.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
@@ -240,12 +252,12 @@ Full model in `references/scenario-schema.md`.
 Don't hand-write the YAML from memory — that's how invented keys (`assertions:` vs `assert:`,
 `json_file`, `answer_policy`) creep in. Start from the bundled generator, which emits the
 known-good skeleton (right tier, scripted `answers:` + `on_unanswered: fail`, content assertions
-separated from live-only ones, one concern per item) and **self-lints its own output**:
+separated from live-only ones, one concern per item) and **self-lints its own output**. The
+generator is the bundled `scripts/scenario.py` — installed as a plugin, point `S` at
+`${CLAUDE_PLUGIN_ROOT}/scripts/scenario.py`; from a repo checkout, use the literal path below:
 
 ```bash
-S="${CLAUDE_PLUGIN_ROOT}/scripts/scenario.py"
-# Working from a repo checkout instead of an installed plugin?
-# S=".claude/skills/cowork-harness/scripts/scenario.py"
+S=".claude/skills/cowork-harness/scripts/scenario.py"
 python3 "$S" scaffold --name report-check --skill ./skills/report-gen \
   --prompt "Generate the weekly report to outputs/report.md." \
   --content 'weekly report' --artifact outputs/report.md \
@@ -372,7 +384,7 @@ than a stuck `"running"`.)
 ### Place assertions in the right CI lane
 
 CI placement: a **token-free `replay` PR gate** (content/structure only) + a **nightly live `run`**
-(filesystem/egress). Fastest setup: `uses: yaniv-golan/cowork-harness@v1` (a packaged GitHub Action with a
+(filesystem/egress). Fastest setup: `uses: yaniv-golan/cowork-harness@main` (a packaged GitHub Action with a
 PR job-summary reporter). See `references/ci-recipe.md` for the Action, the manual step-by-step form, and
 the four-stage pipeline.
 

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

@@ -1,17 +1,20 @@
 # CI recipe — replay vs live lanes
 
-Self-contained reference. Tracks `cowork-harness 0.31.0` (baseline `desktop-1.20186.1`).
+Self-contained reference. Tracks `cowork-harness 0.33.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):
 
 ```yaml
-- uses: yaniv-golan/cowork-harness@v1
+- uses: yaniv-golan/cowork-harness@main
   with:
     command: replay
     path: cassettes/
 ```
 
+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: "0.33.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
 independently instead of as one action run per command).
@@ -29,13 +32,13 @@ jobs:
       - uses: actions/checkout@v4
       - name: Stage the agent binary (official channel, sha256-verified — see docs/maintenance.md)
         run: |
-          V=2.1.197   # match your scenario's pinned baseline's agentVersion
+          V=2.1.205   # match your scenario's pinned baseline's agentVersion
           curl -fSL "https://downloads.claude.ai/claude-code-releases/$V/linux-arm64/claude" -o "$RUNNER_TEMP/claude-$V"
           chmod +x "$RUNNER_TEMP/claude-$V"
           # verify against the committed baseline's sha256 (baselines/desktop-*.json → agentBinary.sha256)
           # before trusting it — see docs/maintenance.md's "Agent-binary provenance" section.
           echo "COWORK_AGENT_BINARY=$RUNNER_TEMP/claude-$V" >> "$GITHUB_ENV"
-      - uses: yaniv-golan/cowork-harness@v1
+      - uses: yaniv-golan/cowork-harness@main
         with:
           command: run
           path: scenarios/
@@ -54,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@>=0.31.0"
+- run: npm i -g "cowork-harness@>=0.33.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
@@ -174,7 +177,7 @@ A typical skill repo runs four stages, fastest/cheapest first:
 
 ## GitHub Actions sketch
 
-The PR gate below is the manual, step-by-step version of what `uses: yaniv-golan/cowork-harness@v1` does
+The PR gate below is the manual, step-by-step version of what `uses: yaniv-golan/cowork-harness@main` does
 in one step (see the top of this doc) — reach for this form when you need independent per-command
 gating/annotations rather than one action run per command. The nightly live job has no packaged-Action
 equivalent yet (the Action's `command: run` mode needs a self-hosted runner with Docker + the agent binary
@@ -194,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@>=0.31.0"
+      - run: npm i -g "cowork-harness@>=0.33.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
@@ -223,7 +226,7 @@ jobs:
             echo "live=true" >> "$GITHUB_OUTPUT"
           fi
       - if: steps.guard.outputs.live == 'true'
-        run: npm i -g "cowork-harness@>=0.31.0"
+        run: npm i -g "cowork-harness@>=0.33.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 0.31.0` (baseline `desktop-1.20186.1`).
+Self-contained reference. Tracks `cowork-harness 0.33.0` (baseline `desktop-1.20186.1`).
 
 ## Fidelity tiers (`fidelity:` in the scenario)
 
@@ -13,10 +13,10 @@ Self-contained reference. Tracks `cowork-harness 0.31.0` (baseline `desktop-1.20
 | `cowork` | Auto-picks `hostloop` vs `container` the way Cowork itself does for the synced release | "Do what real Cowork does for this release." |
 
 - `hostloop` / `cowork` are the production-faithful path; `container` is the practical default.
-- Boundary assertions (`egress_*`, `expect_denied`) are enforced at `container`, `microvm`, and
-  `hostloop` (`container`'s and `hostloop`'s `bash` share the same Docker sandbox + egress proxy —
-  `hostloop`'s native file tools run with no container at all, gated instead by a path-containment hook).
-  Only `protocol` is rejected.
+- Boundary assertions (`egress_*`, `expect_denied`) are enforced at `container`, `microvm`, `hostloop`,
+  and `cowork` (`cowork` auto-resolves to a sandboxed tier; `container`'s and `hostloop`'s `bash` share
+  the same Docker sandbox + egress proxy — `hostloop`'s native file tools run with no container at all,
+  gated instead by a path-containment hook). Only `protocol` is rejected.
 - A `hostloop` scenario with a **writable** connected folder (`mode: rw`/`rwd`) needs `allow_host_writes:
   true` — with no container around the native file tools, that combination gives the agent genuine,
   software-checked-only host filesystem access. Read-only folders and folder-less runs need no opt-in.
@@ -176,7 +176,7 @@ and `scaffold` refuse to treat a partial run's half-finished output as a passing
 - `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.
 - `COWORK_HARNESS_DECIDER_CMD_TIMEOUT_MS` / `COWORK_HARNESS_LLM_TIMEOUT_MS` — decider backstops
   (default 600 s; **fail loud** on timeout).
-- `COWORK_HARNESS_DECIDER_DIR_POLL_MS` / `_TIMEOUT_MS` — the `--decider-dir` rendezvous.
+- `COWORK_HARNESS_DECIDER_DIR_POLL_MS` / `_TIMEOUT_MS` — the `--decider-dir` rendezvous (poll defaults: 300 ms for the run-side rendezvous, 500 ms for `gates --follow`).
 - `COWORK_HARNESS_DIALOG_TIMEOUT_MS` — dialog auto-cancel (default 6 s).
 - `COWORK_HARNESS_LLM_MAX_BYTES` — stdout bound on `--decider-llm` (default 8 MiB).
 - `COWORK_HARNESS_LLM_RETRIES` — bounded retries for a transient non-zero `claude -p` exit on the

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 0.31.0`
+Self-contained reference for authoring `cowork-harness` scenarios. Tracks `cowork-harness 0.33.0`
 (baseline `desktop-1.20186.1`). If your checkout is newer, prefer the live `docs/scenario.md`,
 `docs/session.md`, and `SPEC.md`.
 
@@ -37,7 +37,7 @@ fidelity: container                 # protocol | container | microvm | hostloop
 execution: local                    # OPTIONAL — orthogonal to fidelity (a privilege/sandbox tier, all
                                     # local): local (default) | cloud-describe (RESERVED — no runner
                                     # exists yet; authoring it is a load-time error, not a silent no-op)
-on_unanswered: fail                 # policy for unscripted gates: fail | prompt | first | llm
+on_unanswered: fail                 # policy for unscripted gates: fail | prompt | first | llm — run rejects prompt
                                     # ("agent" is retired — no longer a valid value)
 
 prompt: |                           # the user turn
@@ -312,7 +312,7 @@ same set live from the schema.
 | `egress_allowed: <host>` | the host was allowed through |
 | `no_mcp_error: true` | no MCP round-trip failed (`RunResult.mcpErrors` is empty — no unhandled server, no handler throw) — live-only: MCP round-trips are harness-computed, not in the SDK stdout stream, so evidence-unavailable on replay (never a vacuous pass). **Only `true` is valid** |
 | `max_peak_rss_bytes: <N>` | peak sampled RSS of the agent sandbox ≤ N bytes (`RunResult.resources.peakRssBytes`) — live-only: replay never spawns a sandbox to sample, so evidence-unavailable on replay/protocol (never a vacuous pass); also evidence-unavailable when sampling captured no RSS value |
-| `semantic_matches: {rubric: [...], min_pass?, judge_model?}` | a pinned LLM judge grades each fixed `rubric` claim against the run's answer — the **union of the agent's final result text (`RunResult.finalMessage`), the transcript, and the final on-disk content of any files the agent authored during the run** — so a claim about content the skill led the agent to *write to a file* grades as reliably as one about inlined prose (authored-file evidence is unavailable on the **microvm** tier — no pre-run manifest to diff against, so no files are captured; `container`/`hostloop` do capture them). Beyond the microvm case, when the authored-file evidence backing the judged document is **incomplete** — a file dropped at the capture-size cap, unreadable at read-back, or (on `--resume`) the scratchpad walk skipped — the assert fails evidence-unavailable rather than trusting a judge grade over a partial document; this is separate from the malformed-grade `judgeInvalid` path below. The assert passes iff ≥ `min_pass` claims pass (default: all — avoid for a gating scenario). Results align by claim index and are recorded per-claim in `RunResult.assertions[].semanticClaims` (`[{index, claim, pass}]`, so a consumer can diff the per-claim profile across runs); a rep whose grade can't be parsed (after one retry) is marked `RunResult.assertions[].judgeInvalid` and **never silently dropped** — it is excluded from the pass denominator, and the guard against a misleading score from that exclusion is the gate's minimum-valid-rep floor (`MIN_VALID` ≥ 4) plus this visibility, not a claim that denominator-shrinking inflation is impossible. Within a rep, a grade that's still unparseable after the retry **fails that assert outright** (evidence-unavailable, not a vacuous pass) — a persistently-flaky judge reds the run rather than silently passing. `judge_model` pins the grader (a dated id keeps a before/after comparison reproducible). Live-only: the judge is a live model call, so evidence-unavailable / skipped-loud on replay (never a vacuous pass) |
+| `semantic_matches: {rubric: [...], min_pass?, judge_model?}` | a pinned LLM judge grades each fixed `rubric` claim against the run's answer — the **union of the agent's final result text (`RunResult.finalMessage`), the transcript, and the final on-disk content of any files the agent authored during the run** — so a claim about content the skill led the agent to *write to a file* grades as reliably as one about inlined prose (authored-file evidence is unavailable on the **microvm** tier — no pre-run manifest to diff against, so no files are captured; `container`/`hostloop` do capture them). Beyond the microvm case, when the authored-file evidence backing the judged document is **incomplete** — a file dropped at the capture-size cap, unreadable at read-back, or (on `--resume`) the scratchpad walk skipped — the assert fails evidence-unavailable rather than trusting a judge grade over a partial document; this is separate from the malformed-grade `judgeInvalid` path below. The assert passes iff ≥ `min_pass` claims pass (default: all — avoid for a gating scenario). Results align by claim index and are recorded per-claim in `RunResult.assertions[].semanticClaims` (`[{index, claim, pass}]`, so a consumer can diff the per-claim profile across runs); a rep whose grade can't be parsed (after one retry) is marked `RunResult.assertions[].judgeInvalid` and **never silently dropped** — it is excluded from the pass denominator, and the guard against a misleading score from that exclusion is the gate's minimum-valid-rep floor (`MIN_VALID` ≥ 4) plus this visibility, not a claim that denominator-shrinking inflation is impossible. Within a rep, a grade that's still unparseable after the retry **fails that assert outright** (evidence-unavailable, not a vacuous pass) — a persistently-flaky judge reds the run rather than silently passing. `judge_model` pins the grader (default when neither it nor `COWORK_HARNESS_JUDGE_MODEL` is set: `claude-opus-4-8`; a dated id keeps a before/after comparison reproducible). Live-only: the judge is a live model call, so evidence-unavailable / skipped-loud on replay (never a vacuous pass) |
 | `artifact_json: {artifact, path, …}` | assert a JSON artifact's contents — `equals`/`gt`/`in`/`exists`/`absent`/`is_null` over a dotted `path` (`in` = membership in a list, for a stochastic/LLM value; `absent` ≠ `is_null`; an unresolved intermediate fails loud) |
 | `computer_links_resolve: true` | every `computer://` link in the model-visible transcript resolves to an artifact that exists in the run's collected outputs/mounts — a dangling link fails, naming which target was checked (a live host path, the collected work tree, or the replay manifest). **Requires ≥1 link** (zero links fails — use `computer_links_resolve_if_present` for the presence-free variant). **Only `true` is valid** (`false` is rejected by the schema) |
 | `computer_links_resolve_if_present: true` | like `computer_links_resolve` but passes vacuously when the transcript has zero `computer://` links — the presence-free variant. **Only `true` is valid** |
@@ -329,7 +329,7 @@ paraphrases (that re-records red). Structured JSON → assert it in YAML with **
 `path` + operator); use the pytest lane (`assert_artifact_json`) only for predicates too complex for a
 dotted path.
 
-**VerdictSignals in `result.signals`:** `computeVerdict` pushes signals into `result.signals`; most
+**VerdictSignals in `result.verdict.signals`:** `computeVerdict` pushes signals into `result.verdict.signals`; most
 are **fail**-severity (they flip the run's pass/exit code even though `result.result` itself stays
 `"success"`) and only three are **warn**-severity (informational, never flip pass/fail). Current signal
 codes (`VerdictSignal["code"]` in `src/run/verdict.ts`):
@@ -353,7 +353,7 @@ codes (`VerdictSignal["code"]` in `src/run/verdict.ts`):
 
 A **fail**-severity signal does not change `result.result` (still `"success"`), but it DOES fail the
 overall run verdict and exit code — `assert result: success` alone won't catch it; check
-`result.signals[].severity` or the run's exit code. Only the three **warn** codes are truly benign.
+`result.verdict.signals[].severity` or the run's exit code. Only the three **warn** codes are truly benign.
 
 ## Replay class
 
@@ -491,7 +491,7 @@ reference omits). Neither list is a strict superset of the other — reach for t
    the stochastic path flags the run `nonDeterministic`. The LLM decider is one mechanism, two
    spellings: `on_unanswered: llm` (YAML) and `--decider-llm` (CLI). The bare `--on-unanswered llm`
    is rejected (use `--decider-llm`). `agent` is **retired** — `on_unanswered: agent` is rejected by
-   the schema. (`src/types.ts:365` — the `on_unanswered` enum; `src/cli.ts:899` — the CLI-side
+   the schema. (`src/types.ts` — the `on_unanswered` enum; `src/cli.ts:899` — the CLI-side
    `--on-unanswered` value check.)
 
 4. **`--on-unanswered first` is non-deterministic too** — it picks option 1 and is flagged

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.31.0). Recipe 2's `resolved-tier`/`unverifiable-tier` staleness classes and
+front-matter (currently 0.32.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/scenario.py

@@ -1047,9 +1047,10 @@ def _finding_subagent_not_found_in_plugin(path, line, value, plugin_name, agent,
     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."""
+    provable typo, not an unconfirmable unknown. Provable means it can be a hard gate: WARN (not
+    INFO), so `lint-skill --strict` fails on it."""
     return Finding(
-        "INFO",
+        "WARN",
         "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.",
@@ -1063,20 +1064,23 @@ def _finding_subagent_not_found_in_plugin(path, line, value, plugin_name, agent,
 
 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.
+    clean. Only ONE outcome is a hard gate: `subagent-type-not-found-in-plugin` is WARN (a provable
+    typo, so `lint-skill --strict` fails on it); the two unconfirmable outcomes
+    (`subagent-type-unresolvable`, `subagent-type-unknown`) stay INFO — see the HONEST LIMIT note
+    above this section for why those two can never be proven.
 
     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.
+         plugin's agent set was non-empty (i.e. enumerable) -> `subagent-type-not-found-in-plugin`
+         (WARN — provable typo, gates under `--strict`). 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
+         there's no resolved plugin at all) -> `subagent-type-unresolvable` (INFO — 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.
+         `subagent-type-unknown` (INFO) — genuinely can't confirm statically.
     """
     if value == "general-purpose" or value in plugin_agent_types:
         return None
@@ -1170,10 +1174,10 @@ def cmd_lint_skill(args):
         _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)
     # --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.
+    # — but NEVER on INFO. Of the subagent_type ladder, only `subagent-type-not-found-in-plugin` is
+    # WARN (a provable in-plugin typo — see the subparser help above); `subagent-type-unresolvable` and
+    # `subagent-type-unknown` stay INFO by design (there is no harness registry to disprove an unknown
+    # value against), so those two 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
@@ -1364,17 +1368,26 @@ def main(argv=None):
             "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."
+            "enumerable plugin is a provable typo, reported as `subagent-type-not-found-in-plugin` "
+            "(WARN — gates under `--strict`, since the namespace prefix already commits it to this "
+            "plugin and its agent set was fully enumerated); a `<other-plugin>:<agent>` is reported as "
+            "`subagent-type-unresolvable` (INFO); any other unresolved value (including a same-plugin "
+            "prefix the linter couldn't enumerate) is `subagent-type-unknown` (INFO) — those two stay "
+            "INFO, never WARN, since there is no harness registry of built-in agent types to disprove "
+            "an unknown value against.\n\n"
+            "Plain `lint-skill` (no `--strict`) is ADVISORY — it prints findings but exits 0 on "
+            "WARN/INFO. CI should invoke `lint-skill --strict` to actually gate on the WARN-class "
+            "findings above (the two host-loop footguns and the provable subagent_type typo)."
         ),
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
     lsp.add_argument("paths", nargs="+", help="SKILL.md file(s) or skill director(ies) to inspect")
     lsp.add_argument("--json", action="store_true", help="emit findings as JSON")
-    lsp.add_argument("--strict", action="store_true", help="exit non-zero on WARN too, not just ERROR")
+    lsp.add_argument(
+        "--strict",
+        action="store_true",
+        help="exit non-zero on WARN too, not just ERROR (CI-recommended invocation; plain lint-skill is advisory-only)",
+    )
     lsp.set_defaults(func=cmd_lint_skill)
 
     rap = sub.add_parser(

package/CHANGELOG.md

@@ -6,6 +6,226 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.33.0] — 2026-07-13
+
+### Fixed
+
+- **Empty thinking was surfaced as if the model hadn't reasoned — both `subagents[].reasoning` and the
+  top-level `thinking[]`.** The 0.31.0 sub-agent field captured TEXT turns fine but every `thinking` turn
+  came through as `{kind:"thinking", text:""}`, and the older top-level `thinking[]` field does the same
+  on current-gen models — a consumer couldn't tell "reasoned but text unavailable" from "no thought."
+  Root cause (binary-verified against the staged 2.1.205 agent, corpus-corroborated): it is a
+  **request-side display mode**, not a persist-time strip — the API's `thinking.display` resolves to
+  `"omitted"` (empty thinking text + a signature) for sub-agent turns always, and for the MAIN loop too
+  on models whose API default is `"omitted"` (Opus 4.8, Sonnet 5; Sonnet 4.6 defaulted to `"summarized"`).
+  Corpus: main-loop thinking text is 1810/1810 on Sonnet-4.6 but **0/2 on Opus-4.8 and 0/15 on Sonnet-5**,
+  every empty carrying a signature; sub-agents 0/230. The harness passes no `--thinking-display` —
+  faithfully to real Cowork, whose spawn passes none either. Both fields now mark such blocks
+  `{text:"", redacted:true}` (`kind:"thinking"` for the sub-agent turn shape) so they read as "reasoned,
+  text omitted by request"; TEXT turns are never redacted, and `redacted` is omitted (not `false`) on
+  blocks that carry text.
+- **New `debug.thinking_display` escape hatch** (fenced, non-Cowork — like `debug.max_thinking_tokens`).
+  Set it to `"summarized"` to emit `--thinking-display summarized`, which flips **both** loops to
+  summarized thinking text (the API returns no raw chain-of-thought — `summarized` is the ceiling). It
+  diverges from real Cowork (which passes no such flag) and adds token cost, so it is a debug-only opt-in;
+  the default stays `"omitted"`, byte-identical argv. `docs/subagents.md`, `docs/session.md`,
+  `schema/run-result.json`, and the `RunResult`/`SessionConfig` types state the real capture semantics;
+  the released 0.31.0 note is corrected in place.
+
+- **Docs pointed the GitHub Action at a ref that doesn't exist.** README, `SKILL.md`, and
+  `references/ci-recipe.md` all said `uses: yaniv-golan/cowork-harness@v1`, but no `v1` tag has ever
+  been published — a copy-pasted workflow failed with "unable to resolve action" before running
+  anything. All six references now bind `@main`; a moving major tag is a 1.0.0 question. A new
+  token-free guard (`test/action-docs-sync.test.ts`) locks the ref policy and also validates that
+  every documented `with:` key is a real `action.yml` input and every documented `command:` value is
+  one the Action describes.
+- **`llms.txt` command list was three commands stale** — `lint-skill`, `analyze-skill`, and
+  `probe-dispatch` were missing. Now lists all 29, locked by a new COMMANDS ↔ llms.txt sync test
+  (set-equality, so stale names fail too), and the README "Commands at a glance" guard gained the
+  reverse direction (a README-only row now fails).
+- **README observability prose still called a `subagents[]` field `model`** — renamed to
+  `dispatchModel` (beside `resolvedModel`) in 0.30.0; the prose now names the real fields. Also
+  fixed: the effort enum shorthand now lists `xhigh` (`extra` is the accepted alias) in both places,
+  the CI stage table matches `ci.yml`'s declaration order, the exit-code summary notes
+  `verify-cassettes`' distinct exit-`3` meaning and the reserved exit `4`, a duplicated `--keep`
+  example was collapsed, and `on_unanswered: llm` is explicitly marked as a scenario-YAML key (not a
+  CLI flag).
+- **`status --latest-for` was undocumented in its own guide** — now covered in `docs/run-status.md`
+  (with the real output shape), the `docs/README.md` index row, and the top-level `--help` status
+  entry (with its own `0` found / `2` not found exit semantics).
+- **`probe-dispatch --help` didn't start with a `usage:` line** like every other command; it does
+  now.
+- **`debugging.md` showed only the scenario run-dir layout** — it now also names `chat`'s
+  `runs/chat/<sessionId>/` path. `docs/session.md`'s "all four tiers" now spells out the four
+  execution tiers and that `fidelity: cowork` resolves to one of them. `examples/README.md`'s
+  answer-policies pointer is now a real link. `effectiveFidelity` (the recorded resolved tier behind
+  the `resolved-tier`/`unverifiable-tier` staleness classes) is now mentioned in the README fidelity
+  section and `python/README.md`, not only in `docs/cassette.md`.
+- **The docs told a false "default `8899`" story for `COWORK_VM_PROXY_PORT`** — when the var is
+  unset, the host binds the egress proxy on an OS-assigned free port and threads that value into the
+  guest firewall + `HTTP(S)_PROXY`; `8899` is only the guest-config fallback when a VM is spawned
+  without an explicit port, which never happens on a normal run. README and `docs/scenario.md` now
+  say so. Also closed: `COWORK_HARNESS_STATUS_CORRUPT_TIMEOUT_MS` (30s corrupt-`status.json`
+  backstop on `status --follow`) was the one `COWORK_*` env var documented nowhere — now in
+  `docs/run-status.md` + the README knob list; the `COWORK_HARNESS_DECIDER_DIR_POLL_MS` docs name
+  the per-subsystem defaults (300 ms rendezvous / 500 ms `gates --follow`); the `semantic_matches`
+  judge docs name the pinned default (`claude-opus-4-8`) in README, `docs/scenario.md`, and the
+  skill's schema reference; the heartbeat bullet states its 30s default instead of pointing at a
+  source file.
+- **`replay --explain` was invisible from the command catalog** — the flagship false-green
+  diagnosis flag was documented only in debugging prose; it's now in the `record`/`replay` command
+  table row and leads the record/replay "Flags worth knowing" bullet.
+- **`examples/README.md` ships in the npm tarball while the trees it describes don't** — it now
+  opens with a "Reading this on npm?" callout (clone for `scenarios/`/`sessions/`/`skills/`/`data/`),
+  documents `probes/` (previously invisible: used by `test/live-contract.test.ts` but absent from
+  the layout and from schema validation — `examples/probes` is now in `test/examples.test.ts`'s
+  scenario sweep), and links the matrices worked example; the README documentation-table row carries
+  the same source-checkout caveat.
+- **The companion skill's preflight sent replay-only users through `doctor`**, whose token check
+  hard-fails on every tier — a new "Replay-only? Skip `doctor`" bullet carries the same carve-out
+  `docs/README.md` already had. The 3,200-character single-bullet 0.32.0 feature parenthetical is
+  now a scannable by-release sub-list, with every release bucket tag-verified against git history —
+  which caught and fixed a long-standing wrong tag: `semantic_matches` was labeled "new in 0.27.0"
+  but shipped in 0.28.0; the five path-gate keys, `agent_env`, and the `hostloop` split/
+  `allow_host_writes:` now sit under their real releases (0.30.0 / 0.21.0) too.
+- **`DESIGN.md` still said the staged in-VM agent is 2.1.202** — the `desktop-1.20186.1` baseline
+  re-synced it to 2.1.205; DESIGN.md and `docs/protocol.md` now carry dated patch-only notes for
+  1.20186.1 while the 2026-07-11 live pass stays scoped to `desktop-1.20186.0` (not restamped).
+
+### Added
+
+- **`test/docs-index-sync.test.ts`** — three token-free guards: every `COWORK_*` env var read in
+  `src/` (dot-access **or** helper-read string literal) must be documented in README/`docs/*.md`;
+  the judge-model default id in the docs must match `semantic-judge.ts` (fails loud on a const
+  rename); `llms.txt` must link every top-level `docs/*.md` guide (both directions — `gotchas.md`,
+  `subagents.md`, and `plugin-root.md` were missing and are now linked).
+
+- **The Action's `version` default (`latest`) is now documented as intentional** — in `action.yml`'s
+  input description, the README inputs sentence, and `references/ci-recipe.md` — with
+  pin-an-exact-version guidance for reproducible CI, and why it deliberately differs from the
+  companion skill's `@>=0.32.0` floor for ad-hoc CLI installs.
+- **`--help` and unknown-flag structural-guard test coverage now spans all 29 commands** (previously
+  16 and 17 respectively); `lint`/`lint-skill` are asserted against their `scenario.py` passthrough
+  usage lines and skip cleanly when `python3` is absent.
+
+### Documentation
+
+- **`on_unanswered: prompt` was described as "only valid for `chat`" — wrong on two counts.** `chat`
+  never reads a scenario YAML (it runs an inline interactive scenario), and `prompt` is really a
+  `skill`-command policy (the adaptive-TTY default, or explicit `skill --on-unanswered prompt`);
+  `run` rejects it. The schema `.describe()` (and regenerated `scenario.schema.json`) now say so.
+- **`ANTHROPIC_AUTH_TOKEN` is an accepted auth source but was under-documented.** It resolves
+  identically to `ANTHROPIC_API_KEY` (used only when no OAuth token is set) and was already in
+  `.env.example`, but the README auth text, the `record`/`doctor` `--help` blurbs, the `doctor`
+  no-token detail/remedy, the two `record` credential messages, `docs/cassette.md`, and the companion
+  skill's Auth note named only the other two — all now list it as the third alternative.
+- **`llms.txt` exit-code line** now flags that `3`/`1` carry per-command meanings (e.g.
+  `verify-cassettes` `3` = could-not-verify, `sync` hard-fail = `1`) and links the authoritative
+  SPEC §11 text, instead of implying one global meaning for `3`.
+- **README** gains a platform × tier support matrix (making explicit that Linux live runs are
+  `container`-only), doc-index rows for the spawn contract and `docs/decisions/`, the
+  `probe-dispatch` fidelity set, and a clearer global-install-ships-`examples/replays/`-only warning;
+  `docs/chat.md` notes that scaffolding a `chat` run yields an empty `assert:` block.
+
+## [0.32.0] — 2026-07-13
+
+### Added
+
+- **`assertions --list` now documents that `subagent_dispatch_healthy`'s `type` matches the dispatch
+  description** (not just resolvedAgentType/dispatchAgentType), so a regex can narrow to one dispatch in a
+  same-agent-type fleet — previously only in `docs/scenario.md`.
+- **`analyze-skill` line- and block-scoped ignore markers** — `analyze-skill: ignore-next-line` and
+  `analyze-skill: ignore-start` / `analyze-skill: ignore-end`, alongside the existing file-wide
+  `analyze-skill: ignore`. The file-wide marker silences EVERY finding in the file, which was too coarse
+  for a SKILL.md that carries just one `/sessions`-addressed teaching example (e.g. a "don't do this"
+  callout in `references/`/`agents/`): the whole file went blind to any OTHER, genuine finding. The two
+  new markers suppress only the exact line (`ignore-next-line`) or fenced range (`ignore-start`/
+  `ignore-end`, inclusive) they scope, reusing the same line-anchored marker matching as the file-wide
+  marker (bare, `#`-prefixed, list-bullet, HTML comment, or markdown reference-link comment — never
+  triggered by a marker merely documented mid-prose). An `ignore-start` with no matching `ignore-end`
+  before EOF emits its own gating `unclosed-ignore-fence` finding — it still suppresses to EOF (fail-open),
+  but the missing-`ignore-end` mistake itself prints and fails under `--strict` like any other finding,
+  never a silent notice on a green exit.
+
+- **`analyze-skill <dir>` now scans the UNION of every contract-bearing markdown file in the directory,
+  not just `SKILL.md`.** A plugin's `/sessions` dispatch/output contracts often live in `agents/**` or
+  `references/**` — scanning only `SKILL.md` there was a false green (a consumer's `agents/sub/x.md`
+  could hand a `/sessions` path straight to a file tool and `analyze-skill` would never see it). A
+  directory target is now expanded to every shape it matches, deduped by resolved absolute path: a
+  top-level `SKILL.md` (+ its `references/**`); a plugin root (`.claude-plugin/plugin.json` or
+  `plugin.json`, + `agents/**`, `references/**`, `commands/**`, and each `skills/*/SKILL.md` + that
+  skill's own `references/**`); and a skill dir living inside a plugin also pulls in the enclosing
+  plugin's `agents/**`, `references/**`, and `commands/**`. Every walk is RECURSIVE (Claude Code discovers
+  namespaced commands/agents in subdirectories — `commands/tasks/build.md`, `agents/sub/x.md` — so a
+  single-level listing silently narrowed the scan) and FOLLOWS directory symlinks, loop-guarded against a
+  self-referencing symlink via a realpath visited-set, so a symlinked `references/`/`skills/<name>` is
+  scanned rather than silently dropped. Zero scannable files under a directory target is now a usage error
+  (exit 2) that enumerates the shapes it looked for — never a silent clean pass.
+
+- **`analyze-skill` accepts MULTIPLE positionals + a simple `*` glob, matching `lint-skill`'s
+  `nargs="+"`.** A consumer with several explicit paths (or a directory's flat `*.md` set) no longer has
+  to loop `analyze-skill` once per path: `analyze-skill a/SKILL.md b/SKILL.md`, `analyze-skill skill-a/
+  skill-b/`, and `analyze-skill "plug/agents/*.md"` are all one call now. Each positional resolves
+  independently — a file or directory via the existing rules above, or a `*`-bearing target via a small
+  HAND-ROLLED glob matcher (no new dependency, no `engines.node` bump): `dir/*.md` matches shallowly,
+  `dir/**/*.md` matches recursively (reusing the same symlink-following, loop-guarded walker the
+  directory-target union scan already uses). Every positional's files are UNIONed and deduped by
+  resolved absolute path across the WHOLE invocation, extending the existing single-target dedup to
+  span all of them — a file reached
+  both directly and through a dir/glob positional is analyzed once. Zero scannable files across ALL
+  positionals remains the usage error (exit 2); a bad single positional (missing path, unrecognized glob
+  shape) fails the whole invocation.
+
+### Changed (breaking, pre-1.0)
+
+- **`lint-skill`'s `subagent-type-not-found-in-plugin` finding is now WARN, not INFO** — so
+  `lint-skill --strict` newly gates on it. This is the one `subagent_type` outcome that's a *provable*
+  typo: a `<this-plugin>:<agent>` value whose prefix names the SKILL.md's own enclosing plugin, where
+  that plugin's `agents/*.md` was fully enumerated and doesn't contain the agent — the namespace prefix
+  already commits the value to this plugin, so a miss can never be another binary's built-in hiding
+  from static analysis. The other two `subagent_type` outcomes stay INFO, unchanged, because they
+  genuinely can't be disproven: `subagent-type-unresolvable` (a `<other-plugin>:<agent>` — belongs to
+  a plugin this linter didn't scan) and `subagent-type-unknown` (a bare value with no in-plugin match —
+  may be an agent-binary built-in). A `lint-skill --strict` run that previously passed clean may now
+  fail if it carries this exact typo shape; fix the agent name (or add the missing `agents/<agent>.md`)
+  to restore a clean `--strict` run.
+- **`analyze-skill <dir> --strict` may newly fail where it passed clean before**, if `references/`/
+  `agents/`/`commands/` carries a `/sessions`-addressed teaching example that the old SKILL.md-only scan
+  never looked at — including one nested under a subdirectory or reached only via a symlink, both now
+  scanned. Annotate the example with `analyze-skill: ignore-next-line` (or an `ignore-start`/`ignore-end`
+  fence) to restore a clean `--strict` run — there is no `--skill-md-only` compatibility flag; the
+  narrower scan was the bug this closes.
+- **`analyze-skill --output-format json`'s single-file shape changed.** The flat
+  `{file, findings, suppressed, strict}` payload is now always `{files: [{file, findings, suppressed}],
+  scanned, unscanned, strict}`, for uniformity with a directory target's multi-file result. An external
+  `jq '.findings'` / `jq '.file'` recipe needs `jq '.files[0].findings'` / `jq '.files[0].file'` instead.
+- **`analyze-skill`'s JSON envelope `ok` now mirrors the exit code, not "zero findings."** Previously
+  `ok = findings.length === 0`, so an ADVISORY run (the default — findings print but exit 0) reported
+  `ok:false` even though the process exited 0 and `action.yml`'s own documented contract (`ok` "mirrors
+  the command's exit code") said otherwise; the packaged Action's job-summary reporter then rendered
+  "Overall: ❌ fail" for a run that hadn't actually failed. `ok` is now `true` on an advisory exit-0 run
+  even with findings present, and `false` only under `--strict` with findings or the exit-2 usage error
+  — the same rule `lint`/`lint-skill --output-format json` follow (see the Fixed entry below). A `jq
+  '.ok'` consumer that was treating `ok:false` as "any findings at all" should switch to checking
+  `.files[].findings` directly; the exit code (and `ok`) now only reflect `--strict` gating.
+
+### Fixed
+
+- **The packaged Action's `lint`/`lint-skill` lanes were broken.** `action.yml` always appends
+  `--output-format json` to every command it drives, but the bundled `scenario.py`'s `lint`/`lint-skill`
+  only understand `--json` — `--output-format` was an unrecognized argument to python's argparse (exit 2,
+  empty stdout), so `command: lint` / `command: lint-skill` in the Action always failed with an
+  unhelpful `ok:false` and no findings. `cowork-harness lint`/`lint-skill` now detect json mode
+  themselves, strip `--output-format json|text|=…` before forwarding to python, pass python's own
+  `--json` in json mode, and re-wrap the child's bare findings array in the harness's standard
+  `jsonPayloadEnvelope("lint"/"lint-skill", ok, { findings })` (`ok` mirrors the child's exit code). Text
+  mode (the default) is unaffected in output — `stdio: "inherit"` as before — but now also strips the
+  flag first, since python didn't know the text form either. A python-level usage error in json mode
+  (e.g. a missing required path — argparse exit 2, empty stdout) now surfaces as a `jsonError("usage",
+  …)` envelope instead of a raw `JSON.parse` crash. `action.yml` also now documents `lint-skill` and
+  `analyze-skill` in its `command` input, and no longer forwards the replay-only `--fail-on-skill-drift`
+  flag to any command other than `replay`.
+
 ## [0.31.0] — 2026-07-12
 
 ### Added
@@ -26,6 +246,11 @@ All notable changes to this project are documented here. The format is based on
   `thinking[]` field is (~50 entries, ~10KB/entry each), with `reasoningElided` counting the overflow. A
   missing or malformed child transcript never fails the run — the affected dispatch's `reasoning` is just
   left absent.
+  - **Correction (see Unreleased):** in practice only the TEXT turns carry content — the harness's
+    non-interactive spawn forces the API's `thinking.display` to `"omitted"` for sub-agent turns, so
+    `thinking` turns come through empty (signature-only). The Unreleased `redacted` marker distinguishes
+    "reasoned, text omitted by request" from "no thought"; the "THINKING … turns" wording above
+    overstated what this captures by default.
 
 - **`status --latest-for <scenario-name-or-slug>`** — resolves and prints the NEWEST run dir for a
   scenario by actual run time, replacing the fragile `ls -td runs/<scenario>/* | head -1` idiom: bare