chore(release): merge v2/main into main for v2.11.0

.claude/skills/pr-flow/SKILL.md

@@ -83,13 +83,41 @@ branch cut from `v2/main` arrives at `v1/main` carrying the whole v2 tree
 (Copilot). And never cut from a milestone-merge branch — it carries release-only
 commits that will show up in your PR's diff.
 
-Working in a git worktree is fine and often preferable. ⚠️ **A worktree needs a
-real `npm install`, not a symlinked `node_modules`** — a symlink passes
-lint/test/coverage and then fails all Storybook story files on Vite's
-`fs.allow`.
+**Always cut it into a new git worktree, never by switching branches in the
+primary checkout** (#2661). This repo is routinely worked by several agent
+sessions on one machine at once, and they share the primary checkout: a
+`git switch` there moves the branch out from under every other session using
+it, and carries one task's uncommitted edits, build output and `node_modules`
+state into another's. A worktree per issue gives each task its own tree and
+leaves the primary checkout alone.
+
+Run it from the primary checkout. The worktree is a **sibling** directory named
+for the checkout plus the issue number (`mcp-inspector-v2` →
+`../mcp-inspector-v2-2661`), never a directory inside the repo, where every
+lint, format and typecheck scope would see a second copy of the source:
+
+```sh
+git fetch origin
+git worktree add --no-track "../$(basename "$PWD")-<ISSUE_NUMBER>" \
+  -b v2/fix/<ISSUE_NUMBER>-<slug> origin/v2/main     # origin/v1/main for v1
+cd "../$(basename "$PWD")-<ISSUE_NUMBER>"
+npm install
+```
+
+- `--no-track` keeps the new branch from tracking `origin/v2/main`, so
+  `git status` does not report your work as "ahead of v2/main" and the first
+  push is an explicit `git push -u origin <branch>` to a branch of its own name.
+- ⚠️ **The `npm install` is part of the step, not optional.** A worktree starts
+  with no `node_modules`, and it needs a **real** install — a symlinked
+  `node_modules` passes lint/test/coverage and then fails all Storybook story
+  files on Vite's `fs.allow`. Background it if you have edits to make first;
+  the gate needs it finished.
+- Every later step — edits, the gate, commits, the push — runs **inside the
+  worktree**.
 
 For order-dependent PRs on one issue, **stack** them: each branch is based on the
-previous one, not all cut from `v2/main`.
+previous one, not all cut from `v2/main` — so the child's worktree is cut from
+the parent branch (`git worktree add … -b <child> <parent-branch>`).
 
 ## 3. Sign off every commit
 
@@ -453,3 +481,16 @@ nothing else.
 `Done` is only for work that **shipped** — a merged PR, or a parent whose last
 sub-issue closed. Anything else (duplicate, won't fix, not planned, obsolete)
 means nothing shipped, so **delete the card** instead; see `/board-ops`.
+
+**Then remove the worktree and its local branch**, from the primary checkout,
+once the PR shows as merged (or closed, for work abandoned). A stale worktree
+keeps its branch checked out — git refuses to check that branch out anywhere
+else — and holds a full `node_modules` on disk per issue:
+
+```sh
+git worktree remove "../$(basename "$PWD")-<ISSUE_NUMBER>"
+git branch -D v2/fix/<ISSUE_NUMBER>-<slug>
+```
+
+`git worktree remove` refuses a worktree with uncommitted or untracked changes;
+read what is there before reaching for `--force`.

.claude/skills/pre-push-gate/SKILL.md

@@ -98,6 +98,21 @@ stale install otherwise passes every check and fails later as a behavioral test
 reporting the *old* dependency's behavior as a product bug (#2494). Don't
 "fix" that test.
 
+### `verify:install-scripts`
+
+A dependency with an install script is neither allowed nor denied in the
+`allowScripts` of the `package.json` beside that lockfile (#2712) — usually a
+dependency you just added or bumped. npm 11.x still **runs** such a script, so
+this is a review decision, not a typo: add `"<name>": false` to block it, or
+`"<name>@<version>": true` if the package genuinely needs it. Each install
+reads only its own manifest, so a package held by several installs needs an
+entry in each. A **non-registry** dependency (git, file, remote tarball) is
+reported even with no flagged script, since npm may run its `prepare`; clear it
+with a key equal to its exact `resolved` spec from the lockfile. A **bundled**
+one can't be cleared by any key — the fix is the dependency that bundles it.
+Don't reach for `ignore-scripts` — it also disables the root
+`postinstall` that installs every client.
+
 ### `local:dco`
 
 A commit in `origin/v2/main..HEAD` (minus anything already on `origin/main`)
@@ -178,6 +193,25 @@ lowering the gate. See `/testing` for the acceptable reasons.
 Also check the file is inside a gated directory — the web coverage `include` is
 a whitelist, so a module placed outside it falls out of the gate silently.
 
+### `verify:coverage-scope`
+
+The last step of `coverage` (#2709). A client's `coverage-summary.json` is
+missing files its own coverage `include`/`exclude` declares, so those files
+were never judged by the per-file gate. The failure names the client and each
+missing file. Two causes:
+
+- **The run's glob matching changed** — typically a Vitest bump. The fix is
+  the client's `include` patterns (an absolute `path.join(dirname, …)` pattern
+  means the same thing under every matcher), never an entry that excuses the
+  files.
+- **A file is in scope but the run legitimately drops it.** State it in
+  `KNOWN_OMISSIONS` in `scripts/verify-coverage-scope.mjs`, with the reason —
+  or, better, add it to the client's coverage `exclude`, which says the same
+  thing where the gate reads it.
+
+"no `coverage-summary.json`" means the client's coverage did not run (or ran
+without the `json-summary` reporter). Run `npm run coverage`.
+
 ### `smoke:web*`
 
 ⚠️ **An orphaned prod web server from a previous run fakes a rejection.** It
@@ -241,6 +275,14 @@ One stage has no GitHub CI counterpart, deliberately:
   Firefox. Trialled as a CI job and removed (#2086): across a dozen runs it never
   disagreed with Chromium, and `playwright install --with-deps` carries a real
   flake surface. Kept in front of a human about to push instead.
+  ⚠️ **On macOS 27 it runs inside the Linux Playwright container** (#2625):
+  Playwright's Firefox cannot launch there. It needs a running Docker daemon;
+  without one the stage prints a `SKIPPING … this is NOT a pass` warning and
+  exits 0 so `local:storybook` still runs — start Docker and re-run
+  `npm run smoke:web:firefox` before pushing. A container failure is a real
+  Firefox failure, not an infrastructure one, unless the log shows the image
+  pull or `npm install` failing. `INSPECTOR_FIREFOX_SMOKE=native|container`
+  overrides the routing (`scripts/lib/firefox-container.mjs`).
 
 A guard (`scripts/lib/workflow-gate.mjs`, run by `npm run test:scripts`) fails
 the suite if a workflow invokes a `local:*` script, a non-Chromium engine pass,

.claude/skills/release/SKILL.md

@@ -161,9 +161,13 @@ the `pack:verify OK` line) for the ledger below.
 
 **Every contribution closed in the milestone gets driven, not read.** The bar is
 observed behavior from the running app — a rendered panel, a status attribute, a
-server's own stderr — against a real test server, through whichever clients the
-change touches (web, CLI, TUI). "Its tests pass" is not evidence for this step;
-the gate already said that. For a change with no observable surface, the
+server's own stderr — against a real test server, through whichever surfaces the
+change touches: the web client, the one-shot CLI, the TUI, `mcpdo` (the
+connection CLI, shipped in the same package since 2.10.0) and the Docker image.
+**A change to `core/cli/` is driven through both CLIs** — the one-shot CLI and
+`mcpdo` share its method handlers, exit codes, OAuth flow and output styling
+(#2461), so passing through one says nothing about the other. "Its tests pass"
+is not evidence for this step; the gate already said that. For a change with no observable surface, the
 evidence is the thing that holds it — a probe that makes the guard fire, a
 counted before/after, a resolved binary path.
 
@@ -187,6 +191,14 @@ and link it from PR 2. Shape it like the
 - **One section per theme**, each a table of *Issue · What was driven ·
   Observed · Status*. One row per closed issue, issue-linked, with the actual
   output in the Observed cell.
+  - **An `mcpdo` row runs against a real connection** — `mcpdo connect …`, the
+    command under test, then `mcpdo disconnect …` — and its *What was driven*
+    cell shows all three. ⚠️ The connection daemon (`mcpdod`) outlives a
+    rebuild and keeps serving the code it started with, so a daemon left over
+    from before the production build smokes the wrong bundle and the row reads
+    as a pass. Run `pkill mcpdod` before the first `mcpdo` row (or rebuild with
+    `npm run build:dev` in `clients/mcpdo`, which stops it); see
+    `clients/mcpdo/README.md`.
 - **Notes / findings** — anything that is a caveat rather than a pass, called
   out rather than folded into a row.
 

.claude/skills/test-servers/SKILL.md

@@ -207,7 +207,7 @@ exist whichever one you are in:
 cd clients/web && npm run test-servers:build   # tsc -p test-servers → test-servers/build/
 ```
 
-Scripts reach this through `scripts/ensure-test-servers.mjs`, which builds
+Scripts reach this through `scripts/lib/ensure-test-servers.mjs`, which builds
 **unconditionally** (once per process per repo root).
 
 ⚠️ **Unconditional emit is not a clean.** A **deleted** source file leaves its

.github/workflows/main.yml

@@ -217,6 +217,10 @@ jobs:
         # This also covers the web integration project: web's `test:coverage`
         # runs `--project=unit --project=integration --coverage`, so there is no
         # separate integration step anywhere in this workflow.
+        #
+        # `coverage` ends with `verify:coverage-scope` (#2709), which fails if
+        # any client's report measured fewer files than its coverage `include`
+        # declares — the gate otherwise passes on whatever subset it was handed.
         run: npm run coverage
 
   # Publish the single `@modelcontextprotocol/inspector` package to npm on a

AGENTS.md

@@ -390,12 +390,13 @@ skills; the rules are here.
 - **Every v2 board item has a Priority.** Priority is a **board field**, not a label, so an unboarded issue has nowhere to store it. Derive it with the rubric in the `issue-triage` skill rather than asserting it. Board #11 has no Priority field; a v1 issue gets a Status and nothing else.
 - **`Incoming` ⇔ no milestone; everything past it ⇔ milestoned — on board #28.** Board #11 is exempt for the reason above: a v1 issue has no bucket to take, so its Status is set on its own and the audit's milestone checks do not apply to it. A `[GHSA-` **advisory draft** on #28 is exempt too, for a different reason: a draft card cannot carry a milestone, so its approval act is **accepting the advisory**, which moves it `Incoming` → `Todo`; its milestone arrives with the public issue after publication. The rest of the invariant is unchanged: assigning the milestone _is_ the approval act, so the two always go together. `Todo` asserts a maintainer signed off, so never park an unreviewed issue there — that erases the distinction and quietly promotes unreviewed work into the queue. An issue created through the documented flow skips `Incoming` entirely, because filing it _was_ the approval.
 - **`Done` means the work shipped.** Exactly two things earn a card a place in Done: its **PR merged**, or it is a **parent whose last sub-issue closed**. Anything else — duplicate, won't fix, not planned, obsolete, superseded — means nothing shipped, so the card is **deleted**. Done is read as the record of what a milestone actually delivered; a duplicate sitting there makes that record wrong in a way nobody can detect later. Deleting a card touches the board only — the issue keeps its labels and comments and stays searchable forever.
-- **When work begins**, assign the issue to yourself, create a feature branch and set Status to **In Progress**. **Branch names start with the target version segment** — `v2/fix/2071-oauth-resource-metadata`, `v1/fix/proxy-ssrf-pin` — matching the base branches themselves.
+- **When work begins**, assign the issue to yourself, set Status to **In Progress**, and create the feature branch **in a new git worktree** — never by switching branches in the primary checkout, which concurrent agent sessions share (#2661); remove the worktree once the PR merges. The recipe is the `pr-flow` skill, step 2. **Branch names start with the target version segment** — `v2/fix/2071-oauth-resource-metadata`, `v1/fix/proxy-ssrf-pin` — matching the base branches themselves.
 - **When work is complete**, run `npm run format` then `npm run local:gate`, **sign off every commit** (`git commit -s` — the repo-owned `DCO` check, `.github/workflows/dco.yml`, fails a PR on any unsigned commit with no partial credit; it gates merges into `v2/main` as a **required** status check, set by the `v2/main - DCO` repository ruleset (#2621) and pinned to GitHub Actions so only the workflow can satisfy it; a PR showing the check as missing or "expected" is an outage, not a pass), open a PR against the matching base branch with **`Closes #<ISSUE_NUMBER>` as the body's first line**, and set Status to **In Review**.
 - **After opening a PR, run a Copilot review loop to exhaustion — unprompted.** Request a review, wait for the round to post _or_ for Copilot's session to end without one, answer every comment, and request again whenever a fix was pushed. Stop on the **first** clean round (no confirming round "just to be sure"), a round holding only out-of-scope findings, or two rounds in a row where Copilot's session ends without posting. **Weigh each finding against the issue the PR closes and decline scope expansion** — pre-existing behavior, new capabilities, and hardening the issue did not ask for — because that is what turns a review cycle into overbuilding. The recipe is the `pr-flow` skill, step 7.
 - **Attach screenshots as proof of functionality** for any web-UI or TUI change. Put them in a **`pr-screenshots/`** folder off the repo root — it is **gitignored**, so the images are staged for upload and never committed — and name them for what they show.
 - ⚠️ Closing keywords only auto-link and auto-close for PRs targeting the **default branch** (`main`). A v2 PR targets `v2/main`, so `Closes #N` there is only a cross-reference and the card shows no linked PR. **Link it explicitly** with the `addCloseIssueReferences` GraphQL mutation right after opening the PR (recipe in `pr-flow`, step 6). **On merge, manually close the issue and move the card to Done.** Keep the line anyway, so the issues close if/when `v2/main` reaches `main`.
 - **If new tasks are discovered during development, create issues** and add them to the board.
+- **Pace bulk GitHub writes: 1 s between requests, never in parallel, under 80 a minute and 500 an hour.** The secondary limit refuses while `gh api rate_limit` still shows quota, and most `gh` writes are GraphQL. After a refusal, wait out `retry-after`, or a minute without one; a refused create can still land, so look before retrying.
 
 ### Responding to Code Reviews
 
@@ -421,7 +422,7 @@ diagnose a failing gate — is the `testing` skill. These are the rules.
   - **Root tooling**: a `scripts/*.mjs` helper with pure logic gets a sibling `*.test.mjs`. Keep that exact filename — `node --test` silently _skips_ a file its glob misses and still exits 0.
 - **Render Ink components through the TUI's own `render`** (`clients/tui/__tests__/helpers/renderTui.tsx`), never `ink-testing-library`'s directly. It is the same function with every frame ANSI-stripped, which is what keeps an assertion on styled text from depending on the ambient environment: Ink writes styling _inside_ the styled run, so `<Text underline>I</Text>nfo` reaches the frame buffer with escapes between `I` and `nfo` and `toContain("Info")` fails. It only bites where chalk emits color — a developer whose shell exports `FORCE_COLOR` — so CI is green on a suite that is broken for them (#2207). A test that genuinely needs the raw bytes reads `stdout.lastFrame()` off the returned instance.
 - **Render React components through `renderWithMantine`** (`src/test/renderWithMantine.tsx`); do not hand-roll a bare `MantineProvider`, which skips the project theme and the helper's options and drifts from every other test. Pass the `colorScheme` option to exercise a forced scheme rather than hand-rolling `defaultColorScheme`. Use `renderWithMantineTransitions` **only** when a test must assert mid-flight transition state, and read the long comment on the helper before changing anything about it.
-- **The web coverage `include` is a whitelist.** It names `components`/`hooks`/`theme`/`lib`/`utils`/`server` plus the browser-consumed `core/*` runtime, so a module placed **outside** those directories falls out of the gate entirely, silently. Place new modules inside a gated directory. The documented exceptions — `src/App.tsx` and the `src/main.tsx` / `src/index.ts` bootstraps — are called out in a comment on the `include` array itself.
+- **The web coverage `include` is a whitelist.** It names `components`/`hooks`/`theme`/`lib`/`utils`/`server` plus the browser-consumed `core/*` runtime, so a module placed **outside** those directories falls out of the gate entirely, silently. Place new modules inside a gated directory. The converse — the run measuring **fewer** files than the `include` declares, as web's did under vitest 5 (418 → 11, still green) — is not silent: `npm run verify:coverage-scope`, the last step of `coverage`, fails naming each missing file (#2709). Fix that by fixing the globs, never by excusing the files. The documented exceptions — `src/App.tsx` and the `src/main.tsx` / `src/index.ts` bootstraps — are called out in a comment on the `include` array itself.
 
 ### Test-gate timeouts are chosen values, stated once