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

[cliffhall]

Status 2026-08-02 — the merge is built and waiting on one approval.

PR #1903 is open, MERGEABLE, with npm run ci green on the merged tree. Everything below that was a question has been answered; the original plan needed three corrections, all applied. The only thing left is a maintainer approval (olaservo / BobDickinson) — then merge, then cut the release.

The full v2.1.0 payload — 14 commits, grouped — is in the milestone overview comment.

Why this merge is different from every one that follows

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

1. The branches only just acquired a shared history. They had unrelated histories until the go-live merge (chore: replace main's tree with v2 #1830) established merge base 4d30d1cd. 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 needs saying at all.
2. It needed convergence work that future merges will not. docs: converge README Test servers section with main's restructure #1880 (README) and chore(deps): bring main's rc-series bumps to v2/main (@hono/node-server 2.x, vite 8.1.5) #1881 (main's rc-series deps) existed purely to shrink this merge. 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. 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.

Do not "fix" the divergence with a back-merge of main into v2/main. Built and rejected — see #1868 (closed). It would make the 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.

The sequence

Step 1 is done. #1903 carries it.

# 1. DONE — the merge, resolved on a branch cut from main so v2/main
#    stays untouched (see "the eight conflicts" below).
#      git checkout -b v2/chore/milestone-merge-v2.1.0 origin/main
#      git merge --no-ff origin/v2/main
#    → merge commit 6233d8bb, parents fb1b0cb4 (main) + 834fd2d7 (v2/main)
#    → npm run ci green on the merged tree
#    → opened as PR #1903

# 2. Get ONE approving review on #1903, then merge it with the button
#    (or `gh pr merge 1903 --merge`). A local merge + `git push origin main`
#    is REJECTED — see "main is ruleset-protected" below.

# 3. Cut the release. The version bump is ALREADY on #1903's branch
#    (dedee5af, root package.json 2.0.0 -> 2.1.0), so there is no
#    second bump PR. Two equivalent ways to do this after #1903 merges:
#
#    (a) ENTIRELY IN THE GITHUB UI — no local git needed. Releases > Draft
#        a new release > "Choose a tag" > type 2.1.0 > "Create new tag on
#        publish", with Target = main. Publishing creates the tag AND the
#        release in one step.
#
#    (b) Or from the CLI, if you prefer the tag to exist first:
#          git fetch origin && git checkout main && git pull
#          git tag 2.1.0 && git push origin 2.1.0   # tags are NOT ruleset-protected
#        then draft & publish the release for that tag (UI, or
#        `gh release create 2.1.0 --title 2.1.0 --notes "..."`).
#
#    Either way, publishing the RELEASE is what publishes to npm. Both
#    publish jobs are gated on `github.event_name == 'release'`, so a tag
#    push alone runs the `build` job (the workflow's `on: push:` is
#    unqualified) but will NOT publish. The `publish` job runs pack:verify,
#    asserts the tag matches package.json's version, and pushes the
#    `latest` dist-tag.

Why the tag comes after the merge, not with the bump. #1903 merges as a merge commit, so dedee5af lands on main intact — but only once it merges. A tag created now would point at a commit that isn't on the release branch yet, which is why the bump used npm version --no-git-tag-version. With option (a) the tag is never pushed by hand at all; GitHub creates it against main when you publish.

The eight conflicts — resolved, and the prediction that was wrong

This issue originally predicted zero conflicts once #1880 landed. That went stale: main subsequently took 8 post-swap commits v2/main never did (#1843, #1842, #1841, #1837, #1836, #1835, #1834, #1832, #1831), and #1899/#1900 regenerated every lockfile. A direct v2/main → main PR (#1901, closed) came up CONFLICTING in 8 files.

All eight took v2/main's side in #1903, each verified rather than assumed:

File	Conflict	Why v2/main wins
README.md	content	main's Mcp-Param-* callout is stale; v2/main's is corrected by #1847
SECURITY.md	add/add	restored independently (#1843 / #1867); differ by one line — the CONTRIBUTORS.md → CONTRIBUTING.md rename (#1884)
clients/web/package.json	content	vitest ^4.1.0 → ^4.1.10, the #1899 security fix
root + 4 client package-lock.json	content	took v2/main's, then regenerated from a clean npm install — zero drift

⚠️ Never resolve these with GitHub's web "Resolve conflicts" button. It commits to the head branch — merging main into v2/main, i.e. exactly the #1868 back-merge. Resolving on a branch cut from main avoids that, and the merge commit still carries v2/main's tip as its second parent, so the self-sustaining property below still holds.

main is ruleset-protected

Classic branch protections are not configured (GET /branches/main/protection → 404), which is misleading — protection comes from rulesets. Two target ~DEFAULT_BRANCH, and 2749948 grants bypass to nobody, repo admins included.

• A PR is mandatory. git push origin main is rejected. Applies to npm version too.
• 1 approving review, from someone other than the author. A Copilot approval does not count.
• The build check must pass.
• allowed_merge_methods includes merge, so the --no-ff merge commit is permitted — merge via the button, not a local merge + push.
• Not blockers, verified: require_code_owner_review is inert (no CODEOWNERS anywhere), and the release tag is unrestricted (the only tag ruleset matches refs/tags/1.*).

Pre-flight

• Branch protection on main permits a maintainer merge commit — it does, but only via a PR.
• Decide PR vs. direct maintainer merge — not a choice; a PR is mandatory.
• Conflict expectations — 8 conflicts, all resolved in chore: merge v2/main for the v2.1.0 milestone release #1903, npm run ci green.
• Approving reviewer available — olaservo and BobDickinson.
• Get the approval on chore: merge v2/main for the v2.1.0 milestone release #1903 and merge it.
• Cut the release — push the 2.1.0 tag, then draft & publish the GitHub Release (step 3 above). The version bump is already on the branch, so no second PR.

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 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) and fix(core): mirror SEP-2243 x-mcp-header args to Mcp-Param-* on tools/call #1847 (tools/call now sends the SEP-2243 Mcp-Param-* headers) — the only two user-visible changes, plus the 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).
• Close this issue manually once the release is published. chore: merge v2/main for the v2.1.0 milestone release #1903 says References #1876, not Closes, so it will not auto-close on merge — deliberate, since merging is only step 2 of 3.

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.

The last thing standing in the way of that was .github/workflows/main.yml — the only file where main still had content v2/main lacked (#1831 least-privilege token, #1834 dist-tag derivation, #1836 OIDC trusted publishing). Fixed by #1904 (Closes #1902, merged 07a2b4bd): since v2/main had nothing main lacked except the superseded publish step, it took main's file verbatim. git diff origin/main origin/v2/main -- .github/workflows/main.yml is now empty.

[cliffhall]

Triage record: Priority High — scored 11/16 (severity 4, urgency 5, +2 for milestone and assignee) with the rubric added in #1891. Retained as an audit trail of the rubric; nothing here is needed to execute the merge.

Superseded detail: this was written while the card was in Todo and #1826 was an open flake risk. Both have since moved — the card is In Progress and #1826 shipped in this milestone.

[cliffhall]

Milestone overview — what v2.1.0 actually contains

Status 2026-08-02 — merged and built. All 14 PRs below are on v2/main and carried by PR #1903, which is open, MERGEABLE, and green on npm run ci. Their issues are closed and their board cards are Done.

v2/main is now 15 commits ahead of main, not 14: #1904 (the .github/workflows/main.yml sync, Closes #1902) landed after #1903's branch was cut, so it is not in this release. That's harmless — it only repairs v2/main's copy of a file main already has correct, and workflows aren't in the published tarball.

Scope measured against origin/main, not against the milestone label — 14 PRs, the payload #1903 carries (git rev-list --count origin/main..834fd2d7 → 14).

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 ✅ merged)

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 worth carrying into the release notes: #1900 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.

✅ The merge-order hazard — resolved as specified. #1899 pinned eslint-plugin-react-hooks to ~7.0.1 (tracked as #1897) as a deliberate hold; #1900 required 7.1.1, since 7.0.1's peer range stops at ^9.0.0 and ERESOLVEs against eslint 10. Merging them in the wrong order would have dropped the version back and broken lint.

#1899 was merged first (23e0c39d), then #1900 (834fd2d7). As expected, #1900 went CONFLICTING the moment #1899 landed; it was brought up to date with a merge from v2/main, the ~7.0.1 hold removed, all five lockfiles regenerated from a clean root npm install rather than hand-merged, and npm run ci re-run green end to end (coverage gate, build gate, all smokes, 462 Storybook tests) before merging.

Verified on v2/main after the merge — clients/web/package.json now declares "eslint-plugin-react-hooks": "^7.1.1" with no hold remaining, while #1899's other holds survived intact (zod: "~4.3.6", vitest 4.1.10, Storybook 10.5.5 — those stay held; see v2.2.0 below). #1897 is closed, resolved by #1900 rather than 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, all ✅ merged)

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) — 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 ✅ merged, 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, approved before merge) — 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, ✅ merged)

• ✅ 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.

Spun out of #1839 into v2.2.0 — not part of this release

Untangling the vitest peer knot floated two in-range dependencies that broke the gate for reasons unrelated to the security fix. Both were held rather than silently pinned, and both holds ship as-is in v2.1.0; the follow-up work is milestoned v2.2.0 and is not a candidate for this merge:

• chore(deps): zod 4.4 blows the tsc heap in clients/web — held at ~4.3.6 #1896 (v2.2.0, Medium) — zod held at ~4.3.6 in clients/web and the root; 4.4.3 blows the tsc -b heap.
• chore(storybook): drop the now-redundant setProjectAnnotations call (Storybook >= 10.3 applies it automatically) #1898 (v2.2.0, Low) — Storybook 10.5.5 reports setProjectAnnotations as redundant. Deliberately not removed: ./preview carries the Mantine decorator and the a11y annotations that drive the play-function assertions, so if auto-provisioning missed either, the 462 stories would render unthemed and a11y-inert and still pass. A green run wouldn't prove it safe.

A third, #1897 (react-hooks 7.1), was also filed against v2.2.0 but got resolved early — #1900 was forced to take 7.1.1 regardless, so it closed with this milestone rather than waiting.

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.