cartethyia 2.7.4 → 2.7.6

package/src/workers/daily-checkin.ts

@@ -1,5 +1,9 @@
 // Daily check-in ride-along.
 //
+// dynamic-import-ok: the qoder/buddy check-in imports are lazy-loaded
+// inside the account loop (B-02) so the boot graph stays clean — this runs
+// as a ride-along with the quota sweep, not at startup.
+//
 // WorkBuddy/CodeBuddy grant a free credit package once per calendar day. This
 // claims it for every stored account and logs one line per account, so an
 // operator can confirm each account got its daily login credit.
@@ -23,21 +27,36 @@ import type { CartethyiaDatabase } from "../persistence/db-handle";
 import { dailyCheckinLedger, networkPools } from "../persistence/schema";
 import type { ProviderId } from "../providers/provider-contracts";
 import { log } from "../observability/logger";
-import {
-  DAILY_CHECKIN_PROVIDER_IDS,
-  checkinDayKey,
-  fetchDailyCheckin,
-  type DailyCheckinResult,
-} from "../providers/integrations/buddy/buddy-checkin";
-import {
-  fetchQoderDailyCheckin,
-  isQoderCheckinProvider,
-} from "../providers/integrations/qoder/qoder-checkin";
-import { DrizzleQoderNativeIdentityStore } from "../providers/integrations/qoder/qoder-native-identity-store";
+import type { DailyCheckinResult } from "../providers/integrations/buddy/buddy-checkin";
+import { BUDDY_PROVIDER_IDS } from "../providers/provider-metadata";
 
-export { DAILY_CHECKIN_PROVIDER_IDS, checkinDayKey };
 export type { DailyCheckinResult };
 
+/**
+ * Calendar-day key in UTC, matching the provider's own day boundary.
+ *
+ * Mirrors `buddy-checkin.ts`'s `checkinDayKey` (a pure two-line util). Kept
+ * local so this worker module does not statically import the heavy buddy-checkin
+ * graph just for a date key (B-02).
+ */
+export function checkinDayKey(now: Date = new Date()): string {
+  return now.toISOString().slice(0, 10);
+}
+
+/**
+ * The Buddy and Qoder providers the daily check-in claims a credit for.
+ *
+ * Derived from the shared buddy family set plus the Qoder check-in list, the
+ * same shape as `buddy-checkin.ts`'s `DAILY_CHECKIN_PROVIDER_IDS`. Kept local
+ * so this worker module does not statically import the heavy buddy/qoder
+ * graphs for a constant id list (B-02).
+ */
+const QODER_CHECKIN_PROVIDER_IDS: readonly string[] = ["qoder", "qodercn"];
+export const DAILY_CHECKIN_PROVIDER_IDS: readonly string[] = [
+  ...BUDDY_PROVIDER_IDS,
+  ...QODER_CHECKIN_PROVIDER_IDS,
+];
+
 /**
  * Pending check-in requests handed to the sweep by a caller outside it.
  *
@@ -270,6 +289,38 @@ export async function markCheckinAttempted(args: {
  * An account absent from the result was not attempted, matching the single
  * read's "absent means unknown, never claimed".
  */
