@caelo-cms/provisioning 0.10.55 → 0.10.57

package/src/infra-contract.ts

@@ -22,7 +22,7 @@
  * whose app-roll references infrastructure an install does not have yet fails
  * at roll time, after migrations ran.
  */
-export const INFRA_CONTRACT_VERSION = 8;
+export const INFRA_CONTRACT_VERSION = 10;
 
 // History (why each bump happened — an install below a number needs the
 // converge that introduced it):
@@ -56,6 +56,25 @@ export const INFRA_CONTRACT_VERSION = 8;
 //       CAELO_AUDIT_RESULTS_BUCKET on the admin. The new admin fans every
 //       Stage audit out to that job, and the app-roll moves the job's image,
 //       so it must exist before an in-cloud upgrader rolls onto it.
+//   9 — #819: the converge job (`caelo-<env>-converge`, converge-job-setup.ts)
+//       that installs contract-bumping releases from Settings → Updates as
+//       the install's caelo-provisioner, its Cloud SQL IAM database login
+//       (platform_updater), the admin's start-only grant on it and
+//       CAELO_CONVERGE_JOB on the admin. Installed by the last converge an
+//       Owner runs by hand; every later one runs from Caelo. The same bump
+//       replaces the upgrader's project-wide roles/run.developer (which
+//       holds run.jobs.runWithOverrides on the provisioner's jobs) with the
+//       custom role caeloUpgraderRun (#883 review). An install without a
+//       caelo-provisioner reaches 9 without the job: there is nothing it
+//       could run as, so its admin keeps routing cloud-setup releases to
+//       the terminal (upgrade/converge.ts, update-route.ts).
+//  10 — #806: remote MCP. Two CLI-generated secrets (the Google OAuth client
+//       placeholder, the broker's seal key) the gateway's new revision
+//       references — a secret volume and a secret env var Cloud Run refuses
+//       to deploy without — plus the gateway SA's accessor and the admin
+//       SA's version-adder bindings on them, the operator-access role's
+//       IAP-settings permissions, and on `gcp` the URL-map routes and the
+//       Cloud Armor rule. The in-cloud upgrader can create none of these.
 
 /**
  * What each contract version adds, in operator terms — the upgrader's
@@ -71,6 +90,8 @@ export const INFRA_CONTRACT_STEPS: Readonly<Record<number, string>> = {
   6: "the upgrader's permission to list its ops bucket (#799)",
   7: "the gateway's trusted proxy hop count, CAELO_TRUSTED_PROXY_HOPS (#845)",
   8: "the quality-audit job, its service account, results bucket and grants (#875)",
+  9: "the converge job that installs cloud-setup changes from Settings → Updates, and a narrower Cloud Run role for the upgrader (#819)",
+  10: "remote MCP: the OAuth client and seal-key secrets, their IAM, the gateway's secret file and timeout, IAP programmatic-client sync and the load-balancer rules (#806)",
 };
 
 /**

package/src/install-job.test.ts

@@ -162,7 +162,9 @@ describe("the status document", () => {
 
   it("fails loudly on a malformed document and on an unreadable bucket", () => {
     const objects = new Map([[installJobStatusUrl(BUCKET), '{"statusVersion":9}']]);
-    expect(() => readInstallJobStatus(BUCKET, fakeBucket(objects))).toThrow(/not an install-job/);
+    expect(() => readInstallJobStatus(BUCKET, fakeBucket(objects))).toThrow(
+      /not a job status this CLI understands/,
+    );
     expect(() => readInstallJobStatus(BUCKET, () => fail("403 Forbidden"))).toThrow(/403/);
   });
 });

package/src/install-job.ts

@@ -113,12 +113,12 @@ export function installJobStatusUrl(bucket: string): string {
 const NOT_FOUND = /matched no objects|No URLs matched|NotFound|NOT_FOUND|404|does not exist/i;
 
 /**
- * The install job's status as the ops bucket holds it now (never cached:
- * another process — the job — writes it), or null before the first start.
+ * A job status document (`install-job.json`, and the converge job's
+ * `converge-job.json`, #819) as the ops bucket holds it now — never cached:
+ * another process (the job) writes it — or null before the first start.
  * Throws when the bucket can't be read or the document is malformed.
  */
