fix(installer): align Node version floor with package engine by kiranmagic7 · Pull Request #81264 · openclaw/openclaw

kiranmagic7 · 2026-05-13T03:11:17Z

Summary

Problem: scripts/install.sh accepted Node 22.14+, while package.json and public docs require Node 22.19+.
Why it matters: the installer could keep using an existing Node runtime that npm/package engine checks reject later.
What changed: raised the installer minimum minor from 22.14 to 22.19 and added a regression test against the package engine floor.
What did NOT change: Node 24 remains the recommended/default installer-managed runtime.

AI-assisted: yes, per CONTRIBUTING.md. I understand the change; it is limited to the installer version floor and its targeted test coverage.

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

Closes #
Related #
This PR fixes a bug or regression

Real behavior proof (required for external PRs)

Behavior or issue addressed: installer Node runtime acceptance now matches package.json (>=22.19.0).
Real environment tested: local macOS checkout; shell proof uses a temporary fake node binary so the installer helper is exercised without changing the machine runtime.
Exact steps or command run after this patch:

node scripts/run-vitest.mjs run --config test/vitest/vitest.tooling.config.ts test/scripts/install-sh.test.ts

Focused helper proof:

v22.18.0 status=1
v22.19.0 status=0

Evidence after fix:

✓ tooling test/scripts/install-sh.test.ts (17 tests) 4954ms
Test Files 1 passed (1)
Tests 17 passed (17)

Observed result after fix: Node 22.18 is rejected by node_is_at_least_required; Node 22.19 is accepted.
What was not tested: full mutating installer e2e and hosted CDN sync/deploy.
Before evidence: source had NODE_MIN_MINOR=14, while package.json requires >=22.19.0.

Root Cause (if applicable)

Root cause: installer minimum-version constants drifted below the package engine floor.
Missing detection / guardrail: installer tests did not assert the package engine boundary.
Contributing context (if known): NODE_DEFAULT_MAJOR=24 was already correct; only the compatibility floor was stale.

Regression Test Plan (if applicable)

Coverage level that should have caught this:
- Unit test
- Seam / integration test
- End-to-end test
- Existing coverage already sufficient
Target test or file: test/scripts/install-sh.test.ts
Scenario the test should lock in: fake Node 22.18 is rejected, fake Node 22.19 is accepted, and the package engine remains >=22.19.0.
Why this is the smallest reliable guardrail: it exercises the installer helper directly without running a mutating installer flow.
Existing test that already covers this (if any): none.
If no new test is added, why not: N/A

User-visible / Behavior Changes

Existing Node 22.14 through 22.18 runtimes are no longer treated as acceptable by the installer. Users should use Node 24 recommended, or Node 22.19+ minimum.

Diagram (if applicable)

Before:
existing node v22.14 -> installer accepts -> package engine can reject later

After:
existing node v22.18 -> installer rejects/upgrades path
existing node v22.19 -> installer accepts

Security Impact (required)

New permissions/capabilities? No
Secrets/tokens handling changed? No
New/changed network calls? No
Command/tool execution surface changed? No
Data access scope changed? No
If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

OS: macOS local checkout
Runtime/container: local shell + Vitest tooling config
Model/provider: N/A
Integration/channel (if any): installer script only
Relevant config (redacted): N/A

Steps

Source scripts/install.sh with OPENCLAW_INSTALL_SH_NO_RUN=1.
Put a temporary fake node binary first on PATH.
Run node_is_at_least_required with fake versions v22.18.0 and v22.19.0.
Run the targeted installer test file.

Expected

v22.18.0 is rejected.
v22.19.0 is accepted.
Installer tests pass.

Actual

v22.18.0 status: 1
v22.19.0 status: 0
test/scripts/install-sh.test.ts: 17/17 passing.

Evidence

Failing test/log before + passing after
Trace/log snippets
Screenshot/recording
Perf numbers (if relevant)

Human Verification (required)

What was verified locally, and how:

Verified scenarios: targeted Vitest suite and direct installer helper proof for 22.18 vs 22.19.
Edge cases checked: boundary minor versions around the documented/package-supported Node 22 floor.
What was not verified: full installer e2e, package install under an actual below-floor Node runtime, hosted CDN sync.

Review Conversations

I replied to or resolved every bot review conversation I addressed in this PR.
I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

Backward compatible? No, intentionally rejects Node 22.14 through 22.18 as unsupported.
Config/env changes? No
Migration needed? Yes, for users still on Node 22.14 through 22.18.
If yes, exact upgrade steps: use Node 24 recommended, or upgrade to Node 22.19+ minimum.

