@caelo-cms/provisioning 0.11.9 → 0.11.11

package/src/upgrade/upgrade.ts

@@ -4,14 +4,17 @@
  * `cms-provision upgrade` for one gcp / gcp-firebase install: converge, then
  * app-roll (epic #696). The order, and why:
  *
- *   1. plan (read-only): release digests, both services, the env contract
+ *   1. plan: release digests, the services, the env contract — read-only
+ *      but for the services an older install lacks (#1328, additive and
+ *      serving nothing yet: mcp-auth-proxy-setup.ts)
  *   2. verify the images' signatures
  *   3. pre-upgrade Cloud SQL backup — the first change; if it fails, the
  *      install is exactly as it was
  *   4. converge, the part before the roll (keyless provisioner, IAM, secrets,
  *      MCP access)
  *   5. app-roll: health baseline, migrations, the converge steps that must
- *      follow migrations, admin + gateway rolls, deep health check, rollback
+ *      follow migrations, admin, gateway and MCP-Auth-Proxy rolls, deep
+ *      health check, rollback
  *      on failure, recorded digests
  *   6. converge, the part after the roll; a complete converge records the
  *      install's infrastructure contract version
@@ -29,6 +32,7 @@
 
 import type { GcloudRunner, Sleep } from "../gcloud-retry.js";
 import type { ImageDigests } from "../install-state.js";
+import { ensureReleaseServices } from "../mcp-auth-proxy-setup.js";
 import type { HttpFetch } from "../runtime-secrets.js";
 import {
   type AppRollPlan,
@@ -53,6 +57,12 @@ export interface GcpUpgradeTarget {
   readonly domain: string;
   readonly stagingHost: string;
   readonly ownerEmail: string;
+  /**
+   * #1140 — install.json's `schedulerIntervalMinutes` (absent: the default).
+   * Bounded to 1–15 by the converge, so a tampered record can change only
+   * how soon due work runs.
+   */
+  readonly schedulerIntervalMinutes?: number;
   /** The tag rolled to: a version (`0.11.0`) or a channel tag (`latest`, `rc`). */
   readonly targetTag: string;
   /** The infrastructure contract version this CLI converges to (infra-contract.ts). */
@@ -75,9 +85,17 @@ export interface GcpUpgradeTarget {
  */
 export interface UpgradeCheckpoint {
   readonly backup?: SqlBackup;
-  readonly priorRevisions?: Readonly<Record<RollSlug, string>>;
+  readonly priorRevisions?: PriorRevisions;
 }
 
+/**
+ * The rollback target per service. The MCP-Auth-Proxy's is absent in a
+ * checkpoint a release before #1328 wrote; its planned revision is kept then.
+ */
+export type PriorRevisions = Readonly<Record<"admin" | "gateway", string>> & {
+  readonly "mcp-auth-proxy"?: string;
+};
+
 export interface GcpUpgradeDeps {
   readonly run: GcloudRunner;
   readonly reporter: UpgradeReporter;
@@ -165,6 +183,41 @@ export async function upgradeGcpInstallOutcome(
     r.error(images.error);
     return failed;
   }
+  // #1328 — the services the plan must find: the MCP-Auth-Proxy's account
+  // and, on an install whose stack predates it, the data gateway
+  // (gcp-firebase) or the proxy's own service (gcp). Additive, serving
+  // nothing yet, so the install keeps running as it is when this or
+  // anything after it fails. The gcp proxy runs the new release's image,
+  // so that image's signature is checked before it is deployed.
+  const proxyImage = images.images["mcp-auth-proxy"];
+  if (
+    target.provider === "gcp" &&
+    !target.skipVerify &&
+    !(await deps.verifyImages([{ slug: "mcp-auth-proxy", digest: proxyImage.digest }]))
+  ) {
+    sPre.failed("The MCP-Auth-Proxy image's signature did not verify");
+    return failed;
+  }
+  const ensured = await ensureReleaseServices(
+    {
+      provider: target.provider,
+      projectId,
+      region: target.region,
+      env: target.env,
+      domain: target.domain,
+      mcpAuthProxyImageRef: proxyImage.imageRef,
+    },
+    { run },
+  );
+  const ensureFailed = ensured.filter((o) => o.status === "failed");
+  if (ensureFailed.length > 0) {
+    sPre.failed("The services this release runs could not be set up. Nothing was changed.");
+    for (const o of ensureFailed) r.error(`  FAILED: ${o.id}\n    ${o.error ?? ""}`);
+    return failed;
+  }
+  for (const o of ensured.filter((o) => o.status === "applied")) {
+    r.info(`  created: ${o.id}${o.detail ? ` (${o.detail})` : ""}`);
+  }
   const planned = await planAppRoll(
     {
       provider: target.provider,
@@ -229,6 +282,9 @@ export async function upgradeGcpInstallOutcome(
   const opsImageRef = await verifiedOpsImage(target, deps);
   const converge = startConverge(plan, target.ownerEmail, {
     opsImageRef,
+    ...(target.schedulerIntervalMinutes !== undefined
+      ? { schedulerIntervalMinutes: target.schedulerIntervalMinutes }
+      : {}),
     run,
     reporter: r,
     ...(deps.sleep ? { sleep: deps.sleep } : {}),
@@ -269,7 +325,9 @@ export async function upgradeGcpInstallOutcome(
     },
   );
   if (!rolled.ok) return { ok: false, rolledBack: rolled.rolledBack };
-  r.success(`Upgrade to ${target.targetTag} complete (admin + gateway revisions serving).`);
+  r.success(
+    `Upgrade to ${target.targetTag} complete (admin, gateway and MCP-Auth-Proxy revisions serving).`,
+  );
   r.info(
     `Pre-upgrade backup: ${backup.backup.backupId} (restore: ${restoreCommand(backup.backup)})`,
   );
@@ -314,8 +372,8 @@ function withPriorRevisions(
   return {
     ...plan,
     services: plan.services.map((s) => {
-      const before = recorded[s.slug];
-      if (before === s.priorRevision) return s;
+      const before: string | undefined = recorded[s.slug];
+      if (before === undefined || before === s.priorRevision) return s;
       r.info(
         `Continuing an interrupted update: ${s.slug} goes back to ${before} (what served before it started) if the new release fails its checks.`,
       );

package/src/upgrader-gcp.ts

@@ -16,6 +16,13 @@
 import { mkdtempSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { isIpLiteral } from "@caelo-cms/shared";
+import {
+  ensureCloudSqlVerifyFull,
+  liveDatabaseUrls,
+  moveServicesToDnsHost,
+} from "./cloudsql-tls.js";
+import { findSqlInstance } from "./gateway-credentials.js";
 import { gcloud } from "./gcloud.js";
 import { type GcloudRunner, realSleep } from "./gcloud-retry.js";
 import { GCP_STACK_ENV } from "./gcp-names.js";
@@ -23,10 +30,16 @@ import type { InstallMetadata } from "./install-state.js";
 import { readAdminConfig, runMigrationsViaCloudRunJob } from "./migration-runner.js";
 import { fetchVerifiedReleaseManifest } from "./release-manifest.js";
 import type { HttpFetch } from "./runtime-secrets.js";
+import { DATABASE_URL_VARS } from "./stack-contract.js";
+import { liveContainerEnv } from "./stack-converge.js";
 import { opsBucketName } from "./state-backend.js";
 import { acquireBucketStateLock, GcsStateStore, realSyncGcloud } from "./state-store.js";
-import type { AppRollPlan } from "./upgrade/app-roll.js";
-import { findServiceUrl } from "./upgrade/gcp-lookup.js";
+import type { AppRollPlan, RollSlug } from "./upgrade/app-roll.js";
+import {
+  describeServiceJson,
+  findServiceUrl,
+  resolveGcpResourceName,
+} from "./upgrade/gcp-lookup.js";
 import { createIapHealthProbe } from "./upgrade/health.js";
 import { createReleaseImageForms } from "./upgrade/image-forms.js";
 import { type IamTester, restIamTester } from "./upgrader-iam-preflight.js";
@@ -58,6 +71,55 @@ export async function upgraderDatabaseHost(
   return cfg.databaseHost;
 }
 
+/**
+ * #1338 — the database host for the converge job (#819), after making sure
+ * a verify-full connection to it can work. On an install whose services
+ * still dial the instance's IP it runs the converge's database TLS step
+ * (cloudsql-tls.ts: shared CA, private DNS name, services moved onto it).
+ * Stage 2 of the job runs it as a timeline step, over a queue opened on
+ * the IP (converge-db-trust.ts, #1373), then reconnects on the host this
+ * returns.
+ * The job runs as the install's `caelo-provisioner`, which holds
+ * `roles/cloudsql.admin` and `roles/dns.admin` (gcloud.ts PROVISIONER_ROLES).
+ * Idempotent: the converge's own step finds everything in shape.
+ */
+export async function convergeDatabaseHost(
+  placement: Pick<UpgraderPlacement, "projectId" | "region">,
+  run: GcloudRunner = gcloud,
+  http?: HttpFetch,
+): Promise<string> {
+  const host = await upgraderDatabaseHost(placement, run);
+  if (!isIpLiteral(host)) return host;
+  const install = { projectId: placement.projectId, env: GCP_STACK_ENV };
+  const lookup = await findSqlInstance(install, { run });
+  if (lookup.status !== "found") {
+    throw new Error(`could not find the install's Cloud SQL instance (${lookup.status})`);
+  }
+  const deps = { run, ...(http ? { http } : {}) };
+  const tls = await ensureCloudSqlVerifyFull({ ...install, sqlInstance: lookup.name }, deps);
+  if (!tls.ok) throw new Error(`database TLS could not be set up: ${tls.error}`);
+  const services: { serviceName: string; liveUrls: Record<string, string> }[] = [];
+  for (const slug of ["admin", "gateway"] as const) {
+    const found = await resolveGcpResourceName(
+      run,
+      "run-service",
+      `caelo-${GCP_STACK_ENV}-${slug}`,
+      placement.projectId,
+      placement.region,
+    );
+    if (found.status !== "found") throw new Error(`could not find the ${slug} service`);
+    const json = await describeServiceJson(run, placement.projectId, placement.region, found.name);
+    if (!json) throw new Error(`could not read the ${slug} service's configuration`);
+    services.push({
+      serviceName: found.name,
+      liveUrls: liveDatabaseUrls(liveContainerEnv(json), DATABASE_URL_VARS[slug]),
+    });
+  }
+  const moved = await moveServicesToDnsHost(placement, services, tls.host, deps);
+  if (!moved.ok) throw new Error(moved.error);
+  return tls.host;
+}
+
 /**
  * The IAP-backed deep health probe for `plan`'s install (the upgrader job;
  * the converge job, #819, too). `accessJustChanged`: a converge right
@@ -71,7 +133,7 @@ export async function healthProbeFor(
   context: { readonly accessJustChanged: boolean },
 ) {
   const { install } = plan;
-  const urls: Partial<Record<"admin" | "gateway", string>> = {};
+  const urls: Partial<Record<RollSlug, string>> = {};
   for (const s of plan.services) {
     const url = await findServiceUrl(run, install.projectId, install.region, s.serviceName);
     if (!url) {
@@ -88,6 +150,7 @@ export async function healthProbeFor(
         domain: install.domain,
         adminServiceUrl: urls.admin as string,
         gatewayServiceUrl: urls.gateway as string,
+        mcpAuthProxyServiceUrl: urls["mcp-auth-proxy"] as string,
       },
       { run, http, sleep: realSleep, accessJustChanged: context.accessJustChanged },
     ),

package/src/upgrader-iam-preflight.test.ts

@@ -73,6 +73,11 @@ function setupGrants(): Map<string, Set<string>> {
       `projects/${p}/serviceAccounts/caelo-production-gateway-sa@${p}.iam.gserviceaccount.com`,
       of("roles/iam.serviceAccountUser"),
     ],
+    // #1328 — the MCP-Auth-Proxy's revisions run as its own account.
+    [
+      `projects/${p}/serviceAccounts/caelo-production-mcp-proxy-sa@${p}.iam.gserviceaccount.com`,
+      of("roles/iam.serviceAccountUser"),
+    ],
     [
       `projects/${p}/serviceAccounts/caelo-production-upgrader@${p}.iam.gserviceaccount.com`,
       of("roles/iam.serviceAccountUser"),
@@ -154,6 +159,20 @@ describe("upgraderAccessChecks", () => {
     expect(preflightMissingReason(r.missing, UPGRADER_PREFLIGHT_VOICE)).toContain("capture job");
   });
 
+  it("#1328: the MCP-Auth-Proxy's account is checked, since every app-roll rolls the proxy", async () => {
+    const proxySa =
+      "projects/acme/serviceAccounts/caelo-production-mcp-proxy-sa@acme.iam.gserviceaccount.com";
+    const grants = setupGrants();
+    grants.delete(proxySa);
+    const r = await runIamPreflight(upgraderAccessChecks(TARGET), tester(grants));
+    expect(r.kind).toBe("missing");
+    if (r.kind !== "missing") return;
+    expect(r.missing.map((m) => [resourceName(m.check.resource), m.missing])).toEqual([
+      [proxySa, ["iam.serviceAccounts.actAs"]],
+    ]);
+    expect(preflightMissingReason(r.missing, UPGRADER_PREFLIGHT_VOICE)).toContain("MCP-Auth-Proxy");
+  });
+
   it("never needs a permission only a forbidden role would give (no compute, no IAM admin)", () => {
     const all = upgraderAccessChecks(TARGET).flatMap((c) => c.permissions);
     for (const p of all) {

package/src/upgrader-iam-preflight.ts

@@ -54,6 +54,7 @@ import {
   auditServiceAccountEmail,
   captureServiceAccountEmail,
   gatewayServiceAccountEmail,
+  mcpAuthProxyServiceAccountEmail,
   mcpIapServiceAccountEmail,
   runServiceAccountEmail,
   upgraderJobName,
@@ -186,6 +187,11 @@ export function upgraderAccessChecks(target: {
       resource: sa(gatewayServiceAccountEmail(projectId, env)),
       permissions: ["iam.serviceAccounts.actAs"],
     },
+    {
+      need: "run the MCP-Auth-Proxy as its service account",
+      resource: sa(mcpAuthProxyServiceAccountEmail(projectId, env)),
+      permissions: ["iam.serviceAccounts.actAs"],
+    },
     {
       // #875 — every app-roll moves the audit job onto the new admin image
       // (upgrade/admin-image-jobs.ts), and upgrader-setup.ts grants actAs on

package/src/upgrader-job.test.ts

@@ -57,14 +57,16 @@ const revisionJson = (deployed: string | null, resolved: string) =>
     status: { imageDigest: `${MIRROR}@${resolved}` },
   });
 
-/** Serving revisions deployed as `admin` / `gateway` (index digests). */
+/** Serving revisions deployed as `admin` / `gateway` (index digests); the proxy serves D("3"). */
 const servingAs = (admin: string, gateway: string): [RegExp, Answer] => [
   /^run revisions describe (\S+)/,
   (l) =>
     ok(
       l.includes("-admin-")
         ? revisionJson(admin, `sha256:${"e".repeat(64)}`)
-        : revisionJson(gateway, `sha256:${"d".repeat(64)}`),
+        : l.includes(PROXY)
+          ? revisionJson(D("3"), P("3"))
+          : revisionJson(gateway, `sha256:${"d".repeat(64)}`),
     ),
 ];
 
@@ -79,13 +81,16 @@ const releaseTags = (slug: "admin" | "gateway", tags: Record<string, string>): [
 ];
 
 const ADMIN = "caelo-production-admin-aaa";
-const GATEWAY = "caelo-production-gateway-bbb";
+// #1328 — gcp-firebase: the visitor gateway is the fixed-name data gateway,
+// the MCP-Auth-Proxy the service that was the gateway (E13 a).
+const GATEWAY = "caelo-production-data-gateway";
+const PROXY = "caelo-production-gateway-bbb";
 
 const MANIFEST: ReleaseManifest = {
   manifestVersion: 1,
   version: "0.11.0",
   channel: "stable",
-  digests: { admin: D("a"), gateway: D("b"), ops: D("c") },
+  digests: { admin: D("a"), gateway: D("b"), ops: D("c"), "mcp-auth-proxy": D("d") },
   minFromVersion: "0.10.0",
   infraContractVersion: 2,
   migrations: { contract: false, lastContractVersion: null, head: "0267_platform_updates" },
@@ -121,14 +126,23 @@ const META: InstallMetadata = {
   ownerEmail: "owner@acme.com",
   region: "europe-west1",
   createdAt: "2026-01-01T00:00:00Z",
-  imageDigests: { admin: D("1"), gateway: D("2") },
+  imageDigests: { admin: D("1"), gateway: D("2"), "mcp-auth-proxy": D("3") },
   releaseVersion: "0.10.45",
   infraContractVersion: 2,
 };
 
-const manifestOf = (version: string, admin: string, gateway: string): ReleaseManifestResult => ({
+const manifestOf = (
+  version: string,
+  admin: string,
+  gateway: string,
+  proxy = D("3"),
+): ReleaseManifestResult => ({
   ok: true,
-  manifest: { ...MANIFEST, version, digests: { admin, gateway, ops: D("c") } },
+  manifest: {
+    ...MANIFEST,
+    version,
+    digests: { admin, gateway, ops: D("c"), "mcp-auth-proxy": proxy },
+  },
 });
 
 const serviceJson = (image: string, env: unknown[]) =>
@@ -141,11 +155,13 @@ const ADMIN_JSON = serviceJson("registry/admin@sha256:old", [
   { name: "CAELO_FIREBASE_SITE", value: "caelo-production-site-abc123" },
   {
     name: "ADMIN_DATABASE_URL",
-    value: "postgresql://admin_role@10.20.0.3:5432/cms_admin?sslmode=require",
+    value:
+      "postgresql://admin_role@db1.p-label.europe-west1.sql-psa.goog:5432/cms_admin?sslmode=verify-full&sslrootcert=/etc/caelo/db-ca/cloudsql-global.pem",
   },
   secretRef("ADMIN_DATABASE_PASSWORD", "postgres-password"),
 ]);
 const GATEWAY_JSON = serviceJson("registry/gateway@sha256:old", []);
+const PROXY_JSON = serviceJson("registry/mcp-auth-proxy@sha256:old", []);
 
 type Answer = GcloudResult | ((line: string) => GcloudResult);
 
@@ -153,15 +169,23 @@ function fakeGcloud(events: string[], overrides: [RegExp, Answer][] = []) {
   const rules: [RegExp, Answer][] = [
     ...overrides,
     [/^run services list .*caelo-production-admin/, ok(`${ADMIN}\n`)],
-    [/^run services list .*caelo-production-gateway/, ok(`${GATEWAY}\n`)],
+    [/^run services list .*caelo-production-data-gateway/, ok(`${GATEWAY}\n`)],
+    [/^run services list .*caelo-production-gateway/, ok(`${PROXY}\n`)],
     [/describe (\S+) .*revisionName/, (l) => ok(`${l.split(" ")[3]}-00001-old\n`)],
     [new RegExp(`describe ${ADMIN} .*--format=json`), ok(ADMIN_JSON)],
     [new RegExp(`describe ${GATEWAY} .*--format=json`), ok(GATEWAY_JSON)],
+    [new RegExp(`describe ${PROXY} .*--format=json`), ok(PROXY_JSON)],
     [/describe (\S+) .*status\.url/, (l) => ok(`https://${l.split(" ")[3]}-xyz.a.run.app\n`)],
     [
       /^run revisions describe (\S+)/,
       (l) =>
-        ok(l.includes("-admin-") ? revisionJson(D("1"), P("1")) : revisionJson(D("2"), P("2"))),
+        ok(
+          l.includes("-admin-")
+            ? revisionJson(D("1"), P("1"))
+            : l.includes(PROXY)
+              ? revisionJson(D("3"), P("3"))
+              : revisionJson(D("2"), P("2")),
+        ),
     ],
     [/^sql instances list/, ok("caelo-production-pg-abc\n")],
     [/^sql backups list/, ok("1760000000000\n")],
@@ -307,9 +331,11 @@ function fakeImageForms(order: string[], down: boolean): ReleaseImageForms {
   return {
     ofIndex,
     of: async (m, slug) => {
+      const index = m.digests[slug];
+      if (!index) return { ok: false, transient: false, message: `no ${slug} image` };
       const signed = m.platformDigests?.[slug];
-      if (signed) return { ok: true, digests: [m.digests[slug], signed], amd64: signed };
-      return ofIndex(slug, m.digests[slug]);
+      if (signed) return { ok: true, digests: [index, signed], amd64: signed };
+      return ofIndex(slug, index);
     },
   };
 }
@@ -393,6 +419,21 @@ describe("runUpgraderJob", () => {
     ]);
   });
 
+  it("#1328: a target manifest without an MCP-Auth-Proxy image stops before anything changes", async () => {
+    const { "mcp-auth-proxy": _none, ...digests } = MANIFEST.digests;
+    const { deps, order, q, written } = setup({
+      manifest: { ok: true, manifest: { ...MANIFEST, digests } },
+    });
+    const r = await runUpgraderJob(deps);
+    expect(r.status).toBe("failed");
+    expect(q.end()?.codes).toEqual(["manifest"]);
+    expect(q.end()?.reason).toContain("names no mcp-auth-proxy image");
+    expect(order.some((l) => l.startsWith("gcloud sql backups create"))).toBe(false);
+    expect(order.some((l) => l.startsWith("migrate "))).toBe(false);
+    expect(order.some((l) => l.startsWith("gcloud run services update"))).toBe(false);
+    expect(written).toEqual([]);
+  });
+
   it("#815: decides first, locks right before the backup, holds the lock to the end", async () => {
     const ok = setup();
     await runUpgraderJob(ok.deps);
@@ -429,6 +470,7 @@ describe("runUpgraderJob", () => {
         "iam projects/acme/serviceAccounts/caelo-production-audit@acme.iam.gserviceaccount.com",
         "iam projects/acme/serviceAccounts/caelo-production-capture@acme.iam.gserviceaccount.com",
         "iam projects/acme/serviceAccounts/caelo-production-gateway-sa@acme.iam.gserviceaccount.com",
+        "iam projects/acme/serviceAccounts/caelo-production-mcp-proxy-sa@acme.iam.gserviceaccount.com",
         "iam projects/acme/serviceAccounts/caelo-production-run-sa@acme.iam.gserviceaccount.com",
         "iam projects/acme/serviceAccounts/caelo-production-upgrader@acme.iam.gserviceaccount.com",
         "iam projects/caelo-website/locations/europe-west1/repositories/caelo-cms-images",
@@ -616,12 +658,21 @@ describe("runUpgraderJob", () => {
 
   it("a revision deployed by tag matches by the digest Cloud Run resolved", async () => {
     const { deps, written } = setup({
-      meta: { ...META, imageDigests: { admin: P("1"), gateway: D("2") } },
+      meta: {
+        ...META,
+        imageDigests: { admin: P("1"), gateway: D("2"), "mcp-auth-proxy": D("3") },
+      },
       gcloud: [
         [
           /^run revisions describe (\S+)/,
           (l) =>
-            ok(l.includes("-admin-") ? revisionJson(null, P("1")) : revisionJson(D("2"), P("2"))),
+            ok(
+              l.includes("-admin-")
+                ? revisionJson(null, P("1"))
+                : l.includes(PROXY)
+                  ? revisionJson(D("3"), P("3"))
+                  : revisionJson(D("2"), P("2")),
+            ),
         ],
       ],
     });
@@ -664,14 +715,20 @@ describe("runUpgraderJob", () => {
 
   it("#815: drift + a stop verdict: the records are corrected under the lock, the verdict stands", async () => {
     const drift = {
-      meta: { ...META, imageDigests: { admin: D("9"), gateway: D("2") }, infraContractVersion: 1 },
+      meta: {
+        ...META,
+        imageDigests: { admin: D("9"), gateway: D("2"), "mcp-auth-proxy": D("3") },
+        infraContractVersion: 1,
+      },
       manifests: { "0.10.45": manifestOf("0.10.45", D("1"), D("2")) },
     };
     const free = setup(drift);
     expect((await runUpgraderJob(free.deps)).status).toBe("needs_cloud_shell");
     expect(free.q.end()?.codes).toEqual(["infra-contract"]);
     expect(free.written).toEqual([
-      expect.objectContaining({ imageDigests: { admin: D("1"), gateway: D("2") } }),
+      expect.objectContaining({
+        imageDigests: { admin: D("1"), gateway: D("2"), "mcp-auth-proxy": D("3") },
+      }),
     ]);
     expect(free.order.indexOf("lock")).toBeGreaterThan(step(free.order, /^manifest 0\.11\.0/));
     expect(free.order).toContain("unlock");
@@ -814,7 +871,8 @@ describe("runUpgraderJob", () => {
     const servingPlatform = (admin: string, gateway: string): [RegExp, Answer] => [
       /^run revisions describe (\S+)/,
       (l) => {
-        const d = l.includes("-admin-") ? admin : gateway;
+        // The MCP-Auth-Proxy serves its recorded index D("3") throughout.
+        const d = l.includes("-admin-") ? admin : l.includes(PROXY) ? D("3") : gateway;
         return ok(revisionJson(d, d));
       },
     ];
@@ -824,12 +882,17 @@ describe("runUpgraderJob", () => {
       const v064 = {
         ...MANIFEST,
         version: "0.10.64",
-        digests: { admin: ADMIN_INDEX, gateway: GATEWAY_INDEX, ops: D("c") },
+        digests: {
+          admin: ADMIN_INDEX,
+          gateway: GATEWAY_INDEX,
+          ops: D("c"),
+          "mcp-auth-proxy": D("3"),
+        },
       };
       const { deps, q, written } = setup({
         meta: {
           ...META,
-          imageDigests: { admin: ADMIN_INDEX, gateway: GATEWAY_INDEX },
+          imageDigests: { admin: ADMIN_INDEX, gateway: GATEWAY_INDEX, "mcp-auth-proxy": D("3") },
           releaseVersion: "0.10.64",
         },
         manifests: { "0.10.64": { ok: true, manifest: v064 } },
@@ -839,7 +902,7 @@ describe("runUpgraderJob", () => {
       expect((await runUpgraderJob(deps)).status).toBe("succeeded");
       expect(written[0]).toMatchObject({
         releaseVersion: "0.10.64",
-        imageDigests: { admin: ADMIN_INDEX, gateway: GATEWAY_INDEX },
+        imageDigests: { admin: ADMIN_INDEX, gateway: GATEWAY_INDEX, "mcp-auth-proxy": D("3") },
         platformDigests: { admin: ADMIN_AMD64, gateway: GATEWAY_AMD64 },
       });
       expect(q.events.some((e) => e.message.startsWith("0.10.64 → 0.11.0"))).toBe(true);
@@ -861,6 +924,7 @@ describe("runUpgraderJob", () => {
       expect(order.filter((l) => l.startsWith("index "))).toEqual([
         `index admin@${D("a")}`,
         `index gateway@${D("b")}`,
+        `index mcp-auth-proxy@${D("d")}`,
       ]);
       expect(q.events.some((e) => e.message.includes("refreshed its install records"))).toBe(false);
     });
@@ -868,14 +932,14 @@ describe("runUpgraderJob", () => {
     it("the roll records the new release's platform forms, signed ones first", async () => {
       const signed = {
         ...MANIFEST,
-        platformDigests: { admin: P("x"), gateway: P("y"), ops: P("z") },
+        platformDigests: { admin: P("x"), gateway: P("y"), ops: P("z"), "mcp-auth-proxy": P("w") },
       };
       const { deps, order, written } = setup({ manifest: { ok: true, manifest: signed } });
       expect((await runUpgraderJob(deps)).status).toBe("succeeded");
       expect(written.at(-1)).toMatchObject({
         releaseVersion: "0.11.0",
-        imageDigests: { admin: D("a"), gateway: D("b") },
-        platformDigests: { admin: P("x"), gateway: P("y") },
+        imageDigests: { admin: D("a"), gateway: D("b"), "mcp-auth-proxy": D("d") },
+        platformDigests: { admin: P("x"), gateway: P("y"), "mcp-auth-proxy": P("w") },
       });
       expect(order.some((l) => l.startsWith("index "))).toBe(false);
     });
@@ -886,7 +950,11 @@ describe("runUpgraderJob", () => {
         imageForms: "down",
       });
       expect((await runUpgraderJob(deps)).status).toBe("succeeded");
-      expect(written.at(-1)?.imageDigests).toEqual({ admin: D("a"), gateway: D("b") });
+      expect(written.at(-1)?.imageDigests).toEqual({
+        admin: D("a"),
+        gateway: D("b"),
+        "mcp-auth-proxy": D("d"),
+      });
       expect(written.at(-1)?.platformDigests).toBeUndefined();
       expect(q.events.some((e) => e.level === "warn" && e.message.includes("linux/amd64"))).toBe(
         true,
@@ -995,7 +1063,9 @@ describe("runUpgraderJob", () => {
       manifests: { "0.10.45": manifestOf("0.10.45", D("1"), D("2")) },
     });
     expect((await runUpgraderJob(deps)).status).toBe("needs_cloud_shell");
-    expect(q.end()?.reason).toContain("The admin serves v0.10.45's image, the gateway does not");
+    expect(q.end()?.reason).toContain(
+      "The admin and the MCP-Auth-Proxy serve v0.10.45's image, the gateway does not",
+    );
     expect(written).toEqual([]);
   });
 
@@ -1021,8 +1091,12 @@ describe("runUpgraderJob", () => {
     expect((await runUpgraderJob(deps)).status).toBe("needs_cloud_shell");
     const end = q.end();
     expect(end?.codes).toEqual(["install-state-drift"]);
-    expect(end?.reason).toContain("The gateway serves v0.10.45's image, the admin does not");
-    expect(end?.reason).toContain("the admin serves v0.10.44's image, the gateway does not");
+    expect(end?.reason).toContain(
+      "The gateway and the MCP-Auth-Proxy serve v0.10.45's image, the admin does not",
+    );
+    expect(end?.reason).toContain(
+      "the admin and the MCP-Auth-Proxy serve v0.10.44's image, the gateway does not",
+    );
     expect(written).toEqual([]);
   });