Define coexistence behavior for MSIX and other OpenClaw installations

[xlinush]

Context

The Gateway MSIX may install the native Windows openclaw.exe app execution alias while OpenClaw may already be installed through npm or another distribution channel.

Those installations can live on the same device, expose commands with the same name, and use shared state under ~\.openclaw. The supported behavior for that configuration has not been defined or validated.

Unresolved questions

• Is side-by-side installation supported?
• Which installation owns the openclaw command in each supported shell and automation context?
• How should users understand which installation is being executed?
• What happens when installations provide different OpenClaw versions?
• Which installation owns updates, repair, rollback, and uninstall behavior?
• How is shared configuration and user state under ~\.openclaw handled?
• What remains usable when one installation is upgraded or removed?
• What compatibility and migration guarantees are required across installation channels?

Completion criteria

• The supported coexistence contract is documented for MSIX, npm, and other applicable installation channels.
• Command resolution and ownership are documented for PowerShell, Command Prompt, and relevant automation contexts.
• Version, update, repair, rollback, uninstall, and shared-state behavior are defined.
• The documented contract is validated on Windows with representative side-by-side installations.

Tracked separately from the umbrella packaging discussion in #1.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed September 4, 2026, 3:01 AM ET / 07:01 UTC.

Summary
Keep open: main documents the MSIX lifecycle, but command precedence, mixed-version compatibility, and cross-channel state ownership remain undefined. The closed umbrella discussion explicitly delegates this work here, and the collaborator-authored issue requires a product decision.

Reproducibility: not applicable. this requests a support contract and Windows validation, rather than reporting a specific failure against an established contract.

Root-cause cluster
Relationship: canonical
Canonical: #7
Summary: This is the focused coexistence contract explicitly separated from the closed packaging umbrella.

Members:

• partial_overlap: Outstanding initial MSIX packaging discussion #1 - The closed umbrella records package lifecycle observations but explicitly delegates unresolved cross-channel coexistence here.
• adjacent_distinct: fix: clean up standalone MSIX launcher #2 - The merged launcher cleanup addresses forwarding and repair behavior without resolving the coexistence contract.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.

Maintainer decision needed

Question	Recommendation
Should MSIX and npm coexist through explicit installation selection, offer transparent shared-state compatibility, or require migration to one active distribution?	Define constrained coexistence first: Specify explicit installation selection and channel-owned lifecycle, withholding mixed-version shared-state guarantees until Windows validation supports them.

Why: Current source defines package-local behavior but cannot determine which cross-channel compatibility guarantees the product should support.

Next step
Choose the supported coexistence model before scoping documentation and Windows validation; an automated repair would otherwise invent product policy.

Review details

Best possible solution:

Establish a Windows-validated contract that makes the selected installation visible, preserves existing user state, and assigns update, repair, rollback, and uninstall ownership per channel.

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

Not applicable: this requests a support contract and Windows validation, rather than reporting a specific failure against an established contract.

Is this the best way to solve the issue?

Unclear until the support model is chosen; documenting and validating existing behavior is the narrowest starting point, with detection or migration changes only where that contract requires them.

AGENTS.md: not found in the target repository.

Remaining risk / open question:

• Actual command selection across PowerShell, Command Prompt, and automation remains unvalidated for representative side-by-side installations.
• Compatibility guarantees for different versions sharing configuration, and ownership of cross-channel repair or uninstall effects, remain undecided.

Codex review notes: model internal, reasoning high; reviewed against b621eacd0e55.

Label changes

Label justifications:

• P2: This is a concrete Windows installation-contract improvement without a demonstrated current user blocker or regression.
• impact:other: The primary impact is ambiguous command and installation lifecycle ownership across distribution channels.

Evidence reviewed

What I checked:

• Current default-branch baseline: HEAD matches the supplied fetched main revision; local main and origin/main contain it. Initial and final working-tree status checks were clean. (b621eacd0e55)
• Canonical command alias is registered: The package declares the OpenClaw.Gateway identity and registers openclaw.exe. This establishes the command-name overlap described by the issue, without defining precedence over another installation. (src/OpenClaw.Gateway.Launcher/Package.appxmanifest:49, b621eacd0e55)
• Separate payload location: The launcher stages its payload under the user's .openclaw-msix/app directory. HostOptions preserves all CLI arguments and does not select between installed distribution channels. (src/OpenClaw.Gateway.Launcher/HostOptions.cs:29, b621eacd0e55)
• Existing lifecycle documentation is partial: README documents .openclaw as configuration/user state and says MSIX update or removal neither deletes those directories nor stops a running Gateway. Its full text does not define side-by-side shell resolution, mixed-version compatibility, or cross-channel lifecycle ownership. (README.md:95, b621eacd0e55)
• Packaging and upstream runtime boundary: GatewayLauncher executes the staged openclaw.mjs through Node, forwards arguments, and supplies external-supervisor/no-auto-update environment settings. README explicitly assigns enforcement of those settings to upstream OpenClaw; setting them alone does not establish cross-channel compatibility. (src/OpenClaw.Gateway.Launcher/GatewayLauncher.cs:63, b621eacd0e55)
• Existing tests cover package-local replacement: The inspected tests establish same-directory payload replacement and interrupted-promotion recovery using temporary fixtures. They do not establish shell precedence or compatibility with an npm installation sharing user state. (tests/OpenClaw.Gateway.Launcher.Tests/PayloadStagerTests.cs:195, b621eacd0e55)

Likely related people:

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

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.