@cosmicdrift/kumiko-bundled-features 0.221.0 → 0.223.0

package/src/files-tenant-data/handlers/sweep-orphaned-derivatives.job.ts

@@ -0,0 +1,173 @@
+// Backfill/GC job for derivatives orphaned by a forget/tenant-destroy that ran
+// before #2461 wired binary cleanup into those flows (#2474). Those older runs
+// left the FileRef row gone with no audit trail of what was ever forgotten —
+// so this sweep works forward from the deterministic derivative-key grammar
+// alone: for every key under a tenant's storage prefix that parses as a
+// derivative (parseDerivativeKey), delete it only if NO fileRef row (live or
+// trashed) backs its reconstructed original. A row backing the original — even
+// a soft-deleted one sitting in trash — means the derivative is still
+// legitimate; only genuinely unreferenced derivatives are swept.
+//
+// Manual trigger only (no cron) — an operator runs this once after upgrading
+// past #2461, or on demand for spot-checks.
+//
+// Row unit for runChunkedMigration is a discovered derivative CANDIDATE KEY,
+// not a tenant: one tenant's storage listing produces a variable number of
+// candidates, which doesn't fit "one row -> one migrate outcome" if the row
+// were a tenant. nextBatch pages tenants internally and buffers their
+// candidates into a flat queue so the shared deadline/circuit-breaker/signal
+// handling still applies per-key.
+
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { parseDerivativeKey } from "@cosmicdrift/kumiko-framework/derivatives";
+import type { JobHandlerFn, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import {
+  assertSafeStorageKey,
+  type FileProviderResolver,
+  type FileStorageProvider,
+  fileRefsTable,
+} from "@cosmicdrift/kumiko-framework/files";
+import { z } from "zod";
+import { runChunkedMigration } from "../../shared";
+import { tenantTable } from "../../tenant";
+
+const DEFAULT_TENANT_PAGE_SIZE = 50;
+const DEFAULT_CANDIDATE_BATCH_SIZE = 100;
+const DEFAULT_MAX_FAILURES = 10;
+
+export const sweepOrphanedDerivativesPayloadSchema = z.object({
+  dryRun: z.boolean().optional(),
+  batchSize: z.number().int().positive().optional(),
+  maxDurationMs: z.number().int().positive().optional(),
+  maxFailures: z.number().int().positive().optional(),
+});
+
+type DerivativeCandidate = {
+  readonly tenantId: TenantId;
+  readonly key: string;
+  readonly originalKey: string;
+  readonly provider: FileStorageProvider;
+};
+
+export const sweepOrphanedDerivativesJob: JobHandlerFn = async (rawPayload, ctx): Promise<void> => {
+  const payload = sweepOrphanedDerivativesPayloadSchema.parse(rawPayload ?? {});
+  if (!ctx.db) {
+    throw new InternalError({
+      message:
+        "[files-tenant-data:sweep] ctx.db missing — job context requires a database connection.",
+    });
+  }
+  const db = ctx.db;
+  // Re-bound to a definitely-assigned const: TS control-flow narrowing from
+  // the guard above doesn't cross into fillQueue's nested closure below.
+  const maybeResolver = ctx._fileProviderResolver;
+  if (!maybeResolver) {
+    ctx.log?.warn(
+      "[files-tenant-data:sweep] no _fileProviderResolver wired — nothing to sweep, skipping run",
+    );
+    return;
+  }
+  const resolver: FileProviderResolver = maybeResolver;
+
+  const batchSize = payload.batchSize ?? DEFAULT_CANDIDATE_BATCH_SIZE;
+  const maxFailures = payload.maxFailures ?? DEFAULT_MAX_FAILURES;
+  const deadline = payload.maxDurationMs
+    ? Date.now() + payload.maxDurationMs
+    : Number.POSITIVE_INFINITY;
+  const dryRun = payload.dryRun ?? false;
+
+  let queue: DerivativeCandidate[] = [];
+  let tenantCursor: string | undefined;
+  let tenantsExhausted = false;
+  let dryRunWouldDelete = 0;
+
+  async function fillQueue(): Promise<void> {
+    while (queue.length === 0 && !tenantsExhausted) {
+      const tenants = await selectMany<{ id: string }>(
+        db,
+        tenantTable,
+        tenantCursor ? { id: { gt: tenantCursor } } : {},
+        { orderBy: [{ col: "id", direction: "asc" }], limit: DEFAULT_TENANT_PAGE_SIZE },
+      );
+      if (tenants.length === 0) {
+        tenantsExhausted = true;
+        break;
+      }
+      tenantCursor = tenants.at(-1)?.id;
+      for (const tenant of tenants) {
+        const tenantId = tenant.id as TenantId;
+        let provider: FileStorageProvider;
+        try {
+          provider = await resolver(tenantId);
+        } catch (err) {
+          ctx.log?.warn?.(
+            `[files-tenant-data:sweep] no file provider resolvable for tenant=${tenantId}, skipping: ${err instanceof Error ? err.message : String(err)}`,
+          );
+          continue;
+        }
+        let keys: readonly string[];
+        try {
+          keys = await provider.list(`${tenantId}/`);
+        } catch (err) {
+          ctx.log?.warn?.(
+            `[files-tenant-data:sweep] provider.list() failed for tenant=${tenantId}, skipping: ${err instanceof Error ? err.message : String(err)}`,
+          );
+          continue;
+        }
+        for (const key of keys) {
+          const parsed = parseDerivativeKey(key);
+          if (!parsed) continue;
+          queue.push({ tenantId, key, originalKey: parsed.originalKey, provider });
+        }
+      }
+    }
+  }
+
+  async function nextBatch(): Promise<readonly DerivativeCandidate[]> {
+    await fillQueue();
+    const batch = queue.slice(0, batchSize);
+    queue = queue.slice(batch.length);
+    return batch;
+  }
+
+  async function migrateRow(
+    candidate: DerivativeCandidate,
+  ): Promise<"migrated" | "skipped" | "failed"> {
+    // No isDeleted filter: a soft-deleted (trashed, not yet forgotten) fileRef
+    // still legitimately backs its derivatives — only an ABSENT row (forgotten,
+    // or a tenant destroyed before #2461 with no row left at all) makes a
+    // derivative orphaned.
+    const owners = await selectMany(
+      db,
+      fileRefsTable,
+      { tenantId: candidate.tenantId, storageKey: candidate.originalKey },
+      { limit: 1 },
+    );
+    if (owners.length > 0) return "skipped";
+    if (dryRun) {
+      dryRunWouldDelete++;
+      return "skipped";
+    }
+    assertSafeStorageKey(candidate.key);
+    await candidate.provider.delete(candidate.key);
+    return "migrated";
+  }
+
+  const outcome = await runChunkedMigration<DerivativeCandidate>({
+    nextBatch,
+    migrateRow,
+    maxFailures,
+    deadlineAt: deadline,
+    signal: ctx.signal,
+    onRowError: (candidate, err) => {
+      ctx.log?.warn?.(
+        `[files-tenant-data:sweep] failed to delete key=${candidate.key} tenant=${candidate.tenantId}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    },
+  });
+
+  ctx.log?.info?.(
+    `[files-tenant-data:sweep] complete dryRun=${dryRun} deleted=${outcome.migrated} wouldDelete=${dryRunWouldDelete} skipped=${outcome.skipped} failed=${outcome.failed} batches=${outcome.batchesProcessed} stoppedReason=${outcome.stoppedReason}`,
+  );
+};

package/src/files-tenant-data/hooks.ts

@@ -0,0 +1,93 @@
+// EXT_TENANT_DATA + EXT_STORAGE_PROVIDER destroy hooks for the `fileRef`
+// entity (#2474). Kept apart from the `files` feature (like folders-user-data
+// does for EXT_USER_DATA) so file consumers without the tenant-lifecycle
+// pipeline don't pull a hard dependency — `files` stays usable standalone.
+//
+// Two hooks cover two different destroy stages:
+//   - fileRefTenantDestroyHook ("app-data" stage, EXT_TENANT_DATA): purges
+//     every fileRef ROW for the tenant via forget() — rebuild-safe, mirrors
+//     document-ingest-foundation's documentExtractTenantDestroyHook. No
+//     isDeleted filter: tenant-destroy purges trashed rows too, a destroyed
+//     tenant has no "restore from trash" future.
+//   - fileRefStorageDestroyHook ("files" stage, EXT_STORAGE_PROVIDER): wipes
+//     every BINARY (original + derivatives + anything else) under the
+//     tenant's storage prefix. A full `${tenantId}/` prefix sweep, not a
+//     per-row derivative lookup — buildStorageKey always puts tenantId first,
+//     so this needs only the tenantId, stays correct even though the "files"
+//     stage runs after "app-data" already forgot the rows, and can never
+//     cross into another tenant's keys (the provider's own list() prefix
+//     already scopes it).
+
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { createEventStoreExecutor, createTenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createSystemUser,
+  type StorageProviderDestroyTenantHook,
+  type TenantDataDestroyHook,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  assertSafeStorageKey,
+  fileRefEntity,
+  fileRefsTable,
+} from "@cosmicdrift/kumiko-framework/files";
+
+const crud = createEventStoreExecutor(fileRefsTable, fileRefEntity, { entityName: "fileRef" });
+
+export const fileRefTenantDestroyHook: TenantDataDestroyHook = async (ctx) => {
+  const rows = await selectMany<{ id: string }>(ctx.db, fileRefsTable, {
+    tenantId: ctx.tenantId,
+  });
+  const user = createSystemUser(ctx.tenantId);
+  const db = createTenantDb(ctx.db, ctx.tenantId, "system");
+  for (const row of rows) {
+    const result = await crud.forget({ id: row.id }, user, db);
+    // Executor writes return {isSuccess:false} instead of throwing — a
+    // discarded result would report this destroy stage "succeeded" while the
+    // row (and its PII fileName) survives. Throw so the pipeline's
+    // retry/abandon handling sees it.
+    if (!result.isSuccess) {
+      throw new Error(
+        `files-tenant-data: failed to forget fileRef ${row.id} for tenant ${ctx.tenantId}: ${result.error.message}`,
+      );
+    }
+  }
+};
+
+export const fileRefStorageDestroyHook: StorageProviderDestroyTenantHook = async (
+  tenantId,
+  ctx,
+) => {
+  if (!ctx.fileProviderResolver) {
+    // Resolution unavailable (no file-provider-* feature mounted, or the job
+    // ctx didn't wire one) degrades to a no-op — same "not fail-closed"
+    // stance as the per-user forget hook's resolveProvider: a misconfigured
+    // store must not block the rest of the destroy pipeline forever. The row
+    // purge from the "app-data" stage already ran regardless.
+    ctx.log?.(
+      `[files-tenant-data] no fileProviderResolver wired — tenant ${tenantId}'s file binaries are NOT deleted on destroy`,
+    );
+    // skip: no resolver wired for this destroy run — already logged above, and
+    // the row purge from the "app-data" stage ran regardless.
+    return;
+  }
+  let provider: Awaited<ReturnType<typeof ctx.fileProviderResolver>>;
+  try {
+    provider = await ctx.fileProviderResolver(tenantId);
+  } catch (err) {
+    ctx.log?.(
+      `[files-tenant-data] no file provider resolvable for tenant ${tenantId}: ${err instanceof Error ? err.message : String(err)} — binaries NOT deleted`,
+    );
+    // skip: provider resolution failed for this tenant — already logged
+    // above, binaries are left in place rather than blocking the pipeline.
+    return;
+  }
+  // Provider resolved — a list()/delete() failure from here IS fail-closed:
+  // the "files" stage throws, tenant-lifecycle's retry/abandon handling sees
+  // it, and the next sweep tick retries (list+delete are idempotent, so this
+  // converges rather than double-deleting or erroring on a missing key).
+  const keys = await provider.list(`${tenantId}/`);
+  for (const key of keys) {
+    assertSafeStorageKey(key);
+    await provider.delete(key);
+  }
+};

package/src/files-tenant-data/index.ts

@@ -0,0 +1,58 @@
+// GDPR tenant-destroy + orphaned-derivative backfill coverage for the `files`
+// feature's `fileRef` entity (#2474). Kept apart from `files` — like
+// folders-user-data does for EXT_USER_DATA — so file consumers without the
+// tenant-lifecycle pipeline don't pull a hard dependency; `files` stays usable
+// standalone (e.g. user-data-rights-demo mounts `files` + user-data-rights
+// without tenant-lifecycle).
+//
+// tenant-lifecycle is the hard dependency (EXT_TENANT_DATA + EXT_STORAGE_PROVIDER
+// host). `files` is OPTIONAL: if it's mounted toggleable (default=false), a hard
+// r.requires would throw an "effectively disabled" boot warning even though the
+// fileRef entity exists and the hooks work fine — same reasoning as
+// folders-user-data's optionalRequires("folders").
+
+import {
+  defineFeature,
+  EXT_STORAGE_PROVIDER,
+  EXT_TENANT_DATA,
+  type FeatureDefinition,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  sweepOrphanedDerivativesJob,
+  sweepOrphanedDerivativesPayloadSchema,
+} from "./handlers/sweep-orphaned-derivatives.job";
+import { fileRefStorageDestroyHook, fileRefTenantDestroyHook } from "./hooks";
+
+export function createFilesTenantDataFeature(): FeatureDefinition {
+  return defineFeature("files-tenant-data", (r) => {
+    r.describe(
+      "GDPR coverage for the `files` feature's `fileRef` entity: tenant-destroy row purge (EXT_TENANT_DATA) and full storage-prefix binary wipe (EXT_STORAGE_PROVIDER), plus a manual backfill/GC job that sweeps derivatives orphaned by a forget/tenant-destroy that ran before #2461 wired binary cleanup into those flows. Requires `tenant-lifecycle`, optionalRequires `files`.",
+    );
+    r.uiHints({
+      displayLabel: "Files · Tenant-Destroy & Derivative GC",
+      category: "compliance",
+      recommended: false,
+    });
+    r.requires("tenant-lifecycle");
+    r.optionalRequires("files");
+
+    r.useExtension(EXT_TENANT_DATA, "fileRef", { destroy: fileRefTenantDestroyHook });
+    r.useExtension(EXT_STORAGE_PROVIDER, "fileRef", { destroyTenant: fileRefStorageDestroyHook });
+
+    r.job(
+      "sweep-orphaned-derivatives",
+      {
+        trigger: { manual: true },
+        concurrency: "skip",
+        schema: sweepOrphanedDerivativesPayloadSchema,
+      },
+      sweepOrphanedDerivativesJob,
+    );
+  });
+}
+
+export {
+  sweepOrphanedDerivativesJob,
+  sweepOrphanedDerivativesPayloadSchema,
+} from "./handlers/sweep-orphaned-derivatives.job";
+export { fileRefStorageDestroyHook, fileRefTenantDestroyHook } from "./hooks";

package/src/form-draft/db/queries/cleanup.ts

@@ -53,3 +53,20 @@ export async function selectStaleDraftsBatch(
     insertedAt: Temporal.Instant.fromEpochMilliseconds(+row.inserted_at), // @cast-boundary db-row
   }));
 }