+/**
+ * Shared Redis marker read. One `MGET` when the client supports it; otherwise
+ * (a minimal double, or a client without the command) a `GET` loop. Returns
+ * `undefined` when the ledger is unreadable — unknown, never "not claimed".
+ */
+async function readRedisMarkers(
+  redis: RedisClient,
+  dayKey: string,
+  accountIds: readonly string[],
+): Promise<Map<string, boolean> | undefined> {
+  const attempted = new Map<string, boolean>();
+  try {
+    if (typeof redis.mget === "function") {
+      // One command for every account: one key per account is small, and a
+      // single `MGET` keeps the cost flat instead of linear in the count.
+      const values = await redis.mget(
+        ...accountIds.map((id) => ledgerKey(dayKey, id)),
+      );
+      accountIds.forEach((accountId, index) => {
+        attempted.set(accountId, values[index] != null);
+      });
+      return attempted;
+    }
+    for (const accountId of accountIds) {
+      attempted.set(accountId, (await redis.get(ledgerKey(dayKey, accountId))) !== null);
+    }
+    return attempted;
+  } catch {
+    return undefined;
+  }
+}
+
 export async function checkinAttemptedTodayBatch(args: {
   readonly db: CartethyiaDatabase | undefined;
   readonly redis: RedisClient | undefined;
@@ -279,23 +330,11 @@ export async function checkinAttemptedTodayBatch(args: {
   const attempted = new Map<string, boolean>();
   if (args.accountIds.length === 0) return attempted;
   const dayKey = checkinDayKey(args.now?.() ?? new Date());
-  // A client without MGET (the memory backend) takes the DB path below, or
-  // reports unknown when there is no DB either.
-  if (args.redis !== undefined && typeof args.redis.mget === "function") {
-    try {
-      // One command for every account: one key per account is small, and a
-      // single `MGET` keeps the cost flat instead of linear in the count.
-      const values = (await args.redis.mget(
-        ...args.accountIds.map((id) => ledgerKey(dayKey, id)),
-      )) as Array<string | null>;
-      args.accountIds.forEach((accountId, index) => {
-        attempted.set(accountId, values[index] != null);
-      });
-      return attempted;
-    } catch {
-      // Fall through: an unreadable ledger means unknown, and the DB path is
-      // the only other place the marker could be.
-    }
+  if (args.redis !== undefined) {
+    const fromRedis = await readRedisMarkers(args.redis, dayKey, args.accountIds);
+    if (fromRedis !== undefined) return fromRedis;
+    // Fall through: an unreadable ledger means unknown, and the DB path is
+    // the only other place the marker could be.
   }
   if (args.db === undefined) return attempted;
   try {
@@ -326,11 +365,8 @@ export async function checkinAttemptedToday(args: {
 }): Promise<boolean> {
   const dayKey = checkinDayKey(args.now?.() ?? new Date());
   if (args.redis !== undefined) {
-    try {
-      return (await args.redis.get(ledgerKey(dayKey, args.accountId))) !== null;
-    } catch {
-      return false;
-    }
+    const fromRedis = await readRedisMarkers(args.redis, dayKey, [args.accountId]);
+    if (fromRedis !== undefined) return fromRedis.get(args.accountId) ?? false;
   }
   if (args.db === undefined) return false;
   try {
@@ -384,7 +420,7 @@ export function withDirectFallback(fetcher: typeof fetch): typeof fetch {
  * (`buddy-activity-report`) with its own ledger, so it is not re-POSTed on
  * every sweep. See `buddy-growth-tasks.ts`.
  */
-export type DailyGrowthPassResult = {
+type DailyGrowthPassResult = {
   readonly checkin: DailyCheckinResult;
 };
 
@@ -428,20 +464,37 @@ export async function attemptDailyGrowthPass(args: {
   }
   let checkin: DailyCheckinResult;
   try {
-    checkin = isQoderCheckinProvider(String(providerId))
-      ? await fetchQoderDailyCheckin({
-          providerId: String(providerId),
-          accountId,
-          credential,
-          fetcher,
-          ...(db ? { nativeIdentityStore: new DrizzleQoderNativeIdentityStore(db) } : {}),
-        })
-      : await fetchDailyCheckin({
-          providerId,
-          accountId,
-          credential,
-          fetcher,
-        });
+    // The buddy/qoder check-in graphs are lazy-loaded: only the provider on
+    // this account needs its surface, and neither should sit on the boot graph
+    // (B-02).
+    const isQoderCheckinProvider = (
+      await import("../providers/integrations/qoder/qoder-checkin")
+    ).isQoderCheckinProvider;
+    if (isQoderCheckinProvider(String(providerId))) {
+      const { fetchQoderDailyCheckin } = await import(
+        "../providers/integrations/qoder/qoder-checkin"
+      );
+      const { DrizzleQoderNativeIdentityStore } = await import(
+        "../providers/integrations/qoder/qoder-native-identity-store"
+      );
+      checkin = await fetchQoderDailyCheckin({
+        providerId: String(providerId),
+        accountId,
+        credential,
+        fetcher,
+        ...(db ? { nativeIdentityStore: new DrizzleQoderNativeIdentityStore(db) } : {}),
+      });
+    } else {
+      const { fetchDailyCheckin } = await import(
+        "../providers/integrations/buddy/buddy-checkin"
+      );
+      checkin = await fetchDailyCheckin({
+        providerId,
+        accountId,
+        credential,
+        fetcher,
+      });
+    }
   } catch (error) {
     checkin = {
       providerId,

package/src/workers/maintenance-lease.ts

@@ -16,6 +16,7 @@
  */
 import { randomUUID } from "node:crypto";
 
+import { redisEvalNumber } from "../persistence/redis";
 import type { RedisClient } from "../persistence/redis";
 
 /** Key prefix; the task name is the discriminator. */
@@ -98,29 +99,6 @@ export function leaseTtlMs(intervalMs: number): number {
   return Math.min(MAX_LEASE_TTL_MS, Math.max(MIN_LEASE_TTL_MS, Math.trunc(intervalMs)));
 }
 
-/** A store that hands out no lease — used when Redis is absent. */
-export function createNoopMaintenanceLeaseStore(): MaintenanceLeaseStore {
-  return {
-    async tryAcquire(taskName) {
-      return {
-        taskName,
-        // Held = true: with no shared store this process cannot coordinate, so
-        // the local registry's own re-entrancy rule is the only guard. The
-        // alternative — reporting not-held — would silently disable every
-        // maintenance task on single-process deployments, which is most of
-        // them.
-        held: true,
-        async renew() {
-          return true;
-        },
-        async release() {
-          /* nothing to give back */
-        },
-      };
-    },
-  };
-}
-
 /**
  * A Redis-backed lease store.
  *
@@ -134,18 +112,7 @@ export function createRedisMaintenanceLeaseStore(redis: RedisClient): Maintenanc
     script: string,
     key: string,
     args: readonly (string | number)[],
-  ): Promise<number> => {
-    const raw = await (
-      redis as unknown as {
-        eval: (
-          script: string,
-          numKeys: number,
-          ...args: (string | number)[]
-        ) => Promise<unknown>;
-      }
-    ).eval(script, 1, key, ...args);
-    return Number(raw);
-  };
+  ): Promise<number> => redisEvalNumber(redis, script, 1, key, ...args);
 
   return {
     async tryAcquire(taskName, ttlMs) {

package/src/workers/oauth-refresh-sweep.ts

@@ -9,7 +9,7 @@ export interface DueOAuthAccount {
   readonly providerId: string;
 }
 
-export interface OAuthRefreshSweepDeps {
+interface OAuthRefreshSweepDeps {
   readonly loadDueAccounts: () => Promise<readonly DueOAuthAccount[]>;
   readonly refreshService: Pick<OAuthRefreshService, "ensureFreshAccessToken">;
   /** Resolves a provider's token-endpoint client; accounts with no registered refresher are skipped. */
@@ -17,6 +17,12 @@ export interface OAuthRefreshSweepDeps {
   readonly skewMs?: number;
   /** Maximum accounts in one completed wave. Defaults to 5. */
   readonly maxConcurrency?: number;
+  /**
+   * Wall-clock cap for the whole pass; the next wave does not start past it
+   * (G-04). Mirrors the quota refresh sweep's 45 s pass budget so OAuth
+   * refreshes cannot run away into a heavy foreground minute.
+   */
+  readonly budgetMs?: number;
   /**
    * Milliseconds to pause between accounts when running sequentially. Absent
    * keeps the default wave behavior. Providers whose token endpoint rate-limits
@@ -70,6 +76,7 @@ export async function oauthRefreshSweep(deps: OAuthRefreshSweepDeps): Promise<vo
     ...(deps.interItemDelayMs === undefined
       ? {}
       : { pace: { interItemDelayMs: deps.interItemDelayMs } }),
+    ...(deps.budgetMs === undefined ? {} : { budgetMs: deps.budgetMs }),
   });
 
   // A pass that could not even list its accounts reports no tick: an all-zero

package/src/workers/quota-refresh-sweep.ts

@@ -97,7 +97,7 @@ const DEFAULT_MAX_CHECKINS_PER_PASS = 10;
  * its automatic check-in — only a manual press, which bypasses the cap, ever
  * reaches it.
  */
-export function checkinSlotAvailable(
+function checkinSlotAvailable(
   providerId: string,
   checkinsSoFar: number,
   maxCheckins: number,
@@ -136,6 +136,112 @@ function getErrorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
+/** One candidate the sweep considers: the target plus its cache age. */
+type SweepEntry = { target: QuotaRefreshTarget; ageMs: number };
+
+/**
+ * Selects the batch for one pass: eligible (due or queued) accounts first,
+ * buddy accounts pulled ahead of age ordering so the check-in ride-along is
+ * not starved by older non-buddy rows, capped at `maxPerPass`.
+ */
+function selectBatch(
+  entries: readonly SweepEntry[],
+  minAgeMs: number,
+  maxPerPass: number,
+  listPendingCheckins: () => readonly PendingCheckinRequest[],
+): { batch: SweepEntry[]; skipped: number } {
+  // An account added since the last pass is admitted regardless of cache
+  // age: it has no quota reading at all yet, so the normal freshness gate
+  // would make a brand-new buddy account wait a full sweep cycle before it
+  // could claim its credit — the import enqueued it precisely so it would
+  // not have to. Only the check-in needs this; the quota leg is happy to
+  // fill a cold cache the moment it is asked to.
+  const queued = new Set(
+    listPendingCheckins()
+      .filter((request) => supportsDailyCheckin(request.providerId))
+      .map((request) => request.accountId),
+  );
+  const due = entries.filter(
+    (entry) => entry.ageMs >= minAgeMs || queued.has(entry.target.accountId),
+  );
+  due.sort((left, right) => {
+    const leftQueued = queued.has(left.target.accountId) ? 0 : 1;
+    const rightQueued = queued.has(right.target.accountId) ? 0 : 1;
+    if (leftQueued !== rightQueued) return leftQueued - rightQueued;
+    const leftBuddy = supportsDailyCheckin(left.target.providerId) ? 0 : 1;
+    const rightBuddy = supportsDailyCheckin(right.target.providerId) ? 0 : 1;
+    if (leftBuddy !== rightBuddy) return leftBuddy - rightBuddy;
+    return right.ageMs - left.ageMs;
+  });
+  const batch = due.slice(0, maxPerPass);
+  return { batch, skipped: entries.length - due.length + (due.length - batch.length) };
+}
+
+/**
+ * Runs the daily check-in ride-along for one batch item: claims its slot
+ * before the first await (the wave runs concurrently, so the count read after
+ * resolution would let the whole wave through), then attempts the growth pass
+ * and records the outcome. Bounded by the per-pass cap.
+ */
+async function runCheckinRideAlong(
+  deps: QuotaRefreshSweepDeps,
+  entry: SweepEntry,
+  resolveCredentialCached: (providerId: ProviderId, accountId: string) => Promise<string>,
+  state: { checkins: number; claimed: number; maxCheckins: number },
+  checkinOutcomes: Map<string, DailyCheckinResult>,
+): Promise<void> {
+  // The provider filter comes *before* the slot is consumed. The batch is
+  // oldest-first across every provider, so checking the cap first spends the
+  // whole per-pass budget on non-buddy accounts that the next line would
+  // skip anyway — a buddy account past the cap (a cbcn row behind ten older
+  // non-buddy rows) is never checked in automatically, only when an operator
+  // presses the button, which bypasses this cap entirely.
+  if (!checkinSlotAvailable(entry.target.providerId, state.checkins, state.maxCheckins)) return;
+  // Claim the slot before the first await. The wave runs its items
+  // concurrently, and reading `checkins` only after the growth pass
+  // resolves lets every item in the wave pass the cap check against the
+  // same stale count — the cap then bounds nothing.
+  state.checkins += 1;
+  try {
+    // A `ValidatedFetch` shares the fetch call signature; the only
+    // difference is Bun's `preconnect` static, so a single assertion is
+    // enough (the double cast added nothing).
+    const pooled: typeof fetch | undefined = deps.checkinFetcherFor
+      ? ((await deps.checkinFetcherFor(
+          entry.target.accountId,
+          entry.target.tenantId,
+        )) as typeof fetch)
+      : undefined;
+    const fetcher = pooled ?? deps.checkinFetcher;
+    const pass = await attemptDailyGrowthPass({
+      db: deps.db,
+      redis: deps.redis,
+      providerId: entry.target.providerId as ProviderId,
+      accountId: entry.target.accountId,
+      resolveCredential: resolveCredentialCached,
+      ...(fetcher ? { fetcher } : {}),
+    });
+    // The request has been served: the pass either ran and wrote its own
+    // day marker, or declined because today's slot was already settled.
+    // Holding the entry would only make the next pass re-admit an account
+    // it just handled.
+    dequeueCheckin(entry.target.accountId);
+    if (pass !== null) {
+      if (pass.checkin.state === "claimed") state.claimed += 1;
+      checkinOutcomes.set(entry.target.accountId, pass.checkin);
+    }
+  } catch (error) {
+    checkinOutcomes.set(entry.target.accountId, {
+      providerId: entry.target.providerId,
+      accountId: entry.target.accountId,
+      state: "error",
+      credit: null,
+      streakDays: null,
+      error: getErrorMessage(error),
+    });
+  }
+}
+
 /** `provider/identity` — the account's own label, else its id. */
 function accountName(target: QuotaRefreshTarget): string {
   const label = (target.label ?? "").trim();
@@ -278,9 +384,10 @@ export async function quotaRefreshSweep(deps: QuotaRefreshSweepDeps): Promise<vo
   };
 
   let failed = 0;
-  let claimed = 0;
-  let checkins = 0;
   const maxCheckins = deps.maxCheckinsPerPass ?? DEFAULT_MAX_CHECKINS_PER_PASS;
+  // The ride-along mutates this shared object (not local copies), so its
+  // counters stay visible to the summary and the tick report after the wave.
+  const checkinState = { checkins: 0, claimed: 0, maxCheckins };
 
   /**
    * One log line per account, emitted after the wave completes so the quota
@@ -361,33 +468,7 @@ export async function quotaRefreshSweep(deps: QuotaRefreshSweepDeps): Promise<vo
     // happened when an operator pressed the button. Attendance is once a day
     // and quota is refreshed every pass, so letting the check-in go first
     // costs the quota leg nothing.
-    select: (entries) => {
-      // An account added since the last pass is admitted regardless of cache
-      // age: it has no quota reading at all yet, so the normal freshness gate
-      // would make a brand-new buddy account wait a full sweep cycle before it
-      // could claim its credit — the import enqueued it precisely so it would
-      // not have to. Only the check-in needs this; the quota leg is happy to
-      // fill a cold cache the moment it is asked to.
-      const queued = new Set(
-        listPendingCheckins()
-          .filter((request) => supportsDailyCheckin(request.providerId))
-          .map((request) => request.accountId),
-      );
-      const due = entries.filter(
-        (entry) => entry.ageMs >= minAgeMs || queued.has(entry.target.accountId),
-      );
-      due.sort((left, right) => {
-        const leftQueued = queued.has(left.target.accountId) ? 0 : 1;
-        const rightQueued = queued.has(right.target.accountId) ? 0 : 1;
-        if (leftQueued !== rightQueued) return leftQueued - rightQueued;
-        const leftBuddy = supportsDailyCheckin(left.target.providerId) ? 0 : 1;
-        const rightBuddy = supportsDailyCheckin(right.target.providerId) ? 0 : 1;
-        if (leftBuddy !== rightBuddy) return leftBuddy - rightBuddy;
-        return right.ageMs - left.ageMs;
-      });
-      const batch = due.slice(0, maxPerPass);
-      return { batch, skipped: entries.length - due.length + (due.length - batch.length) };
-    },
+    select: (entries) => selectBatch(entries, minAgeMs, maxPerPass, listPendingCheckins),
     run: async (entry) => {
       attemptedTargets.push(entry.target);
       const outcome = await refreshAccountQuota(
@@ -418,56 +499,13 @@ export async function quotaRefreshSweep(deps: QuotaRefreshSweepDeps): Promise<vo
       // `attemptDailyGrowthPass`). Bounded per pass, and skipped for providers
       // without the billing route — a day marker makes this a no-op on every
       // pass after the first of the day.
-      //
-      // The provider filter comes *before* the slot is consumed. The batch is
-      // oldest-first across every provider, so checking the cap first spends the
-      // whole per-pass budget on non-buddy accounts that the next line would
-      // skip anyway — a buddy account past the cap (a cbcn row behind ten older
-      // non-buddy rows) is never checked in automatically, only when an operator
-      // presses the button, which bypasses this cap entirely.
-      if (!checkinSlotAvailable(entry.target.providerId, checkins, maxCheckins)) return;
-      // Claim the slot before the first await. The wave runs its items
-      // concurrently, and reading `checkins` only after the growth pass
-      // resolves lets every item in the wave pass the cap check against the
-      // same stale count — the cap then bounds nothing.
-      checkins += 1;
-      try {
-        // is only for the `preconnect` static Bun adds to its own fetch (the
-        // same cast the adapters use for `outbound_fetch`).
-        const pooled = deps.checkinFetcherFor
-          ? ((await deps.checkinFetcherFor(
-              entry.target.accountId,
-              entry.target.tenantId,
-            )) as unknown as typeof fetch)
-          : undefined;
-        const fetcher = pooled ?? deps.checkinFetcher;
-        const pass = await attemptDailyGrowthPass({
-          db: deps.db,
-          redis: deps.redis,
-          providerId: entry.target.providerId as ProviderId,
-          accountId: entry.target.accountId,
-          resolveCredential: resolveCredentialCached,
-          ...(fetcher ? { fetcher } : {}),
-        });
-        // The request has been served: the pass either ran and wrote its own
-        // day marker, or declined because today's slot was already settled.
-        // Holding the entry would only make the next pass re-admit an account
-        // it just handled.
-        dequeueCheckin(entry.target.accountId);
-        if (pass !== null) {
-          if (pass.checkin.state === "claimed") claimed += 1;
-          checkinOutcomes.set(entry.target.accountId, pass.checkin);
-        }
-      } catch (error) {
-        checkinOutcomes.set(entry.target.accountId, {
-          providerId: entry.target.providerId,
-          accountId: entry.target.accountId,
-          state: "error",
-          credit: null,
-          streakDays: null,
-          error: getErrorMessage(error),
-        });
-      }
+      await runCheckinRideAlong(
+        deps,
+        entry,
+        resolveCredentialCached,
+        checkinState,
+        checkinOutcomes,
+      );
     },
     onItemError: (entry, error) => {
       failed += 1;
@@ -486,7 +524,7 @@ export async function quotaRefreshSweep(deps: QuotaRefreshSweepDeps): Promise<vo
     now,
   });
 
-  logSweepAccounts(attemptedTargets, quotaOutcomes, checkinOutcomes, failed, claimed);
+  logSweepAccounts(attemptedTargets, quotaOutcomes, checkinOutcomes, failed, checkinState.claimed);
 
   // Release the slots for the accounts whose check-in errored, in one
   // round-trip. Releasing inline per account makes a pass that budgets out with
@@ -507,6 +545,6 @@ export async function quotaRefreshSweep(deps: QuotaRefreshSweepDeps): Promise<vo
     attempted: result.attempted,
     skipped: result.skipped,
     failed,
-    checkins,
+    checkins: checkinState.checkins,
   });
 }

package/src/workers/scheduler.ts

@@ -4,6 +4,7 @@
  * behavior.
  */
 import { log } from "../observability/logger";
+import { foregroundBusy } from "../shared/invoke-guard";
 import type { MaintenanceLeaseStore } from "./maintenance-lease";
 import { leaseTtlMs } from "./maintenance-lease";
 
@@ -12,6 +13,21 @@ export interface ScheduledTask {
   readonly intervalMs: number;
   /** Delay before the first run after the registry starts. */
   readonly initialDelayMs?: number;
+  /**
+   * True when this task should defer its tick while foreground activity is in
+   * flight (console requests / proxy invocations) — the G-03 InvokeGuard.
+   *
+   * Opt-in: tasks that only publish in-process gauges (`runtime-metrics`) or
+   * run at a far cadence (`telemetry-retention`) have no reason to yield, and
+   * a task that must run on schedule (a lease hold) would be the wrong place
+   * to pause. The heavy sweeps set it.
+   *
+   * The defer is a bounded pause, never a skip: a task waits up to
+   * {@link FOREGROUND_DEFER_MAX_MS} for the foreground to clear, then runs
+   * regardless. Foreground starvation of maintenance is worse than a sweep
+   * and foreground sharing one tick.
+   */
+  readonly deferWhenBusy?: boolean;
   /**
    * Whether this task's work is SHARED across the fleet, so only one process
    * should run it per interval.
@@ -28,7 +44,7 @@ export interface ScheduledTask {
   run(): Promise<unknown> | void;
 }
 
-export interface ScheduledTaskRegistryOptions {
+interface ScheduledTaskRegistryOptions {
   /**
    * Cross-process coordinator. When present, a task that cannot acquire the
    * fleet lease SKIPS its tick rather than waiting — the next interval is the
@@ -62,6 +78,12 @@ export async function runGrowingWaves<T>(
     readonly maxConcurrency: number;
     readonly onItem: (item: T) => Promise<void> | void;
     readonly shouldStop?: () => boolean;
+    /**
+     * Invoked before each wave (after `shouldStop`). The sweep runner uses it
+     * to pause while foreground activity is busy (G-03); a caller that does not
+     * need that passes nothing.
+     */
+    readonly beforeWave?: () => Promise<void> | void;
   },
 ): Promise<void> {
   const limit = Math.max(1, options.maxConcurrency);
@@ -69,6 +91,7 @@ export async function runGrowingWaves<T>(
   let waveSize = Math.min(DEFAULT_INITIAL_BATCH_SIZE, limit);
   while (offset < items.length) {
     if (options.shouldStop?.() === true) return;
+    await options.beforeWave?.();
     const wave = items.slice(offset, offset + waveSize);
     offset += wave.length;
     await Promise.all(wave.map((item) => options.onItem(item)));
@@ -76,7 +99,7 @@ export async function runGrowingWaves<T>(
   }
 }
 
-export const DEFAULT_INITIAL_BATCH_SIZE = 2;
+const DEFAULT_INITIAL_BATCH_SIZE = 2;
 
 /**
  * How long a tick may wait for the maintenance lease.
@@ -88,6 +111,28 @@ export const DEFAULT_INITIAL_BATCH_SIZE = 2;
  */
 const LEASE_ACQUIRE_TIMEOUT_MS = 5_000;
 
+/**
+ * How long a deferring task waits for foreground activity to clear before
+ * running anyway (G-03). Deliberately shorter than any sweep budget: the pause
+ * is a courtesy, not a schedule, and a continuous page/stream flood must not
+ * starve maintenance forever.
+ */
+const FOREGROUND_DEFER_MAX_MS = 3_000;
+
+/** Poll interval while waiting for foreground to clear. */
+const FOREGROUND_DEFER_POLL_MS = 50;
+
+/**
+ * Bounded wait for foreground activity to clear. Returns once the foreground
+ * is idle or the deadline elapses — never blocks past `FOREGROUND_DEFER_MAX_MS`.
+ */
+async function deferForForeground(now: () => number, sleep: (ms: number) => Promise<void>): Promise<void> {
+  const until = now() + FOREGROUND_DEFER_MAX_MS;
+  while (foregroundBusy() && now() < until) {
+    await sleep(FOREGROUND_DEFER_POLL_MS);
+  }
+}
+
 /** Resolves with the value, or rejects if `promise` has not settled in time. */
 async function withDeadline<T>(promise: Promise<T>, timeoutMs: number): Promise<T> {
   // `clearTimeout` no-ops for an absent handle, so it needs no guard. A live
@@ -277,6 +322,14 @@ export class ScheduledTaskRegistry {
     // every task fires at once once the blocker finishes, which is the burst
     // this rule exists to prevent.
     if (this.busy !== undefined) return;
+    // G-03: a foreground-deferring task waits out foreground activity (bounded)
+    // before latching the shared gate. The gate is NOT latched during the wait,
+    // so the re-check below is required: a different task can claim the gate
+    // (and finish) while this one is waiting.
+    if (task.deferWhenBusy === true) {
+      await deferForForeground(this.now, (ms) => new Promise((r) => setTimeout(r, ms)));
+    }
+    if (this.running.has(task.name) || this.busy !== undefined) return;
     this.running.add(task.name);
     this.busy = task.name;
     let lease: Awaited<ReturnType<MaintenanceLeaseStore["tryAcquire"]>> | undefined;
@@ -332,8 +385,18 @@ export class ScheduledTaskRegistry {
         log.error(`[scheduled-task:${task.name}] failed`, error as Error);
         // Released on failure too: the error is this process's, not the
         // fleet's, and holding the lease until it expires would block the
-        // next tick for no reason.
-        if (lease !== undefined) await lease.release().catch(() => undefined);
+        // next tick for no reason. A failed release is logged — the TTL is
+        // the backstop, but the failure should stay visible.
+        if (lease !== undefined) {
+          try {
+            await lease.release();
+          } catch (releaseError) {
+            log.warn(
+              `[scheduled-task:${task.name}] lease release failed after task error`,
+              releaseError as Error,
+            );
+          }
+        }
       } finally {
         // No-ops for an absent handle, and the renewal timer is always
         // assigned before this runs.