PR #55457: fix: fall back to copy when runtime file symlinks are denied

• Repository: openclaw/openclaw
• Author: arkyu2077
• State: closed | merged: False
• Link: https://github.com/openclaw/openclaw/pull/55457

Description (problem / solution / changelog)

Summary

Fall back to copying runtime overlay files when file symlink creation is denied during bundled plugin runtime staging. This keeps the symlink-first behavior for normal environments but unblocks Windows builds where creating file symlinks in dist-runtime fails with EPERM/EACCES.

Changes

• catch file-symlink permission failures in symlinkPath()
• copy the source file into dist-runtime when symlink creation is denied
• add a focused regression test covering the fallback path

Testing

• pnpm exec vitest run --config vitest.unit.config.ts src/plugins/stage-bundled-plugin-runtime.test.ts
• repository commit hook checks passed during commit (format:check, lint suite, config/schema checks, plugin boundary checks)

Fixes openclaw/openclaw#55454

Changed files

• scripts/stage-bundled-plugin-runtime.mjs (modified, +12/-1)
• src/plugins/stage-bundled-plugin-runtime.test.ts (modified, +35/-0)

PR #55464: fix: fallback to file copy when symlink creation fails on Windows

• Repository: openclaw/openclaw
• Author: le0nardomartins
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/55464

Description (problem / solution / changelog)

Summary

• Problem: pnpm build fails on Windows when the runtime staging step tries to create a file symlink and Node returns EPERM or EACCES.
• Why it matters: this blocks local builds on Windows environments where file symlink creation is restricted, such as when Developer Mode is disabled or the process is not elevated.
• What changed: added a Windows-specific fallback to copy the file when file symlink creation is denied, and updated the related test coverage.
• What did NOT change (scope boundary): directory symlink behavior, non-Windows behavior, and the broader build pipeline were not changed.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #55454
• Related #
• This PR fixes a bug or regression

Root Cause / Regression History (if applicable)

• Root cause: the Windows build path attempts to create a file symlink during runtime staging, but file symlink creation may be denied on Windows without Developer Mode or elevated permissions.
• Missing detection / guardrail: there was no fallback for file symlink creation failure on Windows for file targets.
• Prior context (git blame, prior PR, issue, or refactor if known): Unknown.
• Why this regressed now: this is environment-dependent and reproduces on Windows setups where file symlink creation is restricted.
• If unknown, what was ruled out: general build flow issues were ruled out, since the build succeeds after handling the denied symlink path.

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: src/plugins/stage-bundled-plugin-runtime.test.ts
• Scenario the test should lock in: when file symlink creation fails on Windows with EPERM or EACCES, the staging path should fall back to copying the file.
• Why this is the smallest reliable guardrail: it validates the exact failure-handling behavior without requiring a full Windows-specific end-to-end environment.
• Existing test that already covers this (if any): none specific to this fallback behavior.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

Windows users can now complete pnpm build successfully in environments where file symlink creation is denied, because the build falls back to copying the file.

Diagram (if applicable)

Before:
[pnpm build] -> [file symlink attempt on Windows] -> [EPERM/EACCES] -> [build fails]

After:
[pnpm build] -> [file symlink attempt on Windows] -> [EPERM/EACCES] -> [copy file fallback] -> [build succeeds]

Security Impact (required)

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

Repro + Verification

Environment

• OS: Windows
• Runtime/container: local Node.js environment
• Model/provider: N/A
• Integration/channel (if any): N/A
• Relevant config (redacted): local checkout, build run via pnpm build

Steps

1. Clone the repository on Windows.
2. Run pnpm build.
3. Observe failure during runtime staging when creating a file symlink.

Expected

• pnpm build should complete successfully.

Actual

• Build failed with EPERM: operation not permitted during fs.symlinkSync(...).

Evidence

Attach at least one:

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

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: ran pnpm build on Windows before and after the change; confirmed the build passed after the fallback was added.
• Edge cases checked: Windows-denied symlink path covered by updated test.
• What you did not verify: non-Windows behavior beyond keeping the existing path unchanged.

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.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps:

Risks and Mitigations

List only real risks for this PR. Add/remove entries as needed. If none, write None.

• Risk: copying a file instead of symlinking may diverge slightly from the original behavior in restricted Windows environments.

  • Mitigation: fallback is only used when symlink creation fails with Windows permission-related errors; normal behavior is preserved otherwise.

Changed files

• scripts/stage-bundled-plugin-runtime.mjs (modified, +28/-4)
• src/plugins/stage-bundled-plugin-runtime.test.ts (modified, +6/-2)