feat: add experimental Wayland desktop env

[steipete]

Summary:

• Add a generic experimental Wayland desktop environment option behind desktop_env=wayland / --desktop-env wayland.
• Bootstrap Sway + WayVNC desktops for brokered Linux and local-container leases, with desktop.env discovery for screenshots, browser launch, WebVNC reset, terminal, and keyboard input helpers.
• Keep XFCE as the default and reject unsupported Wayland video/proof capture paths with explicit errors.

Validation:

• go test ./internal/cli ./internal/providers/localcontainer
• npm test --prefix worker -- bootstrap.test.ts config.test.ts provider-labels.test.ts azure.test.ts
• npm run check --prefix worker
• npm run format:check --prefix worker
• go build -trimpath -o bin/crabbox ./cmd/crabbox
• Manual AWS lease smoke: Sway top bar present, Chrome floating and sized, WebVNC reachable while lease active, grim screenshot works, wtype works in foot. Brokered cold-start proof still requires this Worker change to be deployed.

Review note:

• Autoreview was attempted with Codex tools, Claude tools, and Claude no-tools; each helper subprocess hung before producing a result. No autoreview findings were available to accept or reject.

[clawsweeper]

Codex review: needs real behavior proof before merge.

Latest ClawSweeper review: 2026-05-24 06:03 UTC / May 24, 2026, 2:03 AM ET.

Workflow note: Future ClawSweeper reviews update this same comment in place.

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.

Summary
The PR adds an experimental opt-in Linux Wayland desktop profile across CLI config, brokered/local-container provisioning, desktop helpers, Worker lease config, docs, tests, and changelog.

Reproducibility: not applicable. for the feature request; this is a new opt-in desktop environment, not a bug report. The capability-mismatch findings are source-reproducible from the guarded comparisons in internal/cli/capabilities.go and internal/cli/run.go.

PR rating
Overall: 🦪 silver shellfish
Proof: 🦪 silver shellfish
Patch quality: 🦐 gold shrimp
Summary: The patch is coherent and tested at the source level, but merge confidence is capped by missing runtime proof and the desktop environment mismatch findings.

Rank-up moves:

• Add observable Wayland runtime proof, with private IPs, endpoints, keys, and other sensitive details redacted.
• Fix the XFCE/Wayland capability mismatch checks and add focused regression coverage for missing labels and true mismatches.

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.

Real behavior proof
Needs real behavior proof before merge: The PR body has textual manual smoke testing but no observable after-fix artifact; add a screenshot, recording, terminal output, linked artifact, or redacted log showing the Wayland runtime and update the PR body to trigger re-review.

Mantis proof suggestion
A visible desktop proof would materially help because the PR changes the Linux desktop session, WebVNC display, screenshot, keyboard-input, and video-rejection runtime paths. A maintainer can ask Mantis to capture proof by posting a new PR comment that starts with the OpenClaw Mantis account mention, followed by:

visual task: verify a Linux lease with --desktop --desktop-env wayland shows Sway over WebVNC, captures a grim screenshot, accepts wtype keyboard input, and rejects video capture with the documented error.

Risk before merge

• The PR body reports a manual AWS smoke, but there is still no observable after-fix artifact or output showing Sway, WebVNC, grim screenshots, wtype input, and the unsupported video path.
• Brokered Wayland cold starts require the Worker change to be deployed with the CLI; otherwise the opt-in path can fail at lease capability validation.
• The current capability checks can accept a Wayland lease for an XFCE/default request, which can push users into later runtime failures instead of an immediate environment mismatch.

Maintainer options:

1. Fix compatibility validation and require proof (recommended)
   Repair the XFCE/Wayland mismatch checks, add focused coverage for both missing old labels and true mismatches, then require observable Wayland runtime proof before merge.
2. Accept the experimental deployment risk
   Maintainers may choose to merge after proof while explicitly owning the need to deploy the Worker before brokered Wayland leases work.
3. Pause until the runtime path is proven
   If no real Wayland lease proof is available, leave the PR open or pause it rather than landing an unproven desktop runtime path.

Next step before merge
The remaining blocker is contributor or maintainer runtime proof plus deployment/compatibility review; automation cannot supply proof for the contributor's real Wayland environment.

Security
Cleared: No concrete security or supply-chain regression was confirmed; the new WayVNC path remains loopback-bound and does not add public ingress or new secret handling.

Review findings

• [P2] Reject mismatched managed desktop env labels — internal/cli/capabilities.go:103
• [P2] Reject mismatched coordinator desktop env echoes — internal/cli/run.go:1885

Review details

Best possible solution:

Keep the opt-in Wayland profile, fix the desktop environment compatibility checks, require observable runtime proof, and merge only after maintainers are comfortable with Worker deployment sequencing.

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

Not applicable for the feature request; this is a new opt-in desktop environment, not a bug report. The capability-mismatch findings are source-reproducible from the guarded comparisons in internal/cli/capabilities.go and internal/cli/run.go.

Is this the best way to solve the issue?

Not yet; the overall shape is reasonable because Wayland is explicit and XFCE remains the default, but the mismatch checks and real behavior proof need to be addressed before this is the best mergeable solution.

Label changes:

