@caelo-cms/provisioning 0.11.3 → 0.11.4

package/src/capture-job-setup.ts

@@ -0,0 +1,322 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * #1217 — set up (and converge) the capture job on a Google Cloud install
+ * (`gcp`, `gcp-firebase`): the short-lived Cloud Run job that runs every
+ * server-side browser render (screenshot_page's server path, the external
+ * page tools, the site-import crawl), one execution per render. Run by the
+ * wizard after `pulumi up` and by `cms-provision upgrade`'s converge, both as
+ * the operator's own gcloud identity. App-roll moves the job's image with the
+ * admin's (upgrade/admin-image-jobs.ts), because the job runs the admin image
+ * (which bundles Chromium, #428).
+ *
+ * Why a separate job at all (CLAUDE.md §11.B Tier 5, second exception after
+ * the audit job): a headless Chromium costs 300–700 MB per render, and inside
+ * the 2 GiB admin it was the most plausible cause of the OOM kill of
+ * 2026-10-28 (#1209). In a job it costs the admin nothing.
+ *
+ * Why the CLI owns it and not the stacks: the same as audit-job-setup.ts —
+ * `upgrade` never runs Pulumi.
+ *
+ * Trust boundary. The job renders untrusted pages (third-party sites, module
+ * scripts in a preview), so its identity, `caelo-<env>-capture`, holds:
+ *
+ *   - `roles/storage.objectCreator` on the capture bucket, conditioned to the
+ *     `out/` prefix — create results only: it cannot read, overwrite or list
+ *     anything, nor write where the admin puts inputs;
+ *   - `roles/logging.logWriter`.
+ *
+ * Nothing else: no read right anywhere (its input and the preview's media
+ * arrive as V4 signed URLs the admin creates per capture, valid 5 minutes,
+ * deleted with the capture), no Secret Manager, no Cloud SQL, no VPC egress,
+ * and no IAP access to the admin — a browser exploit in the job reaches
+ * nothing but the internet it already renders.
+ *
+ * The admin's run SA may run the job WITH overrides (it passes the order),
+ * read its executions, use the capture bucket (`roles/storage.objectUser`:
+ * write inputs, read results, delete both) and sign URLs as itself
+ * (`roles/iam.serviceAccountTokenCreator` on its own account only: Cloud Run
+ * holds no key, so V4 signing goes through IAM signBlob; the admin can mint
+ * its own tokens through the metadata server already, so this widens
+ * nothing). {@link CAPTURE_FORBIDDEN_ROLES} names the job's line; the tests
+ * assert no grant crosses it.
+ */
+
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { gcloud as defaultGcloud, type GcloudResult } from "./gcloud.js";
+import { type GcloudRunner, realSleep, runWithRetry, type Sleep } from "./gcloud-retry.js";
+import {
+  captureJobName,
+  captureServiceAccountEmail,
+  captureServiceAccountId,
+  gcpBucketName,
+  runServiceAccountEmail,
+} from "./gcp-names.js";
+import type { GcpProvider } from "./stack-contract.js";
+
+/** Where the admin image ships the task's entry point. */
+export const CAPTURE_TASK_SCRIPT = "/app/packages/admin-core/src/capture/capture-task.ts";
+
+/** Per execution: container start, browser start and one render. */
+const TASK_TIMEOUT = "3m";
+
+/**
+ * Roles the capture job's identity must never hold anywhere. Prefix matches
+ * (`roles/secretmanager.` = every Secret Manager role). Unlike the audit job
+ * it reads nothing, so every storage read role is on the list too.
+ */
+export const CAPTURE_FORBIDDEN_ROLES = [
+  "roles/owner",
+  "roles/editor",
+  "roles/viewer",
+  "roles/run.",
+  "roles/iam.",
+  "roles/iap.",
+  "roles/secretmanager.",
+  "roles/cloudsql.",
+  "roles/compute.",
+  "roles/resourcemanager.",
+  "roles/storage.admin",
+  "roles/storage.objectAdmin",
+  "roles/storage.objectUser",
+  "roles/storage.objectViewer",
+  "roles/storage.legacy",
+] as const;
+
+/** Inputs and results are deleted by the admin; the lifecycle catches leftovers. */
+export const CAPTURE_BUCKET_LIFECYCLE = {
+  rule: [{ action: { type: "Delete" }, condition: { age: 1 } }],
+};
+
+/** The IAM condition that confines the job's create right to `out/`. */
+export function captureResultsCondition(bucket: string): string {
+  return `expression=resource.name.startsWith("projects/_/buckets/${bucket}/objects/out/"),title=capture-results-only,description=The capture job creates its results under out/ and nothing else`;
+}
+
+export interface CaptureJobTarget {
+  readonly provider: GcpProvider;
+  readonly projectId: string;
+  readonly region: string;
+  /** Pulumi stack name (`production`). */
+  readonly env: string;
+  /** The admin image the job runs, digest-pinned (`…/admin@sha256:…`). */
+  readonly adminImageRef: string;
+}
+
+export type CaptureJobResult =
+  | { readonly ok: true; readonly done: string[] }
+  | { readonly ok: false; readonly done: string[]; readonly error: string };
+
+/** Ensure the capture job and everything it needs. Never throws for a gcloud failure. */
+export async function ensureCaptureJob(
+  target: CaptureJobTarget,
+  deps: { run?: GcloudRunner; sleep?: Sleep } = {},
+): Promise<CaptureJobResult> {
+  const run = deps.run ?? defaultGcloud;
+  const sleep = deps.sleep ?? realSleep;
+  const retry = (args: string[]) => runWithRetry(run, sleep, args);
+  const { projectId, region, env, provider } = target;
+  const project = `--project=${projectId}`;
+  const sa = captureServiceAccountEmail(projectId, env);
+  const member = `serviceAccount:${sa}`;
+  const runSa = runServiceAccountEmail(projectId, env);
+  const runSaMember = `serviceAccount:${runSa}`;
+  const job = captureJobName(env);
+  const bucket = gcpBucketName(projectId, env, "capture");
+  const bucketUrl = `gs://${bucket}`;
+  const done: string[] = [];
+  const fail = (step: string, r: GcloudResult): CaptureJobResult => ({
+    ok: false,
+    done,
+    error: `${step}: ${r.stderr.trim()}`,
+  });
+
+  if (!/@sha256:[0-9a-f]{64}$/.test(target.adminImageRef)) {
+    return {
+      ok: false,
+      done,
+      error: `the capture job's image must be pinned by digest, got ${target.adminImageRef}`,
+    };
+  }
+
+  // 1. The job's own service account.
+  const describe = await run([
+    "iam",
+    "service-accounts",
+    "describe",
+    sa,
+    project,
+    "--format=value(email)",
+  ]);
+  if (!describe.ok) {
+    const create = await run([
+      "iam",
+      "service-accounts",
+      "create",
+      captureServiceAccountId(env),
+      "--display-name=Caelo capture",
+      "--description=Runs server-side browser renders (screenshots); creates capture results, nothing else.",
+      project,
+    ]);
+    if (!create.ok && !/already exists/i.test(create.stderr)) return fail(`create ${sa}`, create);
+  }
+  done.push(`service account ${sa}`);
+
+  // 2. The capture bucket: private, everything deleted after a day.
+  const owned = await run(["storage", "buckets", "list", project, "--format=value(name)"]);
+  if (!owned.ok) return fail(`list the buckets of project ${projectId}`, owned);
+  const names = owned.stdout.split("\n").map((l) =>
+    l
+      .trim()
+      .replace(/^gs:\/\//, "")
+      .replace(/\/$/, ""),
+  );
+  if (!names.includes(bucket)) {
+    const created = await run([
+      "storage",
+      "buckets",
+      "create",
+      bucketUrl,
+      project,
+      `--location=${region}`,
+      "--default-storage-class=STANDARD",
+      "--uniform-bucket-level-access",
+      "--public-access-prevention",
+      "--soft-delete-duration=0",
+    ]);
+    if (!created.ok) {
+      return {
+        ok: false,
+        done,
+        error: /already exists|409/i.test(created.stderr)
+          ? `${bucketUrl} exists but does not belong to project ${projectId}; delete or rename that bucket, this install needs the name`
+          : `create ${bucketUrl}: ${created.stderr.trim()}`,
+      };
+    }
+  }
+  // A private directory (mkdtemp, mode 700): no other local user can swap
+  // the file between write and read.
+  const dir = mkdtempSync(join(tmpdir(), "caelo-capture-"));
+  try {
+    const file = join(dir, "lifecycle.json");
+    writeFileSync(file, JSON.stringify(CAPTURE_BUCKET_LIFECYCLE), { mode: 0o600 });
+    const lifecycle = await run([
+      "storage",
+      "buckets",
+      "update",
+      bucketUrl,
+      project,
+      `--lifecycle-file=${file}`,
+    ]);
+    if (!lifecycle.ok) return fail(`set the lifecycle of ${bucketUrl}`, lifecycle);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+  done.push(`bucket ${bucketUrl} (objects deleted after 1 day)`);
+
+  // 3. Bucket grants: the job creates results under out/; the admin writes
+  //    inputs, reads results and deletes both.
+  const bucketGrants: { member: string; role: string; condition?: string; why: string }[] = [
+    {
+      member,
+      role: "roles/storage.objectCreator",
+      condition: captureResultsCondition(bucket),
+      why: "the job writes its result under out/",
+    },
+    {
+      member: runSaMember,
+      role: "roles/storage.objectUser",
+      why: "the admin writes inputs, reads results and deletes both",
+    },
+  ];
+  for (const g of bucketGrants) {
+    const r = await retry([
+      "storage",
+      "buckets",
+      "add-iam-policy-binding",
+      bucketUrl,
+      `--member=${g.member}`,
+      `--role=${g.role}`,
+      ...(g.condition ? [`--condition=${g.condition}`] : []),
+      project,
+      "--quiet",
+      "--format=none",
+    ]);
+    if (!r.ok) return fail(`grant ${g.role} on ${bucketUrl} (${g.why})`, r);
+    done.push(
+      `${g.member === member ? "capture job" : "admin"}: ${g.role} on ${bucketUrl}${g.condition ? " (out/ only)" : ""}`,
+    );
+  }
+
+  // 4. Logs.
+  const logs = await retry([
+    "projects",
+    "add-iam-policy-binding",
+    projectId,
+    `--member=${member}`,
+    "--role=roles/logging.logWriter",
+    "--condition=None",
+    "--quiet",
+    "--format=none",
+  ]);
+  if (!logs.ok) return fail("grant the capture job roles/logging.logWriter", logs);
+  done.push("capture job: roles/logging.logWriter on the project");
+
+  // 5. The admin signs the job's URLs as itself (IAM signBlob).
+  const signer = await retry([
+    "iam",
+    "service-accounts",
+    "add-iam-policy-binding",
+    runSa,
+    `--member=${runSaMember}`,
+    "--role=roles/iam.serviceAccountTokenCreator",
+    project,
+    "--quiet",
+    "--format=none",
+  ]);
+  if (!signer.ok) return fail("let the admin sign URLs as itself", signer);
+  done.push(`admin: roles/iam.serviceAccountTokenCreator on ${runSa} (itself, signed URLs)`);
+
+  // 6. The job: the admin image, its own SA, no secrets, no VPC.
+  const deploy = await run([
+    "run",
+    "jobs",
+    "deploy",
+    job,
+    `--image=${target.adminImageRef}`,
+    `--region=${region}`,
+    project,
+    `--service-account=${sa}`,
+    "--command=bun",
+    `--args=--bun,${CAPTURE_TASK_SCRIPT}`,
+    `--set-env-vars=CAELO_PROVIDER=${provider},CAELO_CAPTURE_BUCKET=${bucket}`,
+    "--max-retries=0",
+    `--task-timeout=${TASK_TIMEOUT}`,
+    "--cpu=1",
+    "--memory=2Gi",
+    "--quiet",
+  ]);
+  if (!deploy.ok) return fail(`deploy job ${job}`, deploy);
+  done.push(`job ${job} (${target.adminImageRef.split("@")[1]?.slice(0, 19)}...)`);
+
+  // 7. The admin may run it with its order and read its executions.
+  for (const role of ["roles/run.jobsExecutorWithOverrides", "roles/run.viewer"]) {
+    const r = await retry([
+      "run",
+      "jobs",
+      "add-iam-policy-binding",
+      job,
+      `--region=${region}`,
+      project,
+      `--member=${runSaMember}`,
+      `--role=${role}`,
+      "--quiet",
+      "--format=none",
+    ]);
+    if (!r.ok) return fail(`grant the admin ${role} on ${job}`, r);
+    done.push(`admin: ${role} on ${job}`);
+  }
+  return { ok: true, done };
+}

package/src/gcp-names.ts

@@ -69,7 +69,7 @@ export function staticPublisherServiceAccountId(env: string): string {
 export function gcpBucketName(
   projectId: string,
   env: string,
-  bucket: "media" | "static" | "staging" | "audit-results",
+  bucket: "media" | "static" | "staging" | "audit-results" | "capture",
 ): string {
   return `${projectId}-${gcpNamePrefix(env)}-${bucket}`;
 }
@@ -162,6 +162,34 @@ export function auditServiceAccountEmail(projectId: string, env: string): string
   return `${auditServiceAccountId(env)}@${projectId}.iam.gserviceaccount.com`;
 }
 
+/**
+ * #1217 — Cloud Run job that runs every server-side browser render
+ * (screenshots, rendered HTML) of the install, one execution per render, so
+ * no Chromium runs in the admin (capture-job-setup.ts).
+ */
+export function captureJobName(env: string): string {
+  return `${gcpNamePrefix(env)}-capture`;
+}
+
+/** Full resource name of the capture job, as the admin's env carries it. */
+export function captureJobResource(projectId: string, region: string, env: string): string {
+  return `projects/${projectId}/locations/${region}/jobs/${captureJobName(env)}`;
+}
+
+/**
+ * Account id of the capture job's own service account: creates capture
+ * results and writes logs — nothing else; it reads only through the signed
+ * URLs the admin hands it (capture-job-setup.ts).
+ */
+export function captureServiceAccountId(env: string): string {
+  return `${gcpNamePrefix(env)}-capture`;
+}
+
+/** Email of the capture job's service account. */
+export function captureServiceAccountEmail(projectId: string, env: string): string {
+  return `${captureServiceAccountId(env)}@${projectId}.iam.gserviceaccount.com`;
+}
+
 /**
  * Account id of the upgrader job's own service account: may roll the two
  * Cloud Run services, run the migration job and back up Cloud SQL, never

package/src/infra-contract.test.ts

@@ -20,8 +20,8 @@ describe("infrastructure contract steps", () => {
     );
   });
 
-  it("is at 13: public_role revoke (3), URL-map redirects role (4), no gateway cms_admin login (5), ops-bucket list (6), gateway proxy hops (7), quality-audit job (8), converge job (9), remote MCP (10), Google sign-in (11), project-level sign-in client (12), edge security headers (13)", () => {
-    expect(INFRA_CONTRACT_VERSION).toBe(13);
+  it("is at 14: public_role revoke (3), URL-map redirects role (4), no gateway cms_admin login (5), ops-bucket list (6), gateway proxy hops (7), quality-audit job (8), converge job (9), remote MCP (10), Google sign-in (11), project-level sign-in client (12), edge security headers (13), capture job (14)", () => {
+    expect(INFRA_CONTRACT_VERSION).toBe(14);
     expect(INFRA_CONTRACT_STEPS[3]).toContain("#633");
     expect(INFRA_CONTRACT_STEPS[4]).toContain("#587");
     expect(INFRA_CONTRACT_STEPS[5]).toContain("#635");
@@ -33,6 +33,7 @@ describe("infrastructure contract steps", () => {
     expect(INFRA_CONTRACT_STEPS[11]).toContain("#914");
     expect(INFRA_CONTRACT_STEPS[12]).toContain("project's IAP settings");
     expect(INFRA_CONTRACT_STEPS[13]).toContain("#891");
+    expect(INFRA_CONTRACT_STEPS[14]).toContain("#1217");
   });
 
   it("lists the pending steps oldest first", () => {
@@ -43,6 +44,6 @@ describe("infrastructure contract steps", () => {
   });
 
   it("names a version a newer release added by number", () => {
-    expect(infraStepsText(13, 14)).toBe("infrastructure step 14 (see that release's notes)");
+    expect(infraStepsText(14, 15)).toBe("infrastructure step 15 (see that release's notes)");
   });
 });

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 = 13;
+export const INFRA_CONTRACT_VERSION = 14;
 
 // History (why each bump happened — an install below a number needs the
 // converge that introduced it):
@@ -101,6 +101,15 @@ export const INFRA_CONTRACT_VERSION = 13;
 //       a Front Door rule set (static-security-headers.ts). Backend-bucket,
 //       object-metadata and CDN writes the in-cloud upgrader holds no rights
 //       for, so the converge applies them.
+//  14 — #1217: the capture job (`caelo-<env>-capture`, capture-job-setup.ts)
+//       every server-side browser render runs in, its service account, the
+//       capture bucket and their grants (job: create under out/ only; admin:
+//       object user on the bucket, run-with-overrides on the job, and
+//       tokenCreator on its own account to sign the job's URLs), the
+//       upgrader's actAs on the job's account, plus CAELO_CAPTURE_JOB /
+//       CAELO_CAPTURE_BUCKET / CAELO_MEDIA_BUCKET on the admin. The new admin
+//       runs no browser itself on GCP and the app-roll moves the job's image,
+//       so it must exist before an in-cloud upgrader rolls onto it.
 
 /**
  * What each contract version adds, in operator terms — the upgrader's
@@ -121,6 +130,7 @@ export const INFRA_CONTRACT_STEPS: Readonly<Record<number, string>> = {
   11: "Google sign-in: the renamed sign-in client secret, its IAM and mounts, the operator-access job's read access to it, and the admin's URL and organisation domain (#914)",
   12: "Google sign-in at project level: the operator-access job's permission to set the sign-in client in the project's IAP settings (#914)",
   13: "the public site's security headers at the edge: nosniff on every file, uploaded SVGs no longer run as documents on the site's origin, and a one-time CDN purge (#891)",
+  14: "the capture job that takes server-side screenshots outside the admin, its service account, bucket and grants (#1217)",
 };
 
 /**

package/src/release-contract.ts

@@ -53,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",
+  // #1217 — the capture job, its service account, bucket and grants.
+  "packages/provisioning/src/capture-job-setup.ts",
   // #819 — the converge job, its database login and the admin's grant on it.
   "packages/provisioning/src/converge-job-setup.ts",
   // #891 — the edge security headers the stacks attach, and the converge's

package/src/stack-contract.test.ts

@@ -71,6 +71,7 @@ describe("adminEnvContract", () => {
       CAELO_GENERATOR_CLI: "/app/apps/static-generator/src/cli.ts",
       MEDIA_ROOT_DIR: "/app/apps/admin/data/media",
       CAELO_MCP_IAP_SERVICE_ACCOUNT: "caelo-mcp@acme.iam.gserviceaccount.com",
+      CAELO_MEDIA_BUCKET: "acme-caelo-production-media",
       // #806 — where Settings → MCP → Remote writes the OAuth client.
       CAELO_OPERATOR_OAUTH_CLIENT_STORE:
         "projects/acme/secrets/caelo-production-operator-oauth-client",
@@ -80,6 +81,8 @@ describe("adminEnvContract", () => {
       CAELO_CONVERGE_JOB: "projects/acme/locations/europe-west1/jobs/caelo-production-converge",
       CAELO_AUDIT_JOB: "projects/acme/locations/europe-west1/jobs/caelo-production-audit",
       CAELO_AUDIT_RESULTS_BUCKET: "acme-caelo-production-audit-results",
+      CAELO_CAPTURE_BUCKET: "acme-caelo-production-capture",
+      CAELO_CAPTURE_JOB: "projects/acme/locations/europe-west1/jobs/caelo-production-capture",
       CAELO_STATIC_BUCKET: "acme-caelo-production-static",
       CAELO_STAGING_BUCKET: "acme-caelo-production-staging",
       ...ADMIN_SECRETS,
@@ -107,6 +110,7 @@ describe("adminEnvContract", () => {
       CAELO_GENERATOR_CLI: "/app/apps/static-generator/src/cli.ts",
       MEDIA_ROOT_DIR: "/app/apps/admin/data/media",
       CAELO_MCP_IAP_SERVICE_ACCOUNT: "caelo-mcp@acme.iam.gserviceaccount.com",
+      CAELO_MEDIA_BUCKET: "acme-caelo-production-media",
       // #806 — where Settings → MCP → Remote writes the OAuth client.
       CAELO_OPERATOR_OAUTH_CLIENT_STORE:
         "projects/acme/secrets/caelo-production-operator-oauth-client",
@@ -116,6 +120,8 @@ describe("adminEnvContract", () => {
       CAELO_CONVERGE_JOB: "projects/acme/locations/europe-west1/jobs/caelo-production-converge",
       CAELO_AUDIT_JOB: "projects/acme/locations/europe-west1/jobs/caelo-production-audit",
       CAELO_AUDIT_RESULTS_BUCKET: "acme-caelo-production-audit-results",
+      CAELO_CAPTURE_BUCKET: "acme-caelo-production-capture",
+      CAELO_CAPTURE_JOB: "projects/acme/locations/europe-west1/jobs/caelo-production-capture",
       CAELO_FIREBASE_SITE: "caelo-production-site-abc123",
       CAELO_GATEWAY_SERVICE: "caelo-production-gateway-1a2b3c4",
       CAELO_GATEWAY_REGION: "europe-west1",

package/src/stack-contract.ts

@@ -38,6 +38,7 @@ import { z } from "zod";
 import type { SupportedProvider } from "./adapter.js";
 import {
   auditJobResource,
+  captureJobResource,
   convergeJobResource,
   gatewayServiceAccountEmail,
   gcpBucketName,
@@ -188,6 +189,16 @@ export const CONVERGE_JOB_ENV_VAR = "CAELO_CONVERGE_JOB";
 export const AUDIT_JOB_ENV_VAR = "CAELO_AUDIT_JOB";
 export const AUDIT_RESULTS_BUCKET_ENV_VAR = "CAELO_AUDIT_RESULTS_BUCKET";
 
+/**
+ * #1217 — the admin env vars naming the capture job, the bucket it hands
+ * inputs and results through, and the media bucket whose objects the admin
+ * signs read URLs for (admin-core capture/capture-backend.ts). `upgrade`
+ * leaves the first two untouched when it could not set the job up.
+ */
+export const CAPTURE_JOB_ENV_VAR = "CAELO_CAPTURE_JOB";
+export const CAPTURE_BUCKET_ENV_VAR = "CAELO_CAPTURE_BUCKET";
+export const MEDIA_BUCKET_ENV_VAR = "CAELO_MEDIA_BUCKET";
+
 /** Where the admin image ships the static-generator CLI. */
 const GENERATOR_CLI = "/app/apps/static-generator/src/cli.ts";
 
@@ -916,6 +927,12 @@ export function adminEnvContract<V>(inputs: AdminEnvInputs<V>): CloudRunEnvVar<V
     // where the tasks write their results (audit-job-setup.ts).
     { name: AUDIT_JOB_ENV_VAR, value: auditJobResource(projectId, inputs.region, env) },
     { name: AUDIT_RESULTS_BUCKET_ENV_VAR, value: gcpBucketName(projectId, env, "audit-results") },
+    // #1217 — the job every server-side browser render runs in, the bucket
+    // it exchanges inputs and results through, and the media bucket the
+    // admin signs a preview's media URLs for (capture-job-setup.ts).
+    { name: CAPTURE_JOB_ENV_VAR, value: captureJobResource(projectId, inputs.region, env) },
+    { name: CAPTURE_BUCKET_ENV_VAR, value: gcpBucketName(projectId, env, "capture") },
+    { name: MEDIA_BUCKET_ENV_VAR, value: gcpBucketName(projectId, env, "media") },
     // #914 — where Settings → Google sign-in writes the install's Google
     // sign-in client (add-version only, see the run SA's secretVersionAdder
     // invariant).

package/src/stack-converge.test.ts

@@ -322,7 +322,7 @@ describe("planContractEnv", () => {
     // #650 — the same roll converges the protected staging domain's host
     // and gate key onto an install that predates it.
     expect(plan.services.admin.flags).toEqual([
-      "--update-env-vars=CAELO_SITE_URL=https://acme.com,MEDIA_ROOT_DIR=/app/apps/admin/data/media,CAELO_MCP_IAP_SERVICE_ACCOUNT=caelo-mcp@acme.iam.gserviceaccount.com,CAELO_OPERATOR_ACCESS_JOB=projects/acme/locations/europe-west1/jobs/caelo-production-operator-access-sync,CAELO_UPGRADER_JOB=projects/acme/locations/europe-west1/jobs/caelo-production-upgrader,CAELO_CONVERGE_JOB=projects/acme/locations/europe-west1/jobs/caelo-production-converge,CAELO_AUDIT_JOB=projects/acme/locations/europe-west1/jobs/caelo-production-audit,CAELO_AUDIT_RESULTS_BUCKET=acme-caelo-production-audit-results,CAELO_OPERATOR_OAUTH_CLIENT_STORE=projects/acme/secrets/caelo-production-operator-oauth-client,CAELO_STAGING_HOST=staging.acme.com",
+      "--update-env-vars=CAELO_SITE_URL=https://acme.com,MEDIA_ROOT_DIR=/app/apps/admin/data/media,CAELO_MCP_IAP_SERVICE_ACCOUNT=caelo-mcp@acme.iam.gserviceaccount.com,CAELO_OPERATOR_ACCESS_JOB=projects/acme/locations/europe-west1/jobs/caelo-production-operator-access-sync,CAELO_UPGRADER_JOB=projects/acme/locations/europe-west1/jobs/caelo-production-upgrader,CAELO_CONVERGE_JOB=projects/acme/locations/europe-west1/jobs/caelo-production-converge,CAELO_AUDIT_JOB=projects/acme/locations/europe-west1/jobs/caelo-production-audit,CAELO_AUDIT_RESULTS_BUCKET=acme-caelo-production-audit-results,CAELO_CAPTURE_JOB=projects/acme/locations/europe-west1/jobs/caelo-production-capture,CAELO_CAPTURE_BUCKET=acme-caelo-production-capture,CAELO_MEDIA_BUCKET=acme-caelo-production-media,CAELO_OPERATOR_OAUTH_CLIENT_STORE=projects/acme/secrets/caelo-production-operator-oauth-client,CAELO_STAGING_HOST=staging.acme.com",
       "--update-secrets=CAELO_STAGING_GATE_SECRET=caelo-production-staging-gate-secret:latest",
     ]);
     expect(plan.services.gateway.flags).toEqual([

package/src/upgrade/{audit-job-roll.ts → admin-image-jobs.ts}

@@ -1,28 +1,57 @@
 // SPDX-License-Identifier: MPL-2.0
 
 /**
- * #875 — the quality-audit job runs the admin image (admin-core
- * quality/audit-task.ts) and refuses a batch from an admin on another
- * version. So every app-roll moves the job onto the admin's new image right
- * after the services rolled, and a rollback moves it back.
+ * The Cloud Run jobs that run the admin image: the quality-audit job (#875,
+ * admin-core quality/audit-task.ts) and the capture job (#1217, admin-core
+ * capture/capture-task.ts). Each refuses an order from an admin on another
+ * version, so every app-roll moves them onto the admin's new image right
+ * after the services rolled, and a rollback moves them back.
  *
- * `run jobs update --image` changes nothing else of the job (identity, env,
+ * `run jobs update --image` changes nothing else of a job (identity, env,
  * parallelism), so this stays inside the app-roll's rights: the upgrader's
- * `roles/run.developer` plus actAs on the job's service account
- * (upgrader-setup.ts).
+ * Cloud Run role plus actAs on each job's service account (upgrader-setup.ts).
  */
 
 import type { GcloudRunner } from "../gcloud-retry.js";
-import { auditJobName } from "../gcp-names.js";
+import { auditJobName, captureJobName } from "../gcp-names.js";
+
+/** One job that follows the admin's image. */
+export interface AdminImageJob {
+  /** The job's name (`caelo-<env>-audit`). */
+  readonly name: string;
+  /** How the upgrade names it (`quality-audit job`). */
+  readonly label: string;
+  /** What fails while it lags behind the admin. */
+  readonly lagging: string;
+}
+
+/** The jobs that follow the admin's image, for one environment. */
+export function adminImageJobs(env: string): readonly AdminImageJob[] {
+  return [
+    { name: auditJobName(env), label: "quality-audit job", lagging: "Stage audits fail" },
+    {
+      name: captureJobName(env),
+      label: "capture job",
+      lagging: "server-side screenshots fail",
+    },
+  ];
+}
+
+interface Install {
+  readonly projectId: string;
+  readonly region: string;
+  readonly env: string;
+}
 
 /**
- * The job's image now; `image: null` only when the install has no audit job
+ * The job's image now; `image: null` only when the install has no such job
  * yet. Any other gcloud failure (permissions, API, network) is an error, not
  * "no job", so the app-roll reports it instead of a misleading hint.
  */
-export async function describeAuditJobImage(
+export async function describeJobImage(
   run: GcloudRunner,
-  install: { readonly projectId: string; readonly region: string; readonly env: string },
+  install: Install,
+  job: string,
 ): Promise<
   | { readonly ok: true; readonly image: string | null }
   | { readonly ok: false; readonly error: string }
@@ -31,7 +60,7 @@ export async function describeAuditJobImage(
     "run",
     "jobs",
     "describe",
-    auditJobName(install.env),
+    job,
     `--region=${install.region}`,
     `--project=${install.projectId}`,
     "--format=value(spec.template.spec.template.spec.containers[0].image)",
@@ -50,17 +79,18 @@ export async function describeAuditJobImage(
   return { ok: true, image };
 }
 
-/** Point the audit job at `imageRef`. */
-export async function setAuditJobImage(
+/** Point a job at `imageRef`. */
+export async function setJobImage(
   run: GcloudRunner,
-  install: { readonly projectId: string; readonly region: string; readonly env: string },
+  install: Install,
+  job: string,
   imageRef: string,
 ): Promise<{ readonly ok: boolean; readonly error?: string }> {
   const r = await run([
     "run",
     "jobs",
     "update",
-    auditJobName(install.env),
+    job,
     `--image=${imageRef}`,
     `--region=${install.region}`,
     `--project=${install.projectId}`,