cowork-harness 3.0.1 → 3.1.0

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

@@ -3,8 +3,8 @@ name: cowork-harness
 description: Test or debug a Claude Code skill/plugin under Claude Cowork's runtime — sandboxed agent, default-deny egress, the can_use_tool permission/question protocol — using the cowork-harness CLI. Use when validating or regression-testing a skill, authoring or debugging a scenario YAML (prompt + scripted answers + assert:), choosing a fidelity tier, scripting AskUserQuestion / tool-permission answers, or asserting artifacts, egress, or sub-agent dispatch. Especially when a harness run no-ops an assertion, fails on an unanswered gate, false-greens, a steered answer never reaches the model, or a web_fetch is unexpectedly denied or gated. 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. 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: 3.0.1
-  tracks-harness: cowork-harness 3.0.1 (baseline desktop-1.40609.0)
+  version: 3.1.0
+  tracks-harness: cowork-harness 3.1.0 (baseline desktop-1.40609.0)
 ---
 
 # cowork-harness
@@ -25,7 +25,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 3.0.1` (baseline
+> **Version note:** the facts and `file:line` pointers here track `cowork-harness 3.1.0` (baseline
 > `desktop-1.40609.0`). If your checkout is newer, prefer the live `--help` and — in a repo checkout —
 > `SPEC.md` / `docs/*.md` over this snapshot, and re-run the bundled linter.
 
@@ -42,7 +42,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, and the baseline in one pass. The bullets below explain each thing it checks (and how to fix it).
 - **Replay-only? Skip `doctor`.** Replaying committed cassettes needs no Docker, no staged agent, and no token — and every tier's `doctor` validates the auth token (the live tiers also Docker + the staged agent), so a ✗ there is expected, not a blocker. Go straight to `cowork-harness replay <cassette>`.
-- **CLI on PATH, recent enough?** Run `cowork-harness --version` — this skill needs **≥ 3.0.1**. If it's missing or older, prefix every command with the version floor `npx "cowork-harness@^3.0.1" <cmd>` (Node ≥ 22), or install once with `npm i -g "cowork-harness@^3.0.1"`. **Pin `@^3.0.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.
+- **CLI on PATH, recent enough?** Run `cowork-harness --version` — this skill needs **≥ 3.1.0**. If it's missing or older, prefix every command with the version floor `npx "cowork-harness@^3.1.0" <cmd>` (Node ≥ 22), or install once with `npm i -g "cowork-harness@^3.1.0"`. **Pin `@^3.1.0`, never `@latest`** — `@latest` can silently fetch an older CLI and the new commands fail as "unknown command", whereas the floor **fails loud** if no compatible version is published.
 
   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)
@@ -568,6 +568,12 @@ Recognize these before "fixing" a non-bug:
   would claim more than the evidence supports, and staying silent would read as clean. Mutually exclusive
   with `undelivered_deliverables`, and quiet on a run that produced nothing to deliver. Not a skill defect —
   a harness coverage gap (see the *File delivery* section of fidelity-gaps).
+- **`model_fallback`** (`WARN`) — the agent switched off the requested model mid-run. Read the `trigger`:
+  `model_not_found` / `model_blocked` / `permission_denied` are properties of the **pin**, so every run of
+  this scenario falls back the same way until you change the pinned id; `overloaded` / `server_error` are
+  transient and a re-run may hold. The run's assertions still mean what they say — but they were produced
+  by a different model than the scenario names, so treat a green as evidence about the fallback model.
+
 - **`mount_delete`** (`WARN`) — a delete touched a **delete-denied mount other than `outputs`**: a `rw`
   connected folder. Production denies `unlink`/`rmdir` on *every* Cowork FUSE mount until per-mount
   approval, not just outputs — a connected folder shows the identical default — so this run diverged from

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 3.0.1` (baseline `desktop-1.40609.0`).
+Self-contained reference. Tracks `cowork-harness 3.1.0` (baseline `desktop-1.40609.0`).
 
 **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. `^2` 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: "3.0.1"`) instead when you want byte-reproducible CI.
+(e.g. `version: "3.1.0"`) 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
@@ -67,7 +67,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@^3.0.1"
+- run: npm i -g "cowork-harness@^3.1.0"
 - 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.
@@ -342,7 +342,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@^3.0.1"
+      - run: npm i -g "cowork-harness@^3.1.0"
       - run: cowork-harness lint scenarios/*.yaml                              # no-silent-false-green (needs python3; PyYAML bundled)
       - run: cowork-harness verify-cassettes cassettes/ --output-format json   # privacy + staleness gate
       - run: cowork-harness replay cassettes/ --output-format json             # token-free content/structure
@@ -371,7 +371,7 @@ jobs:
             echo "live=true" >> "$GITHUB_OUTPUT"
           fi
       - if: steps.guard.outputs.live == 'true'
-        run: npm i -g "cowork-harness@^3.0.1"
+        run: npm i -g "cowork-harness@^3.1.0"
       - 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 3.0.1` (baseline `desktop-1.40609.0`). This is **not** a trim of the full
+Tracks `cowork-harness 3.1.0` (baseline `desktop-1.40609.0`). 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, reproduction discipline, 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/fidelity-and-answers.md

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

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 3.0.1`
+Self-contained reference for authoring `cowork-harness` scenarios. Tracks `cowork-harness 3.1.0`
 (baseline `desktop-1.40609.0`). 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`.
 
@@ -421,6 +421,7 @@ codes (`VerdictSignal["code"]` in `src/run/verdict.ts`):
 | `infra_error` | fail | A supervising process died mid-run (VM/egress sidecar) — the run's evidence is contaminated, not author-suppressible |
 | `stalled` | fail | The run ended on an unanswered question, or on a trailing-`?` final turn with no tool work after the last gate (opt out: `allow_stall`) |
 | `non_deterministic` | warn | The run was LLM/external/human-decided — not reproducible |
+| `model_fallback` | warn | The agent fell back off the requested model mid-run (SDK `model_fallback` event); a `model_not_found`/`model_blocked` trigger repeats every run until the pin changes |
 | `prompt_asset_missing` | warn | The run proceeded with a missing prompt asset (`COWORK_HARNESS_ALLOW_MISSING_PROMPT=1`); fidelity is degraded |
 | `scan_unavailable` | warn | Post-run scan evidence unavailable (`RunResult.scan` undefined) — the host-path and outputs-delete guards did not run this run |
 | `ended_with_question` | warn | Live-lane heuristic: the final answer contains a question and the run wrote no deliverable to `outputs/` — the lenient sibling of `stalled` (covers a mid-message `?`, or tool work after the last gate that still ended asking). Opt out: `allow_stall` |

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 3.0.1` (baseline `desktop-1.40609.0`), same as SKILL.md's front-matter. Recipe 2's `resolved-tier`/`unverifiable-tier` staleness classes and
+Tracks `cowork-harness 3.1.0` (baseline `desktop-1.40609.0`), 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.
 
@@ -46,6 +46,11 @@ what production would do. Two layers of defense:
   statically knowable and only produce a non-failing informational note.
 - **Manual (one-liner):** `grep -h '"effectiveFidelity"' cassettes/*.cassette.json | sort | uniq -c`
   shows the tier distribution of the fleet at a glance.
+- **Do NOT re-record for a `[note]` alone.** A `·`/`[note]` row is informational and the run still exits
+  **0** — `session-fingerprint: predates \`model\` coverage` and `prompt-assets: cassette predates …` both
+  mean "this cassette was recorded before that field existed, and everything the hash *does* cover still
+  matches". Re-recording buys the new coverage and nothing else, so on a fleet of heavy cassettes it is a
+  real bill for no verdict change. Re-record when a `✗` says to (baseline moved, skill drift, tier moved).
 
 ### Cassette anatomy (what you're looking at when you open one)
 
@@ -66,7 +71,7 @@ Top-level fields of a `*.cassette.json` (schema [`schema/cassette.v12.json`](htt
 | `preRunOrigin` | How that pre-run baseline was obtained — `local-walk` (real), `remote-unavailable` or `local-unreadable`. Only `local-walk` supports a verdict: replay fails `no_unexpected_files` as evidence-unavailable on the other two rather than passing vacuously |
 | `scenarioSource` | Relative path to the authored YAML this was recorded from |
 | `authoring` | Present iff a live decider answered ≥1 gate during recording (`nonDeterministic: true`) |
-| `sessionFingerprint` | Optional even on v9+ (the minimum readable version): hash of the session's content-relevant SHAPE (folders/plugins/skills/mcp/egress/web_fetch, plus projects and agent_env when set). Checked ONLY by `verify-cassettes`, never the default replay verdict; absent → not checked |
+| `sessionFingerprint` | Optional even on v9+ (the minimum readable version): hash of the session's content-relevant SHAPE (model/folders/plugins/skills/mcp/egress/web_fetch, plus projects and agent_env when set). Checked ONLY by `verify-cassettes`, never the default replay verdict; absent → not checked |
 | `folderPrefixMap` | Optional even on v9+: the record-time connected-folder host-path → mount-name map. Replay's `computer_links_resolve` uses THIS (never the current session file); absent → the link is treated as evidence-unavailable, never reconstructed from the current session |
 | `timeline`, `timelineHeader` | The recorded per-event timeline (harness-observation timestamps for tool_use/tool_result/subagent_dispatch/thinking/decision/result, in total order) plus its header (`startedAtWall`/`startedAtMono` anchors); informational only — never affects the replay verdict. Absent on a cassette recorded before this field existed |
 | `environment` | Recording provenance: `location` (`"local"` on every cassette this harness produces), the resolved `tier`, `agentBinaryFormat`, and `harnessVersion` — the CLI that RECORDED the cassette (≥1.11.0). A harness-code change can shift recorded behaviour at an UNCHANGED baseline, which no staleness class keys off, so this is the only provenance for that class. **Absent** on pre-1.11.0 cassettes, and never backfilled — the absence is itself the signal |
@@ -241,10 +246,13 @@ Hardening a skill is a loop: run → read what it did → fix → run again. Two
    unrecoverable if skipped. `skillHash` is content-exact, so an edit mid-batch silently splits the
    dataset into two generations — `stats --group-by skill-hash` separates them afterwards, but a hash
    whose source was never committed names a generation that is unrecoverable, which makes the
-   comparison uninterpretable rather than merely noisy. And with no `model:` in the session (or
-   `--model` on the `skill` lane) each run uses whatever the staged agent binary defaults to, so a
-   before/after can silently straddle two models; read `result.json`'s `models` back to confirm —
-   ignoring any `<…>`-wrapped entry (`<synthetic>` marks a turn the agent fabricated locally, not a model).
+   comparison uninterpretable rather than merely noisy. And with no `model:` in the session and no
+   `--model` on the command (every lane takes it), each run uses whatever the staged agent binary
+   defaults to, so a before/after can silently straddle two models — the run warns when nothing pinned
+   one. Read `result.json` back to confirm: `modelSource` says whether anything pinned the model at all,
+   and `modelPinHonored` whether the pin survived (**absent means unverifiable, not "yes"**). `models`
+   lists what served the run — ignore any `<…>`-wrapped entry (`<synthetic>` marks a turn the agent
+   fabricated locally, not a model).
 3. **Don't cross-pair generations.** When you run the same skill across fixes, never pair a *pre-fix*
    `result.json` with a *post-fix* critique. The authoritative version key is `fingerprint.skillHash` —
    content-exact, on every live `run`/`skill` run that mounts a skill or plugin — **but only on ≥ 1.5.0; earlier CLIs emit

package/CHANGELOG.md

@@ -6,6 +6,66 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [3.1.0] — 2026-08-31
+
+### Fixed
+
+- **The pre-coverage cassette note was a paragraph repeated per file.** It fires on every cassette
+  recorded before `model` joined the session shape — for a consumer with a dozen, a dozen identical
+  paragraphs burying the findings that are genuinely per-file. Cut to one line (370 chars to 157), matching
+  the prompt-assets note beside it; the reasoning stays in `docs/fidelity-gaps.md`. Notes are deliberately
+  **not** aggregated in `verify-cassettes` — it is a per-file audit, and collapsing them would destroy the
+  attribution — so length was the part to fix. The note has always been non-failing: a pre-coverage
+  cassette stays clean, and `replay --strict` exits 0.
+- **The unpinned-model warning told `run` users the flag lived on other lanes.** It named the `skill`,
+  `probe-dispatch` and `chat` lanes for a flag `run` and `record` now accept — caught by running it, not
+  by reading it.
+
+- **`run --model ""` started a spending run instead of failing.** SPEC §CB-2 requires an empty or
+  whitespace model value to be a usage error, never a silently-propagated empty string. `record` inherits
+  that from the shared flag parser; `run` hand-rolls its own loop (the session-less lanes take `--model`
+  out of the leftovers themselves, so the shared parser cannot consume it) and did not enforce it.
+
+### Added
+
+- **`--model <id>` on `run` and `record`.** The `skill`, `probe-dispatch` and `chat` lanes already had it;
+  the two lanes that produce cassettes and CI verdicts did not, so the only way to pin them was editing the
+  session file. Precedence is explicit: an `--model` flag or a `--matrix` `models:` axis (a per-invocation
+  act) outranks the session's `model:`, while `COWORK_HARNESS_MODEL` only fills a gap — a machine-scoped
+  variable must never silently outrank a model the scenario declares, or the run's model becomes a
+  property of the shell it was launched from.
+- **Model provenance on every run, and a warning when nothing pins the model.** `--model` reaches the
+  agent only when a session declares `model:`, so an unset session inherits whatever the local CLI would
+  pick — and because the agent selects part of its system prompt by model capability, that moves the
+  *instructions* it is given, not just answer quality. `--effort` is not symmetric: it is always emitted
+  from the baseline's `spawn.effortDefault`, so an unset session pinned the effort and left the model it
+  applies to floating. Runs now warn when no model resolves (`chat` in its own words), naming the key and
+  the flag. Omitting it is deprecated and becomes an error in the next major — the same path
+  `Scenario.fidelity` took, and deliberately not a hard fail today: the repo chose deprecation for a
+  default with a larger blast radius, and a harder gate for a lesser field would be incoherent with that.
+- **A family pin is checked as family membership, not equality.** `--model opus` is resolved by the agent
+  to a concrete id (`claude-opus-5`), never echoed back, and which member an account resolves it to is not
+  something the harness can know — so comparing the two as strings would report a pinned-and-honored run as
+  `modelPinHonored: false`. `opus`/`sonnet`/`haiku`/`fable` now compare by family and still fail on a
+  wrong-family model; `best` and `opusplan` name no comparable model and stay unverifiable.
+- **`RunResult.modelFallbacks`, `modelPinHonored` and `modelSource`.** Fallbacks come from the agent's own
+  `system`/`model_fallback` event rather than a diff of `models[]` — the event names the trigger, which is
+  what separates a retired or blocked pin (every run falls back the same way until the id changes) from a
+  transient overload. A new `model_fallback` warn signal surfaces it in the verdict; it cannot fire on a
+  healthy run, so it adds no volume to a currently-green one. `modelPinHonored` is three-state on purpose:
+  `true`, `false`, and **absent for unverifiable** — nothing pinned, or no live model evidence. The
+  natural two-state shape reports "we could not tell" as "the pin held", which is a false green, so the
+  no-evidence cases are asserted explicitly rather than left to a truthiness check.
+- **A cassette records the model it was recorded with**, in its `environment` block: the id the agent
+  reported (so it survives a mid-run fallback) plus the source. A cassette recorded with nothing pinned
+  says `unresolved`, which is the difference between "recorded on opus-5 by choice" and "on whatever that
+  laptop happened to pick".
+- **The session fingerprint now covers the pinned model.** Editing `model:` after recording previously
+  moved nothing and `verify-cassettes` said nothing, even though the edit changes what the agent was told.
+  A cassette recorded before this coverage reports **unverifiable** rather than clean — its hash cannot
+  tell "the field was never covered" from "the pin changed since", and claiming otherwise in the remedy
+  would reintroduce the false green the coverage exists to close.
+
 ## [3.0.1] — 2026-08-30
 
 ### Changed

package/README.md

@@ -49,8 +49,8 @@ Three ways to use this project. Each row is the whole hook — follow the link f
 
 | I want to… | Start here | Needs |
 |---|---|---|
-| **Run scenarios myself** from a terminal | **[docs/cli.md](./docs/cli.md)**<br><br>`npm i -g "cowork-harness@^3.0.1"`<br>`cowork-harness replay examples/replays/example-pdf-skill.cassette.json` | Node ≥ 22. The replay demo above is token-free and needs nothing else; live tiers above `protocol` need Docker + a staged agent binary |
-| **Have Claude Code drive it** for me | **[docs/companion-skill.md](./docs/companion-skill.md)**<br><br>`/plugin marketplace add yaniv-golan/cowork-harness`<br>`/plugin install cowork-harness@cowork-harness` | Claude Code. The skill self-bootstraps the CLI via `npx "cowork-harness@^3.0.1"` |
+| **Run scenarios myself** from a terminal | **[docs/cli.md](./docs/cli.md)**<br><br>`npm i -g "cowork-harness@^3.1.0"`<br>`cowork-harness replay examples/replays/example-pdf-skill.cassette.json` | Node ≥ 22. The replay demo above is token-free and needs nothing else; live tiers above `protocol` need Docker + a staged agent binary |
+| **Have Claude Code drive it** for me | **[docs/companion-skill.md](./docs/companion-skill.md)**<br><br>`/plugin marketplace add yaniv-golan/cowork-harness`<br>`/plugin install cowork-harness@cowork-harness` | Claude Code. The skill self-bootstraps the CLI via `npx "cowork-harness@^3.1.0"` |
 | **Gate my skill in CI** | **[docs/ci.md](./docs/ci.md)**<br><br>`- uses: yaniv-golan/cowork-harness@v3`<br>`  with: { command: replay, path: cassettes/ }` | Nothing for the token-free gate; the live lane needs a self-hosted runner with Docker + an agent binary |
 
 Not sure a harness is what you need? The next two sections are the argument.

package/SPEC.md

@@ -78,7 +78,8 @@ claude -p --verbose
   (--max-thinking-tokens 31999 | --thinking disabled)   # session.extended_thinking on|off (default on)
                                                 #   debug.max_thinking_tokens → --max-thinking-tokens <N> (fenced, non-Cowork)
   [--append-system-prompt <rendered cowork sections>]
-  [--model <session.model>]
+  [--model <resolved model>]                   # --model flag / matrix axis > session.model > COWORK_HARNESS_MODEL;
+                                                #   omitted when none pin one (the agent picks its own default — warns)
   [--mcp-config <configGuest>/mcp.json]         # if session.mcp.config set — HONORED in plain cowork mode (§6)
   (--plugin-dir <mntRoot>/<p>)…                 # one per pluginDirs entry
   --tools <baseline.spawn.tools…>                # variadic, LAST

package/dist/cli.js

@@ -90,6 +90,7 @@ const HELP = `cowork-harness <command>   (v${"$VERSION"})
 
 ── Automated scenarios ────────────────────────────────────────────────────────
   run <scenario.yaml | dir/>   run one scenario or every *.yaml in a dir (CI-ready exit code)
+      [--model <id>]   pin the model (overrides the session's 'model:'; unset warns)
       [--on-unanswered fail|first]   ('prompt' rejected — breaks determinism)
       [--decider-cmd '<helper>']   answer live questions via a spawned helper
       [--decider-dir <dir>]   answer live questions in-band; then use 'gates'/'answer' to stream/respond
@@ -97,7 +98,7 @@ const HELP = `cowork-harness <command>   (v${"$VERSION"})
       (run 'run --help' for the full flag reference)
 
 ── Cassette lifecycle ─────────────────────────────────────────────────────────
-  record <scenario.yaml>       run + save a control-protocol cassette
+  record <scenario.yaml>       run + save a control-protocol cassette   [--model <id>]
       [--out <file>]           cassette path (default: cassettes/<scenario-name>.cassette.json)
       [--max-artifact-bytes <n>]  inline-body cap (default 65536 / $COWORK_HARNESS_MAX_ARTIFACT_BYTES)
       [--concurrency <N>]      record a dir/ batch (or --rerecord-stale) N at a time (default 1; runs are
@@ -325,6 +326,12 @@ const RUN_HELP = `cowork-harness run <scenario.yaml | dir/>
   ('run' takes no --dry-run: 'record <file.yaml> --dry-run' checks that a scenario LOADS without
    spending; 'lint <file.yaml>' checks the assertion invariants. Both are token-free.)
 
+Model:
+  --model <id>                     pin the model, overriding the session's 'model:' for this run
+                                   (env COWORK_HARNESS_MODEL sets a default; a --matrix 'models:' axis
+                                   wins over both). A run that resolves no model warns: omitting it is
+                                   deprecated and becomes an error in the next major.
+
 Input policy:
   --on-unanswered fail|first       policy for an unscripted question (default: fail — deterministic).
                                    'prompt' is rejected (it would break reproducibility).
@@ -1358,7 +1365,48 @@ async function cmdRun(rawArgs) {
     // swallow a real arg) instead of the loud reject below, so muscle memory from `skill` doesn't error.
     // Note it so the no-effect is visible.
     const keepRequested = rawRest.includes("--keep");
-    const args = rawRest.filter((a) => a !== "--keep");
+    // `--model <id>` — the one-off pin, matching the `skill`/`probe-dispatch`/`chat` lanes (and defaulting
+    // from COWORK_HARNESS_MODEL the same way they do). Parsed HERE rather than in `takeCommonFlags`: those
+    // lanes take `--model` out of the leftovers themselves, so consuming it in the shared parser would
+    // strip it before their own loops ever see it. Extracted before the `--keep` filter so both survive.
+    // The EXPLICIT flag and the env DEFAULT are kept apart deliberately. `run`/`record` resolve a session
+    // FILE, and a machine-scoped env var must never silently outrank a model that file declares — that is
+    // the very defect this whole change exists to close, and collapsing the two here reintroduced it
+    // through the back door (a stray line in a repo `.env` would repoint every clone's runs). The flag is
+    // an explicit per-invocation act and does outrank the file; the env var only fills a gap.
+    let modelFlag;
+    const withoutModel = [];
+    for (let i = 0; i < rawRest.length; i++) {
+        const tok = rawRest[i];
+        // Accept `--model=<id>` too: `record` gets it free from the shared parser, and a form that works on
+        // one lane and is reported as an unexpected argument on the other is just a trap.
+        if (tok.startsWith("--model=")) {
+            // SPEC §CB-2: an empty/whitespace value is a hard usage error, never a silently-propagated empty
+            // model string — the same rule `flagValue()` and chat's own parser enforce.
+            const v = tok.slice("--model=".length);
+            if (v.trim() === "")
+                fail("run", "usage", "--model requires a model id", undefined, isJsonOutput(rawArgs));
+            modelFlag = v;
+            continue;
+        }
+        if (tok === "--model") {
+            const v = rawRest[i + 1];
+            // `takeCommonFlags` has already consumed every flag it knows, so a `-`-prefixed or missing next
+            // token means the value is absent. The `.yaml` check catches the case the `-` guard CANNOT see:
+            // in `run --model --verbose x.yaml`, `--verbose` is consumed upstream, so this loop sees
+            // `["--model","x.yaml"]` and would swallow the scenario path as a model id — then report "no
+            // scenario path", blaming the one argument that was correct. No model id ends in .yaml/.yml.
+            const looksLikeScenario = v !== undefined && /\.ya?ml$/i.test(v);
+            // `v.trim() === ""` is SPEC §CB-2 (an empty model string must never propagate).
+            if (v === undefined || v.trim() === "" || v.startsWith("-") || looksLikeScenario)
+                fail("run", "usage", `--model requires a model id${v === undefined ? "" : ` (found \`${v}\`${looksLikeScenario ? ", which looks like the scenario path" : ""})`}`, undefined, isJsonOutput(rawArgs));
+            modelFlag = v;
+            i++;
+            continue;
+        }
+        withoutModel.push(tok);
+    }
+    const args = withoutModel.filter((a) => a !== "--keep");
     if (keepRequested)
         log("note: `run` always keeps runs (under the runs root); --keep is a no-op here.");
     // A leftover global-only flag is NOT a positional. `takeCommonFlags` has already consumed every real
@@ -1460,7 +1508,9 @@ async function cmdRun(rawArgs) {
             const cellScenario = cell.axes.baseline !== undefined ? { ...scenario, baseline: cell.axes.baseline } : scenario;
             try {
                 const session = applySessionOverrides(baseSession, {
-                    model: cell.axes.model,
+                    // The cell axis is the more specific choice; `--model` is the fallback for a matrix whose
+                    // cells vary some OTHER axis and still want one pinned model across all of them.
+                    model: cell.axes.model ?? modelFlag,
                     skillDirSubstitution: cell.axes.skillDir !== undefined
                         ? [baseSession.plugins.local_plugins[0], resolvedSkillDirs.get(cell.axes.skillDir)]
                         : undefined,
@@ -1584,7 +1634,10 @@ async function cmdRun(rawArgs) {
                     policy,
                     externalChannel,
                     o,
-                    extra: deciderModel ? { llmModel: deciderModel } : undefined,
+                    extra: {
+                        ...(deciderModel ? { llmModel: deciderModel } : {}),
+                        ...(modelFlag !== undefined ? { modelOverride: modelFlag } : {}),
+                    },
                 }));
                 continue;
             }
@@ -1605,7 +1658,10 @@ async function cmdRun(rawArgs) {
                     policy,
                     externalChannel,
                     o,
-                    extra: deciderModel ? { llmModel: deciderModel } : undefined,
+                    extra: {
+                        ...(deciderModel ? { llmModel: deciderModel } : {}),
+                        ...(modelFlag !== undefined ? { modelOverride: modelFlag } : {}),
+                    },
                     rethrowUnanswered: true,
                 }),
                 onResult: (r) => results.push(r),