morluto/rea

Fork 0

mirror of https://github.com/morluto/rea.git synced 2026-11-05 06:45:22 +00:00

[GH-ISSUE #653] [Docs] Installation guide's manual MCP config uses `rea-agents@latest`, which `rea doctor` reports as stale #309

New issue

Closed

opened 2026-10-15 18:23:43 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-15 18:23:43 +00:00

Owner

Originally created by @coygeek on GitHub (Oct 6, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/653

Before submitting

I searched the existing issues for a related documentation report.
I removed credentials, tokens, private paths, and sensitive target data.

Documentation location

docs/installation.md#mcp-registry, the manual configuration example (lines 324-339 on main), which tests/conformance/readmeConsistency.test.ts asserts.

Problem

The manual MCP configuration that docs/installation.md recommends ("args": ["-y", "rea-agents@latest", "mcp"]) is classified by rea doctor as a stale registration with config_drift, healthy: false, exit status 1, and the remediation "Run rea setup to refresh this registration, then restart the client." This happens even when @latest resolves to the same version that runs doctor, so a user who follows the guide's configuration exactly is told their setup is unhealthy. The rest of the project documents an exact-version pin for persistent registrations, and rea setup and rea doctor follow that rule, so the guide's manual example is the outlier. Maintainers may prefer to change the example or to have doctor accept @latest.

Expected content

A user who copies the manual configuration from the "MCP Registry" section of docs/installation.md should get a registration that rea doctor accepts. The project's registration rule is an exact pin: the README says under its own manual example that "Persistent registrations should use one exact package version. rea setup maintains that pin", and docs/installation.md says "Setup continues to pin persistent MCP registrations to the exact version that performed setup. Running current setup later migrates unversioned or older managed registrations". Doctor enforces that rule. The "MCP Registry" section instead presents the @latest form as the manual configuration and treats an exact rea-agents@VERSION as optional, "when a reproducible client configuration is required". So either that example should follow the exact-pin rule, or doctor should accept the documented @latest form while it resolves to the running version; as shipped, the guide and doctor contradict each other.

Supporting evidence

Runtime or environment

Package: rea-agents 4.0.1 from npm, which is the latest dist-tag (release tag rea-agents-4.0.1, commit feeb19b8b3172b2827b80fde8f09570ce5aeed88).
Source: main at 19f8cddfd6f283188567b8ff1e49b810d79952ee, built locally with npm ci --ignore-scripts && npm run build; package.json there still reports version 4.0.1.
Node.js v24.21.0 on macOS 27.0.1 arm64.
Between the release tag and main, the cited files changed only by a catch comment in src/application/ClientRegistrationStatus.ts and an unrelated added paragraph in docs/installation.md; src/application/ClientRegistrationIdentity.ts and src/identity.ts are unchanged.

Steps to reproduce

Create a throwaway home directory so no real client configuration is read or changed, write the guide's manual configuration as a Claude Code registration, and run doctor with CLAUDE_CONFIG_DIR and XDG_CONFIG_HOME cleared so it reads the throwaway file:

TMPHOME="$(mktemp -d)"
printf '%s\n' '{"mcpServers":{"rea":{"command":"npx","args":["-y","rea-agents@latest","mcp"]}}}' > "$TMPHOME/.claude.json"
env -u CLAUDE_CONFIG_DIR -u XDG_CONFIG_HOME HOME="$TMPHOME" npx -y rea-agents@4.0.1 doctor --client claude_code --json > doctor.json
echo "exit=$?"

Inspect the registration result: jq -c '{healthy, registrations: .identity.registrations, scope_checks}' doctor.json.
Control: repeat step 1 with rea-agents@4.0.1 in place of rea-agents@latest in the .claude.json args.
Repeat steps 1 and 3 with the runner npx -y rea-agents@latest doctor ... (the form the bundled skill uses) and with node scripts/rea.mjs doctor ... from a main build.

Actual behavior

Observed locally with the documented @latest registration (relevant fields only):

exit=1
"healthy": false
identity.registrations: [{"client":"claude_code","command":["npx","-y","rea-agents@latest","mcp"],"state":"stale","remediation":"Run rea setup to refresh this registration, then restart the client."}]
scope_checks: [{"name":"node","classification":"healthy"},{"name":"registration:claude_code","classification":"config_drift"}]

The control with rea-agents@4.0.1 in the registration returned exit=0, "healthy": true, "state": "aligned", and registration:claude_code classified healthy. A registration naming the older rea-agents@4.0.0 returned stale, config_drift, and exit 1, the same result as @latest. With the runner npx -y rea-agents@latest doctor, identity.cli_package_version was 4.0.1, and the @latest registration was still stale with exit 1. The main build gave the same results: @latest was stale with exit 1, and @4.0.1 was aligned with exit 0.

Evidence

Expected source: docs/installation.md "MCP Registry" section, lines 324-339 on main (manual configuration with rea-agents@latest, exact version presented as optional for reproducibility), github.com/morluto/rea@19f8cddfd6/docs/installation.md (L324-L339), asserted by tests/conformance/readmeConsistency.test.ts lines 89-103; against the exact-pin rule in README.md lines 433-434 and docs/installation.md lines 35-37 on main.
Failure source: local rea doctor --client claude_code --json runs above; the registrationAligned check in src/application/ClientRegistrationStatus.ts lines 155-162 on main accepts an npx -y <package> mcp registration only when the package equals PRODUCT_IDENTITY.registrationPackageSpecifier (rea-agents@<running version>, src/identity.ts line 10), github.com/morluto/rea@19f8cddfd6/src/application/ClientRegistrationStatus.ts (L155-L162), while src/application/ClientRegistrationIdentity.ts lines 38-44 recognize rea-agents@latest as a REA-owned registration.
Evidence provenance: observed
Local verification: reproduced
Reproduction completeness: complete

Restoration check

With the documented manual configuration from docs/installation.md in a throwaway $HOME/.claude.json, rea doctor --client claude_code --json should no longer report state: "stale", config_drift, and exit 1 while the guide still presents that configuration as the one to use. Either doctor accepts the documented form when it resolves to the running version, or the guide and its conformance assertion stop recommending a form that doctor reports as stale. Controls: a registration naming the exact running version (rea-agents@4.0.1 on the tested builds) should stay aligned with exit 0, a registration naming an exact older version such as rea-agents@4.0.0 should still be reported stale, and the unversioned rea-agents registration covered by the existing "reports an unversioned npx registration as stale" test in tests/boundary/filesystem/clientRegistrationStatus.test.ts should keep its current result.

Additional context

The README "Manual MCP configuration" section already uses an exact pinned version (rea-agents@4.0.1), and rea setup writes the exact running version, so among the user-facing docs only the installation guide's manual example and its conformance assertion use @latest as a registration; @latest elsewhere in the docs appears in one-off commands such as npx -y rea-agents@latest doctor. The contributor script npm run config:print (scripts/print-mcp-config.mjs) also prints an rea-agents@latest registration.
The bundled skill (skills/reverse-engineer-anything/SKILL.md, "Readiness and setup") tells agents to run doctor when a registration is reported stale and to propose setup when doctor finds an alignment problem. An agent following the skill on a client configured from the guide would therefore propose rewriting a registration that already launches the current release.
History, for context only: commit 3e3d45856ede849371027b62ad1a7b0687798951 changed the aligned check from the @latest specifier to the exact version, and the "MCP Registry" section with the @latest example and its conformance assertion arrived later, in #464. This does not show which behavior is intended.

Triage assessment

Impact level: P2
Assessment status: supported
Impact basis: Observed locally on the 4.0.1 release and main: following the documented manual configuration makes rea doctor report healthy: false, config_drift, and exit 1, which misleads users and any script or agent that checks doctor's result; the README and the rest of the installation guide already state the exact-pin rule, which limits but does not remove the confusion, and the bundled skill directs agents toward rea setup; the MCP server itself still launches the current release, so analysis is not blocked.
Workaround status: available
Workaround basis: Writing an exact rea-agents@VERSION in the registration, as the README manual example and rea setup already do, produced aligned and exit 0 in the control run; the tradeoff is that the pin must be refreshed after each upgrade, and doctor then reports it stale as intended.

Originally created by @coygeek on GitHub (Oct 6, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/653 ### Before submitting - [x] I searched the existing issues for a related documentation report. - [x] I removed credentials, tokens, private paths, and sensitive target data. ### Documentation location `docs/installation.md#mcp-registry`, the manual configuration example (lines 324-339 on `main`), which `tests/conformance/readmeConsistency.test.ts` asserts. ### Problem The manual MCP configuration that `docs/installation.md` recommends (`"args": ["-y", "rea-agents@latest", "mcp"]`) is classified by `rea doctor` as a `stale` registration with `config_drift`, `healthy: false`, exit status 1, and the remediation "Run rea setup to refresh this registration, then restart the client." This happens even when `@latest` resolves to the same version that runs `doctor`, so a user who follows the guide's configuration exactly is told their setup is unhealthy. The rest of the project documents an exact-version pin for persistent registrations, and `rea setup` and `rea doctor` follow that rule, so the guide's manual example is the outlier. Maintainers may prefer to change the example or to have doctor accept `@latest`. ### Expected content A user who copies the manual configuration from the "MCP Registry" section of `docs/installation.md` should get a registration that `rea doctor` accepts. The project's registration rule is an exact pin: the README says under its own manual example that "Persistent registrations should use one exact package version. `rea setup` maintains that pin", and `docs/installation.md` says "Setup continues to pin persistent MCP registrations to the exact version that performed setup. Running current setup later migrates unversioned or older managed registrations". Doctor enforces that rule. The "MCP Registry" section instead presents the `@latest` form as the manual configuration and treats an exact `rea-agents@VERSION` as optional, "when a reproducible client configuration is required". So either that example should follow the exact-pin rule, or doctor should accept the documented `@latest` form while it resolves to the running version; as shipped, the guide and doctor contradict each other. ### Supporting evidence #### Runtime or environment - Package: `rea-agents` 4.0.1 from npm, which is the `latest` dist-tag (release tag `rea-agents-4.0.1`, commit `feeb19b8b3172b2827b80fde8f09570ce5aeed88`). - Source: `main` at `19f8cddfd6f283188567b8ff1e49b810d79952ee`, built locally with `npm ci --ignore-scripts && npm run build`; `package.json` there still reports version 4.0.1. - Node.js v24.21.0 on macOS 27.0.1 arm64. - Between the release tag and `main`, the cited files changed only by a catch comment in `src/application/ClientRegistrationStatus.ts` and an unrelated added paragraph in `docs/installation.md`; `src/application/ClientRegistrationIdentity.ts` and `src/identity.ts` are unchanged. #### Steps to reproduce 1. Create a throwaway home directory so no real client configuration is read or changed, write the guide's manual configuration as a Claude Code registration, and run doctor with `CLAUDE_CONFIG_DIR` and `XDG_CONFIG_HOME` cleared so it reads the throwaway file: ```bash TMPHOME="$(mktemp -d)" printf '%s\n' '{"mcpServers":{"rea":{"command":"npx","args":["-y","rea-agents@latest","mcp"]}}}' > "$TMPHOME/.claude.json" env -u CLAUDE_CONFIG_DIR -u XDG_CONFIG_HOME HOME="$TMPHOME" npx -y rea-agents@4.0.1 doctor --client claude_code --json > doctor.json echo "exit=$?" ``` 2. Inspect the registration result: `jq -c '{healthy, registrations: .identity.registrations, scope_checks}' doctor.json`. 3. Control: repeat step 1 with `rea-agents@4.0.1` in place of `rea-agents@latest` in the `.claude.json` args. 4. Repeat steps 1 and 3 with the runner `npx -y rea-agents@latest doctor ...` (the form the bundled skill uses) and with `node scripts/rea.mjs doctor ...` from a `main` build. #### Actual behavior Observed locally with the documented `@latest` registration (relevant fields only): ```text exit=1 "healthy": false identity.registrations: [{"client":"claude_code","command":["npx","-y","rea-agents@latest","mcp"],"state":"stale","remediation":"Run rea setup to refresh this registration, then restart the client."}] scope_checks: [{"name":"node","classification":"healthy"},{"name":"registration:claude_code","classification":"config_drift"}] ``` The control with `rea-agents@4.0.1` in the registration returned `exit=0`, `"healthy": true`, `"state": "aligned"`, and `registration:claude_code` classified `healthy`. A registration naming the older `rea-agents@4.0.0` returned `stale`, `config_drift`, and exit 1, the same result as `@latest`. With the runner `npx -y rea-agents@latest doctor`, `identity.cli_package_version` was `4.0.1`, and the `@latest` registration was still `stale` with exit 1. The `main` build gave the same results: `@latest` was stale with exit 1, and `@4.0.1` was aligned with exit 0. #### Evidence - Expected source: `docs/installation.md` "MCP Registry" section, lines 324-339 on `main` (manual configuration with `rea-agents@latest`, exact version presented as optional for reproducibility), https://github.com/morluto/rea/blob/19f8cddfd6f283188567b8ff1e49b810d79952ee/docs/installation.md#L324-L339, asserted by `tests/conformance/readmeConsistency.test.ts` lines 89-103; against the exact-pin rule in `README.md` lines 433-434 and `docs/installation.md` lines 35-37 on `main`. - Failure source: local `rea doctor --client claude_code --json` runs above; the `registrationAligned` check in `src/application/ClientRegistrationStatus.ts` lines 155-162 on `main` accepts an `npx -y <package> mcp` registration only when the package equals `PRODUCT_IDENTITY.registrationPackageSpecifier` (`rea-agents@<running version>`, `src/identity.ts` line 10), https://github.com/morluto/rea/blob/19f8cddfd6f283188567b8ff1e49b810d79952ee/src/application/ClientRegistrationStatus.ts#L155-L162, while `src/application/ClientRegistrationIdentity.ts` lines 38-44 recognize `rea-agents@latest` as a REA-owned registration. - Evidence provenance: observed - Local verification: reproduced - Reproduction completeness: complete #### Restoration check With the documented manual configuration from `docs/installation.md` in a throwaway `$HOME/.claude.json`, `rea doctor --client claude_code --json` should no longer report `state: "stale"`, `config_drift`, and exit 1 while the guide still presents that configuration as the one to use. Either doctor accepts the documented form when it resolves to the running version, or the guide and its conformance assertion stop recommending a form that doctor reports as stale. Controls: a registration naming the exact running version (`rea-agents@4.0.1` on the tested builds) should stay `aligned` with exit 0, a registration naming an exact older version such as `rea-agents@4.0.0` should still be reported stale, and the unversioned `rea-agents` registration covered by the existing "reports an unversioned npx registration as stale" test in `tests/boundary/filesystem/clientRegistrationStatus.test.ts` should keep its current result. ### Additional context - The README "Manual MCP configuration" section already uses an exact pinned version (`rea-agents@4.0.1`), and `rea setup` writes the exact running version, so among the user-facing docs only the installation guide's manual example and its conformance assertion use `@latest` as a registration; `@latest` elsewhere in the docs appears in one-off commands such as `npx -y rea-agents@latest doctor`. The contributor script `npm run config:print` (`scripts/print-mcp-config.mjs`) also prints an `rea-agents@latest` registration. - The bundled skill (`skills/reverse-engineer-anything/SKILL.md`, "Readiness and setup") tells agents to run `doctor` when a registration is reported stale and to propose `setup` when doctor finds an alignment problem. An agent following the skill on a client configured from the guide would therefore propose rewriting a registration that already launches the current release. - History, for context only: commit `3e3d45856ede849371027b62ad1a7b0687798951` changed the aligned check from the `@latest` specifier to the exact version, and the "MCP Registry" section with the `@latest` example and its conformance assertion arrived later, in #464. This does not show which behavior is intended. #### Triage assessment - Impact level: P2 - Assessment status: supported - Impact basis: Observed locally on the 4.0.1 release and `main`: following the documented manual configuration makes `rea doctor` report `healthy: false`, `config_drift`, and exit 1, which misleads users and any script or agent that checks doctor's result; the README and the rest of the installation guide already state the exact-pin rule, which limits but does not remove the confusion, and the bundled skill directs agents toward `rea setup`; the MCP server itself still launches the current release, so analysis is not blocked. - Workaround status: available - Workaround basis: Writing an exact `rea-agents@VERSION` in the registration, as the README manual example and `rea setup` already do, produced `aligned` and exit 0 in the control run; the tradeoff is that the pin must be refreshed after each upgrade, and doctor then reports it stale as intended.

bsakaguchi

2026-10-15 18:23:43 +00:00

closed this issue
added the
area: mcp

documentation
labels

bsakaguchi referenced this issue

2026-10-16 21:12:45 +00:00

[PR #309] [MERGED] fix(ci): retry published package verification #1945

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

morluto/rea#309

No description provided.

Rows
Columns

[GH-ISSUE #653] [Docs] Installation guide's manual MCP config uses rea-agents@latest, which rea doctor reports as stale #309