Stop automatic update retries when the update helper rejects the installation and report its code

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 Notable changes to Wisp are recorded here.
 
+## Unreleased
+
+- Report which check the update helper failed when an update cannot start, and show how to reinstall when this copy of Wisp does not match the registered installation. Automatic update attempts stop for the session after such a rejection; Install update remains available from the dashboard.
+
 ## 2.6.13 - 2026-10-17
 
 - Keep the HUD renderer running when a native graphics allocation fails; report the failure and restart the renderer instead of closing Wisp.

src/Wisp.App/App.xaml.cs

@@ -645,6 +645,7 @@ internal async Task<ApplicationUpdateStartResult> TryBeginApplicationUpdateAsync
             return (false, "Application updates were paused. Review the update again when available.");
         }
         ApplicationUpdateHandoff handoff;
+        var launchedAt = DateTimeOffset.UtcNow;
         try
         {
             handoff = ApplicationUpdateLauncher.Launch(installer);
@@ -730,17 +731,31 @@ InvalidOperationException or ArgumentException or Win32Exception or
             }
             if (handoffState != ApplicationUpdateHandoffState.Ready)
             {
-                RecordSupplementarySignal("update", "update", handoffState == ApplicationUpdateHandoffState.TimedOut ? "timeout" : "failure", "install-handoff",
-                    incident: Supplementary.SupplementaryIncidentSchema.Create("update",
-                        handoffState == ApplicationUpdateHandoffState.TimedOut ? "timeout" : "update-verification-failed", "update-install-handoff"));
+                string error;
+                var helperRejected = false;
+                if (handoffState == ApplicationUpdateHandoffState.HelperExited)
+                {
+                    // The helper records which check failed before it exits. Report that code now,
+                    // and stop automatic attempts when the same check fails again in this session.
+                    var exit = ApplicationUpdateLauncher.DescribeHelperExit(handoff.ExitCode, launchedAt);
+                    RecordSupplementarySignal("update", "update", "failure", "install-handoff", incident: exit.Incident);
+                    error = exit.Status;
+                    helperRejected = exit.Permanent;
+                }
+                else
+                {
+                    RecordSupplementarySignal("update", "update", handoffState == ApplicationUpdateHandoffState.TimedOut ? "timeout" : "failure", "install-handoff",
+                        incident: Supplementary.SupplementaryIncidentSchema.Create("update",
+                            handoffState == ApplicationUpdateHandoffState.TimedOut ? "timeout" : "update-verification-failed", "update-install-handoff"));
+                    error = handoffState == ApplicationUpdateHandoffState.TimedOut
+                        ? "The update helper did not become ready in time. Wisp stayed open and no files were installed."
+                        : "The update helper could not verify this installation. Wisp stayed open and no files were installed.";
+                }
                 handoff.StopIfRunning();
                 _applicationUpdateHandoffActive = false;
                 _controller.Runs.CancelMetadataClosePreparation();
-                var error = handoffState == ApplicationUpdateHandoffState.TimedOut
-                    ? "The update helper did not become ready in time. Wisp stayed open and no files were installed."
-                    : "The update helper could not verify this installation. Wisp stayed open and no files were installed.";
                 _controller.ViewModel.UpdateApplicationUpdateStatus(error, "Try again", canCheck: true);
-                return (false, error);
+                return new ApplicationUpdateStartResult(false, error, HelperRejected: helperRejected);
             }
         }
 

src/Wisp.App/AppController.cs

@@ -723,9 +723,19 @@ private static ApplicationUpdateDetails ApplicationUpdateDetailsFrom(UpdateRelea
         }
     }
 
+    // Once automatic installation has stopped for the session (the update helper is missing or
+    // rejected this installation), the periodic check points at the full installer instead of
+    // promising an installation that cannot happen. The buttons still try once per click.
+    private bool AutomaticInstallationStopped => _automaticInstaller is { HandoffUnavailable: true };
+
+    private static string ManualInstallStatus(SemanticVersion version) =>
+        $"Wisp {ApplicationVersionInfo.Format(version)} could not be installed automatically. Download and run the full installer from wispoverlay.com.";
+
     private void ShowAvailableApplicationUpdate(UpdateRelease release) =>
         ViewModel.UpdateApplicationUpdateStatus(
-            $"Wisp {ApplicationVersionInfo.Format(release.Version)} is available. Wisp will update and restart after Forza closes.",
+            AutomaticInstallationStopped
+                ? ManualInstallStatus(release.Version)
+                : $"Wisp {ApplicationVersionInfo.Format(release.Version)} is available. Wisp will update and restart after Forza closes.",
             "Update",
             canCheck: true,
             isUpdateAvailable: true);
@@ -737,7 +747,9 @@ private bool TryShowPendingApplicationUpdate(bool canCheck = true)
             return false;
         }
         ViewModel.UpdateApplicationUpdateStatus(
-            $"Wisp {ApplicationVersionInfo.Format(pending.Version)} is verified and ready to install.",
+            AutomaticInstallationStopped
+                ? ManualInstallStatus(pending.Version)
+                : $"Wisp {ApplicationVersionInfo.Format(pending.Version)} is verified and ready to install.",
             "Install update",
             canCheck,
             isUpdateAvailable: true);