PLN-324: Guard onboarding races

- Cancel stale managed onboarding continuations before manual API key, settings, or saved-config changes can be overwritten

- Catch activate-time onboarding rejections outside the process-level unhandled rejection handler

- Add cancellation-aware repo seeding plus focused regression tests

Testing: pnpm -C apps/desktop exec tsx --test test/app-lifecycle.test.ts test/managed-onboarding-run.test.ts test/managed-onboarding.test.ts test/seed-repos-config.test.ts; pnpm -C apps/desktop typecheck; pnpm -C apps/desktop lint; pnpm -C apps/desktop test; git diff --check

Risks: Low; managed onboarding now prefers explicit user action and activation failures are logged without exiting.

Author: shafty023

apps/desktop/src/main/app-lifecycle.ts

@@ -0,0 +1,21 @@
+/**
+ * Handles Electron lifecycle callbacks that dispatch async Desktop work.
+ *
+ * Electron does not await event listener promises. Keeping the catch inside the
+ * lifecycle helper prevents expected activation-time failures from becoming
+ * process-level unhandled rejections.
+ */
+export async function handleActivateEvent(deps: {
+  handleActivate: () => Promise<void>;
+  log: (message: string) => void;
+}): Promise<void> {
+  try {
+    await deps.handleActivate();
+  } catch (error) {
+    const message =
+      error instanceof Error
+        ? `${error.message}${error.stack ? `\n${error.stack}` : ""}`
+        : String(error);
+    deps.log(`activate handling failed: ${message}`);
+  }
+}

apps/desktop/src/main/app.ts

@@ -90,6 +90,10 @@ import {
   type TrustedDesktopConfigResult,
   withSingleManagedOnboardingRetry,
 } from "./managed-onboarding.js";