+
+/** Re-check staleness after the select→release window so a freshly saved draft is not deleted. */
+export async function isDraftStillStale(
+  db: DbConnection,
+  id: string,
+  olderThanDays: number,
+): Promise<boolean> {
+  const rows = (await unsafeReadRetrying(
+    db,
+    `SELECT 1 FROM "read_form_drafts"
+     WHERE "id" = $1
+       AND COALESCE("modified_at", "inserted_at") < now() - ($2::int * interval '1 day')
+     LIMIT 1`,
+    [id, olderThanDays],
+  )) as readonly unknown[];
+  return rows.length > 0;
+}

package/src/form-draft/handlers/cleanup.job.ts

@@ -24,7 +24,11 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
 import { fileRefEntity, fileRefsTable } from "@cosmicdrift/kumiko-framework/files";
-import { type StaleDraftRow, selectStaleDraftsBatch } from "../db/queries/cleanup";
+import {
+  isDraftStillStale,
+  type StaleDraftRow,
+  selectStaleDraftsBatch,
+} from "../db/queries/cleanup";
 import { filterOwnedFileRefs } from "../db/queries/owned-file-refs";
 import { formDraftExecutor } from "../executor";
 import { collectDraftFileRefKeys, releaseDraftFileRefs } from "../release-file-refs";
