@cosmicdrift/kumiko-bundled-features 0.212.0 → 0.213.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.212.0",
+  "version": "0.213.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -126,12 +126,12 @@
     "./step-dispatcher": "./src/step-dispatcher/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.212.0",
-    "@cosmicdrift/kumiko-framework": "0.212.0",
-    "@cosmicdrift/kumiko-headless": "0.212.0",
-    "@cosmicdrift/kumiko-renderer": "0.212.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.212.0",
-    "@cosmicdrift/kumiko-types": "0.212.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.213.0",
+    "@cosmicdrift/kumiko-framework": "0.213.0",
+    "@cosmicdrift/kumiko-headless": "0.213.0",
+    "@cosmicdrift/kumiko-renderer": "0.213.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.213.0",
+    "@cosmicdrift/kumiko-types": "0.213.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -160,6 +160,6 @@
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
     "@types/qrcode": "^1.5.5",
-    "@cosmicdrift/kumiko-locale-de": "0.212.0"
+    "@cosmicdrift/kumiko-locale-de": "0.213.0"
   }
 }

package/src/auth-email-password/__tests__/password-reset.integration.test.ts

@@ -3,6 +3,7 @@ import { randomBytes } from "node:crypto";
 import { authFoundationFeature } from "@cosmicdrift/kumiko-bundled-features/auth-foundation";
 import { asRawClient, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { SYSTEM_TENANT_ID, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { registerMailTranslations } from "@cosmicdrift/kumiko-framework/i18n";
 import {
   setupTestStack,
   type TestStack,
@@ -11,6 +12,7 @@ import {
   unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
 import { createTestEnvelopeCipher, seedRow } from "@cosmicdrift/kumiko-framework/testing";
+import { localeDeBundle } from "@cosmicdrift/kumiko-locale-de";
 import { Temporal } from "temporal-polyfill";
 import { createChannelEmailFeature, createInMemoryTransport } from "../../channel-email";
 import { createConfigFeature } from "../../config";
@@ -39,6 +41,13 @@ import { signResetToken } from "../reset-token";
 // directly (no jobRunner in the test stack → inline send).
 const emailTransport = createInMemoryTransport();
 
+// Kept in sync with LOCALE_HEADER_NAME in api-constants.ts by hand — that
+// constant is a framework-internal implementation detail, not exported from
+// the public /api barrel (same as TENANT_HEADER_NAME).
+const LOCALE_HEADER_NAME = "X-Locale";
+
+registerMailTranslations("de", localeDeBundle);
+
 // Records the userId every time the sessions feature's auto-revoke hook
 // fires after a password change. The session-revoke tests assert on this
 // list — we don't need a full session store, just proof the hook fired.
@@ -146,8 +155,12 @@ async function seedUser(opts: {
   return { id: created.id, tenantId };
 }
 
-async function post(path: string, body: unknown): Promise<Response> {
-  return stack.http.raw("POST", path, body);
+async function post(
+  path: string,
+  body: unknown,
+  headers?: Record<string, string>,
+): Promise<Response> {
+  return stack.http.raw("POST", path, body, headers);
 }
 
 // --- request-password-reset -----------------------------------------------
@@ -182,6 +195,22 @@ describe("POST /auth/request-password-reset", () => {
     expect(await res.json()).toEqual({ isSuccess: true });
     expect(emailTransport.sent).toHaveLength(0);
   });
+
+  test("X-Locale: de → the reset mail is rendered in German, same as signup", async () => {
+    await seedUser({ email: "locale-de@example.com", password: "initial-pw!" });
+
+    const res = await post(
+      "/api/auth/request-password-reset",
+      { email: "locale-de@example.com" },
+      { [LOCALE_HEADER_NAME]: "de" },
+    );
+
+    expect(res.status).toBe(200);
+    expect(emailTransport.sent).toHaveLength(1);
+    const sent = emailTransport.sent[0];
+    if (!sent) throw new Error("no email sent");
+    expect(sent.subject).toContain("Passwort zurücksetzen");
+  });
 });
 
 // --- reset-password --------------------------------------------------------

package/src/auth-email-password/__tests__/signup-flow.integration.test.ts

@@ -29,12 +29,14 @@ import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:tes
 import { asRawClient, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { registerMailTranslations } from "@cosmicdrift/kumiko-framework/i18n";
 import {
   setupTestStack,
   type TestStack,
   unsafeCreateEntityTable,
   unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
+import { localeDeBundle } from "@cosmicdrift/kumiko-locale-de";
 import { createChannelEmailFeature, createInMemoryTransport } from "../../channel-email";
 import { createConfigFeature } from "../../config";
 import { createConfigResolver } from "../../config/resolver";
@@ -96,6 +98,13 @@ const tenantMembershipHookVendorFeature = defineFeature(
 
 const APP_ACTIVATION_URL = "https://app.example.com/signup/complete";
 
+// Kept in sync with LOCALE_HEADER_NAME in api-constants.ts by hand — that
+// constant is a framework-internal implementation detail, not exported from
+// the public /api barrel (same as TENANT_HEADER_NAME).
+const LOCALE_HEADER_NAME = "X-Locale";
+
+registerMailTranslations("de", localeDeBundle);
+
 // Activation mails now go through delivery (ctx.notify → channel-email). The
 // in-memory transport captures what would be sent; route:{email} delivers
 // directly (no jobRunner in the test stack → inline send).
@@ -177,8 +186,11 @@ beforeEach(async () => {
   if (allKeys.length > 0) await stack.redis.redis.del(...allKeys);
 });
 
-async function postSignupRequest(email: string): Promise<Response> {
-  return stack.http.raw("POST", "/api/auth/signup-request", { email });
+async function postSignupRequest(
+  email: string,
+  headers?: Record<string, string>,
+): Promise<Response> {
+  return stack.http.raw("POST", "/api/auth/signup-request", { email }, headers);
 }
 
 async function postSignupConfirm(token: string, password: string): Promise<Response> {
@@ -425,3 +437,164 @@ describe("POST /api/auth/signup-confirm", () => {
     expect(userRows).toHaveLength(0);
   });
 });
+
+describe("POST /api/auth/signup-request — mail locale follows the active browser language", () => {
+  // The stack config sets no `signup.locale` (see beforeAll above) — this
+  // isolates ctx.locale as the only possible source, so a German subject
+  // here can only come from the X-Locale header, never from opts.locale.
+  test("X-Locale: de → the activation mail is rendered in German", async () => {
+    const res = await postSignupRequest("locale-de@example.com", { [LOCALE_HEADER_NAME]: "de" });
+    expect(res.status).toBe(200);
+    expect(emailTransport.sent).toHaveLength(1);
+    const sent = emailTransport.sent[0];
+    if (!sent) throw new Error("no mail sent");
+    expect(sent.subject).toContain("Account aktivieren");
+  });
+
+  test("no X-Locale header → the activation mail falls back to English", async () => {
+    const res = await postSignupRequest("locale-default@example.com");
+    expect(res.status).toBe(200);
+    expect(emailTransport.sent).toHaveLength(1);
+    const sent = emailTransport.sent[0];
+    if (!sent) throw new Error("no mail sent");
+    expect(sent.subject).toContain("Activate your account");
+  });
+});
+
+describe("POST /api/auth/signup-request — opts.locale stays a real fallback", () => {
+  // Regression guard: ctx.locale is always resolved (never undefined), so a
+  // naive `ctx.locale ?? opts.locale` would make opts.locale unreachable and
+  // silently drop every app's configured mail language the moment this PR
+  // ships. This stack configures signup.locale statically (no defaultLocale
+  // on the app context either) — a request with no X-Locale header must
+  // still land in the handler's configured language, not "en".
+  const optsLocaleTransport = createInMemoryTransport();
+  let optsLocaleStack: TestStack;
+
+  beforeAll(async () => {
+    optsLocaleStack = await setupTestStack({
+      features: [
+        createConfigFeature(),
+        createUserFeature(),
+        createTenantFeature(),
+        createTemplateResolverFeature(),
+        createRendererFoundationFeature(),
+        createDeliveryFeature(),
+        createRendererSimpleFeature(),
+        createChannelEmailFeature({
+          transport: optsLocaleTransport,
+          renderer: simpleRenderer,
+          resolveEmail: async () => "unused@test.local",
+        }),
+        createAuthEmailPasswordFeature({
+          signup: { tokenTtlMinutes: 60, appUrl: APP_ACTIVATION_URL, locale: "de" },
+        }),
+      ],
+      extraContext: (deps) => ({
+        ...createDeliveryTestContext(deps),
+        configResolver: createConfigResolver(),
+      }),
+      authConfig: {
+        membershipQuery: "tenant:query:memberships",
+        loginHandler: AuthHandlers.login,
+        signup: {
+          requestHandler: AuthHandlers.signupRequest,
+          confirmHandler: AuthHandlers.signupConfirm,
+        },
+      },
+    });
+    await unsafeCreateEntityTable(optsLocaleStack.db, userEntity);
+    await unsafeCreateEntityTable(optsLocaleStack.db, tenantEntity);
+    await unsafePushTables(optsLocaleStack.db, {
+      configValuesTable,
+      tenantMembershipsTable,
+      notificationPreferencesTable,
+    });
+  });
+
+  afterAll(async () => {
+    await optsLocaleStack.cleanup();
+  });
+
+  test("no X-Locale header → falls back to the handler's configured opts.locale, not English", async () => {
+    const res = await optsLocaleStack.http.raw("POST", "/api/auth/signup-request", {
+      email: "opts-locale@example.com",
+    });
+    expect(res.status).toBe(200);
+    expect(optsLocaleTransport.sent).toHaveLength(1);
+    const sent = optsLocaleTransport.sent[0];
+    if (!sent) throw new Error("no mail sent");
+    expect(sent.subject).toContain("Account aktivieren");
+  });
+});
+
+describe("POST /api/auth/signup-request — appUrl as a function picks the activation link's locale", () => {
+  // This is the actual mechanism the whole PR exists for: an app with
+  // language-in-path routing (/de/activate, /en/activate, ...) passes a
+  // function instead of a plain string, and the resolved locale must land
+  // in the link the user actually clicks — not just the mail's language.
+  const appUrlTransport = createInMemoryTransport();
+  let appUrlStack: TestStack;
+
+  beforeAll(async () => {
+    appUrlStack = await setupTestStack({
+      features: [
+        createConfigFeature(),
+        createUserFeature(),
+        createTenantFeature(),
+        createTemplateResolverFeature(),
+        createRendererFoundationFeature(),
+        createDeliveryFeature(),
+        createRendererSimpleFeature(),
+        createChannelEmailFeature({
+          transport: appUrlTransport,
+          renderer: simpleRenderer,
+          resolveEmail: async () => "unused@test.local",
+        }),
+        createAuthEmailPasswordFeature({
+          signup: {
+            tokenTtlMinutes: 60,
+            appUrl: (locale) => `https://app.example.com/${locale}/activate`,
+          },
+        }),
+      ],
+      extraContext: (deps) => ({
+        ...createDeliveryTestContext(deps),
+        configResolver: createConfigResolver(),
+      }),
+      authConfig: {
+        membershipQuery: "tenant:query:memberships",
+        loginHandler: AuthHandlers.login,
+        signup: {
+          requestHandler: AuthHandlers.signupRequest,
+          confirmHandler: AuthHandlers.signupConfirm,
+        },
+      },
+    });
+    await unsafeCreateEntityTable(appUrlStack.db, userEntity);
+    await unsafeCreateEntityTable(appUrlStack.db, tenantEntity);
+    await unsafePushTables(appUrlStack.db, {
+      configValuesTable,
+      tenantMembershipsTable,
+      notificationPreferencesTable,
+    });
+  });
+
+  afterAll(async () => {
+    await appUrlStack.cleanup();
+  });
+
+  test("X-Locale: de → the activation link in the sent mail points at /de/activate", async () => {
+    const res = await appUrlStack.http.raw(
+      "POST",
+      "/api/auth/signup-request",
+      { email: "appurl-de@example.com" },
+      { [LOCALE_HEADER_NAME]: "de" },
+    );
+    expect(res.status).toBe(200);
+    expect(appUrlTransport.sent).toHaveLength(1);
+    const sent = appUrlTransport.sent[0];
+    if (!sent) throw new Error("no mail sent");
+    expect(sent.html).toContain("https://app.example.com/de/activate?token=");
+  });
+});

package/src/auth-email-password/feature.ts

@@ -64,8 +64,10 @@ export type PasswordResetOptions = {
   readonly tokenTtlMinutes?: number;
   // App page that receives the magic-link; the handler appends `?token=…` and
   // sends the mail via delivery (ctx.notify). No sendResetEmail callback — the
-  // app mounts `delivery` + a mail channel instead.
-  readonly appUrl: string;
+  // app mounts `delivery` + a mail channel instead. Apps with language-in-path
+  // routing may pass a function to pick the right page for the resolved
+  // locale instead of a plain string.
+  readonly appUrl: string | ((locale: string) => string);
   readonly appName?: string;
   readonly locale?: AuthMailLocale;
 };
@@ -80,8 +82,10 @@ export type EmailVerificationOptions = {
   readonly tokenTtlMinutes?: number;
   readonly mode?: "strict" | "off";
   // App page that receives the magic-link; the handler appends `?token=…` and
-  // sends via delivery (ctx.notify). No sendVerificationEmail callback.
-  readonly appUrl: string;
+  // sends via delivery (ctx.notify). No sendVerificationEmail callback. Apps
+  // with language-in-path routing may pass a function to pick the right page
+  // for the resolved locale instead of a plain string.
+  readonly appUrl: string | ((locale: string) => string);
   readonly appName?: string;
   readonly locale?: AuthMailLocale;
 };

package/src/auth-email-password/handlers/invite-create.write.ts

@@ -17,7 +17,7 @@
 // erlaubt new-user-signup mit dem Token. Keine Enumeration durchs
 // invite-create.
 
-import { generateToken } from "@cosmicdrift/kumiko-framework/api";
+import { generateToken, requestContext } from "@cosmicdrift/kumiko-framework/api";
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
 import { access, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
@@ -62,9 +62,14 @@ export type InviteCreateOptions = {
   /** TTL für den Activation-Token. Default 7 Tage. */
   readonly tokenTtlMinutes?: number;
   /** App page that receives the magic-link; the handler appends `?token=…`
-   *  and dispatches the invite mail via delivery (ctx.notify). */
-  readonly appUrl: string;
+   *  and dispatches the invite mail via delivery (ctx.notify). Apps with
+   *  language-in-path routing pass a function to pick the right page for
+   *  the resolved locale; everyone else keeps a plain string. */
+  readonly appUrl: string | ((locale: string) => string);
   readonly appName?: string;
+  /** Static fallback mail locale, used only when the request itself
+   *  carries no locale signal (no X-Locale header, no usable
+   *  Accept-Language) — see the locale resolution in the handler below. */
   readonly locale?: AuthMailLocale;
   // Opt-in role-hierarchy gate. Roles are app-defined strings, not a framework
   // concept, so the hierarchy itself must live in the app — this hook lets it
@@ -154,6 +159,11 @@ export function createInviteCreateHandler(opts: InviteCreateOptions) {
 
       await storeInviteToken(ctx.redis, { invitationId, token, ttlSeconds });
 
+      // Same precedence as signup/reset/verify: the inviting admin's active
+      // browser language wins when the request carries one, else the
+      // handler's static opts.locale, else ctx.locale's own default.
+      const locale = requestContext.get()?.locale ?? opts.locale ?? ctx.locale;
+
       await dispatchMagicLinkMail(
         ctx.notify,
         {
@@ -168,7 +178,7 @@ export function createInviteCreateHandler(opts: InviteCreateOptions) {
           token,
           expiresAt: expiresAt.toString(),
           ...(opts.appName !== undefined && { appName: opts.appName }),
-          ...(opts.locale !== undefined && { locale: opts.locale }),
+          locale,
         },
       );
 

package/src/auth-email-password/handlers/signup-request.write.ts

@@ -1,27 +1,27 @@
-// Magic-Link-Signup, Step 1 (request).
+// Magic-link signup, step 1 (request).
 //
-// User gibt Email ein → wir minten einen opaken Random-Token, speichern
-// ihn bidirektional in Redis (token↔email), und schicken die Activation-Mail
-// via delivery (ctx.notify) — wie reset/verify. Anders als die: HIER kein
-// userId-Lookup und kein HMAC-signing (es gäbe kein Subject — im Normalfall
-// existiert der User noch nicht). Ob die Email bereits ein Konto hat,
-// entscheidet bewusst der Confirm-Schritt, nicht dieser.
+// User enters an email → we mint an opaque random token, store it
+// bidirectionally in Redis (token<->email), and send the activation mail
+// via delivery (ctx.notify) — same as reset/verify. Unlike those: NO
+// userId lookup and NO HMAC signing here (there'd be no subject — normally
+// the user doesn't exist yet). Whether the email already has an account is
+// deliberately decided by the confirm step, not this one.
 //
 // Resend: if a token is still live for this email, we invalidate it and
 // mint a fresh one — the user gets a second mail with a NEW activation
 // link, and the first link stops working. Deliberate: at most one live
 // signup token per email at any time (see signup-token-store.ts).
 //
-// Always-200 (enumeration-safe): das Response sieht für jede Email gleich
-// aus, egal ob sie schon registriert ist oder nicht. Eine Email KANN bereits
-// ein Konto haben (Seeding oder früherer Signup) — die Sperre dagegen sitzt
-// bewusst im Confirm-Schritt (#365): signup-confirm lehnt eine bereits
-// registrierte Email ab statt den bestehenden User wiederzuverwenden. Hier
-// bleibt's always-200 + Resend-idempotent, damit der Request-Pfad nichts
-// leakt; ein request-seitiges Unterdrücken des Links wäre Defense-in-depth,
-// aber mit Enumeration-Risiko (separat).
+// Always-200 (enumeration-safe): the response looks the same for every
+// email, whether it's already registered or not. An email CAN already have
+// an account (seeding or an earlier signup) — the actual gate sits
+// deliberately in the confirm step (#365): signup-confirm rejects an
+// already-registered email instead of reusing the existing user. Here it
+// stays always-200 + resend-idempotent so the request path leaks nothing;
+// suppressing the link on the request side would be defense-in-depth, but
+// with an enumeration risk of its own (separate concern).
 
-import { generateToken } from "@cosmicdrift/kumiko-framework/api";
+import { generateToken, requestContext } from "@cosmicdrift/kumiko-framework/api";
 import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import { Temporal } from "temporal-polyfill";
@@ -53,13 +53,18 @@ export type SignupRequestData =
   | { readonly kind: "no-op" };
 
 export type SignupRequestOptions = {
-  /** TTL für den Activation-Token. Default 24 h — lang genug damit User
-   *  "morgen aktivieren" können ohne Resend-Spam. */
+  /** TTL for the activation token. Default 24h — long enough that users
+   *  can "activate tomorrow" without resend spam. */
   readonly tokenTtlMinutes?: number;
   /** App page that receives the magic-link; the handler appends `?token=…`
-   *  and dispatches the activation mail via delivery (ctx.notify). */
-  readonly appUrl: string;
+   *  and dispatches the activation mail via delivery (ctx.notify). Apps
+   *  with language-in-path routing pass a function to pick the right page
+   *  for the resolved locale; everyone else keeps a plain string. */
+  readonly appUrl: string | ((locale: string) => string);
   readonly appName?: string;
+  /** Static fallback mail locale for this handler instance, used only when
+   *  the request itself carries no locale signal (no X-Locale header, no
+   *  usable Accept-Language) — see the locale resolution below. */
   readonly locale?: AuthMailLocale;
 };
 
@@ -101,22 +106,21 @@ export function createSignupRequestHandler(opts: SignupRequestOptions) {
         );
       }
 
-      // Email-Normalisierung lebt im Store (signup-token-store). Der
-      // Handler reicht die raw email durch — eine Quelle, kein Drift
-      // zwischen Lookup-Pfaden die unterschiedlich (oder gar nicht)
-      // lowercased haben.
+      // Email normalization lives in the store (signup-token-store). The
+      // handler passes the raw email through — one source, no drift
+      // between lookup paths that lowercase differently (or not at all).
       const email = event.payload.email;
 
       // At most one live signup token per email: invalidate whatever's
       // there before minting the new one (see signup-token-store.ts).
       await invalidateExistingSignupToken(ctx.redis, email);
       // 32 random bytes = 256 bits unguessable randomness, base64url
-      // encoded zu 43 chars. Math.random war früher ein Bug:
-      // xorshift128+ hat ~128 Bit State der nach ~5 beobachteten
-      // Outputs rekonstruierbar ist — Angreifer könnte eigene
-      // signup-requests triggern und die Tokens fremder User
-      // vorhersagen. generateToken nutzt randomBytes aus node:crypto,
-      // dieselbe Quelle wie CSRF/Session-Tokens.
+      // encoded to 43 chars. Math.random used to be a bug here:
+      // xorshift128+ has ~128 bits of state that's reconstructible after
+      // ~5 observed outputs — an attacker could trigger their own
+      // signup-requests and predict other users' tokens. generateToken
+      // uses randomBytes from node:crypto, the same source as CSRF/
+      // session tokens.
       const token = generateToken();
 
       const expiresAt = Temporal.Now.instant().add({ seconds: ttlSeconds });
@@ -124,11 +128,21 @@ export function createSignupRequestHandler(opts: SignupRequestOptions) {
 
       await storeSignupToken(ctx.redis, { email, token, ttlSeconds });
 
-      // normalizeEmail aus dem Store — eine Quelle für die Normalisierungs-
-      // Verantwortung; delivery-Empfänger + Lookup-Pfad kriegen konsistent
-      // das gleiche Format.
+      // normalizeEmail from the store — one source of truth for
+      // normalization; the delivery recipient + lookup path consistently
+      // get the same format.
       const normalizedEmail = normalizeEmail(email);
 
+      // ctx.locale always resolves to something (falls back to the app's
+      // boot default, then "en" — dispatch-shared.ts), so it can't tell us
+      // whether THIS request actually carried a locale signal. Read the raw
+      // request-layer value instead: present → the browser's active
+      // language wins over opts.locale (this handler's static config);
+      // absent → opts.locale is the real, still-relevant fallback
+      // (backwards compatibility for callers that configured it and never
+      // send X-Locale), then ctx.locale's own resolved default.
+      const locale = requestContext.get()?.locale ?? opts.locale ?? ctx.locale;
+
       await dispatchMagicLinkMail(
         ctx.notify,
         {
@@ -142,7 +156,7 @@ export function createSignupRequestHandler(opts: SignupRequestOptions) {
           token,
           expiresAt: expiresAtIso,
           ...(opts.appName !== undefined && { appName: opts.appName }),
-          ...(opts.locale !== undefined && { locale: opts.locale }),
+          locale,
         },
       );
 

package/src/auth-email-password/handlers/token-request-handler.ts

@@ -1,5 +1,6 @@
 // Shared factory for the request-side of out-of-band token flows
-// (password-reset, email-verification). Both follow the same shape:
+// (password-reset, email-verification, account-unlock). All follow the
+// same shape:
 //
 //   POST email
 //     → resolve user (system-scoped query)
@@ -11,6 +12,7 @@
 // default TTL, extra skip condition) + two error codes — encoded on the
 // spec rather than duplicated across two near-identical handler bodies.
 
+import { requestContext } from "@cosmicdrift/kumiko-framework/api";
 import { createSystemUser, defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
 import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import type { Temporal } from "temporal-polyfill";
@@ -70,9 +72,14 @@ export type TokenRequestSpec<TName extends string, TSuccessKind extends string>
 export type TokenRequestOptions = {
   readonly hmacSecret: string;
   readonly tokenTtlMinutes?: number;
-  // App page that receives the magic-link; the handler appends `?token=…`.
-  readonly appUrl: string;
+  /** App page that receives the magic-link; the handler appends `?token=…`.
+   *  Apps with language-in-path routing pass a function to pick the right
+   *  page for the resolved locale; everyone else keeps a plain string. */
+  readonly appUrl: string | ((locale: string) => string);
   readonly appName?: string;
+  /** Static fallback mail locale, used only when the request itself
+   *  carries no locale signal (no X-Locale header, no usable
+   *  Accept-Language) — see the locale resolution in the handler below. */
   readonly locale?: AuthMailLocale;
 };
 
@@ -117,6 +124,15 @@ export function createTokenRequestHandler<TName extends string, TSuccessKind ext
 
       const { token, expiresAt } = spec.sign(user.id, ttl, opts.hmacSecret);
 
+      // ctx.locale always resolves to something (falls back to the app's
+      // boot default, then "en"), so it can't tell us whether THIS request
+      // actually carried a locale signal. Read the raw request-layer value
+      // instead: present → the requester's active language wins over
+      // opts.locale (this handler's static config); absent → opts.locale
+      // is the real, still-relevant fallback, then ctx.locale's own
+      // resolved default.
+      const locale = requestContext.get()?.locale ?? opts.locale ?? ctx.locale;
+
       await dispatchMagicLinkMail(
         ctx.notify,
         {
@@ -132,7 +148,7 @@ export function createTokenRequestHandler<TName extends string, TSuccessKind ext
           token,
           expiresAt: expiresAt.toString(),
           ...(opts.appName !== undefined && { appName: opts.appName }),
-          ...(opts.locale !== undefined && { locale: opts.locale }),
+          locale,
         },
       );
 

package/src/auth-email-password/i18n.ts

@@ -115,6 +115,8 @@ export const defaultTranslations: TranslationsByLocale = {
     "auth.signupComplete.submitting": "…",
     "auth.signupComplete.missingToken":
       "Activation link is missing a token. Please request a new one.",
+    "auth.signupComplete.activated": "Your account is active and you're signed in.",
+    "auth.signupComplete.continue": "Continue",
     "auth.inviteAccept.title": "Accept invitation",
     "auth.inviteAccept.intro": "You've been invited to a workspace. Click 'Accept' to join.",
     "auth.inviteAccept.loggedInAs": "Signed in as {email}",

package/src/auth-email-password/magic-link-mail.ts

@@ -21,15 +21,23 @@ export type MagicLinkMailSpec = {
 
 // Per-request values: the recipient + the app page that receives the token, plus
 // optional presentation. appUrl is the bare page URL; the token is appended here.
+// appUrl as a function lets apps with language-in-path routing (/de/activate,
+// /en/activate) pick the right page for `locale` — the mail is the only
+// channel that survives a device switch (signup on desktop, open on mobile),
+// so this is the last point where the language can still reach the link.
 export type MagicLinkMailParams = {
   readonly email: string;
-  readonly appUrl: string;
+  readonly appUrl: string | ((locale: string) => string);
   readonly token: string;
   readonly expiresAt: string;
   readonly appName?: string;
   readonly locale?: AuthMailLocale;
 };
 
+function resolveAppUrl(appUrl: string | ((locale: string) => string), locale: string): string {
+  return typeof appUrl === "function" ? appUrl(locale) : appUrl;
+}
+
 function appendToken(appUrl: string, token: string): string {
   const sep = appUrl.includes("?") ? "&" : "?";
   return `${appUrl}${sep}token=${encodeURIComponent(token)}`;
@@ -48,8 +56,9 @@ export async function dispatchMagicLinkMail(
       message: `${spec.handlerName}: ctx.notify unavailable — the delivery feature must be mounted`,
     });
   }
+  const locale = params.locale ?? "en";
   const content = spec.renderContent({
-    url: appendToken(params.appUrl, params.token),
+    url: appendToken(resolveAppUrl(params.appUrl, locale), params.token),
     expiresAt: params.expiresAt,
     ...(params.locale !== undefined && { locale: params.locale }),
     ...(params.appName !== undefined && { appName: params.appName }),

package/src/auth-email-password/web/__tests__/signup-complete-screen.test.tsx

@@ -57,12 +57,10 @@ describe("SignupCompleteScreen", () => {
     expect(fetchMock).not.toHaveBeenCalled();
   });
 
-  test("happy path: gültiges Passwort → signup-confirm fetch + location.assign", async () => {
-    const assigned: string[] = [];
+  test("happy path: gültiges Passwort → Bestätigung statt sofortigem Redirect, Weiter-Button trifft resolveLoggedInHref-Ziel", async () => {
+    const assignMock = mock((_url: string | URL): void => {});
     const assignOrig = window.location.assign.bind(window.location);
-    window.location.assign = ((url: string | URL) => {
-      assigned.push(String(url));
-    }) as typeof window.location.assign;
+    window.location.assign = assignMock as typeof window.location.assign;
 
     const fetchMock = mock(
       async () =>
@@ -94,8 +92,16 @@ describe("SignupCompleteScreen", () => {
             body: JSON.stringify({ token: "abc-token", password: "validpass1" }),
           }),
         );
-        expect(assigned).toEqual(["/acme/"]);
+        expect(screen.getByText("Your account is active and you're signed in.")).toBeTruthy();
       });
+
+      // No automatic redirect: the form is gone, but nothing navigated us away.
+      expect(assignMock).not.toHaveBeenCalled();
+
+      // Continue button targets exactly what resolveLoggedInHref computes from
+      // the response's tenantKey, via the app-supplied function-form prop.
+      const continueLink = screen.getByRole("link", { name: "Continue" }) as HTMLAnchorElement;
+      expect(continueLink.getAttribute("href")).toBe("/acme/");
     } finally {
       window.location.assign = assignOrig;
     }
@@ -130,5 +136,8 @@ describe("SignupCompleteScreen", () => {
     await waitFor(() => {
       expect(screen.getByRole("alert").textContent).toMatch(/invalid|expired/i);
     });
+    // Error path stays on the form — no confirmation, no continue link.
+    expect(screen.queryByRole("link", { name: "Continue" })).toBeNull();
+    expect(document.getElementById("signup-password")).toBeTruthy();
   });
 });

package/src/auth-email-password/web/signup-complete-screen.tsx

@@ -1,19 +1,19 @@
 // @runtime client
 // SignupCompleteScreen — Magic-Link-Self-Signup, Step 2.
 //
-// Liest `?token=...` aus der URL, zeigt Form mit Password + Confirm.
-// Submit triggert /api/auth/signup-confirm — bei Erfolg setzt der
-// Server JWT + Cookies (Auto-Login!) und liefert tenantKey für den
-// Post-Signup-Redirect.
+// Reads `?token=...` from the URL, shows a form with password + confirm.
+// Submit posts to /api/auth/signup-confirm — on success the server sets
+// JWT + cookies (auto-login!) and returns the tenantKey.
 //
-// Token-Quelle ist read-once via useUrlToken: liest `?token=...` beim
-// Mount und scrubbt den Param danach aus der URL (#774). Apps die einen
-// server-injected Token nutzen, reichen `token` als Prop durch.
+// Token source is read-once via useUrlToken: reads `?token=...` on mount
+// and scrubs the param from the URL afterwards (#774). Apps that inject a
+// server-side token pass `token` as a prop instead.
 //
-// Nach success: redirect via window.location.assign zu loggedInHref.
-// Default-Pattern ist "/<tenantKey>/" — die App reicht ein Template
-// rein. Default-Template "/" wäre auch valide (App hat dann eigene
-// Routing-Logik die den eingeloggten User zur richtigen Page schickt).
+// On success: shows a confirmation (account active, signed in) with a
+// button to loggedInHref, instead of navigating away immediately — the
+// server already logged the user in via cookies, but a silent redirect
+// leaves no signal that activation worked. Default pattern is "/" — apps
+// with multi-tenant routing pass `(data) => "/" + data.tenantKey + "/"`.
 
 import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
 import { type FormEvent, type ReactNode, useState } from "react";
@@ -50,6 +50,7 @@ export function SignupCompleteScreen({
   const [confirmPassword, setConfirmPassword] = useState("");
   const [submitting, setSubmitting] = useState(false);
   const [error, setError] = useState<string | null>(null);
+  const [continueHref, setContinueHref] = useState<string | null>(null);
 
   const doSubmit = async (): Promise<void> => {
     setError(null);
@@ -66,9 +67,10 @@ export function SignupCompleteScreen({
     const res = await confirmSignup(token, password);
     setSubmitting(false);
     if (res.ok) {
-      // Auto-Login: Cookies sind via Set-Cookie schon im Browser. Wir
-      // schicken den User direkt zur eingeloggten Page.
-      window.location.assign(resolveLoggedInHref(loggedInHref, res.data.tenantKey));
+      // Cookies are already set (auto-login). Show a confirmation with an
+      // explicit continue button instead of navigating away silently —
+      // the user otherwise gets no signal that activation worked.
+      setContinueHref(resolveLoggedInHref(loggedInHref, res.data.tenantKey));
       return;
     }
     if (res.error.reason === "invalid_signup_token") {
@@ -104,6 +106,19 @@ export function SignupCompleteScreen({
     );
   }
 
+  if (continueHref !== null) {
+    return (
+      <AuthCard title={effectiveTitle}>
+        <div className="p-6 pt-0 flex flex-col gap-4">
+          <p className="text-sm text-muted-foreground">{t("auth.signupComplete.activated")}</p>
+          <Link href={continueHref} variant="button">
+            {t("auth.signupComplete.continue")}
+          </Link>
+        </div>
+      </AuthCard>
+    );
+  }
+
   return (
     <AuthCard title={effectiveTitle}>
       <div className="p-6 pt-0 flex flex-col gap-4">

package/src/config/db/queries/__tests__/resolver.test.ts

@@ -0,0 +1,64 @@
+// #1163: config:query:readiness read config rows via asRawClient(db).unsafe()
+// directly, bypassing the #1358 closed-connection retry that only covered
+// bun-db/query.ts's own selectMany/countWhere. Routed through the exported
+// unsafeReadRetrying helper instead — this test mirrors
+// bun-db/__tests__/select-many-retry.test.ts's fake-client pattern to prove
+// the retry now actually fires for this call site.
+
+import { describe, expect, test } from "bun:test";
+import { selectConfigRowsForKeys, selectConfigRowsForScope } from "../resolver";
+
+function closedConnectionError(): Error {
+  return Object.assign(new Error("The connection was closed."), { name: "AbortError" });
+}
+
+type FakeClient = {
+  unsafe: (sql: string, params?: readonly unknown[]) => Promise<readonly unknown[]>;
+  begin: () => never;
+  calls: number;
+};
+
+function fakeClient(failures: Error[]): FakeClient {
+  const remaining = [...failures];
+  const client: FakeClient = {
+    calls: 0,
+    unsafe: async () => {
+      client.calls++;
+      const err = remaining.shift();
+      if (err) throw err;
+      return [{ id: "r1", key: "k", value: "v", tenantId: "t1", userId: null }];
+    },
+    // Top-level pool client — matches what dispatch-query.ts hands buildHandlerContext
+    // for a standalone query.execute() call (no tx passed, resolveDbSource falls back
+    // to the pool connection, which has .begin()).
+    begin: () => {
+      throw new Error("not used in test");
+    },
+  };
+  return client;
+}
+
+describe("config db/queries/resolver — closed-connection retry (#1163)", () => {
+  test("selectConfigRowsForScope retries once and returns rows", async () => {
+    const db = fakeClient([closedConnectionError()]);
+    const rows = await selectConfigRowsForScope(db as never, "system", "t1", "u1");
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.key).toBe("k");
+    expect(db.calls).toBe(2);
+  });
+
+  test("selectConfigRowsForKeys retries once and returns rows", async () => {
+    const db = fakeClient([closedConnectionError()]);
+    const rows = await selectConfigRowsForKeys(db as never, ["k"], "system", "t1", "u1");
+    expect(rows).toHaveLength(1);
+    expect(db.calls).toBe(2);
+  });
+
+  test("gives up after the single retry when the connection stays closed", async () => {
+    const db = fakeClient([closedConnectionError(), closedConnectionError()]);
+    await expect(selectConfigRowsForScope(db as never, "system", "t1", "u1")).rejects.toThrow(
+      "connection was closed",
+    );
+    expect(db.calls).toBe(2);
+  });
+});

package/src/config/db/queries/resolver.ts

@@ -1,4 +1,4 @@
-import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import { unsafeReadRetrying } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbRunner, TenantDb } from "@cosmicdrift/kumiko-framework/db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 
@@ -16,7 +16,8 @@ export async function selectConfigRowsForScope(
   tenantId: TenantId,
   userId: string,
 ): Promise<readonly ConfigRow[]> {
-  return asRawClient(db).unsafe<ConfigRow>(
+  return unsafeReadRetrying<ConfigRow>(
+    db,
     `SELECT id, key, value, tenant_id AS "tenantId", user_id AS "userId"
      FROM read_config_values
      WHERE (tenant_id = $1 AND user_id IS NULL)
@@ -33,7 +34,8 @@ export async function selectConfigRowsForKeys(
   tenantId: TenantId,
   userId: string,
 ): Promise<readonly ConfigRow[]> {
-  return asRawClient(db).unsafe<ConfigRow>(
+  return unsafeReadRetrying<ConfigRow>(
+    db,
     `SELECT id, key, value, tenant_id AS "tenantId", user_id AS "userId"
      FROM read_config_values
      WHERE key = ANY($1)

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)}`,
+        );
+      }
+    }
   }
 
   // ---------------------------------------------------------------