+import {
+  ManagedOnboardingRunTracker,
+  type ManagedOnboardingRunToken,
+} from "./managed-onboarding-run.js";
 import {
   getCanonicalOnboardingHandoffPath,
   isCanonicalOnboardingHandoffPath,
@@ -146,6 +150,7 @@ export class DesktopApplication {
   private bootReadyForOnboarding = false;
   private processingOnboardingHandoff = false;
   private readonly queuedOpenFileHandoffs = new OnboardingHandoffQueue();
+  private readonly managedOnboardingRuns = new ManagedOnboardingRunTracker();
   private managedOnboardingState: ManagedOnboardingState = { status: "idle" };
   private readonly queueStatsTelemetryDebounce: QueueStatsDebounce =
     createQueueStatsDebounce(
@@ -560,6 +565,7 @@ export class DesktopApplication {
   private async handleLoadedOnboardingHandoff(
     payload: PendingOnboardingHandoff,
   ): Promise<void> {
+    const run = this.managedOnboardingRuns.begin();
     this.managedOnboardingState = {
       status: "awaiting-origin-confirmation",
       webAppOrigin: payload.webAppOrigin,
@@ -569,6 +575,9 @@ export class DesktopApplication {
     this.showWindow();
 
     const confirmed = await this.confirmManagedOnboardingOrigin(payload);
+    if (this.shouldStopManagedOnboardingRun(run, "origin confirmation")) {
+      return;
+    }
     if (!confirmed) {
       this.setManagedOnboardingFailure(
         "origin_confirmation_dismissed",
@@ -578,7 +587,7 @@ export class DesktopApplication {
       return;
     }
 
-    await this.runManagedOnboardingProvisioning(payload);
+    await this.runManagedOnboardingProvisioning(payload, run);
   }
 
   private async confirmManagedOnboardingOrigin(
@@ -599,7 +608,11 @@ export class DesktopApplication {
 
   private async runManagedOnboardingProvisioning(
     payload: PendingOnboardingHandoff,
+    run: ManagedOnboardingRunToken,
   ): Promise<void> {
+    if (this.shouldStopManagedOnboardingRun(run, "provisioning start")) {
+      return;
+    }
     this.managedOnboardingState = {
       status: "provisioning",
       webAppOrigin: payload.webAppOrigin,
@@ -612,8 +625,12 @@ export class DesktopApplication {
         fetchTrustedDesktopConfig({ webAppOrigin: payload.webAppOrigin }),
       shouldRetry: isRetryableTrustedConfigFailure,
       delayMs: MANAGED_ONBOARDING_RETRY_DELAY_MS,
-      isCancelled: () => this.shuttingDown,
+      isCancelled: () =>
+        this.managedOnboardingRuns.isCancelled(run, this.shuttingDown),
     });
+    if (this.shouldStopManagedOnboardingRun(run, "trusted config result")) {
+      return;
+    }
     if (trustedConfig.kind !== "ok") {
       this.setManagedOnboardingFailure(
         trustedConfig.reason,
@@ -623,6 +640,9 @@ export class DesktopApplication {
       return;
     }
 
+    if (this.shouldStopManagedOnboardingRun(run, "claim start")) {
+      return;
+    }
     this.managedOnboardingState = {
       status: "provisioning",
       webAppOrigin: payload.webAppOrigin,
@@ -643,9 +663,13 @@ export class DesktopApplication {
         }),
       shouldRetry: isRetryableBootstrapClaimFailure,
       delayMs: MANAGED_ONBOARDING_RETRY_DELAY_MS,
-      isCancelled: () => this.shuttingDown,
+      isCancelled: () =>
+        this.managedOnboardingRuns.isCancelled(run, this.shuttingDown),
     });
 
+    if (this.shouldStopManagedOnboardingRun(run, "claim result")) {
+      return;
+    }
     if (claimResult.kind === "manual_fallback") {
       this.setManagedOnboardingFailure(
         claimResult.reason,
@@ -663,6 +687,9 @@ export class DesktopApplication {
       return;
     }
 
+    if (this.shouldStopManagedOnboardingRun(run, "managed key persistence")) {
+      return;
+    }
     this.apiKeyStore.setApiKey(claimResult.apiKey, "DESKTOP_MANAGED");
     const sandboxBaseDirectory = normalizeScopePath(
       payload.sandboxBaseDirectory,
@@ -685,7 +712,16 @@ export class DesktopApplication {
     });
 
     if (safeSandboxBaseDirectory) {
-      await seedReposConfig(safeSandboxBaseDirectory);
+      if (this.shouldStopManagedOnboardingRun(run, "repo config seeding")) {
+        return;
+      }
+      await seedReposConfig(safeSandboxBaseDirectory, {
+        isCancelled: () =>
+          this.managedOnboardingRuns.isCancelled(run, this.shuttingDown),
+      });
+      if (this.shouldStopManagedOnboardingRun(run, "completion state update")) {
+        return;
+      }
       this.managedOnboardingState = {
         status: "idle",
         webAppOrigin: payload.webAppOrigin,
@@ -706,6 +742,33 @@ export class DesktopApplication {
     this.showWindow();
   }
 
+  private shouldStopManagedOnboardingRun(
+    run: ManagedOnboardingRunToken,
+    stage: string,
+  ): boolean {
+    if (!this.managedOnboardingRuns.isCancelled(run, this.shuttingDown)) {
+      return false;
+    }
+    gatewayLog.debug(
+      "managed-onboarding",
+      `Skipping stale managed onboarding continuation at ${stage}.`,
+    );
+    return true;
+  }
+
+  private cancelManagedOnboardingForUserChange(reason: string): void {
+    this.managedOnboardingRuns.cancel();
+    if (this.managedOnboardingState.status === "idle") {
+      return;
+    }
+    gatewayLog.debug(
+      "managed-onboarding",
+      `Canceled automated onboarding because ${reason}.`,
+    );
+    this.managedOnboardingState = { status: "idle" };
+    this.notifyOnboardingStateChanged();
+  }
+
   private setManagedOnboardingFailure(
     reason: string,
     message: string,
@@ -1326,6 +1389,21 @@ export class DesktopApplication {
           );
         }
 
+        const updatesOnboardingState = (
+          [
+            "sandboxBaseDirectory",
+            "onboardingCompleted",
+            "relayOrigin",
+            "apiOrigin",
+            "webAppOrigin",
+          ] as const
+        ).some((key) => key in partial);
+        if (updatesOnboardingState) {
+          this.cancelManagedOnboardingForUserChange(
+            "settings were updated manually",
+          );
+        }
+
         const updated = this.settingsStore.update(
           nextPartial as Partial<DesktopSettings>,
         );
@@ -1500,11 +1578,13 @@ export class DesktopApplication {
       if (!trimmed.startsWith("sk_live_")) {
         throw new Error("API key must start with sk_live_");
       }
+      this.cancelManagedOnboardingForUserChange("a manual API key was set");
       this.apiKeyStore.setApiKey(trimmed);
       this.restartCloudSocket();
       return this.apiKeyStore.getStatus();
     });
     ipcMain.handle("desktop:clear-api-key", () => {
+      this.cancelManagedOnboardingForUserChange("the API key was cleared");
       this.apiKeyStore.clearApiKey();
       this.restartCloudSocket();
       return this.apiKeyStore.getStatus();
@@ -1571,7 +1651,6 @@ export class DesktopApplication {
           if (!trimmedApiKey.startsWith("sk_live_")) {
             throw new Error("API key must start with sk_live_");
           }
-          this.apiKeyStore.setApiKey(trimmedApiKey, "USER_CREATED");
         } else {
           const onboardingAttemptId =
             typeof payload.onboardingAttemptId === "string"
@@ -1582,6 +1661,10 @@ export class DesktopApplication {
           }
         }
 
+        this.cancelManagedOnboardingForUserChange("manual onboarding completed");
+        if (trimmedApiKey) {
+          this.apiKeyStore.setApiKey(trimmedApiKey, "USER_CREATED");
+        }
         this.settingsStore.update({
           ...(relayOrigin !== undefined ? { relayOrigin } : {}),
           ...(apiOrigin !== undefined ? { apiOrigin } : {}),
@@ -1735,6 +1818,9 @@ export class DesktopApplication {
       }
       const { wasActive } = this.settingsStore.deleteConfig(id);
       if (wasActive) {
+        this.cancelManagedOnboardingForUserChange(
+          "the active saved config was deleted",
+        );
         this.settingsStore.setRelayOrigin(DEFAULT_DESKTOP_SETTINGS.relayOrigin);
         this.settingsStore.setApiOrigin(DEFAULT_DESKTOP_SETTINGS.apiOrigin);
         this.settingsStore.setWebAppOrigin(DEFAULT_DESKTOP_SETTINGS.webAppOrigin);
@@ -1764,6 +1850,7 @@ export class DesktopApplication {
       if (!safeStorage.isEncryptionAvailable()) {
         throw new Error("safeStorage is not available -- cannot apply config");
       }
+      this.cancelManagedOnboardingForUserChange("a saved config was applied");
       const appliedConfig = this.settingsStore.applyConfig(id);
       const profileKey = this.apiKeyStore.getProfileKeyRecord(id);
       if (profileKey) {

apps/desktop/src/main/index.ts

@@ -1,5 +1,6 @@
 import { app, nativeTheme } from "electron";
 import { DesktopApplication } from "./app.js";
+import { handleActivateEvent } from "./app-lifecycle.js";
 import { handleUncaughtException, handleUnhandledRejection } from "./error-handlers.js";
 import { gatewayLog } from "./gateway-logger.js";
 
@@ -31,7 +32,10 @@ app.on("ready", () => {
 });
 
 app.on("activate", () => {
-  void desktopApplication.handleActivate();
+  void handleActivateEvent({
+    handleActivate: () => desktopApplication.handleActivate(),
+    log: (message) => gatewayLog.warn("activate", message),
+  });
 });
 
 let quitPromise: Promise<void> | null = null;

apps/desktop/src/main/managed-onboarding-run.ts

@@ -0,0 +1,38 @@
+/**
+ * Tracks the active managed-onboarding continuation so newer user action can
+ * cancel stale async work before it writes credentials or settings.
+ */
+export type ManagedOnboardingRunToken = {
+  readonly id: number;
+};
+
+/**
+ * Small, framework-free run coordinator for Desktop managed onboarding.
+ *
+ * A token is current only until a newer managed run starts or a manual action
+ * cancels automated onboarding. Callers should check the token after awaited
+ * work and immediately before durable side effects.
+ */
+export class ManagedOnboardingRunTracker {
+  private currentRunId = 0;
+
+  begin(): ManagedOnboardingRunToken {
+    this.currentRunId += 1;
+    return { id: this.currentRunId };
+  }
+
+  cancel(): void {
+    this.currentRunId += 1;
+  }
+
+  isCurrent(token: ManagedOnboardingRunToken): boolean {
+    return token.id === this.currentRunId;
+  }
+
+  isCancelled(
+    token: ManagedOnboardingRunToken,
+    externallyCancelled = false,
+  ): boolean {
+    return externallyCancelled || !this.isCurrent(token);
+  }
+}

apps/desktop/src/main/seed-repos-config.ts

@@ -12,17 +12,31 @@ import { loadReposConfig, saveReposConfig } from "../server/operations/repos-con
  * Repos are added explicitly by the user via POST /api/gateway/repos — this
  * function never auto-discovers repos from the filesystem.
  *
- * Best-effort — logs errors but never throws.
+ * Best-effort — logs errors but never throws. When provided, `isCancelled`
+ * lets long-running callers avoid writing stale repo defaults after the user
+ * has switched to another onboarding/settings path.
  */
-export async function seedReposConfig(rawSandboxBaseDirectory: string): Promise<void> {
+export async function seedReposConfig(
+  rawSandboxBaseDirectory: string,
+  options: { isCancelled?: () => boolean } = {},
+): Promise<void> {
   try {
+    if (options.isCancelled?.()) {
+      return;
+    }
     const sandboxBaseDirectory = normalizeScopePath(rawSandboxBaseDirectory);
     if (!sandboxBaseDirectory) {
       return;
     }
+    if (options.isCancelled?.()) {
+      return;
+    }
 
     const symphonyDir = computeSymphonyDir(sandboxBaseDirectory);
     const configDir = path.join(symphonyDir, "config");
+    if (options.isCancelled?.()) {
+      return;
+    }
     mkdirSync(configDir, { recursive: true });
 
     // Ensure worktreeParentDir + worktreeParentDirConfirmed are both set.
@@ -37,6 +51,9 @@ export async function seedReposConfig(rawSandboxBaseDirectory: string): Promise<
     //     set confirmed only.
     // Single load → mutate in-memory → single save.
     const config = await loadReposConfig(configDir);
+    if (options.isCancelled?.()) {
+      return;
+    }
     let dirty = false;
 
     const existingDir = config.settings.worktreeParentDir;
@@ -58,7 +75,7 @@ export async function seedReposConfig(rawSandboxBaseDirectory: string): Promise<
       dirty = true;
     }
 
-    if (dirty) {
+    if (dirty && !options.isCancelled?.()) {
       await saveReposConfig(config, configDir);
     }
   } catch (err) {

apps/desktop/test/app-lifecycle.test.ts

@@ -0,0 +1,30 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { handleActivateEvent } from "../src/main/app-lifecycle.js";
+
+test("activate handler logs rejected async work without rethrowing", async () => {
+  const logs: string[] = [];
+
+  await assert.doesNotReject(
+    handleActivateEvent({
+      handleActivate: async () => {
+        throw new Error("handoff read failed");
+      },
+      log: (message) => logs.push(message),
+    }),
+  );
+
+  assert.equal(logs.length, 1);
+  assert.match(logs[0], /activate handling failed: handoff read failed/);
+});
+
+test("activate handler does not log successful activation", async () => {
+  const logs: string[] = [];
+
+  await handleActivateEvent({
+    handleActivate: async () => {},
+    log: (message) => logs.push(message),
+  });
+
+  assert.deepEqual(logs, []);
+});