@@ -121,16 +125,21 @@ export function groupStaleDraftIdsByTenant(
 async function deleteStaleDraftsBatch(
   batch: readonly StaleDraftRow[],
   db: DbConnection,
+  retentionDays: number,
   log: AppContext["log"],
-): Promise<number> {
-  let deleted = 0;
+): Promise<readonly StaleDraftRow[]> {
+  const deletedRows: StaleDraftRow[] = [];
+  const byId = new Map(batch.map((row) => [row.id, row]));
   for (const [tenantId, ids] of groupStaleDraftIdsByTenant(batch)) {
     const systemUser = createSystemUser(tenantId);
     const tenantDb = createTenantDb(db, tenantId, "system");
     for (const id of ids) {
+      // Race: user may have saved between select and here — skip if no longer stale.
+      if (!(await isDraftStillStale(db, id, retentionDays))) continue;
       const result = await formDraftExecutor.delete({ id }, systemUser, tenantDb);
       if (result.isSuccess) {
-        deleted++;
+        const row = byId.get(id);
+        if (row) deletedRows.push(row);
       } else {
         log?.warn?.(
           `[form-draft:cleanup] failed to delete stale draft id=${id} tenant=${tenantId}: ${result.error.message}`,
@@ -138,7 +147,7 @@ async function deleteStaleDraftsBatch(
       }
     }
   }
-  return deleted;
+  return deletedRows;
 }
 
 export const cleanupDraftsJob: JobHandlerFn = async (_payload, ctx) => {
@@ -182,13 +191,14 @@ export const cleanupDraftsJob: JobHandlerFn = async (_payload, ctx) => {
     // tenant per job run and would be wrong here, so each row resolves its
     // own tenant's provider via _fileProviderResolver instead. Skipped
     // entirely for rows with no FileRefs in the blob, the common case.
-    for (const row of batch) {
+    // Delete first (with staleness re-check), then release binaries from rows
+    // that actually disappeared — never release a draft the user just saved.
+    const deletedRows = await deleteStaleDraftsBatch(batch, db, retentionDays, ctx.log);
+    for (const row of deletedRows) {
       await releaseRowFileRefs(row, db, fileProviderResolver, ctx.log);
     }
-
-    const batchDeleted = await deleteStaleDraftsBatch(batch, db, ctx.log);
-    deleted += batchDeleted;
-    if (batchDeleted === 0 || batch.length < DEFAULT_BATCH_SIZE) break;
+    deleted += deletedRows.length;
+    if (deletedRows.length === 0 || batch.length < DEFAULT_BATCH_SIZE) break;
   }
   ctx.log?.info?.(`[form-draft:cleanup] deleted=${deleted} retentionDays=${retentionDays}`);
 };

package/src/form-draft/handlers/discard.write.ts

@@ -74,13 +74,31 @@ export const discardDraftWrite = defineWriteHandler({
         const forgetResult = await fileRefExecutor.forget({ id: ref.id }, event.user, ctx.db);
         if (!forgetResult.isSuccess) return forgetResult;
       }
-      await releaseDraftFileRefs(
-        ownedRefs.map((ref) => ref.storageKey),
-        async (key) => {
-          await files.ref(key).delete();
-        },
-        ctx.log,
-      );
+      // Binary delete only after commit — in-tx delete would orphan pointers
+      // if the surrounding write transaction rolls back after this handler.
+      const keys = ownedRefs.map((ref) => ref.storageKey);
+      const log = ctx.log;
+      const schedule = ctx.scheduleAfterCommit;
+      if (schedule) {
+        schedule(async () => {
+          await releaseDraftFileRefs(
+            keys,
+            async (key) => {
+              await files.ref(key).delete();
+            },
+            log,
+          );
+        });
+      } else {
+        // Unit/harness paths without a commit sink — best-effort inline.
+        await releaseDraftFileRefs(
+          keys,
+          async (key) => {
+            await files.ref(key).delete();
+          },
+          log,
+        );
+      }
     }
     return { isSuccess: true as const, data: { discarded: true } };
   },

package/src/form-draft/handlers/get.query.ts

@@ -2,7 +2,7 @@ import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { FORM_DRAFT_ACCESS } from "../constants";
 import { lookupDraft } from "../lookup";
 import type { FormDraftBlob } from "../schemas";
-import { getDraftPayloadSchema } from "../schemas";
+import { formDraftBlobSchema, getDraftPayloadSchema } from "../schemas";
 
 export type GetDraftResult = { readonly draft: FormDraftBlob | null };
 
@@ -21,6 +21,8 @@ export const getDraftQuery = defineQueryHandler({
       query.user.id,
       query.payload.draftKey,
     );
-    return { draft: row?.draft ?? null };
+    if (!row) return { draft: null };
+    const parsed = formDraftBlobSchema.safeParse(row.draft);
+    return { draft: parsed.success ? parsed.data : null };
   },
 });

package/src/form-draft/handlers/list.query.ts

@@ -43,7 +43,10 @@ export const listDraftsQuery = defineQueryHandler({
         stepIndex: row.draft.stepIndex,
         savedAt: row.draft.savedAt,
       }))
