feat: bundle Node.js runtime in the Gateway MSIX

[xlinush]

What Problem This Solves

Remove the device-wide Node.js prerequisite by bundling the official architecture-specific runtime with the Gateway MSIX.

Why This Change Was Made

A majority of maintainers have voted to bundle Node.js with the MSIX again, revising the previous no-bundling decision in #4 and #12. OpenClaw will publish updated MSIX packages in response to Node.js security releases. Runtime servicing is delivered through package releases, not an independent runtime updater.

Node.js dependency resolution

1. The Linux job already checked out openclaw/openclaw at OPENCLAW_REF; that ref is unchanged. Removing path: openclaw-source puts the source at the workspace root, so its local actions and their nested action references resolve correctly. The corresponding build-step working-directory overrides are removed.
2. Replace the packaging-owned NODE_VERSION/PNPM_VERSION pins and separate Node/Corepack setup steps with uses: ./.github/actions/setup-node-env. This runs the action from the selected upstream checkout, not from the packaging repository. No node-version override is supplied. Optional Bun setup is disabled, and the explicit pnpm install --frozen-lockfile step is retained.
3. Capture the actual version with node -p 'process.versions.node' and record it in the job output and source.json. Both Windows payload jobs use that exact version; Build-Payload.ps1 rejects mismatches and records it in payload-metadata.json.
4. Build-MSIX.ps1 uses that metadata to fetch the matching official Windows Node ZIP for x64 or ARM64 and includes it through NodeRuntimeArchiveFileName. The launcher derives its runtime identity from the archive name; there is no separate launcher pin or duplicated support-range policy.

Resolution follows upstream's policy, including compatible-cache reuse; it is not an unconditional latest-Node lookup.

User Impact

Run clawctl setup after installation and whenever an update changes the bundled Node version. Setup validates and repairs versioned LocalState runtimes, reclaims interrupted staging, and serializes installation across Windows sessions. It extracts the bundled ZIP without downloading a runtime.

OpenClaw still executes directly from the immutable MSIX application tree. The child's PATH includes the bundled tools; arguments, working directory, exit codes, and the existing System.CommandLine control UX are preserved.

Evidence

Validated at 5baa5e646d61de3257099c1a7f506ed235925ed9:

• CI passed, including upstream package creation, host checks, and x64/ARM64 payload and unsigned MSIX builds.
• Local quality gate, 94 .NET tests, packaging/signing script suites, and workflow lint passed.
• The repository NativeAOT CLI gate passed; an isolated real-Node NativeAOT harness also covered setup, reuse, repair, concurrency, version changes, child-tool resolution, and argument/exit-code forwarding with Node 24.15.0 and 24.16.0.
• Local x64 MSIX composition passed with the payload's recorded 24.16.0 runtime and a controlled non-default 24.15.0 metadata fixture.

Installed-MSIX fresh/upgrade flows and ARM64 execution were not exercised locally.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: blocked before merge. Reviewed September 12, 2026, 2:43 AM ET / 06:43 UTC (Revision 5).

ClawSweeper review

What this changes

The PR packages the upstream-selected Node.js runtime, adds setup-time extraction and repair, and launches OpenClaw with the bundled tools.

Merge readiness

⛔ Blocked before merge - 3 items remain

The change remains useful: main still requires device-installed Node.js. Both earlier code findings are resolved, and the updated maintainer comments settle the bundling and servicing policy. No blocking code defect was found; only acceptance of the remaining installed-package validation gap needs clarification.

Priority: P2
Reviewed head: 5baa5e646d61de3257099c1a7f506ed235925ed9
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A coherent implementation with focused regression coverage and resolved earlier findings; the remaining validation-scope decision does not lower patch quality.
Proof confidence	🌊 off-meta tidepool	Not applicable: The collaborator exemption applies. The captured body reports real-Node NativeAOT setup, repair, version-change, and forwarding coverage; installed-MSIX coverage is explicitly excluded and assessed separately as a compatibility decision.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: The collaborator exemption applies. The captured body reports real-Node NativeAOT setup, repair, version-change, and forwarding coverage; installed-MSIX coverage is explicitly excluded and assessed separately as a compatibility decision.
Evidence reviewed	10 items	Current main still requires device Node: The main-branch resolver searches PATH, queries Node's version, and checks its architecture; it does not prepare a bundled runtime. Earlier repair finding resolved: Setup validates an existing executable under the installation mutex, replaces invalid runtimes, validates staged extraction before publication, and cleans interrupted staging. Focused tests cover repair, reuse, concurrent setup, and unsafe archive entries. Earlier version-selection finding resolved: The workflow invokes the selected upstream checkout's setup action, records process.versions.node, and passes that version to Windows payload jobs. Payload creation rejects mismatches; package composition derives the archive name from the same metadata.
Findings	None	None.
Security	None	None.

How this fits together

The Windows Gateway package contains OpenClaw and a native command-line launcher. Packaging selects the runtime, setup prepares it in per-user storage, and the launcher forwards commands to the packaged OpenClaw application.

flowchart TD
  A[Upstream build toolchain] --> B[Runtime version metadata]
  B --> C[Windows package and Node archive]
  C --> D[Setup validates or extracts runtime]
  D --> E[Versioned per-user runtime]
  E --> F[Native command launcher]
  C --> F
  F --> G[Packaged OpenClaw application]

Loading

Decision needed

