test(release): cover live onboarding, viewer recovery, and integration drift regressions

[oaslananka]

Summary

Add non-destructive release-confidence coverage for the user-facing failures and drift classes found during the 2026-08-30 live extension audit.

Context

The repository already has strong unit, security, accessibility, webview, visual, integration, real-pair, canary, mutation, and package checks. The live audit still found defects that are difficult to catch with isolated tests: installer/runtime mismatch, first-load viewer recovery, profile catalog drift, and multi-surface onboarding state.

This issue should extend the existing strategy rather than introduce a parallel test framework.

Scope

Add focused coverage for:

• kicad-mcp-pro installer selection across Python/runtime combinations;
• post-install re-detection and stale-failure recovery;
• initial KiCanvas/WebGL failure with automatic CLI SVG fallback;
• Task Hub canonical actions and duplicate setup-state prevention;
• BoardReadyOps disabled/configured/incompatible contract states;
• MCP profile discovery/migration against a published server artifact;
• BOM/Netlist and integration empty-state behavior.

Acceptance criteria

• Every live-audit regression above has a deterministic automated test at the lowest appropriate layer.
• At least one extension-host or equivalent end-to-end lane proves the complete install/detect or simulated-install state transition without modifying production user data.
• Viewer fallback is tested on Linux with WebGL unavailable or deterministically mocked unavailable.
• Real-pair tests consume published/packaged server artifacts for compatibility claims.
• Tests do not depend on external paid services, personal credentials, or mutable local state.
• No existing test is skipped, weakened, or removed to make the new lane pass.
• CI runtime and bundle/performance budgets remain within the repository's existing policy.

Validation

• Existing check:kicad-studio, security, accessibility, webview/visual, integration, and real-pair suites.
• New focused regression tests run in the appropriate required or canary lane.
• Repeatable VSIX/package validation remains green.

[oaslananka]

2026-08-30 release-confidence coverage revalidation

Several audit regressions are now covered by merged work; this issue remains open only for the gaps below.

Completed evidence:

• Installer/runtime selection: bug(setup): make kicad-mcp-pro installation Python-version aware and self-healing #620 added Python 3.13-aware uv/pipx/pip candidate tests, including rejecting incompatible pipx runtimes and refreshing MCP state after a successful install task.
• Compatibility drift: chore(compat): separate CLI, MCP, protocol, and BoardReadyOps support claims #621 added independently validated Studio CLI, MCP server, protocol, and BoardReadyOps support axes plus published-artifact drift checks.
• Viewer recovery: fix(kicad-studio): recover viewer renderer failures automatically #640 added deterministic no-WebGL Extension Host coverage requiring CLI SVG fallback, plus final-failure webview/visual regressions on Linux/Windows.
• BoardReadyOps health states: mcpToolsProvider covers disabled, enabled/unavailable, compatible and incompatible-version states against the compatibility contract.
• Empty data surfaces: BOM loading/empty behavior has webview coverage; Netlist has provider-level empty-netlist/error-state coverage.

Remaining release-confidence gaps:

1. Add one Extension Host or equivalent integration flow that proves install completion -> real MCP re-detection/state update without touching production user data. Existing bug(setup): make kicad-mcp-pro installation Python-version aware and self-healing #620 command tests verify the refresh call but not the full state transition in one lane.
2. Add published-artifact profile discovery/migration coverage so stored legacy Studio profile values cannot silently drift or gain privilege as server profile vocabularies evolve (ux(mcp): align profile selection with Review, Build, Release, and Expert workflows #622 dependency).
3. Add a focused Task Hub/onboarding regression proving MCP setup actions have one authoritative state and do not create duplicate setup prompts (ux(vscode): make Task Hub the primary workflow router and simplify sidebar information architecture #624 dependency).
4. Promote Netlist empty-state coverage from provider payload only to the rendered user-facing surface if ux(vscode): make Task Hub the primary workflow router and simplify sidebar information architecture #624 changes that UI.

No existing gate should be weakened or duplicated; these should extend the current integration/real-pair suites.

[oaslananka]

Progress reconciliation after #644 merged:

Covered on main:

• installer selection/runtime combinations: mcpDetector.test.ts covers uv → pipx → pip ordering, compatible-Python pinning, incompatible-Python rejection, and python -m pip fallback (bug(setup): make kicad-mcp-pro installation Python-version aware and self-healing #620);
• post-install re-detection/state recovery: test(kicad-studio): cover MCP install re-detection transition #644 adds the successful install → real McpClient/McpActivationController refresh → shared McpStateStore transition;
• initial viewer recovery: Linux Extension Host E2E plus webview tests cover WebGL/KiCanvas failure → CLI SVG fallback (fix(kicad-studio): recover viewer renderer failures automatically #640);
• BoardReadyOps provider states: absent, disabled, healthy/configured, old-version/incompatible-contract, and unhealthy/degraded paths are covered;
• BOM/Netlist empty-data behavior has existing focused provider/parser tests;
• published-artifact compatibility remains exercised by the real-pair/cross-repo lanes.

Still not claiming #628 complete: Task Hub duplicate setup-state prevention and MCP profile discovery/migration against the published server artifact still need explicit deterministic regression coverage. The issue stays open until those gaps and the full acceptance checklist are proven.