@caelo-cms/provisioning 0.10.53 → 0.10.57

package/src/upgrader-setup.ts

@@ -17,12 +17,23 @@
  * The job's own service account, `caelo-<env>-upgrader`, may do exactly
  * what an app-roll needs (upgrade/app-roll.ts):
  *
- *   - `roles/run.developer` on the project: deploy admin/gateway revisions,
- *     move traffic, recreate the migration job, update its own job image.
- *     It includes no `*.setIamPolicy`.
+ *   - the custom role `caeloUpgraderRun` on the project
+ *     ({@link UPGRADER_RUN_ROLE}): deploy admin/gateway revisions, move
+ *     traffic, recreate and run the migration job, update its own job image.
+ *     NOT `roles/run.developer`: that role holds `run.jobs.runWithOverrides`
+ *     on every job of the project, including the converge job and the
+ *     install job, which run as `caelo-provisioner` — the upgrader could run
+ *     them with its own args (destroy, owner-reset) or env (CLOUDSDK_*,
+ *     PULUMI_*) and so act as the provisioner (#883 review). The custom role
+ *     has no `runWithOverrides` and no `*.setIamPolicy`. Updating another
+ *     job (the converge job's image, say) additionally needs `actAs` on its
+ *     service account, which the upgrader holds only on the admin, gateway
+ *     and its own. A grant of `roles/run.developer` left by an earlier
+ *     setup is removed.
  *   - `roles/iam.serviceAccountUser` on exactly the admin's and the
- *     gateway's runtime service accounts (a revision runs as them) and on
- *     itself (its own job) — not on the project.
+ *     gateway's runtime service accounts (a revision runs as them), on
+ *     itself (its own job) and on the quality-audit job's account (the
+ *     app-roll moves that job's image, #875) — not on the project.
  *   - the custom role `caeloUpgraderSqlBackup`: create/read Cloud SQL
  *     backups and read the instance — no restore, no instance changes.
  *   - `roles/cloudsql.instanceUser` + a Cloud SQL IAM database user that
@@ -45,12 +56,26 @@
  * is a converge, which only the operator runs ("Run in Cloud Shell").
  * {@link UPGRADER_FORBIDDEN_ROLES} names that line; the tests assert no
  * grant crosses it.
+ *
+ * Direct VPC egress (#818): the migration job and both services run with
+ * `--network/--subnet`. Google documents the compute permissions that needs
+ * (`compute.subnetworks.use`, `compute.addresses.createInternal`, …) on the
+ * Cloud Run service agent, which `roles/run.serviceAgent` already gives it
+ * (cloud.google.com/run/docs/configuring/vpc-direct-vpc), not on the
+ * principal that deploys. So the upgrader gets no compute role; the
+ * real-GCP upgrader smoke test (.github/workflows/upgrader-smoke.yml) shows
+ * it once a stable release was installed on the smoke install through
+ * Settings → Updates (the next tag cannot ship before). Every permission
+ * the job needs is checked by the job itself before it changes anything
+ * (upgrader-iam-preflight.ts);
+ * a grant added or removed here must keep that list in step.
  */
 
 import { ensureCloudSqlIamUser } from "./cloudsql-iam-user.js";
 import { gcloud as defaultGcloud, type GcloudResult } from "./gcloud.js";
 import { type GcloudRunner, realSleep, runWithRetry, type Sleep } from "./gcloud-retry.js";
 import {
+  auditServiceAccountEmail,
   gatewayServiceAccountEmail,
   mcpIapServiceAccountEmail,
   runServiceAccountEmail,
@@ -89,22 +114,72 @@ export const UPGRADER_OPS_LIST_ROLE: CustomRoleSpec = {
   permissions: ["storage.objects.list"],
 };
 
-/** Project-level roles of the upgrader's service account. */
+/**
+ * What an app-roll does on Cloud Run (upgrade/app-roll.ts, migration-runner.ts,
+ * the self-update, the #815 lock lease) — `roles/run.developer` minus
+ * everything else, above all `run.jobs.runWithOverrides` (see the file
+ * header). Keep in step with upgrader-iam-preflight.ts.
+ */
+export const UPGRADER_RUN_ROLE: CustomRoleSpec = {
+  roleId: "caeloUpgraderRun",
+  title: "Caelo upgrader: roll Cloud Run",
+  description:
+    "Lets the Caelo upgrader job deploy admin/gateway revisions, run the migration job and update its own image. Cannot start any job with changed arguments or env, cannot change IAM.",
+  permissions: [
+    "run.configurations.get",
+    "run.configurations.list",
+    "run.executions.get",
+    "run.executions.list",
+    "run.jobs.create",
+    "run.jobs.delete",
+    "run.jobs.get",
+    "run.jobs.list",
+    "run.jobs.run",
+    "run.jobs.update",
+    "run.operations.get",
+    "run.revisions.get",
+    "run.revisions.list",
+    "run.routes.get",
+    "run.routes.list",
+    "run.services.get",
+    "run.services.list",
+    "run.services.update",
+    "run.tasks.get",
+    "run.tasks.list",
+  ],
+};
+
+/** Project-level predefined roles of the upgrader's service account. */
 export const UPGRADER_PROJECT_ROLES = [
-  "roles/run.developer",
   "roles/cloudsql.instanceUser",
   "roles/logging.logWriter",
 ] as const;
 
+/**
+ * Predefined roles that hold `run.jobs.runWithOverrides`. Neither the
+ * upgrader nor the admin may hold any of them anywhere: with it, either
+ * could run the converge or install job — which run as caelo-provisioner —
+ * with its own arguments or environment (#883 review).
+ */
+export const RUN_WITH_OVERRIDES_ROLES = [
+  "roles/owner",
+  "roles/editor",
+  "roles/run.admin",
+  "roles/run.developer",
+  "roles/run.invoker",
+  "roles/run.jobsExecutorWithOverrides",
+] as const;
+
+/** A project-level grant an earlier setup gave the upgrader; removed on every setup. */
+const LEGACY_UPGRADER_PROJECT_ROLES = ["roles/run.developer"] as const;
+
 /**
  * Roles the upgrader must never hold anywhere — they would let it change
  * IAM, manage service accounts or secrets, or touch compute/projects.
  * Prefix matches (`roles/compute.` = every compute role).
  */
 export const UPGRADER_FORBIDDEN_ROLES = [
-  "roles/owner",
-  "roles/editor",
-  "roles/run.admin",
+  ...RUN_WITH_OVERRIDES_ROLES,
   "roles/iam.serviceAccountAdmin",
   "roles/iam.serviceAccountKeyAdmin",
   "roles/iam.securityAdmin",
@@ -122,8 +197,14 @@ export const UPGRADER_FORBIDDEN_ROLES = [
 /** Database role migration 0267 creates for the job. */
 export const UPGRADER_DB_ROLE = "platform_updater";
 
-/** The job's resources: enough for a backup + roll; the job ends within it. */
-const JOB_TASK_TIMEOUT = "60m";
+/**
+ * The job's task timeout in minutes: enough for a backup + roll; the job
+ * ends within it. It is also the lease on the state lock the job takes
+ * (#815, state-lock-lease.ts): after it, Cloud Run has killed the run.
+ */
+export const UPGRADER_TASK_TIMEOUT_MINUTES = 60;
+
+const JOB_TASK_TIMEOUT = `${UPGRADER_TASK_TIMEOUT_MINUTES}m`;
 
 export interface UpgraderSetupTarget {
   readonly projectId: string;
@@ -195,7 +276,7 @@ export async function ensureUpgraderJob(
   }
 
   // 1. The backup and ops-bucket-list roles.
-  for (const role of [UPGRADER_SQL_BACKUP_ROLE, UPGRADER_OPS_LIST_ROLE]) {
+  for (const role of [UPGRADER_RUN_ROLE, UPGRADER_SQL_BACKUP_ROLE, UPGRADER_OPS_LIST_ROLE]) {
     const roleError = await ensureCustomRole(run, projectId, role);
     if (roleError) return { ok: false, done, error: roleError };
     done.push(`custom role ${role.roleId}`);
@@ -227,6 +308,7 @@ export async function ensureUpgraderJob(
   // 3. Project-level roles.
   for (const role of [
     ...UPGRADER_PROJECT_ROLES,
+    customRoleName(projectId, UPGRADER_RUN_ROLE.roleId),
     customRoleName(projectId, UPGRADER_SQL_BACKUP_ROLE.roleId),
   ]) {
     const r = await retry([
@@ -243,6 +325,34 @@ export async function ensureUpgraderJob(
     done.push(`upgrader: ${role} on the project`);
   }
 
+  // 3b. The project-wide roles/run.developer an earlier setup granted holds
+  //     run.jobs.runWithOverrides on the provisioner's jobs: take it away.
+  //     Only after the custom role above is bound, so a running upgrade
+  //     never loses its Cloud Run rights in between.
+  const policy = await run(["projects", "get-iam-policy", projectId, "--format=json"]);
+  if (!policy.ok) return fail("read the project's IAM policy", policy);
+  for (const role of LEGACY_UPGRADER_PROJECT_ROLES) {
+    let held: boolean;
+    try {
+      held = projectPolicyHas(policy.stdout, role, member);
+    } catch (e) {
+      return { ok: false, done, error: `read the project's IAM policy: ${String(e)}` };
+    }
+    if (!held) continue;
+    const r = await retry([
+      "projects",
+      "remove-iam-policy-binding",
+      projectId,
+      `--member=${member}`,
+      `--role=${role}`,
+      "--all",
+      "--quiet",
+      "--format=none",
+    ]);
+    if (!r.ok) return fail(`remove the upgrader's ${role}`, r);
+    done.push(`upgrader: removed ${role} on the project`);
+  }
+
   // 4. Resource-level grants on single service accounts.
   const onAccounts: { account: string; role: string; why: string }[] = [
     {
@@ -256,6 +366,11 @@ export async function ensureUpgraderJob(
       why: "gateway revisions run as it",
     },
     { account: sa, role: "roles/iam.serviceAccountUser", why: "the job updates its own image" },
+    {
+      account: auditServiceAccountEmail(projectId, env),
+      role: "roles/iam.serviceAccountUser",
+      why: "the app-roll moves the quality-audit job, which runs as it, onto the new image",
+    },
     {
       account: mcpIapServiceAccountEmail(projectId),
       role: "roles/iam.serviceAccountTokenCreator",
@@ -366,6 +481,15 @@ export async function ensureUpgraderJob(
   return { ok: true, done };
 }
 
+/** Whether a gcloud IAM policy (JSON) grants `role` to `member`. */
+export function projectPolicyHas(policyJson: string, role: string, member: string): boolean {
+  // Throws on unreadable JSON: the caller reports it, never guesses "absent".
+  const policy = JSON.parse(policyJson.trim() || "{}") as {
+    bindings?: { role: string; members?: string[] }[];
+  };
+  return (policy.bindings ?? []).some((b) => b.role === role && (b.members ?? []).includes(member));
+}
+
 /**
  * {@link ensureUpgraderJob}'s target, with the VPC read from the deployed
  * admin service (the job reaches Cloud SQL's private IP the same way).

package/src/wizards/gcp-cost.ts

@@ -101,10 +101,10 @@ export function estimateGcpCost(inputs: CostEstimateInputs): {
           : `${inputs.adminMinInstances} min-instance${inputs.adminMinInstances > 1 ? "s" : ""} (no cold start)`,
     },
     {
-      name: "Quality checks (Lighthouse on the admin)",
-      monthlyUsd: 1,
+      name: "Quality checks (Cloud Run audit job)",
+      monthlyUsd: 2,
       notes:
-        "~2-4 min of admin CPU per audited Stage (up to 5 pages x 5 runs); ~$1/mo at a few Stages a day",
+        "one container per Lighthouse run, all in parallel (up to 5 pages x 3 runs, ~90 s at 2 vCPU each): ~$0.05 per audited Stage, partly in the free tier; results bucket ~$0",
     },
     {
       name: "Cloud Run gateway",
@@ -138,6 +138,14 @@ export function estimateGcpCost(inputs: CostEstimateInputs): {
               ? "Adaptive protection (ML-based bot mitigation)"
               : "Free tier — rate limit + OWASP basic rules",
           },
+          {
+            // #806 — the remote-MCP throttle (src/remote-mcp-edge.ts) is one
+            // more rule on the gateway's policy; Cloud Armor Standard bills
+            // each rule at about $1/mo.
+            name: "Cloud Armor rule: remote MCP throttle",
+            monthlyUsd: 1,
+            notes: "Per-IP throttle for /api/mcp/* (remote MCP clients)",
+          },
         ] satisfies CostLine[])
       : ([
           {
@@ -155,9 +163,10 @@ export function estimateGcpCost(inputs: CostEstimateInputs): {
       notes: "~5 GB storage + low egress; growth roughly $0.02/GB",
     },
     {
-      name: "Secret Manager (5 secrets)",
-      monthlyUsd: 0,
-      notes: "Free tier",
+      name: "Secret Manager (runtime secrets)",
+      monthlyUsd: 0.2,
+      notes:
+        "6 active versions free, then ~$0.06 each; remote MCP (#806) adds the OAuth client and its seal key",
     },
     {
       name: "BigQuery edge log sink",

package/src/wizards/gcp-pulumi.ts

@@ -13,6 +13,7 @@
 
 import { resolve as resolvePath } from "node:path";
 import * as pulumi from "@pulumi/pulumi/automation";
+import { AUDIT_PARALLELISM_DEFAULT } from "../audit-job-setup.js";
 import { checkpointableOutputs } from "../checkpoint-secrets.js";
 import { GCP_STACK_ENV } from "../gcp-names.js";
 import type { ImageDigests } from "../install-state.js";
@@ -36,6 +37,12 @@ export const GCP_STACK_KNOB_DEFAULTS = {
   adminMemory: ADMIN_MEMORY_DEFAULT,
   gatewayMinInstances: 0,
   wafAdaptiveProtection: false,
+  /**
+   * #875 — audit tasks at once. Not stack config: the audit job is
+   * CLI-owned (audit-job-setup.ts), so the wizard passes it to the job and
+   * `upgrade` keeps whatever the job has.
+   */
+  auditParallelism: AUDIT_PARALLELISM_DEFAULT,
 } as const;
 
 export interface PulumiUpInputs {

package/src/wizards/gcp.ts

@@ -33,8 +33,10 @@ import { join } from "node:path";
 import { cancel, confirm, isCancel, log, note, select, spinner } from "@clack/prompts";
 import { bold, cyan, dim, green, red, yellow } from "kleur/colors";
 import { checkAdcImpersonation } from "../adc-impersonation.js";
+import { ensureAuditJob, resolveAdminImage } from "../audit-job-setup.js";
 import { CERT_WAIT_TIMEOUT_MS, lbCertProbe, waitForCert } from "../cert-wait.js";
 import { redactCredentials } from "../checkpoint-secrets.js";
+import { ensureConvergeJob } from "../converge-job-setup.js";
 import { removeDefaultFirewallRules } from "../default-firewall.js";
 import {
   checkDeployedRuntimeEnv,
@@ -100,6 +102,7 @@ import {
 } from "../provisioner-identity.js";
 import { revokePublicRoleMemberships } from "../public-role-isolation.js";
 import { decideRegion, detectCliRegion, installableRegions, suggestRegion } from "../regions.js";
+import { ensureRemoteMcpEdge, ensureRemoteMcpIdentityEnv } from "../remote-mcp.js";
 import type { RunMode } from "../run-mode.js";
 import { selfCommand } from "../self-command.js";
 import { ABSENT_DEFAULT_FIREWALL_RULES } from "../stack-contract.js";
@@ -114,6 +117,7 @@ import {
   resolveBackend,
 } from "../state-backend.js";
 import { acquireStateLock, GcsStateStore } from "../state-store.js";
+import { resolveGcpResourceName } from "../upgrade/gcp-lookup.js";
 import {
   releaseVersionForDigest,
   resolveOpsImageRef,
@@ -454,11 +458,17 @@ export async function runGcpConverge(opts: GcpConvergeOpts): Promise<void> {
 
   phase("Finishing: operator access, welcome page");
 
+  // === 11.3. The quality-audit job: parallel Lighthouse runs (#875) ===
+  // Before the upgrader, which gets actAs on the job's service account.
+  await stepAuditJob(projectId, region, provider);
+
   // === 11.4. The upgrader job: Settings → Updates → Install update (#696) ===
   // Before operator access, which keeps the upgrader's caelo-mcp grant.
   const releaseVersion = await releaseVersionForDigest(gcloud, "admin", imageDigests.admin);
   const upgraderReady = await stepUpgraderJob(projectId, region, releaseVersion);
   const keepSigner = upgraderReady || (await upgraderExists(projectId));
+  // === 11.45. The converge job: releases that change the cloud setup (#819) ===
+  const convergeReady = await stepConvergeJob(projectId, region, releaseVersion);
 
   // === 11.5. Operator access: IAP follows the Caelo user list ===
   await stepOperatorAccessSync(
@@ -469,11 +479,18 @@ export async function runGcpConverge(opts: GcpConvergeOpts): Promise<void> {
     keepSigner ? [`serviceAccount:${upgraderServiceAccountEmail(projectId, GCP_STACK_ENV)}`] : [],
   );
 
+  // === 11.6. Remote MCP (#806): LB rules (gcp) + the identity env ===
+  // After `pulumi up` on every pass: the identity env names services Pulumi
+  // generated, so the stack cannot declare it, and an `up` that changed a
+  // service's template dropped it (remote-mcp.ts).
+  const remoteMcpReady = await stepRemoteMcp(projectId, region, provider, domain);
+
   // A fresh install ran every converge step above, so it is at this CLI's
-  // infrastructure contract — recorded only when the upgrader is in place
-  // (the last step a contract bump added). With the release version, the
-  // admin can install the next update itself.
-  if (upgraderReady) {
+  // infrastructure contract — recorded only when the upgrader and the
+  // converge job are in place (the steps contract bumps 2 and 9 added) and
+  // remote MCP's steps (#806, bump 10) succeeded. With the release version,
+  // the admin can install the next update itself.
+  if (upgraderReady && convergeReady && remoteMcpReady) {
     const version = releaseVersion;
     recordImageDigests(installId, imageDigests, version);
     recordInfraContractVersion(installId, INFRA_CONTRACT_VERSION);
@@ -976,6 +993,95 @@ async function stepUpgraderJob(
   return true;
 }
 
+/**
+ * Set up the converge job (converge-job-setup.ts, #819): what the admin's
+ * "Install update" starts for a release that changes the cloud setup. Same
+ * shape as {@link stepUpgraderJob}: after migrations (its database login
+ * gets migration 0267's role), only a verified ops image, and a failure
+ * only warns — such releases then install from a terminal until a later
+ * `upgrade` sets the job up. Idempotent.
+ *
+ * @returns whether the job is ready
+ */
+async function stepConvergeJob(
+  projectId: string,
+  region: string,
+  releaseVersion: string | null,
+): Promise<boolean> {
+  const opsImageRef = releaseVersion ? await resolveOpsImageRef(releaseVersion) : null;
+  const digest = opsImageRef ? /@(sha256:[0-9a-f]{64})$/.exec(opsImageRef)?.[1] : undefined;
+  // The job runs as the provisioner: only a verified image, ever.
+  if (digest && !(await verifyCosignAll([{ slug: "ops", digest }]))) {
+    log.warn(
+      `The converge job is not set up: its image's signature did not verify. The install works; ${bold(selfCommand("upgrade"))} sets it up later.`,
+    );
+    return false;
+  }
+  const s = spinner();
+  s.start("Setting up the converge job (cloud-setup updates from the admin)...");
+  const resolved = opsImageRef
+    ? await resolveUpgraderTarget({ projectId, region, env: GCP_STACK_ENV, opsImageRef })
+    : {
+        ok: false as const,
+        error: releaseVersion
+          ? `release ${releaseVersion} has no caelo-ops image in the registry`
+          : "the release this install runs could not be told from its images",
+      };
+  const r = resolved.ok
+    ? await ensureConvergeJob(resolved.target)
+    : { ok: false as const, done: [], error: resolved.error };
+  if (!r.ok && r.reason === "no-provisioner") {
+    // #883 review — not needed for the contract: such an install installs
+    // cloud-setup releases from a terminal, and its admin says so.
+    s.stop(yellow("No converge job: this install has no caelo-provisioner to run it as"));
+    log.info(
+      "Releases that change the cloud setup install from a terminal; Settings → Updates says so when one comes.",
+    );
+    return true;
+  }
+  if (!r.ok) {
+    s.stop(yellow(`Converge job not set up: ${r.error}`));
+    log.warn(
+      `The install works; releases that change the cloud setup install from a terminal until ${bold(selfCommand("upgrade"))} sets the job up.`,
+    );
+    return false;
+  }
+  s.stop(green(`Converge job ready (${r.done.length} steps)`));
+  return true;
+}
+
+/**
+ * Set up the quality-audit job (audit-job-setup.ts) on the deployed admin's
+ * image. A failure stops the wizard: without the job every Stage audit
+ * fails. Idempotent, so it runs on every wizard pass.
+ */
+async function stepAuditJob(
+  projectId: string,
+  region: string,
+  provider: "gcp" | "gcp-firebase",
+): Promise<void> {
+  const s = spinner();
+  s.start("Setting up the quality-audit job (parallel Lighthouse runs)...");
+  const image = await resolveAdminImage({ projectId, region, env: GCP_STACK_ENV });
+  const r = image.ok
+    ? await ensureAuditJob({
+        provider,
+        projectId,
+        region,
+        env: GCP_STACK_ENV,
+        adminImageRef: image.imageRef,
+        parallelism: GCP_STACK_KNOB_DEFAULTS.auditParallelism,
+      })
+    : { ok: false as const, done: [], error: image.error };
+  if (!r.ok) {
+    s.stop(red(`Failed: ${r.error}`));
+    log.error("Re-run the wizard once the cause is fixed (this step is idempotent).");
+    cancel("Aborted.");
+    process.exit(1);
+  }
+  s.stop(green(`Quality-audit job ready (${r.done.length} steps)`));
+}
+
 /**
  * Whether an upgrader set up by an earlier run exists, so a failed setup
  * this time still keeps its caelo-mcp signing grant (the operator-access
@@ -1027,6 +1133,58 @@ async function stepOperatorAccessSync(
   s.stop(green(`Operator-access sync job ready (${r.done.length} steps)`));
 }
 
+/**
+ * #806 — the CLI's part of remote MCP (remote-mcp.ts): on `gcp` the load
+ * balancer's discovery routes and Cloud Armor rule, on both providers the
+ * env vars naming the admin URL, the broker's public URL and the IAP
+ * audience. Remote MCP stays off until the Owner sets it up under Settings →
+ * MCP, so a failure does not stop the install: it warns, and the next pass
+ * or `upgrade` retries. Idempotent.
+ *
+ * @returns whether every part is in place
+ */
+async function stepRemoteMcp(
+  projectId: string,
+  region: string,
+  provider: "gcp" | "gcp-firebase",
+  domain: string,
+): Promise<boolean> {
+  const s = spinner();
+  s.start(
+    "Preparing remote MCP (ChatGPT / claude.ai connectors; off until the Owner enables it)...",
+  );
+  const name = (slug: "admin" | "gateway") =>
+    resolveGcpResourceName(
+      gcloud,
+      "run-service",
+      `caelo-${GCP_STACK_ENV}-${slug}`,
+      projectId,
+      region,
+    );
+  const [admin, gateway] = [await name("admin"), await name("gateway")];
+  const failed = (error: string) => {
+    s.stop(yellow(`Remote MCP not prepared: ${error}`));
+    log.warn(
+      `The install works; Settings → MCP reports remote MCP as unavailable until ${bold(selfCommand("upgrade"))} prepares it.`,
+    );
+    return false;
+  };
+  if (!admin || !gateway) return failed("the admin or gateway Cloud Run service was not found");
+  const edge = await ensureRemoteMcpEdge({ provider, projectId, env: GCP_STACK_ENV, domain });
+  if (!edge.ok) return failed(edge.error);
+  const env = await ensureRemoteMcpIdentityEnv({
+    provider,
+    projectId,
+    region,
+    env: GCP_STACK_ENV,
+    domain,
+    services: { admin, gateway },
+  });
+  if (!env.ok) return failed(env.error);
+  s.stop(green(`Remote MCP prepared (${env.identity.mcpPublicUrl})`));
+  return true;
+}
+
 /**
  * Delete the firewall rules GCP pre-populates on the `default` network
  * (SSH, RDP, ICMP, internal; default-firewall.ts). A customised rule of the

package/stacks/aws/index.ts

@@ -349,10 +349,28 @@ new aws.cloudwatch.LogDelivery(
 //
 // Each Caelo service runs as its own Fargate service; sharing a cluster
 // keeps the per-month Fargate-cluster fee at zero (clusters are free).
+//
+// FIXME(issue #749): no quality-audit task definition yet. On GCP every
+// Lighthouse run of a Stage audit runs in its own container (#875,
+// src/audit-job-setup.ts); the AWS equivalent is a Fargate task per run
+// (admin-core quality/parallel-runner.ts `AuditTaskLauncher`). Until it
+// exists the admin records every Lighthouse audit as failed with that gap
+// (quality/lighthouse-runner-select.ts) instead of measuring on its own
+// shared CPU. Nothing is staged on AWS before #749 either.
+//
+// FIXME(issue #696): no in-cloud upgrader or converge job (#819) yet. On
+// GCP Settings → Updates hands app-roll releases to the upgrader job and
+// cloud-setup releases to the converge job; on AWS the admin refuses a
+// cloud-setup release with the CLI command that installs it (admin-core
+// platform-updates/update-route.ts) until this adapter gains both jobs.
 const cluster = new aws.ecs.Cluster(`${namePrefix}-ecs`, {
   settings: [{ name: "containerInsights", value: "enabled" }],
 });
 
+// #806 — no remote MCP on AWS: it rides Google IAP (gcp stacks only). The
+// gateway task definition, once it exists, sets none of its env, so /api/mcp/*
+// answers 503 remote_mcp_not_configured and the admin reports it unavailable.
+//
 // One task role per service (#635): the gateway's may read only the
 // public_role password, never a secret that unlocks a cms_admin login
 // (src/aws-task-roles.ts AWS_SERVICE_SECRETS, asserted by

package/stacks/azure/index.ts

@@ -330,6 +330,21 @@ const logWorkspace = new azure.operationalinsights.Workspace(`${namePrefix}-logs
 });
 
 // === 6. Container Apps environment + apps ===
+//
+// FIXME(issue #750): no quality-audit Container Apps job yet. On GCP every
+// Lighthouse run of a Stage audit runs in its own container (#875,
+// src/audit-job-setup.ts); the Azure equivalent is a Container Apps job
+// with one replica per run (admin-core quality/parallel-runner.ts
+// `AuditTaskLauncher`). Until it exists the admin records every Lighthouse
+// audit as failed with that gap (quality/lighthouse-runner-select.ts)
+// instead of measuring on its own shared CPU. Nothing is staged on Azure
+// before #750 either.
+//
+// FIXME(issue #696): no in-cloud upgrader or converge job (#819) yet. On
+// GCP Settings → Updates hands app-roll releases to the upgrader job and
+// cloud-setup releases to the converge job; on Azure the admin refuses a
+// cloud-setup release with the CLI command that installs it (admin-core
+// platform-updates/update-route.ts) until this adapter gains both jobs.
 const cappEnv = new azure.app.ManagedEnvironment(`${namePrefix}-capp-env`, {
   resourceGroupName: rg.name,
   environmentName: `${namePrefix}-capp-env`,
@@ -421,6 +436,9 @@ const _gatewayApp = containerApp({
   serviceName: "gateway",
   databaseEnv: [{ name: "PUBLIC_DATABASE_URL", value: publicDatabaseUrl }],
   // Which X-Forwarded-For entry is the visitor (api-gateway client-ip.ts).
+  // #806 — no remote-MCP env: remote MCP rides Google IAP (gcp stacks
+  // only); unset, the gateway answers /api/mcp/* with 503
+  // remote_mcp_not_configured and the admin reports it unavailable.
   extraEnv: [{ name: TRUSTED_PROXY_HOPS_ENV, value: String(GATEWAY_TRUSTED_PROXY_HOPS.azure) }],
 });
 const _orchestratorApp = containerApp({