fix(update): keep self-updates on the running install's global root by buddyh · Pull Request #101228 · openclaw/openclaw

buddyh · 2026-07-06T23:38:18Z

What Problem This Solves

openclaw update can run from one npm global install while the npm found on PATH derives npm root -g from another Node installation. In mixed Homebrew plus nvm/asdf/Volta setups, the updater could install successfully into that second tree and leave the running OpenClaw copy unchanged.

This PR keeps npm self-updates on the global prefix that owns the running OpenClaw package. It also handles scoped package roots and retains the package-manager probe when the package root is not a valid global npm layout.

Why This Change Was Made

The final implementation resolves the target at the shared resolveGlobalInstallTarget boundary:

A running package at <prefix>/lib/node_modules/openclaw selects that node_modules root even when PATH's probe diverges.
A scoped package at <prefix>/lib/node_modules/@scope/name resolves to the same owning root.
A source checkout or other non-global package root does not override npm root -g.
A failed probe can still fall back to a structurally valid running npm prefix.

This is narrower than trusting any path shaped like node_modules; only recognized npm global-prefix layouts receive the preference.

User Impact

Self-update changes the OpenClaw installation that actually launched the command instead of creating or refreshing a stale second copy. No config, CLI, or migration surface changes.

Evidence

Blacksmith Testbox tbx_01kwxa3ffx5t6s471n157f2dfv: 277 focused tests passed across update-global, update-runner, and update CLI coverage.
Full pnpm build: passed.
pnpm check:changed: passed.
Live filesystem/process probe: three real temporary layouts passed — divergent unscoped root, divergent scoped root, and non-global package-root fallback. The npm probe ran as a real subprocess in each case.
Fresh exact-branch autoreview: no accepted/actionable findings.

Closes the mixed-Node self-update targeting failure described in this PR. Thanks @buddyh for the report and original fix.

clawsweeper · 2026-07-06T23:50:55Z

Codex review: needs maintainer review before merge. Reviewed July 7, 2026, 12:03 AM ET / 04:03 UTC.

Summary
The branch updates global npm install target resolution/tests and also carries script test-plan caching, Tool Search stream hardening, and proxy upstream-error handling changes.

PR surface: Source +38, Tests +375, Other +23. Total +436 across 7 files.

Reproducibility: yes. Current main's resolver can still fall through to PATH's probed npm root, and the PR includes live mixed nvm/Homebrew proof showing the fixed path updates the running package tree.

Review metrics: 1 noteworthy metric.

Head freshness: 5 commits ahead, 19 commits behind dc5d413. The branch should be refreshed so already-landed proxy/tool-search/script changes do not obscure the update resolver merge result.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

Refresh the branch against current main and confirm the final merge diff is the update resolver/tests.
Rerun the focused update checks on the refreshed exact head before landing.

Risk before merge

[P1] The PR intentionally changes npm self-update target precedence: valid running global npm package roots win over PATH's npm root, which is upgrade-sensitive for mixed Node/package-manager environments.
[P1] The current head is behind reviewed main and its stale comparison includes already-merged script, Tool Search, and proxy changes; maintainers should refresh the exact merge result before landing.
[P1] The strongest live proof is macOS mixed nvm/Homebrew, while exact-head automated proof is Linux/Node 24; maintainers may still ask for a broader version-manager matrix if they want more upgrade-path coverage.

Maintainer options:

Rebase to an update-only merge result (recommended)
Refresh the branch against current main, confirm the final diff is the npm running-root resolver/tests, and rerun exact-head checks before merge.
Accept the stale-branch merge risk
Maintainers may still merge if the three-way result is clean and they are comfortable with the already-merged sibling patches appearing in the PR history.
Pause for more live update proof
Hold the PR if maintainers want more real mixed-manager update transcripts before changing global npm update target precedence.

Next step before merge

[P2] Maintainer action is to refresh/rebase and decide whether to accept the compatibility-sensitive npm update target precedence; no narrow automated repair finding is open.

Maintainer decision needed

Question: Should maintainers accept the npm self-update target-precedence change after rebasing/refreshing this branch against current main?
Rationale: The code path is the right layer and proof is strong, but changing package update target selection can affect existing mixed Node/npm installs and requires maintainer ownership of the upgrade behavior.
Likely owner: steipete — steipete is assigned, authored the maintainer fixup, and has the strongest recent history on update runner compatibility.
Options:
- Refresh and merge the bounded update fix (recommended): Rebase or otherwise refresh the branch so the merge result is update-focused, rerun exact-head checks, and merge if the compatibility change is accepted.
- Hold for broader live matrix: Keep the PR open until additional macOS/version-manager live update transcripts prove the same behavior across more npm ownership layouts.