Question	Recommendation
Can the reported real-Node NativeAOT coverage support this pre-release merge, with installed-MSIX validation deferred until the first official release?	Accept pre-release coverage: Accept the reported harness and package-build evidence for merging, while requiring installed setup and runtime-changing update validation before the first official release.

Why: The policy reversal and historical migration objection are resolved, but the previously requested installed-package coverage remains explicitly unperformed; accepting that release-stage boundary requires maintainer intent.

Before merge

• Resolve merge risk (P1) - Installed package identity and LocalState setup have not been exercised for this branch. Experimental installations and future runtime-changing package updates stop until clawctl setup runs; the reported harness covers runtime version changes but not an actual MSIX update.
• Complete next step (P2) - Confirm acceptance of the reported runtime harness for this pre-release merge, or provide installed-MSIX setup and runtime-version transition evidence.
• Resolve maintainer decision - Resolve the maintainer decision shown above before merge.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Production and test growth	Production +374 net lines; tests +440 net lines	Launcher and packaging-script growth implements the stated runtime-bundling feature; counts exclude workflow and documentation changes.

Merge-risk options

Maintainer options:

1. Accept the pre-release validation boundary (recommended)
   Explicitly accept the isolated runtime coverage for merge and reserve installed setup/update validation for the first official release.
2. Exercise the installed transition now
   Supply installed-package evidence showing setup recovery after a runtime-version change and preservation of OpenClaw user state.

Technical review

Best possible solution:

Keep the approved bundled-runtime design and establish installed setup and runtime-changing update coverage before the first official release.

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

Not applicable: this adds bundled-runtime support rather than fixing a reproduced bug; current main's device-Node requirement is directly visible in source.

Is this the best way to solve the issue?

Yes: following upstream runtime selection and confining extraction to setup is coherent with the approved direction. Installed-package validation remains a release-readiness consideration.

AGENTS.md: not found in the target repository.

Codex review notes: model internal, reasoning medium; reviewed against 6f89905a5349.

Labels

Label changes:

• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The collaborator exemption applies. The captured body reports real-Node NativeAOT setup, repair, version-change, and forwarding coverage; installed-MSIX coverage is explicitly excluded and assessed separately as a compatibility decision.
• remove status: ⏳ waiting on author: Current PR status label is status: 👀 ready for maintainer look.
• remove merge-risk: 🚨 security-boundary: Current PR review merge-risk labels are merge-risk: 🚨 compatibility.

Label justifications:

• P2: This is a bounded packaging improvement with approved direction and no demonstrated urgent regression.
• merge-risk: 🚨 compatibility: The runtime prerequisite changes to explicit setup, while installed-package setup and version-changing update behavior remain unexercised.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The collaborator exemption applies. The captured body reports real-Node NativeAOT setup, repair, version-change, and forwarding coverage; installed-MSIX coverage is explicitly excluded and assessed separately as a compatibility decision.

Evidence

What I checked:

• Current main still requires device Node: The main-branch resolver searches PATH, queries Node's version, and checks its architecture; it does not prepare a bundled runtime. (src/OpenClaw.Launcher/NodeRuntimeResolver.cs:34, 6f89905a5349)
• Earlier repair finding resolved: Setup validates an existing executable under the installation mutex, replaces invalid runtimes, validates staged extraction before publication, and cleans interrupted staging. Focused tests cover repair, reuse, concurrent setup, and unsafe archive entries. (src/OpenClaw.Launcher/NodeRuntimeInstaller.cs:99, 5baa5e646d61)
• Earlier version-selection finding resolved: The workflow invokes the selected upstream checkout's setup action, records process.versions.node, and passes that version to Windows payload jobs. Payload creation rejects mismatches; package composition derives the archive name from the same metadata. (.github/workflows/gateway-msix.yml:115, 5baa5e646d61)
• Verified upstream dependency contract: The directly invoked setup-node-env action defaults to Node 24.x, runs its ensure-node helper, and references setup-pnpm-store-cache relative to the checkout root. This supports the workflow's root-checkout change and establishes the affirmative dependency signal. (.github/actions/setup-node-env/action.yml:9, 0965053fe6b9)
• Maintainer dispositions supersede earlier policy blockers: The collaborator confirms majority approval for bundling and package-based Node security servicing at feat: bundle Node.js runtime in the Gateway MSIX #30 (comment) and explicitly dismisses historical migration concerns because there have been no official releases at feat: bundle Node.js runtime in the Gateway MSIX #30 (comment).
• Release check: The GitHub releases endpoint returned an empty list, consistent with the maintainer's statement that no official release migration is involved.

Likely related people:

• xlinush: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• paulcam206: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Demonstrate installed-MSIX setup and a bundled-runtime version transition before the first official release.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
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.

Workflow

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

History

Review history (4 earlier review cycles)

• reviewed 2026-09-11T22:13:15.196Z sha 27cc6b8 :: blocked before merge. :: [P2] Repair an invalid existing runtime before reusing it | [P2] Use one runtime version across build and launcher
• reviewed 2026-09-11T23:28:44.339Z sha 5208c1d :: blocked before merge. :: none
• reviewed 2026-09-11T23:54:35.198Z sha 5baa5e6 :: blocked before merge. :: none
• reviewed 2026-09-12T00:26:34.502Z sha 5baa5e6 :: blocked before merge. :: none

[xlinush]

Two maintainer decisions remain before this should leave draft: runtime-servicing ownership and the install/upgrade preparation contract.

[xlinush]

@copilot resolve the merge conflicts in this pull request