@cosmicdrift/kumiko-bundled-features 0.211.0 → 0.213.0

package/src/custom-fields/handlers/delete-tenant-field.write.ts

@@ -1,6 +1,9 @@
 import { isSystemTenant, type WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import { fieldDefinitionAggregateId } from "../aggregate-id";
-import { FIELD_DEFINITION_AGGREGATE_TYPE } from "../constants";
+import {
+  DEFAULT_FIELD_DEFINITION_WRITE_ROLES,
+  FIELD_DEFINITION_AGGREGATE_TYPE,
+} from "../constants";
 import { fieldDefinitionExecutor } from "../executor";
 import { customFieldsFeature } from "../feature";
 import { type DeleteFieldPayload, deleteFieldPayloadSchema } from "../schemas";
@@ -15,36 +18,54 @@ import { type DeleteFieldPayload, deleteFieldPayloadSchema } from "../schemas";
 // **Idempotency:** Delete auf nicht-existente Definition → version_conflict
 // (executor.delete returns failure, dispatcher 404/422). Caller sieht "not
 // found" — kein Crash.
-export const deleteTenantFieldHandler: WriteHandlerDef = {
-  name: "delete-tenant-field",
-  schema: deleteFieldPayloadSchema,
-  access: { roles: ["TenantAdmin"] },
-  handler: async (event, ctx) => {
-    const payload = event.payload as DeleteFieldPayload; // @cast-boundary engine-payload
-    const tenantId = event.user.tenantId;
-
-    if (isSystemTenant(tenantId)) {
-      throw new Error(
-        "delete-tenant-field: tenantId is SYSTEM_TENANT_ID — use delete-system-field for system-scope deletions",
+export interface DeleteTenantFieldOptions {
+  /** Access roles for this handler. Default ["TenantAdmin"] (#2296) — see
+   *  DefineTenantFieldOptions.roles, the definition-CRUD triad shares one gate. */
+  readonly roles?: readonly string[];
+}
+
+export function createDeleteTenantFieldHandler(
+  opts: DeleteTenantFieldOptions = {},
+): WriteHandlerDef {
+  return {
+    name: "delete-tenant-field",
+    schema: deleteFieldPayloadSchema,
+    access: { roles: opts.roles ?? DEFAULT_FIELD_DEFINITION_WRITE_ROLES },
+    handler: async (event, ctx) => {
+      const payload = event.payload as DeleteFieldPayload; // @cast-boundary engine-payload
+      const tenantId = event.user.tenantId;
+
+      if (isSystemTenant(tenantId)) {
+        throw new Error(
+          "delete-tenant-field: tenantId is SYSTEM_TENANT_ID — use delete-system-field for system-scope deletions",
+        );
+      }
+
+      const aggregateId = fieldDefinitionAggregateId(
+        tenantId,
+        payload.entityName,
+        payload.fieldKey,
       );
-    }
-
-    const aggregateId = fieldDefinitionAggregateId(tenantId, payload.entityName, payload.fieldKey);
-
-    const result = await fieldDefinitionExecutor.delete({ id: aggregateId }, event.user, ctx.db);
-
-    // Emit cascade-cleanup-Event NACH erfolgreichem Delete. host-entity-MSPs
-    // (registriert via wireCustomFieldsFor) konsumieren das + entfernen orphan
-    // values aus ihrer customFields jsonb. Im selben TX = atomic cleanup.
-    if (result.isSuccess) {
-      await ctx.unsafeAppendEvent({
-        aggregateId,
-        aggregateType: FIELD_DEFINITION_AGGREGATE_TYPE,
-        type: customFieldsFeature.exports.fieldDefinitionDeletedEvent.name,
-        payload: { entityName: payload.entityName, fieldKey: payload.fieldKey, tenantId },
-      });
-    }
-
-    return result;
-  },
-};
+
+      const result = await fieldDefinitionExecutor.delete({ id: aggregateId }, event.user, ctx.db);
+
+      // Emit cascade-cleanup-Event NACH erfolgreichem Delete. host-entity-MSPs
+      // (registriert via wireCustomFieldsFor) konsumieren das + entfernen orphan
+      // values aus ihrer customFields jsonb. Im selben TX = atomic cleanup.
+      if (result.isSuccess) {
+        await ctx.unsafeAppendEvent({
+          aggregateId,
+          aggregateType: FIELD_DEFINITION_AGGREGATE_TYPE,
+          type: customFieldsFeature.exports.fieldDefinitionDeletedEvent.name,
+          payload: { entityName: payload.entityName, fieldKey: payload.fieldKey, tenantId },
+        });
+      }
+
+      return result;
+    },
+  };
+}
+
+// Backwards-compat: existing imports of `deleteTenantFieldHandler` keep
+// working — identical to createDeleteTenantFieldHandler() with default roles.
+export const deleteTenantFieldHandler: WriteHandlerDef = createDeleteTenantFieldHandler();

package/src/custom-fields/handlers/update-tenant-field.write.ts

@@ -1,6 +1,7 @@
 import { isSystemTenant, type WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import { failNotFound, failUnprocessable } from "@cosmicdrift/kumiko-framework/errors";
 import { fieldDefinitionAggregateId } from "../aggregate-id";
+import { DEFAULT_FIELD_DEFINITION_WRITE_ROLES } from "../constants";
 import { fieldDefinitionExecutor } from "../executor";
 import { buildFieldDefinitionColumns } from "../lib/field-definition-row";
 import { type UpdateFieldPayload, updateFieldPayloadSchema } from "../schemas";
@@ -29,45 +30,67 @@ import { type UpdateFieldPayload, updateFieldPayloadSchema } from "../schemas";
 // **skipOptimisticLock:** Definition-Edits sind admin-only + low-frequency
 // (gleiche Abwägung wie der Quota-soft-cap in define). Last-write-wins
 // statt version-Roundtrip durch den Edit-Screen.
-export const updateTenantFieldHandler: WriteHandlerDef = {
-  name: "update-tenant-field",
-  schema: updateFieldPayloadSchema,
-  access: { roles: ["TenantAdmin"] },
-  handler: async (event, ctx) => {
-    const payload = event.payload as UpdateFieldPayload; // @cast-boundary engine-payload
-    const tenantId = event.user.tenantId;
+export interface UpdateTenantFieldOptions {
+  /** Access roles for this handler. Default ["TenantAdmin"] (#2296) — see
+   *  DefineTenantFieldOptions.roles, the definition-CRUD triad shares one gate. */
+  readonly roles?: readonly string[];
+}
 
-    if (isSystemTenant(tenantId)) {
-      throw new Error(
-        "update-tenant-field: tenantId is SYSTEM_TENANT_ID — system-scope definitions have no update handler (delete + re-define via the system-field handlers)",
+export function createUpdateTenantFieldHandler(
+  opts: UpdateTenantFieldOptions = {},
+): WriteHandlerDef {
+  return {
+    name: "update-tenant-field",
+    schema: updateFieldPayloadSchema,
+    access: { roles: opts.roles ?? DEFAULT_FIELD_DEFINITION_WRITE_ROLES },
+    handler: async (event, ctx) => {
+      const payload = event.payload as UpdateFieldPayload; // @cast-boundary engine-payload
+      const tenantId = event.user.tenantId;
+
+      if (isSystemTenant(tenantId)) {
+        throw new Error(
+          "update-tenant-field: tenantId is SYSTEM_TENANT_ID — system-scope definitions have no update handler (delete + re-define via the system-field handlers)",
+        );
+      }
+
+      const aggregateId = fieldDefinitionAggregateId(
+        tenantId,
+        payload.entityName,
+        payload.fieldKey,
       );
-    }
 
-    const aggregateId = fieldDefinitionAggregateId(tenantId, payload.entityName, payload.fieldKey);
+      const existing = await fieldDefinitionExecutor.detail(
+        { id: aggregateId },
+        event.user,
+        ctx.db,
+      );
+      if (!existing) {
+        return failNotFound("field-definition", aggregateId);
+      }
 
-    const existing = await fieldDefinitionExecutor.detail({ id: aggregateId }, event.user, ctx.db);
-    if (!existing) {
-      return failNotFound("field-definition", aggregateId);
-    }
+      if (existing["type"] !== payload.serializedField.type) {
+        return failUnprocessable("field_type_immutable", {
+          entityName: payload.entityName,
+          fieldKey: payload.fieldKey,
+          currentType: existing["type"],
+          requestedType: payload.serializedField.type,
+        });
+      }
 
-    if (existing["type"] !== payload.serializedField.type) {
-      return failUnprocessable("field_type_immutable", {
-        entityName: payload.entityName,
-        fieldKey: payload.fieldKey,
-        currentType: existing["type"],
-        requestedType: payload.serializedField.type,
-      });
-    }
+      // entityName/fieldKey sind die Identität — nicht Teil der changes.
+      const {
+        entityName: _entityName,
+        fieldKey: _fieldKey,
+        ...changes
+      } = buildFieldDefinitionColumns(payload);
 
-    // entityName/fieldKey sind die Identität — nicht Teil der changes.
-    const {
-      entityName: _entityName,
-      fieldKey: _fieldKey,
-      ...changes
-    } = buildFieldDefinitionColumns(payload);
+      return fieldDefinitionExecutor.update({ id: aggregateId, changes }, event.user, ctx.db, {
+        skipOptimisticLock: true,
+      });
+    },
+  };
+}
 
-    return fieldDefinitionExecutor.update({ id: aggregateId, changes }, event.user, ctx.db, {
-      skipOptimisticLock: true,
-    });
-  },
-};
+// Backwards-compat: existing imports of `updateTenantFieldHandler` keep
+// working — identical to createUpdateTenantFieldHandler() with default roles.
+export const updateTenantFieldHandler: WriteHandlerDef = createUpdateTenantFieldHandler();

package/src/delivery/feature.ts

@@ -163,9 +163,7 @@ export function createDeliveryFeature(options?: DeliveryFeatureOptions): Feature
     r.nav({
       id: "delivery-log",
       label: "delivery:nav.deliveryLog",
-      // "send" isn't in the closed NavIconKey vocabulary (packages/types/src/
-      // nav-icon.ts) — "bell" matches the feature's own notifications framing.
-      icon: "bell",
+      icon: "send",
       screen: "delivery:screen:delivery-log",
       order: 40,
     });

package/src/feature-toggles/feature.ts

@@ -67,6 +67,7 @@ export function createFeatureTogglesFeature(
       registered: r.queryHandler(registeredQuery),
     };
 
+    // kumiko-lint-ignore app-feature-structure Phase-3 conversion tracked in #2312
     r.screen({
       id: TOGGLE_ADMIN_SCREEN_ID,
       type: "custom",

package/src/feature-toggles/web/toggle-admin-screen.tsx

@@ -38,6 +38,7 @@ export function ToggleAdminScreen(): ReactNode {
     setState({ kind: "ready", items: res.data.items });
   }, [dispatcher]);
 
+  // kumiko-lint-ignore no-raw-hooks Phase-3 conversion tracked in #2312
   useEffect(() => {
     void load();
   }, [load]);

package/src/folders/web/folder-manager.tsx

@@ -108,6 +108,7 @@ export function FolderManager({
   const [pendingDelete, setPendingDelete] = useState<FolderNode | null>(null);
 
   // Persist expand/collapse so a reload (F5) doesn't re-expand everything.
+  // kumiko-lint-ignore no-raw-hooks DOM integration: writes to window.localStorage, no framework query/mutation equivalent
   useEffect(() => {
     if (typeof window === "undefined") return;
     try {

package/src/inbound-mail-foundation/__tests__/watch-supervisor.integration.test.ts

@@ -10,6 +10,7 @@ import { configurePiiSubjectKms, InMemoryKmsAdapter } from "@cosmicdrift/kumiko-
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import { createSystemUser, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { createEventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import { createDistributedLock } from "@cosmicdrift/kumiko-framework/pipeline";
 import {
   createTestUser,
   setupTestStack,
@@ -429,3 +430,143 @@ describe("watch-supervisor — watch restart + ingest resilience", () => {
     }
   });
 });
+
+describe("watch-supervisor — multi-worker watch coordination (#1719)", () => {
+  // Counts only watch-path ingests (payload.providerCursor === "watch") —
+  // the reconciliation poll is deliberately N-fold (every worker polls
+  // every account) and would otherwise inflate this count regardless of
+  // which worker actually holds the watch lease.
+  function makeWatchIngestCounter() {
+    let count = 0;
+    const dispatchWrite = ({
+      handlerQn,
+      payload,
+      tenantId,
+    }: {
+      handlerQn: string;
+      payload: unknown;
+      tenantId: string;
+    }) => {
+      if (handlerQn === InboundMailFoundationHandlers.ingestMessage) {
+        const cursor = (payload as { providerCursor?: string }).providerCursor;
+        if (cursor === "watch") count += 1;
+      }
+      return stack.dispatcher.write(
+        handlerQn,
+        payload,
+        createSystemUser(tenantId as TenantId, [ROLES.SystemAdmin]),
+      );
+    };
+    return { dispatchWrite, watchIngestCount: () => count };
+  }
+
+  test("only one supervisor holds the watch lease; the peer takes over after stop()", async () => {
+    const admin = adminFor(4200);
+    const accountId = await connectSharedAccount(admin);
+    const lock = createDistributedLock(stack.redis.redis, "test-watch-lease:");
+    const a = makeWatchIngestCounter();
+    const b = makeWatchIngestCounter();
+    const supervisorA = createInboundMailSupervisor({
+      providerCtx: { registry: stack.registry },
+      db,
+      dispatchWrite: a.dispatchWrite,
+      lock,
+      watchLeaseTtlSeconds: 5,
+      pollIntervalMs: 60_000,
+    });
+    const supervisorB = createInboundMailSupervisor({
+      providerCtx: { registry: stack.registry },
+      db,
+      dispatchWrite: b.dispatchWrite,
+      lock,
+      watchLeaseTtlSeconds: 5,
+      pollIntervalMs: 60_000,
+    });
+
+    try {
+      await supervisorA.start();
+      await waitFor(() => {
+        expect(isWatching(accountId)).toBe(true);
+      });
+
+      // B's own start() polls too (poll stays N-fold by design) but must
+      // not claim the watch lease — A already holds it.
+      await supervisorB.start();
+
+      await seedInboundMessage(accountId, rawMsg({ providerMessageId: "mw-1" }));
+      await waitFor(() => {
+        expect(a.watchIngestCount()).toBe(1);
+      });
+      expect(b.watchIngestCount()).toBe(0);
+
+      await supervisorA.stop();
+      expect(isWatching(accountId)).toBe(false);
+
+      await supervisorB.pollOnce();
+      await waitFor(() => {
+        expect(isWatching(accountId)).toBe(true);
+      });
+
+      await seedInboundMessage(accountId, rawMsg({ providerMessageId: "mw-2" }));
+      await waitFor(() => {
+        expect(b.watchIngestCount()).toBe(1);
+      });
+      expect(a.watchIngestCount()).toBe(1);
+    } finally {
+      await supervisorA.stop();
+      await supervisorB.stop();
+    }
+  });
+
+  test("the holder renews its lease past the TTL — the peer still can't claim it", async () => {
+    const admin = adminFor(4201);
+    const accountId = await connectSharedAccount(admin);
+    const lock = createDistributedLock(stack.redis.redis, "test-watch-lease-renew:");
+    const a = makeWatchIngestCounter();
+    const b = makeWatchIngestCounter();
+    const supervisorA = createInboundMailSupervisor({
+      providerCtx: { registry: stack.registry },
+      db,
+      dispatchWrite: a.dispatchWrite,
+      lock,
+      watchLeaseTtlSeconds: 1,
+      pollIntervalMs: 60_000,
+    });
+    const supervisorB = createInboundMailSupervisor({
+      providerCtx: { registry: stack.registry },
+      db,
+      dispatchWrite: b.dispatchWrite,
+      lock,
+      watchLeaseTtlSeconds: 1,
+      pollIntervalMs: 60_000,
+    });
+
+    try {
+      await supervisorA.start();
+      await waitFor(() => {
+        expect(isWatching(accountId)).toBe(true);
+      });
+
+      // 2.5x the 1s TTL: long enough that a dead heartbeat guarantees the
+      // key expired (1.5x left this indistinguishable from Redis's
+      // second-granularity EX not having rolled over yet).
+      await new Promise((r) => setTimeout(r, 2500));
+
+      // Direct probe of the invariant: the lease itself must still be held,
+      // independent of B's behavior below (which only infers it indirectly).
+      expect(await lock.acquire(accountId, { ttlSeconds: 1 })).toBeNull();
+
+      await supervisorB.start();
+      expect(isWatching(accountId)).toBe(true);
+
+      await seedInboundMessage(accountId, rawMsg({ providerMessageId: "mw-renew-1" }));
+      await waitFor(() => {
+        expect(a.watchIngestCount()).toBe(1);
+      });
+      expect(b.watchIngestCount()).toBe(0);
+    } finally {
+      await supervisorA.stop();
+      await supervisorB.stop();
+    }
+  });
+});

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

@@ -5,27 +5,44 @@
 // Dedup im ingest-Handler macht Watch/Poll-Überschneidung idempotent —
 // der Poll ist Korrektheits-Anker, watch nur Latenz-Optimierung.
 //
-// **Plan-Abweichung (dokumentiert):** Der Plan sah den Poll als
-// `r.job`-Cron vor. JobContext hat aber KEINEN Dispatcher (verifiziert:
-// run-export-jobs.ts "Worker-AppContext hat kein queryAs/write") — der
-// ingest MUSS durch den Standard-Write-Handler (ES-Executor, PII,
-// Idempotency). Deshalb ist der Supervisor eine app-verdrahtete
-// Komponente mit `dispatchSystemWrite` in den Deps, exakt wie
-// billing-foundation's webhook-handler. Der App-Owner startet ihn in
-// bin/server.ts:
+// **Plan deviation (documented):** the plan had the poll as an `r.job`
+// cron trigger. At the time this was written, JobContext had no
+// dispatcher (verified against run-export-jobs.ts). It now does
+// (`ctx.write`/`ctx.queryAs`, job-runner.ts) — but converting the poll to
+// a cron job is a separate migration (job concurrency instead of this
+// dispatcher contract), not part of #1719, and stays untouched here. The
+// app owner still wires the supervisor in bin/server.ts:
 //
 //   const supervisor = createInboundMailSupervisor({
 //     providerCtx: { registry: deps.registry, secrets },
 //     db,
 //     dispatchWrite: ({ handlerQn, payload, tenantId }) =>
 //       deps.dispatchSystemWrite({ handlerQn, payload, tenantId: tenantId as TenantId }),
+//     // Multi-worker deployments: share one DistributedLock (same Redis,
+//     // same key prefix) across every worker process so only one of them
+//     // holds the IMAP IDLE connection per account (#1719). Omit `lock`
+//     // for a single-process deployment — every active account gets
+//     // watched locally, same as before.
+//     lock: createDistributedLock(redis, `${RedisKeys.lock}inbound-mail:watch:`),
 //   });
 //   await supervisor.start();
 //   // shutdown-hook: await supervisor.stop();
 //
-// **Betriebsrisiko IDLE (Plan §7.3):** langlebige Sockets im Prozess.
-// Mitigation hier: Backoff-Restart via onError, sauberes stop() aller
-// Watcher beim Shutdown, Poll fängt jede Lücke.
+// **IDLE operational risk (plan §7.3):** long-lived sockets in-process.
+// Mitigated here via backoff-restart on onError, a clean stop() of every
+// watcher on shutdown, and the poll covering every gap.
+//
+// **Multi-worker coordination (#1719):** the reconciliation poll stays
+// deliberately N-fold — every worker polls every active account, which
+// is idempotent and cheap. Only `plugin.watch()` holds a long-lived
+// connection, and only one worker may hold it per account. With
+// `deps.lock`, `ensureWatcher` claims a TTL lease (`lock.acquire`) for
+// the account before connecting; a worker that doesn't get it leaves the
+// account to its current holder — the poll still covers it. The holder
+// renews the claim via heartbeat (`lock.renew`, every ttl/3) for as long
+// as the watcher state lives, including across reconnect backoff, not
+// only while the connection is open. Losing the claim (Redis outage, TTL
+// exceeded) tears down the local watcher instead of racing a new holder.
 
 import { fetchOne, insertOne, selectMany, updateMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import {
@@ -33,6 +50,7 @@ import {
   decryptPiiFieldValues,
 } from "@cosmicdrift/kumiko-framework/crypto";
 import type { DbConnection, EntityTableMeta } from "@cosmicdrift/kumiko-framework/db";
+import type { DistributedLock } from "@cosmicdrift/kumiko-framework/pipeline";
 import { Temporal } from "temporal-polyfill";
 import { InboundMailAccountStatuses, InboundMailFoundationHandlers } from "./constants";
 import { MAIL_ACCOUNT_PII_FIELDS, syncCursorTable } from "./entities";
@@ -54,6 +72,7 @@ const DEFAULT_BACKFILL_WINDOW_DAYS = 30;
 const DEFAULT_MAX_MESSAGES_PER_POLL = 200;
 const DEFAULT_WATCH_BACKOFF_INITIAL_MS = 5_000;
 const DEFAULT_WATCH_BACKOFF_MAX_MS = 5 * 60 * 1000;
+const DEFAULT_WATCH_LEASE_TTL_SECONDS = 90;
 /** V1: ein Cursor pro Account (eine Mailbox-Inbox). Multi-Folder später
  *  über weitere scopes ohne Schema-Änderung. */
 const CURSOR_SCOPE = "default";
@@ -85,6 +104,15 @@ export type InboundMailSupervisorDeps = {
   readonly maxMessagesPerPoll?: number;
   readonly watchBackoffInitialMs?: number;
   readonly watchBackoffMaxMs?: number;
+  /** Coordinates the IMAP watch (not the poll) across worker processes:
+   *  before `plugin.watch()`, ensureWatcher claims a TTL lease for the
+   *  account via `lock.acquire` and renews it via `lock.renew` while the
+   *  watcher lives. Omit for single-process deployments — every active
+   *  account is watched locally, same as before #1719. */
+  readonly lock?: DistributedLock;
+  /** TTL (seconds) for the per-account watch lease. Default 90s, renewed
+   *  every ttl/3. Only used when `lock` is set. */
+  readonly watchLeaseTtlSeconds?: number;
   readonly log?: (line: string) => void;
 };
 
@@ -95,8 +123,14 @@ type WatcherState = {
   /** Bump beim stop() — verhindert dass ein nachzügelnder Restart einen
    *  bereits gestoppten Watcher wiederbelebt. */
   generation: number;
+  /** Token from `deps.lock.acquire` while this worker owns the account's
+   *  watch lease; null when unclaimed (no `deps.lock`, or claim lost). */
+  lockToken: string | null;
+  renewTimer: ReturnType<typeof setTimeout> | null;
 };
 
+type WatchLeaseResult = "acquired" | "no-token" | "stale";
+
 export type InboundMailSupervisor = {
   readonly start: () => Promise<void>;
   /** Ein Reconciliation-Durchlauf über alle aktiven Accounts — auch
@@ -113,6 +147,11 @@ export function createInboundMailSupervisor(
   const maxMessagesPerPoll = deps.maxMessagesPerPoll ?? DEFAULT_MAX_MESSAGES_PER_POLL;
   const backoffInitialMs = deps.watchBackoffInitialMs ?? DEFAULT_WATCH_BACKOFF_INITIAL_MS;
   const backoffMaxMs = deps.watchBackoffMaxMs ?? DEFAULT_WATCH_BACKOFF_MAX_MS;
+  const leaseTtlSeconds = deps.watchLeaseTtlSeconds ?? DEFAULT_WATCH_LEASE_TTL_SECONDS;
+  // ttl/3 keeps at least two renewal attempts inside the TTL window before
+  // it lapses. The 50ms floor only guards against a pathologically small
+  // configured TTL — real deployments (default 90s) never hit it.
+  const renewIntervalMs = Math.max(50, Math.floor((leaseTtlSeconds * 1000) / 3));
   const log = deps.log ?? (() => {});
 
   let running = false;
@@ -343,6 +382,72 @@ export function createInboundMailSupervisor(
   // ---------------------------------------------------------------
   // Watch-Lifecycle mit Backoff-Restart.
   // ---------------------------------------------------------------
+  // Heartbeat for a held watch lease. Independent of the connection's own
+  // 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.
+  function scheduleRenew(
+    account: MailAccountRecord,
+    state: WatcherState,
+    generation: number,
+  ): void {
+    state.renewTimer = setTimeout(() => {
+      void (async () => {
+        state.renewTimer = null;
+        // skip: supervisor stopped, generation superseded, or lease already lost — stale timer fire, nothing to renew.
+        if (!running || state.generation !== generation || !state.lockToken || !deps.lock) return;
+        let renewed: boolean;
+        try {
+          renewed = await deps.lock.renew(account.id, state.lockToken, leaseTtlSeconds);
+        } catch (err) {
+          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.
+          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;
+        }
+        if (!renewed) {
+          log(
+            `inbound-mail: watch lease for account ${account.id} lost — tearing down local watcher`,
+          );
+          state.lockToken = null;
+          await stopWatcher(account.id);
+          // skip: watcher already torn down by stopWatcher() above — nothing left to do.
+          return;
+        }
+        if (running && state.generation === generation && state.lockToken) {
+          scheduleRenew(account, state, generation);
+        }
+      })();
+    }, renewIntervalMs);
+  }
+
+  async function acquireWatchLease(
+    account: MailAccountRecord,
+    state: WatcherState,
+  ): Promise<WatchLeaseResult> {
+    if (!deps.lock || state.lockToken) return "acquired";
+    const token = await deps.lock.acquire(account.id, { ttlSeconds: leaseTtlSeconds });
+    if (!token) return "no-token";
+    // The acquire() await is a yield point: a concurrent stopWatcher()
+    // (e.g. from a lost-lease renewal on a different generation) may have
+    // already retired this exact state and removed it from the map. If so,
+    // committing the fresh token onto it would leak the lease — nothing
+    // would ever release it, blocking failover for the full TTL.
+    if (watchers.get(account.id) !== state) {
+      await deps.lock.release(account.id, token);
+      return "stale";
+    }
+    state.lockToken = token;
+    scheduleRenew(account, state, state.generation);
+    return "acquired";
+  }
+
   async function ensureWatcher(
     account: MailAccountRecord,
     plugin: InboundMailProviderPlugin,
@@ -358,8 +463,26 @@ export function createInboundMailSupervisor(
       backoffMs: backoffInitialMs,
       restartTimer: null,
       generation: 0,
+      lockToken: null,
+      renewTimer: null,
     };
     watchers.set(account.id, state);
+
+    const leaseResult = await acquireWatchLease(account, state);
+    if (leaseResult === "no-token") {
+      // Another worker already holds this account's watch lease — the poll
+      // still covers it, this worker just doesn't open a second IDLE
+      // connection. Retried on the next tick.
+      if (!existing) watchers.delete(account.id);
+      // skip: no lease token acquired above — nothing more to set up here.
+      return;
+    }
+    if (leaseResult === "stale") {
+      // skip: state was retired by a concurrent stopWatcher while acquire()
+      // awaited — committing here would leak the lease.
+      return;
+    }
+
     const generation = state.generation;
 
     const scheduleRestart = (err: unknown) => {
@@ -434,8 +557,17 @@ export function createInboundMailSupervisor(
       clearTimeout(state.restartTimer);
       state.restartTimer = null;
     }
+    if (state.renewTimer) {
+      clearTimeout(state.renewTimer);
+      state.renewTimer = null;
+    }
     const stop = state.stop;
     state.stop = null;
+    // Read the token before clearing it: only OUR claim gets released — a
+    // caller that already cleared lockToken (lease-lost path in
+    // scheduleRenew) means someone else may own it by now.
+    const lockToken = state.lockToken;
+    state.lockToken = null;
     watchers.delete(accountId);
     if (stop) {
       try {
@@ -446,6 +578,15 @@ export function createInboundMailSupervisor(
         );
       }
     }
+    if (deps.lock && lockToken) {
+      try {
+        await deps.lock.release(accountId, lockToken);
+      } catch (err) {
+        log(
+          `inbound-mail: watch lease release for account ${accountId} failed: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
   }
 
   // ---------------------------------------------------------------