@paradigma-inc/flywheel 0.2.29 → 0.2.31

package/src/runtime/vendor/flywheel-cli-dist/generatedProductTelemetryContract.js.map

@@ -1 +1 @@
-{"version":3,"file":"generatedProductTelemetryContract.js","sourceRoot":"","sources":["../src/generatedProductTelemetryContract.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,uBAAuB;AAEvB,MAAM,CAAC,MAAM,kCAAkC,GAAG,cAAuB,CAAC;AAE1E,MAAM,CAAC,MAAM,6BAA6B,GAAG;IAC3C,+BAA+B;IAC/B,6BAA6B;IAC7B,+BAA+B;IAC/B,0BAA0B;IAC1B,4BAA4B;IAC5B,cAAc;IACd,cAAc;IACd,oBAAoB;IACpB,mBAAmB;IACnB,sBAAsB;IACtB,qBAAqB;IACrB,gCAAgC;IAChC,mCAAmC;IACnC,+BAA+B;IAC/B,sBAAsB;IACtB,gBAAgB;IAChB,4BAA4B;IAC5B,6BAA6B;IAC7B,6BAA6B;IAC7B,8BAA8B;IAC9B,6BAA6B;IAC7B,gCAAgC;IAChC,mBAAmB;IACnB,sBAAsB;IACtB,4BAA4B;IAC5B,wBAAwB;IACxB,oBAAoB;IACpB,oCAAoC;IACpC,iCAAiC;IACjC,+BAA+B;IAC/B,+BAA+B;IAC/B,qCAAqC;IACrC,0BAA0B;IAC1B,uBAAuB;IACvB,kBAAkB;IAClB,8BAA8B;IAC9B,2BAA2B;IAC3B,4BAA4B;IAC5B,wBAAwB;IACxB,kBAAkB;IAClB,gCAAgC;IAChC,0BAA0B;IAC1B,wBAAwB;IACxB,iBAAiB;IACjB,yBAAyB;IACzB,sBAAsB;IACtB,qBAAqB;IACrB,uBAAuB;IACvB,8BAA8B;IAC9B,2BAA2B;IAC3B,yBAAyB;IACzB,uBAAuB;IACvB,iCAAiC;IACjC,yBAAyB;IACzB,iBAAiB;IACjB,0BAA0B;IAC1B,wBAAwB;IACxB,0BAA0B;IAC1B,uBAAuB;IACvB,wBAAwB;IACxB,qBAAqB;IACrB,gCAAgC;IAChC,6BAA6B;CACrB,CAAC;AAIX,MAAM,CAAC,MAAM,0BAA0B,GAAG;IACxC,KAAK;IACL,YAAY;IACZ,KAAK;IACL,KAAK;IACL,QAAQ;IACR,OAAO;CACC,CAAC;AAIX,MAAM,CAAC,MAAM,mCAAmC,GAAG;IACjD,gBAAgB;IAChB,4BAA4B;IAC5B,6BAA6B;IAC7B,6BAA6B;IAC7B,8BAA8B;IAC9B,6BAA6B;IAC7B,gCAAgC;IAChC,mBAAmB;IACnB,sBAAsB;IACtB,4BAA4B;IAC5B,wBAAwB;IACxB,oBAAoB;IACpB,oCAAoC;IACpC,iCAAiC;IACjC,+BAA+B;IAC/B,+BAA+B;IAC/B,qCAAqC;IACrC,0BAA0B;IAC1B,uBAAuB;IACvB,kBAAkB;IAClB,8BAA8B;IAC9B,2BAA2B;IAC3B,4BAA4B;IAC5B,wBAAwB;IACxB,kBAAkB;IAClB,gCAAgC;IAChC,0BAA0B;IAC1B,wBAAwB;IACxB,iBAAiB;IACjB,yBAAyB;IACzB,sBAAsB;IACtB,qBAAqB;IACrB,uBAAuB;IACvB,8BAA8B;IAC9B,2BAA2B;IAC3B,yBAAyB;IACzB,uBAAuB;IACvB,iCAAiC;IACjC,yBAAyB;IACzB,iBAAiB;IACjB,0BAA0B;IAC1B,wBAAwB;IACxB,0BAA0B;IAC1B,uBAAuB;IACvB,wBAAwB;IACxB,qBAAqB;IACrB,gCAAgC;IAChC,6BAA6B;CACrB,CAAC;AAIX,MAAM,CAAC,MAAM,4BAA4B,GAAG;IAC1C,WAAW;IACX,QAAQ;IACR,oBAAoB;IACpB,QAAQ;IACR,QAAQ;IACR,cAAc;IACd,cAAc;IACd,OAAO;IACP,OAAO;IACP,SAAS;IACT,YAAY;IACZ,gBAAgB;IAChB,WAAW;IACX,gBAAgB;IAChB,mBAAmB;IACnB,uBAAuB;IACvB,aAAa;IACb,cAAc;IACd,aAAa;IACb,MAAM;IACN,iBAAiB;CACT,CAAC;AAIX,MAAM,CAAC,MAAM,gCAAgC,GAAG;IAC9C,aAAa;IACb,6BAA6B;IAC7B,mBAAmB;IACnB,aAAa;IACb,uBAAuB;IACvB,8BAA8B;IAC9B,WAAW;IACX,wBAAwB;IACxB,uBAAuB;IACvB,kBAAkB;IAClB,gBAAgB;IAChB,sBAAsB;IACtB,wBAAwB;IACxB,mBAAmB;IACnB,iCAAiC;IACjC,yBAAyB;IACzB,0BAA0B;IAC1B,2BAA2B;IAC3B,aAAa;IACb,uBAAuB;IACvB,sBAAsB;IACtB,kBAAkB;IAClB,oBAAoB;IACpB,eAAe;IACf,oBAAoB;IACpB,eAAe;IACf,aAAa;IACb,YAAY;IACZ,qBAAqB;IACrB,cAAc;IACd,gBAAgB;IAChB,iBAAiB;IACjB,2BAA2B;CACnB,CAAC;AAIX,MAAM,CAAC,MAAM,6BAA6B,GAAG,IAAI,CAAC,KAAK,CACrD,itJAAitJ,CAC7qJ,CAAC;AAEvC,MAAM,CAAC,MAAM,kCAAkC,GAC7C,IAAI,CAAC,KAAK,CACR,i994BAAi994B,CACl994B,CAAC"}
+{"version":3,"file":"generatedProductTelemetryContract.js","sourceRoot":"","sources":["../src/generatedProductTelemetryContract.ts"],"names":[],"mappings":"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"}

package/src/runtime/vendor/manifest.json

@@ -1,5 +1,5 @@
 {
-  "sourceDigest": "sha256:d9e81d93a26e2afff24ba2a773aaf8913645bf2395ecb0b3320dbaaf94370404",
+  "sourceDigest": "sha256:8dc86325003b086c0d36470bfd6ecddf341c4bc7ef61df112d9dfc1ff3560e79",
   "files": [
     "auth/active-key-id.js",
     "auth/active-key-id.js.map",

package/src/setup/modes/cli.mjs

@@ -199,6 +199,7 @@ export async function runCliSetupMode({
   cleanupSkillArtifactsForHosts = cleanupInstalledSkillArtifactsForHosts,
   removeDir = rm,
   resolveSetupApiKeyFn = resolveSetupApiKey,
+  onStartRetry,
   writeRuntimeConfigFn = writeRuntimeConfig,
   validateRemoteReadinessFn = validateCandidateRemoteReadiness,
   resolveFlywheelBinaryPath = resolveFlywheelBinaryOnPath,
@@ -313,6 +314,9 @@ export async function runCliSetupMode({
           authMode,
         },
         baseUrl,
+        // Presentation-only progress for scheduled start retries; never part
+        // of the setup result.
+        onStartRetry,
       });
       await validateRemoteReadinessFn({
         baseUrl,

package/src/setup/modes/mcp-command.mjs

@@ -20,7 +20,10 @@ import {
  readYamlConfig,
  resolveMcpPath,
 } from "../../mcp-writer.mjs";
-import { resolveSetupApiKey } from "../../setup-auth.mjs";
+import {
+ formatStartRetryMessage,
+ resolveSetupApiKey,
+} from "../../setup-auth.mjs";
 import {
  cleanupInstalledSkillArtifactsForHosts,
  formatSupportedInstallSkillHosts,
@@ -319,20 +322,31 @@ async function resolveHosts(options, scope, serverName, allowPrompt = true) {
  return selected;
 }
 
-async function resolveApiKey(options, baseUrl) {
+async function resolveApiKey(
+ options,
+ baseUrl,
+ {
+  resolveSetupApiKeyFn = resolveSetupApiKey,
+  createAuthSpinner = (text) => ora(text).start(),
+ } = {},
+) {
  if (Object.hasOwn(options, "apiKey")) {
-  const resolved = await resolveSetupApiKey({
+  const resolved = await resolveSetupApiKeyFn({
    options,
    baseUrl,
   });
   return resolved.apiKey;
  }
 
- const spinner = ora("Configuring authentication...").start();
+ const spinner = createAuthSpinner("Configuring authentication...");
  try {
-  const resolved = await resolveSetupApiKey({
+  const resolved = await resolveSetupApiKeyFn({
    options,
    baseUrl,
+   // Retry progress is presentation-only: update the current spinner text.
+   onStartRetry: (progress) => {
+    spinner.text = formatStartRetryMessage(progress);
+   },
   });
   spinner.succeed(`Authenticated (${resolved.authMode})`);
   return resolved.apiKey;
@@ -586,6 +600,8 @@ function printSetupResultSummary(setupResult) {
 
 export async function runMcpModeCommand(options, deps = {}) {
  const projectRoot = process.cwd();
+ const detectPriorModeFn = deps.detectPriorModeForSetupFn ?? detectPriorModeForSetup;
+ const installSkillForHostsFn = deps.installSkillForHosts ?? installBundledSkillForHosts;
  const skillDecisionMode = normalizeSkillDecisionMode(options);
  const guidedSkillDecisionOverride = getGuidedSkillDecisionOverrideForTests();
  const nonInteractive = process.stdout.isTTY !== true;
@@ -682,12 +698,12 @@ export async function runMcpModeCommand(options, deps = {}) {
 
  // Capture prior-mode state before any install/auth side effects so the
  // detector does not classify artifacts created by this same command as
- // pre-existing CLI-mode installs, and so a refuse or reconcile decision
- // happens before we touch disk or start a browser auth flow. Running this
- // inside runMcpSetupMode (the prior placement) meant --force would uninstall
- // the freshly installed bundled skills, and the non-force path would still
- // have run auth before surfacing the conflict.
- const priorModeSnapshot = await detectPriorModeForSetup({
+ // pre-existing CLI-mode installs, and so a refuse decision happens before we
+ // touch disk or start a browser auth flow. Running this inside
+ // runMcpSetupMode (the prior placement) meant --force would uninstall the
+ // freshly installed bundled skills, and the non-force path would still have
+ // run auth before surfacing the conflict.
+ const priorModeSnapshot = await detectPriorModeFn({
   targetMode: "mcp",
   selectedHosts: hosts,
   scope,
@@ -695,11 +711,12 @@ export async function runMcpModeCommand(options, deps = {}) {
   serverName,
   serverUrl,
  });
- const reconciled = [];
- if (
-  priorModeSnapshot.priorMode &&
-  priorModeSnapshot.affectedHosts.length > 0
- ) {
+ // Conflict detection itself performs no write, so it stays ahead of
+ // authentication; the refusal and dependency checks below only throw.
+ const hasPriorModeConflict =
+  Boolean(priorModeSnapshot.priorMode) &&
+  priorModeSnapshot.affectedHosts.length > 0;
+ if (hasPriorModeConflict) {
   if (deps.force !== true) {
    throw new SetupModeUsageError(
     formatPriorModeConflictError(priorModeSnapshot),
@@ -710,37 +727,6 @@ export async function runMcpModeCommand(options, deps = {}) {
     "reconcilePriorMode dependency is required when --force is used.",
    );
   }
-  const reconcileEntries = Array.isArray(priorModeSnapshot.entries)
-   ? priorModeSnapshot.entries
-   : priorModeSnapshot.affectedHosts.map((hostName) => ({
-    hostName,
-    serverNames: [],
-   }));
-  for (const entry of reconcileEntries) {
-   try {
-    // eslint-disable-next-line no-await-in-loop
-    await deps.reconcilePriorMode({
-     priorMode: priorModeSnapshot.priorMode,
-     targetMode: "mcp",
-     hostNames: [entry.hostName],
-     serverNames: entry.serverNames,
-     scope,
-     cwd: projectRoot,
-     serverName,
-     serverUrl,
-    });
-   } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    const reconcileError = new Error(
-     `Failed to reconcile prior --mode ${priorModeSnapshot.priorMode} artifacts for host ${entry.hostName}: ${message}`,
-    );
-    reconcileError.exitCode = 4;
-    throw reconcileError;
-   }
-  }
-  reconciled.push(
-   `removed prior --mode ${priorModeSnapshot.priorMode} artifacts for host(s): ${priorModeSnapshot.affectedHosts.join(", ")}`,
-  );
  }
 
  const installDriftHosts = driftHosts;
@@ -757,8 +743,61 @@ export async function runMcpModeCommand(options, deps = {}) {
   );
  }
 
+ // FLY-1112: authentication must finish before every configuration,
+ // reconciliation, and skill-install mutation, so a failed (or cancelled)
+ // authorization sequence never partially reconfigures the machine.
+ let apiKey = null;
+ const explicitApiKeyProvided = Object.hasOwn(options, "apiKey") || options.apiKeyStdin === true;
+ const shouldResolveApiKey =
+  !oauthMode && (needsSetupHosts.length > 0 || explicitApiKeyProvided);
+ if (shouldResolveApiKey) {
+  apiKey = authResult?.apiKey ?? await resolveApiKey(options, baseUrl, {
+   resolveSetupApiKeyFn: deps.resolveSetupApiKeyFn,
+   createAuthSpinner: deps.createAuthSpinner,
+  });
+  if (!apiKey) {
+   log.warn("Setup cancelled");
+   return { exitCode: 0 };
+  }
+ }
+
+ const reconciled = [];
  let cleanupState = null;
  try {
+  if (hasPriorModeConflict) {
+   const reconcileEntries = Array.isArray(priorModeSnapshot.entries)
+    ? priorModeSnapshot.entries
+    : priorModeSnapshot.affectedHosts.map((hostName) => ({
+     hostName,
+     serverNames: [],
+    }));
+   for (const entry of reconcileEntries) {
+    try {
+     // eslint-disable-next-line no-await-in-loop
+     await deps.reconcilePriorMode({
+      priorMode: priorModeSnapshot.priorMode,
+      targetMode: "mcp",
+      hostNames: [entry.hostName],
+      serverNames: entry.serverNames,
+      scope,
+      cwd: projectRoot,
+      serverName,
+      serverUrl,
+     });
+    } catch (error) {
+     const message = error instanceof Error ? error.message : String(error);
+     const reconcileError = new Error(
+      `Failed to reconcile prior --mode ${priorModeSnapshot.priorMode} artifacts for host ${entry.hostName}: ${message}`,
+     );
+     reconcileError.exitCode = 4;
+     throw reconcileError;
+    }
+   }
+   reconciled.push(
+    `removed prior --mode ${priorModeSnapshot.priorMode} artifacts for host(s): ${priorModeSnapshot.affectedHosts.join(", ")}`,
+   );
+  }
+
   if (skillDecisionMode === "install") {
    logBundledSkillInstallPlan({
     bundledSkillNames,
@@ -772,7 +811,7 @@ export async function runMcpModeCommand(options, deps = {}) {
     scope,
     skillNames: bundledSkillNames,
    });
-   await installBundledSkillForHosts({
+   await installSkillForHostsFn({
     projectRoot,
     hostNames: supportedHosts,
     scope,
@@ -787,28 +826,6 @@ export async function runMcpModeCommand(options, deps = {}) {
    }
   }
 
-  let apiKey = null;
-  const explicitApiKeyProvided = Object.hasOwn(options, "apiKey") || options.apiKeyStdin === true;
-  const shouldResolveApiKey =
-   !oauthMode && (needsSetupHosts.length > 0 || explicitApiKeyProvided);
-  if (shouldResolveApiKey) {
-   apiKey = authResult?.apiKey ?? await resolveApiKey(options, baseUrl);
-   if (!apiKey) {
-    if (cleanupState) {
-     await cleanupInstalledSkillArtifactsForHosts({
-      projectRoot,
-      hostNames: supportedHosts,
-      priorState: cleanupState,
-      scope,
-      skillNames: bundledSkillNames,
-     });
-     cleanupState = null;
-    }
-    log.warn("Setup cancelled");
-    return { exitCode: 0 };
-   }
-  }
-
   const setupResult = await runMcpSetupMode({
    selectedHosts: hosts,
    scope,
@@ -927,7 +944,7 @@ export async function runMcpModeCommand(options, deps = {}) {
    scope,
    skillNames: bundledSkillNames,
   });
-  await installBundledSkillForHosts({
+  await installSkillForHostsFn({
    projectRoot,
    hostNames: supportedHosts,
    scope,

package/src/setup-auth.mjs

@@ -7,11 +7,25 @@ import { isatty } from "node:tty";
 import { setTimeout as delay } from "node:timers/promises";
 
 import { SetupInputUsageError } from "./setup/mode.mjs";
+import {
+  isRetryableNetworkError,
+  isRetryableStatus,
+  parseRetryAfterMs,
+  withRetry,
+} from "./runtime/vendor/flywheel-cli-dist/http/retry.js";
 
 const DEFAULT_AUTH_TIMEOUT_MS = 5 * 60 * 1000;
 const MIN_POLL_DELAY_MS = 1000;
 const MAX_POLL_DELAY_MS = 10_000;
 const SETUP_DEVICE_API_PREFIX = "/api/v1/auth/mcp-api-keys/setup-device";
+// FLY-1112: the setup-device start request is retried through the bundled
+// helper. One logical request (body, idempotency key, request ID) is reused
+// across at most three attempts; each attempt gets a fresh signal of at most
+// 15s, and the whole recovery sequence is bounded by 49s so a temporary
+// routing failure fails fast instead of pinning the spinner for two minutes.
+const START_ATTEMPT_TIMEOUT_MS = 15_000;
+const START_RECOVERY_BUDGET_MS = 49_000;
+const START_MAX_ATTEMPTS = 3;
 const readDescriptor = promisify(readFd);
 
 async function readStdin(fd, buffer, offset, length, position) {
@@ -211,77 +225,246 @@ export function normalizeSetupAuthMode(value) {
 //   return { apiKey: key };
 // }
 
+export function formatStartRetryMessage({ nextAttempt, maxAttempts }) {
+  return `Flywheel is taking longer than expected; retrying (${nextAttempt} of ${maxAttempts})...`;
+}
+
+// A retryable-class start failure: local attempt timeout, recognized
+// temporary network error, or accepted HTTP status. Carries the structured
+// summary used for progress callbacks and the exhausted-attempts error, plus
+// the original error so non-retried failures retain their existing detail.
+class StartAttemptFailure extends Error {
+  constructor(failure, cause, { retryAfter = null, returnAsIs = false } = {}) {
+    super(cause.message);
+    this.failure = failure;
+    this.cause = cause;
+    this.retryAfter = retryAfter;
+    this.returnAsIs = returnAsIs;
+  }
+}
+
+// Internal sentinels: the sleep gate raises these when the next attempt can
+// no longer fit inside a deadline; the outer catch maps them to the exact
+// public error messages.
+class StartRecoveryExhausted extends Error {
+  constructor(failure) {
+    super("start recovery budget exhausted");
+    this.failure = failure;
+  }
+}
+class StartAuthorizationDeadline extends Error {}
+
+function startFailureDescription(failure) {
+  return failure.kind === "http" ? `HTTP ${failure.status}` : failure.kind;
+}
+
 async function startSetupDeviceSession({
   baseUrl,
   keyName,
   verificationBaseUrl,
-  remainingMs,
+  authorizationDeadlineMs,
+  now = Date.now,
+  fetchFn = fetch,
+  sleep = defaultSleep,
+  random = Math.random,
+  createTimeoutSignal = AbortSignal.timeout,
+  onStartRetry,
 }) {
   const startUrl = new URL(`${SETUP_DEVICE_API_PREFIX}/start`, baseUrl);
-  const startTimeoutSignal = AbortSignal.timeout(remainingMs);
-  let response;
-  let payload;
+  // One logical request: serialized body, idempotency key, and request ID are
+  // created once before attempt 1 and reused unchanged on every attempt so the
+  // server can replay the first unexpired session instead of duplicating it.
+  const body = JSON.stringify({
+    name: keyName,
+    verification_base_url: verificationBaseUrl,
+  });
+  const idempotencyKey = `setup-device-start:${crypto.randomUUID()}`;
+  const requestId = crypto.randomUUID();
+  const recoveryDeadlineMs = Math.min(
+    authorizationDeadlineMs,
+    now() + START_RECOVERY_BUDGET_MS,
+  );
+  // Tracks the most recently classified retryable failure so a budget
+  // guard reached at the top of a later attempt (see attemptStart below)
+  // can still attribute exhaustion to the retry sequence instead of the
+  // generic authorization timeout, matching gatedSleep's own attribution.
+  let lastFailure = null;
+
+  const attemptStart = async () => {
+    const signalBudgetMs = Math.min(
+      START_ATTEMPT_TIMEOUT_MS,
+      authorizationDeadlineMs - now(),
+      recoveryDeadlineMs - now(),
+    );
+    if (signalBudgetMs <= 0) {
+      // Ordinarily unreachable: the caller guards the authorization deadline
+      // before the first attempt, and gatedSleep already re-checks this same
+      // budget before scheduling any later attempt's sleep. Kept as a
+      // defensive fallback for real-world sleep/timer overrun (the actual
+      // wait exceeding the requested delay) between gatedSleep's check and
+      // this attempt actually starting.
+      if (recoveryDeadlineMs < authorizationDeadlineMs && lastFailure) {
+        throw new StartRecoveryExhausted(lastFailure);
+      }
+      throw new StartAuthorizationDeadline();
+    }
+    const signal = createTimeoutSignal(signalBudgetMs);
+    let response;
+    let payload;
+    try {
+      response = await fetchFn(startUrl, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          "Idempotency-Key": idempotencyKey,
+          "X-Flywheel-Surface": "cli",
+          "X-Flywheel-Request-Id": requestId,
+          "X-Request-ID": requestId,
+        },
+        body,
+        signal,
+      });
+      payload = await parseJsonResponse(response, { signal });
+    } catch (error) {
+      // Only an abort of this attempt's own signal is a local timeout.
+      if (signal.aborted) {
+        throw new StartAttemptFailure({ kind: "timeout" }, error);
+      }
+      if (isRetryableNetworkError(error)) {
+        throw new StartAttemptFailure({ kind: "network" }, error);
+      }
+      throw error;
+    }
+    if (!response.ok) {
+      const detail = resolveErrorMessage(payload, "Failed to start setup device flow.");
+      throw new StartAttemptFailure(
+        { kind: "http", status: response.status },
+        new Error(detail),
+        { retryAfter: response.headers?.get?.("retry-after") ?? null },
+      );
+    }
+
+    const deviceCode = nonEmptyString(payload.device_code);
+    const userCode = nonEmptyString(payload.user_code);
+    const verificationUri = nonEmptyString(payload.verification_uri);
+    const verificationUriComplete = nonEmptyString(payload.verification_uri_complete);
+    const pollIntervalSeconds = Number(payload.poll_interval_seconds);
+    const expiresInSeconds = Number(payload.expires_in_seconds);
+
+    if (!deviceCode || !userCode || !verificationUri || !verificationUriComplete) {
+      throw new Error("Setup device session response missing required fields.");
+    }
+    if (
+      !Number.isFinite(pollIntervalSeconds) ||
+      pollIntervalSeconds <= 0 ||
+      !Number.isFinite(expiresInSeconds) ||
+      expiresInSeconds <= 0
+    ) {
+      throw new Error("Setup device session response contained invalid timing values.");
+    }
+
+    return {
+      deviceCode,
+      userCode,
+      verificationUri,
+      verificationUriComplete,
+      pollIntervalSeconds: Math.floor(pollIntervalSeconds),
+      expiresInSeconds: Math.floor(expiresInSeconds),
+    };
+  };
+
+  let pendingRetry = null;
+  // A retry is scheduled only when the delay plus a full 15s next attempt still
+  // fits inside the recovery budget. The gate runs before the progress
+  // callback so "retrying" is announced only when another attempt will happen.
+  const gatedSleep = async (delayMs) => {
+    const { nextAttempt, failure } = pendingRetry;
+    pendingRetry = null;
+    if (now() + delayMs + START_ATTEMPT_TIMEOUT_MS > recoveryDeadlineMs) {
+      if (recoveryDeadlineMs === authorizationDeadlineMs) {
+        throw new StartAuthorizationDeadline();
+      }
+      throw new StartRecoveryExhausted(failure);
+    }
+    try {
+      onStartRetry?.({
+        nextAttempt,
+        maxAttempts: START_MAX_ATTEMPTS,
+        delayMs,
+        requestId,
+        failure,
+      });
+    } catch {
+      // Presentation is best-effort and must not change retry behavior.
+    }
+    await sleep(delayMs);
+  };
+
   try {
-    response = await fetch(startUrl, {
-      method: "POST",
-      headers: {
-        "content-type": "application/json",
-        "Idempotency-Key": `setup-device-start:${crypto.randomUUID()}`,
+    return await withRetry(attemptStart, {
+      maxAttempts: START_MAX_ATTEMPTS,
+      sleep: gatedSleep,
+      random,
+      shouldRetry: (error, attempt) => {
+        if (!(error instanceof StartAttemptFailure) || error.returnAsIs) {
+          return { retry: false };
+        }
+        const { failure } = error;
+        if (failure.kind === "http") {
+          if (!isRetryableStatus(failure.status)) {
+            return { retry: false };
+          }
+          const retryAfterMs = parseRetryAfterMs(error.retryAfter);
+          if (retryAfterMs !== null) {
+            // A valid Retry-After replaces the helper's delay only when it
+            // leaves room for the remaining 15s attempts; otherwise the
+            // current HTTP failure is returned unchanged.
+            if (now() + retryAfterMs + START_ATTEMPT_TIMEOUT_MS <= recoveryDeadlineMs) {
+              pendingRetry = { nextAttempt: attempt + 1, failure };
+              lastFailure = failure;
+              return { retry: true, delayMs: retryAfterMs };
+            }
+            error.returnAsIs = true;
+            return { retry: false };
+          }
+        }
+        pendingRetry = { nextAttempt: attempt + 1, failure };
+        lastFailure = failure;
+        return { retry: true };
       },
-      body: JSON.stringify({
-        name: keyName,
-        verification_base_url: verificationBaseUrl,
-      }),
-      signal: startTimeoutSignal,
     });
-    payload = await parseJsonResponse(response, { signal: startTimeoutSignal });
   } catch (error) {
-    if (startTimeoutSignal.aborted) {
+    if (error instanceof StartAuthorizationDeadline) {
       throw new Error("Timed out waiting for device authorization.");
     }
+    if (error instanceof StartRecoveryExhausted) {
+      throw new Error(
+        `Failed to start device authorization after ${START_MAX_ATTEMPTS} attempts (last failure: ${startFailureDescription(error.failure)}; request ID: ${requestId}). Run the same setup command again.`,
+      );
+    }
+    if (error instanceof StartAttemptFailure) {
+      const retryableClass =
+        error.failure.kind !== "http" || isRetryableStatus(error.failure.status);
+      if (retryableClass && !error.returnAsIs) {
+        // A retryable failure escaping withRetry means the final attempt
+        // failed; report the exhausted sequence with request correlation.
+        throw new Error(
+          `Failed to start device authorization after ${START_MAX_ATTEMPTS} attempts (last failure: ${startFailureDescription(error.failure)}; request ID: ${requestId}). Run the same setup command again.`,
+        );
+      }
+      throw error.cause;
+    }
     throw error;
   }
-  if (!response.ok) {
-    const detail = resolveErrorMessage(payload, "Failed to start setup device flow.");
-    throw new Error(detail);
-  }
-
-  const deviceCode = nonEmptyString(payload.device_code);
-  const userCode = nonEmptyString(payload.user_code);
-  const verificationUri = nonEmptyString(payload.verification_uri);
-  const verificationUriComplete = nonEmptyString(payload.verification_uri_complete);
-  const pollIntervalSeconds = Number(payload.poll_interval_seconds);
-  const expiresInSeconds = Number(payload.expires_in_seconds);
-
-  if (!deviceCode || !userCode || !verificationUri || !verificationUriComplete) {
-    throw new Error("Setup device session response missing required fields.");
-  }
-  if (
-    !Number.isFinite(pollIntervalSeconds) ||
-    pollIntervalSeconds <= 0 ||
-    !Number.isFinite(expiresInSeconds) ||
-    expiresInSeconds <= 0
-  ) {
-    throw new Error("Setup device session response contained invalid timing values.");
-  }
-
-  return {
-    deviceCode,
-    userCode,
-    verificationUri,
-    verificationUriComplete,
-    pollIntervalSeconds: Math.floor(pollIntervalSeconds),
-    expiresInSeconds: Math.floor(expiresInSeconds),
-  };
 }
 
-async function pollSetupDeviceSession({ baseUrl, userCode, deviceCode }) {
+async function pollSetupDeviceSession({ baseUrl, userCode, deviceCode, fetchFn = fetch, now = Date.now }) {
   const pollUrl = new URL(`${SETUP_DEVICE_API_PREFIX}/poll`, baseUrl);
-  const response = await fetch(pollUrl, {
+  const response = await fetchFn(pollUrl, {
     method: "POST",
     headers: {
       "content-type": "application/json",
-      "Idempotency-Key": `setup-device-poll:${deviceCode}:${Date.now()}`,
+      "Idempotency-Key": `setup-device-poll:${deviceCode}:${now()}`,
     },
     body: JSON.stringify({
       user_code: userCode,
@@ -377,6 +560,12 @@ export async function resolveSetupApiKey({
   acquireDeviceFlow = acquireApiKeyViaDeviceFlow,
   acquireBrowserBridge = acquireApiKeyViaBrowserBridge,
   keyNameFactory = () => `flywheel-setup-${crypto.randomBytes(3).toString("hex")}`,
+  fetchFn,
+  now,
+  sleep,
+  random,
+  createTimeoutSignal,
+  onStartRetry,
 } = {}) {
   // Check the value, not just property presence: callers like runCliSetupMode
   // always forward `{apiKey, authMode}` to share one helper shape, so the
@@ -410,6 +599,12 @@ export async function resolveSetupApiKey({
         baseUrl,
         keyName,
         verificationBaseUrl: baseUrl,
+        fetchFn,
+        now,
+        sleep,
+        random,
+        createTimeoutSignal,
+        onStartRetry,
       })
       : await acquireBrowserBridge({
         baseUrl,
@@ -594,17 +789,28 @@ export async function acquireApiKeyViaDeviceFlow({
   timeoutMs = DEFAULT_AUTH_TIMEOUT_MS,
   openUrl = openUrlInBrowser,
   sleep = defaultSleep,
+  fetchFn = fetch,
+  now = Date.now,
+  random = Math.random,
+  createTimeoutSignal = AbortSignal.timeout,
+  onStartRetry,
 }) {
-  const startedAt = Date.now();
-  const remainingMs = timeoutMs - (Date.now() - startedAt);
-  if (remainingMs <= 0) {
+  const startedAt = now();
+  const authorizationDeadlineMs = startedAt + timeoutMs;
+  if (authorizationDeadlineMs - now() <= 0) {
     throw new Error("Timed out waiting for device authorization.");
   }
   const session = await startSetupDeviceSession({
     baseUrl,
     keyName,
     verificationBaseUrl,
-    remainingMs,
+    authorizationDeadlineMs,
+    now,
+    fetchFn,
+    sleep,
+    random,
+    createTimeoutSignal,
+    onStartRetry,
   });
 
   console.log("Opening browser for Flywheel device authorization...");
@@ -617,12 +823,14 @@ export async function acquireApiKeyViaDeviceFlow({
   launchBrowser(openUrl, session.verificationUriComplete);
 
   let attempt = 0;
-  while (Date.now() - startedAt < timeoutMs) {
+  while (now() - startedAt < timeoutMs) {
     // eslint-disable-next-line no-await-in-loop
     const pollResult = await pollSetupDeviceSession({
       baseUrl,
       userCode: session.userCode,
       deviceCode: session.deviceCode,
+      fetchFn,
+      now,
     });
     if (pollResult.status === "approved") {
       return { apiKey: pollResult.apiKey };