• add P2: This is a substantive opt-in desktop feature with limited blast radius because XFCE remains the default, but it still affects real lease provisioning paths.
• add merge-risk: 🚨 compatibility: The PR adds a new lease capability/config value whose CLI and Worker deployment order plus environment mismatch handling can affect existing lease reuse semantics.
• add rating: 🦪 silver shellfish: Current PR rating is 🦪 silver shellfish because proof is 🦪 silver shellfish, patch quality is 🦐 gold shrimp, and The patch is coherent and tested at the source level, but merge confidence is capped by missing runtime proof and the desktop environment mismatch findings.
• remove rating: 🦐 gold shrimp: Current PR rating is rating: 🦪 silver shellfish, so this older rating label is no longer current.

Label justifications:

• P2: This is a substantive opt-in desktop feature with limited blast radius because XFCE remains the default, but it still affects real lease provisioning paths.
• merge-risk: 🚨 compatibility: The PR adds a new lease capability/config value whose CLI and Worker deployment order plus environment mismatch handling can affect existing lease reuse semantics.
• rating: 🦪 silver shellfish: Current PR rating is 🦪 silver shellfish because proof is 🦪 silver shellfish, patch quality is 🦐 gold shrimp, and The patch is coherent and tested at the source level, but merge confidence is capped by missing runtime proof and the desktop environment mismatch findings.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The PR body has textual manual smoke testing but no observable after-fix artifact; add a screenshot, recording, terminal output, linked artifact, or redacted log showing the Wayland runtime and update the PR body to trigger re-review.

Full review comments:

• [P2] Reject mismatched managed desktop env labels — internal/cli/capabilities.go:103
  This guard skips validation whenever the request resolves to xfce, so a managed lease labeled desktop_env=wayland is still accepted for an XFCE/default request. That can lead to later X11-only helper failures instead of an immediate capability mismatch; missing old labels already normalize to XFCE, so true mismatches should be rejected.
  Confidence: 0.82
• [P2] Reject mismatched coordinator desktop env echoes — internal/cli/run.go:1885
  The coordinator echo check has the same blind spot: a brokered lease that reports desktopEnv=wayland can satisfy an XFCE/default request. That leaves the CLI believing it has the default desktop while later helper behavior follows the probed Wayland environment, so compare the normalized values or otherwise track explicit default semantics.
  Confidence: 0.8

Overall correctness: patch is incorrect
Overall confidence: 0.82

What I checked:

• Current main desktop baseline: Current main's managed Linux desktop bootstrap still uses Xvfb/XFCE/x11vnc and has no desktopEnv/Wayland capability path, so the central feature is not already implemented on main. (internal/cli/bootstrap.go:594, 46887c69350a)
• PR adds the user-facing option: The PR registers --desktop-env on lease creation flags and carries the value into lease config/options, establishing a new user-facing configuration surface. (internal/cli/lease_flags.go:37, baec269af2dd)
• PR adds brokered Wayland bootstrap: The PR adds Sway/WayVNC cloud-init write files and bootstrap branches for desktopEnv=wayland, including /var/lib/crabbox/desktop.env discovery. (internal/cli/bootstrap.go:892, baec269af2dd)
• PR adds Worker Wayland support: The Worker config now parses desktopEnv and the Worker bootstrap emits Wayland services when requested, so brokered cold starts depend on deploying the Worker change. (worker/src/config.ts:117, baec269af2dd)
• Managed lease mismatch blind spot: The managed lease check skips desktop environment validation whenever the request normalizes to XFCE, so a lease labeled desktop_env=wayland can satisfy an XFCE/default request. (internal/cli/capabilities.go:103, baec269af2dd)
• Coordinator echo mismatch blind spot: The coordinator lease echo check has the same XFCE guard, so a brokered Wayland lease can be accepted for an XFCE/default request instead of failing at capability validation. (internal/cli/run.go:1885, baec269af2dd)

Likely related people:

• steipete: Peter Steinberger authored the recent main commits that introduced and refined the Linux desktop/WebVNC bootstrap and browser theme behavior, and also authored this Wayland PR branch. (role: recent area contributor and proposed feature author; confidence: high; commits: e1f2f9317a65, 52629abc235c, d81682aa; files: internal/cli/bootstrap.go, internal/cli/desktop.go, internal/cli/capabilities.go)

Codex review notes: model gpt-5.5, reasoning high; reviewed against 46887c69350a.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 00bd8cc53c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Enforce XFCE/Wayland match for coordinator leases

Remove the requestedDesktopEnv != desktopEnvXFCE guard so this capability check runs for explicit/default XFCE requests too. As written, a lease provisioned with desktopEnv=wayland is accepted when the client requests XFCE (the default), which lets an environment mismatch slip through and later desktop flows can fail with confusing runtime errors instead of an immediate capability mismatch.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Enforce XFCE/Wayland match for managed lease labels

This guard has the same blind spot as the coordinator path: it skips validation whenever the requested env is XFCE, so a managed lease labeled desktop_env=wayland is still treated as compatible with an XFCE request. Because missing labels already normalize to XFCE, comparing unconditionally would preserve backward compatibility while correctly rejecting true mismatches.

Useful? React with 👍 / 👎.

[clawsweeper]

ClawSweeper PR egg

🎁 Pass real behavior proof to wake the egg and unlock a hatchable treat.

Where did the egg go?

• The egg game starts only after the PR passes the real-behavior proof check.
• Before that, no creature or rarity is rolled. The treat waits for real proof.
• This is still just collectible flavor: proof affects review readiness, not creature quality.