chore: merge v2/main for the v2.2.0 milestone release

.github/copilot-instructions.md

@@ -72,6 +72,14 @@ Both exist and do different jobs. Theme files (`src/theme/<Component>.ts`) custo
 - `src/types/` is only for ambient `.d.ts` module stubs — not a home for new domain types.
 - ⚠️ The coverage `include` is a **whitelist** naming `components` / `hooks` / `theme` / `lib` / `utils` / `server` (plus the `core/*` runtime). A module placed outside those directories silently falls out of the ≥90% gate. Flag new top-level files or new grab-bag directories.
 
+## Dependency placement
+
+- **The MCP SDK packages (`@modelcontextprotocol/client`, `core`, `server`, `server-legacy`, `ext-apps`) belong in the root `package.json` only.** Adding one to a `clients/*/package.json` is a review finding: Node resolution walks up, so the root install already serves every client, and a per-client entry installs a second copy that drifts (it produced two versions of `ext-apps`, and of the transitive v1 SDK, at once — #1970) and reintroduces the duplicate-copy failure `vitest.shared.mts` has a `dedupe` workaround for.
+- **The v1 `@modelcontextprotocol/sdk` is not a dependency of this repo** and must not become one. It is a peer of `ext-apps`, present in lock files only.
+- Dependencies reached only through **root-owned code with no manifest** (`test-servers/src`, `core/`) are declared at the root and aliased to the **repo root** in `vitest.shared.mts` — as `express` and `yaml` are — not to `<client>/node_modules` like the other pins there.
+- **A dependency that renders React components must be bundled into the client that uses it, and is then not a root dependency.** An externalized package resolves its own `react` from wherever npm placed it in the *consumer's* tree, beside a React satisfying *its* peer range — looser than ours, which is all it takes to split React. `ink-form`/`ink-scroll-view` declare `">=18"`, so a consumer's React 18 satisfies them, the TUI ends up with two React instances, and it crashes on the first hook (#1952). Both are inlined via `noExternal` in `clients/tui/tsup.config.ts`. **`ink` is the one exemption, justified by cost (~1.4MB) — never by a peer range**: flag any claim that `">=19"` keeps npm from misplacing it, which is false and was in this repo once. What keeps it safe is the **root `react` range staying open to the whole major (`^19.0.0`)** so npm can dedupe with a consumer's pinned React 19; treat narrowing that range as reopening the bug. `clients/tui/__tests__/tsupConfig.test.ts` enforces the split, the root-declaration of exempt packages, and that range.
+- **Which section is a separate question from which manifest.** A package `core/` imports at runtime must be in root **`dependencies`**: client builds externalize npm packages, so a published install resolves them from the root manifest and devDependencies are absent there. Only test/build-only packages (`express`) belong in `devDependencies`. Flag a runtime `core/` import added to `devDependencies` — it passes every local check and breaks the published package.
+
 ## Tests and the coverage gate
 
 - **All new or modified code needs tests.** The per-file gate is **≥ 90% on all four dimensions** — lines, statements, functions, **and branches** — enforced in CI for `clients/{web,cli,tui,launcher}` and the gated `core/` runtime.
@@ -85,15 +93,18 @@ Both exist and do different jobs. Theme files (`src/theme/<Component>.ts`) custo
 
 ### Rendering components in tests
 
-- **Always render through `renderWithMantine`** from `src/test/renderWithMantine.tsx`. Never hand-roll a bare `MantineProvider` — that reintroduces a real failure class where a `Transition`/`Modal` timer fires after happy-dom tears down `window` and fails the entire run.
+- **Always render through `renderWithMantine`** from `src/test/renderWithMantine.tsx`. A hand-rolled bare `MantineProvider` skips the project theme and the helper's options, and drifts from every other test. (It does *not* reintroduce the timer-leak class — an older version of this rule said so; the leaked-timer net in `setup.ts` is global and covers every unit test regardless of how it renders.)
 - For a forced color scheme, pass the option — `renderWithMantine(ui, { colorScheme: "dark" })` — rather than a hand-rolled `defaultColorScheme` provider.
 - Only when asserting _mid-flight_ transition state, use `renderWithMantineTransitions`, passing `settleMs` derived from the component's real animation duration. Do **not** combine it with `vi.useFakeTimers()`, and use the `unmount()` it returns if the test unmounts the tree itself.
 
 ## Gates and PR hygiene
 
 - `npm run format` before committing; **`npm run ci` before pushing** (`validate` → `coverage` → `verify:build-gate` → `smoke` → Storybook). `npm run validate` is the fast inner-loop check and is **not** a substitute — it runs `test`, not `test:coverage`, so it does zero coverage gating.
+- **A dependency bump must land in every install that declares it.** v2 is not a workspace — the root and each `clients/*` have their own `node_modules`, and a client's test project compiles `core/` and `test-servers/src` (which resolve from the **root**) alongside the client's own sources. Bumping a shared dependency in one manifest only puts two versions of it in one `tsc` program; for a recursive-generic surface like zod that exhausts the tsc heap (#1896). `verify:dep-lockstep` fails the build on this, so a PR bumping a package that the shared sources import should update the root **and every client that already lists it** — not every client unconditionally, since a package absent from an install can't skew and adding it there would be a spurious dependency.
+- **A test or smoke must not touch real user state.** The web smokes run against a throwaway catalog via the shared `scripts/lib/prod-web-server.mjs` helper, never the developer's `~/.mcp-inspector/mcp.json` (#1977); the cli/tui smokes drive a temp `--catalog`. A new smoke spawning its own server, or teardown that removes a work dir without first awaiting `stopChild` (the #1801 race — `child-cleanup.mjs` exports both halves and both are required), should be flagged.
 - **Every PR references an issue**, first body line `Closes #<ISSUE_NUMBER>`.
 - **Every PR carries exactly one version label**, `v1` or `v2`, matching its base branch.
+- **Commits carry a `Signed-off-by:` trailer.** The DCO check is a hard merge gate and fails on a single unsigned commit; it matches the trailer against the author *or* committer, and skips only merge and bot commits. Use `git commit -s` — note `format.signOff` does *not* sign `git commit` (only `format-patch`). Repairing pushed commits means `git rebase HEAD~<n> --signoff` + `git push --force-with-lease`; remediation commits are not enabled on this repo.
 - Update the relevant `README.md` / `AGENTS.md` when a change adds, removes, renames, or repurposes a file or folder, changes the structure or tech stack, or introduces a command, dependency, or architectural pattern.
 
 ## What to prioritize in review

.github/workflows/claude.yml

@@ -35,13 +35,18 @@ jobs:
       id-token: write
       actions: read
     steps:
+      # Actions are pinned to full commit SHAs rather than mutable major tags:
+      # this job holds ANTHROPIC_API_KEY and grants the agent Bash, so a
+      # force-moved tag would be an unreviewed code change inside a
+      # secret-holding job. The trailing `# vX.Y.Z` comment is the form
+      # Dependabot reads, so pinning costs us no upgrade automation. (#1882)
       - name: Get PR details
         if: |
           (github.event_name == 'issue_comment' && github.event.issue.pull_request) ||
           github.event_name == 'pull_request_review_comment' ||
           github.event_name == 'pull_request_review'
         id: pr
-        uses: actions/github-script@v8
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           script: |
             let prNumber;
@@ -57,26 +62,58 @@ jobs:
               pull_number: prNumber
             });
 
+            // A fork PR's head lives in a different repository — or in none at
+            // all, if the fork was deleted after the PR was opened (`head.repo`
+            // is then null). Neither is ours to check out, so both count as a
+            // fork here and the steps below decline rather than guess.
+            const headRepo = pr.data.head.repo?.full_name ?? null;
+            const isFork = headRepo !== `${context.repo.owner}/${context.repo.repo}`;
+
             core.setOutput('sha', pr.data.head.sha);
-            core.setOutput('repo', pr.data.head.repo.full_name);
+            core.setOutput('is_fork', String(isFork));
+
+      # A fork PR's head is untrusted code, and checking it out would put it in
+      # reach of a tool-enabled agent run holding ANTHROPIC_API_KEY. Reviewing
+      # the base tree instead would only trade that for a confident review of
+      # the wrong tree, so decline visibly and leave the reason in the run.
+      - name: Decline fork PR
+        if: steps.pr.outcome == 'success' && steps.pr.outputs.is_fork == 'true'
+        run: |
+          {
+            echo "### Claude Code declined this pull request"
+            echo
+            echo "The head branch lives in a fork, so its code is not checked out and Claude is not run."
+            echo "Push the branch to this repository and re-trigger if a review is needed."
+          } >> "$GITHUB_STEP_SUMMARY"
 
+      # No `repository:` — a same-repo head is all that reaches this step, and
+      # checkout defaults to `github.repository`, which no PR can influence.
       - name: Checkout PR branch
-        if: steps.pr.outcome == 'success'
-        uses: actions/checkout@v6
+        if: steps.pr.outcome == 'success' && steps.pr.outputs.is_fork == 'false'
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ steps.pr.outputs.sha }}
-          repository: ${{ steps.pr.outputs.repo }}
           fetch-depth: 0
 
