@desplega.ai/agent-swarm 1.80.2 → 1.81.0

package/src/http/webhooks.ts

@@ -412,9 +412,18 @@ export async function handleWebhooks(
 
     try {
       switch (payload.event_type) {
+        case "message.received.unauthenticated":
+          console.warn(
+            `[AgentMail] Received unauthenticated message - treating as received event for inbox ${payload.message?.inbox_id ?? "unknown"}`,
+          );
+
+          await handleMessageReceived(payload);
+          break;
+
         case "message.received":
           await handleMessageReceived(payload);
           break;
+
         default:
           console.log(`[AgentMail] Ignoring event type: ${payload.event_type}`);
       }

package/src/http/workflows.ts

@@ -341,24 +341,11 @@ export async function handleWorkflows(
     }
     const rawBody = Buffer.concat(chunks).toString();
 
-    // Validate JSON before processing (but pass raw string for HMAC)
-    try {
-      if (rawBody) JSON.parse(rawBody);
-    } catch {
-      jsonError(res, "Invalid JSON body", 400);
-      return true;
-    }
-
-    const signature =
-      (req.headers["x-hub-signature-256"] as string | undefined) ??
-      (req.headers["x-signature"] as string | undefined);
-
     try {
       const result = await handleWebhookTrigger(
         workflowId,
-        rawBody, // Raw body string — used for HMAC verification + passed as triggerData
-        signature,
-        signature,
+        rawBody, // Raw body string — HMAC is verified against raw bytes; JSON parsing happens inside
+        req.headers, // Full header bag — signature header resolved per trigger config
         getExecutorRegistry(),
       );
       json(res, result, 201);

package/src/linear/oauth.ts

@@ -1,6 +1,10 @@
+import { upsertKv } from "../be/db";
 import { getOAuthApp } from "../be/db-queries/oauth";
 import { buildAuthorizationUrl, exchangeCode, type OAuthProviderConfig } from "../oauth/wrapper";
 
+/** kv namespace for the Linear bot's appUserId (Q21.C). Keyed by workspace ID. */
+const APP_USER_ID_NAMESPACE = "integration:linear:bot-app-user-id";
+
 export function getLinearOAuthConfig(): OAuthProviderConfig | null {
   const app = getOAuthApp("linear");
   if (!app) return null;
@@ -31,7 +35,63 @@ export async function handleLinearCallback(
 ): Promise<{ accessToken: string; refreshToken?: string; expiresIn?: number; scope?: string }> {
   const config = getLinearOAuthConfig();
   if (!config) throw new Error("Linear OAuth not configured");
-  return exchangeCode(config, code, state);
+  const result = await exchangeCode(config, code, state);
+
+  // Best-effort: capture the Linear bot's appUserId now that we have a fresh
+  // token (Q21.C). Persisted in kv_entries so webhook handlers can guard
+  // against the swarm hearing itself ("creator.id === storedAppUserId").
+  // Failure here is non-fatal — the guard is a no-op until the next refresh.
+  captureLinearAppUserId(result.accessToken).catch((err) => {
+    console.warn(
+      "[Linear] Failed to capture appUserId during OAuth completion (non-fatal):",
+      err instanceof Error ? err.message : err,
+    );
+  });
+
+  return result;
+}
+
+/**
+ * Query Linear's GraphQL `viewer` to find the OAuth-actor's user id and
+ * organization id, then persist it under `integration:linear:bot-app-user-id`.
+ *
+ * NOTE: when the OAuth app is installed with `actor=app`, Linear's `viewer`
+ * resolves to the synthetic app-user — the "bot identity" that emits
+ * AgentSessionEvent.created with `agentSession.creator.id === viewer.id`. That
+ * is precisely the value Q21.C asks us to compare against.
+ */
+export async function captureLinearAppUserId(accessToken: string): Promise<void> {
+  const query = `query { viewer { id organization { id } } }`;
+  const res = await fetch("https://api.linear.app/graphql", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${accessToken}`,
+    },
+    body: JSON.stringify({ query }),
+  });
+  if (!res.ok) {
+    throw new Error(`Linear viewer query failed: HTTP ${res.status}`);
+  }
+  const body = (await res.json()) as {
+    data?: { viewer?: { id?: string; organization?: { id?: string } } };
+    errors?: Array<{ message: string }>;
+  };
+  if (body.errors?.length) {
+    throw new Error(`Linear viewer query returned errors: ${body.errors[0]?.message ?? "?"}`);
+  }
+  const appUserId = body.data?.viewer?.id;
+  const workspaceId = body.data?.viewer?.organization?.id;
+  if (!appUserId) {
+    throw new Error("Linear viewer query returned no id");
+  }
+  upsertKv({
+    namespace: APP_USER_ID_NAMESPACE,
+    key: workspaceId && workspaceId !== "" ? workspaceId : "default",
+    value: appUserId,
+    valueType: "string",
+    expiresAt: null,
+  });
 }
 
 /**

package/src/linear/sync.ts

@@ -1,4 +1,4 @@
-import { cancelTask, getAllAgents, getTaskById, resolveUser } from "../be/db";
+import { cancelTask, getAllAgents, getKv, getTaskById, incrKv, upsertKv } from "../be/db";
 import { getOAuthTokens } from "../be/db-queries/oauth";
 import {
   createTrackerSync,
@@ -6,6 +6,7 @@ import {
   getTrackerSyncByExternalId,
   updateTrackerSync,
 } from "../be/db-queries/tracker";
+import { findOrCreateUserByEmail, findUserByExternalId, linkIdentity } from "../be/users";
 import { ensureToken } from "../oauth/ensure-token";
 import { resolveTemplate } from "../prompts/resolver";
 import { linearContextKey } from "../tasks/context-key";
@@ -343,6 +344,100 @@ function findLeadAgent() {
   return agents.find((a) => a.isLead) ?? null;
 }
 
+// ─── Identity resolution (Q21.A / Q21.C / Q17.B) ──────────────────────────
+//
+// Linear app config is currently agent-session-events-only — only
+// AgentSessionEvent.created/prompted arrive. If subscriptions widen to
+// Issue/Comment events later, handle system-actor case (per Q21.B / Q22).
+// Identity primitives in src/be/users.ts are event-type-agnostic; only the
+// extraction shape changes.
+
+const UNMAPPED_NAMESPACE = "integration:unmapped:linear";
+const UNMAPPED_TTL_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+const LINEAR_WEBHOOK_ACTOR = { kind: "system", id: "webhook:linear" } as const;
+
+/** kv namespace for the Linear bot's appUserId (Q21.C). Keyed by workspace ID. */
+const APP_USER_ID_NAMESPACE = "integration:linear:bot-app-user-id";
+
+/**
+ * Read the bot's persisted appUserId for the given workspace (or the default
+ * slot). Returns null when not yet captured (early OAuth installs).
+ */
+function getStoredAppUserId(workspaceId: string | null): string | null {
+  const key = workspaceId && workspaceId !== "" ? workspaceId : "default";
+  const entry = getKv(APP_USER_ID_NAMESPACE, key);
+  if (!entry) return null;
+  return typeof entry.value === "string" ? entry.value : null;
+}
+
+/**
+ * Cascade per Q17.B:
+ *   1. `findUserByExternalId('linear', linearUserId)` (fast path).
+ *   2. On miss + email present → `findOrCreateUserByEmail(email, {name})` then
+ *      `linkIdentity(...)`.
+ *   3. Else record unmapped kv entries for operator triage.
+ *
+ * Q21.C bot-self-link guard: if `linearUserId === storedAppUserId` (the swarm
+ * hearing itself), short-circuit — no users row, no unmapped entry.
+ *
+ * Returns `undefined` when no mapping could be established — callers pass
+ * that straight to `requestedByUserId`.
+ */
+function resolveLinearActor(
+  linearUserId: string,
+  email: string,
+  name: string,
+  workspaceId: string | null,
+  sampleEventType: string,
+  sampleContext: string | null,
+): string | undefined {
+  if (!linearUserId) {
+    // No identifier — nothing to map. We don't even know what to track as
+    // unmapped, so just return undefined.
+    return undefined;
+  }
+
+  // Q21.C bot-self-link guard.
+  const storedAppUserId = getStoredAppUserId(workspaceId);
+  if (storedAppUserId && linearUserId === storedAppUserId) {
+    return undefined;
+  }
+  if (!storedAppUserId) {
+    // Non-fatal: log once per call. Real guard re-engages after the next
+    // OAuth refresh or admin capture step persists the appUserId.
+    console.warn("[linear] appUserId not yet stored; bot-self-link guard disabled");
+  }
+
+  const existing = findUserByExternalId("linear", linearUserId);
+  if (existing) return existing.id;
+
+  const trimmedEmail = typeof email === "string" ? email.trim() : "";
+  if (trimmedEmail !== "") {
+    const { user: linked } = findOrCreateUserByEmail(
+      trimmedEmail,
+      { name: name?.trim() || undefined },
+      LINEAR_WEBHOOK_ACTOR,
+    );
+    linkIdentity(linked.id, "linear", linearUserId, LINEAR_WEBHOOK_ACTOR);
+    return linked.id;
+  }
+
+  // No mapping + no inline email → unmapped tracker (Q14/Q17.D).
+  upsertKv({
+    namespace: UNMAPPED_NAMESPACE,
+    key: `${linearUserId}:meta`,
+    value: {
+      lastSeenAt: new Date().toISOString(),
+      sampleEventType,
+      sampleContext: sampleContext ? sampleContext.slice(0, 100) : null,
+    },
+    valueType: "json",
+    expiresAt: Date.now() + UNMAPPED_TTL_MS,
+  });
+  incrKv(UNMAPPED_NAMESPACE, `${linearUserId}:count`, 1);
+  return undefined;
+}
+
 /**
  * Handle AgentSession events from Linear.
  * These are fired when an issue is assigned to the Linear agent integration,
@@ -375,16 +470,26 @@ export async function handleAgentSessionEvent(event: Record<string, unknown>): P
     return;
   }
 
-  // Extract actor identity from Linear webhook payload
-  const actor = event.actor as Record<string, unknown> | undefined;
-  const actorLinearId = actor ? String(actor.id ?? "") : "";
-  const actorName = actor ? String(actor.name ?? "") : "";
-  const actorEmail = actor ? String(actor.email ?? "") : "";
-  const requestedByUserId = resolveUser({
-    linearUserId: actorLinearId || undefined,
-    email: actorEmail || undefined,
-    name: actorName || undefined,
-  })?.id;
+  // Extract actor identity from Linear webhook payload (Q21.A bug fix).
+  // The old code read a top-level `actor` field that does NOT exist in
+  // AgentSessionEvent payloads. The human is at agentSession.creator for
+  // the `created` action and agentActivity.user for `prompted`.
+  const session = event.agentSession as Record<string, unknown> | undefined;
+  const creator = session?.creator as Record<string, unknown> | undefined;
+  const linearUserId = creator ? String(creator.id ?? "") : "";
+  const actorEmail = creator ? String(creator.email ?? "") : "";
+  const actorName = creator ? String(creator.name ?? "") : "";
+  const workspaceId = (event.organizationId ?? event.workspaceId) as string | undefined;
+  const sampleContext =
+    (session?.comment as { body?: string } | undefined)?.body ?? issueTitle ?? null;
+  const requestedByUserId = resolveLinearActor(
+    linearUserId,
+    actorEmail,
+    actorName,
+    workspaceId ?? null,
+    "AgentSessionEvent.created",
+    sampleContext,
+  );
 
   // Check if we already track this issue
   const existing = getTrackerSyncByExternalId("linear", "task", issueId);
@@ -687,16 +792,24 @@ export async function handleAgentSessionPrompted(event: Record<string, unknown>)
   // Task is completed/failed/cancelled or doesn't exist — create a new follow-up task
   const lead = findLeadAgent();
 
-  // Extract actor identity from Linear webhook payload
-  const promptedActor = event.actor as Record<string, unknown> | undefined;
-  const promptedActorLinearId = promptedActor ? String(promptedActor.id ?? "") : "";
-  const promptedActorEmail = promptedActor ? String(promptedActor.email ?? "") : "";
-  const promptedActorName = promptedActor ? String(promptedActor.name ?? "") : "";
-  const promptedRequestedByUserId = resolveUser({
-    linearUserId: promptedActorLinearId || undefined,
-    email: promptedActorEmail || undefined,
-    name: promptedActorName || undefined,
-  })?.id;
+  // Extract actor identity from Linear webhook payload (Q21.A bug fix).
+  // For `prompted` action, the human is at `event.agentActivity.user`.
+  const activity = event.agentActivity as Record<string, unknown> | undefined;
+  const promptUser = activity?.user as Record<string, unknown> | undefined;
+  const promptedActorLinearId = promptUser ? String(promptUser.id ?? "") : "";
+  const promptedActorEmail = promptUser ? String(promptUser.email ?? "") : "";
+  const promptedActorName = promptUser ? String(promptUser.name ?? "") : "";
+  const promptedWorkspaceId = (event.organizationId ?? event.workspaceId) as string | undefined;
+  const promptedSampleContext =
+    (activity?.content as { body?: string } | undefined)?.body ?? userMessage ?? null;
+  const promptedRequestedByUserId = resolveLinearActor(
+    promptedActorLinearId,
+    promptedActorEmail,
+    promptedActorName,
+    promptedWorkspaceId ?? null,
+    "AgentSessionEvent.prompted",
+    promptedSampleContext,
+  );
 
   const followupResult = resolveTemplate("linear.issue.followup", {
     issue_identifier: issueIdentifier,

package/src/slack/actions.ts

@@ -1,8 +1,9 @@
 import type { App } from "@slack/bolt";
-import { cancelTask, getAgentById, getLeadAgent, getTaskById, resolveUser } from "../be/db";
+import { cancelTask, getAgentById, getLeadAgent, getTaskById } from "../be/db";
 import { slackContextKey } from "../tasks/context-key";
 import { createTaskWithSiblingAwareness } from "../tasks/sibling-awareness";
 import { buildCancelledBlocks, getTaskLink } from "./blocks";
+import { resolveSlackUserId } from "./enrich";
 
 export function registerActionHandlers(app: App): void {
   // "View Full Logs" — URL button, just ack (Slack opens the link automatically)
@@ -67,7 +68,12 @@ export function registerActionHandlers(app: App): void {
     if (!originalTask || !originalTask.slackChannelId) return;
 
     const lead = getLeadAgent();
-    const requestedByUserId = resolveUser({ slackUserId: body.user.id })?.id;
+    // Resolve via the shared cascade. Sample context = the modal callback ID
+    // so operators can see *which* modal-submit triggered an unmapped entry.
+    const requestedByUserId = await resolveSlackUserId(client, body.user.id, {
+      sampleEventType: "view_submission",
+      sampleContext: view.callback_id || "follow_up_submit",
+    });
     const followUpTask = createTaskWithSiblingAwareness(followUpText, {
       agentId: lead?.id,
       source: "slack",

package/src/slack/assistant.ts

@@ -1,13 +1,9 @@
 import { Assistant } from "@slack/bolt";
-import {
-  getAgentWorkingOnThread,
-  getLeadAgent,
-  getMostRecentTaskInThread,
-  resolveUser,
-} from "../be/db";
+import { getAgentWorkingOnThread, getLeadAgent, getMostRecentTaskInThread } from "../be/db";
 import { resolveTemplate } from "../prompts/resolver";
 import { slackContextKey } from "../tasks/context-key";
 import { createTaskWithSiblingAwareness } from "../tasks/sibling-awareness";
+import { resolveSlackUserId } from "./enrich";
 import { wasEventSeen } from "./event-dedup";
 import { bufferThreadMessage } from "./thread-buffer";
 // Side-effect import: registers all Slack event templates in the in-memory registry
@@ -41,7 +37,7 @@ export function createAssistant(): Assistant {
       await saveThreadContext();
     },
 
-    userMessage: async ({ message, body, say, setStatus, setTitle, getThreadContext }) => {
+    userMessage: async ({ message, body, say, setStatus, setTitle, getThreadContext, client }) => {
       // Slack retries deliveries on 3s timeout / 5xx. Drop duplicates before
       // any task-creation work runs (DES-293).
       const eventId = body?.event_id;
@@ -76,8 +72,15 @@ export function createAssistant(): Assistant {
         const messageText = (msg.text as string) || "";
         const userId = (msg.user as string) || "";
 
-        // Resolve canonical user identity (graceful — null if not found)
-        const requestedByUserId = userId ? resolveUser({ slackUserId: userId })?.id : undefined;
+        // Resolve canonical user identity via the shared cascade. On no-email,
+        // the cascade records the user in the kv unmapped tracker; this handler
+        // proceeds without a `requestedByUserId`.
+        const requestedByUserId = userId
+          ? await resolveSlackUserId(client, userId, {
+              sampleEventType: "assistant_message",
+              sampleContext: messageText,
+            })
+          : undefined;
 
         // 1. Check if an agent is already working in this thread
         const workingAgent = getAgentWorkingOnThread(channelId, threadTs);

package/src/slack/enrich.ts

@@ -0,0 +1,162 @@
+/**
+ * Slack-side identity enrichment + resolution cascade.
+ *
+ * Two helpers — together they replace the in-process email-lookup Map that
+ * previously lived in `src/slack/handlers.ts` (Q17.E):
+ *
+ *   * `enrichSlackUserEmail(slackUserId)` — kv-backed cache of the user's
+ *     email + display name from `client.users.info`. 24h TTL on success;
+ *     failures are NEVER cached so rate-limit recovery just works on retry.
+ *
+ *   * `resolveSlackUserId(client, slackUserId, ctx)` — the three-step cascade
+ *     each Slack webhook entry point uses to map a Slack user to a canonical
+ *     `users.id`:
+ *
+ *       1. `findUserByExternalId('slack', slackUserId)` — fast path.
+ *       2. On miss: enrich → `findOrCreateUserByEmail` + `linkIdentity`.
+ *       3. On no-email: record into the kv unmapped tracker. Returns
+ *          `undefined` — task creation proceeds without a `requestedByUserId`.
+ *
+ * Both helpers are API-side (live under `src/slack/` which is API-only) — they
+ * may import from `src/be/`.
+ */
+
+import type { WebClient } from "@slack/web-api";
+import { getKv, upsertKv } from "../be/db";
+import { recordUnmappedIdentity } from "../be/unmapped-identities";
+import {
+  findOrCreateUserByEmail,
+  findUserByExternalId,
+  type IdentityActor,
+  linkIdentity,
+} from "../be/users";
+
+const ENRICHMENT_NAMESPACE = "integration:user-enrichment:slack";
+const ENRICHMENT_TTL_MS = 24 * 60 * 60 * 1000; // 24h
+
+/**
+ * Persisted enrichment payload. `email: null` cases are NEVER stored — see
+ * Q17.E. We keep `name` so future People-page renders don't need to refetch.
+ */
+interface EnrichedSlackUser {
+  email: string;
+  name: string | null;
+  fetchedAt: string;
+}
+
+/**
+ * Fetch a Slack user's email, caching successful results for 24h in the
+ * `integration:user-enrichment:slack` kv namespace.
+ *
+ * Returns `null` (without caching) when:
+ *   * `client.users.info` throws (network / 5xx / rate-limit).
+ *   * The profile is missing `profile.email` (bot accounts, restricted users).
+ *
+ * Caching null would defeat retry-on-recovery, so we intentionally skip the
+ * cache write on every failure path.
+ */
+export async function enrichSlackUserEmail(
+  client: WebClient,
+  slackUserId: string,
+): Promise<string | null> {
+  // Cache hit — return the persisted email straight through.
+  const cached = getKv(ENRICHMENT_NAMESPACE, slackUserId);
+  if (cached !== null) {
+    const payload = cached.value as EnrichedSlackUser;
+    if (payload?.email) {
+      return payload.email;
+    }
+    // Defensive: if a stale row landed without email somehow, fall through to
+    // refetch rather than handing back `null` from cache.
+  }
+
+  // Cache miss — hit the Slack API.
+  let email: string | null = null;
+  let name: string | null = null;
+  try {
+    const result = await client.users.info({ user: slackUserId });
+    email = result.user?.profile?.email ?? null;
+    name = result.user?.profile?.real_name ?? result.user?.real_name ?? null;
+  } catch (error) {
+    console.error(`[Slack] enrichSlackUserEmail failed for ${slackUserId}:`, error);
+    return null;
+  }
+
+  if (!email) {
+    // Q17.E: do NOT cache the no-email case.
+    return null;
+  }
+
+  upsertKv({
+    namespace: ENRICHMENT_NAMESPACE,
+    key: slackUserId,
+    value: {
+      email,
+      name,
+      fetchedAt: new Date().toISOString(),
+    } satisfies EnrichedSlackUser,
+    valueType: "json",
+    expiresAt: Date.now() + ENRICHMENT_TTL_MS,
+  });
+
+  return email;
+}
+
+/** Audit-trail actor for the auto-link cascade. */
+const SLACK_WEBHOOK_ACTOR: IdentityActor = { kind: "system", id: "webhook:slack" };
+
+/**
+ * Three-step cascade used by every Slack webhook entry point to map a Slack
+ * user ID to a canonical `users.id`:
+ *
+ *   1. Look up the existing `(slack, <userId>)` mapping in `user_external_ids`.
+ *   2. If missing, enrich the Slack profile to extract an email; if found,
+ *      auto-link via `findOrCreateUserByEmail` + `linkIdentity`. Emits an
+ *      `auto_merge` (existing user) or `identity_added` (new user) event,
+ *      followed by an `identity_added` event for the Slack alias itself.
+ *   3. If no email is recoverable, record into the kv unmapped tracker so the
+ *      operator can triage manually. Returns `undefined` — task creation
+ *      proceeds without `requestedByUserId`.
+ *
+ * `eventContext` shapes the sample written to the unmapped tracker — the
+ * sample is truncated to 100 chars inside `recordUnmappedIdentity`.
+ */
+export async function resolveSlackUserId(
+  client: WebClient,
+  slackUserId: string,
+  eventContext: { sampleEventType: string; sampleContext: string },
+): Promise<string | undefined> {
+  // 1. Fast path — existing alias.
+  const existing = findUserByExternalId("slack", slackUserId);
+  if (existing) return existing.id;
+
+  // 2. Enrich → auto-link by email.
+  const email = await enrichSlackUserEmail(client, slackUserId);
+  if (email) {
+    // Pull the cached name back out for the user-row hints. The kv read is
+    // cheap (single primary-key lookup) and avoids a second `users.info`.
+    const cached = getKv(ENRICHMENT_NAMESPACE, slackUserId);
+    const name = (cached?.value as EnrichedSlackUser | undefined)?.name ?? undefined;
+
+    const { user } = findOrCreateUserByEmail(email, { name }, SLACK_WEBHOOK_ACTOR);
+
+    // Link the Slack identity to whichever user we resolved to. PK collision
+    // on `(slack, <id>)` shouldn't happen — we just confirmed no existing
+    // mapping in step 1 — but guard defensively so a race doesn't 500 the
+    // webhook.
+    try {
+      linkIdentity(user.id, "slack", slackUserId, SLACK_WEBHOOK_ACTOR);
+    } catch (error) {
+      console.warn(
+        `[Slack] linkIdentity('slack', ${slackUserId}) failed — likely a concurrent enroll`,
+        error,
+      );
+    }
+
+    return user.id;
+  }
+
+  // 3. No email — track as unmapped.
+  recordUnmappedIdentity("slack", slackUserId, eventContext);
+  return undefined;
+}

package/src/slack/handlers.ts

@@ -6,13 +6,13 @@ import {
   getLeadAgent,
   getMostRecentTaskInThread,
   getTasksByAgentId,
-  resolveUser,
 } from "../be/db";
 import { resolveTemplate } from "../prompts/resolver";
 import { slackContextKey } from "../tasks/context-key";
 import { createTaskWithSiblingAwareness } from "../tasks/sibling-awareness";
 import { workflowEventBus } from "../workflows/event-bus";
 import { buildTreeBlocks, type TreeNode } from "./blocks";
+import { enrichSlackUserEmail, resolveSlackUserId } from "./enrich";
 import { wasEventSeen } from "./event-dedup";
 import type { SlackFile } from "./files";
 import { extractTaskFromMessage, hasOtherUserMention, routeMessage } from "./router";
@@ -34,9 +34,6 @@ const allowedUserIds = (process.env.SLACK_ALLOWED_USER_IDS || "")
 
 const filteringEnabled = allowedEmailDomains.length > 0 || allowedUserIds.length > 0;
 
-// Cache for user email lookups (to avoid repeated API calls)
-const userEmailCache = new Map<string, string | null>();
-
 /**
  * Configuration for user filtering.
  */
@@ -110,19 +107,8 @@ async function isUserAllowed(client: WebClient, userId: string): Promise<boolean
     return false;
   }
 
-  // Check email domain
-  let email = userEmailCache.get(userId);
-  if (email === undefined) {
-    try {
-      const result = await client.users.info({ user: userId });
-      email = result.user?.profile?.email || null;
-      userEmailCache.set(userId, email);
-    } catch (error) {
-      console.error(`[Slack] Failed to fetch user email for ${userId}:`, error);
-      userEmailCache.set(userId, null);
-      email = null;
-    }
-  }
+  // Check email domain — uses kv-backed enrichment (24h TTL, only success cached).
+  const email = await enrichSlackUserEmail(client, userId);
 
   if (!email) {
     console.log(`[Slack] User ${userId} has no email, denying access`);
@@ -391,8 +377,14 @@ export function registerMessageHandler(app: App): void {
       return;
     }
 
-    // Resolve canonical user identity (graceful — null if not found)
-    const requestedByUserId = resolveUser({ slackUserId: msg.user })?.id;
+    // Resolve canonical user identity via the three-step cascade:
+    //   fast-path alias lookup → enrich+auto-link by email → unmapped tracker.
+    // Returns undefined when no email is recoverable; task creation proceeds
+    // without `requestedByUserId` and the operator triages from the Unmapped tab.
+    const requestedByUserId = await resolveSlackUserId(client, msg.user, {
+      sampleEventType: "message",
+      sampleContext: msg.text ?? "",
+    });
 
     // Emit workflow trigger event for Slack messages
     workflowEventBus.emit("slack.message", {