Security
Cleared: No concrete security or supply-chain regression was found; the PR changes local update target resolution and already-reviewed stream/error handling without new dependencies, workflows, permissions, downloads, or secret handling.

Review details

Best possible solution:

Refresh to a clean update-focused merge result, rerun exact-head checks, then land the resolver fix if maintainers accept the npm target-precedence compatibility change.

Do we have a high-confidence way to reproduce the issue?

Yes. Current main's resolver can still fall through to PATH's probed npm root, and the PR includes live mixed nvm/Homebrew proof showing the fixed path updates the running package tree.

Is this the best way to solve the issue?

Yes, after branch refresh. The shared global install target resolver is the right layer because CLI and gateway update flows consume that target before staging, verification, swap, and post-update doctor work.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against dc5d4138f9ae.

Label changes

Label changes:

add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
remove rating: 🦞 diamond lobster: Current PR rating is rating: 🐚 platinum hermit, so this older rating label is no longer current.

Label justifications:

P2: The PR fixes a bounded update/install skew that can report success while leaving the running CLI on an older package tree.
merge-risk: 🚨 compatibility: The diff changes npm global self-update target selection for existing installs, which can affect upgrades in mixed Node/npm environments.
rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): Sufficient terminal proof is present: the PR body and maintainer comment describe a live macOS mixed nvm/Homebrew update that changed the running tree, plus sanitized AWS exact-head validation.
proof: sufficient: Contributor real behavior proof is sufficient. Sufficient terminal proof is present: the PR body and maintainer comment describe a live macOS mixed nvm/Homebrew update that changed the running tree, plus sanitized AWS exact-head validation.

Evidence reviewed

PR surface:

Source +38, Tests +375, Other +23. Total +436 across 7 files.

View PR surface stats

Area	Files	Added	Removed	Net
Source	3	49	11	+38
Tests	3	376	1	+375
Docs	0	0	0	0
Config	0	0	0	0
Generated	0	0	0	0
Other	1	30	7	+23
Total	7	455	19	+436

What I checked:

Repository policy read: Root AGENTS.md and scoped scripts/src-agents guidance were read; the update target precedence change falls under AGENTS.md compatibility-sensitive install/update behavior. (AGENTS.md:1, dc5d4138f9ae)
Current-main behavior: Current main resolves the npm target from the probed globalRoot after pnpm/bun/honorPackageRoot checks, so a divergent PATH npm can still decide the package update target. (src/infra/update-global.ts:799, dc5d4138f9ae)
PR update resolver change: The PR derives an npm target root from the running package root when it has a valid npm prefix and prefers that root before the probed npm root; it also adds scoped-root inference and local-root fallback coverage. (src/infra/update-global.ts:794, 26a041228029)
Caller and swap path: Package updates pass the resolved installTarget into runGlobalPackageUpdateSteps, which verifies the staged package and swaps it into installTarget.packageRoot, so the resolver is the correct ownership boundary for this bug. (src/infra/package-update-steps.ts:680, dc5d4138f9ae)
npm layout contract: Official npm folders docs state global installs use {prefix}/lib/node_modules on Unix, {prefix}/node_modules on Windows, and scoped packages live under the relevant node_modules/@scope folder; that matches the PR's global-root inference boundary. (docs.npmjs.com)
Real behavior and exact-head proof: The PR body and maintainer comment report live macOS mixed nvm/Homebrew update proof, plus sanitized AWS Crabbox run run_50739d922bcb with focused update tests and changed checks passing. (26a041228029)

Likely related people:

steipete: Assigned on the PR, authored the maintainer fixup commit, and has recent history across update runner/package update compatibility paths. (role: recent area contributor and reviewer; confidence: high; commits: f17f77ba41c6, bb44c2311d74, a326faa10cf8; files: src/infra/update-global.ts, src/infra/update-runner.ts, src/cli/update-cli/update-command.ts)
vincentkoc: Authored and merged prior per-Node npm prefix self-update work that this PR builds on. (role: adjacent behavior contributor; confidence: high; commits: df8ceb526725, b63336186ae1; files: src/infra/update-global.ts, src/infra/update-global.test.ts, src/infra/package-update-steps.ts)
kevinslin: Recent extended-stable update work touched packageName-aware target resolution and scoped package roots on the same resolver surface. (role: recent update-global contributor; confidence: medium; commits: d2146223205e; files: src/infra/update-global.ts, src/infra/update-global.test.ts, src/infra/update-runner.ts)
shakkernerd: Earlier commits established atomic npm global update staging and swap behavior that consumes the resolved target root. (role: introduced adjacent update staging behavior; confidence: medium; commits: 6985c6751c3d, 2186080963f4; files: src/infra/package-update-steps.ts, src/infra/update-global.ts)

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

