cowork-harness 4.9.0 → 4.9.1

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, asserting artifacts, egress, or sub-agent dispatch, measuring how long each tool call took (toolDurations / trace), or debugging a failed run or verdict from its result.json or transcript. 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. Also when iterating or hardening a skill across fixes, or grounding a skill's self-critique against its own run evidence — including a document-analysis skill (cap table, deck, financial model, transcript) that needs an uploaded file attached to be critiqued at all. Also for comparing two versions of a skill before merging an edit — did it make answers worse? (`eval`: paired A/B, pinned models) — or improving one round by round (`hillclimb`, the `/claude-api hillclimb` runner). 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 / critique / stats / eval / hillclimb commands and the session-vs-scenario split.
 metadata:
   author: cowork-harness
-  version: 4.9.0
-  tracks-harness: cowork-harness 4.9.0 (baseline desktop-2.31226.1)
+  version: 4.9.1
+  tracks-harness: cowork-harness 4.9.1 (baseline desktop-2.37337.1)
 ---
 
 # cowork-harness
@@ -26,8 +26,8 @@ allowlist). This skill exists mostly to keep you out of those traps — the *Inv
 full landmine catalog in [`references/gotchas.md`](references/gotchas.md) are the highest-value part.
 Read them.
 
-> **Version note:** the facts and `file:line` pointers here track `cowork-harness 4.9.0` (baseline
-> `desktop-2.31226.1`). 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 4.9.1` (baseline
+> `desktop-2.37337.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
@@ -43,7 +43,7 @@ Before the first command, confirm the CLI is reachable and **fail loud** (never
 
 - **One-shot check.** Run `cowork-harness doctor [--tier <tier>]` first — a read-only prerequisite check that inspects Docker, the staged agent, the token, the baseline and the `device_bridge` image (built, or built on the first bridge run) in one pass. The bullets below explain each thing it checks (and how to fix it).
 - **Replay-only? Skip `doctor`.** Replaying committed cassettes needs no Docker, no staged agent, and no token — and every tier's `doctor` validates the auth token (the live tiers also Docker + the staged agent), so a ✗ there is expected, not a blocker. Go straight to `cowork-harness replay <cassette>`.
-- **CLI on PATH, recent enough?** Run `cowork-harness --version` — this skill needs **≥ 4.9.0**. If it's missing or older, prefix every command with the version floor `npx "cowork-harness@^4.9.0" <cmd>` (Node ≥ 22), or install once with `npm i -g "cowork-harness@^4.9.0"`. **Pin `@^4.9.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.
+- **CLI on PATH, recent enough?** Run `cowork-harness --version` — this skill needs **≥ 4.9.1**. If it's missing or older, prefix every command with the version floor `npx "cowork-harness@^4.9.1" <cmd>` (Node ≥ 22), or install once with `npm i -g "cowork-harness@^4.9.1"`. **Pin `@^4.9.1`, 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.
 
   This skill documents the CURRENT surface, not release history. If `cowork-harness --version` is
   OLDER than the floor, the per-release record of what you are missing is [CHANGELOG.md](https://github.com/yaniv-golan/cowork-harness/blob/main/CHANGELOG.md)

package/.claude/skills/cowork-harness/references/assertion-catalog-agents-skills-budgets.md

@@ -1,6 +1,6 @@
 # Assertion catalog: sub-agents, skills and connectors, budgets, tasks, delivery
 
-Tracks `cowork-harness 4.9.0` (baseline `desktop-2.31226.1`). Part 2 of 3 of the per-key table. The conventions every key shares (an item with several
+Tracks `cowork-harness 4.9.1` (baseline `desktop-2.37337.1`). Part 2 of 3 of the per-key table. The conventions every key shares (an item with several
 keys is an AND; glob vs regex name matching) and the verdict-signal table are in
 [`assertion-catalog.md`](./assertion-catalog.md); the other parts are [`assertion-catalog-outcome-files-tools.md`](./assertion-catalog-outcome-files-tools.md), [`assertion-catalog-gates-hooks-modifiers.md`](./assertion-catalog-gates-hooks-modifiers.md).
 

package/.claude/skills/cowork-harness/references/assertion-catalog-gates-hooks-modifiers.md

@@ -1,6 +1,6 @@
 # Assertion catalog: gates, hooks, path denial, verdict modifiers, egress, judged keys
 
-Tracks `cowork-harness 4.9.0` (baseline `desktop-2.31226.1`). Part 3 of 3 of the per-key table. The conventions every key shares (an item with several
+Tracks `cowork-harness 4.9.1` (baseline `desktop-2.37337.1`). Part 3 of 3 of the per-key table. The conventions every key shares (an item with several
 keys is an AND; glob vs regex name matching) and the verdict-signal table are in
 [`assertion-catalog.md`](./assertion-catalog.md); the other parts are [`assertion-catalog-outcome-files-tools.md`](./assertion-catalog-outcome-files-tools.md), [`assertion-catalog-agents-skills-budgets.md`](./assertion-catalog-agents-skills-budgets.md).
 
@@ -17,7 +17,7 @@ refused at load: no question reaches the harness to grade.
 | `gate_answers_delivered: true` | every answered gate's answer reached the model (observed `tool_result`; unobserved = fail); **zero gates fired passes vacuously** — pair with `gate_answer_count_min: >= 1` to also require a gate, or drop this key and declare `questions_count_max: 0` in a scenario that expects none |
 | `gate_answers_delivered: false` | asserts at least one answered gate's answer was **confirmed not delivered** (an observed delivery failure); an unobserved/null delivery does **not** satisfy this — for negative-path delivery tests. Requires a gate, so **mutually exclusive** with `questions_count_max: 0` (refused by `run`/`skill`/`record`) |
 | `gate_answer_count_min: <N>` | at least N AskUserQuestion gates fired AND were delivered non-error — presence companion to `gate_answers_delivered`'s vacuous-pass. **`: 0` asserts nothing** and does not satisfy that pairing; `>= 1` is **mutually exclusive** with `questions_count_max: 0` (refused by `run`/`skill`/`record`) |
-| `gates_all_scripted: true \| {include_permissions: true}` | every AskUserQuestion gate that fired was answered by a scripted rule (`answers:` / `--answer`) — not the LLM decider, `first`, or an external or human decider; a failure names each such gate and who answered it. A gate asked but never answered fails. **Evidence:** the run's decisions — a result with no decisions record, or an answer with no recognisable source, fails evidence-unavailable, never passes. On replay each gate is re-classified against the cassette's frozen `answers:`; that is evidence-unavailable when those answers were redacted, or when the cassette records that a live decider answered a gate yet its frozen rules cover every gate (they are not the rules it recorded with). **`{include_permissions: true}`** also checks tool permissions: a scripted `when_tool` rule or a fixed rule counts (a Read/Glob/Grep registry allow, a strict-parity deny, the harness's own path-gate deny, the fail-closed deny when nothing answered live — on replay that row means the recording held no answer, evidence-unavailable); a web_fetch deny that no answer source decided fails (`answered by abstain-fallback`), because real Cowork asks the user (under the default `on_unanswered: fail` such a fetch ends the run as an unanswered gate before any deny, so this arises only under `first` or `llm`); cowork parity's permissive off-registry auto-allow never does, and a replayed web_fetch permission cannot be attributed (evidence-unavailable). Zero gates passes (nothing needed a person), so pair it with `gate_answer_count_min: >= 1` or `questions_count_max` to state whether gates were expected (`lint` warns `unpaired-gates-all-scripted`). |
+| `gates_all_scripted: true \| {include_permissions: true}` | every AskUserQuestion gate that fired was answered by a scripted rule (`answers:` / `--answer`) — not the LLM decider, `first`, or an external or human decider; a failure names each such gate and who answered it. A gate asked but never answered fails. **Evidence:** the run's decisions — a result with no decisions record, or an answer with no recognisable source, fails evidence-unavailable, never passes. On replay each gate is re-classified against the cassette's frozen `answers:`; that is evidence-unavailable when those answers were redacted, or when the cassette records that a live decider answered a gate yet its frozen rules cover every gate (they are not the rules it recorded with). **`{include_permissions: true}`** also checks tool permissions: a scripted `when_tool` rule or a fixed rule counts (a Read/Glob/Grep registry allow, a strict-parity deny, the harness's own path-gate deny, the fail-closed deny when nothing answered live — on replay that row means the recording held no answer, evidence-unavailable); a web_fetch deny that no answer source decided fails (`answered by abstain-fallback`), because real Cowork asks the user (under the default `on_unanswered: fail` such a fetch ends the run as an unanswered gate before any deny, so this arises only under `first`: the LLM decider always picks a button or fails the run); cowork parity's permissive off-registry auto-allow never does, and a replayed web_fetch permission cannot be attributed (evidence-unavailable). Zero gates passes (nothing needed a person), so pair it with `gate_answer_count_min: >= 1` or `questions_count_max` to state whether gates were expected (`lint` warns `unpaired-gates-all-scripted`). |
 | `hook_blocked: <regex>` | one of the harness's own PreToolUse hook callbacks blocked a tool whose name matches the regex (`RunResult.hookEvents`; a plugin's hook never reaches it: use `hook_event_blocked`) — evidence-unavailable if hook telemetry is absent. Replay: needs a `controlOut` cassette (a custom hook's decision lives only there, not the recorded stream). **Does not see the agent's own refusal**: on `hostloop` against Desktop 2.7032.0+ a relative `Read`/`Write`/`Edit` is denied by the agent's permission rules before any hook runs, so neither this key nor `path_denied` records it — assert it with `tool_result_contains: "denied by your permission settings"` |
 | `no_hook_blocked: true` | no tool was blocked by the harness's own hook callbacks (a plugin's hook never reaches it: use `no_hook_event_blocked`) (distinguishes a real tool crash from an intentional hook block) — evidence-unavailable if hook telemetry is absent. Replay: needs a `controlOut` cassette. **Only `true` is valid** |
 | `hook_event_fired: <HookEvent>` | a **command hook** for this event (a plugin's `hooks/hooks.json` or manifest hook — `Stop`, `SessionStart`, `PostToolUse`, …) ran: a `hook_response` system frame with that `hook_event` was recorded (`RunResult.contextEvents`). Any outcome counts. The harness passes `--include-hook-events` whenever a staged plugin declares hooks — that is what puts events other than SessionStart/Setup on the stream — so a recording made without it reports "never fired". Content-class, grades on replay. Recorded end-to-end for `Stop` ([stop-hook-probe.scenario.yaml](https://github.com/yaniv-golan/cowork-harness/blob/main/examples/probes/stop-hook-probe.scenario.yaml)) and for `PreToolUse` at `container` (deciding by JSON and by exit 2); the other names match the same frame but have not each been recorded |

package/.claude/skills/cowork-harness/references/assertion-catalog-outcome-files-tools.md

@@ -1,6 +1,6 @@
 # Assertion catalog: outcome, transcript, files and artifacts, tools, tool results
 
-Tracks `cowork-harness 4.9.0` (baseline `desktop-2.31226.1`). Part 1 of 3 of the per-key table. The conventions every key shares (an item with several
+Tracks `cowork-harness 4.9.1` (baseline `desktop-2.37337.1`). Part 1 of 3 of the per-key table. The conventions every key shares (an item with several
 keys is an AND; glob vs regex name matching) and the verdict-signal table are in
 [`assertion-catalog.md`](./assertion-catalog.md); the other parts are [`assertion-catalog-agents-skills-budgets.md`](./assertion-catalog-agents-skills-budgets.md), [`assertion-catalog-gates-hooks-modifiers.md`](./assertion-catalog-gates-hooks-modifiers.md).
 

package/.claude/skills/cowork-harness/references/assertion-catalog.md

@@ -1,6 +1,6 @@
 # Assertion catalog
 
-Tracks `cowork-harness 4.9.0` (baseline `desktop-2.31226.1`). Every `assert:` key with its semantics, and the
+Tracks `cowork-harness 4.9.1` (baseline `desktop-2.37337.1`). Every `assert:` key with its semantics, and the
 verdict-signal table. Which keys survive `replay` is in [`scenario-schema.md`](./scenario-schema.md#replay-class);
 the scenario and session YAML fields are there too.
 

package/.claude/skills/cowork-harness/references/assertions-guide.md

@@ -1,6 +1,6 @@
 # Assertions guide
 
-Tracks `cowork-harness 4.9.0` (baseline `desktop-2.31226.1`). Read it when choosing assertion keys: the two orthogonal axes and the goal → key map. The full catalog starts at `assertion-catalog.md`, which indexes the per-family files that hold every key's row.
+Tracks `cowork-harness 4.9.1` (baseline `desktop-2.37337.1`). Read it when choosing assertion keys: the two orthogonal axes and the goal → key map. The full catalog starts at `assertion-catalog.md`, which indexes the per-family files that hold every key's row.
 
 ### Assertions: two orthogonal axes
 

package/.claude/skills/cowork-harness/references/authoring.md

@@ -1,6 +1,6 @@
 # Authoring a scenario
 
-Tracks `cowork-harness 4.9.0` (baseline `desktop-2.31226.1`). Read it when composing a `scenarios/*.yaml`: session vs scenario, discovery, the fidelity tier, the answer path, `web_fetch`, and scaffold + lint.
+Tracks `cowork-harness 4.9.1` (baseline `desktop-2.37337.1`). Read it when composing a `scenarios/*.yaml`: session vs scenario, discovery, the fidelity tier, the answer path, `web_fetch`, and scaffold + lint.
 
 ## Part I — AUTHOR a scenario
 

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 4.9.0` (baseline `desktop-2.31226.1`).
+Self-contained reference. Tracks `cowork-harness 4.9.1` (baseline `desktop-2.37337.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):
@@ -17,7 +17,7 @@ job-summary reporter (verdict table, staleness findings, cost/turns when availab
 CLI major reaches your workflow the moment it is promoted even though your `uses:` ref never changed — so a
 copy-pasted recipe that omits the input takes a major bump with no say in it. `^4` holds the major, needs no
 patch number to remember, and only wants a human decision at the next major. Pin an exact version
-(e.g. `version: "4.9.0"`) instead when you want byte-reproducible CI.
+(e.g. `version: "4.9.1"`) instead when you want byte-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
@@ -82,7 +82,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@^4.9.0"
+- run: npm i -g "cowork-harness@^4.9.1"
 - run: cowork-harness lint scenarios/*.yaml --strict --min-severity WARN
                                                     # no silent false-greens. WITHOUT --strict this
                                                     # step cannot fail on a WARN-class rule (e.g.
@@ -411,7 +411,7 @@ jobs:
         with: { node-version: '24' }
       - uses: actions/setup-python@v5
         with: { python-version: '3.x' }                                       # python3 only — PyYAML is bundled with the linter
-      - run: npm i -g "cowork-harness@^4.9.0"
+      - run: npm i -g "cowork-harness@^4.9.1"
       - 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
@@ -440,7 +440,7 @@ jobs:
             echo "live=true" >> "$GITHUB_OUTPUT"
           fi
       - if: steps.guard.outputs.live == 'true'
-        run: npm i -g "cowork-harness@^4.9.0"
+        run: npm i -g "cowork-harness@^4.9.1"
       - if: steps.guard.outputs.live == 'true'
         run: cowork-harness run scenarios/ --output-format json
         env:

package/.claude/skills/cowork-harness/references/critique.md

@@ -1,6 +1,6 @@
 # Critique — the facts a plugin install can't otherwise reach
 
-Tracks `cowork-harness 4.9.0` (baseline `desktop-2.31226.1`). This is **not** a trim of the full
+Tracks `cowork-harness 4.9.1` (baseline `desktop-2.37337.1`). This is **not** a trim of the full
 [`docs/critique.md`](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/critique.md) (repo-only —
 flags, cost, reading several critiques, known limitations all live there). This file covers exactly what a
 plugin install cannot otherwise discover: the run-dir artifact a harvester actually reads, the report's

package/.claude/skills/cowork-harness/references/debugging.md

@@ -1,6 +1,6 @@
 # Debugging a run
 
-Tracks `cowork-harness 4.9.0` (baseline `desktop-2.31226.1`). Read it when a run misbehaved or a green looks wrong: triage, the observability output, and `chat`.
+Tracks `cowork-harness 4.9.1` (baseline `desktop-2.37337.1`). Read it when a run misbehaved or a green looks wrong: triage, the observability output, and `chat`.
 
 ## Part III — Debug
 
@@ -35,6 +35,13 @@ received a question or permission request anyway; `events.jsonl` and `control-ou
 already does.
 <!-- END triage-canonical -->
 
+**A multi-leg run (`legs:`) is read one leg at a time.** `trace`, `verify-run` and `regrade` take
+`--leg <id>` (or the leg dir `<root>/legs/<id>` itself); `inspect` and `fixture export` take the leg dir. A
+multi-leg root without `--leg` is refused, and `trace` / `inspect` name its legs. A host-action leg has no
+agent session and is refused too — its record is `legs/<id>/action.json`. `search-pool build --from <root>` is the
+exception: it reads every prompt leg of the root, each as its own source run. See
+[docs/scenario.md → Multi-leg scenarios](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/scenario.md#multi-leg-scenarios-legs).
+
 **`verify-run` never calls the semantic judge**, so it cannot re-grade a `semantic_matches` or `semantic_pairwise` assert. When the
 rubric changed (or you want another judge model) on a run you already paid for, use
 `cowork-harness regrade <run-dir> --scenario <scenario.yaml>` instead: it re-grades those asserts against the

package/.claude/skills/cowork-harness/references/eval.md

@@ -1,6 +1,6 @@
 # `eval` — paired before/after comparison of a skill edit (EXPERIMENTAL)
 
-Tracks `cowork-harness 4.9.0` (baseline `desktop-2.31226.1`). The full guide is
+Tracks `cowork-harness 4.9.1` (baseline `desktop-2.37337.1`). The full guide is
 [docs/eval.md](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/eval.md); this is the part you
 need while running it.
 

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

@@ -1,6 +1,6 @@
 # Fidelity tiers & answer paths
 
-Self-contained reference. Tracks `cowork-harness 4.9.0` (baseline `desktop-2.31226.1`).
+Self-contained reference. Tracks `cowork-harness 4.9.1` (baseline `desktop-2.37337.1`).
 
 > **This page vs. the repo docs.** This is the **offline snapshot** that ships inside the installed
 > plugin — it is self-contained on purpose. The repo carries four other fidelity views, each answering a

package/.claude/skills/cowork-harness/references/gotchas.md

@@ -1,6 +1,6 @@
 # Gotchas
 
-Tracks `cowork-harness 4.9.0` (baseline `desktop-2.31226.1`). The full "✓ passed ≠ correct" landmine catalog.
+Tracks `cowork-harness 4.9.1` (baseline `desktop-2.37337.1`). The full "✓ passed ≠ correct" landmine catalog.
 
 ## Gotchas — the "✓ passed ≠ correct" landmines
 

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

@@ -1,6 +1,6 @@
 # Recipe 7 — Climb a skill with `/claude-api hillclimb` and the harness as its runner
 
-Tracks `cowork-harness 4.9.0` (baseline `desktop-2.31226.1`). It needs a `cowork-harness` whose
+Tracks `cowork-harness 4.9.1` (baseline `desktop-2.37337.1`). It needs a `cowork-harness` whose
 `hillclimb --help` lists `--skill` (help goes to stderr). This page is the loop's procedure, step by step, in the order of the
 `/claude-api hillclimb` guide. Every mechanic (flags, refusals, the gate, `regrade`, `freeze-ref`, exit codes,
 row keys) is in [`hillclimb.md`](hillclimb.md); the setup and the full list of differences from the guide's own

package/.claude/skills/cowork-harness/references/hillclimb.md

@@ -1,6 +1,6 @@
 # `hillclimb` — the runner for a `/claude-api hillclimb` loop
 
-Tracks `cowork-harness 4.9.0` (baseline `desktop-2.31226.1`). It needs a `cowork-harness` whose
+Tracks `cowork-harness 4.9.1` (baseline `desktop-2.37337.1`). It needs a `cowork-harness` whose
 `hillclimb --help` lists `--skill` (help goes to stderr). The command reference is
 [docs/cli.md](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/cli.md); this is the part a loop needs
 while it runs. It covers `run`, `check`, `state-template`, `freeze-ref` and `regrade`.
@@ -254,8 +254,9 @@ and rewrites each row through the same producer `run` writes it with. Pass the s
 `COWORK_HARNESS_RUNS_DIR` the runs were written with, or every row is listed as having no kept run dir. A runs root
 moved to where `--run-dir` now points is read from there; a COPY of it while the original still exists is refused
 row by row (point `--run-dir` at the original root instead). A bare
-`prune` keeps hillclimb-labelled runs; `prune --include-hillclimb` deletes them for every flow under the runs root,
-a loop still running included, and `freeze-ref` re-reads a frozen reference's source run, so pass it only once
+`prune` keeps hillclimb-labelled runs; `prune --include-hillclimb` ranks them with every other run under
+`--keep-last`, so the runs of every flow under the runs root, a loop still running included, can lose the ones
+a later re-grade or reference freeze needs (freezing a reference re-reads its source run). Pass it only once
 every climb there is finished.
 
 - **Default:** the row is rebuilt from the scenario as it is now, so a changed value, an added or a removed assert

package/.claude/skills/cowork-harness/references/measurement.md

@@ -1,6 +1,6 @@
 # Measurement
 
-Tracks `cowork-harness 4.9.0` (baseline `desktop-2.31226.1`). Read it before comparing runs: `--repeat`, `--ablate-skill`, and the hygiene that keeps a batch valid.
+Tracks `cowork-harness 4.9.1` (baseline `desktop-2.37337.1`). Read it before comparing runs: `--repeat`, `--ablate-skill`, and the hygiene that keeps a batch valid.
 
 ### Measure — before/after, with/without (`--repeat`, `--ablate-skill`)
 

package/.claude/skills/cowork-harness/references/run-record-replay.md

@@ -1,6 +1,6 @@
 # Run, record and lock
 
-Tracks `cowork-harness 4.9.0` (baseline `desktop-2.31226.1`). Read it when running a scenario, recording or placing a cassette, reading verdict signals, checking a background run, or choosing CI lanes.
+Tracks `cowork-harness 4.9.1` (baseline `desktop-2.37337.1`). Read it when running a scenario, recording or placing a cassette, reading verdict signals, checking a background run, or choosing CI lanes.
 
 ## Part II — RUN, RECORD & LOCK
 
@@ -229,7 +229,7 @@ Recognize these before "fixing" a non-bug:
   `markitdown`/`magika` (`ml_extract`), `cv2` (`cv`), `camelot`/`tabula` (`pdf_tables`), or `wand`
   (`magick`) can trip this even though real Cowork **ships** those (per the rootfs manifest captured at
   Desktop `2.9939.2` — `baselines/provisioning/rootfs-provisioning.json`, which is the dated evidence
-  behind that sentence; 8 baselines have shipped since without a re-capture). The message says so ("likely a FALSE
+  behind that sentence; 9 baselines have shipped since without a re-capture). The message says so ("likely a FALSE
   NEGATIVE (real Cowork ships them)"). Fix: rebuild full parity (`--build-arg COWORK_FULL_PARITY=1`, point
   `COWORK_AGENT_IMAGE` at it), or — if the skill's fallback is genuinely equivalent — assert
   `allow_missing_capability: true`. (Two sources: a skill *observed using* an omitted family, live lane;
@@ -439,11 +439,13 @@ with the ordinary commands, one scenario at a time:
   `trace <root | run-id> --leg <id>`, `inspect <root>/legs/<id>`. A prompt leg is read from its snapshot
   (`legs/<id>/snapshot/`, its files as they were when it ended), so every prompt leg of a kept run re-grades at no
   cost (a host-action leg has no session and is refused). The snapshot is a copy-on-write clone where the filesystem
-  supports one (APFS, btrfs, XFS with reflink), costing almost no disk until a later leg changes a file, and
-  otherwise (ext4, the usual Linux and CI disk) a full copy of the leg's outputs and connected folders, per prompt
-  leg; `snapshot.json` records which as `method` (`clone`, `copy`, `mixed` or `none`), and `leg-post-manifest.json`
+  supports one (macOS APFS through `cp -c`, only when the folder is on the same volume as the run dir; Linux btrfs,
+  XFS with reflink), costing almost no disk until a later leg changes a file, and otherwise (ext4, the usual Linux and
+  CI disk, or a folder on another volume) a full copy of the leg's outputs and connected folders, per prompt leg;
+  `snapshot.json` records which as `method` (`clone`, `copy`, `mixed` — one folder cloned, another copied — or
+  `none`), on macOS `fallback` says why a folder was copied rather than cloned, and `leg-post-manifest.json`
   holds the hashes that prove it is the leg's own. A leg over `COWORK_HARNESS_LEG_SNAPSHOT_MAX_BYTES` (default
-  512 MiB; a malformed value is refused before the run) gets no snapshot. A leg with no usable snapshot falls back to its session tree and is refused when a later leg changed that tree. A
+  512 MiB; a malformed value is refused before the run) gets no snapshot. A leg with no usable snapshot falls back to its session tree. Under `workdir: persistent` only the last leg of a finished scenario can use it (later legs changed the shared tree); every other leg is refused. That last leg, and every `cowork-task` leg, is refused when its tree changed after the leg ended, or when there is no post-run manifest to check it against. A
   multi-leg root without `--leg` is refused, naming the legs.
 
 Full rules: [docs/scenario.md → "Multi-leg scenarios"](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/scenario.md#multi-leg-scenarios-legs).
@@ -467,8 +469,10 @@ Full rules: [docs/scenario.md → "Multi-leg scenarios"](https://github.com/yani
   path unless `--allow-host-paths` (a path into a run dir or a guest session is refused regardless).
   `--session-paths` tokenises this run's own session roots instead of refusing them, and staging writes the new
   run's roots in (hostloop, container, microvm); `--exclude <path>` drops a file.
-- `prune [--keep-last <n>] [--pinned-older-than <N>d]` removes old run dirs (default `--keep-last 5`);
-  `--dry-run` previews it.
+- `prune [--keep-last <n>] [--pinned-older-than <N>d|h|m] [--include-hillclimb]` removes old run dirs (default
+  `--keep-last 5`); `--dry-run` previews it. Hillclimb-labelled runs are kept outside `--keep-last`;
+  `--include-hillclimb` ranks them with the rest, so every flow's runs under the runs root (a running climb
+  included) can lose the ones `hillclimb regrade` / `freeze-ref` need; pass it only once every climb there is finished.
 
 ### Place assertions in the right CI lane
 

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

@@ -1,7 +1,7 @@
 # Scenario & session schema, replay class, web_fetch, authoring gotchas
 
-Self-contained reference for authoring `cowork-harness` scenarios. Tracks `cowork-harness 4.9.0`
-(baseline `desktop-2.31226.1`). If your checkout is newer, prefer the live [`docs/scenario.md`](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/scenario.md),
+Self-contained reference for authoring `cowork-harness` scenarios. Tracks `cowork-harness 4.9.1`
+(baseline `desktop-2.37337.1`). If your checkout is newer, prefer the live [`docs/scenario.md`](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/scenario.md),
 [`docs/session.md`](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/session.md), and `SPEC.md`.
 
 **Minimal scenario** — `prompt` and `fidelity` are required:
@@ -156,6 +156,8 @@ metrics:                            # OPTIONAL — numbers read from JSON files
                                     # run as `<script> <events-file> [args]` over this turn's scrubbed slice of
                                     # events.jsonl; it must print exactly one JSON number. Script + deps: regular,
                                     # git-tracked files inside the scenario's repo (no symlink, no hard link, <= 1 MiB).
+                                    # `timeout_ms`: the script's wall-clock limit per run (1000-300000, default
+                                    # 30000; command only — refused on an artifact metric), past it command_timeout.
                                     # RUNS THE REPO'S CODE AS YOU (only repos you would `npm test`). Live runs run it;
                                     # replay reports the frozen record-time value (cassette v18); verify-run / regrade /
                                     # hillclimb regrade carry it forward unless --allow-metric-commands. Its own reasons:

package/.claude/skills/cowork-harness/references/semantic-judging.md

@@ -1,6 +1,6 @@
 # `semantic_matches` — the full semantics
 
-Tracks `cowork-harness 4.9.0` (baseline `desktop-2.31226.1`). The one-line summary is in
+Tracks `cowork-harness 4.9.1` (baseline `desktop-2.37337.1`). The one-line summary is in
 [assertion-catalog-gates-hooks-modifiers.md](assertion-catalog-gates-hooks-modifiers.md); this is the whole contract, split out so the catalog stays within the
 agent's single-read size.
 

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.
-Tracks `cowork-harness 4.9.0` (baseline `desktop-2.31226.1`), same as SKILL.md's front-matter. Recipe 2's `resolved-tier`/`unverifiable-tier` staleness classes and
+Tracks `cowork-harness 4.9.1` (baseline `desktop-2.37337.1`), same as SKILL.md's front-matter. 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.
 
@@ -62,7 +62,7 @@ Top-level fields of a `*.cassette.json` (schema [`schema/cassette.v18.json`](htt
 
 | Field | What it is |
 |---|---|
-| `$schema`, `generator`, `cassetteVersion` | Provenance: schema URL, producing tool, format version — the MINIMUM a reader needs for this scenario, not the recorder's version (current max: 18 — the hash-format epoch floors every stamp at 12, so a fresh recording stamps 12 unless a key lifts it: 13 when its `assert:` uses the object form of `tool_called` / `tool_not_called`, 14 for a v14 key such as `include_fork_results` on `semantic_matches`, 15 for a v15 one such as `gates_all_scripted`, a glob `artifact_json`, an `artifact_json` carrying `schema`, any `artifact_json` on `lane: remote`, or a recording under `answer_channel: none`, 16 for a recording whose `hookFailureBlocks` lists an event or is unknown, 18 for a scenario with `device_bridge: true` (a v17 bridge recording still reads) or one declaring a command metric (its record-time values frozen in `commandMetrics`); the full list is in the cassette docs' version table) |
+| `$schema`, `generator`, `cassetteVersion` | Provenance: schema URL, producing tool, format version — the MINIMUM a reader needs for this scenario, not the recorder's version (current max: 18 — the hash-format epoch floors every stamp at 12, so a fresh recording stamps 12 unless a key lifts it: 13 when its `assert:` uses the object form of `tool_called` / `tool_not_called`, 14 for a v14 key such as `include_fork_results` on `semantic_matches`, 15 for a v15 one such as `gates_all_scripted`, a glob `artifact_json`, an `artifact_json` carrying `schema`, any `artifact_json` on `lane: remote`, or a recording under `answer_channel: none`, 16 for a recording whose `hookFailureBlocks` lists an event or is unknown, 18 for a scenario with `device_bridge: true` (a v17 bridge recording still reads) or one declaring a command metric (its record-time values frozen in `commandMetrics`), and for a multi-leg (`legs:`) scenario; the full list is in the cassette docs' version table) |
 | `scenario` | The embedded scenario snapshot at record time |
 | `events` | The recorded agent event stream (the replay source) |
 | `legs`, `verdict` | Multi-leg form only (a `legs:` scenario, v18), in place of `events`: `legs[]` holds one entry per leg in order — a prompt leg nests its own complete single-prompt cassette under `cassette`, a host action its record under `action`, a leg after a failing one `status: "skipped"` — and `verdict.pass` is the scenario verdict at record time. `replay` and `verify-cassettes` read this form; other cassette readers refuse it by name |
@@ -521,6 +521,8 @@ cowork-harness search-pool export market-sizing --out ~/market-sizing-pool.json
 cowork-harness search-pool import ~/market-sizing-pool.json market-sizing-copy             # re-verifies both hashes
 ```
 
+- **Multi-leg runs.** A multi-leg run under a `--from` dir adds each prompt leg as its own source run (`legs/<id>/`);
+  a host-action leg has no searches.
 - **One skill per pool.** A run whose skill differs from the others, or that names no single skill, is refused. Pass
   `--skill <name>` to name the skill for runs that name none, or `--mixed` for a pool of several skills (a measured
   variant, never a baseline).
@@ -548,5 +550,4 @@ Copy [the resumable-probe scenario](https://github.com/yaniv-golan/cowork-harnes
 - Re-grade or read one leg with `--leg <id>`: `verify-run <run-dir> <legs.yaml> --leg <id>`,
   `regrade <run-dir> --scenario <legs.yaml> --leg <id>`, `trace <run-dir | run-id> --leg <id>`. Each prompt leg is read
   from its own snapshot (its files as they stood when it ended; a clone where the filesystem supports one, else a
-  full copy, so budget disk on ext4 and CI), so it re-grades at no cost. A leg too large to snapshot falls back to its
-  session tree and is refused once a later leg changed it; a host-action leg is refused.
+  full copy, so budget disk on ext4 and CI), so it re-grades at no cost. A leg too large to snapshot falls back to its session tree. Under `workdir: persistent` only the last leg of a finished scenario can use it (later legs changed the shared tree); every other leg is refused. That last leg, and every `cowork-task` leg, is refused when its tree changed after the leg ended, or when there is no post-run manifest to check it against; a host-action leg is refused.

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

@@ -272,16 +272,24 @@ VERDICT_MODIFIER_KEYS = {
 _CLASSIFIED_KEYS = CONTENT_KEYS | GATE_KEYS | MANIFEST_KEYS | LIVE_ONLY_KEYS | VERDICT_MODIFIER_KEYS | {"replay_protocol_fidelity"}
 
 
+def _str_list(v, name):
+    """`v` as a list of strings, or a TypeError naming the field: a string where a key list belongs would otherwise
+    be iterated as characters, and the loaders fall back to their embedded copies on any error."""
+    if not isinstance(v, list) or not all(isinstance(x, str) for x in v):
+        raise TypeError(f"assertion-keys.json {name} is not a list of strings")
+    return v
+
+
 def _load_assert_keys():
     """The authoritative `assert:` key set, generated from the Zod Assertion schema into a sibling
     `assertion-keys.json` (so the unknown-key check can't drift). Falls back to the embedded
     `_CLASSIFIED_KEYS` (kept equal to the generated list) with a loud warning if the file is missing."""
     p = Path(__file__).resolve().parent / "assertion-keys.json"
     try:
-        return set(json.loads(p.read_text(encoding="utf-8"))["keys"])
-    except Exception:
+        return set(_str_list(json.loads(p.read_text(encoding="utf-8"))["keys"], "keys"))
+    except Exception as e:
         print(
-            f"::warning:: assertion-keys.json not found next to scenario.py ({p}) — "
+            f"::warning:: assertion-keys.json missing or malformed next to scenario.py ({p}): {e} — "
             "using a built-in key list that may be stale (run `npm run schema`).",
             file=sys.stderr,
         )
@@ -344,22 +352,35 @@ def _load_hook_events():
     p = Path(__file__).resolve().parent / "assertion-keys.json"
     try:
         d = json.loads(p.read_text(encoding="utf-8"))
-        served, known = set(d["servedHookEvents"]), set(d["knownHookEvents"])
-        # Tolerate a sidecar generated before liveVerifiedHookEvents existed: fall back rather than
-        # dropping to the embedded KNOWN set wholesale, which would undo the 33-name fix. Membership
-        # test, NOT truthiness: an explicitly EMPTY list means the firing receipt was withdrawn, and
-        # `or` would silently restore the 3-name claim -- widening a receipt, which is the one direction
-        # this constant exists to prevent.
-        live = set(d["liveVerifiedHookEvents"]) if "liveVerifiedHookEvents" in d else set(_FALLBACK_LIVE_VERIFIED_HOOK_EVENTS)
-        if served and known:
-            return served, known, live
-    except Exception:
-        pass
-    return (
-        set(_FALLBACK_SERVED_HOOK_EVENTS),
-        set(_FALLBACK_KNOWN_HOOK_EVENTS),
-        set(_FALLBACK_LIVE_VERIFIED_HOOK_EVENTS),
-    )
+        served = set(_str_list(d["servedHookEvents"], "servedHookEvents"))
+        known = set(_str_list(d["knownHookEvents"], "knownHookEvents"))
+        if not (served and known):
+            raise ValueError("servedHookEvents or knownHookEvents is empty")
+    except Exception as e:
+        print(
+            f"::warning:: assertion-keys.json missing or malformed next to scenario.py ({p}): {e} — "
+            "using built-in hook-event lists that may be stale (run `npm run schema`).",
+            file=sys.stderr,
+        )
+        return (
+            set(_FALLBACK_SERVED_HOOK_EVENTS),
+            set(_FALLBACK_KNOWN_HOOK_EVENTS),
+            set(_FALLBACK_LIVE_VERIFIED_HOOK_EVENTS),
+        )
+    # Tolerate a sidecar generated before liveVerifiedHookEvents existed: fall back rather than
+    # dropping to the embedded KNOWN set wholesale, which would undo the 33-name fix. Membership
+    # test, NOT truthiness: an explicitly EMPTY list means the firing receipt was withdrawn, and
+    # `or` would silently restore the 3-name claim -- widening a receipt, which is the one direction
+    # this constant exists to prevent. For the same reason a MALFORMED list verifies nothing: falling
+    # back to the built-in list there would widen a receipt the sidecar does not give.
+    if "liveVerifiedHookEvents" not in d:
+        return served, known, set(_FALLBACK_LIVE_VERIFIED_HOOK_EVENTS)
+    try:
+        live = set(_str_list(d["liveVerifiedHookEvents"], "liveVerifiedHookEvents"))
+    except TypeError as e:
+        print(f"::warning:: {e} ({p}) — treating no hook event as live-verified (run `npm run schema`).", file=sys.stderr)
+        live = set()
+    return served, known, live
 
 
 SERVED_HOOK_EVENTS, KNOWN_HOOK_EVENTS, LIVE_VERIFIED_HOOK_EVENTS = _load_hook_events()
@@ -410,7 +431,7 @@ _EMBEDDED_TOP_LEVEL_KEYS = {
     "allow_host_writes",
     "allow_host_hooks",  # protocol consent: a staged plugin's hooks run as NATIVE HOST processes  # hostloop native-split: consent for a writable connected folder (pre-run gate)
     "workspace_fixture",  # a saved outputs tree staged into outputs/ before turn 1 (scenario-file-relative dir)
-    "metrics",  # numbers read from JSON files the run wrote, reported beside the verdict (RunResult.metrics)
+    "metrics",  # numbers read from JSON files the run wrote or printed by a command metric's script, reported beside the verdict (RunResult.metrics)
 }
 
 
@@ -424,10 +445,10 @@ def _load_top_level_keys():
         keys = json.loads(p.read_text(encoding="utf-8")).get("topLevelKeys")
         if not keys:
             raise KeyError("topLevelKeys")
-        return set(keys)
-    except Exception:
+        return set(_str_list(keys, "topLevelKeys"))
+    except Exception as e:
         print(
-            f"::warning:: assertion-keys.json missing or has no topLevelKeys next to scenario.py ({p}) — "
+            f"::warning:: assertion-keys.json missing, malformed or without topLevelKeys next to scenario.py ({p}): {e} — "
             "using a built-in top-level-key list that may be stale (run `npm run schema`).",
             file=sys.stderr,
         )
@@ -500,14 +521,26 @@ def _load_enums():
         enums = json.loads(p.read_text(encoding="utf-8")).get("enums")
         if not enums:
             raise KeyError("enums")
-        return enums
-    except Exception:
+        if not isinstance(enums, dict):
+            raise TypeError("assertion-keys.json enums is not a map")
+    except Exception as e:
         print(
-            f"::warning:: assertion-keys.json missing or has no enums next to scenario.py ({p}) — "
+            f"::warning:: assertion-keys.json missing, malformed or without enums next to scenario.py ({p}): {e} — "
             "using a built-in enum-value map that may be stale (run `npm run schema`).",
             file=sys.stderr,
         )
         return dict(_EMBEDDED_ENUMS)
+    # Each field's values must be a list of strings: a string value would turn the membership test into a substring
+    # test, and anything else would crash the lint. A malformed field falls back to its built-in values alone.
+    out = {}
+    for field, values in enums.items():
+        try:
+            out[field] = _str_list(values, f"enums.{field}")
+        except TypeError as e:
+            print(f"::warning:: {e} ({p}) — using its built-in values (run `npm run schema`).", file=sys.stderr)
+            if field in _EMBEDDED_ENUMS:
+                out[field] = list(_EMBEDDED_ENUMS[field])
+    return out
 
 
 # field id -> allowed values (generated from the zod schemas; see _load_enums)
@@ -1484,8 +1517,8 @@ def _hook_block_contradictions(items):
 
 # A multi-leg (`legs:`) scenario: these top-level keys, and per-leg prompt/host_action/session/assert. Kept equal to
 # MultiLegScenarioObject (src/run/multi-leg-scenario.ts); the harness loader is the authority and runs first under
-# the `cowork-harness lint` wrapper.
-_MULTI_LEG_TOP_KEYS = {
+# the `cowork-harness lint` wrapper. Read from the generated assertion-keys.json at run time; this is its fallback.
+_EMBEDDED_MULTI_LEG_TOP_KEYS = {
     "name",
     "baseline",
     "session",
@@ -1502,6 +1535,24 @@ _MULTI_LEG_TOP_KEYS = {
     "allow_host_hooks",
     "workspace_fixture",
 }
+
+
+def _load_multi_leg_top_keys():
+    """A multi-leg scenario's top-level keys, from the generated assertion-keys.json (multiLeg.topLevelKeys), so the
+    unknown-key check can't drift; falls back to the embedded copy (kept equal, test-enforced) with a warning."""
+    p = Path(__file__).resolve().parent / "assertion-keys.json"
+    try:
+        return set(_str_list(json.loads(p.read_text(encoding="utf-8"))["multiLeg"]["topLevelKeys"], "multiLeg.topLevelKeys"))
+    except Exception as e:
+        print(
+            f"::warning:: multiLeg.topLevelKeys missing or malformed in {p}: {e} — "
+            "using a built-in key list that may be stale (run `npm run schema`).",
+            file=sys.stderr,
+        )
+        return set(_EMBEDDED_MULTI_LEG_TOP_KEYS)
+
+
+_MULTI_LEG_TOP_KEYS = _load_multi_leg_top_keys()
 # The scenario-wide keys a prompt leg runs with (legScenario in src/run/execute.ts).
 _LEG_SHARED_KEYS = (
     "name",

package/AGENTS.md

@@ -58,8 +58,10 @@ here**, and the failure is silent. Every one below was hit by an agent working i
   hand-maintained** — `cassette.v*.json`, `run-result.json`, `doctor.json`, `protocol.v1.json`,
   `critique-report.json`, `verify-cassettes.json`, `regrade.json`, `schedule-cost.json`. Adding a field to those means editing the TS type **and**
   the JSON by hand; nothing syncs them. Then regenerate the surface baseline (below).
-- **Surface-baseline ordering:** edit the schema → `npm run check:surface` (review the diff, expect
-  `+N -0 ~0`) → `npm run gen:surface` → `check:surface` again (now `+0 -0 ~0`). Running `gen:surface`
+- **Surface-baseline ordering:** edit the schema → `npm run check:surface` (review the diff: a new property or
+  an output-schema addition reads `+N -0 ~0`; a tightened constraint on the scenario or session schema reads `~N`
+  by design and needs a major, see RELEASING.md; a loosened one is listed as widened) → `npm run gen:surface` →
+  `check:surface` again (now `+0 -0 ~0`). Running `gen:surface`
   first hides the very diff you were supposed to review.
 - **A `RunResult` field is a 5-call-site change.** `assembleRunResult` has **5** call sites across
   `assemble-run-result.ts` / `execute.ts` / `cassette.ts` / `chat-result.ts`, plus the TS type, the