+      # `skipped` means the trigger was an issue or a non-PR comment, so there
+      # is no head to check out and the base tree is the right one. The lookup
+      # having *failed* is deliberately not included: this condition carries no
+      # status-check function, so GitHub applies an implicit `success()` and
+      # skips the step after a failed prior step anyway. Spelling out `skipped`
+      # keeps that from having to be re-derived by the next reader.
       - name: Checkout repository
-        if: steps.pr.outcome != 'success'
-        uses: actions/checkout@v6
+        if: steps.pr.outcome == 'skipped'
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
 
       - name: Run Claude Code
+        # Runs only against a tree this workflow actually checked out: the base
+        # repo (non-PR trigger) or a same-repo PR head. A fork PR reaches here
+        # with `is_fork == 'true'` and both disjuncts false, so it is skipped.
+        if: steps.pr.outcome == 'skipped' || steps.pr.outputs.is_fork == 'false'
         id: claude
-        uses: anthropics/claude-code-action@v1
+        uses: anthropics/claude-code-action@5ef2e550a465a721f4f45e4a7d3c340c873e1dcc # v1.0.190
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
 

.github/workflows/main.yml

@@ -93,9 +93,11 @@ jobs:
         # CLI/web). Not part of any client's `validate`: it needs the
         # cli/tui/launcher bundles, which `validate` above already built
         # (smoke:web builds clients/web/dist on demand — #1486). smoke:web:browser
-        # boots the prod web bundle in headless chromium (#1615). smoke:tui
-        # self-skips here — the Ink TUI needs a real TTY (raw mode) that headless
-        # CI lacks, so its boot/render check is local-only.
+        # boots the prod web bundle in headless chromium (#1615); smoke:web:app
+        # goes further and drives connect → open app → widget ready against a
+        # composable MCP App server (#1859). Both reuse the chromium installed
+        # above. smoke:tui self-skips here — the Ink TUI needs a real TTY (raw
+        # mode) that headless CI lacks, so its boot/render check is local-only.
         run: npm run smoke
 
       - name: Run Storybook play-function tests