gateway: fix global Control UI 404s for symlinked wrappers and bundled package roots by velvet-shark · Pull Request #40385 · openclaw/openclaw

velvet-shark · 2026-03-09T00:21:10Z

Summary

Problem: bundled Control UI assets can return 404 Not Found for global installs when argv1 points at a symlinked wrapper or when auto-detected package-store layouts expose bundled files through hardlinks.
Why it matters: global installs can ship a valid dashboard but still fail at GET /, while the previous package-root heuristic also widened the file-read boundary for configured roots.
What changed: make Control UI root discovery symlink-aware, classify auto-detected package-proven roots as bundled, and allow hardlinks only for those bundled roots.
What did NOT change (scope boundary): explicit gateway.controlUi.root overrides still stay on the strict hardlink boundary and continue to reject hardlinked assets.

Change Type (select all)

Scope (select all touched areas)

Linked Issue/PR

Closes [Bug]: Global installation via Bun results in 404 Not Found on native Dashboard URL (Port 18789) #39693
Related v2026.3.7 dashboard returns plain-text Not Found after upgrade #39621
Related gateway: fix global Control UI 404s for symlinked wrappers and pnpm hardlinks #39856 (closed dirty; this PR recreates only the intended Control UI fix on a clean branch)

User-visible / Behavior Changes

Auto-detected global/package installs can serve the bundled Control UI again when the executable is reached through a symlinked wrapper or when bundled files are hardlinked in a package-store layout.
Explicit gateway.controlUi.root overrides remain strict and still reject hardlinked assets.

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:

Repro + Verification

Environment

OS: macOS
Runtime/container: Node 22 + pnpm
Model/provider: N/A
Integration/channel (if any): Gateway Control UI HTTP handler
Relevant config (redacted): default auto-root plus explicit gateway.controlUi.root fixtures

Steps

Point Control UI discovery at a symlinked global wrapper or an auto-detected package root whose bundled files are hardlinked.
Request GET / or a bundled asset.
Repeat with an explicit gateway.controlUi.root fixture that points at a hardlinked package-store Control UI root.

Expected

Auto-detected bundled roots serve the dashboard and bundled assets.
Explicit configured roots still reject hardlinked assets.

Actual

Verified by focused regression tests below.

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: symlinked-wrapper asset discovery, bundled-vs-resolved hardlink handling, explicit configured-root rejection.
Edge cases checked: hardlinked index.html, hardlinked bundled assets, non-package fallback roots, SPA fallback under bundled roots.
What you did not verify: full repo-wide gates on this clean branch.

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? (Yes)
Config/env changes? (No)
Migration needed? (No)
If yes, exact upgrade steps:

Failure Recovery (if this breaks)

How to disable/revert this change quickly: revert this PR or keep using an explicit custom Control UI root with non-hardlinked assets.
Files/config to restore: src/infra/control-ui-assets.ts, src/gateway/server.impl.ts, src/gateway/control-ui.ts
Known bad symptoms reviewers should watch for: bundled global installs still returning 404, or configured custom roots unexpectedly serving hardlinked files.

Risks and Mitigations

Risk: auto-detected bundled roots could be misclassified if package provenance logic is too loose.
- Mitigation: root classification is package-proven only and has dedicated regression tests for package and fallback roots.

@velvet-shark

…nks @velvet-shark

greptile-apps · 2026-03-09T00:31:36Z

Greptile Summary

This PR fixes Control UI 404 Not Found errors for global installs by making root discovery symlink-aware and introducing a "bundled" root classification that permits hardlinked assets for package-proven (auto-detected) installs, while keeping explicit gateway.controlUi.root overrides on the strict hardlink-rejection boundary.

Key changes:

resolveControlUiDistIndexPath and resolveControlUiRootSync now call realpathSync on argv1 so symlinked global wrappers (e.g., Bun, pnpm shims) correctly resolve to the package's dist/control-ui directory.
New isPackageProvenControlUiRootSync utility classifies a resolved root as "package-proven" by comparing it (via realpathSync) to the package root's dist/control-ui.
New "bundled" discriminant on ControlUiRootState; server.impl.ts pre-computes this at startup so no per-request filesystem cost is incurred in production.
resolveSafeControlUiFile now accepts rejectHardlinks and passes it through to openBoundaryFileSync, enabling hardlinks only for bundled roots.
Explicit controlUiRootOverride paths continue to receive kind: "resolved" and always reject hardlinks — the security boundary is intact.
Test coverage is thorough: symlinked-wrapper discovery, bundled vs. resolved hardlink handling, configured-root rejection, and package-proven vs. fallback root classification are all exercised.

Confidence Score: 5/5