Risks and Mitigations

Risk: users on Node 22.14 through 22.18 see an installer upgrade/reject path earlier than before.
- Mitigation: this matches the existing package engine and docs, so the failure moves earlier and is clearer.

clawsweeper · 2026-05-13T03:14:27Z

Codex review: needs maintainer review before merge. Reviewed May 29, 2026, 6:34 PM ET / 22:34 UTC.

Summary
This PR adds an installer Vitest regression test that derives the Node 22 minor floor from package.json and verifies node_is_at_least_required rejects one minor below while accepting the floor.

PR surface: Tests +53. Total +53 across 1 file.

Reproducibility: yes. for the historical bug: source history and the PR body show the installer floor had drifted below the package/docs Node 22.19 contract. Current main already has the runtime floor fixed, so the remaining reproducible surface is the regression test added by this PR.

Review metrics: none identified.

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

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

Risk before merge

[P1] Exact-head check runs currently show two failed core/runtime lanes; I did not find a diff-introduced defect, but maintainers should inspect or rerun those checks before merge.

Maintainer options:

Decide the mitigation before merge
Land the focused regression test once exact-head required checks are green, while keeping the already-shipped Node 22.19 installer/package floor unchanged.
Pause or close
Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

[P2] No repair lane is needed because there are no actionable patch findings; maintainers should resolve the exact-head check failures and perform normal merge review.

Security
Cleared: The current diff adds a test-only fake-node fixture and does not change production execution, dependency resolution, secrets, permissions, or supply-chain surfaces.

Review details

Best possible solution:

Land the focused regression test once exact-head required checks are green, while keeping the already-shipped Node 22.19 installer/package floor unchanged.

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

Yes for the historical bug: source history and the PR body show the installer floor had drifted below the package/docs Node 22.19 contract. Current main already has the runtime floor fixed, so the remaining reproducible surface is the regression test added by this PR.

Is this the best way to solve the issue?

Yes; now that the runtime change is on main, tying the shell helper floor to package.json with a focused boundary test is the narrowest maintainable remaining fix.

AGENTS.md: found and applied where relevant.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 63a06e312dfe.

Label changes

Label changes:

add proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes after-fix terminal proof for the v22.18 rejection and v22.19 acceptance boundary plus the focused installer test run; no contributor action is needed for proof.

Label justifications:

P2: This is a normal-priority installer regression guard with limited blast radius and no current patch correctness finding.
rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The PR body includes after-fix terminal proof for the v22.18 rejection and v22.19 acceptance boundary plus the focused installer test run; no contributor action is needed for proof.
proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes after-fix terminal proof for the v22.18 rejection and v22.19 acceptance boundary plus the focused installer test run; no contributor action is needed for proof.

Evidence reviewed

PR surface:

Tests +53. Total +53 across 1 file.

View PR surface stats

Area	Files	Added	Net
Source	0	0	0
Tests	1	53	+53
Docs	0	0	0
Config	0	0	0
Generated	0	0	0
Other	0	0	0
Total	1	53	+53

What I checked:

Current installer floor: Current main sets NODE_MIN_MINOR=19 and node_is_at_least_required accepts Node 22 only when the minor is at or above that floor. (scripts/install.sh:21, 63a06e312dfe)
Package engine contract: Current main declares the package Node engine as >=22.19.0, matching the installer floor. (package.json:1941, 63a06e312dfe)
Public docs contract: The Node install docs state that OpenClaw requires Node 22.19 or newer and recommends Node 24. Public docs: docs/install/node.md. (docs/install/node.md:10, 63a06e312dfe)
PR test coverage: The PR head adds a test that reads package.json, checks the installer constant, and exercises fake Node versions one minor below and at the floor. (test/scripts/install-sh.test.ts:962, 42cde563b78d)
Current-main gap: The corresponding current-main test area jumps from the supported-binary test to the Linux-path persistence test, so this exact package-engine floor guard is not already present on main. (test/scripts/install-sh.test.ts:962, 63a06e312dfe)
Release behavior provenance: The latest release tag v2026.5.27 contains NODE_MIN_MINOR=19 in scripts/install.sh and package.json has node >=22.19.0, while the new regression test is not in that tag. (scripts/install.sh:21, 27ae826f6525)

Likely related people:

steipete: Current main and the latest release carry Peter Steinberger-authored/grafted changes over scripts/install.sh, package.json, and installer tests, and earlier history shows work on node version guard parsing. (role: recent area contributor; confidence: high; commits: 493b560dfdfd, 27ae826f6525, e6b011823ebb; files: scripts/install.sh, package.json, test/scripts/install-sh.test.ts)
Altay: Altay authored the March 2026 commits that raised the Node 22 compatibility floor to 22.16 and aligned installer guidance before the later 22.19 update. (role: historical Node floor contributor; confidence: medium; commits: 0a8d2b6200f6, b0f717aa0294; files: scripts/install.sh, package.json)
obviyus: Ayaan Zaidi committed the March 2026 Node 22.16 floor and guidance changes, making them a useful routing candidate for this installer/runtime floor history. (role: historical merger/committer; confidence: medium; commits: 0a8d2b6200f6, b0f717aa0294; files: scripts/install.sh, package.json)

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.

github-actions · 2026-05-19T00:58:48Z

Dependency Changes Detected

This PR changes dependency-related files. Maintainers should confirm these changes are intentional.

Changed files:

package.json

Maintainer follow-up:

Review whether the dependency changes are intentional.
Inspect resolved package deltas when lockfile or workspace dependency policy changes are present.
Run pnpm deps:changes:report -- --base-ref origin/main --markdown /tmp/dependency-changes.md --json /tmp/dependency-changes.json locally for detailed release-style evidence.

kiranmagic7 · 2026-05-23T00:39:13Z

Updated the PR body with the current v22.18 rejection / v22.19 acceptance proof.

@clawsweeper re-review

clawsweeper · 2026-05-23T00:39:15Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

State: Complete
Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
Run: https://github.com/openclaw/clawsweeper/actions/runs/26318700070
Updated: 2026-05-23T00:48:07.168Z

clawsweeper · 2026-05-23T00:48:00Z

ClawSweeper PR egg

✨ Hatched: 🥚 common Gilded Diff Drake

Hatch command

Comment @clawsweeper hatch when this PR is hatchable.

Hatchability rules:

Merged PRs are hatchable.
Open PRs are hatchable when they are status: 👀 ready for maintainer look, status: 🚀 automerge armed, or labeled clawsweeper:automerge.
Closed unmerged PRs are hatchable only when one of those hatchable labels is still present in the durable record.

Rarity: 🥚 common.
Trait: keeps receipts.
Image traits: location merge queue dock; accessory tiny test log scroll; palette seafoam, black, and opal; mood proud; pose holding its accessory up for inspection; shell smooth pearl shell; lighting calm overcast light; background tiny artifact crates.
Share on X: post this hatch
Copy: My PR egg hatched a 🥚 common Gilded Diff Drake in ClawSweeper.

What is this egg doing here?

Eggs appear after the PR passes real-behavior proof. It is here for vibes, not verdicts: it does not change labels, ratings, merge decisions, or automation.
The shell reacts to review momentum: open follow-up work warms it up, re-review makes it wobble, and a clean final review lets it hatch.
Hatchability usually comes from sufficient real-behavior proof, no blocking P0/P1/P2 findings, no security attention needed, and clean correctness. A merged PR is already final, so merge makes the egg hatchable independently.
The hatch is seeded from this repository and PR number, so the same PR keeps the same creature; the reviewed head SHA can only change safe visual details.
Rarity is just collectible sparkle: 🥚 common, 🌱 uncommon, 💎 rare, ✨ glimmer, and 🌈 legendary.

RomneyDa · 2026-05-29T06:29:40Z

Heads up: this PR needs to be updated against current main before the new required Dependency Guard check can pass.

steipete · 2026-06-01T01:23:15Z

Maintainer land check for #81264 at head 42cde563b78d0c7adba838286e4333a154ada95e.

Local proof run from the PR branch:

.agents/skills/autoreview/scripts/autoreview --mode branch --base origin/main
node scripts/run-vitest.mjs run --config test/vitest/vitest.tooling.config.ts test/scripts/install-sh.test.ts

Results:

Autoreview: clean, no accepted/actionable findings.
Focused installer test: 1 file passed, 44 tests passed.
Diff checked: test/scripts/install-sh.test.ts only, +53/-0.

CI status before rerun: run https://github.com/openclaw/openclaw/actions/runs/26665279169 had two red unrelated lanes:

checks-node-core-runtime-infra-state: unhandled rejection from src/infra/net/http-connect-tunnel.test.ts.
checks-node-agentic-gateway-core: timeout in src/gateway/gateway-cli-backend.live-probe-helpers.test.ts.

