Define the Companion and Gateway lifecycle contract

[xlinush]

Context

The OpenClaw Companion and Gateway are separate Windows components with different distribution models:

• Companion is delivered through the Microsoft Store.
• Gateway is delivered as an independently signed, non-Store MSIX.
• Companion may optionally acquire and install Gateway.
• Gateway installation may also provide the canonical native-Windows OpenClaw CLI.
• Existing npm or other native installations may already own the CLI and share state under ~\.openclaw.

Before the Gateway MSIX can move beyond preview use, we need a written and tested lifecycle contract defining how these components interact. Without that contract, installation, updates, rollback, removal, and shared-state handling can conflict or leave users with an unsupported configuration.

Decisions required

Acquisition and installation

• [MSIX Storage] Decide where to host Gateway MSIX artifacts #6
• Define how Companion discovers, obtains, and installs the independently signed Gateway MSIX.
• Specify user-consent behavior and the supported Windows deployment API or App Installer flow.
• Confirm with Partner Center that a Store app may download and initiate installation of a separate non-Store executable package.
• Define behavior when Gateway is already installed independently.

Identity, trust, and version discovery

• Define the stable publisher and package identity.
• Define trusted signing and certificate rotation or renewal behavior.
• Define how Companion discovers available Gateway versions and verifies the update source.
• Define compatibility rules between Companion, Gateway, and the OpenClaw CLI payload.

Updates, repair, and rollback

• Decide whether Companion owns Gateway updates.
• Decide whether openclaw update participates or a generic Gateway update provider is needed.
• Define upgrade, repair, rollback, and recovery behavior.
• Define which component detects and stops a running Gateway before an update.
• Define which component restarts Gateway after a successful update or rollback.
• Ensure package repair or reset cannot unsafely terminate Gateway or delete shared user state.

Uninstall and shared state

• Define which component owns shared state under ~\.openclaw.
• Document what remains after Companion is removed.
• Document what remains after the Gateway MSIX is removed.
• Define user-consent and safety requirements for deleting Gateway payload or shared state.
• Define behavior when npm or another native OpenClaw installation remains on the device.

Companion integration

• Integrate Companion with this MSIX for native Windows Gateway installation where appropriate instead of WSL or npm.
• Surface installation, update, repair, and failure states clearly in Companion.
• Define telemetry and diagnostics ownership across the two components.

Acceptance criteria

• A reviewed lifecycle contract documents ownership for acquisition, installation, updates, repair, rollback, shutdown, restart, uninstall, and shared state.
• Partner Center or Store-policy feasibility is confirmed for the selected installation flow.
• The contract covers independently installed Gateway and existing npm/native installations.
• Automated or documented end-to-end tests cover install, update, rollback, repair, and uninstall while Gateway is running.
• Tests verify state preservation and cleanup when either Companion or Gateway is removed.
• Companion integration follows the approved contract and reports actionable errors for failed lifecycle operations.
• Production signing and acquisition remain disabled until the lifecycle contract is approved and validated.

Tracked separately from the umbrella packaging discussion in #1.

Source review comments

• Maintainer architecture review and lifecycle requirements
• Clarified Companion/Store and separate Gateway MSIX architecture
• Artifact hosting, update ownership, and Companion integration follow-ups

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed September 8, 2026, 6:27 PM ET / 22:27 UTC.

Summary
Keep open: current main covers launcher safeguards, but the cross-component lifecycle contract remains unresolved. GitHub Releases is now confirmed, and the existing PRD provides a concrete starting point. This collaborator-authored request still warrants maintainer attention.

Reproducibility: not applicable. this requests an approved lifecycle capability and ownership contract, rather than reporting a reproducible defect in established behavior.

Root-cause cluster
Relationship: canonical
Canonical: #5
Summary: This remains the lifecycle contract tracker; related packaging work supplies inputs rather than replacing it.

Members:

• partial_overlap: Outstanding initial MSIX packaging discussion #1 - The closed umbrella explicitly delegates Companion lifecycle ownership to this issue.
• partial_overlap: [MSIX Storage] Decide where to host Gateway MSIX artifacts #6 - The closed hosting decision resolves the download channel while leaving orchestration here.
• adjacent_distinct: Investigate immutable packaged OpenClaw payload architecture #10 - Payload location and execution identity constrain lifecycle design but are separately scoped.
• partial_overlap: Add selective clawctl and require device-installed Node.js #12 - Merged launcher safeguards address only part of lifecycle safety.
• adjacent_distinct: feat: execute packaged OpenClaw directly #15 - The open immutable-payload proposal excludes cross-user deployment ownership and does not implement Companion lifecycle orchestration.

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 the existing PRD assign Gateway acquisition and servicing to Companion, with explicit standalone-install and shared-state rules?	Review the PRD as the lifecycle contract: Use the existing PRD to approve an ownership matrix and validation criteria before enabling production acquisition.

Why: The architecture discussion favors Companion ownership, but deployment authority, Store feasibility, and shared-state consent require cross-component approval.

Next step
Bring the existing PRD and Store feasibility evidence into the assigned-owner discussion; cross-component authority and product choices preclude an autonomous repair PR.

Security
Needs attention: Deployment authority and shared-state consent require approval; no concrete vulnerability is established by this issue.

Review details

Best possible solution:

Approve one PRD-backed ownership contract with consent, coexistence, state preservation, and visible Companion recovery controls, then validate fresh installation and lifecycle transitions on both architectures.

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

Not applicable: this requests an approved lifecycle capability and ownership contract, rather than reporting a reproducible defect in established behavior.

Is this the best way to solve the issue?

Yes: reviewing the existing PRD against current launcher behavior and the architecture guidance is the narrowest coherent path; the final ownership choices remain human decisions.

AGENTS.md: not found in the target repository.

Remaining risk / open question:

• The PRD's approved scope, Store-policy feasibility, and final ownership of updates, rollback, restart, and shared-state deletion remain unverified.
• The workflow supports official signing, but repository source does not establish whether operational approval gates prevent production use before lifecycle validation.

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

Label changes

Label justifications:

• P2: This is a concrete preview-to-production lifecycle design dependency, without an established current-user outage.
• impact:security: The contract determines trusted package acquisition, deployment authority, signing trust, and consent for shared-state deletion.

Evidence reviewed

Security concerns:

• [medium] Approve acquisition and destructive-operation authority
  The contract must identify who may install, update, remove, or delete shared state when Companion, standalone Gateway, and another native installation coexist.
  Confidence: 0.95

What I checked:

• Current implementation covers only part of the contract: README documents manual preparation, launch-time readiness checks, process lifetime ownership, and retained profile directories after package removal. It does not establish Companion acquisition, servicing orchestration, or shared-state deletion consent. (README.md:69, b3984af1c7a6)
• Running-payload safeguards: Program holds a payload lease while GatewayLauncher runs; PayloadStager acquires a mutation lease before replacement. The inspected lock tests cover launch/mutation exclusion. These safeguards do not choose who orchestrates package updates and restarts. (src/OpenClaw.Launcher/Program.cs:125, b3984af1c7a6)
• Existing PRD and assigned owner: The issue is assigned to xlinush. MythiliMur identifies an existing PRD by Samantha Song: Define the Companion and Gateway lifecycle contract #5 (comment). Its contents were not supplied, so approval and coverage are not established.
• Hosting decision is resolved: The latest human update confirms GitHub Releases remains planned; release maintainers would handle any subsequent Microsoft Store duplication. The closed hosting issue explicitly leaves Companion acquisition and update orchestration here: [MSIX Storage] Decide where to host Gateway MSIX artifacts #6.
• Original cross-component architecture guidance: The architecture review recommends Companion ownership of package lifecycle and explicitly requires consent, Store-policy confirmation, coexistence, stop/restart, and state ownership decisions: feat: add OpenClaw Gateway MSIX packaging openclaw-windows-node#1186 (comment). This establishes the Companion integration boundary, without proving that the contract is implemented.
• Related implementations do not supersede the contract: Merged Add selective clawctl and require device-installed Node.js #12 supplies launcher preparation and process safeguards. Open feat: execute packaged OpenClaw directly #15 addresses immutable application placement and explicitly excludes cross-user deployment ownership. Neither completes the requested lifecycle contract. (b3984af1c7a6)

Likely related people:

• xlinush: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• Samantha Song: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• MythiliMur: 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.