fix(migration): Store migration blocked for Native Gateway users and correction releases

[natalie-aguinaldo]

Related: #1374

What Problem This Solves

Fixes: Store migration refuses to start for users who set up the Native Gateway, and treats stable correction releases such as v2026.9.8-1 as unsupported, so the Store app stays locked behind "Update Required" or a validation failure.

User Impact

User impact: people on a correction release, or with a Native Gateway set up, can now move from the Inno (.exe) app to the Store version and keep their existing gateway connection.

Why This Change Was Made

• Native Gateway draft: Native setup intentionally keeps gateways\native-setup-draft.json after setup. The migration inventory treated it as an unexpected file and refused. It is now recognized by exact name, and checked for consistency during capture so a draft created mid-capture cannot slip through.
• Correction releases: X.Y.Z-N now maps to Version(X,Y,Z,N). The installed source is only accepted when its FileVersion is the base X.Y.Z.0 and its ProductVersion carries the exact release identity (optional +build metadata allowed). Base releases reject a ProductVersion with a correction suffix.
• Matching for draft and temp names is ordinal and case-sensitive. docs/RELEASING.md documents the draft and the correction-version floor.

Evidence

Real migration on a machine that reproduced both bugs: v2026.9.8-1 Inno app with a Native Gateway set up and the draft present. The migration offer appeared, validation succeeded, finalization completed after uninstall, and the Store-identity app reconnected to the same Native Gateway. Screenshots and the redacted log are under Real Behavior Proof.

Change Type

• Bug fix
• Feature
• Refactor
• Docs or instructions
• Tests or validation
• Security hardening
• Chore or infrastructure

Scope

• Tray or WinUI UX
• Windows node capability
• Local MCP or winnode
• Gateway, connection, or pairing
• Setup or onboarding
• Permissions, privacy, or security
• Tests, CI, or docs

Required proof pools

• windows-clean-installer-upgrade: Inno to Store MSIX migration path using a released Inno build as the source.

Validation

• ./build.ps1: passed
• Focused migration tests (OpenClaw.Connection.Tests migration classes): 285/285 passed
• dotnet test ./tests/OpenClaw.Shared.Tests/OpenClaw.Shared.Tests.csproj --no-restore: 4,262 passed, 35 skipped, 0 failed
• dotnet test ./tests/OpenClaw.Tray.Tests/OpenClaw.Tray.Tests.csproj --no-restore: 3,996 passed, 0 failed
• git diff --check: clean
• Hanselman dual-model review (Opus 5.5 + GPT-6 Astra), two delta rounds: all findings fixed, final round clean on both models.

New tests cover: correction parsing and the version floor; FileVersion/ProductVersion provenance (matching, mismatched, missing, malformed, base vs correction); draft accepted as a file, rejected as a directory or reparse point, and a draft appearing mid-capture; case-variant and malformed draft/temp names.

Real Behavior Proof

• Environment tested: Windows 11 VM, Inno OpenClaw Companion 2026.9.8-1 (DisplayVersion 2026.9.8-1, FileVersion 2026.9.8.0, ProductVersion 2026.9.8-1+2ba89f37...) with the Native Gateway set up on ws://127.0.0.1:63360 and native-setup-draft.json present. Target: production-identity migration-test MSIX (OpenClawFoundation.OpenClaw 2026.9.5.0, test-signed) built from this branch.
• PR head or commit tested: 92f47c6e
• Exact steps or command run:
  1. Removed the previously installed Store build (newer version blocked the test package) and confirmed no migration receipt.
  2. Add-AppxPackage -Path OpenClaw-MigrationTest-x64.msix -ForceApplicationShutdown, launched OpenClaw from Start.
  3. Chose Migrate, uninstalled OpenClaw Companion from Installed apps, chose Retry.
• Evidence before fix:

Correction release v2026.9.8-1 installed, but the Store version told the user to update it to a supported version:

[17:45:54] Store migration startup admission: UpdateInno (receipt: False, source payload: True).
[17:46:52] Store migration startup admission: UpdateInno (receipt: False, source payload: True).

Native Gateway user: migration refused because the inventory rejected the retained gateways\native-setup-draft.json (expected a directory, found a file):

• Evidence after fix:

Migration offer (previously Update Required / validation failure):

Validation succeeded with the draft present:

Uninstalling the previous Inno app:

Store-identity app connected to the same Native Gateway after migration:

Post-migration state (draft kept, receipt cleared by finalization, test package installed, no Inno uninstall entry):

Redacted tray log:

[17:36:02] Store migration startup admission: ConsentRequired (receipt: False, source payload: False).
[17:36:16] Store migration preparation completed: [REDACTED_ID].
[17:36:16] Store migration completion recorded: [REDACTED_ID].
[17:37:16] Store migration startup admission: FinalizationRequired (receipt: True, source payload: False).
[17:37:16] Store migration finalized: [REDACTED_ID].