-      .sort(byNewestFirst);
+      .sort(byNewestFirst)
+      // Matches listDraftsByScreen selectMany limit — JS sort cannot push the
+      // ceiling into SQL while savedAt lives inside jsonb.
+      .slice(0, 200);
     return { drafts };
   },
 });

package/src/form-draft/lookup.ts

@@ -47,9 +47,16 @@ export async function listDraftsByScreen(
   ownerId: string,
   screenId: string,
 ): Promise<readonly FormDraftSummaryRow[]> {
-  return selectMany<FormDraftSummaryRow>(db, formDraftTable, {
-    tenantId,
-    ownerId,
-    draftKey: { like: `${escapeLikePattern(screenId)}:%` },
-  });
+  // ponytail: hard cap — savedAt lives in jsonb so SQL ORDER BY+LIMIT is wrong;
+  // promote savedAt to a column when callers need correct newest-N under the ceiling.
+  return selectMany<FormDraftSummaryRow>(
+    db,
+    formDraftTable,
+    {
+      tenantId,
+      ownerId,
+      draftKey: { like: `${escapeLikePattern(screenId)}:%` },
+    },
+    { limit: 200 },
+  );
 }

package/src/inbound-mail-foundation/watch-supervisor.ts

@@ -127,6 +127,10 @@ type WatcherState = {
    *  watch lease; null when unclaimed (no `deps.lock`, or claim lost). */
   lockToken: string | null;
   renewTimer: ReturnType<typeof setTimeout> | null;
+  /** Consecutive renew() throws — tear down once failures span a full TTL. */
+  renewFailures: number;
+  /** True while plugin.watch() is in flight (re-entrancy guard). */
+  starting: boolean;
 };
 
 type WatchLeaseResult = "acquired" | "no-token" | "stale";