Review history (3 earlier review cycles)

reviewed 2026-07-07T00:00:53.367Z sha 8b46030 :: needs real behavior proof before merge. :: [P2] Handle scoped package roots in the npm fallback
reviewed 2026-07-07T01:14:33.843Z sha 657cc2d :: needs maintainer review before merge. :: none
reviewed 2026-07-07T01:22:01.270Z sha 657cc2d :: needs maintainer review before merge. :: none

steipete · 2026-07-07T03:19:32Z

Maintainer fixup and verification completed on the final reviewed patch, merged from exact head 735c262135e68dec202eadaf4a7d32e21ce2cbd2 as 964fd53076cbb1ec4c6a2420b0b3559d42f29c6e.

The final refactor keeps the proven fix and narrows its policy boundary: a recognized running npm prefix now wins over a divergent PATH probe (src/infra/update-global.ts:797), while a local/non-global node_modules root still uses npm's probe. Scoped roots share the same canonical prefix inference (src/infra/update-global.ts:444, src/infra/update-global.ts:587). This removes the submitted broad rejection of all version-manager probe roots, which disabled atomic staging without preventing bare npm from using the same prefix.

Proof:

contributor live macOS update: the running nvm tree advanced from 2026.6.9 to 2026.6.11 while the skewed Cellar target remained empty;
sanitized AWS Crabbox run run_50739d922bcb on the patch-identical pre-rebase head (public network, no Tailscale, empty instance profile, no credential hydration);
pnpm test src/infra/update-global.test.ts src/infra/update-runner.test.ts src/cli/update-cli.test.ts — 273 passed;
pnpm check:changed -- src/infra/update-global.ts src/infra/update-global.test.ts — production/test typechecks, lint, dependency/boundary/runtime guards all passed;
oxfmt --check src/infra/update-global.ts src/infra/update-global.test.ts — passed;
fresh final autoreview — clean, no accepted/actionable findings;
final exact-head hosted CI run 28840812369 — all checks passed before merge.

Known gap: the contributor's live update proof is macOS; the final exact-head hosted proof is Linux/Node 24. The final fixup does not change the live-proven divergent-running-root branch; it removes unrelated probe policy and adds the local-root guard regression (src/infra/update-global.test.ts:566).

