fix(scripts): clarify Windows update retry marker semantics

scripts/desktop-update/retry-policy.ps1

@@ -8,8 +8,10 @@ function Test-HermesUpdateShouldRetry {
     if ($ExitCode -ne 2) { return $true }
 
     # Exit 2 is shared by non-retryable safety refusals and the self-lock
-    # deferral. Only the latter writes this marker, which a fresh Python
-    # process consumes before importing native modules.
+    # deferral. Only the latter writes this marker. The handoff treats it as a
+    # retry signal for one fresh-process attempt; early recovery does not run
+    # while argv contains "update".
     $deferredInstallMarker = Join-Path $InstallRoot ".update-incomplete"
     return Test-Path -LiteralPath $deferredInstallMarker
 }
+

scripts/desktop-update/windows.ps1

@@ -1502,8 +1502,11 @@ try {
     if (Test-HermesUpdateShouldRetry -ExitCode $res.Code -InstallRoot $InstallRoot) {
         # One retry for update-boundary failures. Most exit-2 safety refusals
         # remain terminal, but self-lock deferral also uses exit 2 and writes
-        # .update-incomplete after the code swap. A fresh process consumes that
-        # marker before native imports, then resumes the full update pipeline.
+        # .update-incomplete after the code swap. That marker is only a retry
+        # signal here: early recovery skips argv containing "update", so this
+        # fresh process must finish dependency sync without holding the locked
+        # native modules (lazy imports on the swapped checkout), then continue
+        # the remaining Desktop/skills stages of the full update pipeline.
         Write-HandoffLog "first attempt left retryable update state; retrying once in a fresh process"
         Publish-UiProgress "Retrying update"
         $res = Invoke-HermesStep $pythonExe $updateArgs "update"

tests/test_desktop_update_windows_retry_policy.py

@@ -53,4 +53,4 @@ def test_retry_policy_distinguishes_self_lock_deferral(tmp_path: Path) -> None:
         "withoutMarker": [False, True, False],
         "withMarker": True,
     }
-    assert marker.exists()
+    assert marker.exists()