-export function readInstallJobStatus(bucket: string, run: SyncGcloud): InstallJobStatus | null {
-  const url = installJobStatusUrl(bucket);
+export function readJobStatusDoc<T>(url: string, schema: z.ZodType<T>, run: SyncGcloud): T | null {
   const r = run(["storage", "cat", url]);
   if (!r.ok) {
     if (NOT_FOUND.test(r.stderr)) return null;
@@ -128,26 +128,26 @@ export function readInstallJobStatus(bucket: string, run: SyncGcloud): InstallJo
   try {
     json = JSON.parse(r.stdout);
   } catch {
-    throw new Error(`${url} is not valid JSON; remove it and re-run to start the install again.`);
+    throw new Error(`${url} is not valid JSON; remove it and re-run to start again.`);
   }
-  const parsed = InstallJobStatusSchema.safeParse(json);
+  const parsed = schema.safeParse(json);
   if (!parsed.success) {
     throw new Error(
-      `${url} is not an install-job status this CLI understands (${parsed.error.message}); remove it and re-run.`,
+      `${url} is not a job status this CLI understands (${parsed.error.message}); remove it and re-run.`,
     );
   }
   return parsed.data;
 }
 
-/** Replace the status document. Refuses secret material (#656). */
-export function writeInstallJobStatus(
-  bucket: string,
-  status: InstallJobStatus,
+/** Replace a job status document. Refuses secret material (#656). */
+export function writeJobStatusDoc<T>(
+  url: string,
+  schema: z.ZodType<T>,
+  status: T,
   run: SyncGcloud,
 ): void {
-  const parsed = InstallJobStatusSchema.parse(status);
-  assertNoSecrets(parsed, "install-job.json");
-  const url = installJobStatusUrl(bucket);
+  const parsed = schema.parse(status);
+  assertNoSecrets(parsed, url.split("/").pop() ?? url);
   const r = run(
     ["storage", "cp", "-", url, "--content-type=application/json"],
     `${JSON.stringify(parsed, null, 2)}\n`,
@@ -157,6 +157,23 @@ export function writeInstallJobStatus(
   }
 }
 
+/**
+ * The install job's status as the ops bucket holds it now, or null before
+ * the first start ({@link readJobStatusDoc}).
+ */
+export function readInstallJobStatus(bucket: string, run: SyncGcloud): InstallJobStatus | null {
+  return readJobStatusDoc(installJobStatusUrl(bucket), InstallJobStatusSchema, run);
+}
+
+/** Replace the status document. Refuses secret material (#656). */
+export function writeInstallJobStatus(
+  bucket: string,
+  status: InstallJobStatus,
+  run: SyncGcloud,
+): void {
+  writeJobStatusDoc(installJobStatusUrl(bucket), InstallJobStatusSchema, status, run);
+}
+
 /**
  * Write `status` only if the document doesn't name its execution yet and
  * nobody wrote it since this call read it (`--if-generation-match`). The

package/src/lifecycle.ts

@@ -32,6 +32,7 @@ import {
   installRoot,
   installStagingHost,
   listInstalls,
+  readLocalMetadata,
   readMetadata,
   readSecret,
   recordImageDigests,
@@ -53,14 +54,18 @@ import {
   rolesOfSecret,
   rotateRuntimeSecret,
   rotationRefusal,
+  SEAL_KEY_SECRET,
 } from "./runtime-secrets.js";
+import { finishSealKeyRotation, startSealKeyRotation } from "./seal-key-rotation.js";
 import { selfCommand } from "./self-command.js";
 import {
   backendShellEnv,
   localStateNotice,
+  OPS_INSTALL_PREFIX,
   type ResolvedBackend,
   resolveBackend,
 } from "./state-backend.js";
+import { acquireStateLock, realSyncGcloud, releaseOnSignal } from "./state-store.js";
 import {
   type AppRollPlan,
   type ReleaseImage,
@@ -70,6 +75,7 @@ import {
 import { restoreCommand, takeSqlBackup } from "./upgrade/backup.js";
 import { findServiceUrl, resolveGcpResourceName } from "./upgrade/gcp-lookup.js";
 import { createIapHealthProbe, type HealthProbe } from "./upgrade/health.js";
+import { recordRolledDigests } from "./upgrade/record-rolled.js";
 import {
   canonicalReleaseTag,
   fetchLatestReleaseTag,
@@ -488,6 +494,53 @@ async function upgradeInstall(
   const provider = meta.provider;
   const projectId = meta.projectId;
 
+  // #815 — the install's state lock, the one the in-app upgrader job,
+  // `pulumi up` and `state migrate` take: a Cloud Shell upgrade must not
+  // race an Owner-started or automatic job run. The local copy always
+  // names where the state lives (install-state.ts stateStoreFor). A lock
+  // left by a job whose run has ended, by a CLI whose process is gone on
+  // this machine, or by one that stopped renewing its lease is broken
+  // automatically. This run's own lock carries host + pid and a lease its
+  // heartbeat renews, and is given back on Ctrl-C / SIGTERM — a killed CLI
+  // or a closed Cloud Shell never blocks in-app updates for good.
+  const backend = readLocalMetadata(installId)?.stateBackend;
+  let releaseLock: () => void;
+  try {
+    releaseLock = acquireStateLock(
+      backend?.kind === "gcs" ? { kind: "gcs", bucket: backend.bucket } : { kind: "local" },
+      installRoot(installId),
+      "cms-provision upgrade",
+      realSyncGcloud,
+      {
+        onBreak: (message) => log.info(message),
+        onLost: (message) => log.error(red(message)),
+      },
+    );
+  } catch (e) {
+    log.error(red(`Nothing was changed: ${e instanceof Error ? e.message : String(e)}`));
+    return false;
+  }
+  const disposeSignals = releaseOnSignal(releaseLock, (message) => log.warn(yellow(message)));
+  try {
+    return await upgradeLockedInstall(installId, meta, opts, provider, projectId);
+  } finally {
+    disposeSignals();
+    try {
+      releaseLock();
+    } catch (e) {
+      log.warn(yellow(e instanceof Error ? e.message : String(e)));
+    }
+  }
+}
+
+/** {@link upgradeInstall} once it holds the install's state lock. */
+async function upgradeLockedInstall(
+  installId: string,
+  meta: InstallMetadata,
+  opts: UpgradeOpts,
+  provider: "gcp" | "gcp-firebase",
+  projectId: string,
+): Promise<boolean> {
   // #607 — upgrade never moves an install: a `--region` other than the
   // recorded one is refused before anything rolls.
   const region = installRegion(meta, opts.region);
@@ -501,7 +554,9 @@ async function upgradeInstall(
 
   const run: GcloudRunner = gcloud;
   const http = fetch as unknown as HttpFetch;
-  const ok = await upgradeGcpInstall(
+  // #860 — a roll whose records could not be written is a failed upgrade.
+  let recorded = true;
+  const rolled = await upgradeGcpInstall(
     {
       provider,
       projectId,
@@ -524,20 +579,29 @@ async function upgradeInstall(
       migrate: (imageRef) =>
         runMigrationsViaCloudRunJob({ projectId, region, imageOverride: imageRef }, { run }),
       healthProbe: (plan) => gcpHealthProbe(run, http, plan),
-      recordDigests: async (digests) =>
-        recordRolledDigests(
+      recordDigests: async (digests) => {
+        recorded = await recordRolledRelease(
           installId,
           provider,
           digests,
           // #696 — the version the upgrader job judges later updates by.
           canonicalReleaseTag(targetTag)?.replace(/^v/, "") ??
             (await releaseVersionForDigest(run, "admin", digests.admin)),
-        ),
+        );
+      },
       resolveOpsImage: resolveOpsImageRef,
       recordInfraContractVersion: (version) => recordInfraContractVersion(installId, version),
       provisionerIdentity: () => upgradeKeylessProvisioner(installId, projectId),
     },
   );
+  if (rolled && !recorded) {
+    log.error(
+      red(
+        "The new release serves, but the upgrade could not record it (see above). Apply the fixes above; until then this upgrade counts as failed.",
+      ),
+    );
+  }
+  const ok = rolled && recorded;
   // #696 — upgrade never moves Pulumi state; it says how to.
   const stateNotice = localStateNotice(meta);
   if (stateNotice) note(stateNotice, "Pulumi state is on this machine");
@@ -586,74 +650,44 @@ async function gcpHealthProbe(
 }
 
 /**
- * Record the digests just rolled so nothing re-deploys an older release:
- * install.json (what a wizard re-run deploys) and the Pulumi stack config
- * (what a plain `pulumi up` deploys). The roll already succeeded, so each
- * write that fails warns with the exact manual fix instead of failing the
- * upgrade, and one failing never skips the other.
+ * Record the digests just rolled (upgrade/record-rolled.ts), wired to this
+ * install's install.json and Pulumi stack. The converge job (#819,
+ * converge-job-gcp.ts) records through the same function as the terminal.
+ *
+ * @returns whether every record was written; false fails the upgrade.
  */
-async function recordRolledDigests(
+export function recordRolledRelease(
   installId: string,
   provider: "gcp" | "gcp-firebase",
   digests: ImageDigests,
   releaseVersion: string | null,
-): Promise<void> {
-  const reason = (e: unknown) => (e instanceof Error ? e.message.split("\n")[0] : String(e));
-  if (!releaseVersion) {
-    log.warn(
-      yellow(
-        "Could not tell which Caelo release these images are (no version tag points at them), so install.json records none; in-product updates stay unavailable until an upgrade to a released version.",
-      ),
-    );
-  }
-  try {
-    recordImageDigests(installId, digests, releaseVersion);
-  } catch (e) {
-    log.warn(
-      yellow(
-        `Could not record the rolled digests in the install.json of ${installId} (${reason(e)}). Add this before re-running the installer, or it deploys the newest release instead:\n  "imageDigests": ${JSON.stringify(digests)}`,
-      ),
-    );
-  }
-  const meta = readMetadata(installId);
-  const manual = stackConfigRecovery(installId, meta ?? {}, provider, digests);
-  let backend: ResolvedBackend;
-  try {
-    if (!meta) throw new Error(`no install.json for '${installId}'`);
-    backend = resolveBackend(meta, {
-      installRoot: installRoot(installId),
-      readPassphrase: () => readSecret(installId, "pulumi-passphrase"),
-    });
-  } catch (e) {
-    log.warn(
-      yellow(
-        `Stack config not updated (${reason(e)}). Before any manual \`pulumi up\`, run:\n${manual}`,
-      ),
-    );
-    return;
-  }
-  try {
-    const { writeImageDigestsToStack } = await import("./wizards/gcp-pulumi.js");
-    const { removedOverrides } = await writeImageDigestsToStack({
-      backend,
-      provider,
-      digests,
-    });
-    log.info(dim("Pinned the rolled image digests in the Pulumi stack config."));
-    if (removedOverrides.length > 0) {
-      log.warn(
-        yellow(
-          `Removed ${removedOverrides.join(", ")} from the stack config: those image overrides win over the digest pins, so a later \`pulumi up\` would have rolled back to them.`,
-        ),
-      );
-    }
-  } catch (e) {
-    log.warn(
-      yellow(
-        `Could not pin the rolled digests in the Pulumi stack config (${reason(e)}). Before any manual \`pulumi up\`, run:\n${manual}`,
-      ),
-    );
-  }
+): Promise<boolean> {
+  // The local copy always names where the state lives (install-state.ts
+  // stateStoreFor), and reading it cannot fail on bucket access.
+  const local = readLocalMetadata(installId);
+  const bucket = local?.stateBackend?.kind === "gcs" ? local.stateBackend.bucket : null;
+  return recordRolledDigests(digests, releaseVersion, {
+    recordInstall: (d, v) => recordImageDigests(installId, d, v),
+    pinStack: async (d) => {
+      const meta = readMetadata(installId);
+      if (!meta) throw new Error(`no install.json for '${installId}'`);
+      const backend: ResolvedBackend = resolveBackend(meta, {
+        installRoot: installRoot(installId),
+        readPassphrase: () => readSecret(installId, "pulumi-passphrase"),
+      });
+      const { writeImageDigestsToStack } = await import("./wizards/gcp-pulumi.js");
+      return writeImageDigestsToStack({ backend, provider, digests: d });
+    },
+    stackRecovery: (d) => stackConfigRecovery(installId, local ?? {}, provider, d),
+    installJsonLocation: bucket
+      ? `gs://${bucket}/${OPS_INSTALL_PREFIX}/install.json (and ${join(installRoot(installId), "install.json")})`
+      : join(installRoot(installId), "install.json"),
+    log: {
+      info: (m) => log.info(dim(m)),
+      warn: (m) => log.warn(yellow(m)),
+      error: (m) => log.error(red(m)),
+    },
+  });
 }
 
 /**
@@ -717,10 +751,13 @@ async function backupOf(meta: InstallMetadata): Promise<boolean> {
 // rotate-secret <name>
 // =========================================================================
 
-export async function rotateSecretCommand(name: string | undefined): Promise<void> {
+export async function rotateSecretCommand(
+  name: string | undefined,
+  opts: { readonly finish?: boolean; readonly now?: boolean } = {},
+): Promise<void> {
   if (!name) {
-    log.error(red("Usage: caelo-cms rotate-secret <name>"));
-    log.warn(`Names: ${ROTATABLE_SECRETS.join(", ")}`);
+    log.error(red("Usage: caelo-cms rotate-secret <name> [--finish]"));
+    log.warn(`Names: ${[...ROTATABLE_SECRETS, SEAL_KEY_SECRET].join(", ")}`);
     process.exit(2);
   }
   const refusal = rotationRefusal(name);
@@ -728,7 +765,10 @@ export async function rotateSecretCommand(name: string | undefined): Promise<voi
     log.error(red(refusal));
     process.exit(2);
   }
-  const secret = name as RotatableSecret;
+  if (opts.finish && name !== SEAL_KEY_SECRET) {
+    log.error(red(`--finish applies to ${SEAL_KEY_SECRET} only; ${name} rotates in one step.`));
+    process.exit(2);
+  }
   const { meta } = await requireInstall("rotate-secret");
   if (meta.provider !== "gcp" && meta.provider !== "gcp-firebase") {
     log.warn(`rotate-secret for provider ${meta.provider} not yet implemented.`);
@@ -737,6 +777,32 @@ export async function rotateSecretCommand(name: string | undefined): Promise<voi
   if (!meta.projectId) return;
   const region = installRegion(meta);
 
+  if (name === SEAL_KEY_SECRET) {
+    const gatewayService = await resolveGcpResourceName(
+      gcloud,
+      "run-service",
+      "caelo-production-gateway",
+      meta.projectId,
+      region,
+    );
+    if (!gatewayService) {
+      log.error(
+        red("Could not find the caelo-production-gateway* Cloud Run service — nothing rotated"),
+      );
+      return;
+    }
+    const target = { projectId: meta.projectId, region, env: GCP_STACK_ENV, gatewayService };
+    const report = opts.finish
+      ? await finishSealKeyRotation(target, {}, { now: opts.now === true })
+      : await startSealKeyRotation(target);
+    for (const step of report.steps) log.info(`  ${step}`);
+    if (report.ok)
+      log.success(green(opts.finish ? "seal-key rotation finished" : "seal-key rotation started"));
+    else log.error(red(report.error ?? "seal-key rotation failed"));
+    return;
+  }
+  const secret = name as RotatableSecret;
+
   const s = spinner();
   s.start(`Rotating ${secret}...`);
   const services: Partial<Record<"admin" | "gateway", string>> = {};

package/src/operator-access.test.ts

@@ -330,3 +330,17 @@ describe("resolveOperatorAccessTarget", () => {
     expect(r2.ok === false && r2.error).toContain("exactly one");
   });
 });
+
+describe("caeloOperatorAccess role (#806)", () => {
+  it("holds IAM-policy and IAP-settings rights on web services and the MCP SA — nothing else", () => {
+    expect([...OPERATOR_ACCESS_ROLE.permissions].sort()).toEqual([
+      "iam.serviceAccounts.getIamPolicy",
+      "iam.serviceAccounts.setIamPolicy",
+      "iap.webServices.getIamPolicy",
+      // The admin IAP resource's programmatic_clients (remote MCP).
+      "iap.webServices.getSettings",
+      "iap.webServices.setIamPolicy",
+      "iap.webServices.updateSettings",
+    ]);
+  });
+});

package/src/operator-access.ts

@@ -6,7 +6,9 @@
  * `cms-provision upgrade`, both as the operator's own gcloud identity.
  *
  * Trust boundary. Who may pass the admin's IAP gate and sign as `caelo-mcp`
- * follows the Caelo user list. The admin does NOT write that: its runtime
+ * follows the Caelo user list; which OAuth client may call the admin
+ * programmatically (IAP `programmatic_clients`, remote MCP #806) follows the
+ * client the Owner configured under Settings → MCP → Remote. The admin does NOT write that: its runtime
  * service account holds no IAM-policy rights. A Cloud Run job with its own
  * service account (admin-core security/operator-access/sync-job.ts) is the
  * only principal that may change those two bindings, and it only ever grants
@@ -19,7 +21,8 @@
  *
  * What this ensures, every step idempotent:
  *   1. the Cloud Scheduler API;
- *   2. the custom role `caeloOperatorAccess` (get/setIamPolicy only);
+ *   2. the custom role `caeloOperatorAccess` (get/setIamPolicy, and
+ *      get/updateSettings for `programmatic_clients`);
  *   3. the job's service account, bound to that role on exactly the admin's
  *      IAP resource and the `caelo-mcp` service account, plus
  *      `cloudsql.instanceUser` + `logging.logWriter`;
@@ -66,10 +69,17 @@ export const OPERATOR_ACCESS_ROLE: CustomRoleSpec = {
   roleId: "caeloOperatorAccess",
   title: "Caelo operator access",
   description:
-    "Lets the Caelo operator-access sync job set who passes the admin's IAP gate and who may sign as caelo-mcp. Bound only on those two resources, only to the job's service account.",
+    "Lets the Caelo operator-access sync job set who passes the admin's IAP gate, which OAuth client may call it programmatically (remote MCP), and who may sign as caelo-mcp. Bound only on those two resources, only to the job's service account.",
   permissions: [
     "iap.webServices.getIamPolicy",
     "iap.webServices.setIamPolicy",
+    // #806 — the admin IAP resource's `programmatic_clients` (the remote-MCP
+    // OAuth client). IAP settings permissions per resource level:
+    // cloud.google.com/iap/docs/customizing ("Web Services": getSettings /
+    // updateSettings); the role is bound on exactly the admin's IAP web
+    // service, so it reaches no other resource's settings.
+    "iap.webServices.getSettings",
+    "iap.webServices.updateSettings",
     "iam.serviceAccounts.getIamPolicy",
     "iam.serviceAccounts.setIamPolicy",
   ],

package/src/release-contract.ts

@@ -11,8 +11,9 @@
  * The admin's upgrader job (Phase 2) only rolls images: it holds no IAM
  * write, no secret create, no resource create. Anything a release needs
  * beyond "new image digests + expand-only migrations" must therefore be
- * declared here, so the upgrader refuses it and sends the Owner to the
- * "Run in Cloud Shell" path instead of half-applying it.
+ * declared here, so the upgrader refuses it and the admin routes the
+ * release to the converge job (#819; the provisioner's identity) instead
+ * of half-applying it.
  */
 
 /**
@@ -52,6 +53,8 @@ export const INFRA_CONTRACT_PATHS: readonly string[] = [
   // #875 — the quality-audit job, its service account, results bucket and
   // grants.
   "packages/provisioning/src/audit-job-setup.ts",
+  // #819 — the converge job, its database login and the admin's grant on it.
+  "packages/provisioning/src/converge-job-setup.ts",
 ];
 
 /**

package/src/release-manifest.test.ts

@@ -172,6 +172,48 @@ describe("fetchVerifiedReleaseManifest", () => {
     expect(r.ok ? "" : r.error.message).toContain("HTTP 404");
   });
 
+  it("regression #865: a missing manifest or blob (404) is not transient — a retry cannot find it", async () => {
+    const missing = await fetchVerifiedReleaseManifest(
+      "0.11.0",
+      fixture({ manifestStatus: 404 }).deps,
+    );
+    expect(missing.ok ? null : missing.error).toMatchObject({ code: "registry" });
+    expect(missing.ok ? null : missing.error.transient).toBeUndefined();
+    const { deps } = fixture();
+    const noBlob = await fetchVerifiedReleaseManifest("0.11.0", {
+      ...deps,
+      fetch: async (url, init) =>
+        url.includes("/blobs/") ? new Response("", { status: 404 }) : deps.fetch(url, init),
+    });
+    expect(noBlob.ok ? null : noBlob.error.code).toBe("registry");
+    expect(noBlob.ok ? null : noBlob.error.transient).toBeUndefined();
+  });
+
+  it("regression #865: 5xx, 429 and network failures are transient", async () => {
+    for (const status of [500, 503, 429]) {
+      const r = await fetchVerifiedReleaseManifest(
+        "0.11.0",
+        fixture({ manifestStatus: status }).deps,
+      );
+      expect(r.ok ? null : r.error).toMatchObject({ code: "registry", transient: true });
+    }
+    const { deps } = fixture();
+    const blob503 = await fetchVerifiedReleaseManifest("0.11.0", {
+      ...deps,
+      fetch: async (url, init) =>
+        url.includes("/blobs/") ? new Response("", { status: 503 }) : deps.fetch(url, init),
+    });
+    expect(blob503.ok ? null : blob503.error).toMatchObject({ code: "registry", transient: true });
+    const down = await fetchVerifiedReleaseManifest("0.11.0", {
+      ...deps,
+      fetch: async () => {
+        throw new TypeError("fetch failed: ECONNRESET");
+      },
+    });
+    expect(down.ok ? null : down.error).toMatchObject({ code: "registry", transient: true });
+    expect(down.ok ? "" : down.error.message).toContain("ECONNRESET");
+  });
+
   it("rejects a non-SemVer version without touching the network", async () => {
     const { deps, urls } = fixture();
     const r = await fetchVerifiedReleaseManifest("v0.11.0", deps);

package/src/release-manifest.ts

@@ -129,6 +129,8 @@ export type ReleaseManifestErrorCode =
 export interface ReleaseManifestError {
   readonly code: ReleaseManifestErrorCode;
   readonly message: string;
+  /** On `registry` errors a retry may cure; absent for not-found (see @caelo-cms/shared ReleaseArtifactError). */
+  readonly transient?: true;
 }
 
 export type ReleaseManifestResult =