[Bug] Registrations launched via npx rea-agents@X fail when the client starts inside a REA checkout; 6.8.0 doctor reports them "aligned" #9685

Before submitting

• I searched the open and closed issues for a related report.
• I removed credentials, tokens, private paths, and sensitive target data.

Area

Setup, packaging, or upgrade

Observed behavior

• Claude Code's user-scope registration was cmd.exe /d /c npx -y rea-agents@6.8.0 mcp. Started with cwd = a REA source checkout, the server failed with CONNECTION_CLOSED.
• Inside that checkout, npx -y rea-agents@6.8.0 --version printed 'rea' is not recognized as an internal or external command.
• npx -y rea-agents@6.8.0 doctor --client claude_code --json fails the same way inside the checkout. When run from %APPDATA%\npm\rea.cmd instead, doctor reported this registration as "state":"aligned" with "remediation":null.

Reproduction

Each step was run once on this machine.

1. In a REA source checkout (root package.json name is rea-agents, nothing built into node_modules\.bin), make sure no rea is on PATH.
2. npx -y rea-agents@6.8.0 --version fails with "'rea' is not recognized".
3. npx -y -p rea-agents@6.8.0 -c "echo %PATH%": the child PATH has <checkout>\node_modules\.bin and its parent chain. It has no _npx\<hash>\node_modules\.bin entry.
4. cd %TEMP% and repeat step 2: it prints 6.8.0.

Expected behavior

• doctor should not report a package-runner registration as aligned when it can't establish that the client can launch it.
• Setup and the recovery guidance should avoid launchers whose resolution depends on the client's working directory.

Impact and scope

• REA contributors whose agent runs inside the checkout. The registration silently fails, and doctor's "aligned" points the recovery away from the cause.
• Untested: other clients, macOS/Linux shells, and bunx.

REA version

6.8.0 (npm, published 2026-10-25). Source compared at main c5301e614.

Runtime and platform

Node 26.13.0, npm 11.20.0, Windows 11 x64, Claude Code.

Target and artifact context

Not applicable (MCP registration and launcher resolution)

Interface

Package or setup

Earliest failure stage

Setup or provider admission

Relevant output or evidence

• Observed: the commands and output above, and doctor's identity.registrations[] entry for claude_code showing state: "aligned".
• Source (6.8.0 dist, application/ClientRegistrationStatus.js, registrationAligned): an exact npx/bunx registration command returns "aligned" without further checks.
• Source (main): c77735fa8 (2026-10-28, "bind managed registrations to selected installation") classifies package-runner registrations as "stale", and setup migrates them to the selected installation. The skill now says to run npx "from a trusted directory outside the target project".
• Likely fixed on main for registration status, but unreleased. NOT_ENOUGH_INFO on whether main behaves correctly at runtime: main wasn't built or run here.

Analysis or suspected cause

Source-derived and observed: npm exec resolves the request against the local project named rea-agents rather than the published package, so it looks for a bin that doesn't exist.

Proposed (unverified):

• In the connection/recovery guide and AGENTS.md, say explicitly not to run npx rea-agents from inside a REA checkout.
• Confirm that the next release's doctor marks old npx registrations stale.