@vellumai/assistant 0.6.3 → 0.6.5

package/src/runtime/routes/inbound-message-handler.ts

@@ -19,10 +19,29 @@ import {
   recordConversationSeenSignal,
   type SignalType,
 } from "../../memory/conversation-attention-store.js";
+import {
+  addMessage,
+  countMessagesWithSlackMeta,
+  getMessageById,
+  getMessages,
+  updateMessageMetadata,
+} from "../../memory/conversation-crud.js";
 import * as deliveryChannels from "../../memory/delivery-channels.js";
 import * as deliveryCrud from "../../memory/delivery-crud.js";
 import * as deliveryStatus from "../../memory/delivery-status.js";
 import * as externalConversationStore from "../../memory/external-conversation-store.js";
+import type { Message as ProviderMessage } from "../../messaging/provider-types.js";
+import {
+  backfillDm,
+  backfillThread,
+} from "../../messaging/providers/slack/backfill.js";
+import {
+  mergeSlackMetadata,
+  readSlackMetadata,
+  type SlackMessageMetadata,
+  writeSlackMetadata,
+} from "../../messaging/providers/slack/message-metadata.js";
+import { wrapUntrustedContent } from "../../security/untrusted-content.js";
 import { canonicalizeInboundIdentity } from "../../util/canonicalize-identity.js";
 import { getLogger } from "../../util/logger.js";
 import { DAEMON_INTERNAL_ASSISTANT_ID } from "../assistant-scope.js";
@@ -52,6 +71,28 @@ import { handleVerificationIntercept } from "./inbound-stages/verification-inter
 
 const log = getLogger("runtime-http");
 