Safe to merge. Security boundary for explicit root overrides is maintained; hardlinks are rejected for configured roots and allowed only for package-proven auto-detected roots.
The PR correctly fixes the 404 errors for symlinked global wrappers and bundled installs while maintaining the strict hardlink-rejection boundary for explicitly configured Control UI roots. The symlink resolution uses realpathSync appropriately, the bundled vs. resolved classification is sound, and production performance is optimized through pre-computation at startup. Test coverage is comprehensive and exercises the key scenarios.
No files require special attention.

_{Last reviewed commit: d025bea}

@velvet-shark

…anks @velvet-shark

velvet-shark · 2026-03-09T00:51:42Z

Merged via squash.

Prepared head SHA: 567b3ed68434220bb319a940fa1b834a2f520ff5
Merge commit: 4f42c03a49e18fdecc4a433a68dc95e12ff058c3

Thanks @velvet-shark!

@velvet-shark

…d package roots (openclaw#40385) Merged via squash. Prepared head SHA: 567b3ed Co-authored-by: velvet-shark <[email protected]> Co-authored-by: velvet-shark <[email protected]> Reviewed-by: @velvet-shark

@velvet-shark

…d package roots (#40385) Merged via squash. Prepared head SHA: 567b3ed Co-authored-by: velvet-shark <[email protected]> Co-authored-by: velvet-shark <[email protected]> Reviewed-by: @velvet-shark

@velvet-shark

…d package roots (openclaw#40385) Merged via squash. Prepared head SHA: 567b3ed Co-authored-by: velvet-shark <[email protected]> Co-authored-by: velvet-shark <[email protected]> Reviewed-by: @velvet-shark

@velvet-shark

…d package roots (openclaw#40385) Merged via squash. Prepared head SHA: 567b3ed Co-authored-by: velvet-shark <[email protected]> Co-authored-by: velvet-shark <[email protected]> Reviewed-by: @velvet-shark

@velvet-shark

…d package roots (openclaw#40385) Merged via squash. Prepared head SHA: 567b3ed Co-authored-by: velvet-shark <[email protected]> Co-authored-by: velvet-shark <[email protected]> Reviewed-by: @velvet-shark

@velvet-shark

…d package roots (openclaw#40385) Merged via squash. Prepared head SHA: 567b3ed Co-authored-by: velvet-shark <[email protected]> Co-authored-by: velvet-shark <[email protected]> Reviewed-by: @velvet-shark

@velvet-shark

…d package roots (openclaw#40385) Merged via squash. Prepared head SHA: 567b3ed Co-authored-by: velvet-shark <[email protected]> Co-authored-by: velvet-shark <[email protected]> Reviewed-by: @velvet-shark

@velvet-shark

…d package roots (openclaw#40385) Merged via squash. Prepared head SHA: 567b3ed Co-authored-by: velvet-shark <[email protected]> Co-authored-by: velvet-shark <[email protected]> Reviewed-by: @velvet-shark

openclaw-barnacle bot added app: web-ui App: web-ui gateway Gateway runtime size: M maintainer Maintainer-authored PR labels Mar 9, 2026

velvet-shark mentioned this pull request Mar 9, 2026

gateway: fix global Control UI 404s for symlinked wrappers and pnpm hardlinks #39856

Closed

fix(gateway): fix bundled control-ui global install 404s (#40385) tha…

4da82e9

…nks @velvet-shark

chore(format): normalize daemon lifecycle test formatting (#40385) th…

567b3ed

…anks @velvet-shark

velvet-shark force-pushed the codex/pr-39856-clean branch from d025bea to 567b3ed Compare March 9, 2026 00:37

openclaw-barnacle bot added the cli CLI command changes label Mar 9, 2026

velvet-shark self-assigned this Mar 9, 2026

velvet-shark merged commit 4f42c03 into main Mar 9, 2026
29 of 30 checks passed

velvet-shark deleted the codex/pr-39856-clean branch March 9, 2026 00:50

github-actions bot mentioned this pull request Mar 9, 2026

📡 Upstream Digest — 2026-03-09 01:21 UTC curtismercier/openclaw-mods#217

Open

scoootscooob mentioned this pull request Mar 9, 2026

[Bug]: [Windows + pnpm] Gateway dashboard returns 404 after upgrading from 2026.3.2 to 2026.3.7 #40551

Open

github-actions bot mentioned this pull request Mar 9, 2026

上游更新: v2026.3.8 — 4 P0 + 48 P1 待合并 jiulingyun/openclaw-cn#488

Open

lzc8568 mentioned this pull request Mar 10, 2026

Cron isolated session not executing in v2026.3.8 #41798

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

gateway: fix global Control UI 404s for symlinked wrappers and bundled package roots#40385

gateway: fix global Control UI 404s for symlinked wrappers and bundled package roots#40385
velvet-shark merged 2 commits intomainfrom
codex/pr-39856-clean

velvet-shark commented Mar 9, 2026

Uh oh!

greptile-apps bot commented Mar 9, 2026

Uh oh!

Uh oh!

velvet-shark commented Mar 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant