cowork-harness 1.9.0 → 1.10.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: 1.9.0
-  tracks-harness: cowork-harness 1.9.0 (baseline desktop-1.24012.1)
+  version: 1.10.0
+  tracks-harness: cowork-harness 1.10.0 (baseline desktop-1.24012.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 1.9.0` (baseline
+> **Version note:** the facts and `file:line` pointers here track `cowork-harness 1.10.0` (baseline
 > `desktop-1.24012.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.
 
@@ -39,100 +39,11 @@ Before the first command, confirm the CLI is reachable and **fail loud** (never
 
 - **One-shot check.** Run `cowork-harness doctor [--tier <tier>]` first — a read-only prerequisite check that inspects Docker, the staged agent, the token, and the baseline in one pass. The bullets below explain each thing it checks (and how to fix it).
 - **Replay-only? Skip `doctor`.** Replaying committed cassettes needs no Docker, no staged agent, and no token — and every tier's `doctor` validates the auth token (the live tiers also Docker + the staged agent), so a ✗ there is expected, not a blocker. Go straight to `cowork-harness replay <cassette>`.
-- **CLI on PATH, recent enough?** Run `cowork-harness --version` — this skill needs **≥ 1.9.0**. If it's missing or older, prefix every command with the version floor `npx "cowork-harness@>=1.9.0" <cmd>` (Node ≥ 20), or install once with `npm i -g "cowork-harness@>=1.9.0"`. **Pin `@>=1.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.
-
-  What the ≥ 1.9.0 floor gates, by release:
-
-  - **1.9.0 (critique report schema + shareable, screenshot-safe output):**
-    `schema/critique-report.json` (descriptive, test-pinned — parse the report against it, not prose;
-    NOT §12-frozen while critique is EXPERIMENTAL), `gradedSkill` in the report (text header + JSON;
-    multi-skill pairing key — pair by `(gradedSkillHash, gradedSkill)`, since the hash alone keys the whole
-    plugin and cross-pairs its skills). Critique's text report and stderr diagnostics now **collapse host
-    paths to `~`** (a shared report or screenshot no longer leaks the username + filesystem layout; the JSON
-    report and persisted-artifact paths stay raw for machine consumers), a **missing or non-directory skill
-    folder is refused pre-spawn** (fast exit 2, no stray run dir left behind), and the report header + stderr
-    prefixes now read **`critique:`** (were `skill-critique:`).
-
-  - **1.8.0 (critique hardening + hostloop unpin):** `critique --skill <name>` (multi-skill-plugin
-    grading — a plugin root with no `--skill` is refused pre-spend; the evidence package gains the
-    invoked skill's `agents/<name>.md` + bounded `references/*.md` CONTENT), run-dir artifacts
-    (`critique-report.json` always, `critique-evidence-package.txt` when the evaluator ran,
-    `critique-salvage.json` on exit 2) + `--out <path>`, per-critique `costUsd` across all four
-    workloads, `findingFingerprint` per item (cross-INPUT clustering; HIGH-precision
-    LOW-recall — a match proves reproduction, a mismatch does NOT prove non-reproduction, the same
-    finding reworded fingerprints differently; skillHash stays the cross-FIX
-    key), gate-answer `--answer` echo in the report, per-item-tolerant evaluator parse
-    (`droppedEvaluatorItems`), `skillMdTruncated` (a readable-but-oversized SKILL.md is flagged
-    "graded a cut copy" — distinct from missing/unreadable), `subagents[].webSearches` +
-    `trace --view subagent-research` (live/record lane), and the hostloop uploads-bullet fix (Read of
-    an uploaded file at the advertised path works — no copy-into-outputs workaround needed). Also:
-    **`critique --fidelity hostloop`** (the container-tier pin is lifted — resume-continuity proven
-    live on the native binary; `microvm`/`protocol`/`cowork` stay refused, each with a tagged reason),
-    **`skill --allow-host-writes`** (hostloop writable-folder consent; `critique` forwards it to both
-    turns), `verdictProvenance` stamped on every critique report (advisory self-run, not an
-    attestation), evidence caps 64KB SKILL.md / 32KB transcript / 144KB package (a flagship-sized
-    SKILL.md grades untruncated; ~2–2.5× evaluator cost on large skills), pinned sessions stamp their
-    fidelity and a cross-tier `--resume` fails loud pre-spawn, and `doctor`'s advisory
-    `image-freshness` check (pulled agent image behind the published GHCR one → warn + re-pull
-    remedy).
-
-  - **1.7.0 (per-turn run-directory layout, single shape):** every run dir — `run`/`skill`/`chat`,
-    single-turn or multi-turn (any `--session-id` + `--resume`, and **every `critique`**: task turn +
-    reflection turn) — writes each turn's `result.json` / `run.jsonl` / `trace.json` / `resources.jsonl`
-    into **`turns/<N>/`**, written once and never renamed. **There is no root compat copy of anything —
-    `<run-dir>/result.json` does not exist.** **When a user asks about a run, point them at
-    `turns/1/result.json`** (the only completion on a single-turn dir) — or on a `critique` dir, better yet
-    at `result.graded.json` / `trace.graded.json`, the role-stable aliases `critique` writes (the graded
-    task turn, never the reflection one). `events.jsonl` / `timeline.jsonl` stay cumulative at the run-dir
-    root, always. A dir written before this layout existed is refused LOUD, by name, naming the shape found
-    — never silently misread as if it were `turns/1/`. **Convert it in place with
-    `cowork-harness migrate-run-dir` (dry-run by default); do NOT tell the user to re-run or re-record,
-    which throws away history the migrator recovers.** Its `events.jsonl` still fully supports `trace`,
-    which is why every refusal points there. `verify-run` REFUSES a multi-turn dir rather than certifying
-    the wrong turn, and `trace` shows the latest turn with a `::notice::` when earlier turns exist.
-
-  - **1.7.0 (limitation provenance):** every `critique` limitation in `critique --help` and
-    docs/critique.md is tagged with WHY it exists — `[structural]` (permanent), `[unverified]` (unproven,
-    **not** known-impossible), `[deliberate]`, `[not-built]`. **Read the tag before telling a user to
-    design around a limitation.** Worked example of why the tag matters: `critique`'s container-tier pin
-    was tagged `[unverified]`, not permanent — and 1.8.0 lifted it (hostloop allowed, see above) exactly
-    as the tag predicted a proof could.
-
-  - **1.6.0 (`critique`'s skill-flag parity):** `critique` accepts most `skill` flags under the same names,
-    which is what makes a document-analysis skill (cap table, deck, financial model, transcript)
-    critiquable at all: `--upload`/`--folder`/`--plugin`/`--marketplace`/`--enable`/`--model`/
-    `--allow-missing-capability` reach BOTH spawned turns; `--label`/`--timeout`/`--answer`/
-    `--answer-policy`/`--on-unanswered`/the decider flags reach the graded turn only; `--prompt-file` is
-    new. Anything that can't work is REFUSED with a reason rather than silently ignored.
-    **Repeating a flag:** `--upload`/`--folder`/`--plugin`/`--marketplace`/`--enable`/`--answer`
-    accumulate; every other value-taking flag is single-valued and repeating it is a usage error (exit `2`)
-    rather than a silent last-wins — do not assume the CLI-conventional "last one wins". Booleans repeat
-    harmlessly. On `1.5.0` these flags do not exist: `critique --upload x.xlsx` fails as "unknown flag", so
-    if a user hits that, they are below the floor.
-
-  - **1.5.0:** `critique <skill-folder> --prompt "<probe>"` (EXPERIMENTAL) — runs a skill, asks the agent
-    what confused it, then grades that self-report against a frozen record of the run: a blinded evaluator
-    plus mechanical citation checking. Findings NEVER gate (exit 0); exit 2 means no critique was produced.
-    `skill --repeat N` (2-100) with `--min-pass-rate`/`--stop-on-diverge`/`--max-budget-usd`/
-    `--allow-budget-stop` brings the variance rollup to the exploratory lane. `result.json` gains
-    `outcome` (`errored`/`no_deliverable`/`delivered_with_verdict_fail`/`delivered_clean`). The
-    `skill`/`probe-dispatch` lanes now emit `fingerprint.skillHash`/`skillCommit` at all — before 1.5.0
-    they emitted NEITHER, so a generation-pairing step over those lanes silently grouped on an absent key.
-    `diff`'s exit code now honours its own documented gateable signal (tools/artifacts/meta; a
-    transcript-only difference no longer fails it).
-  - **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.
-  - **1.0.0:** first stable release — the SPEC §12 compatibility contract takes effect (covered CLI/schema/env/Action surfaces are now stable; breaking changes need a major bump). No new author-facing command; the floor simply tracks the 1.0 release.
-  - **1.1.0:** `analyze-skill` now also flags **interactive-artifact write-backs lost under Cowork** — a relative `fetch`/XHR/`sendBeacon`/`<form method=post>` in an emitted `.html` (or its `.py`/`.js` generator) that silently fails when the artifact is served from Cowork's own origin. `artifact-write-back-lost` gates under `--strict`; `artifact-write-back-suspect` is advisory; an unanalyzable candidate is a could-not-verify exit 3. An optional **`analyze-skill --runtime`** drives the artifact in a headless DOM (needs `jsdom`) to *observe* the lost write-back — enrichment only, never changes the exit code. Plus a `lint` check for a container-only assertion key (`no_scratchpad_leak`/`present_files_called`) used off the `container` tier, and the `doctor --output-format json` envelope frozen as a covered SPEC §12 surface (`schema/doctor.json`).
-  - **1.2.0:** three new assertion keys — `no_lost_write_back: true` (the write-back detector above wired as a per-scenario gate over the run's authored files, live-only) and the regex siblings `tool_result_matches`/`tool_result_not_matches` (case-insensitive per-result, for an error-signature *family* a literal substring can't express). **`microvm` outputs are now observable** — its session tree is snapshotted from the VM into the run dir, so `file_exists`/`artifact_json`/`user_visible_artifact`/`no_unexpected_files`/`input_unmodified`/`no_lost_write_back`/`semantic_matches` all work there, no longer `container`/`hostloop`-only. `status <dir>` also resolves the newest session under a `--run-dir` root; the completion footer prints a `→ result: …/result.json` pointer; the `on_unanswered=fail` error also points to `on_unanswered: llm`. `analyze-skill` hardening: a phantom `<script>` prose block no longer sinks a real verdict, a delete/remove flow claiming success classifies as lost (error) not just suspect, and write-back detection widened (optional-call `?.` spellings, member-spelled/aliased `fetch`/`sendBeacon`, axios instance/config forms).
-  - **1.3.0:** run-identity for the iterate-across-fixes loop — `skill`/`run` take `--label <tag>` (a generation tag surfaced in `result.json` `runLabel`, the run-index row, `inspect`, and `status.json`) alongside an auto-recorded `skillCommit`, layered on the **authoritative** content-exact `fingerprint.skillHash` a harvest step should pair critiques by (`inspect`/index surface a short `skillHash` prefix). `trace --full-results` captures the full input+result of **every** tool call — successful ones too, not just errors — so an external grader can ground a self-critique finding against the call it cites. `verify-run` now **warns** on skillHash drift for answer-less scenarios (was silent unless the scenario declared scripted `answers`). Plus `skill --allow-missing-capability` (the open-ended-run opt-out for a capability FALSE-NEGATIVE on the lean `core` image), a new **warn-severity `ended_with_question`** verdict signal (the agent's final answer contains a question and the run wrote no `outputs/` deliverable — the lenient sibling of the strict `stalled`), and LLM-decider `OTHER:` free-text answers now marked `[via Other free-text]` in gate provenance.
-  - **1.4.0:** platform baseline synced to Desktop **1.22209.3** (agent 2.1.215; no prompt/spawn/egress drift), and **`coworkWebFetchDedup` is now enacted** on the hostloop `web_fetch` path — a repeat fetch of the same normalized URL within the TTL (15 min, cap 100) makes **no network request** and returns a marker to re-use the earlier result, with no egress event. Baseline-gated (Desktop ≥ 1.22209.3), keyed under the request + terminal `destination_url`, never caching errors/empty; a hit is assertable via `tool_result_contains: "Already fetched"`.
+- **CLI on PATH, recent enough?** Run `cowork-harness --version` — this skill needs **≥ 1.10.0**. If it's missing or older, prefix every command with the version floor `npx "cowork-harness@>=1.10.0" <cmd>` (Node ≥ 20), or install once with `npm i -g "cowork-harness@>=1.10.0"`. **Pin `@>=1.10.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)
+  — upgrade rather than work around it, since this skill's `file:line` pointers and flag names track the floor.
 - **Agent binary (sandboxed live tiers — `container`/`microvm`/`hostloop`/`cowork`).** The staged Claude Code agent is **bind-mounted** from a local Claude Desktop install, or point `COWORK_AGENT_BINARY` at a `claude-code-vm/<ver>/claude` ELF. Nothing is bundled. `protocol` (L0) and `replay` need no staged agent; for the sandboxed tiers, no agent → no run; report that, don't skip silently.
 - **Docker / Lima.** Only `--fidelity protocol` (L0) runs without them. `container` / `microvm` / `hostloop` / `cowork` need Docker (Lima for L2). If they're absent, drop to `--fidelity protocol` and **say so** — a green that never exercised the sandbox is not a sandbox pass.
 - **Auth.** `CLAUDE_CODE_OAUTH_TOKEN` (preferred), or `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN`, via env or `.env`. Minting an OAuth token needs the **`claude` CLI** (`npm i -g @anthropic-ai/claude-code`, then `claude setup-token`).

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

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

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

@@ -1,6 +1,6 @@
 # Fidelity tiers & answer paths
 
-Self-contained reference. Tracks `cowork-harness 1.9.0` (baseline `desktop-1.24012.1`).
+Self-contained reference. Tracks `cowork-harness 1.10.0` (baseline `desktop-1.24012.1`).
 
 ## 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 1.9.0`
+Self-contained reference for authoring `cowork-harness` scenarios. Tracks `cowork-harness 1.10.0`
 (baseline `desktop-1.24012.1`). If your checkout is newer, prefer the live `docs/scenario.md`,
 `docs/session.md`, and `SPEC.md`.
 
@@ -136,6 +136,8 @@ plugins:
   remote_plugins: []
 skills:
   local: []                      # extra host skill dirs
+  suggest_enabled: true          # gate 245679952 override — `mcp__skills__suggest_skills` on/off (default true)
+  proactive_suggest_enabled: false  # gate 1598976391 override — proactive description + `trigger` param (default false)
 mcp:
   config: null                   # --mcp-config file (standard mcpServers map)
   enabled: []
@@ -274,7 +276,7 @@ same set live from the schema.
 | `no_skill_triggered: <regex>` | no invoked skill id matched — the negative-control / description-collision catcher; evidence-unavailable (never a vacuous pass) if invocation data is absent or the `Skill` tool is unobservable |
 | `skill_available: <regex>` | a staged skill's id matched the regex (offered, not necessarily invoked — see `skill_triggered` for invocation) — content-class: the id list comes from the agent's init `skills` listing, so it replays from the frozen init event (id-only; the `whenToUse` enrichment is live-disk and thus absent on replay, but the id is what's matched); evidence-unavailable only if `RunResult.context.availableSkills` is absent entirely (an older cassette recorded before the available-skills listing was captured) |
 | `connector_available: <regex>` | an MCP server/connector's name matched the regex (available, not necessarily used) — evidence-unavailable if `RunResult.context.mcpServers` is absent |
-| `tool_available: <regex>` | a tool in the init manifest matched the regex (available, not necessarily called — see `tool_called` for invocation) — evidence-unavailable if `RunResult.context.tools` is absent |
+| `tool_available: <regex>` | a tool in the init manifest matched the regex (available, not necessarily called — see `tool_called` for invocation) — evidence-unavailable if `RunResult.context.tools` is absent. The `mcp__skills__*`/`mcp__plugins__*` discovery tools are modeled (as `alwaysLoad`) on `container`/`hostloop`/`cowork` — a miss there is a real absence; `microvm`/`protocol` declare no such server, so a miss on those two tiers means "not modeled at this tier", not "provably unavailable" |
 
 **Name-matching styles differ by key (don't mix them up):** `tool_called`, `tool_not_called`,
 `subagent_tool_used`, `subagent_tool_absent` are **glob** (anchored, case-sensitive, `*`/`?`). `tool_available`,

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 1.9.0` (baseline `desktop-1.24012.1`), same as SKILL.md's front-matter. Recipe 2's `resolved-tier`/`unverifiable-tier` staleness classes and
+Tracks `cowork-harness 1.10.0` (baseline `desktop-1.24012.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.
 

package/AGENTS.md

@@ -21,7 +21,8 @@ protocol layer or run-loop bookkeeping in the CLI.
 - Tests are **token-free & spawn-free** wherever possible (`cli-json` uses usage-errors + cassette replay).
   Don't add a test that needs a live model or Docker to the default suite; that's the `pytest -m cowork` /
   `npm run test:live` lane. Python fast lane (from `python/`): `pytest -m 'not cowork'`.
-- CLI binary `cowork-harness`; env vars `COWORK_HARNESS_*` (+ `COWORK_AGENT_BINARY` / `COWORK_AGENT_IMAGE`).
+- CLI binary `cowork-harness`; env vars `COWORK_HARNESS_*` (+ `COWORK_AGENT_BINARY` / `COWORK_AGENT_IMAGE`) —
+  see README's [Reproducibility knobs](./README.md#reproducibility-knobs) for the full env-var list.
   Node ≥ 20.
 - `cowork-harness sync` is **local-only** (needs Desktop + `app.asar`; not on CI). The committed
   `baselines/*.json` are CI's source of truth — never hand-edit release facts into source; they come from

package/CHANGELOG.md

@@ -6,6 +6,50 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [1.10.0] — 2026-07-25
+
+### Changed
+
+- **The packaged `cowork-harness` skill no longer carries a per-release version history.** SKILL.md's
+  "what the floor gates, by release" list had grown to 19 releases / ~15 KB (about a fifth of the file)
+  and was self-defeating: every entry described a feature at or below the floor, so anyone meeting the
+  floor already had all of it. Because SKILL.md is loaded into an agent's context on every invocation,
+  that was pure token cost for content that cannot change behaviour. The version floor (and *why* to pin
+  it rather than use `@latest`) stays; the history now lives where it belongs — this changelog — with a
+  pointer for anyone diagnosing an older CLI. SKILL.md: 77 KB → 62 KB.
+
+### Added
+
+- **Skill/plugin discovery SDK-MCP servers** (`mcp__skills__list_skills`/`suggest_skills`,
+  `mcp__plugins__list_plugins`/`search_plugins`/`suggest_plugin_install`) — modeled on `container` and
+  `hostloop` (and `cowork`, which resolves to one of those) alongside the existing `cowork`/`workspace`
+  servers, via a new `combineSdkMcp` composition helper (`src/agent/session.ts`). Every tool is
+  `alwaysLoad` so it surfaces in `system/init.tools` from turn one, matching real Cowork; `list_skills`/
+  `list_plugins` are populated deterministically from the session's actually-mounted skills/plugins,
+  and `suggest_skills`/`search_plugins`/`suggest_plugin_install` return a deterministic empty-catalog
+  advisory result (the real add/install catalog is out of band). Two gates control the `skills` server's
+  `suggest_skills` tool — `suggestSkillsEnabled` (default on) and `proactiveSkillSuggestEnabled` (default
+  off, adds a `trigger` param) — read from the synced baseline via a new bare-boolean `readGateBool`
+  reader, with new session-level overrides `skills.suggest_enabled` / `skills.proactive_suggest_enabled`
+  (see [docs/session.md](./docs/session.md)). `tool_available: "mcp__skills__.*"` /
+  `"mcp__plugins__.*"` is no longer a false negative on `container`/`hostloop`/`cowork` (still absent on
+  `microvm`/`protocol` — see [docs/fidelity-gaps.md](./docs/fidelity-gaps.md)). Fidelity scope: the tool
+  inventory, inputSchemas, gating, and the `list_skills`/`list_plugins` envelopes are asar/session-log
+  derived; the tool **description strings** and the `search_plugins`/`suggest_plugin_install` envelopes are
+  a faithful reconstruction rather than byte-captured — see [docs/fidelity-gaps.md](./docs/fidelity-gaps.md).
+  Both catalogs report what the sandbox will actually **receive**: a plugin skill directory that staging
+  drops (untracked, under the default git-tracked staging boundary) is omitted from `list_skills` *and*
+  `list_plugins`, including on `--resume`, so the two never contradict each other within a run.
+
+### Fixed
+
+- **`chat --fidelity container` declared SDK-MCP tools it never served.** The container branch built its
+  SDK-MCP bundle and then discarded it, so `mcp__cowork__present_files` was advertised on `--tools`/
+  `--allowedTools` while its server was never announced in `initialize` — calling it failed, and
+  `context.mcpServers` omitted `cowork`. (`run --fidelity container` was unaffected; this was the
+  interactive `chat` lane only.) The bundle is now forwarded, which also serves the new
+  `skills`/`plugins` discovery servers on that lane.
+
 ## [1.9.0] — 2026-07-24
 
 ### Added

package/CONTRIBUTING.md

@@ -2,7 +2,8 @@
 
 Thanks for helping make Cowork skill-testing reproducible.
 
-For the full documentation map, see [docs/README.md](./docs/README.md).
+For the full documentation map, see [docs/README.md](./docs/README.md). Read [AGENTS.md](./AGENTS.md) —
+the canonical agent/architecture contract (architecture seams, invariants) — before changing code.
 
 ## Development setup
 
@@ -29,7 +30,8 @@ CI Stage 1 (the `build` job in `.github/workflows/ci.yml`) does **not** invoke `
 gate steps individually — e.g. `check:versions`, `format:check`, `typecheck`, `build`, a CLI smoke
 (`node dist/cli.js list`), three token-free `replay` gate fixtures, `verify-cassettes`, `lint`, and
 source-guard checks — while the unit suite runs separately as the 4-shard `test` job (see `ci.yml` for
-the authoritative list). Only `release.yml` calls `npm run ci`.
+the authoritative list). Only `release.yml` calls `npm run ci`. For a copy-paste GitHub Actions setup,
+see [ci-recipe.md](./.claude/skills/cowork-harness/references/ci-recipe.md).
 
 > **Cutting a release?** See [RELEASING.md](./RELEASING.md) for the branch → PR → tag → publish flow.
 

package/README.md

@@ -91,7 +91,7 @@ node dist/cli.js replay examples/replays/example-pdf-skill.cassette.json
 
 > **Installed globally instead?** Once linked/installed, the same command is `cowork-harness replay
 > <cassette>` — but the relative path above only resolves from a source checkout's `examples/replays/`.
-> From a global install (`npm i -g "cowork-harness@>=1.9.0"`), point at the package root instead:
+> From a global install (`npm i -g "cowork-harness@>=1.10.0"`), point at the package root instead:
 > `cowork-harness replay "$(npm root -g)/cowork-harness/examples/replays/example-pdf-skill.cassette.json"`
 > (or copy the cassette into your own project and pass that path).
 
@@ -101,7 +101,7 @@ Live `run`/`skill` need the prerequisites in the next section — note the `prot
 > - **Replay only (zero setup):** `cowork-harness replay <cassette>` — no token, no Docker, no agent. The command above.
 > - **`protocol` (real model, no Docker):** needs only the auth token (item 3 below).
 > - **Live `container` / `microvm` / `hostloop` / `cowork`:** needs Docker (or Lima for `microvm`), a staged agent, and the token — run `cowork-harness doctor` first.
-> - **Invocation:** from a source checkout, `node dist/cli.js <cmd>` (or `npm link` to get the `cowork-harness` command); from a global install, `cowork-harness <cmd>`; the companion skill falls back to `npx "cowork-harness@>=1.9.0"`.
+> - **Invocation:** from a source checkout, `node dist/cli.js <cmd>` (or `npm link` to get the `cowork-harness` command); from a global install, `cowork-harness <cmd>`; the companion skill falls back to `npx "cowork-harness@>=1.10.0"`.
 
 Two more worked examples worth knowing about: `examples/scenarios/protocol-smoke.yaml` (zero-Docker smoke
 test) and `examples/scenarios/skill-loads.yaml` (container-tier acceptance check) — see
@@ -126,7 +126,7 @@ claude plugin marketplace add yaniv-golan/cowork-harness
 claude plugin install cowork-harness@cowork-harness
 ```
 
-The skill **self-bootstraps the CLI**: if `cowork-harness` isn't on your PATH it falls back to `npx "cowork-harness@>=1.9.0"` (a version floor that fails loud rather than silently fetching a too-old CLI; Node ≥ 20). Tiers above `protocol` still need Docker/Lima and a Claude Desktop agent binary — see the prerequisites below.
+The skill **self-bootstraps the CLI**: if `cowork-harness` isn't on your PATH it falls back to `npx "cowork-harness@>=1.10.0"` (a version floor that fails loud rather than silently fetching a too-old CLI; Node ≥ 20). Tiers above `protocol` still need Docker/Lima and a Claude Desktop agent binary — see the prerequisites below.
 
 It also follows the open [Agent Skills](https://agentskills.io) spec, so it installs cross-editor (Cursor, Codex, OpenCode, …) via [`npx skills`](https://github.com/vercel-labs/skills) (Vercel Labs' CLI implementation of that spec):
 
@@ -147,7 +147,7 @@ A global install is enough for CI `lint`, reading the teaching skill, and replay
 To `run` the worked examples live or copy them as a starting point, use a source checkout. (The marketplace
 skill install itself only pulls `.claude/skills/cowork-harness/` — SKILL.md + `references/` + `scenario.py`/
 assertion keys, per `.claude-plugin/marketplace.json`'s `source` — not the rest of this table; the full set
-above becomes available once the skill's first command self-bootstraps `npx "cowork-harness@>=1.9.0"` — see
+above becomes available once the skill's first command self-bootstraps `npx "cowork-harness@>=1.10.0"` — see
 [above](#drive-it-from-claude-code-companion-skill) — which pulls the same npm package as the global-install row.)
 
 ### Prerequisites for anything above `protocol` fidelity
@@ -363,6 +363,10 @@ L2  microvm parity    Optional. Agent inside a real Linux microVM (Lima/Apple-VZ
                       routes via host curl. A PreToolUse path-containment hook is the security boundary
                       for real filesystem access at this tier — see docs/boundary.md.
 
+    Both container and hostloop also declare the skills/plugins skill/plugin-discovery SDK-MCP servers
+    (mcp__skills__list_skills/suggest_skills, mcp__plugins__list_plugins/search_plugins/
+    suggest_plugin_install) alongside cowork/workspace — see docs/fidelity-gaps.md.
+
     cowork            Auto-picks hostloop vs container the way Cowork itself does — decoded from
                       GrowthBook gate 1143815894 (Cowork's internal feature-flag system) in the
                       synced baseline. "Do what real Cowork does."
@@ -396,7 +400,7 @@ Skill testing is the headline use, but the tool is a general harness over the Co
 
 | Command | What it does | Reach for it when… |
 |---|---|---|
-| `skill <folder> "<prompt>"` | Run a local skill/plugin folder once against the staged agent; `--compact`/`--demo` trim output for shareable screenshots/GIFs; `--ablate-skill` runs the same prompt with the skill removed (a negative control for skill-lift); `--label <tag>` stamps a generation name for the iterate-across-fixes loop (surfaced in `result.json`/index/`inspect`); `--repeat N` (2-100) runs the same skill+prompt N times and aggregates a variance rollup — "did this finding reproduce, or did it pass once?"; `--allow-missing-capability` stops a capability false-negative on the lean `core` image from failing the verdict (open-ended equivalent of asserting `allow_missing_capability: true`) | ad-hoc "is the skill alive / does it do X?" — the fast inner loop |
+| `skill <folder> "<prompt>"` | Run a local skill/plugin folder once against the staged agent; an unanswered gate's `--on-unanswered` defaults adaptively (`prompt` on a TTY, `fail` in CI/non-TTY); `--compact`/`--demo` trim output for shareable screenshots/GIFs; `--ablate-skill` runs the same prompt with the skill removed (a negative control for skill-lift); `--label <tag>` stamps a generation name for the iterate-across-fixes loop (surfaced in `result.json`/index/`inspect`); `--repeat N` (2-100) runs the same skill+prompt N times and aggregates a variance rollup — "did this finding reproduce, or did it pass once?"; `--allow-missing-capability` stops a capability false-negative on the lean `core` image from failing the verdict (open-ended equivalent of asserting `allow_missing_capability: true`); `--allow-host-writes` consents to a writable `hostloop`-fidelity connected folder (same consent as clicking "connect folder" in Desktop; no effect off `hostloop` or without a writable `--folder`) | ad-hoc "is the skill alive / does it do X?" — the fast inner loop |
 | `run <scenario.yaml \| dir/>` | Run authored scenarios with `assert:` + a CI-ready exit code; a decider can answer unscripted gates; `--repeat`/`--matrix` add variance runs / a compatibility matrix (detail below); `--ablate-skill` runs the same prompt with the skill removed (a negative control for skill-lift) | you want a repeatable, **asserted regression test** — to **measure flakiness** instead of trusting one green — or to **test a compatibility matrix** (multiple baselines/models/skill variants) in one run |
 | `chat <folder> [prompt]` | Interactive multi-turn REPL against a skill (TTY); optional seed prompt is sent as the first turn. `--upload <file>` / `--folder <dir>` (repeatable) attach files/project folders; `--verbose` shows thinking blocks + tool inputs; `--fidelity protocol\|container\|hostloop` (no `microvm`/`cowork` in the REPL); `--allow-host-writes` consents to a writable `hostloop`-fidelity connected folder (same consent as clicking "connect folder" in Desktop); `--raw` skips the control protocol for native `docker run -it` (rejects `--upload`/`--folder`/`--plugin`/`--fidelity`) | debugging a multi-turn flow by hand |
 | `record` / `replay` | **Record a live run once → replay it token-free, Docker-free thereafter** (key flags below; `replay --explain` prints the evidence behind every passing assert) | **token-free, Docker-free CI** from a once-recorded run |
@@ -429,7 +433,7 @@ Skill testing is the headline use, but the tool is a general harness over the Co
 
 **Flags worth knowing** (the full list is always `<command> --help`):
 - `run`: a decider (`--decider-cmd <helper>`/`--decider-dir <dir>`, or a scenario's `on_unanswered: llm` — a scenario-YAML key, not a CLI flag; `run` rejects `--on-unanswered llm`) can answer unscripted gates; `--repeat N` (2-100) runs each scenario N times and aggregates a variance rollup instead of a single pass/fail (`--min-pass-rate`, `--stop-on-diverge`, `--max-budget-usd` tune the batch verdict/loop); `--matrix <matrix.yaml>` runs ONE scenario across the cross-product of baseline/model/skill_dir axes (worked example: `examples/matrices/csv-metrics-matrix.yaml`; `--max-cells`/`--concurrency` tune the cap/pool — any cell failing, assertion or infra, fails the run); `--compact`/`--demo` trim `run`/`skill` output for shareable screenshots/GIFs; `--label <tag>` (both `run` and `skill`) stamps a generation name for the iterate-across-fixes loop — surfaced in `result.json` (`runLabel`), the run-index row, `inspect`, and `status.json`, alongside the auto-recorded `skillCommit` (git provenance) and the authoritative `fingerprint.skillHash` a harvest step should pair critiques by.
-- `record`/`replay`: `replay --explain` prints the evidence trail behind every passing assert (the flagship false-green tool — text mode; `--output-format json` already carries `assertions[].evidence`); `--decider-llm`/`--decider-dir` answer gates live during recording; `--rerecord-stale`/`--concurrency <N>` batch re-record; `--assert-from <scenario.yaml>`/`--reassert` re-check the on-disk `assert:` instead of the frozen one; `--strict`/`--fail-on-skill-drift` control staleness handling on replay; `--no-redact` skips record-time redaction; `--allow-failing` relaxes the post-run verdict gate; `--dry-run` resolves without recording; `--force` overrides the refusal to overwrite a default-path cassette that belongs to a *different* scenario (a slug collision) — not a general overwrite-anything flag; `replay --best-effort-future-cassette` lets a cassette from a newer format version replay anyway (warn instead of the default hard error).
+- `record`/`replay`: `replay --explain` prints the evidence trail behind every passing assert (the flagship false-green tool — text mode; `--output-format json` already carries `assertions[].evidence`); `--decider-llm`/`--decider-dir` answer gates live during recording; `record <dir/>` is itself a first-class batch input (recording a whole directory of scenarios), and `--rerecord-stale` re-records everything stale in one pass — `--concurrency <N>` bounds the parallelism for either; `--assert-from <scenario.yaml>`/`--reassert` re-check the on-disk `assert:` instead of the frozen one; `--strict`/`--fail-on-skill-drift` control staleness handling on replay; `--no-redact` skips record-time redaction; `--allow-failing` relaxes the post-run verdict gate; `--dry-run` resolves without recording; `--force` overrides the refusal to overwrite a default-path cassette that belongs to a *different* scenario (a slug collision) — not a general overwrite-anything flag; `replay --best-effort-future-cassette` lets a cassette from a newer format version replay anyway (warn instead of the default hard error).
 - `verify-cassettes`: privacy scan (email/currency/domain/path/machine-inventory) + staleness — exit 1 when verification RAN and found a real problem (a finding, a genuine drift, or scenario-prompt drift), exit 3 when it could NOT complete (an unverifiable-class staleness finding, a too-new cassette format, or a read error); whole-token allows via `--allow <regex>` (a pattern) / class-scoped `--allow-domain` / `--allow-email` / `--allow-path` / `--allow-machine-inventory` / `--allow-patterns-file <path>` (a **file** of patterns, one regex per line); `--skip-privacy` or `--skip-staleness` runs only part of the gate; a diverged scenario `prompt` vs. the cassette's frozen prompt is also a hard fail (its own `scenarioDrift` bucket), opt out with `--skip-scenario-drift`; `--margins` adds a per-cassette recorded-vs-budget report for count-bound assertions (a single-sample estimate — diagnostic only, never changes the gate verdict).
 - `stats`: reads `<runsRoot>/index.jsonl`, written automatically at every result; `--since`/`--baseline`/`--branch` filter; `--last <n>` windows per-scenario; `--reindex` rebuilds the index from the physical run-dir tree (the migration path for pre-index runs).
 - `diff`: `--changelog` renders known-field prose for a baseline diff; `--view tools|transcript|artifacts|meta` narrows a run/cassette diff to one section; normalization (default on) masks per-run noise (ids/timestamps/session markers/host paths) so two runs of the same scenario diff as identical — `--no-normalize` compares raw values.
@@ -690,7 +694,7 @@ jobs:
           anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
 ```
 
-Every run writes a Markdown verdict table (scenario, pass/fail, signals, cost/turns when available, staleness findings, and the replay-skipped-assertions honesty line) to the job summary. Inputs: `command`, `path` (required), `version` (npm dist-tag/version, default `latest` — intentional so recipes track the current release; pin an exact version for reproducible CI. The companion skill's `cowork-harness@>=1.9.0` floor guidance applies to ad-hoc CLI installs, not this input), `strict` (applies to `replay` (staleness findings), `lint`/`lint-skill` (WARN/INFO), and `analyze-skill` (any advisory finding); IGNORED — not forwarded — for `verify-cassettes`/`run`, which don't accept the flag), `fail-on-skill-drift` (**`replay`-only** — never forwarded to the analyzers), `extra-args`, `summary` (default `true`), `anthropic-api-key` (live lane only). See [`action.yml`](./action.yml) for the full input reference.
+Every run writes a Markdown verdict table (scenario, pass/fail, signals, cost/turns when available, staleness findings, and the replay-skipped-assertions honesty line) to the job summary. Inputs: `command`, `path` (required), `version` (npm dist-tag/version, default `latest` — intentional so recipes track the current release; pin an exact version for reproducible CI. The companion skill's `cowork-harness@>=1.10.0` floor guidance applies to ad-hoc CLI installs, not this input), `strict` (applies to `replay` (staleness findings), `lint`/`lint-skill` (WARN/INFO), and `analyze-skill` (any advisory finding); IGNORED — not forwarded — for `verify-cassettes`/`run`, which don't accept the flag), `fail-on-skill-drift` (**`replay`-only** — never forwarded to the analyzers), `extra-args`, `summary` (default `true`), `anthropic-api-key` (live lane only). See [`action.yml`](./action.yml) for the full input reference.
 
 The provided [GitHub Actions workflow](.github/workflows/ci.yml) runs a **seven-stage pipeline**. The **build** + **test** stages are the token-free gate you can copy into your skill repo; the `action-self-test`, `python`, `boundary`, `scenarios`, and `parity-drift` stages are this repo's own fidelity self-tests and are not directly portable (they build the harness's Docker image and run harness-specific e2e scenarios — see [`ci-recipe.md`](./.claude/skills/cowork-harness/references/ci-recipe.md) for the skill-repo template):
 
@@ -734,6 +738,8 @@ Most runs need **none** of these — the defaults are correct. They're grouped b
 - `COWORK_HARNESS_JUDGE_MODEL` — the default model for `semantic_matches`' LLM judge (overridden by a
   per-assertion `judge_model`; falls back to the pinned default `claude-opus-4-8`). Pin it alongside `judge_model` for a
   reproducible before/after comparison across re-records.
+- `COWORK_HARNESS_EVALUATOR_MODEL` — the default `critique` grading model (overridden by the `--evaluator-model` flag;
+  falls back to the pinned default `claude-opus-4-8`).
 - `COWORK_HARNESS_RUNS_DIR` (or the `--run-dir <path>` flag — a **global** flag that must precede the subcommand — `--dotenv` follows the same rule everywhere except `critique`, which also takes it per-command) — override the default run-output root `~/.cowork-harness/runs` (kept out of any working tree so sensitive skill inputs/outputs don't land in a repo). Precedence: `--run-dir` > env > default. The root is flat and machine-global (shared across projects); pinned `--session-id` runs are guarded against cross-project overwrite, and `prune` never prunes them. In CI, set it to a workspace path (e.g. `runs`) so artifact upload can collect the runs. `COWORK_HARNESS_ALLOW_FOREIGN_RESUME=1` overrides the guard that blocks `--resume` onto another project's pinned session.
 - **Networking / loop:** `COWORK_EGRESS_PROXY` overrides the egress-proxy URL injected into the sandbox; `COWORK_PROXY_IMAGE` overrides the egress proxy Docker image name (default `cowork-egress-proxy:2`); `COWORK_DOCKER_NETWORK` pins the Docker network the agent container joins; `CLAUDE_FORCE_HOST_LOOP=1` forces the host-loop path regardless of the baseline's loop decision (the `cowork` tier's auto-pick). `COWORK_LIMACTL` overrides the `limactl` binary path (default `/opt/homebrew/bin/limactl`).
 - `COWORK_HARNESS_PRERUN_HASH_CAP` — override the default cap on pre-run file hashing (bytes); raise it if `input_unmodified`/`no_unexpected_files` report evidence unavailable on a large connected folder.
@@ -840,6 +846,7 @@ a global install has them locally too, not just on GitHub.
 | [examples/README.md](./examples/README.md) | The worked examples to copy — sessions, scenarios, and skills you can run end-to-end (from a source checkout — a global npm install's only runnable `examples/` subtree is `replays/`; see the "What ships" table). |
 | [SECURITY.md](./SECURITY.md) | Threat model — the sandbox is a fidelity fixture, not a security boundary. |
 | [RELEASING.md](./RELEASING.md) | The release flow — branch → PR → tag → npm publish. |
+| [llms.txt](./llms.txt) | The AI-agent index — a machine-readable map of this repo's docs for an agent bootstrapping context. |
 
 ## Versioning
 

package/RELEASING.md

@@ -50,14 +50,14 @@ Never push the tag before CI is green for the exact commit you intend to tag. Th
 enforces this (`Require ci.yml success for this commit` step), but don't rely on it — tag a green
 SHA.
 
-**Tag the MERGE COMMIT (main HEAD after the merge), never the release-branch head — and here's why.**
-The publish gate (`require-ci-success`) queries `ci.yml` runs with `--event push` for the tagged SHA.
-`ci.yml` only triggers `on: push` for **`main`** (plus `pull_request` / `workflow_dispatch`), so a
-release-branch/PR head has *only* a `pull_request` run — which the `--event push` filter ignores.
-Tagging that SHA makes the gate poll ~30 min and then FAIL. Only the merge commit (produced by
-`gh pr merge`, then `git pull`ed onto `main`) has a push-event `ci.yml` run. This is why Phase 3 tags
-`main` HEAD after the merge — do **not** "optimize" by tagging the branch commit whose PR CI you just
-watched go green.
+> **Tag the MERGE COMMIT (main HEAD after the merge), never the release-branch head — and here's why.**
+> The publish gate (`require-ci-success`) queries `ci.yml` runs with `--event push` for the tagged SHA.
+> `ci.yml` only triggers `on: push` for **`main`** (plus `pull_request` / `workflow_dispatch`), so a
+> release-branch/PR head has *only* a `pull_request` run — which the `--event push` filter ignores.
+> Tagging that SHA makes the gate poll ~30 min and then FAIL. Only the merge commit (produced by
+> `gh pr merge`, then `git pull`ed onto `main`) has a push-event `ci.yml` run. This is why Phase 3 tags
+> `main` HEAD after the merge — do **not** "optimize" by tagging the branch commit whose PR CI you just
+> watched go green.
 
 When you query runs by SHA, use the **full 40-char SHA** (`git rev-parse HEAD`) —
 `gh run list --commit <short-sha>` silently returns empty. If you mis-tag: `git push origin

package/dist/agent/session.js

@@ -4,6 +4,41 @@ import { createWriteStream } from "node:fs";
 import { join } from "node:path";
 import readline from "node:readline";
 import { TimelineWriter } from "./timeline.js";
+import { BoundaryError } from "../errors.js";
+/**
+ * Compose multiple SDK-MCP bundles into one, so a tier can pass several in-process servers through the
+ * single `sdkMcp` slot `AgentSession.init/start` accepts (e.g. container: `cowork` + `skills` + `plugins`;
+ * hostloop: `workspace` + `skills` + `plugins`). `servers` is the plain concatenation (order preserved,
+ * first-bundle-first); `handle` routes each `mcp_message` to the ONE bundle that declared the message's
+ * `server_name` — the dispatcher already threads `server` through every `handle(server, jr)` call (see
+ * `AgentSession.pump`'s mcp_message branch), so routing by that name is additive, not new plumbing. A
+ * `server_name` no bundle declared (shouldn't happen — the agent only addresses a server it was told
+ * about via `sdkMcpServers` in `initialize`) surfaces the SAME "no handler configured" shape the
+ * no-`sdkMcp`-at-all path already uses, rather than throwing. A bundle's own `handle` may still throw or
+ * reject — that propagates UNCHANGED to the caller (which already catches it, see the `mcp_message`
+ * branch's try/catch), so no sub-handler error is swallowed or reshaped here.
+ */
+export function combineSdkMcp(...bundles) {
+    const servers = bundles.flatMap((b) => b.servers);
+    const byServer = new Map();
+    for (const b of bundles)
+        for (const s of b.servers) {
+            // Fail loud on a wiring mistake: two bundles claiming the same server name would silently shadow
+            // one handler and double the name in `sdkMcpServers`. Names are distinct today; this guards regressions.
+            if (byServer.has(s))
+                throw new BoundaryError(`combineSdkMcp: duplicate sdkMcp server name "${s}"`);
+            byServer.set(s, b.handle);
+        }
+    return {
+        servers,
+        handle: (server, jsonrpc) => {
+            const handle = byServer.get(server);
+            if (!handle)
+                return { error: { code: -32601, message: `no sdkMcp handler configured for server "${server}"` } };
+            return handle(server, jsonrpc);
+        },
+    };
+}
 // ---- Protocol ingress validation (fail-closed) ----
 /** Every control_request that the driver answers carries a non-empty string `request_id` — it is the
  *  address the control_response is written back to. A missing / non-string / empty id means the agent sent

package/dist/assert.js

@@ -1011,10 +1011,18 @@ function check(a, ctx) {
             results.push(fail(`tool_available: bad regex "${a.tool_available}": ${c.error}`));
         else if (ctx.availableTools === undefined)
             results.push(fail(`evidence unavailable: availableTools absent from result.json — cannot evaluate tool_available`));
-        else
-            results.push(ctx.availableTools.some((t) => c.re.test(t))
-                ? ok()
-                : fail(`no tool in the init manifest matched "${a.tool_available}" — note context.tools is the EAGERLY-LOADED tool set; a factory-deferred tool (surfaced via a system-reminder, e.g. the skill-discovery tools) can be available yet absent here, so a miss is "not eagerly loaded", not "provably unavailable"`));
+        else if (ctx.availableTools.some((t) => c.re.test(t)))
+            results.push(ok());
+        else {
+            // The general caveat applies to every miss; the discovery-server paragraph is appended ONLY when
+            // the pattern actually concerns those tools, so an ordinary `tool_available: "Bash"` miss isn't
+            // buried under ~450 characters about a surface it never mentioned.
+            const discoveryRelevant = /mcp__(?:skills|plugins)/.test(a.tool_available);
+            results.push(fail(`no tool in the init manifest matched "${a.tool_available}" — note context.tools is the EAGERLY-LOADED tool set; a factory-deferred tool (surfaced via a system-reminder) can be available yet absent here, so a miss is "not eagerly loaded", not "provably unavailable"` +
+                (discoveryRelevant
+                    ? `. The mcp__skills__*/mcp__plugins__* discovery tools ARE modeled as alwaysLoad on container/hostloop (and cowork, which resolves to one of those) — a miss there is a real absence, but microvm/protocol still declare no such server, so a miss on those tiers means "not modeled at this tier", not "provably unavailable"`
+                    : "")));
+        }
     }
     if (a.skill_tool_used !== undefined) {
         const { skill, tool } = a.skill_tool_used;