+// Delete-lookup retry configuration. Delete webhooks can race ahead of
+// the inbound handler's `linkMessage` call when the original message's
+// agent loop is still running. Retrying buys time for the link to land
+// before we drop the deletion signal. Mirrors the edit-intercept path's
+// EDIT_LOOKUP_RETRIES / EDIT_LOOKUP_DELAY_MS constants.
+let deleteLookupRetries = 5;
+let deleteLookupDelayMs = 2000;
+
+/**
+ * Test-only override for the delete-lookup retry timings. Used by
+ * tests that exercise the "no such message" path without waiting
+ * through the full production backoff. Not exported from any barrel
+ * file — only the test file imports it directly.
+ */
+export function _setDeleteLookupConfigForTests(
+  retries: number,
+  delayMs: number,
+): void {
+  deleteLookupRetries = retries;
+  deleteLookupDelayMs = delayMs;
+}
+
 export async function handleChannelInbound(
   req: Request,
   processMessage?: MessageProcessor,
@@ -238,6 +279,152 @@ export async function handleChannelInbound(
   if (aclResult.earlyResponse) return aclResult.earlyResponse;
   const { resolvedMember, guardianVerifyCode } = aclResult;
 
+  // ── Slack delete propagation ──
+  // Slack message_deleted events are forwarded by the gateway with the
+  // sentinel `callbackData = "message_deleted"` and `sourceMetadata.messageId`
+  // set to the original (deleted) message's ts. Short-circuit the rest of
+  // the pipeline: the agent loop should not run for delete notifications,
+  // and routing the event through approval / agent paths would be incorrect.
+  // We mark the stored row as deleted in slackMeta but leave `content`
+  // untouched for audit purposes — rendering elides based on the deletedAt
+  // marker. Gated behind ingress ACL so non-members cannot drive deletes
+  // (matches the edit-intercept policy).
+  if (sourceChannel === "slack" && body.callbackData === "message_deleted") {
+    const deletedMessageTs =
+      typeof sourceMetadata?.messageId === "string"
+        ? sourceMetadata.messageId
+        : undefined;
+
+    if (!deletedMessageTs) {
+      log.debug(
+        { conversationExternalId },
+        "Slack message_deleted event missing sourceMetadata.messageId; ignoring",
+      );
+      return Response.json({ accepted: true, deleted: false });
+    }
+
+    // Look up the stored message via the existing channel-event lookup.
+    // The original message's externalMessageId may differ from its ts
+    // (Slack populates client_msg_id when present), so we join via the
+    // sourceMessageId column which records the ts explicitly.
+    //
+    // Retry with backoff mirrors the edit-intercept path: delete webhooks
+    // can race ahead of `linkMessage` when the original message's agent
+    // loop is still running. Without retries a delete that arrives in
+    // that window is silently dropped and the deletion signal is lost.
+    let original: { messageId: string; conversationId: string } | null = null;
+    for (let attempt = 0; attempt <= deleteLookupRetries; attempt++) {
+      original = deliveryCrud.findMessageBySourceId(
+        sourceChannel,
+        conversationExternalId,
+        deletedMessageTs,
+      );
+      if (original) break;
+      if (attempt < deleteLookupRetries) {
+        log.info(
+          {
+            conversationExternalId,
+            deletedMessageTs,
+            attempt: attempt + 1,
+            maxAttempts: deleteLookupRetries,
+          },
+          "Original message not linked yet, retrying delete lookup",
+        );
+        await new Promise((resolve) =>
+          setTimeout(resolve, deleteLookupDelayMs),
+        );
+      }
+    }
+
+    if (!original) {
+      log.debug(
+        { conversationExternalId, deletedMessageTs },
+        "No stored message found for Slack delete after retries; ignoring",
+      );
+      return Response.json({ accepted: true, deleted: false });
+    }
+
+    // Merge deletedAt into the existing slackMeta sub-key. If the row has
+    // no slackMeta (legacy pre-upgrade row), skip — the renderer's flat
+    // fallback ignores deletedAt for those rows anyway, and synthesizing
+    // a partial slackMeta here would produce metadata that fails
+    // readSlackMetadata validation.
+    const row = getMessageById(original.messageId);
+    if (!row?.metadata) {
+      log.debug(
+        {
+          conversationExternalId,
+          deletedMessageTs,
+          messageId: original.messageId,
+        },
+        "Stored Slack message has no metadata; skipping delete marker",
+      );
+      return Response.json({ accepted: true, deleted: false });
+    }
+
+    let parentMetadata: Record<string, unknown>;
+    try {
+      const parsed = JSON.parse(row.metadata) as unknown;
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        parentMetadata = parsed as Record<string, unknown>;
+      } else {
+        parentMetadata = {};
+      }
+    } catch {
+      log.debug(
+        {
+          conversationExternalId,
+          deletedMessageTs,
+          messageId: original.messageId,
+        },
+        "Failed to parse stored metadata; skipping delete marker",
+      );
+      return Response.json({ accepted: true, deleted: false });
+    }
+
+    const existingSlackMeta =
+      typeof parentMetadata.slackMeta === "string"
+        ? parentMetadata.slackMeta
+        : null;
+
+    if (!existingSlackMeta) {
+      log.debug(
+        {
+          conversationExternalId,
+          deletedMessageTs,
+          messageId: original.messageId,
+        },
+        "Stored Slack message has no slackMeta; skipping delete marker",
+      );
+      return Response.json({ accepted: true, deleted: false });
+    }
+
+    const updatedSlackMeta = mergeSlackMetadata(existingSlackMeta, {
+      deletedAt: Date.now(),
+    });
+
+    // updateMessageMetadata performs a shallow merge over the parent
+    // metadata, replacing only `slackMeta` and leaving sibling keys
+    // (channel, interface, provenance, etc.) untouched. Content column
+    // is intentionally not updated.
+    updateMessageMetadata(original.messageId, { slackMeta: updatedSlackMeta });
+
+    log.info(
+      {
+        conversationExternalId,
+        deletedMessageTs,
+        messageId: original.messageId,
+      },
+      "Marked Slack message as deleted",
+    );
+
+    return Response.json({
+      accepted: true,
+      deleted: true,
+      messageId: original.messageId,
+    });
+  }
+
   if (hasAttachments) {
     const resolved = attachmentsStore.getAttachmentsByIds(attachmentIds);
     if (resolved.length !== attachmentIds.length) {
@@ -369,6 +556,119 @@ export async function handleChannelInbound(
     });
   }
 
+  // ── Slack reaction handling ──
+  // Reactions arrive as regular `SlackInboundEvent`s with `callbackData`
+  // prefixed `reaction:` (added) or `reaction_removed:` (removed).
+  //
+  // Two paths from here:
+  //   1. Guardian approval-by-reaction. A `reaction:` (added) event from
+  //      the guardian on an active approval prompt is consumed by
+  //      `handleApprovalInterception` to apply the decision. In that case
+  //      we do NOT persist the reaction as a transcript line — resolved
+  //      guardian approval reactions have no transcript representation.
+  //   2. All other reactions (non-guardian, no pending approval, stale,
+  //      and any `reaction_removed:` event regardless of actor) fall
+  //      through to `persistSlackReactionAsMessage` so the chronological
+  //      renderer (PR 18) can surface them inline. Reactions never
+  //      trigger an agent response, so we short-circuit before
+  //      escalation and agent-loop dispatch in both cases.
+  if (isSlackReactionEvent(body)) {
+    // Approval interception runs only for reactions (added) — `reaction_removed`
+    // never expresses an approval intent, so un-reacting is left as a pure
+    // transcript signal. Gated by the same `replyCallbackUrl && !duplicate`
+    // preconditions used by the standard approval interception call below.
+    const isReactionAdded = body.callbackData?.startsWith("reaction:") === true;
+    if (isReactionAdded && replyCallbackUrl && !result.duplicate) {
+      const trustCtxForReaction: TrustContext = resolveTrustContext({
+        assistantId: canonicalAssistantId,
+        sourceChannel,
+        conversationExternalId,
+        actorExternalId: rawSenderId,
+        actorUsername: body.actorUsername,
+        actorDisplayName: body.actorDisplayName,
+      });
+
+      const approvalMessageTs =
+        typeof sourceMetadata?.messageId === "string"
+          ? sourceMetadata.messageId
+          : undefined;
+
+      const reactionApprovalResult = await handleApprovalInterception({
+        conversationId: result.conversationId,
+        callbackData: body.callbackData,
+        content: trimmedContent,
+        conversationExternalId,
+        sourceChannel,
+        actorExternalId: canonicalSenderId ?? rawSenderId,
+        replyCallbackUrl,
+        bearerToken: mintBearerToken(),
+        trustCtx: trustCtxForReaction,
+        assistantId: canonicalAssistantId,
+        approvalCopyGenerator,
+        approvalConversationGenerator,
+        approvalMessageTs,
+      });
+
+      // A real guardian decision was applied — short-circuit and skip the
+      // reaction-persistence path so we do not double-record it as a
+      // transcript line. All other interception outcomes (stale_ignored,
+      // non-guardian, no pending approval) fall through to persistence.
+      if (reactionApprovalResult.type === "guardian_decision_applied") {
+        return Response.json({
+          accepted: true,
+          duplicate: false,
+          eventId: result.eventId,
+          approval: reactionApprovalResult.type,
+        });
+      }
+    }
+
+    const reactedMessageTs =
+      typeof sourceMetadata?.messageId === "string"
+        ? sourceMetadata.messageId
+        : undefined;
+    if (!reactedMessageTs) {
+      log.debug(
+        { conversationId: result.conversationId, eventId: result.eventId },
+        "Skipping reaction persistence: missing sourceMetadata.messageId",
+      );
+      return Response.json({
+        accepted: result.accepted,
+        duplicate: result.duplicate,
+        eventId: result.eventId,
+      });
+    }
+
+    const threadTs =
+      typeof sourceMetadata?.threadId === "string"
+        ? sourceMetadata.threadId
+        : undefined;
+
+    try {
+      await persistSlackReactionAsMessage({
+        conversationId: result.conversationId,
+        conversationExternalId,
+        eventId: result.eventId,
+        callbackData: body.callbackData!,
+        actorDisplayName: body.actorDisplayName,
+        threadTs,
+        reactedMessageTs,
+        duplicate: result.duplicate,
+      });
+    } catch (err) {
+      log.error(
+        { err, conversationId: result.conversationId, eventId: result.eventId },
+        "Failed to persist Slack reaction event",
+      );
+    }
+
+    return Response.json({
+      accepted: result.accepted,
+      duplicate: result.duplicate,
+      eventId: result.eventId,
+    });
+  }
+
   // ── Ingress escalation ──
   const escalationResponse = handleEscalationIntercept({
     resolvedMember,
@@ -606,7 +906,13 @@ export async function handleChannelInbound(
     // of whether content/attachments are present — callback payloads always
     // have non-empty content (normalize.ts sets message.content to cbq.data),
     // so checking for empty content alone would miss stale callbacks.
-    if (hasCallbackData) {
+    //
+    // Reaction events (`reaction:` / `reaction_removed:`) are persisted by
+    // the earlier `isSlackReactionEvent` branch and never reach here; guard
+    // explicitly so a future refactor can't let a reaction ts drive a
+    // "This approval request has been resolved." edit that would clobber
+    // the user's reacted-to message.
+    if (hasCallbackData && !isSlackReactionEvent(body)) {
       // Record seen signal even for stale callbacks — the user still interacted
       if (sourceChannel === "telegram" || sourceChannel === "slack") {
         try {
@@ -698,6 +1004,93 @@ export async function handleChannelInbound(
         heartbeatService?.resetTimer();
       }
 
+      // Slack inbound metadata captured for thread-aware persistence. The
+      // gateway forwards `thread_ts` under `sourceMetadata.threadId` and the
+      // message's own ts under `sourceMetadata.messageId`. Persistence turns
+      // this into a `slackMeta` sub-object in the row's metadata column so
+      // the chronological renderer can reconstruct thread structure without
+      // re-fetching from Slack.
+      const slackThreadTs =
+        sourceChannel === "slack" &&
+        typeof sourceMetadata?.threadId === "string"
+          ? sourceMetadata.threadId
+          : undefined;
+      const slackInbound =
+        sourceChannel === "slack"
+          ? {
+              channelId: conversationExternalId,
+              channelTs: sourceMessageId ?? externalMessageId,
+              ...(slackThreadTs ? { threadTs: slackThreadTs } : {}),
+              ...((body.actorDisplayName ?? body.actorUsername)
+                ? {
+                    displayName: body.actorDisplayName ?? body.actorUsername!,
+                  }
+                : {}),
+            }
+          : undefined;
+
+      // Account identifier threaded into backfill so `resolveConnection()`
+      // can pick the right workspace in multi-account setups. Best-effort:
+      // the gateway forwards `sourceMetadata.account` when it knows which
+      // Slack workspace the event came from; when absent, both helpers
+      // fall back to the default-active connection.
+      const slackAccount =
+        sourceChannel === "slack" &&
+        typeof sourceMetadata?.account === "string" &&
+        sourceMetadata.account.length > 0
+          ? sourceMetadata.account
+          : undefined;
+
+      // ── DM cold-start backfill ──
+      // First time a Slack DM lands in a conversation that has fewer than
+      // SLACK_DM_BACKFILL_WARM_THRESHOLD stored slackMeta messages, fetch a
+      // window of recent history so the agent sees prior context. One-shot:
+      // once persistence warms up past the threshold, subsequent DMs no
+      // longer trigger backfill. Failures are non-fatal — the new message
+      // proceeds without backfilled history.
+      if (sourceChannel === "slack" && sourceChatType === "im") {
+        await tryBackfillSlackDmIfCold({
+          conversationId: result.conversationId,
+          channelId: conversationExternalId,
+          account: slackAccount,
+          // Exclude the just-arrived webhook message from the history window —
+          // the normal inbound persistence path writes it separately, so
+          // including it here would produce duplicate user turns.
+          latestTs: slackInbound?.channelTs,
+        });
+      }
+
+      // ── Thread-ancestor backfill ──
+      // When a Slack reply arrives for a thread the daemon never saw the
+      // parent of, fetch the thread's recent history from Slack and persist
+      // the missing messages so the chronological renderer (PR 18) has the
+      // full conversation. Awaited (mirrors the DM cold-start path above)
+      // so the agent loop dispatched immediately afterwards observes the
+      // backfilled parent — without this, `loadSlackChronologicalMessages`
+      // can race the persist and miss thread context. Backfill is bounded
+      // (parent + ~50 messages) and the agent latency is dominated by the
+      // LLM call, so the added latency is negligible. Failures are
+      // swallowed inside the helper so they never block dispatch.
+      if (slackThreadTs) {
+        await triggerSlackThreadBackfillIfNeeded({
+          conversationId: result.conversationId,
+          channelId: conversationExternalId,
+          threadTs: slackThreadTs,
+          excludeChannelTs: slackInbound?.channelTs,
+          account: slackAccount,
+        });
+      }
+
+      // Wrap non-guardian inbound content in external_content boundaries so
+      // the model can distinguish external channel messages from instructions.
+      const contentForProcessing =
+        trustCtx.trustClass !== "guardian"
+          ? wrapUntrustedContent(trimmedContent, {
+              source: "webhook",
+              sourceDetail: trustCtx.requesterIdentifier,
+            })
+          : trimmedContent;
+
       // Fire-and-forget: process the message and deliver the reply in the background.
       // The HTTP response returns immediately so the gateway webhook is not blocked.
       // The onEvent callback in processMessage registers pending interactions, and
@@ -706,7 +1099,7 @@ export async function handleChannelInbound(
         processMessage,
         conversationId: result.conversationId,
         eventId: result.eventId,
-        content: trimmedContent,
+        content: contentForProcessing,
         attachmentIds: hasAttachments ? attachmentIds : undefined,
         sourceChannel,
         sourceInterface,
@@ -721,6 +1114,7 @@ export async function handleChannelInbound(
         assistantId: canonicalAssistantId,
         approvalCopyGenerator,
         chatType: sourceChatType,
+        slackInbound,
       });
     }
   }
@@ -731,3 +1125,519 @@ export async function handleChannelInbound(
     eventId: result.eventId,
   });
 }
+
+/**
+ * Detect a Slack reaction event by inspecting the inbound payload's
+ * `callbackData` prefix. The gateway encodes reactions as a unified
+ * `SlackInboundEvent` with `callbackData` of the form
+ * `reaction:<emoji>` (added) or `reaction_removed:<emoji>` (removed) —
+ * see `gateway/src/slack/normalize.ts`. This helper centralizes that
+ * convention so the daemon can route reactions to a dedicated persistence
+ * branch instead of the agent-response pipeline.
+ */
+export function isSlackReactionEvent(body: {
+  sourceChannel?: string;
+  callbackData?: string;
+}): boolean {
+  if (body.sourceChannel !== "slack") return false;
+  const cb = body.callbackData;
+  if (typeof cb !== "string") return false;
+  return cb.startsWith("reaction:") || cb.startsWith("reaction_removed:");
+}
+
+/**
+ * Parse a reaction `callbackData` string into its op (added/removed) and
+ * emoji name. Returns `null` when the input is not a reaction prefix or
+ * when the emoji portion is empty.
+ */
+export function parseSlackReactionCallbackData(
+  callbackData: string,
+): { op: "added" | "removed"; emoji: string } | null {
+  let op: "added" | "removed";
+  let emoji: string;
+  if (callbackData.startsWith("reaction_removed:")) {
+    op = "removed";
+    emoji = callbackData.slice("reaction_removed:".length);
+  } else if (callbackData.startsWith("reaction:")) {
+    op = "added";
+    emoji = callbackData.slice("reaction:".length);
+  } else {
+    return null;
+  }
+  if (emoji.length === 0) return null;
+  return { op, emoji };
+}
+
+/**
+ * Persist a Slack reaction event as a `messages` row with `slackMeta`
+ * envelope so the renderer can surface it inline in the chronological
+ * transcript. Reactions do not trigger an agent response — the row is
+ * written and the inbound event is linked, but the agent loop is not
+ * dispatched.
+ *
+ * The caller is expected to have run `recordInbound` already so that
+ * deduplication and conversation resolution have happened. Duplicate
+ * inbound events are skipped here to keep persistence idempotent.
+ */
+async function persistSlackReactionAsMessage(params: {
+  conversationId: string;
+  conversationExternalId: string;
+  eventId: string;
+  callbackData: string;
+  actorDisplayName?: string;
+  threadTs?: string;
+  reactedMessageTs: string;
+  duplicate: boolean;
+}): Promise<void> {
+  if (params.duplicate) return;
+
+  const parsed = parseSlackReactionCallbackData(params.callbackData);
+  if (!parsed) {
+    log.debug(
+      {
+        conversationId: params.conversationId,
+        callbackData: params.callbackData,
+      },
+      "Skipping reaction persistence: unparseable callbackData",
+    );
+    return;
+  }
+
+  const slackMeta: SlackMessageMetadata = {
+    source: "slack",
+    channelId: params.conversationExternalId,
+    channelTs: params.reactedMessageTs,
+    eventKind: "reaction",
+    ...(params.threadTs ? { threadTs: params.threadTs } : {}),
+    ...(params.actorDisplayName
+      ? { displayName: params.actorDisplayName }
+      : {}),
+    reaction: {
+      emoji: parsed.emoji,
+      targetChannelTs: params.reactedMessageTs,
+      op: parsed.op,
+      ...(params.actorDisplayName
+        ? { actorDisplayName: params.actorDisplayName }
+        : {}),
+    },
+  };
+
+  // Sentinel content — renderers (PR 18) read `slackMeta` to format the
+  // reaction line; the literal text is never displayed to the model.
+  const persisted = await addMessage(
+    params.conversationId,
+    "user",
+    "[reaction]",
+    { slackMeta: writeSlackMetadata(slackMeta) },
+    { skipIndexing: true },
+  );
+  deliveryCrud.linkMessage(params.eventId, persisted.id);
+  deliveryStatus.markProcessed(params.eventId);
+}
+
+/**
+ * Threshold of stored Slack-tagged messages below which a conversation is
+ * considered "cold" and eligible for one-shot backfill. The number is
+ * deliberately small but greater than 1 so a single sentinel row (e.g. a
+ * stale reaction) does not disqualify a conversation that has no real
+ * message history yet.
+ */
+const SLACK_DM_BACKFILL_WARM_THRESHOLD = 3;
+
+/**
+ * Count messages in a conversation whose `metadata` carries a `slackMeta`
+ * envelope, capped at the warm threshold. Delegates to the DB helper which
+ * pushes both `LIKE` and `LIMIT` into SQL so a warm DM conversation never
+ * scans beyond the threshold's worth of rows on the webhook critical path.
+ */
+function countSlackMetaMessages(conversationId: string): number {
+  return countMessagesWithSlackMeta(
+    conversationId,
+    SLACK_DM_BACKFILL_WARM_THRESHOLD,
+  );
+}
+
+/**
+ * Build the set of `slackMeta.channelTs` values already stored on a
+ * conversation. Used by both DM cold-start backfill and thread-ancestor
+ * backfill to dedupe rows so a partial prior backfill (or a single message
+ * that was already persisted via the live ingress path) does not double-write.
+ */
+function readStoredSlackChannelTs(conversationId: string): Set<string> {
+  const seen = new Set<string>();
+  for (const row of getMessages(conversationId)) {
+    if (!row.metadata) continue;
+    let parent: Record<string, unknown> | null = null;
+    try {
+      const parsed = JSON.parse(row.metadata) as unknown;
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        parent = parsed as Record<string, unknown>;
+      }
+    } catch {
+      continue;
+    }
+    if (!parent) continue;
+    const raw = parent.slackMeta;
+    if (typeof raw !== "string") continue;
+    const meta = readSlackMetadata(raw);
+    // Only message rows represent stored Slack messages. Reaction rows carry
+    // `channelTs` equal to the target message's ts, so including them would
+    // make a reaction on a thread parent wrongly short-circuit ancestor
+    // backfill (the parent itself may still be unseen).
+    if (meta && meta.eventKind === "message") seen.add(meta.channelTs);
+  }
+  return seen;
+}
+
+/**
+ * Persist a single backfilled Slack message as a `messages` row with a
+ * `slackMeta` envelope.
+ *
+ * Shared insertion point for any path that hydrates Slack history lazily
+ * (DM cold-start backfill, thread-ancestor backfill, etc.). Role is derived
+ * from `message.metadata.isBot` — bot-authored rows map to `"assistant"` so
+ * our own prior replies (and any other bot traffic) are not rehydrated as
+ * user turns, which would otherwise corrupt speaker attribution and make
+ * the assistant treat its own outputs as new user input on later turns.
+ * Caller is responsible for dedup checks before invoking; this helper
+ * performs no idempotency check itself.
+ */
+async function persistBackfilledSlackMessage(params: {
+  conversationId: string;
+  channelId: string;
+  message: ProviderMessage;
+}): Promise<void> {
+  const { message } = params;
+  const slackMeta: SlackMessageMetadata = {
+    source: "slack",
+    channelId: params.channelId,
+    channelTs: message.id,
+    eventKind: "message",
+    ...(message.threadId ? { threadTs: message.threadId } : {}),
+    ...(message.sender?.name ? { displayName: message.sender.name } : {}),
+  };
+  const role = message.metadata?.isBot === true ? "assistant" : "user";
+  await addMessage(params.conversationId, role, message.text ?? "", {
+    slackMeta: writeSlackMetadata(slackMeta),
+  });
+}
+
+/**
+ * In-memory map of in-flight DM cold-start backfills keyed by conversationId.
+ * Concurrent inbound DMs to the same cold conversation share a single
+ * backfill promise instead of each issuing their own Slack history fetch and
+ * write — without this, two near-simultaneous DMs would both observe a cold
+ * count, both fetch the same history window, and both insert duplicate rows
+ * (channelTs lives inside a JSON metadata blob, so the DB has no uniqueness
+ * constraint to fall back on).
+ */
+const _dmBackfillInFlight = new Map<string, Promise<void>>();
+
+/**
+ * One-shot DM cold-start backfill. When a Slack DM lands in a conversation
+ * with fewer than `SLACK_DM_BACKFILL_WARM_THRESHOLD` stored Slack-tagged
+ * messages, fetch a window of recent history via `backfillDm` and persist
+ * each returned message with a `slackMeta` envelope. Already-stored
+ * messages (matched by `slackMeta.channelTs`) are skipped to keep the
+ * operation idempotent across retries.
+ *
+ * Failure semantics: any error is logged at WARN and swallowed. The caller
+ * proceeds with only the new message.
+ */
+async function tryBackfillSlackDmIfCold(params: {
+  conversationId: string;
+  channelId: string;
+  account?: string;
+  latestTs?: string;
+}): Promise<void> {
+  const existing = _dmBackfillInFlight.get(params.conversationId);
+  if (existing) {
+    await existing;
+    return;
+  }
+  const promise = runBackfillSlackDmIfCold(params).finally(() => {
+    _dmBackfillInFlight.delete(params.conversationId);
+  });
+  _dmBackfillInFlight.set(params.conversationId, promise);
+  await promise;
+}
+
+async function runBackfillSlackDmIfCold(params: {
+  conversationId: string;
+  channelId: string;
+  account?: string;
+  latestTs?: string;
+}): Promise<void> {
+  try {
+    const storedCount = countSlackMetaMessages(params.conversationId);
+    if (storedCount >= SLACK_DM_BACKFILL_WARM_THRESHOLD) {
+      return;
+    }
+
+    // Pass the webhook message's ts as `before` (Slack's `latest`,
+    // exclusive) so history never contains the message that's about to be
+    // persisted by the live inbound path. Without this bound the just-arrived
+    // DM would be written twice — once here and once via normal persistence —
+    // producing duplicate user turns.
+    const fetched = await backfillDm(params.channelId, {
+      limit: 50,
+      account: params.account,
+      before: params.latestTs,
+    });
+    if (fetched.length === 0) {
+      log.debug(
+        { conversationId: params.conversationId, channelId: params.channelId },
+        "DM backfill returned no messages",
+      );
+      return;
+    }
+
+    const seen = readStoredSlackChannelTs(params.conversationId);
+    let written = 0;
+    // Slack's conversation.history returns most-recent first. Reverse so
+    // rows insert in chronological order, giving stable createdAt ordering
+    // and a transcript that reads correctly when the renderer joins on
+    // monotonic createdAt.
+    const ordered = [...fetched].reverse();
+    for (const message of ordered) {
+      if (seen.has(message.id)) continue;
+      try {
+        await persistBackfilledSlackMessage({
+          conversationId: params.conversationId,
+          channelId: params.channelId,
+          message,
+        });
+        seen.add(message.id);
+        written++;
+      } catch (perRowErr) {
+        log.warn(
+          {
+            err: perRowErr,
+            conversationId: params.conversationId,
+            channelId: params.channelId,
+            channelTs: message.id,
+          },
+          "Failed to persist backfilled DM row; continuing",
+        );
+      }
+    }
+
+    log.info(
+      {
+        conversationId: params.conversationId,
+        channelId: params.channelId,
+        fetched: fetched.length,
+        written,
+      },
+      "DM cold-start backfill complete",
+    );
+  } catch (err) {
+    // `channel_not_found` almost always means the resolved connection is
+    // pointing at the wrong Slack workspace (a real config bug), so log it
+    // at ERROR to match backfill's rethrow contract. Other failures
+    // (timeout, auth, ratelimited, …) stay at WARN — they're expected
+    // transient blips and the caller proceeds without backfilled history.
+    const channelNotFound =
+      err instanceof Error && /channel_not_found/i.test(err.message);
+    const payload = {
+      err,
+      conversationId: params.conversationId,
+      channelId: params.channelId,
+      account: params.account,
+    };
+    if (channelNotFound) {
+      log.error(
+        payload,
+        "DM cold-start backfill hit channel_not_found — connection likely points at the wrong Slack workspace",
+      );
+    } else {
+      log.warn(
+        payload,
+        "DM cold-start backfill failed; proceeding without history",
+      );
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Slack thread backfill on gap detection
+// ---------------------------------------------------------------------------
+
+/**
+ * In-memory TTL cache keyed by `<conversationId>:<threadTs>`. Tracks recent
+ * thread-backfill triggers so a burst of replies inside the same Slack
+ * thread (e.g. a guardian rapidly typing several lines) does not re-fetch
+ * the same parent messages from Slack repeatedly. Entries naturally fall
+ * out after the TTL — if the thread is still active later, a fresh
+ * backfill becomes a cheap "are the parents already stored?" DB lookup
+ * that short-circuits before the Slack API is touched.
+ *
+ * Exported only for tests; production callers should use
+ * {@link triggerSlackThreadBackfillIfNeeded}.
+ */
+export const _backfillTriggerCache = new Map<string, number>();
+
+const BACKFILL_TRIGGER_TTL_MS = 10 * 60 * 1000; // 10 minutes
+const BACKFILL_TRIGGER_CACHE_MAX = 1_000;
+
+function pruneBackfillCacheIfNeeded(): void {
+  if (_backfillTriggerCache.size < BACKFILL_TRIGGER_CACHE_MAX) return;
+  const now = Date.now();
+  for (const [key, ts] of _backfillTriggerCache) {
+    if (now - ts >= BACKFILL_TRIGGER_TTL_MS) {
+      _backfillTriggerCache.delete(key);
+    }
+  }
+  // If still over the cap after TTL sweep, drop the oldest entries (LRU-ish).
+  if (_backfillTriggerCache.size >= BACKFILL_TRIGGER_CACHE_MAX) {
+    const entries = [..._backfillTriggerCache.entries()].sort(
+      (a, b) => a[1] - b[1],
+    );
+    const toRemove = entries.slice(
+      0,
+      entries.length - BACKFILL_TRIGGER_CACHE_MAX + 1,
+    );
+    for (const [key] of toRemove) {
+      _backfillTriggerCache.delete(key);
+    }
+  }
+}
+
+function isBackfillRecentlyTriggered(cacheKey: string): boolean {
+  const ts = _backfillTriggerCache.get(cacheKey);
+  if (ts === undefined) return false;
+  if (Date.now() - ts >= BACKFILL_TRIGGER_TTL_MS) {
+    _backfillTriggerCache.delete(cacheKey);
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Lazily backfill missing Slack thread ancestors for an inbound thread reply.
+ *
+ * When a reply arrives for a thread the daemon has never seen (e.g. the bot
+ * was just added to the channel, or the parent message pre-dates the
+ * conversation), the daemon fetches the thread's recent history via
+ * {@link backfillThread}, persists each unseen message as a `messages` row
+ * with a `slackMeta` envelope, and skips duplicates whose `ts` already
+ * appears in the conversation.
+ *
+ * Behavior contracts:
+ * - **No-op when the parent is already stored.** Looks up the conversation's
+ *   messages and short-circuits if any row has `slackMeta.channelTs ===
+ *   threadTs`. This keeps subsequent replies in the same thread cheap.
+ * - **TTL idempotency cache.** A 10-minute in-memory cache prevents bursts
+ *   of replies in the same thread from re-running the DB lookup or the
+ *   Slack API call.
+ * - **Failure-tolerant.** Any error (Slack API failure, DB error, malformed
+ *   payload) is logged at `warn` and swallowed — the inbound turn must
+ *   never block on backfill.
+ */
+export async function triggerSlackThreadBackfillIfNeeded(params: {
+  conversationId: string;
+  channelId: string;
+  threadTs: string;
+  /**
+   * The inbound message's own `channelTs`. Pre-seeded into the dedup set so
+   * this helper does not re-persist the just-received message when Slack's
+   * `conversations.replies` returns it in the thread window. Necessary
+   * because thread backfill runs concurrently with
+   * `processChannelMessageInBackground`, so the inbound row may not yet be
+   * in the DB when `readStoredSlackChannelTs` snapshots the conversation.
+   */
+  excludeChannelTs?: string;
+  /**
+   * OAuth account identifier used to disambiguate which Slack workspace the
+   * backfill should read from in multi-account setups. Passed through to
+   * `backfillThread` → `resolveConnection`. Best-effort: if omitted, the
+   * resolver falls back to the default-active connection.
+   */
+  account?: string;
+}): Promise<void> {
+  const { conversationId, channelId, threadTs, excludeChannelTs, account } =
+    params;
+  const cacheKey = `${conversationId}:${threadTs}`;
+
+  try {
+    if (isBackfillRecentlyTriggered(cacheKey)) {
+      return;
+    }
+
+    const storedChannelTs = readStoredSlackChannelTs(conversationId);
+    if (excludeChannelTs) storedChannelTs.add(excludeChannelTs);
+    if (storedChannelTs.has(threadTs)) {
+      // Parent is already in the conversation; mark the cache so a burst of
+      // replies in this thread does not redo the DB scan for each one.
+      _backfillTriggerCache.set(cacheKey, Date.now());
+      pruneBackfillCacheIfNeeded();
+      return;
+    }
+
+    // Mark the trigger before issuing the network call. Doing this first
+    // means a second concurrent reply in the same thread short-circuits
+    // immediately even while the first call is still awaiting the Slack
+    // API. The cost is a slightly larger window where a transient Slack
+    // failure suppresses a retry, which the next reply outside the TTL
+    // (or a daemon restart) will re-attempt anyway.
+    _backfillTriggerCache.set(cacheKey, Date.now());
+    pruneBackfillCacheIfNeeded();
+
+    const fetched = await backfillThread(channelId, threadTs, { account });
+    if (fetched.length === 0) {
+      log.debug(
+        { conversationId, channelId, threadTs },
+        "Slack thread backfill returned no messages",
+      );
+      return;
+    }
+
+    let persisted = 0;
+    for (const message of fetched) {
+      if (!message.id) continue;
+      if (storedChannelTs.has(message.id)) continue;
+      try {
+        await persistBackfilledSlackMessage({
+          conversationId,
+          channelId,
+          message,
+        });
+        storedChannelTs.add(message.id);
+        persisted++;
+      } catch (err) {
+        log.warn(
+          { err, conversationId, channelId, threadTs, channelTs: message.id },
+          "Failed to persist backfilled Slack thread message",
+        );
+      }
+    }
+
+    log.info(
+      {
+        conversationId,
+        channelId,
+        threadTs,
+        persisted,
+        fetched: fetched.length,
+      },
+      "Slack thread backfill persisted ancestor messages",
+    );
+  } catch (err) {
+    // `channel_not_found` almost always means the resolved connection is
+    // pointing at the wrong Slack workspace (a real config bug), so log it
+    // at ERROR to match backfill's rethrow contract. Other failures
+    // (timeout, auth, ratelimited, …) stay at WARN — they're expected
+    // transient blips and dispatch proceeds without the ancestors.
+    const channelNotFound =
+      err instanceof Error && /channel_not_found/i.test(err.message);
+    const payload = { err, conversationId, channelId, threadTs, account };
+    if (channelNotFound) {
+      log.error(
+        payload,
+        "Slack thread backfill hit channel_not_found — connection likely points at the wrong Slack workspace",
+      );
+    } else {
+      log.warn(payload, "Slack thread backfill failed; proceeding without it");
+    }
+  }
+}