@caelo-cms/provisioning 0.11.10 → 0.11.11

package/src/upgrade/converge.ts

@@ -5,7 +5,8 @@
  * service accounts, secrets or other cloud resources so the install matches
  * what the release's stacks declare — the gateway's run SA and the
  * CLI-generated runtime secrets, the stack's IAM/CDN/firewall invariants,
- * MCP access through IAP, public_role's Cloud SQL role memberships (#633),
+ * MCP access through IAP, the staging database and its gateway login
+ * (#1329), the gateway logins' Cloud SQL role memberships (#633),
  * the gateway's and public_role's database logins, the operator-access sync
  * job, the quality-audit job (#875), the remote-MCP load-balancer rules and
  * identity env (#806), and dropping bindings nothing reads any more.
@@ -39,7 +40,7 @@ import {
 import { ensureConvergeJob } from "../converge-job-setup.js";
 import { findSqlInstance, planPublicRoleSwitch } from "../gateway-credentials.js";
 import type { GcloudRunner, Sleep } from "../gcloud-retry.js";
-import { upgraderServiceAccountEmail } from "../gcp-names.js";
+import { schedulerServiceAccountEmail, upgraderServiceAccountEmail } from "../gcp-names.js";
 import type { InstallMetadata } from "../install-state.js";
 import { ensureMcpIapAccess, type IapResource } from "../mcp-iap.js";
 import { ensureOperatorAccessSync, resolveOperatorAccessTarget } from "../operator-access.js";
@@ -52,6 +53,7 @@ import {
   plainGeneratedSecretSeed,
   readSecretReplication,
 } from "../runtime-secrets.js";
+import { ensureSchedulerTick } from "../scheduler-setup.js";
 import { selfCommand } from "../self-command.js";
 import {
   AUDIT_JOB_ENV_VAR,
@@ -64,7 +66,9 @@ import {
   INTERIM_FORWARD_ORIGIN_ENV,
   MCP_ENV_VAR,
   OPERATOR_ACCESS_JOB_ENV_VAR,
+  parseSchedulerIntervalMinutes,
   remoteMcpIdentityEnv,
+  SCHEDULER_SERVICE_ACCOUNT_ENV_VAR,
   UPGRADER_JOB_ENV_VAR,
 } from "../stack-contract.js";
 import {
@@ -73,6 +77,7 @@ import {
   liveEnvHasInlinePassword,
   removeRetiredIamBindings,
 } from "../stack-converge.js";
+import { ensureStagingDatabase } from "../staging-database.js";
 import { ensureUpgraderJob, resolveUpgraderTarget } from "../upgrader-setup.js";
 import { ensureUrlMapRedirectsAccess } from "../url-map-redirects-access.js";
 import type { AppRollHooks, AppRollPlan, RollPlan, RollSlug } from "./app-roll.js";
@@ -110,6 +115,11 @@ export interface ConvergeDeps {
    * then fails and the converge stays incomplete.
    */
   readonly opsImageRef?: string | null;
+  /**
+   * #1140 — the install's `schedulerIntervalMinutes` knob (install.json);
+   * absent: the default. The scheduler step refuses an out-of-range value.
+   */
+  readonly schedulerIntervalMinutes?: number;
 }
 
 export interface ConvergeSession {
@@ -234,22 +244,48 @@ export function startConverge(
     return true;
   }
 
+  async function stagingDatabase(): Promise<boolean> {
+    // #1329 — staging's own database and its gateway login, on an install
+    // from before them. Before migrations: the cms_public_staging run and
+    // migration 0530 need both, and the membership revoke below needs the
+    // user. A failure aborts — the new admin refuses to start without the
+    // staging database.
+    const s = r.step("Ensuring the staging database (cms_public_staging) and its gateway login...");
+    const outcomes = await ensureStagingDatabase(
+      { projectId: install.projectId, env: install.env, credentials: install.credentials },
+      { ...runDeps, ...(deps.http ? { http: deps.http } : {}) },
+    );
+    const failed = outcomes.filter((o) => o.status === "failed");
+    if (failed.length > 0) {
+      s.failed("The staging database could not be set up. Aborting upgrade.");
+      for (const o of failed) r.error(`  FAILED: ${o.id}\n    ${o.error ?? ""}`);
+      r.warn("No traffic was shifted and no migrations ran. Fix the above and re-run.");
+      return false;
+    }
+    s.done("Staging database and its gateway login ready");
+    for (const o of outcomes.filter((o) => o.status === "applied")) {
+      r.info(`  ${o.id}: ${o.detail ?? "created"}`);
+    }
+    return true;
+  }
+
   async function publicRoleIsolation(): Promise<boolean> {
-    // #633 — the Admin API made public_role a member of cloudsqlsuperuser.
-    // Revoked here, before migrations, because the migration job's role
-    // audit is what verifies it and fails the upgrade while it remains.
-    const s = r.step("Removing public_role from the Cloud SQL superuser group...");
+    // #633 — the Admin API made public_role (and, #1329, public_staging_role)
+    // a member of cloudsqlsuperuser. Revoked here, before migrations,
+    // because the migration job's role audit is what verifies it and fails
+    // the upgrade while it remains.
+    const s = r.step("Removing the gateway logins from the Cloud SQL superuser group...");
     const outcome = await revokePublicRoleMemberships(
       { projectId: install.projectId, env: install.env, credentials: install.credentials },
       runDeps,
     );
     if (outcome.status === "failed") {
-      s.failed("public_role's role memberships could not be revoked. Aborting upgrade.");
+      s.failed("The gateway logins' role memberships could not be revoked. Aborting upgrade.");
       r.error(`  ${outcome.error ?? ""}`);
       r.warn("No traffic was shifted and no migrations ran. Fix the above and re-run.");
       return false;
     }
-    s.done(`public_role holds no database roles (${outcome.detail ?? "revoked"})`);
+    s.done(`The gateway logins hold no database roles (${outcome.detail ?? "revoked"})`);
     return true;
   }
 
@@ -427,6 +463,9 @@ export function startConverge(
     return [{ name: INTERIM_FORWARD_ORIGIN_ENV, value: new URL(url).origin }];
   }
 
+  /** The admin's origin behind IAP, once {@link remoteMcpIdentity} read it. */
+  let resolvedAdminUrl: string | null = null;
+
   async function remoteMcpIdentity(): Promise<Record<RollSlug, CloudRunEnvVar[]> | null> {
     // #806 — CAELO_ADMIN_URL / CAELO_MCP_PUBLIC_URL / CAELO_IAP_AUDIENCE
     // name identities the env contract cannot (stack-contract.ts
@@ -449,6 +488,7 @@ export function startConverge(
       runDeps,
     );
     if (resolved.ok) {
+      resolvedAdminUrl = resolved.identity.adminUrl;
       s.done(
         `Google sign-in and remote MCP can be set up under Settings → Google sign-in (${resolved.identity.mcpPublicUrl})`,
       );
@@ -672,6 +712,77 @@ export function startConverge(
     leaveUntouched.push(CONVERGE_JOB_ENV_VAR);
   }
 
+  let schedulerReady = false;
+  /** The scheduler's SA exists from an earlier run though this one failed. */
+  let schedulerAccountExists = false;
+
+  async function setUpSchedulerTick(): Promise<
+    | { ok: true; done: string[]; intervalMinutes: number }
+    | { ok: false; done: string[]; error: string }
+  > {
+    let intervalMinutes: number;
+    try {
+      intervalMinutes = parseSchedulerIntervalMinutes(
+        deps.schedulerIntervalMinutes,
+        "install.json schedulerIntervalMinutes",
+      );
+    } catch (e) {
+      return { ok: false, done: [], error: (e as Error).message };
+    }
+    const resource = await adminIapResource();
+    if (!resource) return { ok: false, done: [], error: "the admin's IAP resource was not found" };
+    if (!resolvedAdminUrl)
+      return { ok: false, done: [], error: "the admin's URL could not be read" };
+    const st = await ensureSchedulerTick(
+      {
+        projectId: install.projectId,
+        region: install.region,
+        env: install.env,
+        adminUrl: resolvedAdminUrl,
+        resource,
+        intervalMinutes,
+      },
+      runDeps,
+    );
+    return st.ok ? { ok: true, done: st.done, intervalMinutes } : st;
+  }
+
+  async function schedulerTick(): Promise<void> {
+    // #1140 — the one Cloud Scheduler job that calls the admin's tick
+    // (scheduler-setup.ts). After migrations and before the operator-access
+    // step, which must keep the scheduler's account on IAP. The schedule
+    // starts right away: until the roll below finishes, a tick reaches the
+    // previous admin, which has no such endpoint (404) — that execution
+    // fails and nothing runs; the first tick after the roll does the work.
+    // A failure costs the periodic work (plugin workers, GC, release check),
+    // not the site, so it warns and the admin keeps its current env.
+    const s = r.step("Ensuring the scheduler tick (periodic work and plugin workers)...");
+    const st = await setUpSchedulerTick();
+    for (const step of st.done) r.info(`  ${step}`);
+    if (st.ok) {
+      schedulerReady = true;
+      s.done(`Scheduler tick ready (every ${st.intervalMinutes} min)`);
+      return;
+    }
+    s.warned(`Scheduler tick not set up: ${st.error}`);
+    // An account set up by an earlier run keeps its IAP access, or the next
+    // sync would cut off a tick that still works.
+    const exists = await run([
+      "iam",
+      "service-accounts",
+      "describe",
+      schedulerServiceAccountEmail(install.projectId, install.env),
+      `--project=${install.projectId}`,
+      "--format=value(email)",
+    ]);
+    schedulerAccountExists = exists.ok;
+    r.warn(
+      "The upgrade continues; plugin workers, update checks and clean-up run late or not at all until this succeeds. Re-run upgrade once the cause is fixed.",
+    );
+    incomplete = true;
+    leaveUntouched.push(SCHEDULER_SERVICE_ACCOUNT_ENV_VAR);
+  }
+
   async function operatorAccess(): Promise<void> {
     // The job that keeps IAP in step with the user list (operator-access.ts).
     // After migrations: its database user gets the role migration 0239
@@ -699,6 +810,13 @@ export function startConverge(
                   ],
                 }
               : {}),
+            ...(schedulerReady || schedulerAccountExists
+              ? {
+                  iapServiceAccounts: [
+                    schedulerServiceAccountEmail(install.projectId, install.env),
+                  ],
+                }
+              : {}),
           },
           runDeps,
         )
@@ -721,6 +839,7 @@ export function startConverge(
       if (deps.provisionerIdentity && !(await deps.provisionerIdentity())) return false;
       if (!(await runtimeIdentities())) return false;
       if (!(await stackInvariants())) return false;
+      if (!(await stagingDatabase())) return false;
       if (!(await publicRoleIsolation())) return false;
       if (!(await databaseTls())) return false;
       await mcpAccess();
@@ -734,10 +853,12 @@ export function startConverge(
     hooks: {
       async afterMigrations() {
         if (!(await databaseLogins())) return { ok: false };
+        // Read-only, first: the scheduler tick needs the admin's URL.
+        const identity = await remoteMcpIdentity();
         await upgraderJob();
         await convergeJob();
+        await schedulerTick();
         await operatorAccess();
-        const identity = await remoteMcpIdentity();
         let forward: CloudRunEnvVar[];
         try {
           forward = await interimForwardEnv();

package/src/upgrade/upgrade.test.ts

@@ -423,6 +423,66 @@ describe("upgradeGcpInstall — converge, then app-roll", () => {
     ).toBe(false);
   });
 
+  it("#1140 — sets up the scheduler tick before operator access keeps its account on IAP, and tells the admin whom to trust", async () => {
+    const events: string[] = [];
+    const { deps, lines } = upgradeDeps(events);
+    expect(await upgradeGcpInstall({ ...TARGET, schedulerIntervalMinutes: 2 }, deps)).toBe(true);
+    const workflow = indexOf(events, /^gcloud workflows deploy caelo-production-scheduler-tick /);
+    const schedule = indexOf(
+      events,
+      /^gcloud scheduler jobs (create|update) http caelo-production-scheduler-tick /,
+    );
+    const opAccess = indexOf(
+      events,
+      /^gcloud run jobs deploy caelo-production-operator-access-sync /,
+    );
+    const adminRoll = indexOf(events, new RegExp(`^gcloud run services update ${ADMIN} `));
+    expect(workflow < schedule && schedule < opAccess && opAccess < adminRoll).toBe(true);
+    expect(events[schedule]).toContain("--schedule=*/2 * * * *");
+    expect(events[schedule]).toContain(
+      "--oauth-service-account-email=caelo-production-scheduler@acme.iam.gserviceaccount.com",
+    );
+    expect(events[opAccess]).toContain(
+      "CAELO_OPERATOR_ACCESS_IAP_SERVICE_ACCOUNTS=caelo-production-scheduler@acme.iam.gserviceaccount.com",
+    );
+    expect(events[adminRoll]).toContain(
+      "CAELO_SCHEDULER_SERVICE_ACCOUNT=caelo-production-scheduler@acme.iam.gserviceaccount.com",
+    );
+    expect(lines).toContain("done: Scheduler tick ready (every 2 min)");
+  });
+
+  it("#1140 — a failed scheduler setup leaves the converge incomplete and the admin's trust env untouched", async () => {
+    const events: string[] = [];
+    const { deps, recorded, lines } = upgradeDeps(events, {
+      overrides: [
+        [/^workflows deploy caelo-production-scheduler-tick/, fail("PERMISSION_DENIED")],
+        [/^iam service-accounts describe caelo-production-scheduler@/, fail("NOT_FOUND")],
+      ],
+    });
+    expect(await upgradeGcpInstall(TARGET, deps)).toBe(true);
+    expect(recorded.contract).toEqual([]);
+    expect(lines.some((l) => l.includes("Scheduler tick not set up"))).toBe(true);
+    expect(
+      events.some((e) =>
+        /services update caelo-production-admin.*CAELO_SCHEDULER_SERVICE_ACCOUNT=/.test(e),
+      ),
+    ).toBe(false);
+    expect(
+      events.some((e) =>
+        /^gcloud scheduler jobs (create|update) http caelo-production-scheduler-tick/.test(e),
+      ),
+    ).toBe(false);
+  });
+
+  it("#1140 — refuses an out-of-range interval in install.json without touching the scheduler", async () => {
+    const events: string[] = [];
+    const { deps, recorded, lines } = upgradeDeps(events);
+    expect(await upgradeGcpInstall({ ...TARGET, schedulerIntervalMinutes: 60 }, deps)).toBe(true);
+    expect(recorded.contract).toEqual([]);
+    expect(lines.some((l) => l.includes("between 1 and 15"))).toBe(true);
+    expect(events.some((e) => /^gcloud workflows deploy/.test(e))).toBe(false);
+  });
+
   it("an unreadable audit job is reported as an error, not as a missing job, and is not moved", async () => {
     const events: string[] = [];
     const { deps, lines } = upgradeDeps(events, {
@@ -748,10 +808,33 @@ describe("upgradeGcpInstall — converge, then app-roll", () => {
     expect(indexOf(events, /^gcloud sql backups create/)).toBeLessThan(revoke);
     expect(revoke).toBeLessThan(indexOf(events, /^migrate /));
     expect(lines).toContain(
-      "done: public_role holds no database roles (no database roles left on caelo-production-pg-abc)",
+      "done: The gateway logins hold no database roles (public_role and public_staging_role hold no database roles on caelo-production-pg-abc)",
     );
   });
 
+  it("creates the staging database and its login before the revoke and the migrations (#1329)", async () => {
+    const events: string[] = [];
+    const { deps, lines } = upgradeDeps(events);
+    expect(await upgradeGcpInstall(TARGET, deps)).toBe(true);
+    const created = indexOf(events, /^gcloud sql databases (list|create)/);
+    const revoke = indexOf(events, /^gcloud sql users assign-roles public_staging_role/);
+    expect(created).toBeGreaterThan(-1);
+    expect(created).toBeLessThan(revoke);
+    expect(revoke).toBeLessThan(indexOf(events, /^migrate /));
+    expect(lines).toContain("done: Staging database and its gateway login ready");
+  });
+
+  it("a staging database that cannot be created stops the upgrade before migrations and any roll (#1329)", async () => {
+    const events: string[] = [];
+    const { deps, calls, lines } = upgradeDeps(events, {
+      overrides: [[/^sql databases list/, fail("PERMISSION_DENIED: no")]],
+    });
+    expect(await upgradeGcpInstall(TARGET, deps)).toBe(false);
+    expect(events.some((e) => e.startsWith("migrate"))).toBe(false);
+    expect(calls.filter((c) => APP_ROLL_WRITE.test(c))).toEqual([]);
+    expect(lines).toContain("failed: The staging database could not be set up. Aborting upgrade.");
+  });
+
   it("a refused public_role revoke stops the upgrade before migrations and any roll (#633)", async () => {
     const events: string[] = [];
     const { deps, calls, lines } = upgradeDeps(events, {
@@ -761,7 +844,7 @@ describe("upgradeGcpInstall — converge, then app-roll", () => {
     expect(events.some((e) => e.startsWith("migrate"))).toBe(false);
     expect(calls.filter((c) => APP_ROLL_WRITE.test(c))).toEqual([]);
     expect(lines).toContain(
-      "failed: public_role's role memberships could not be revoked. Aborting upgrade.",
+      "failed: The gateway logins' role memberships could not be revoked. Aborting upgrade.",
     );
   });
 

package/src/upgrade/upgrade.ts

@@ -57,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). */
@@ -276,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 } : {}),

package/src/upgrader-gcp.ts

@@ -73,11 +73,12 @@ export async function upgraderDatabaseHost(
 
 /**
  * #1338 — the database host for the converge job (#819), after making sure
- * a verify-full connection to it can work. The job opens its database
- * queue before it converges anything, with this release's code, which
- * connects with verify-full only; on an install whose services still dial
- * the instance's IP it first runs the converge's database TLS step
+ * 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.

package/src/wizard.ts

@@ -72,6 +72,13 @@ export interface WizardOptions {
    * install a different value is refused.
    */
   region?: string;
+  /**
+   * #1140 — `--scheduler-interval-minutes` (1–15, already validated): how
+   * often the scheduler tick calls the admin. Recorded in install.json, so
+   * every later `upgrade` keeps it; omitted keeps what is recorded (or the
+   * default, 5).
+   */
+  schedulerIntervalMinutes?: number;
   /**
    * #696 — where `pulumi up` and the rest of a GCP install run
    * (run-mode.ts): `job` (default in Cloud Shell) or `local`.
@@ -192,6 +199,18 @@ export async function runWizard(opts: WizardOptions = {}): Promise<void> {
     }
   }
 
+  // #1140 — the scheduler knob, on a new install and on a resumed one alike
+  // (every later `upgrade` reads it from install.json).
+  if (opts.schedulerIntervalMinutes !== undefined) {
+    const recorded = readMetadata(installId);
+    if (recorded) {
+      writeMetadata(installId, {
+        ...recorded,
+        schedulerIntervalMinutes: opts.schedulerIntervalMinutes,
+      });
+    }
+  }
+
   // 3.5. #656 — a re-run of an install an earlier CLI set up: drop the
   // secrets that CLI checkpointed (database passwords, the setup link)
   // before any step writes progress.json again, and say what to rotate.

package/src/wizards/gcp-cost.test.ts

@@ -7,7 +7,14 @@
  */
 
 import { describe, expect, it } from "bun:test";
-import { type CostEstimateInputs, estimateGcpCost } from "./gcp-cost.js";
+import { SERVICE_CPU_IDLE } from "../stack-contract.js";
+import {
+  adminKeptWarmByTicks,
+  alwaysOnAdminInstanceUsd,
+  type CostEstimateInputs,
+  estimateGcpCost,
+  schedulerTickMonthlyUsd,
+} from "./gcp-cost.js";
 
 const inputs: CostEstimateInputs = {
   cloudSqlTier: "db-f1-micro",
@@ -48,3 +55,49 @@ describe("cost table: MCP-Auth-Proxy (#1328)", () => {
     expect(names("gcp")).toContain("Cloud Run gateway");
   });
 });
+
+describe("cost table: scheduler tick (#1140)", () => {
+  it("lists the tick at the default 5 minutes: well under a dollar", () => {
+    const line = estimateGcpCost(inputs).lines.find((l) => l.name.startsWith("Scheduler tick"));
+    expect(line?.name).toBe("Scheduler tick (Cloud Scheduler + Workflows, every 5 min)");
+    // 8,640 ticks: 25,920 internal steps (20,920 billed) + 8,640 external
+    // (6,640 billed) + the scheduler job.
+    expect(line?.monthlyUsd).toBe(0.48);
+  });
+
+  it("follows the knob: one minute stays a few dollars, fifteen little more than the job", () => {
+    expect(schedulerTickMonthlyUsd(1)).toBe(2.38);
+    expect(schedulerTickMonthlyUsd(15)).toBe(0.16);
+    const fast = estimateGcpCost({ ...inputs, schedulerIntervalMinutes: 1 }).lines.find((l) =>
+      l.name.startsWith("Scheduler tick"),
+    );
+    expect(fast?.name).toContain("every 1 min");
+  });
+
+  it("prices the admin kept up around the clock while its CPU is always allocated (#1361)", () => {
+    // The tick (at most every 15 minutes) beats Cloud Run's 15-minute idle
+    // shutdown, so a scale-to-zero admin never stops.
+    expect(SERVICE_CPU_IDLE.admin).toBe(false);
+    expect(adminKeptWarmByTicks(0)).toBe(true);
+    // 2,592,000 s x (1 vCPU x $0.000018 + 2 GiB x $0.000002).
+    expect(alwaysOnAdminInstanceUsd(2)).toBe(57);
+    const admin = estimateGcpCost(inputs).lines.find((l) => l.name.startsWith("Cloud Run admin"));
+    expect(admin?.monthlyUsd).toBe(57);
+    expect(admin?.notes).toContain("around the clock");
+    expect(admin?.notes).toContain("#1361");
+  });
+
+  it("adds nothing on the admin with a min instance, which is up anyway", () => {
+    expect(adminKeptWarmByTicks(1)).toBe(false);
+    const admin = estimateGcpCost({ ...inputs, adminMinInstances: 1 }).lines.find((l) =>
+      l.name.startsWith("Cloud Run admin"),
+    );
+    expect(admin?.notes).toContain("the scheduler tick adds nothing");
+  });
+
+  it("refuses an interval outside 1-15 minutes", () => {
+    expect(() => estimateGcpCost({ ...inputs, schedulerIntervalMinutes: 20 })).toThrow(
+      "between 1 and 15",
+    );
+  });
+});

package/src/wizards/gcp-cost.ts

@@ -11,7 +11,12 @@
  * + AI calls + storage growth on top.
  */
 
-import { ADMIN_MEMORY_DEFAULT, memoryQuantityMiB } from "../stack-contract.js";
+import {
+  ADMIN_MEMORY_DEFAULT,
+  memoryQuantityMiB,
+  parseSchedulerIntervalMinutes,
+  SERVICE_CPU_IDLE,
+} from "../stack-contract.js";
 
 export interface CostLine {
   name: string;
@@ -41,6 +46,82 @@ export interface CostEstimateInputs {
   provider?: "gcp" | "gcp-firebase";
   /** #607 — the install region; shown in the table (prices are {@link PRICED_REGION} rates). */
   region: string;
+  /** #1140 — the `schedulerIntervalMinutes` knob (1–15); undefined: the default. */
+  schedulerIntervalMinutes?: number;
+}
+
+/**
+ * #1140 — Workflows steps one scheduler tick costs (scheduler-setup.ts
+ * schedulerWorkflowSource): the claims `assign`, the signJwt call (a Google
+ * API, billed as an internal step), the `return` — and the POST to the
+ * admin, the one external HTTP step.
+ */
+export const SCHEDULER_TICK_STEPS = { internal: 3, external: 1 } as const;
+
+/**
+ * Workflows list prices (USD, cloud.google.com/workflows/pricing, as of
+ * 2026-11) and the monthly free tier per billing account.
+ */
+const WORKFLOWS_PRICE = {
+  internalPer1000: 0.01,
+  externalPer1000: 0.025,
+  freeInternal: 5_000,
+  freeExternal: 2_000,
+} as const;
+
+/** Cloud Scheduler: $0.10 per job a month; the first 3 per billing account are free. */
+const SCHEDULER_JOB_USD = 0.1;
+
+/**
+ * #1140 — what the scheduler tick costs a month at `minutes` between ticks:
+ * the Cloud Scheduler job (priced as paid — the 3 free jobs are shared
+ * with every other project on the billing account) plus the Workflows
+ * steps past the free tier. What the tick costs on the admin's side is
+ * priced on the admin's own line ({@link adminKeptWarmByTicks}).
+ */
+export function schedulerTickMonthlyUsd(minutes: number): number {
+  const ticks = Math.ceil((30 * 24 * 60) / parseSchedulerIntervalMinutes(minutes));
+  const internal = Math.max(
+    0,
+    ticks * SCHEDULER_TICK_STEPS.internal - WORKFLOWS_PRICE.freeInternal,
+  );
+  const external = Math.max(
+    0,
+    ticks * SCHEDULER_TICK_STEPS.external - WORKFLOWS_PRICE.freeExternal,
+  );
+  const usd =
+    SCHEDULER_JOB_USD +
+    (internal / 1000) * WORKFLOWS_PRICE.internalPer1000 +
+    (external / 1000) * WORKFLOWS_PRICE.externalPer1000;
+  return Math.round(usd * 100) / 100;
+}
+
+/**
+ * Cloud Run instance-based billing (CPU always allocated) list rates, USD,
+ * tier-1 region, cloud.google.com/run/pricing as of 2026-11. The free tier
+ * is left out: it is shared by every service on the billing account.
+ */
+const CLOUD_RUN_INSTANCE_PRICE = { vcpuSecond: 0.000018, gibSecond: 0.000002 } as const;
+
+/** Seconds in the 30-day month the table prices. */
+const MONTH_SECONDS = 30 * 24 * 60 * 60;
+
+/**
+ * #1140 — whether the scheduler tick keeps a scale-to-zero admin instance
+ * up around the clock. Cloud Run keeps an idle instance for up to 15
+ * minutes after its last request, and the tick comes at most every 15
+ * minutes, so with CPU always allocated (`SERVICE_CPU_IDLE.admin` false
+ * until #1361) the instance never stops and is billed every second. With
+ * request-billed CPU an idle instance costs nothing between ticks.
+ */
+export function adminKeptWarmByTicks(adminMinInstances: number): boolean {
+  return adminMinInstances === 0 && !SERVICE_CPU_IDLE.admin;
+}
+
+/** One always-on admin instance (1 vCPU, `gib` memory) a month at instance-based list rates. */
+export function alwaysOnAdminInstanceUsd(gib: number): number {
+  const perSecond = CLOUD_RUN_INSTANCE_PRICE.vcpuSecond + gib * CLOUD_RUN_INSTANCE_PRICE.gibSecond;
+  return Math.round(perSecond * MONTH_SECONDS);
 }
 
 /** The region the price table's list rates are for. */
@@ -71,6 +152,7 @@ export function estimateGcpCost(inputs: CostEstimateInputs): {
   const sqlMonthly = Math.round(sqlBase * sqlMultiplier);
 
   const provider = inputs.provider ?? "gcp";
+  const schedulerMinutes = parseSchedulerIntervalMinutes(inputs.schedulerIntervalMinutes);
   const adminMemory = inputs.adminMemory ?? ADMIN_MEMORY_DEFAULT;
   const adminMiB = memoryQuantityMiB(adminMemory);
   if (adminMiB === null) {
@@ -91,17 +173,20 @@ export function estimateGcpCost(inputs: CostEstimateInputs): {
     },
     {
       name: `Cloud Run admin (${adminMemory})`,
-      // FIXME(issue #1140): ~$1 once the admin runs request-billed CPU
-      // (SERVICE_CPU_IDLE). Until then each editing session is billed for
-      // as long as the instance stays up, ~15 minutes past its last request.
-      monthlyUsd:
-        inputs.adminMinInstances === 0
+      // FIXME(issue #1361): with request-billed CPU (SERVICE_CPU_IDLE) the
+      // ticks stop keeping the instance up and this line drops to ~$7 of
+      // editing sessions. Until then the scheduler tick (#1140) keeps one
+      // instance up around the clock, billed at the always-on rate.
+      monthlyUsd: adminKeptWarmByTicks(inputs.adminMinInstances)
+        ? alwaysOnAdminInstanceUsd(adminGiB)
+        : inputs.adminMinInstances === 0
           ? 7
           : Math.round(1 + inputs.adminMinInstances * perMinInstanceUsd),
-      notes:
-        inputs.adminMinInstances === 0
-          ? "scale-to-zero, CPU always allocated while running; ~$7/mo light editorial use"
-          : `${inputs.adminMinInstances} min-instance${inputs.adminMinInstances > 1 ? "s" : ""} (no cold start)`,
+      notes: adminKeptWarmByTicks(inputs.adminMinInstances)
+        ? `scale-to-zero, but CPU is always allocated and the scheduler tick (every ${schedulerMinutes} min) comes before Cloud Run's 15-minute idle shutdown, so one instance (1 vCPU, ${adminMemory}) runs around the clock until request-billed CPU lands (#1361)`
+        : inputs.adminMinInstances === 0
+          ? "scale-to-zero, request-billed CPU; ~$7/mo light editorial use, ticks inside the free tier"
+          : `${inputs.adminMinInstances} min-instance${inputs.adminMinInstances > 1 ? "s" : ""} (no cold start); the scheduler tick adds nothing, the instance is up anyway`,
     },
     {
       name: "Quality checks (Cloud Run audit job)",
@@ -192,7 +277,7 @@ export function estimateGcpCost(inputs: CostEstimateInputs): {
       name: "Secret Manager (runtime secrets)",
       monthlyUsd: 0.2,
       notes:
-        "6 active versions free, then ~$0.06 each; the Google sign-in client (#914) and the remote-MCP seal key (#806)",
+        "6 active versions free, then ~$0.06 each; the Google sign-in client (#914), the remote-MCP seal key (#806) and the staging database login's password (#1329; the staging database itself shares the Cloud SQL instance at no extra cost)",
     },
     {
       name: "BigQuery edge log sink",
@@ -211,6 +296,11 @@ export function estimateGcpCost(inputs: CostEstimateInputs): {
       notes:
         "Hourly ~20 s job keeps Google IAP in step with the user list; within the Cloud Run free tier, 1 of 3 free scheduler jobs",
     },
+    {
+      name: `Scheduler tick (Cloud Scheduler + Workflows, every ${schedulerMinutes} min)`,
+      monthlyUsd: schedulerTickMonthlyUsd(schedulerMinutes),
+      notes: `one job starts a ${SCHEDULER_TICK_STEPS.internal + SCHEDULER_TICK_STEPS.external}-step workflow that calls the admin's periodic work and plugin workers; ~${Math.ceil((30 * 24 * 60) / schedulerMinutes)} ticks/mo; what the ticks cost on the admin is on the admin line`,
+    },
   ];
 
   // Cents, so a sub-dollar line (the KMS key) doesn't print float noise.