fix(setup): materialize the pinned package-runner cache before the first client start - #7032

Fixes #7027

Problem

Package runners key their package cache by the requested spec, so the _npx entry installed for the rea-agents@latest invocation that ran setup cannot serve the pinned rea-agents@<version> registration that setup writes. The first client start after setup installs that entry inside the client's MCP startup deadline; one client log recorded three consecutive connection timed out after 30000ms failures, and a controlled cold install with every tarball already in _cacache took 22 s on the same machine (issue has the full measurements).

Change

• src/application/SetupRegistrationPrewarm.ts: derives a cache-materializing variant of the registration command (same spec, terminating --version subcommand) and materializes it once through execFileOutput with a bounded timeout. Direct launcher registrations return skipped. The spawn runs in a neutral working directory: inside a REA source checkout the package runner resolves the local project instead of the published entry and the warm-up fails.
• SetupHost.systemSetupHost exposes this as the optional host capability prewarmRegistrationRunner; runSetupWorkflow invokes it after client configuration and skill installation succeed, before the final doctor summary. The step is best-effort and non-fatal: SetupResult carries an optional prewarm summary, interactive output prints a warning line on failure, and hosts without the capability are unaffected.
• docs/installation.md: documents why setup performs this step and what happens when it cannot run.

Tests

• src/application/SetupRegistrationPrewarm.test.ts (services): command derivation for npx/bunx/Windows-wrapped and direct launchers; warmed, skipped, bounded-failure, and timeout outcomes through an injected spawn.
• tests/boundary/filesystem/setupRegistrationPrewarm.test.ts (boundary): the workflow invokes the capability exactly once after configuring clients; a failed prewarm keeps setup ready and emits a warning progress event; a host without the capability omits the summary. These hosts pin nodeVersion so readiness does not depend on the developer machine's runtime.

Verification

Run locally on Windows 11, Node 24.14.0 (below the repository pin 24.22.1, engine checks relaxed):

• tsc --noEmit clean; oxlint 0 errors with no new warnings on modified files (the two warnings in the new module mirror the existing control-character sanitization pattern in SetupHost.ts); oxfmt --check clean; verify:module-boundaries, verify-test-discovery (2424 test files), and verify:architecture-guards pass; knip output identical to the pristine tree.
• Focused tests: 11/11 across both new files. Full services project run shows only the 4 failures in environmentBuild.test.ts and decompileAll.test.ts that reproduce identically on the pristine tree on this machine (not caused by this change).
• End-to-end against the built output: warm prewarm returns {"status":"warmed"} in ~1.6 s from a REA source checkout (neutral-cwd fix above); after deleting the pinned _npx entry, prewarm absorbs the 19 s cold install and returns {"status":"warmed"}, leaving nothing to install inside a client startup deadline.

Not run locally: the full check pipeline on the repository-pinned Node and the built-lane suites; CI coverage for those is expected. Bun bunx warm-up shares the command derivation but was not executed (no Bun on this machine).

Ownership

The PR author is the human owner of this change per the contribution policy.

Author readiness

Human owner: @wxj006007

• I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
• I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
• I declare this PR ready for initial maintainer review.