@@ -386,12 +390,14 @@ export function createInboundMailSupervisor(
   // lifecycle — it keeps renewing across reconnect backoff, not just while
   // `plugin.watch()` is actually connected, so a flaky IMAP link doesn't
   // make this worker lose the account to a peer mid-backoff.
+  // kumiko-lint-ignore complexity-budget watch lease renew backoff/re-acquire loop
   function scheduleRenew(
     account: MailAccountRecord,
     state: WatcherState,
     generation: number,
   ): void {
     state.renewTimer = setTimeout(() => {
+      // kumiko-lint-ignore complexity-budget renew timer callback (renew/backoff/re-acquire)
       void (async () => {
         state.renewTimer = null;
         // skip: supervisor stopped, generation superseded, or lease already lost — stale timer fire, nothing to renew.
@@ -403,14 +409,25 @@ export function createInboundMailSupervisor(
           log(
             `inbound-mail: watch lease renew for account ${account.id} failed: ${err instanceof Error ? err.message : String(err)}`,
           );
-          // Treat a renew error as transient (Redis blip) — keep the local
-          // watcher running and retry next tick within the TTL grace window.
+          state.renewFailures += 1;
+          // After failures spanning a full lease TTL, tear down — otherwise a
+          // peer can acquire the expired key while we still hold an IDLE conn.
+          if (state.renewFailures * renewIntervalMs >= leaseTtlSeconds * 1000) {
+            log(
+              `inbound-mail: watch lease renew for account ${account.id} failed across TTL — tearing down local watcher`,
+            );
+            state.lockToken = null;
+            await stopWatcher(account.id);
+            // skip: local watcher torn down after renew failures spanning a full lease TTL.
+            return;
+          }
           if (running && state.generation === generation && state.lockToken) {
             scheduleRenew(account, state, generation);
           }
           // skip: renew already rescheduled above (or conditions no longer hold) — nothing left to do this tick.
           return;
         }
+        state.renewFailures = 0;
         if (!renewed) {
           log(
             `inbound-mail: watch lease for account ${account.id} lost — tearing down local watcher`,
@@ -427,6 +444,7 @@ export function createInboundMailSupervisor(
     }, renewIntervalMs);
   }
 
+  // kumiko-lint-ignore complexity-budget yield-point stale-map check after acquire is intentional (#2460)
   async function acquireWatchLease(
     account: MailAccountRecord,
     state: WatcherState,
@@ -448,6 +466,7 @@ export function createInboundMailSupervisor(
     return "acquired";
   }
 
+  // kumiko-lint-ignore complexity-budget watch lifecycle (start/stop/restart) stays cohesive
   async function ensureWatcher(
     account: MailAccountRecord,
     plugin: InboundMailProviderPlugin,
@@ -455,8 +474,8 @@ export function createInboundMailSupervisor(
     // skip: Provider ohne Live-Push — der Reconciliation-Poll deckt den Account ab.
     if (!plugin.watch) return;
     const existing = watchers.get(account.id);
-    // skip: Watcher läuft bereits bzw. Restart ist geplant — nichts zu tun.
-    if (existing?.stop || existing?.restartTimer) return;
+    // skip: Watcher läuft bereits, startet gerade, oder Restart ist geplant.
+    if (existing?.stop || existing?.restartTimer || existing?.starting) return;
 
     const state: WatcherState = existing ?? {
       stop: null,
@@ -465,6 +484,8 @@ export function createInboundMailSupervisor(
       generation: 0,
       lockToken: null,
       renewTimer: null,
+      renewFailures: 0,
+      starting: false,
     };
     watchers.set(account.id, state);
 
@@ -501,6 +522,7 @@ export function createInboundMailSupervisor(
       }, delay);
     };
 
+    state.starting = true;
     try {
       const stop = await plugin.watch(deps.providerCtx, account, {
         onMessages: async (msgs) => {
@@ -545,6 +567,8 @@ export function createInboundMailSupervisor(
     } catch (err) {
       const keepRunning = await handleSyncError(account, err);
       if (keepRunning) scheduleRestart(err);
+    } finally {
+      state.starting = false;
     }
   }