test(mcp): registry-iterating done-bar drift guard + agent-facing error contract tests

[mastermanas805]

What

Raises MCP test coverage toward the flow matrix (docs/sessions/2026-06-04/USER-FLOW-INVENTORY-AND-TEST-MATRIX.md §4.2) and the done-bar. Agents are the PRIMARY consumers of instanode, so MCP tool flows + the agent-facing error surface are P0. No src/ changes — test + test-harness + CI-wiring only.

Tools inventoried (19 registered)

All 19 server.tool(...) already had success-path + network-error handler tests (tools-unit.test.ts) and endpoint/payload tests (client-unit.test.ts). The real gaps this PR closes:

1. No registry-iterating done-bar / drift guard existed.
2. The 402 over-limit → agent_action path was never exercised end-to-end through a real tool call (only via the pure formatError unit + an unreachable x-mock-tier mock header).

Added

test/tool-coverage.test.ts — done-bar drift guard (matrix §4.2, rule 18)

Iterates the live server._registeredTools registry (not a hand-typed slice) and FAILS CI if any registered tool lacks:

• a J-row mapping in MAPPED_TOOLS,
• a callable handler + inputSchema + description, or
• any test exercising it in test/*.test.ts.

Also reds on stale mappings (renamed/removed tool — both drift directions). Verified failing-then-passing: dropping a MAPPED_TOOLS row reds "no flow-matrix J-row mapping: redeploy".

test/tool-contract.test.ts — agent-facing error + endpoint contract

Drives real tool handlers against the mock api and asserts the envelope the LLM reads aloud:

• 402 tier-gate (create_deploy({private:true}) on hobby) → Action: + Upgrade: block surfaced verbatim (rule 12 / FIX-E #C7), with a Pro negative control.
• 401 on auth-required tools → dashboard CTA.
• 404 (cross-team / absent, J11+J17) → clean not_found.
• Endpoint contract for gap tools J5/J6/J7/J14/J15/J16 (correct endpoint hit + documented response shape).

test/mock-api.ts

Adds HOBBY_TOKEN so the tier-gate 402 is reachable through a real create_deploy call (previously only via an x-mock-tier header the InstantClient never sends). Tier now derives from the bearer; the header override still wins (backward-compat — existing tests stay green).

CI wiring

Both new files added to npm test / test:nocov and the coverage.yml lcov step.

Scope note

Real-backend mutating MCP flows still depend on the W0 skip-cohort guard (matrix §3.W0) and remain STAGING-only — documented in the test header. These tests run hermetically against the in-process mock.

Gate

npm run build && npm test green — 390 tests (was 373). No src/ lines changed, so the diff-cover 100%-patch gate is trivially satisfied.

🤖 Generated with Claude Code