I reran failed jobs on run https://github.com/openclaw/openclaw/actions/runs/26665279169 and will merge only if the required gate is green.

fix(installer): align Node version floor with package engine

d767656

openclaw-barnacle Bot added scripts Repository scripts size: S proof: supplied External PR includes structured after-fix real behavior proof. labels May 13, 2026

clawsweeper Bot added the proof: sufficient ClawSweeper judged the real behavior proof convincing. label May 13, 2026

clawsweeper Bot mentioned this pull request May 14, 2026

docs(getting-started): add Step 0 prerequisite checks and dependency install hints #70459

Closed

4 tasks

github-actions Bot added the dependencies-changed PR changes dependency-related files label May 19, 2026

openclaw-barnacle Bot removed the proof: sufficient ClawSweeper judged the real behavior proof convincing. label May 19, 2026

test(installer): keep Node floor tied to package engine

76287f0

kiranmagic7 force-pushed the kiran/daily-community-20260513-node-floor branch from db11c79 to 76287f0 Compare May 19, 2026 10:26

Merge branch 'main' into kiran/daily-community-20260513-node-floor

11fb650

openclaw-barnacle Bot removed the scripts Repository scripts label May 29, 2026

github-actions Bot removed the dependencies-changed PR changes dependency-related files label May 29, 2026

clawsweeper Bot removed the rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. label May 29, 2026

clawsweeper Bot added the rating: 🦞 diamond lobster Very strong PR readiness with only minor maintainer review expected. label May 29, 2026

Merge branch 'main' into kiran/daily-community-20260513-node-floor

dad53b8

openclaw-barnacle Bot removed the proof: sufficient ClawSweeper judged the real behavior proof convincing. label May 29, 2026

clawsweeper Bot added the proof: sufficient ClawSweeper judged the real behavior proof convincing. label May 29, 2026

Merge branch 'main' into kiran/daily-community-20260513-node-floor

f7b1e16

openclaw-barnacle Bot removed the proof: sufficient ClawSweeper judged the real behavior proof convincing. label May 29, 2026

clawsweeper Bot added the proof: sufficient ClawSweeper judged the real behavior proof convincing. label May 29, 2026

Merge branch 'main' into kiran/daily-community-20260513-node-floor

42cde56

openclaw-barnacle Bot removed the proof: sufficient ClawSweeper judged the real behavior proof convincing. label May 29, 2026

clawsweeper Bot added the proof: sufficient ClawSweeper judged the real behavior proof convincing. label May 29, 2026

steipete self-assigned this Jun 1, 2026

steipete merged commit cc97eca into openclaw:main Jun 1, 2026
152 of 155 checks passed

clawsweeper Bot mentioned this pull request Jun 29, 2026

docs: clarify source checkout Node floor #97898

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

fix(installer): align Node version floor with package engine#81264

fix(installer): align Node version floor with package engine#81264
steipete merged 6 commits into
openclaw:mainfrom
kiranmagic7:kiran/daily-community-20260513-node-floor

kiranmagic7 commented May 13, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented May 13, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 19, 2026

Uh oh!

kiranmagic7 commented May 23, 2026

Uh oh!

clawsweeper Bot commented May 23, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented May 23, 2026

Uh oh!

RomneyDa commented May 29, 2026

Uh oh!

steipete commented Jun 1, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Uh oh!

Conversation

kiranmagic7 commented May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

Real behavior proof (required for external PRs)

Root Cause (if applicable)

Regression Test Plan (if applicable)

User-visible / Behavior Changes

Diagram (if applicable)

Security Impact (required)

Repro + Verification

Environment

Steps

Expected

Actual

Evidence

Human Verification (required)

Review Conversations

Compatibility / Migration

Risks and Mitigations

Uh oh!

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

Uh oh!

Uh oh!

github-actions Bot commented May 19, 2026

Dependency Changes Detected

Uh oh!

kiranmagic7 commented May 23, 2026

Uh oh!

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

Uh oh!

Uh oh!

clawsweeper Bot commented May 23, 2026

Hatch command

Uh oh!

RomneyDa commented May 29, 2026

Uh oh!

steipete commented Jun 1, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

kiranmagic7 commented May 13, 2026 •

edited

Loading

clawsweeper Bot commented May 13, 2026 •

edited

Loading

clawsweeper Bot commented May 23, 2026 •

edited

Loading