feat: update Companion-owned Gateway safely in place

[TheAngryPit]

Closes #901

Credit to @iamalin for originating and detailing the lock-step Gateway proposal in #901. This implementation preserves that direction and extends it with a recoverable in-place update transaction.

Thanks to @shanselman for identifying that routine full-VHD rollback would not scale for long-lived Gateways. The revised design keeps VHD protection explicit and uses OpenClaw's native verified backup for routine updates.

Stacked Dependency

This PR remains stacked conceptually on #999, which owns the package lifecycle, reload-schema, LKG, and setup/reconnect contracts consumed here. This PR adds the in-place update, protection, recovery, retention, and synchronization transaction.

After #999 lands, this branch should be rebased once onto main; the resulting diff should contain only the #901-specific update path. The current proof is intentionally frozen at this PR head rather than chasing unrelated upstream drift.

Problem

The Windows Companion can update while its Companion-owned WSL Gateway remains on the version installed during onboarding. This leaves the Tray, Windows node, and Gateway on a runtime combination that the installed Companion was not built or tested against.

The update must preserve the existing distro, agents, configuration, memory, channels, node identity, and ownership. It also needs a bounded rollback path that does not require routine full-distro exports on ordinary user machines.

Changed Behavior

• Detects a Gateway version mismatch and offers an explicit in-place alignment operation.
• Uses openclaw backup create --verify --json for routine protection.
• Binds the host copy to the SHA-256 and byte size calculated inside WSL after native verification.
• Uses a unique owner-checked 0700 staging directory and rejects symlink or ownership substitution.
• Keeps Full VHD protection as an explicit compatibility or operator-selected path with capacity preflight.
• Persists private idempotent receipts for update, recovery, rollback, and retention.
• Binds Core completion to the Gateway identity recorded by the accepted transaction.
• Resynchronizes the same Companion-owned Gateway and Windows node after update or recovery.
• Defaults retention to one previous version plus seven days; users can retain one, two, or all previous points.
• Preserves unresolved receipts and protection points instead of cleaning up ambiguous state.

User Impact

Users can align the Gateway owned by their installed Companion without recreating the distro or rerunning onboarding. Routine updates use a compact native backup rather than a full VHD export, while explicit VHD protection remains available where byte-for-byte rollback is required.

Any malformed receipt, identity mismatch, digest mismatch, insufficient VHD capacity, ambiguous installer outcome, or replacement Gateway record fails closed before the transaction is completed.

Non-Goals

• no npm latest chasing;
• no unattended update;
• no onboarding rerun or routine distro recreation;
• no remote Gateway management;
• no change to the Windows executable updater;
• no new credentials, permissions, channels, or authority plane;
• no representation of a native backup archive as a directly restorable VHD.

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

Exact-Head Validation

Validated candidate: b571afe5900a9f11e26087bb33af0d4c5eb268d1

• Native-backup focused tests: 15/15 passed
• Native-backup and recovery focused tests: 30/30 passed
• Complete Connection suite: 621 passed, 3 declared host reparse-capability skips, 0 failed
• Tray suite before the final Connection-only hardening: 1,978/1,978 passed
• Shared suite: 3,240 passed, 31 declared environment-dependent skips
• Complete Release solution before the final Connection-only hardening: zero warnings and zero errors
• git diff --check: passed; Windows line-ending notices only
• Follow-up CI composition review: YAML parse passed; the workflow now composes frozen Core main 6277c35d9a97cb128d32ed7ab5632cfc4163c746 with exact PR #110382 head 6edc1e40f37b833ec0493ec331eba6cd49db4fb6; merged Core PR #111956 is consumed from main at 2296e898e13a5b250bf557e9632e000c093e61f1 rather than reapplied.
• The full stacked Auto-review bundle was rejected before model invocation because it exceeded the helper's safe size limit; no truncated bundle was sent. Four of five rebased functional commits retain identical patch IDs. The new convergence delta was reviewed separately; its only finding referenced a workflow writer that is absent from the exact source and was rejected with direct source proof.

The final follow-up commit changes only the CI composition contract and one stale reparse-boundary expectation. The complete Connection suite was rerun afterward: 621 passed, 3 declared host reparse-capability skips, 0 failed.

Real Behavior Proof

• A disposable OpenClawUpdateLab WSL target, not the operator Gateway, created a real OpenClaw native backup with --verify --json.
• Host SHA-256 and size were read back, and a second official openclaw backup verify --json returned ok=true.
• A disposable interrupted-update marker survived exact-distro termination; the delayed mutation did not execute; proof residue was removed.
• Coordinator-level tests cover successful verified backup, update dispatch, exact post-update version, synchronization, healthy update.complete, retained protection metadata, and zero VHD terminate/export calls on the native path.
• Failed-first Gateway-replacement proof confirms recovery sends no completion RPC and leaves the receipt unresolved when the current Gateway identity differs from the transaction identity.

The previous public CI run provided failed-first evidence: it reapplied Core PR #111956 after that change had already merged, used stale composed refs, and expected the later restore boundary even though the fixture is rejected earlier at the staging-root boundary. Those causes are corrected on the current head. The branch was then rebased onto #999 head f5958e2190e5484a40ce551783765c0637a1786a, which restores the 2026.7.1 minimum security floor and stable-only forward-update rule. Current-head GitHub Windows/WSL CI is running after publication.

Disposable full update-to-rollback runtime proof remains a pre-promotion gate; no operator runtime was mutated.

Security Impact

• New permissions or capabilities? (No)
• Secrets or tokens handling changed? (No)
• New or changed network calls? (No; the existing pinned installer path is reused)
• Command or tool execution surface changed? (Yes)
• Data access scope changed? (No)

Mitigations:

• explicit user confirmation before update;
• native verified backup or capacity-checked explicit VHD protection before mutation;
• SHA-256 and size binding across the WSL-to-host copy boundary;
• private owner-checked staging and durable receipts;
• distro ownership, machine identity, package target, Gateway identity, and node policy revalidated fail closed;
• no silent downgrade;
• no cleanup of unresolved recovery state.

Compatibility And Migration

• Backward compatible? (Yes)
• Config or environment changes? (Yes)
• Migration needed? (No)

Existing settings default to native verified backup, one retained previous version, and a seven-day retention window. Schema v3 rollback receipts remain readable as Full VHD protection. Existing Companion-owned Gateway records keep the same distro, identity, and connection ownership.

The ordinary package fallback is inherited from #999: 2026.7.1 is the minimum security floor and may advance only to a strictly newer official stable release. Composed packages continue to use exact immutable metadata.

Review Conversations

• Incorporated the maintainer storage-scaling feedback.
• Addressed accepted scoped review findings in the same update/backup/recovery boundary.
• Rebasing preserved fix(setup): validate current OpenClaw package lifecycle #999's secure LKG floor and kept composed package selection separate.
• Left only decisions and proof gates that require current-head CI or maintainer judgment.

Agent Transcript

Redacted operator/agent design and implementation timeline

This is a bounded reconstruction from the local Codex sessions used for this PR. It omits raw logs, private paths, credentials, unrelated work, and internal reasoning. Discussion records design provenance; the validation sections above remain the proof authority.

1. Destination locked by the operator

• The operator required a real in-place update of the existing Companion-owned OpenClawGateway, not a replacement distro or a parallel Linux install.
• The required invariant was that the Companion, distro identity, Gateway state, node relationship, and rollback path survive the update as one continuous installation.
• The operator also required rollback to at least the previous version and asked that retention eventually be understandable and controllable by ordinary users.

2. First design and challenge

• The initial implementation protected every update with a full VHD export because it offered a strong whole-distro rollback boundary.
• Scott Hanselman's review challenged that default: a live distro plus one retained VHD can approach two copies at steady state, while the next update can temporarily approach three. He also identified the absence of a proportional free-space preflight before stopping the distro.
• The operator explicitly accepted the critique rather than defending the original patch: the design needed to work for machines without abundant spare storage, and the response should treat the reviewer as a teammate improving the solution.

3. Alternatives debated

• Keep mandatory VHD rollback for every update: rejected as disproportionate for the routine path.
• Remove whole-distro recovery entirely: rejected because incompatible migrations and high-protection operator choices still need that boundary.
• Rely only on package rollback: rejected because package rollback alone does not protect mutable Gateway state.
• Layer protection by risk: accepted.

4. Contract selected

• Routine updates use the official staged package rollback together with a native openclaw backup create --verify state backup.
• Full VHD protection is reserved for incompatible migrations or an explicit higher-protection choice and must pass capacity checks.
• Retention is bounded by version count and age rather than growing indefinitely.
• Update completion requires the same persisted Gateway identity to return healthy and synchronized; recovery cannot silently bind to a replacement record.

5. Implementation and failed-first evidence

• Focused review and tests exposed receipt ambiguity, retry target substitution, concurrent receipt adjudication, installer-start uncertainty, cleanup races, host-copy integrity, predictable staging, and Gateway-record replacement.
• Each accepted defect was fixed at the boundary that owned it rather than by adding a parallel updater or compatibility wrapper.
• The native backup crossing WSL to Windows is bound to the WSL-produced SHA-256 and byte size after OpenClaw verification.
• Interrupted and failed updates retain unresolved recovery state instead of claiming completion or deleting the only rollback material.

6. Proof and current boundary

• Disposable WSL proof exercised native backup creation and independent verification without using the operator Gateway.
• The complete Connection suite passed after the final correction. The full stacked review bundle exceeded the safe helper limit; unchanged rebased commits were identified by patch ID and the new convergence delta was reviewed separately.
• The previous public CI failure exposed stale composition and one stale expected boundary; the rebased current head b571afe5900a9f11e26087bb33af0d4c5eb268d1 preserves those corrections and aligns with fix(setup): validate current OpenClaw package lifecycle #999's security-floor decision.
• Remaining gate: current-head GitHub CI plus disposable full update/rollback runtime proof. The operator runtime, private data, credentials, and channels were not used as the iterative lab.

[shanselman]

Bot perspective: I think the full-VHDX rollback strategy may be operationally untenable for routine Gateway updates.

Every update runs wsl --export ... --vhd, creating another complete dynamic VHDX. With the default retention of one point, steady-state storage can approach the live distro plus one full rollback copy. During the next update, the live VHDX, retained rollback, and newly exported rollback can temporarily approach three copies of the distro's allocated data. Failed or recovery-pending transactions intentionally retain their copy as well.

I also could not find a free-space preflight before the distro is stopped and export begins. On a machine with limited storage, that means an otherwise routine Gateway package update can consume many gigabytes, fill the system drive, and fail after disrupting the running Gateway.

Could we reconsider whether a complete VHDX is proportionate for every update? A safer layered policy might be:

1. For normal package updates, use the official updater's staged package rollback plus openclaw backup create --verify for Gateway state.
2. Reserve full VHDX recovery points for migrations known to change incompatible state or schemas.
3. If full VHDX remains mandatory, estimate the live VHDX size, require sufficient free space plus a safety margin before stopping WSL, show the expected storage cost in the confirmation UI, and prune eligible old points before export without deleting the latest known-good point.
4. Surface total rollback storage and provide an explicit cleanup action.

What failure model requires a byte-for-byte distro copy for every package update, and is that benefit worth the potentially 2x steady-state and 3x transient storage cost on ordinary user machines?

[TheAngryPit]

Thanks, Scott @shanselman . You're right about the storage model.

We optimized for the strongest possible rollback on machines with plenty of disk and made the most expensive recovery path routine. That does not scale to a normal user machine, especially as the Gateway distro grows over time.

We'll rework this into layered rollback:

• Routine package updates will use the official updater's staged package rollback plus openclaw backup create --verify for Gateway state.
• Full VHDX recovery points will be reserved for migrations that can change incompatible distro or schema state, or when the user explicitly asks for that level of protection.
• Any VHDX path will estimate the required space, enforce a safety margin before stopping WSL, show the expected cost in the confirmation UI, and prune eligible old points without deleting the latest known-good point.
• Settings will show total rollback storage and provide an explicit cleanup action.

For retention, our current direction is to keep the latest verified pre-update recovery point until the next update is healthy, then apply a seven-day grace period by default. Users will be able to choose a longer window or indefinite retention.

Before changing the implementation, we'll verify that the official staged rollback works with the exact pinned package used by the Companion and document precisely what the native backup includes and excludes. If either leaves a recovery gap, we'll map that gap to the specific cases that still need a VHDX instead of requiring one for every update.

This is a better design. Thanks for catching it before we shipped the expensive path as the default.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed July 26, 2026, 6:40 AM ET / 10:40 UTC.

ClawSweeper review

What this changes

Adds a user-confirmed Tray workflow that detects a local Companion-owned WSL Gateway version mismatch, protects its state, updates it in place, and verifies recovery plus Gateway and Windows-node synchronization.

Merge readiness

⛔ Blocked until stronger real behavior proof is added - 6 items remain

This PR remains necessary because current main does not yet provide the requested Companion-owned Gateway alignment workflow. The branch has credible unit and partial disposable-runtime evidence, but it still lacks a current-head, disposable full update followed by recovery or rollback and healthy Gateway/node confirmation; it also intentionally carries the unresolved package-lifecycle dependency from #999.

Priority: P2
Reviewed head: b571afe5900a9f11e26087bb33af0d4c5eb268d1
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The branch presents substantial implementation and partial runtime evidence, but its dependency stack and missing end-to-end recovery proof prevent a higher readiness rating.
Proof confidence	🦐 gold shrimp (3/6)	Needs stronger real behavior proof before merge: The PR shows real native-backup verification and interruption evidence, but it expressly lacks a current-head disposable full update followed by recovery or rollback and confirmed healthy Gateway and Windows-node state. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Patch quality	🦐 gold shrimp (3/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Needs proof	Needs stronger real behavior proof before merge: The PR shows real native-backup verification and interruption evidence, but it expressly lacks a current-head disposable full update followed by recovery or rollback and confirmed healthy Gateway and Windows-node state. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Evidence reviewed	5 items	Feature implementation surface: The proposed head introduces the version-alignment coordinator and rollback-point manager that implement protected in-place Gateway updates, recovery receipts, retention, and synchronization. Architecture ownership declared by the branch: The architecture ledger assigns Gateway version alignment to the connection coordinator and keeps the Tray as composition and presentation only, matching the repository's god-file reduction policy. Current-head proof remains incomplete: The PR explicitly records native-backup verification and interrupted-update evidence, but states that disposable full update-to-rollback runtime proof remains a pre-promotion gate.
Findings	None	None.
Security	None	None.

How this fits together

The Windows Tray owns setup-managed local WSL Gateway lifecycle while the connection layer manages Gateway and Windows-node health. This change sits between startup keepalive/version probing and the post-update reconnect path, adding protected package alignment and recovery handling.

flowchart LR
  A[Tray startup keepalive] --> B[Local WSL Gateway]
  B --> C[Installed version probe]
  C --> D{Version matches target?}
  D -->|No| E[User-confirmed update plan]
  E --> F[Verified backup or VHD protection]
  F --> G[In-place package update]
  G --> H[Gateway and node health synchronization]
  D -->|Yes| H

Loading

Decision needed

Question	Recommendation
Should the repository adopt the proposed Companion-owned in-place Gateway update and layered recovery transaction after the package-lifecycle dependency lands?	Land as a focused follow-up: Merge the package-lifecycle dependency first, then rebase this PR so it contains only the reviewed Gateway-alignment transaction and its completed runtime proof.

Why: The implementation adds a substantial new user-facing update, recovery, retention, and persisted-settings contract. The collaborator feedback establishes a preferred protection shape, but it does not establish final maintainer acceptance of this product boundary or its dependency split.

Before merge

• Add real behavior proof - Needs stronger real behavior proof before merge: The PR shows real native-backup verification and interruption evidence, but it expressly lacks a current-head disposable full update followed by recovery or rollback and confirmed healthy Gateway and Windows-node state. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
• Resolve merge risk (P1) - The PR changes a security-sensitive WSL package-update and recovery boundary, but no current-head disposable proof yet demonstrates the complete update, failed path, recovery or rollback, and final Gateway/node health sequence.
• Resolve merge risk (P1) - The branch intentionally includes the still-open package-lifecycle work from fix(setup): validate current OpenClaw package lifecycle #999; merging before that dependency is resolved would make the final ownership and review boundary unclear.
• Resolve merge risk (P1) - The new persisted protection preferences and recovery receipts affect existing installations, so fresh-install and upgrade behavior need to remain covered after the dependency rebase.
• Complete next step (P2) - This requires maintainer product-direction approval and contributor-supplied real behavior proof, not a bounded automated repair.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Review surface	79 files affected; 14,576 additions and 281 deletions	The diff combines a broad update feature with its unmerged package-lifecycle dependency, so a rebase is needed to establish the final merge boundary.

Merge-risk options

Maintainer options:

1. Rebase after the lifecycle dependency lands (recommended)
   Resolve fix(setup): validate current OpenClaw package lifecycle #999 first, then reduce this branch to the Gateway-alignment-specific diff and rerun upgrade coverage.
2. Pause for a sponsored update contract
   Hold this PR if maintainers do not yet want Companion-managed package updates, recovery receipts, and rollback retention as a supported product contract.

Technical review

Best possible solution:

Land or explicitly retire the package-lifecycle dependency first, then rebase this work into a focused Gateway-alignment PR and attach redacted current-head disposable proof of update, rollback or recovery, and healthy Gateway/node synchronization.

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

Not applicable as a bug reproduction: this PR proposes a new update and recovery capability. Its partial disposable evidence is credible, but the full intended runtime flow has not yet been demonstrated on the current head.

Is this the best way to solve the issue?

Unclear. The in-place, user-confirmed approach is aligned with the linked requirement and the layered-protection review feedback, but maintainers must first accept the new product contract and review it after the package-lifecycle dependency is separated.

AGENTS.md: found and applied where relevant.

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

Labels

Label justifications:

• P2: This is a substantial but user-confirmed local Gateway update feature with bounded impact rather than an active core-runtime outage.
• merge-risk: 🚨 compatibility: The PR adds persisted rollback settings, receipt formats, package-target behavior, and upgrade handling for existing Companion-owned installations.
• merge-risk: 🚨 security-boundary: The update path executes package installation inside WSL and validates package, identity, staging, and recovery boundaries before completing a transaction.
• merge-risk: 🚨 availability: A failed update or recovery path can leave the local Gateway unavailable until its protected recovery workflow completes.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🦐 gold shrimp and patch quality is 🦐 gold shrimp.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs stronger real behavior proof before merge: The PR shows real native-backup verification and interruption evidence, but it expressly lacks a current-head disposable full update followed by recovery or rollback and confirmed healthy Gateway and Windows-node state. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence

What I checked:

• Feature implementation surface: The proposed head introduces the version-alignment coordinator and rollback-point manager that implement protected in-place Gateway updates, recovery receipts, retention, and synchronization. (src/OpenClaw.Connection/GatewayVersionAlignmentCoordinator.cs, b571afe5900a)
• Architecture ownership declared by the branch: The architecture ledger assigns Gateway version alignment to the connection coordinator and keeps the Tray as composition and presentation only, matching the repository's god-file reduction policy. (docs/ARCHITECTURE.md:117, b571afe5900a)
• Current-head proof remains incomplete: The PR explicitly records native-backup verification and interrupted-update evidence, but states that disposable full update-to-rollback runtime proof remains a pre-promotion gate. (b571afe5900a)
• Unmerged dependency remains material: The PR body says it is conceptually stacked on the still-open package-lifecycle PR and should be rebased onto main after that work lands, so the present 79-file diff is not yet the final review boundary. (f5958e2190e5)
• Original product requirement: The linked issue defines the central user problem: detect and safely align the setup-managed local WSL Gateway with the Windows Companion without recreating the distro.

Likely related people:

• iamalin: Opened the linked lock-step Gateway requirement that defines the user-visible behavior this PR is intended to implement. (role: feature originator; confidence: medium; files: src/OpenClaw.Connection/GatewayVersionAlignmentCoordinator.cs, src/OpenClaw.Tray.WinUI/App.xaml.cs)
• shanselman: Provided the collaborator review that redirected routine protection away from mandatory full-VHD rollback toward the layered backup and explicit-VHD design now used by this PR. (role: design reviewer; confidence: medium; files: src/OpenClaw.Connection/GatewayRollbackPointManager.cs, src/OpenClaw.Tray.WinUI/Pages/SettingsPage.xaml)
• CassieMei: Authored the commits on this branch covering the package contract, update transaction, recovery, tests, and documentation. (role: recent implementation contributor; confidence: medium; commits: 2dabee170176, 4b1d13c096cc, b571afe5900a; files: src/OpenClaw.Connection/GatewayVersionAlignmentCoordinator.cs, src/OpenClaw.Connection/GatewayRollbackPointManager.cs, tests/OpenClaw.Connection.Tests/GatewayVersionAlignmentCoordinatorTests.cs)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Post redacted current-head terminal output, logs, or a recording for a disposable update and recovery or rollback through healthy Gateway and Windows-node confirmation.
• After fix(setup): validate current OpenClaw package lifecycle #999 is resolved, rebase and reduce the diff to the alignment-specific transaction before final review.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
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.

Workflow

• 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.

History

Review history (4 earlier review cycles)

• reviewed 2026-07-25T04:54:22.152Z sha 090e9b8 :: needs real behavior proof before merge. :: [P1] Do not require a full VHD rollback for every update
• reviewed 2026-07-26T02:13:36.644Z sha 8ced19b :: needs real behavior proof before merge. :: none
• reviewed 2026-07-26T06:56:03.624Z sha 526e933 :: needs real behavior proof before merge. :: none
• reviewed 2026-07-26T10:34:43.000Z sha b571afe :: needs real behavior proof before merge. :: none

[TheAngryPit]

Rebase and secure package-policy alignment published

Current head: b571afe5900a9f11e26087bb33af0d4c5eb268d1

This branch is now rebased onto #999 head f5958e2190e5484a40ce551783765c0637a1786a. The in-place update transaction keeps the layered native-backup/VHD design discussed with @shanselman while inheriting the corrected package contract:

• ordinary fallback: official stable 2026.7.1 security floor;
• future fallback movement: exact stable releases strictly newer than the pin;
• composed candidate: exact version, credential-free URI, and SHA-256 metadata;
• explicit hot and restart reload modes remain unchanged rather than being rewritten to hybrid.

Fresh exact-head local proof:

• YAML and package-policy simulation: passed;
• focused SetupEngine: 13/13;
• focused package-target tests: 20/20;
• complete Release build: passed;
• SetupEngine: 793/793;
• Connection: 621 passed with 3 declared host-capability skips;
• Shared: 3,240 passed with 31 declared environment-dependent skips;
• Tray: 1,978/1,978;
• git diff --check: clean.

The complete stacked Auto-review bundle exceeded the helper's safe size limit and was not sent truncated. Patch-ID comparison showed four of five rebased functional commits unchanged; the new convergence delta was reviewed separately. Its sole finding referred to a removed workflow writer and was rejected against the exact source. GitHub checks started automatically from this push; no manual ClawSweeper request was added.