@@ -51,7 +51,7 @@ void platform install \
 
 Mutations require `--yes` in CI; a read-only `--plan` does not. Custom runtimes also require `--runtime <directory>`. For a new installation, run `--plan` with the same account, name, and domain options as the unattended install. If you use `--auth-config`, pass the same file to both commands. Register `<platform-api-url>/auth/callback` when creating a login provider's OAuth or OIDC client manually; automatic Access setup manages its own application. A custom API hostname is optional.
 
-In CI, `upgrade`, `repair`, `enable`, `rollback`, and `install --resume` stop before they change anything when a platform Worker was changed in the Cloudflare dashboard or with the Cloudflare API, or has an active version without a Void deployment record. See [Platform Workers changed outside Void](/guide/platform/installation/maintenance#workers-changed-outside-void).
+In CI, `upgrade`, `repair`, `enable`, `rollback`, and `install --resume` stop before they change a platform Worker or pause traffic when a platform Worker was changed in the Cloudflare dashboard or with the Cloudflare API, or has an active version without a Void deployment record. See [Platform Workers changed outside Void](/guide/platform/installation/maintenance#workers-changed-outside-void).
 
 :::
 
 
@@ -149,7 +149,7 @@ Let running rotations finish before you roll back. If an older proxy runs next t
 
 Void manages the platform's own Workers. Do not change them in the Cloudflare dashboard or with the Cloudflare API. To change the platform, use the Void commands on this page.
 
-`upgrade`, `repair`, `enable`, `rollback`, and `install --resume` deploy the platform Workers again. Before they change anything, Void finds each platform Worker that:
+`upgrade`, `repair`, `enable`, `rollback`, and `install --resume` deploy the platform Workers again. Before they change a platform Worker or pause traffic, Void finds each platform Worker that:
 
 - was changed in the Cloudflare dashboard or with the Cloudflare API.
 - has an active version without a Void deployment record. This can occur when an earlier run replaced a change made outside Void, and then stopped or failed. If that run stopped during the cutover to the new version, the command first makes the earlier versions active again. Void checks those earlier versions too. A version that an older Void release deployed can also have no record.
@@ -158,14 +158,16 @@ The `--plan` preview of `upgrade`, `repair`, `enable`, and `rollback` shows the
 
 In a terminal, Void lists these Workers and asks **Replace the configuration of these Workers?** The default answer is No.
 
-- If you answer No, the command stops. Nothing changed, and the command did not pause traffic.
+- If you answer No, the command stops. No platform Worker changed, and the command did not pause traffic.
 - If you answer Yes, the command continues. First, Void prepares the platform resources and the database. Then, before it pauses traffic or deploys a Worker, the Cloudflare CLI asks you again for each Worker changed in the dashboard or with the API. For a dashboard change, it shows the differences. Void uploads a new version of each of these Workers and does not deploy it yet. For a Worker that has an active version without a Void deployment record, the Cloudflare CLI does not ask again.
 
 If you refuse in the Cloudflare CLI, the command stops. Void does not undo the resource and database changes. No deployment changed, and the command did not pause traffic.
 
 The replacement removes values that Void does not set, for example an `EMAIL_FROM` variable that you added. It also resets values that Void sets, for example `AUTH_REDIRECT_URI`.
 
-Without a terminal, for example in CI, or with `--yes`, the command stops before it changes anything, and it does not pause traffic. Run the command that Void prints once in a terminal, and answer the questions there. After that run completes, the command works in CI again.
+Without a terminal, for example in CI, or with `--yes`, the command stops before it changes a platform Worker, and it does not pause traffic. Run the command that Void prints once in a terminal, and answer the questions there. After that run completes, the command works in CI again.
+
+If Void cannot read a platform Worker, the command also stops before it changes a platform Worker or pauses traffic. Run the command again. If a platform Worker has no single version that gets 100% of traffic, for example after a gradual deployment, deploy one version of it to 100% of traffic in the Cloudflare dashboard. Then run the command once in a terminal, so that you can approve the dashboard change.
 
 If an earlier run failed after it paused traffic, traffic stays paused after these stops. To resume traffic, see [Upgrade the platform](#upgrade-the-platform).
 
 
@@ -137,7 +137,7 @@ After discovery on another machine, set `VOID_PLATFORM_DATABASE_URL`. See [Manag
 
 Repair and upgrade preserve disabled state. New, resumed, and previously disabled installations block user traffic until all target Workers pass verification; the installer's health probes can still run. Routes and custom domains remain attached.
 
-If a platform Worker was changed outside Void, or has an active version without a Void deployment record, a command that deploys the platform Workers stops before it changes anything or pauses traffic, unless you agree in a terminal to replace the changes. See [Platform Workers changed outside Void](../../guide/platform/installation/maintenance.md#workers-changed-outside-void).
+If a platform Worker was changed outside Void, or has an active version without a Void deployment record, a command that deploys the platform Workers stops before it changes a platform Worker or pauses traffic, unless you agree in a terminal to replace the changes. See [Platform Workers changed outside Void](../../guide/platform/installation/maintenance.md#workers-changed-outside-void).
 
 `--runtime` selects a custom platform build. Relative paths resolve from your current directory. Void verifies the build before making changes; see [Platform Development](../../guide/platform/development/runtime.md#deploying-your-runtime) for creating one.
 
 
@@ -56,45 +56,52 @@ export async function readActivePlatformWorkerVersion(
 }
 
 /**
- * Whether the active version of a platform Worker has Void's record of its
- * triggers. An upgrade refuses an active version without it, for example a
- * version deployed outside Void. This reads the active version as
- * readActivePlatformWorkerVersion does, but through the Cloudflare API. Null
- * when the Worker has no single active version.
+ * The active version in a Cloudflare API answer for the deployments of a
+ * platform Worker. deployPlatformWorker continues only when the latest
+ * deployment sends all traffic to one version (deploymentRunsOnlyVersion).
+ * `split` is each other answer, for example a gradual deployment.
  */
-export async function activePlatformWorkerHasTriggerRecord(
-  readCloudflare: (path: string) => Promise<unknown>,
-  accountId: string,
-  workerName: string,
-): Promise<boolean | null> {
-  const base = `/accounts/${encodeURIComponent(accountId)}/workers/scripts/${encodeURIComponent(workerName)}`;
-  const response = await readCloudflare(`${base}/deployments`);
+export function readActivePlatformWorkerDeployment(
+  response: unknown,
+):
+  | Readonly<{ kind: 'active'; versionId: string }>
+  | Readonly<{ kind: 'malformed' }>
+  | Readonly<{ kind: 'split' }> {
   const deployments =
-    response && typeof response === 'object'
+    response && typeof response === 'object' && !Array.isArray(response)
       ? (response as { deployments?: unknown }).deployments
       : null;
-  const latest = Array.isArray(deployments) ? (deployments[0] as unknown) : null;
+  if (!Array.isArray(deployments)) {
+    return { kind: 'malformed' };
+  }
+  if (deployments.length === 0) {
+    return { kind: 'split' };
+  }
+  const latest: unknown = deployments[0];
   const versions =
     latest && typeof latest === 'object' ? (latest as { versions?: unknown }).versions : null;
-  const active = Array.isArray(versions)
-    ? versions.filter(
-        (entry) =>
-          entry &&
-          typeof entry === 'object' &&
-          Number((entry as { percentage?: unknown }).percentage) === 100,
-      )
-    : [];
-  const versionId =
-    active.length === 1 ? (active[0] as { version_id?: unknown }).version_id : undefined;
-  if (typeof versionId !== 'string') {
-    return null;
+  if (
+    !Array.isArray(versions) ||
+    versions.some(
+      (version) =>
+        !version ||
+        typeof version !== 'object' ||
+        typeof (version as { version_id?: unknown }).version_id !== 'string' ||
+        !Number.isFinite(Number((version as { percentage?: unknown }).percentage)),
+    )
+  ) {
+    return { kind: 'malformed' };
   }
-  return platformWorkerVersionHasTriggerRecord(readCloudflare, accountId, workerName, versionId);
+  const [only] = versions as Array<{ percentage: unknown; version_id: string }>;
+  return versions.length === 1 && only && Number(only.percentage) === 100
+    ? { kind: 'active', versionId: only.version_id }
+    : { kind: 'split' };
 }
 
 /**
  * Whether a version of a platform Worker has Void's record of its triggers.
- * This is the rule of the upgrade: it refuses a version without the record.
+ * This is the rule of the upgrade: it refuses a version without the record,
+ * for example a version deployed outside Void.
  */
 export async function platformWorkerVersionHasTriggerRecord(
   readCloudflare: (path: string) => Promise<unknown>,
 
@@ -1,12 +1,16 @@
+import { setTimeout as delay } from 'node:timers/promises';
 import type { PlatformInstallationManifest } from '@void/platform';
 import type { PlatformRuntime } from '@void/platform/installer';
 import { confirm, isCancel, log, type SpinnerResult } from '@voidzero-dev/vite-plus-prompts';
 import { note } from './output.ts';
-import type { PlatformCloudflareClient } from './platform-cloudflare.ts';
+import {
+  PlatformCloudflareApiError,
+  type PlatformCloudflareClient,
+} from './platform-cloudflare.ts';
 import { interruptedWorkerCutover } from './platform-installer-cutover.ts';
 import {
-  activePlatformWorkerHasTriggerRecord,
   platformWorkerVersionHasTriggerRecord,
+  readActivePlatformWorkerDeployment,
 } from './platform-installer-inspection.ts';
 import { runPlatformWranglerAtApiBase } from './platform-installer-process.ts';
 import type {
@@ -41,6 +45,52 @@ const PLATFORM_WORKER_KEYS: ReadonlyArray<PlatformWorkerKey> = [
   'dispatch',
 ];
 
+// The lifecycle lock can change the database before this check. The check
+// itself changes no Worker and does not pause traffic.
+const NO_WORKER_CHANGED =
+  'No platform Worker changed. This command did not pause application traffic.';
+
+/** The wait before the second and the third read of a Worker. */
+const READ_RETRY_DELAYS_MS = [250, 500] as const;
+
+/** Stop before the run changes a Worker, because Void cannot tell what the run replaces. */
+function unreadablePlatformWorker(workerName: string, error: unknown): Error {
+  const status = error instanceof PlatformCloudflareApiError ? error.status : null;
+  const answer =
+    status === null
+      ? `no HTTP response: ${error instanceof Error ? error.message : String(error)}`
+      : `HTTP ${status}`;
+  return new Error(
+    [
+      `platform: Void cannot read the platform Worker ${workerName} (${answer}), so it cannot find changes made outside Void.`,
+      NO_WORKER_CHANGED,
+      status === 401 || status === 403
+        ? 'Make sure that the Cloudflare API token has Account → Workers Scripts → Edit for this account. Then run the command again.'
+        : 'Run the command again.',
+    ].join(' '),
+    { cause: error },
+  );
+}
+
+/**
+ * Read a Worker again after a rate limit, a Cloudflare server error or a
+ * network failure. Each other failure, or a third failure, stops the run.
+ */
+async function readPlatformWorker<T>(workerName: string, read: () => Promise<T>): Promise<T> {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return await read();
+    } catch (error) {
+      const status = error instanceof PlatformCloudflareApiError ? error.status : null;
+      const wait = READ_RETRY_DELAYS_MS[attempt];
+      if (wait === undefined || (status !== null && status !== 429 && status < 500)) {
+        throw unreadablePlatformWorker(workerName, error);
+      }
+      await delay(wait);
+    }
+  }
+}
+
 export type PlatformWorkerOutsideChange = Readonly<{
   key: PlatformWorkerKey;
   name: string;
@@ -115,35 +165,59 @@ export async function findPlatformWorkerOutsideChanges(
       : new Map<string, string>();
   const changes = await Promise.all(
     workers.map(async (worker): Promise<PlatformWorkerOutsideChange | null> => {
-      // A failed read does not show a change. The upload still reports a real conflict.
-      let source: string | null;
-      try {
-        source = await client.getWorkerLastDeployedFrom(plan.account.id, worker.name);
-      } catch {
-        return null;
+      // A read that fails stops the run. Without the answer, the run can
+      // pause traffic and then fail in the Cloudflare CLI or the upgrade.
+      const readCloudflare = (path: string) =>
+        readPlatformWorker(worker.name, () => client.request<unknown>(path));
+      const source = await readPlatformWorker(worker.name, () =>
+        client.getWorkerLastDeployedFrom(plan.account.id, worker.name),
+      );
+      const deployments = await readPlatformWorker(worker.name, () =>
+        client
+          .request<unknown>(
+            `/accounts/${encodeURIComponent(plan.account.id)}/workers/scripts/${encodeURIComponent(worker.name)}/deployments`,
+          )
+          .catch((error: unknown) => {
+            if (error instanceof PlatformCloudflareApiError && error.status === 404) {
+              return null;
+            }
+            throw error;
+          }),
+      );
+      // No deployments. The installer finds a missing Worker itself, but a
+      // marker from outside Void still makes the Cloudflare CLI stop.
+      if (deployments === null) {
+        return source === 'dash' || source === 'api' ? { ...worker, source } : null;
+      }
+      const active = readActivePlatformWorkerDeployment(deployments);
+      if (active.kind === 'malformed') {
+        throw new Error(
+          `platform: Cloudflare returned malformed deployment data for the platform Worker ${worker.name}, so Void cannot find changes made outside Void. ${NO_WORKER_CHANGED} Run the command again.`,
+        );
+      }
+      // The deploy and the restore of a stopped cutover need one active version.
+      if (active.kind === 'split') {
+        throw new Error(
+          `platform: The platform Worker ${worker.name} has no single version that gets 100% of traffic, for example after a gradual deployment. This command deploys a new version only when one version gets all traffic. ${NO_WORKER_CHANGED} In the Cloudflare dashboard, deploy one version of ${worker.name} to 100% of traffic. Then run this command once in a terminal, so that you can approve the dashboard change.`,
+        );
       }
       if (source === 'dash' || source === 'api') {
         return { ...worker, source };
       }
       // The upgrade reads the active version. After a stopped cutover, the
       // installer first makes the earlier version active again.
-      const readCloudflare = (path: string) => client.request(path);
       const restoredVersion = restored.get(worker.name);
-      const recorded = await Promise.all([
-        activePlatformWorkerHasTriggerRecord(readCloudflare, plan.account.id, worker.name).catch(
-          () => null,
+      const recorded = await Promise.all(
+        [active.versionId, ...(restoredVersion === undefined ? [] : [restoredVersion])].map(
+          (versionId) =>
+            platformWorkerVersionHasTriggerRecord(
+              readCloudflare,
+              plan.account.id,
+              worker.name,
+              versionId,
+            ),
         ),
-        ...(restoredVersion === undefined
-          ? []
-          : [
-              platformWorkerVersionHasTriggerRecord(
-                readCloudflare,
-                plan.account.id,
-                worker.name,
-                restoredVersion,
-              ).catch(() => null),
-            ]),
-      ]);
+      );
       return recorded.includes(false) ? { ...worker, source: 'unrecorded' } : null;
     }),
   );
@@ -167,10 +241,10 @@ export function formatPlatformWorkerOutsideChanges(
 }
 
 /**
- * Do this before a run changes anything. When platform Workers were changed
- * outside Void, stop, or ask the operator in a terminal. Returns the Workers
- * whose outside changes the operator agreed to replace. The installer uploads
- * them later with uploadPlatformWorkerOutsideChanges.
+ * Do this before a run changes a Worker or pauses traffic. When platform
+ * Workers were changed outside Void, stop, or ask the operator in a terminal.
+ * Returns the Workers whose outside changes the operator agreed to replace.
+ * The installer uploads them later with uploadPlatformWorkerOutsideChanges.
  */
 export async function reviewPlatformWorkerOutsideChanges(
   input: Readonly<{
@@ -197,7 +271,7 @@ export async function reviewPlatformWorkerOutsideChanges(
     throw new Error(
       [
         `platform: ${formatPlatformWorkerOutsideChanges(changes)}`,
-        'Nothing changed. This command did not pause application traffic.',
+        NO_WORKER_CHANGED,
         'This command replaces their configuration with the Void configuration. It can ask for your approval only in a terminal.',
         `Run this command once in a terminal to review them:\n${input.command}`,
       ].join('\n'),
@@ -225,9 +299,7 @@ export async function reviewPlatformWorkerOutsideChanges(
     initialValue: false,
   });
   if (isCancel(answer) || typeof answer === 'symbol' || !answer) {
-    throw new Error(
-      'platform: Cancelled. Nothing changed. This command did not pause application traffic.',
-    );
+    throw new Error(`platform: Cancelled. ${NO_WORKER_CHANGED}`);
   }
   return changes;
 }