kernalix7--winpodx/docs/design/GUEST_SYNC_DESIGN.md

Guest sync — apply host-side updates to a running guest without reinstall

Problem

Upgrading WinPodX on the host updates the host binary, but the guest-side artifacts that were staged at first install go stale until the user wipes and reinstalls Windows:

• C:\OEM\agent.ps1 — the in-guest agent (bind/retry logic, endpoints).
• install.bat-derived runtime state — urlacl reservation (#269), RDP / multi-session registry, Defender exclusions, TermService recovery, NIC tweaks.
• Guest binaries — rdprrap zip, shim.exe (reverse-open), rcedit.exe.

winpodx pod apply-fixes already re-applies some idempotent registry fixes, but it does not refresh agent.ps1, the urlacl reservation, or the guest binaries — and it is manual. Users on an upgraded host silently run an old guest until they reinstall.

Key enabler

/oem is a live bind mount of the host's config/oem ({oem_dir}:/oem:Z in compose.py). So after a host upgrade the container's /oem already contains the new agent.ps1 / rdprrap / scripts — no image rebuild. Delivery into the guest is the same channel winpodx pod recover-oem already uses (tar /oem → container HTTP :8766 → guest pulls via the QEMU NAT gateway 10.0.2.2), except for sync the agent is alive, so it runs over /exec automatically instead of noVNC paste.

Version stamp

The guest records what provisioned it at C:\winpodx\install-state\guest_version.json:

{ "winpodx": "0.5.8", "oem_bundle": "25" }

• Host current = winpodx.__version__ + core.info._bundled_oem_version().
• read_guest_version() reads the file via /exec; missing/old/unparseable → treated as "needs sync".
• Written only after a fully successful sync (or by the installer on a fresh provision).

guest_sync_needed(cfg) returns True when the guest stamp differs from the host pair (or is absent).

Sync flow (core/guest_sync.py :: sync_guest)

All steps idempotent; ordered so a partial failure is safe to re-run.

1. Deliver /oem to the guest. Tar /oem in the container into a dedicated serve dir, start the :8766 HTTP server (reuse the recover-oem container ops), then over /exec: Invoke-WebRequest http://10.0.2.2:8766/oem.tar.gz → tar -xzf into C:\OEM. This refreshes agent.ps1, rdprrap, shim.exe, rcedit.exe, and the helper scripts in one shot. install.bat is NOT run — it contains one-shot first-boot logic (autologon, account setup) that must not re-run on a live install.
2. urlacl reservation (#269) — port install.bat's netsh block to /exec: delete the overlapping 8765 reservations, then netsh http add urlacl url=http://+:8765/ sddl=D:(A;;GX;;;WD).
3. Idempotent registry/runtime fixes — call the existing provisioner.apply_windows_runtime_fixes(cfg) (max_sessions, rdp_timeouts, oem_runtime_fixes, vbs_launchers, multi_session). This also re-activates rdprrap against the refreshed binaries.
4. Restart the agent — the agent is what /exec runs through, so it can't kill itself synchronously. Register a one-shot scheduled task that fires in ~5 s to stop the current agent process and relaunch C:\OEM\agent.ps1 (the HKCU\Run command). The /exec call returns before the task fires; the new agent binds 8765 with the now-correct urlacl.
5. Write the version stamp — only if steps 1–3 succeeded (step 4 is fire-and-forget; readiness is reconfirmed by the caller).

sync_guest returns a per-step result map (like apply_windows_runtime_fixes) so CLI/GUI can render rows.

Triggers

• Auto (default on): after the pod is responsive (provisioner.ensure_ready / pod wait-ready tail), if guest_sync_needed → run sync_guest. Cheap no-op when versions match. Gated to podman/docker.
• Manual: winpodx pod sync-guest [--force] and a GUI Tools → Sync Guest action. --force re-syncs even when the stamp matches.

Config: pod.guest_autosync (bool, default True). false = only manual.

Risks / mitigations

Risk	Mitigation
Agent restart drops the /exec we're inside	one-shot scheduled task fires after the call returns; never Stop-Process the agent synchronously
rdprrap re-activation disconnects a live session	auto-sync is post-readiness at pod start (no user session yet); manual sync warns
Partial sync leaves mixed state	every step idempotent + re-runnable; stamp written only on success so the next start retries
/oem tar exposes /storage	serve a dedicated dir with only oem.tar.gz (same as recover-oem)
Download integrity	size + extract check; agent_token already shared, no new trust boundary

Real-Windows smoke checklist (gate before merge/release)

Guest-side /exec work — pwsh-on-Linux Pester is not sufficient.

1. Upgrade host WinPodX (bump oem_bundle), start an existing pod. → auto-sync runs; guest_version.json updates to the new pair.
2. C:\OEM\agent.ps1 matches the new host copy (hash/length).
3. Agent rebinds 8765 after the restart task (no manual step); winpodx check shows agent reachable.
4. netsh http show urlacl url=http://+:8765/ shows the WD SID reservation.
5. rdprrap still active; multi-session still works.
6. winpodx pod sync-guest --force on an up-to-date guest is a clean no-op (no session disruption, exit 0).
7. Re-run sync after killing it mid-flight → converges (idempotency).