[PR #4994] [CLOSED] fix(setup): register a stable launcher from a version-scoped store #6716

Closed
opened 2026-11-01 21:42:31 +00:00 by bsakaguchi · 0 comments
Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/4994
Author: @skyzhao1223
Created: 10/18/2026
Status: ❌ Closed

Base: main ← Head: fix/setup-version-scoped-launcher


📝 Commits (1)

  • 00d269f fix(setup): register a stable launcher from a version-scoped store

📊 Changes

3 files changed (+92 additions, -0 deletions)

View changed files

📝 src/application/ClientRegistrationIdentity.ts (+19 -0)
📝 src/application/SetupHost.ts (+7 -0)
➕ src/application/SetupRegistrationLauncher.test.ts (+66 -0)

📄 Description

Summary

Fixes #4847.

When a package manager installs each release into its own directory and runs the
CLI through a shim (aube/mise, pnpm global), process.argv[1] is the versioned
store path, so rea setup registered something like
.../.mise/rea-agents@6.5.0/node_modules/rea-agents/scripts/rea.mjs. The
package manager removes that directory when it installs and prunes the next
version, so the agent's registration stopped existing after an upgrade while the
rea command on PATH kept working.

Problem and expected behavior

Smallest trigger: start setup from a store path whose package directory contains
the running package's name@version segment. Setup writes that exact path into
the client configuration. Expected: the registered launcher keeps working after
the package manager replaces that version.

Change and scope

setupRegistrationCommand now detects a version-scoped package store
(versionScopedStoreEntrypoint) and, for that layout only, registers the pinned
package-runner launcher the entrypoint already publishes:
npx -y rea-agents@<package version> mcp. ClientRegistrationStatus
already classifies that exact command as aligned, so no ownership rule,
registration state, or doctor/uninstall behavior changes.

Intentionally not included: the three directions in the issue. This is the
smallest change that stops the registration from expiring; it does not make the
registration follow the installed version by itself, and I have not guessed
which of those directions you prefer. Could a maintainer confirm the direction?

  1. bare rea — already classified as owned, but deliberately stale because it
    depends on the client's PATH;
  2. an explicit launcher option (rea setup --command <path> /
    REA_REGISTRATION_COMMAND) — needs recorded ownership so doctor, maintenance
    and uninstall can still prove the launcher is REA's;
  3. realpath(argv[1]) — keeps ownership and survives until the old version is
    pruned, but pins one version and regresses Homebrew-style layouts.

I am happy to implement or drop this in favor of whichever direction you accept.

Contract and boundary impact

  • Semantic owner and earliest changed stage: SetupHost.setupRegistrationCommand, after the entrypoint is resolved and before any client configuration is written.
  • Contribution scope fit and linked maintainer decision: ordinary fix inside existing setup boundaries; no new provider, capability, or authority. The registration form it selects already exists and is validated. The open design question is stated above for maintainer confirmation.
  • CLI and MCP/tool-catalog contract: no CLI flag, MCP tool, or catalog change; only the command string setup writes for this install layout.
  • Provider, bridge, target-format, or platform compatibility: Windows keeps the cmd.exe /d /c package-runner wrapper that clients can spawn; POSIX keeps npx.
  • Evidence, artifact, provenance, or reconstruction contract: none.
  • Target selection, authority, upstream behavior, and cleanup details (if applicable): not applicable; no target interaction.
  • Generated metadata, package, or installation impact: none; the fallback reuses PRODUCT_IDENTITY.registrationPackageSpecifier, so the registered package reference stays pinned to the running version.

Expected effects (check known effects; use documentation-only on its own).
Unchecked items do not establish absence; leave uncertainties visible.

  • Read existing files or captured data.
  • Launch or attach to a process.
  • Inject instrumentation or run scripts/code.
  • Change process memory, registers, files, or configuration.
  • Contact network services.
  • Recover protected code or work around protections.
  • Documentation or usability only; no target interaction.
  • Not sure yet; investigation or maintainer guidance needed.

Evidence and regression coverage

  • Tests added or updated: src/application/SetupRegistrationLauncher.test.ts covers the version-scoped POSIX and Windows store paths, the unchanged direct launcher for a release-independent path, another version's segment, and the explicit package-runner argument.
  • Base reproduction or other evidence: with the pre-change build, the same versioned store layout planned "/tmp/.../rea-agents@6.6.0/node_modules/rea-agents/scripts/rea.mjs" "mcp"; after the change it plans "npx" "-y" "rea-agents@6.6.0" "mcp".
  • User-visible CLI/MCP output (if applicable): setup --client codex --dry-run --json planned action below.
  • Remaining proof gaps: no real aube/mise or pnpm host was used; the fallback therefore requires npx on the host that starts the agent, and the pinned reference still needs a later rea setup (or an explicit runner invocation) to pick up a new version. No agent-side start after an upgrade was reproduced.

For evidence-bearing changes:

  • Observed, derived, and inferred claims remain distinguishable.
  • Artifact identity, source provenance, and failed attempts remain preserved.
  • Unsupported, incomplete, unavailable, or uncertain outcomes remain visible.

Validation performed

  • npm run build:cached — 3 tasks successful.
  • npm run test:local -- src/application/SetupRegistrationLauncher.test.ts — 2 passed.
  • npm run test:local -- src/application/Setup.configuration.test.ts — 22 passed (unchanged file; existing registration expectations).
  • npm run check:fast — typecheck and lint, 2 tasks successful.
  • npx oxfmt --check src/application/SetupHost.ts src/application/ClientRegistrationIdentity.ts src/application/SetupRegistrationLauncher.test.ts — all files correctly formatted.
  • Versioned store (package copied into /tmp/rea-store-4847/node_modules/.mise/rea-agents@6.6.0/node_modules/rea-agents, isolated HOME/TMPDIR, setup --client codex --dry-run --json) — planned command "npx" "-y" "rea-agents@6.6.0" "mcp".
  • Control store without a version segment (/tmp/rea-store-control/node_modules/rea-agents) — planned command "/tmp/rea-store-control/node_modules/rea-agents/scripts/rea.mjs" "mcp", so the direct launcher is preserved.

Compatibility, safety, and release

  • Breaking changes or migration steps: none. Existing registrations are unchanged; a later rea setup refreshes this layout to the package-runner command.
  • Real Hopper/Ghidra, browser, or OS coverage: none required or run.
  • Package or release metadata impact: none.
  • Security, privacy, process, or containment review: none; the fallback removes a path that expires and registers the same pinned package reference the npx path already uses.

Author readiness

Human owner: @skyzhao1223

  • 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.

Before merge

  • This PR addresses a concrete problem or an agreed enhancement.
  • Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff.
  • The PR has one focused outcome and the title follows type(scope): outcome.
  • Related issue is linked, or the reason for not linking one is stated above.
  • Tests cover changed observable behavior and meaningful failure paths.
  • Owning docs, contracts, and generated metadata are updated where needed.
  • User-visible CLI/MCP changes include representative output.
  • I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/4994 **Author:** [@skyzhao1223](https://github.com/skyzhao1223) **Created:** 10/18/2026 **Status:** ❌ Closed **Base:** `main` ← **Head:** `fix/setup-version-scoped-launcher` --- ### 📝 Commits (1) - [`00d269f`](https://github.com/morluto/rea/commit/00d269feb82d3d035f468f6b1901acbabd423b12) fix(setup): register a stable launcher from a version-scoped store ### 📊 Changes **3 files changed** (+92 additions, -0 deletions) <details> <summary>View changed files</summary> 📝 `src/application/ClientRegistrationIdentity.ts` (+19 -0) 📝 `src/application/SetupHost.ts` (+7 -0) ➕ `src/application/SetupRegistrationLauncher.test.ts` (+66 -0) </details> ### 📄 Description ## Summary Fixes #4847. When a package manager installs each release into its own directory and runs the CLI through a shim (aube/mise, pnpm global), `process.argv[1]` is the versioned store path, so `rea setup` registered something like `.../.mise/rea-agents@6.5.0/node_modules/rea-agents/scripts/rea.mjs`. The package manager removes that directory when it installs and prunes the next version, so the agent's registration stopped existing after an upgrade while the `rea` command on `PATH` kept working. ## Problem and expected behavior Smallest trigger: start setup from a store path whose package directory contains the running package's `name@version` segment. Setup writes that exact path into the client configuration. Expected: the registered launcher keeps working after the package manager replaces that version. ## Change and scope `setupRegistrationCommand` now detects a version-scoped package store (`versionScopedStoreEntrypoint`) and, for that layout only, registers the pinned package-runner launcher the entrypoint already publishes: `npx -y rea-agents@<package version> mcp`. `ClientRegistrationStatus` already classifies that exact command as `aligned`, so no ownership rule, registration state, or doctor/uninstall behavior changes. Intentionally not included: the three directions in the issue. This is the smallest change that stops the registration from expiring; it does not make the registration follow the installed version by itself, and I have not guessed which of those directions you prefer. Could a maintainer confirm the direction? 1. bare `rea` — already classified as owned, but deliberately `stale` because it depends on the client's `PATH`; 2. an explicit launcher option (`rea setup --command <path>` / `REA_REGISTRATION_COMMAND`) — needs recorded ownership so doctor, maintenance and uninstall can still prove the launcher is REA's; 3. `realpath(argv[1])` — keeps ownership and survives until the old version is pruned, but pins one version and regresses Homebrew-style layouts. I am happy to implement or drop this in favor of whichever direction you accept. ## Contract and boundary impact - Semantic owner and earliest changed stage: `SetupHost.setupRegistrationCommand`, after the entrypoint is resolved and before any client configuration is written. - Contribution scope fit and linked maintainer decision: ordinary fix inside existing setup boundaries; no new provider, capability, or authority. The registration form it selects already exists and is validated. The open design question is stated above for maintainer confirmation. - CLI and MCP/tool-catalog contract: no CLI flag, MCP tool, or catalog change; only the command string setup writes for this install layout. - Provider, bridge, target-format, or platform compatibility: Windows keeps the `cmd.exe /d /c` package-runner wrapper that clients can spawn; POSIX keeps `npx`. - Evidence, artifact, provenance, or reconstruction contract: none. - Target selection, authority, upstream behavior, and cleanup details (if applicable): not applicable; no target interaction. - Generated metadata, package, or installation impact: none; the fallback reuses `PRODUCT_IDENTITY.registrationPackageSpecifier`, so the registered package reference stays pinned to the running version. Expected effects (check known effects; use documentation-only on its own). Unchecked items do not establish absence; leave uncertainties visible. - [x] Read existing files or captured data. - [ ] Launch or attach to a process. - [ ] Inject instrumentation or run scripts/code. - [x] Change process memory, registers, files, or configuration. - [ ] Contact network services. - [ ] Recover protected code or work around protections. - [ ] Documentation or usability only; no target interaction. - [ ] Not sure yet; investigation or maintainer guidance needed. ## Evidence and regression coverage - Tests added or updated: `src/application/SetupRegistrationLauncher.test.ts` covers the version-scoped POSIX and Windows store paths, the unchanged direct launcher for a release-independent path, another version's segment, and the explicit package-runner argument. - Base reproduction or other evidence: with the pre-change build, the same versioned store layout planned `"/tmp/.../rea-agents@6.6.0/node_modules/rea-agents/scripts/rea.mjs" "mcp"`; after the change it plans `"npx" "-y" "rea-agents@6.6.0" "mcp"`. - User-visible CLI/MCP output (if applicable): `setup --client codex --dry-run --json` planned action below. - Remaining proof gaps: no real aube/mise or pnpm host was used; the fallback therefore requires `npx` on the host that starts the agent, and the pinned reference still needs a later `rea setup` (or an explicit runner invocation) to pick up a new version. No agent-side start after an upgrade was reproduced. For evidence-bearing changes: - [x] Observed, derived, and inferred claims remain distinguishable. - [ ] Artifact identity, source provenance, and failed attempts remain preserved. - [x] Unsupported, incomplete, unavailable, or uncertain outcomes remain visible. ## Validation performed - `npm run build:cached` — 3 tasks successful. - `npm run test:local -- src/application/SetupRegistrationLauncher.test.ts` — 2 passed. - `npm run test:local -- src/application/Setup.configuration.test.ts` — 22 passed (unchanged file; existing registration expectations). - `npm run check:fast` — typecheck and lint, 2 tasks successful. - `npx oxfmt --check src/application/SetupHost.ts src/application/ClientRegistrationIdentity.ts src/application/SetupRegistrationLauncher.test.ts` — all files correctly formatted. - Versioned store (package copied into `/tmp/rea-store-4847/node_modules/.mise/rea-agents@6.6.0/node_modules/rea-agents`, isolated `HOME`/`TMPDIR`, `setup --client codex --dry-run --json`) — planned command `"npx" "-y" "rea-agents@6.6.0" "mcp"`. - Control store without a version segment (`/tmp/rea-store-control/node_modules/rea-agents`) — planned command `"/tmp/rea-store-control/node_modules/rea-agents/scripts/rea.mjs" "mcp"`, so the direct launcher is preserved. ## Compatibility, safety, and release - Breaking changes or migration steps: none. Existing registrations are unchanged; a later `rea setup` refreshes this layout to the package-runner command. - Real Hopper/Ghidra, browser, or OS coverage: none required or run. - Package or release metadata impact: none. - Security, privacy, process, or containment review: none; the fallback removes a path that expires and registers the same pinned package reference the npx path already uses. ## Author readiness <!-- The human owner completes these declarations before requesting review. AI agents must leave these declarations to a human. Draft PRs may leave them unchecked. --> Human owner: @skyzhao1223 - [x] 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. - [x] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [x] I declare this PR ready for initial maintainer review. ## Before merge - [ ] This PR addresses a concrete problem or an agreed enhancement. - [ ] Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff. - [ ] The PR has one focused outcome and the title follows `type(scope): outcome`. - [ ] Related issue is linked, or the reason for not linking one is stated above. - [ ] Tests cover changed observable behavior and meaningful failure paths. - [ ] Owning docs, contracts, and generated metadata are updated where needed. - [ ] User-visible CLI/MCP changes include representative output. - [ ] I checked the final diff for secrets, unrelated cleanup, and unsupported claims. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
bsakaguchi 2026-11-01 21:42:31 +00:00
Sign in to join this conversation.
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#6716
No description provided.