• Observed result: full migration succeeded. Finalization re-captures the inventory and compares it to the receipt, so the draft passed both validation and finalization.
• Screenshot or artifact links verified? Yes
• Not verified or blocked: not run with a Store-signed package. The proof used a test-signed MSIX with the production identity, since a Dev identity cannot exercise migration.

Security Impact

• New permissions or capabilities? No
• Secrets or tokens handling changed? No
• New or changed network calls? No
• Command or tool execution surface changed? No
• Data access scope changed? No
• If any answer is Yes, explain the risk and mitigation: N/A

Compatibility and Migration

• Backward compatible? Yes
• Config or environment changes? No
• Migration needed? No
• If yes, list the exact upgrade steps: N/A

Review Conversations

• I replied to or resolved every bot review conversation addressed by this PR.
• I left unresolved only conversations that still need maintainer judgment.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed October 7, 2026, 8:56 PM ET / October 8, 2026, 00:56 UTC (Revision 2).

ClawSweeper review

What this changes

The branch allows Store migration from stable correction releases and includes the retained Native Gateway setup draft in migration validation.

Example: A user migrates Companion v2026.9.8-1 with a Native Gateway configured

• Before: The Store app requests an update or refuses validation because native-setup-draft.json is treated as a directory.
• After: Migration validates successfully, completes after uninstall, and preserves the existing Native Gateway connection.

Product

Kind: Bug fix · Worth it: Yes · Fix scope: Complete
User problem: Users with the latest correction release or a configured Native Gateway cannot complete the switch to the Store app.
Reason: The existing migration contract preserves saved gateway state and accepts supported releases. This patch repairs two demonstrated refusals without introducing another workflow or configuration choice.

Merge readiness

✅ Ready for maintainer review

This PR remains necessary: current main still rejects correction releases and the retained Native Gateway draft. The focused repair has sufficient current-head Windows migration proof, and no concrete blocking defect was found.

Priority: P0
Reviewed head: 92f47c6e6345abc9c4821c1f9324c73d6b0f4c62

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A useful, focused repair with real packaged migration proof, compatibility coverage, and no confirmed blocking finding.
Proof confidence	🦞 diamond lobster (5/6)	Sufficient (logs): At head 92f47c6, the Windows 11 production-identity MSIX exercised the changed installation detector and inventory against released v2026.9.8-1 with the retained native draft. Inspected screenshots show admission and validation succeeding; copied runtime logs show completion and finalization after uninstall. Existing-state compatibility is sufficient: state remains in place, stored schemas are unchanged, and fresh finalization fingerprint checks remain enforced. Actual Store signing remains an established release-time gate.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Before merge

None.

Findings

None.

Agent review details

How this fits together

The Store migration flow checks the previous installer-based Companion and its saved state before allowing the Store app to start. It preserves settings and gateway connections in place, then verifies removal of the previous app before finalizing.

flowchart TD
  A[Previous Companion installation] --> C[Release and executable checks]
  B[Saved settings and Gateway draft] --> D[State inventory]
  C --> E[Migration validation]
  D --> E
  E --> F[User removes previous app]
  F --> G[Recheck state and finalize]
  G --> H[Store app uses preserved connection]

Loading

Technical review

Best possible solution:

Keep the existing user-directed migration flow and land this narrow eligibility and inventory repair, preserving the established release-time signing gates.

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

Yes. Current-main source proves both refusal paths, and the supplied Windows screenshots show the failures; this read-only review did not execute a reproduction.

Is this the best way to solve the issue?

Yes. The repair recognizes the repository's existing correction-release format and setup descriptor while retaining exact executable checks, inventory locking, and finalization validation.

AGENTS.md: found and applied where relevant.

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

Provenance checked

• src/OpenClaw.Connection/Migration/MigrationVersionPolicy.cs changes intended behavior with a stated reason (5a59535: Strict stable-version admission prevents unsupported sources from authorizing migration and uninstall.)
• src/OpenClaw.Connection/Migration/InnoInstallationDetector.cs keeps the original intent (5a59535: Require exact supported installation and executable evidence before admitting migration.)
• src/OpenClaw.Connection/Migration/MigrationInventory.cs keeps the original intent (5a59535: Capture bounded, stable source state and fail closed on unexpected or unsafe filesystem entries.)
• src/OpenClaw.SetupEngine/NativeGatewaySetupService.cs keeps the original intent (dba8121: Retain a native setup descriptor for resumable onboarding and recovery.)
• docs/RELEASING.md keeps the original intent (244f684: Document exact source eligibility and coordinated release acceptance requirements.)

Testing

Proof path: shipped entry point. Added test files: 4.

Security

None.

Evidence

What I checked:

• Current main still needs the repair: Current main accepts only numeric release versions; its gateway inventory still treats every child as an identity directory. The released v2026.9.8-1 tree is also the verified introduction baseline, so these fixes are not already shipped. (src/OpenClaw.Connection/Migration/MigrationVersionPolicy.cs:10, 037c17dcb581)
• Exact introduced changes: Read all ten introduced file diffs. Correction admission requires the matching ProductVersion and base FileVersion; draft inventory retains bounded JSON reads, hashes, file locks, reparse rejection, and capture-time consistency checks. (src/OpenClaw.Connection/Migration/MigrationVersionPolicy.cs:22, 92f47c6e6345)
• Windows behavior and upgrade proof: Inspected all four prepared screenshots: correction-release refusal, native-draft failure, migration offer, and successful validation. The complete PR body identifies head 92f47c6 and a Windows 11 migration from released v2026.9.8-1 to a test-signed production-identity MSIX. Copied runtime output records preparation, completion, and finalization, with the same Native Gateway connection reported afterward. Source identity: b6e8fc8a4c5b602848102906ae1dc164be08a8b58db31485d2122806126990dd. Three additional attachment fetches returned browser cache misses; that reviewer limitation does not negate the inspected screenshots and copied runtime evidence. (92f47c6e6345)
• Existing-state compatibility: No settings, credential, or receipt schema is replaced. Draft-free inventories retain their prior entries; a draft could not previously complete migration. Finalization still recaptures the inventory and compares its fingerprint before applying startup preference and clearing the receipt. (src/OpenClaw.Connection/Migration/StoreMigrationFinalizationCoordinator.cs:460, 92f47c6e6345)
• Prior migration intent and ownership: feat(migration): gate Inno-to-Store migration preview and preserve the gateway on uninstall #1461 established strict same-user inventory and source admission; feat(migration): ship the Inno-to-Store migration #1519 shipped the user-directed migration flow. Their bodies and relevant discussion support preserving these safeguards. Main history records Natalie Aguinaldo on both merged migration changes. (src/OpenClaw.Connection/Migration/InnoInstallationDetector.cs:100, 244f684ef291)
• Native draft purpose: The architecture ledger defines the draft as a credential-free recovery descriptor. Existing setup writes it through the atomic-file owner, whose temporary naming pattern matches the narrowly accepted temporary siblings. History connects this path to feat(setup): guide native Gateway installation and onboarding #1447. (src/OpenClaw.SetupEngine/NativeGatewaySetupService.cs:83, dba81213371c)

Likely related people:

• Natalie Aguinaldo: Raw commit 244f684 adds src/OpenClaw.Connection/Migration/InnoInstallationDetector.cs:100 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: 244f684ef291; files: src/OpenClaw.Connection/Migration/InnoInstallationDetector.cs)
• Karen: Raw commit dba8121 adds src/OpenClaw.SetupEngine/NativeGatewaySetupService.cs:68 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: dba81213371c; files: src/OpenClaw.SetupEngine/NativeGatewaySetupService.cs)

Review metrics

Metric	Value	Why it matters
Net code growth	production +151 lines; tests +236 lines	Production growth implements strict correction-version validation and bounded draft admission, with focused negative and compatibility coverage.

Labels

Label changes:

• add P0: The demonstrated Store onboarding path blocks users already on the latest correction release or directs Native Gateway users to inspect logs, without an effective in-product recovery.
• remove P1: Current review triage priority is P0, so this older priority label is no longer current.

Label justifications:

• P0: The demonstrated Store onboarding path blocks users already on the latest correction release or directs Native Gateway users to inspect logs, without an effective in-product recovery.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR.
• proof: sufficient: Contributor real behavior proof is sufficient.

Rating scale

6/6 🦀 challenger crab · 5/6 🦞 diamond lobster · 4/6 🐚 platinum hermit · 3/6 🦐 gold shrimp · 2/6 🦪 silver shellfish · 1/6 🧂 unranked krab. Overall follows the weaker of proof and patch quality; ✨ marks media proof (a screenshot, video, or linked artifact) that directly shows the changed behavior.

Workflow

ClawSweeper edits this one comment on every review. Comment @clawsweeper re-review for a fresh review only; repair and merge need explicit maintainer commands such as @clawsweeper autofix or @clawsweeper automerge.

History

Review history (1 earlier review cycle)

• reviewed 2026-10-08T00:45:54.624Z sha 92f47c6 :: needs maintainer review before merge. :: none

[karkarl]

Global triage: HOLD_FOR_AUTHOR. Take confidence 10%; recommendation confidence 99%; effort medium; risk high.

Reviewed exact head 92f47c6e6345. GitHub currently reports BLOCKED with 26 passing, 2 failing, and 0 pending checks. proof label is sufficient. Durable automated signal: Codex review: needs maintainer review before merge..

Author: update from current main, resolve conflicts or branch-policy blockers, then rerun exact-head validation and request review.

This is a triage classification, not a merge action. No branch changes were made.