Package self-updates resolved their install target from `npm root -g` even when the running install's package root was already known. In an environment where PATH's npm does not belong to the running install's Node tree (a launchd/systemd service PATH, or mixed Homebrew + nvm setups), the probe points at a different global root — or derives a brand-new one — so the update installs there, reports success, and leaves the running install stale. Observed in the wild: a gateway-managed `openclaw update --yes` on 2026.5.28 ran nvm's npm under Homebrew's node, npm derived its default prefix from the realpathed execPath, and the update installed a full copy into /opt/homebrew/Cellar/node/26.3.1/lib/node_modules/openclaw ("before": null — a tree that had never existed) while the running nvm install stayed on the old version until a manual shell update. resolveGlobalInstallTarget now prefers the package root's own global root for npm targets; the `npm root -g` probe only decides the target when no package root is known, and an ephemeral per-Node probe result (Homebrew Cellar, nvm/n/asdf/volta version dirs — the same set openclaw#93650 filters npm commands against) is never adopted.

The running-root fallback missed scoped installs because inferGlobalRootFromPackageRoot only accepted an immediate node_modules parent. Hop over an @scope segment so node_modules/@scope/name resolves to the same global root. Regression test: scoped package root with an ephemeral probe now falls back to the running root.

steipete · 2026-07-07T04:20:59Z

Land-ready proof for exact head 735c262135e68dec202eadaf4a7d32e21ce2cbd2:

Review artifacts validate with zero findings; fresh exact-head autoreview is clean (0.86 confidence).
Blacksmith Testbox tbx_01kwxa3ffx5t6s471n157f2dfv: 96 infrastructure tests plus 181 CLI tests passed; full build and exact changed gate passed.
Live filesystem/process probe on the same Testbox passed all three root-selection cases: unscoped global package, scoped global package, and source checkout with package-manager probe.
Exact-head hosted CI run 28840812369 completed successfully.
OPENCLAW_TESTBOX=1 scripts/pr prepare-run 101228 passed exact-head hosted CI/Testbox gates and the native push guard.

Known proof gaps: none for the changed self-update root-selection surface.

steipete · 2026-07-07T04:21:18Z

Merged via squash.

Prepared head SHA: 735c262135e68dec202eadaf4a7d32e21ce2cbd2
Landed commit: 964fd53076cbb1ec4c6a2420b0b3559d42f29c6e

…penclaw#101228) * fix(update): keep self-updates on the running install's global root Package self-updates resolved their install target from `npm root -g` even when the running install's package root was already known. In an environment where PATH's npm does not belong to the running install's Node tree (a launchd/systemd service PATH, or mixed Homebrew + nvm setups), the probe points at a different global root — or derives a brand-new one — so the update installs there, reports success, and leaves the running install stale. Observed in the wild: a gateway-managed `openclaw update --yes` on 2026.5.28 ran nvm's npm under Homebrew's node, npm derived its default prefix from the realpathed execPath, and the update installed a full copy into /opt/homebrew/Cellar/node/26.3.1/lib/node_modules/openclaw ("before": null — a tree that had never existed) while the running nvm install stayed on the old version until a manual shell update. resolveGlobalInstallTarget now prefers the package root's own global root for npm targets; the `npm root -g` probe only decides the target when no package root is known, and an ephemeral per-Node probe result (Homebrew Cellar, nvm/n/asdf/volta version dirs — the same set openclaw#93650 filters npm commands against) is never adopted. * fix(update): infer global roots for scoped package roots The running-root fallback missed scoped installs because inferGlobalRootFromPackageRoot only accepted an immediate node_modules parent. Hop over an @scope segment so node_modules/@scope/name resolves to the same global root. Regression test: scoped package root with an ephemeral probe now falls back to the running root. * fix(update): scope running-root selection * docs(changelog): note npm self-update root fix * chore(changelog): defer release note --------- Co-authored-by: Peter Steinberger <steipete@gmail.com>

openclaw-barnacle Bot added size: S triage: needs-pr-context Candidate: external PR body lacks required problem context or evidence. labels Jul 6, 2026

openclaw-barnacle Bot removed the triage: needs-pr-context Candidate: external PR body lacks required problem context or evidence. label Jul 7, 2026

steipete self-assigned this Jul 7, 2026

steipete force-pushed the fix/self-update-honor-running-package-root branch from f17f77b to bf3128a Compare July 7, 2026 03:23

openclaw-barnacle Bot added scripts Repository scripts agents Agent runtime and tooling size: M and removed size: S labels Jul 7, 2026

clawsweeper Bot added rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. and removed rating: 🦞 diamond lobster Very strong PR readiness with only minor maintainer review expected. labels Jul 7, 2026

openclaw-barnacle Bot added size: XL and removed size: M labels Jul 7, 2026

buddyh and others added 5 commits July 7, 2026 00:08

fix(update): scope running-root selection

e801b61

docs(changelog): note npm self-update root fix

d5b7465

chore(changelog): defer release note

735c262

steipete force-pushed the fix/self-update-honor-running-package-root branch from 95d2960 to 735c262 Compare July 7, 2026 04:08

steipete merged commit 964fd53 into openclaw:main Jul 7, 2026
119 checks passed

steipete mentioned this pull request Jul 15, 2026

openclaw update trusts npm root -g stdout verbatim, but npm >= 11 redacts UUID-like path segments to literal *** — update then installs into a literal ***/ directory tree and silently leaves the live install stale #107239

Closed

arcabotai mentioned this pull request Jul 19, 2026

fix(update): reject npm redacted global root paths #107963

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

fix(update): keep self-updates on the running install's global root#101228

fix(update): keep self-updates on the running install's global root#101228
steipete merged 5 commits into
openclaw:mainfrom
buddyh:fix/self-update-honor-running-package-root

buddyh commented Jul 6, 2026 •

edited by steipete

Loading

Uh oh!

clawsweeper Bot commented Jul 6, 2026 •

edited

Loading

Uh oh!

steipete commented Jul 7, 2026 •

edited

Loading

Uh oh!

steipete commented Jul 7, 2026

Uh oh!

Uh oh!

steipete commented Jul 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

buddyh commented Jul 6, 2026 • edited by steipete Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What Problem This Solves

Why This Change Was Made

User Impact

Evidence

Uh oh!

clawsweeper Bot commented Jul 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

steipete commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

steipete commented Jul 7, 2026

Uh oh!

Uh oh!

steipete commented Jul 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

buddyh commented Jul 6, 2026 •

edited by steipete

Loading

clawsweeper Bot commented Jul 6, 2026 •

edited

Loading

steipete commented Jul 7, 2026 •

edited

Loading