Execute the first v2/main → main milestone merge and cut the release

[cliffhall]

Why this merge is different from every one that follows

This is the first v2/main → main milestone merge, and it is the only one that will look like this. Read the sequence below as a one-off, not as the template.

Three things make it exceptional, and all three are consequences of the 2.0.0 go-live rather than of anything in v2.1.0:

1. The branches only just acquired a shared history. main and v2/main had unrelated histories until the go-live merge (chore: replace main's tree with v2 #1830) established merge base 4d30d1cd by replacing main's tree with v2's. That makes this an ordinary merge — but it is the first time that has been true, which is why the "never use --allow-unrelated-histories" warning below needs saying at all.
2. It needed convergence work that future merges will not. Because main accumulated rc-series changes during the 2.0.0 run that v2/main never saw, two PRs existed purely to make this merge tractable: docs: converge README Test servers section with main's restructure #1880 (README Test servers convergence — the PR that removes the one conflict hunk) and chore(deps): bring main's rc-series bumps to v2/main (@hono/node-server 2.x, vite 8.1.5) #1881 (main's dependency bumps brought onto v2/main). Nothing analogous will be needed again.
3. The payload is repo infrastructure, not product work. The tree swap dropped files that lived only in the old tree, so most of this milestone restores them (SECURITY.md, the Claude workflow, dependabot.yml, the CoC) or adapts docs to the new contribution model. Exactly one PR (fix(core): mirror SEP-2243 x-mcp-header args to Mcp-Param-* on tools/call #1847) changes runtime behavior. A normal milestone will invert that ratio. See the milestone overview comment for the full grouped breakdown.

After this lands, the steady-state merge is just steps 1–3 with no conflict and no convergence PRs. Once v2/main's tip is an ancestor of main, and main continues to make no content changes of its own, every subsequent milestone merge is conflict-free — see "Then it's self-sustaining" at the bottom. The one-time cost is this merge.

Do not generalize the pre-flight below either. The branch-protection check and the PR-vs-direct-merge decision are first-time questions; once answered they stay answered.

---

Sequence

git fetch origin

# 1. Merge the milestone's work into the release branch.
git checkout -B main origin/main
git merge --no-ff origin/v2/main -m "chore: merge v2/main for <version> milestone release"
#    → PR #1880 is the convergence step. If it has merged, expect ZERO
#      conflicts. If it hasn't, expect exactly ONE conflict hunk in README.md
#      (the stale-vs-corrected `Mcp-Param-*` callout) — take v2/main's side.
#      Measured in a scratch worktree, not estimated.

# 2. Gate before it becomes the release.
npm install && npm run ci

# 3. Publish the branch, then cut the release from it.
git push origin main
npm version <major|minor|patch>   # on main
git push --follow-tags
#    → draft & publish the GitHub Release for that tag; the `publish` job runs
#      pack:verify and publishes the `latest` dist-tag

# 4. Back-sync only what release adds (version bump), so package.json doesn't
#    diverge and conflict on every future merge.

Ordinary merge — the branches share merge base 4d30d1cd (established by the go-live merge #1830). Never use --allow-unrelated-histories; see the correction block in #1821's description.

Do not "fix" this with a back-merge of main into v2/main. That was built and rejected — see #1868 (closed). It would make this first merge conflict-free, but only by pulling 224 commits, 212 of them pre-swap v1-tree commits, permanently into the develop branch's ancestry. git log, bisect, and every GitHub compare on v2/main would carry the v1 lineage from then on. It is not worth avoiding a three-line conflict once, and after this merge the problem does not recur at all (see "Then it's self-sustaining" below).

Pre-flight

• Branch protection on main permits a maintainer merge commit — the only thing that can block this. Everything else is verified.
• Decide whether the merge goes through a PR (v2/main → main, reviewable, consistent with the no-direct-pushes posture) or a direct maintainer merge. Note closing keywords do work in such a PR, since main is the default branch.

After it lands

• @claude should work again — comment @claude review on any open PR (claude[bot] replied in ~19s on docs: refresh V2 board Status option IDs in AGENTS.md (#1823) #1825). Workflows for issue_comment events run from the default branch, so ci: restore the Claude Code workflow and .mcp.json, lost in the v2 tree swap #1869 is inert until now.
• Dependabot version-update PRs should start appearing against v2/main, and security updates should still appear (they're a repo setting, and ran while dependabot.yml was missing entirely — build(deps): bump the npm_and_yarn group across 5 directories with 12 updates #1833, build(deps): bump the npm_and_yarn group across 5 directories with 2 updates #1840 — but target-branch is documented as affecting security-update behavior, so confirm).
• Release notes call out the Node engine bump (>=22.7.5 → >=22.19.0).

Then it's self-sustaining

Once v2/main's tip is an ancestor of main, and main makes no content changes of its own, every subsequent milestone merge is conflict-free with no back-merge needed. This one-time conflict is the whole cost.

[cliffhall]

Deliberately not getting a PR in the current fan-out, and it shouldn't.

This issue isn't a change to v2/main — it is the v2/main → main merge, so the only PR that could represent it is a cross-branch release PR targeting main. It's also blocked on every other sub-issue of #1821 landing first: merging before #1874 means resolving the README section by hand, and merging before #1875 means the release ships without the rc-series security bumps.

It stays Todo until the rest of #1821's plan is merged. At that point the sequence in the description above is ready to execute as-is — and per its pre-flight list, the two things to settle first are whether branch protection on main permits a maintainer merge commit, and whether the merge goes through a reviewable PR or a direct merge.

[cliffhall]

Triage: Priority = High

Scored 11/16 with the priority rubric added to AGENTS.md in #1891. This card is already approved and sitting in Todo — only Priority was set here, its Status is unchanged.

Axis	Score	Reasoning
Severity / impact	4/5	This is the v2.1.0 release — the milestone merge and publish. Nothing in the milestone reaches a user until it runs, including the four High-priority published-v2 defects triaged this week. Not a 5 because users aren't stranded: v2.0.0 is already out and working for most.
Urgency / staleness	5/5	Blocking a release, with the v2.1.0 milestone due 2026-08-05 — four days out.
Signal bonuses	+2	milestone (v2.1.0) (+1), assigned (+1)
Total	11	Lands in the High band (9-11).

Related issues. These look connected and may be worth reading together:

• pack:verify: await the --web child's exit before removing its work dir #1826 — pack:verify is part of the release gate this runs, and its cleanup race is a live flake risk during exactly this sequence
• go-live 9/9: write the v1 to v2 migration guide #1822 — the v1→v2 migration guide is meant to ship alongside the swap this completes

Worth a second look. Highest-scoring item in the Todo column. Everything else in v2.1.0 is effectively gated behind it.

Scores are a starting point, not a verdict — the rubric is meant to be overruled when it's plainly wrong, provided the reason is written down.

[cliffhall]

Milestone overview — what v2.1.0 actually contains

Scope measured against origin/main, not against the milestone label: 9 merged PRs sit on v2/main and are not yet in main (git rev-list --count origin/main..origin/v2/main → 9), plus 5 open PRs in review. That is the payload this merge carries.

The shape of it is unusual and worth stating plainly: this milestone is mostly repo infrastructure, not product work. Exactly one PR changes runtime behavior. The rest exists because the 2.0.0 tree swap replaced main's tree wholesale and took a set of repo-level files with it, or because the contribution model changed underneath us in the same week.

---

1. Security & dependency hardening (2 PRs, both in review)

Both are dev-scope — neither ships in the tarball — and both were deferred out of the pre-2.0.0 sweep (#1837) precisely so a major upgrade wouldn't land immediately before an irreversible publish.

PR	Issue	What it does
#1899	#1839	vitest / @vitest/browser / @vitest/browser-playwright / @vitest/coverage-v8 → 4.1.10, clearing GHSA-p63j-vcc4-9vmv (critical) plus two more. Storybook 10.2.19 → 10.5.5 to satisfy the exact peer pins. clients/web audit 19 → 1.
#1900	#1838	eslint 10, clearing the brace-expansion DoS from all five lockfiles. Dropping @eslint/eslintrc took js-yaml with it, clearing a second high advisory for free.

Two things about #1900 worth knowing before review: it is larger than a version bump because eslint 10 surfaced 21 genuine violations — 15 preserve-caught-error sites, 2 dead initializers, and 8 react-hooks/set-state-in-effect sites — all fixed in code, with no rule disabled or scoped away. And the issue's predicted fix for #1839 does not work: even naming every vitest and Storybook package in one npm i -D still ERESOLVEs, because npm resolves against the existing lock tree. Regenerating clients/web/package-lock.json is the only mechanism, which is why that lock diff is large — it is the fix, not churn.

⚠️ These two collide on merge order. #1899 pins eslint-plugin-react-hooks to ~7.0.1 (tracked as #1897) as a deliberate hold; #1900 is forced to 7.1.1, since 7.0.1's peer range stops at ^9.0.0 and ERESOLVEs against eslint 10. If #1899 merges after #1900, that pin drops the version back and breaks lint. Both also touch clients/web/package.json and its lockfile, so whichever goes second needs a rebase regardless. #1897 should close with #1900 rather than be worked separately.

2. Tree-swap recovery — files main had that v2/main didn't (3 PRs, all merged)

The swap (#1830) replaced main's tree with v2's, so anything living only in the old tree vanished from the released branch. Each of these is a restoration, and each is written so the next swap-like event can't repeat it.

• ci: restore the Claude Code workflow and .mcp.json, lost in the v2 tree swap #1869 (Claude Code workflow (.github/workflows/claude.yml) and .mcp.json lost in the v2 tree swap — @claude no longer triggers #1850) — .github/workflows/claude.yml + .mcp.json. This is why @claude has been inert: workflows for issue_comment events run from the default branch, so the restored workflow does nothing until this merge lands.
• chore: restore repo files dropped by the v2 tree swap #1871 (Restore repo files dropped by the v2 tree swap (dependabot, issue template, .gitattributes, CoC) #1870) — dependabot.yml, the legacy issue template, .gitattributes, Code of Conduct.
• docs: restore SECURITY.md on v2/main, so the next tree swap can't drop it #1867 (SECURITY.md is missing from v2/main — the next milestone merge will drop it from main again #1864) — SECURITY.md, restored on v2/main specifically so the next milestone merge can't drop it from main again.

3. Contribution model & branch policy (4 PRs — 3 merged, 1 in review)

The repo moved to Collaborators-only in the go-live, making issues the single intake channel for everyone outside the org. These make that legible.

• docs: post-swap branch model, PR policy, milestone rule, and Copilot review instructions #1866 (Post-swap docs: correct the branch model, PR policy, and stale AGENTS.md content #1873, Add .github/copilot-instructions.md so Copilot reviews against our actual conventions #1877) — post-swap branch model, PR policy, the milestone rule, and .github/copilot-instructions.md so Copilot reviews against our actual conventions. (docs: add .github/copilot-instructions.md and require mirroring into it #1878 was the standalone attempt; superseded and closed.)
• docs: unpin the branch-pinned CONTRIBUTORS.md links in the PR template #1879 (docs: reconcile the v1 policy wording and fix branch-pinned PR-template links #1813) — reconciles the v1 policy wording and unpins branch-pinned links in the PR template.
• docs: rename CONTRIBUTORS.md to CONTRIBUTING.md so GitHub surfaces the policy #1884 (Rename CONTRIBUTORS.md → CONTRIBUTING.md so GitHub surfaces the contributing policy #1883) — CONTRIBUTORS.md → CONTRIBUTING.md, so GitHub actually surfaces the policy in its contribution UI.
• docs: replace the markdown bug template with GitHub issue forms #1894 (docs: add issue templates for the issues-only contribution model #1844, in review) — replaces the legacy markdown bug template with GitHub issue forms (enforced required fields: client, version line, transport). Deliberately no security template — a .yml template still opens a public issue, which is the one thing a vulnerability report must not do; it wires a contact link to /security/advisories/new instead.

4. Board & triage process (1 PR in review, plus board-only work)

• docs: add Incoming to both boards, adopt the v2 Priority field, and document the triage rubric #1892 (Boards: add an Incoming status to both boards, adopt the v2 Priority field, and document the triage rubric #1891, in review, approved) — adds Incoming to both boards, adopts the v2 Priority field, and documents the scoring rubric so triage is derived rather than asserted. Also hardens the updateProjectV2Field hazard guidance and adds a snapshot/recovery recipe — that mutation full-replaces the option list and has orphaned every card on the board twice.
• Triage the open issue backlog: backfill v1/v2 labels, close legacy, board the rest #1872, go-live 7/9: triage and bulk-close the v1 PR backlog #1819 closed with no PR — backlog triage and v1 PR-backlog closure were board actions, not code.

5. Protocol correctness — the only runtime change in the milestone (1 PR, merged)

• fix(core): mirror SEP-2243 x-mcp-header args to Mcp-Param-* on tools/call #1847 (tools/call omits SEP-2243 Mcp-Param-* headers (x-mcp-header mirroring), rejected by strict modern servers #1846) — tools/call omitted the SEP-2243 Mcp-Param-* headers, so strict modern servers rejected the call. The SDK only mirrors inside client.callTool() and skips it in the browser; the Inspector routes through client.request() to drive MRTR manually, so it now builds the mirrored headers itself — on every client, web included.

6. Merge convergence — work whose only purpose was making this merge possible (2 PRs, merged)

• docs: converge README Test servers section with main's restructure #1880 (Converge README.md on v2/main with main's restructured Test servers section #1874) — converges the README Test servers section with main's restructure. This is the PR that removes the one conflict hunk from the sequence below.
• chore(deps): bring main's rc-series bumps to v2/main (@hono/node-server 2.x, vite 8.1.5) #1881 (Bring main's rc-series dependency bumps to v2/main (@hono/node-server 2.x, vite 8.1.5) #1875) — brings main's rc-series bumps (@hono/node-server 2.x, vite 8.1.5) onto v2/main so the two branches don't disagree on dependencies at the merge point.

#1868 — the rejected alternative. A back-merge of main into v2/main would have made this merge conflict-free, but only by pulling 224 commits, 212 of them pre-swap v1-tree commits, permanently into the develop branch's ancestry. Closed unmerged. The three-line conflict is cheaper than that lineage, and it does not recur.

7. Tooling reliability (1 PR in review)

• fix(scripts): await the pack:verify web child's exit before removing its work dir #1895 (pack:verify: await the --web child's exit before removing its work dir #1826) — pack:verify SIGTERM'd the --web child and rmSync'd its work dir in the same breath. Extracts scripts/lib/child-cleanup.mjs so this file and smoke-tui.mjs (fixed for the same race in fix: wait for the TUI to exit before removing its temp dir (#1801) #1814) can't drift apart again — which is the whole reason pack:verify: await the --web child's exit before removing its work dir #1826 existed as a follow-up.

---

Not in this milestone's payload

• docs: new modelcontextprotocol.io Inspector documentation for v2 (legacy vs. modern era, more screenshots) #1803 — the modelcontextprotocol.io docs rewrite. Lands in the modelcontextprotocol/docs repo, not this one; no PR exists yet. Tracked here for ownership only, so it does not gate the release.
• test: cover v2/main mid-session-auth code to the ≥90% per-file gate (cliOAuth.ts, TUI App.tsx, AuthTab.tsx) #1610 / PR test: cover v2/main mid-session-auth code to the ≥90% per-file gate #1611 — carries the v2.1.0 milestone but merged 2026-07-06 and already shipped in 2.0.0 (its merge commit is an ancestor of origin/main). A milestone-assignment artifact, not pending work.
• plan: v2 go-live runbook — deprecate v1 (1.0.1), branch v1/main, swap main to v2, publish 2.0.0, close v1 backlog, restrict external PRs #1804 / go-live 7/9: triage and bulk-close the v1 PR backlog #1819 / go-live 8/9: post-swap docs, labels, boards, and integration hygiene #1821 — the go-live umbrellas. Their code shipped as 2.0.0 (chore: v1 deprecation notices in all four packages, bump to 1.0.1 #1827, chore: replace main's tree with v2 #1830); what remained here was docs and board hygiene, delivered by the PRs above.

Release-note candidates

Only three items are user-visible; everything else is repo hygiene a consumer never sees:

1. tools/call now sends Mcp-Param-* headers (fix(core): mirror SEP-2243 x-mcp-header args to Mcp-Param-* on tools/call #1847) — fixes rejection by strict modern servers.
2. Node engine floor >=22.7.5 → >=22.19.0 (already called out in the pre-flight below).
3. Issue forms + issues-only contribution model (docs: replace the markdown bug template with GitHub issue forms #1894, docs: rename CONTRIBUTORS.md to CONTRIBUTING.md so GitHub surfaces the policy #1884) — changes how people report things.