@vellumai/assistant 0.6.6 → 0.7.1

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

@@ -12,9 +12,14 @@ import {
   parseInterfaceId,
 } from "../../channels/types.js";
 import { touchContactInteraction } from "../../contacts/contacts-write.js";
-import type { TrustContext } from "../../daemon/conversation-runtime-assembly.js";
-import type { HeartbeatService } from "../../heartbeat/heartbeat-service.js";
-import * as attachmentsStore from "../../memory/attachments-store.js";
+import {
+  createApprovalConversationGenerator,
+  createApprovalCopyGenerator,
+} from "../../daemon/approval-generators.js";
+import { processMessage } from "../../daemon/process-message.js";
+import type { TrustContext } from "../../daemon/trust-context.js";
+import { HeartbeatService } from "../../heartbeat/heartbeat-service.js";
+import { getAttachmentsByIds } from "../../memory/attachments-store.js";
 import {
   recordConversationSeenSignal,
   type SignalType,
@@ -26,18 +31,27 @@ import {
   selectSlackMetaCandidateMetadata,
   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 {
+  clearPendingVerificationReply,
+  getPendingVerificationReply,
+} from "../../memory/delivery-channels.js";
+import {
+  findMessageBySourceId,
+  linkMessage,
+  recordInbound,
+} from "../../memory/delivery-crud.js";
+import { markProcessed } from "../../memory/delivery-status.js";
+import { upsertBinding } from "../../memory/external-conversation-store.js";
 import type { Message as ProviderMessage } from "../../messaging/provider-types.js";
 import {
   backfillDm,
-  backfillThread,
+  backfillThreadWindowPage,
+  type SlackBackfillWindowPage,
 } from "../../messaging/providers/slack/backfill.js";
 import {
   mergeSlackMetadata,
   readSlackMetadata,
+  type SlackFileMetadata,
   type SlackMessageMetadata,
   writeSlackMetadata,
 } from "../../messaging/providers/slack/message-metadata.js";
@@ -45,18 +59,10 @@ 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";
-import { mintDaemonDeliveryToken } from "../auth/token-service.js";
 import { deliverChannelReply } from "../gateway-client.js";
-import { httpError } from "../http-errors.js";
-import type {
-  ApprovalConversationGenerator,
-  ApprovalCopyGenerator,
-  GuardianActionCopyGenerator,
-  GuardianFollowUpConversationGenerator,
-  MessageProcessor,
-} from "../http-types.js";
 import { resolveTrustContext } from "../trust-context-resolver.js";
 import { canonicalChannelAssistantId } from "./channel-route-shared.js";
+import { BadRequestError } from "./errors.js";
 import { handleApprovalInterception } from "./guardian-approval-interception.js";
 import { enforceIngressAcl } from "./inbound-stages/acl-enforcement.js";
 import { processChannelMessageInBackground } from "./inbound-stages/background-dispatch.js";
@@ -67,7 +73,7 @@ import { handleGuardianActivationIntercept } from "./inbound-stages/guardian-act
 import { handleGuardianReplyIntercept } from "./inbound-stages/guardian-reply-intercept.js";
 import { runSecretIngressCheck } from "./inbound-stages/secret-ingress-check.js";
 import { tryTranscribeAudioAttachments } from "./inbound-stages/transcribe-audio.js";
-import { handleVerificationIntercept } from "./inbound-stages/verification-intercept.js";
+import type { RouteHandlerArgs } from "./types.js";
 
 const log = getLogger("runtime-http");
 
@@ -93,28 +99,19 @@ export function _setDeleteLookupConfigForTests(
   deleteLookupDelayMs = delayMs;
 }
 
-export async function handleChannelInbound(
-  req: Request,
-  processMessage?: MessageProcessor,
-  assistantId: string = DAEMON_INTERNAL_ASSISTANT_ID,
-  approvalCopyGenerator?: ApprovalCopyGenerator,
-  approvalConversationGenerator?: ApprovalConversationGenerator,
-  _guardianActionCopyGenerator?: GuardianActionCopyGenerator,
-  _guardianFollowUpConversationGenerator?: GuardianFollowUpConversationGenerator,
-  heartbeatService?: HeartbeatService,
-): Promise<Response> {
+export async function handleChannelInbound({
+  body: rawBody = {},
+}: RouteHandlerArgs) {
   // Gateway-origin proof is enforced by route-policy middleware (svc_gateway
   // principal type required) before this handler runs. The exchange JWT
   // itself proves gateway origin.
 
-  // Factory that mints a fresh short-lived JWT for each daemon-to-gateway
-  // delivery callback. The JWT has a 60-second TTL, so long-running
-  // background operations (typing heartbeats, approval watchers, reply
-  // delivery) must call this at each delivery attempt rather than reusing
-  // a single token from request start.
-  const mintBearerToken = (): string => mintDaemonDeliveryToken();
+  const assistantId = DAEMON_INTERNAL_ASSISTANT_ID;
+  const approvalCopyGenerator = createApprovalCopyGenerator();
+  const approvalConversationGenerator = createApprovalConversationGenerator();
+  const heartbeatService = HeartbeatService.getInstance();
 
-  const body = (await req.json()) as {
+  const body = rawBody as {
     sourceChannel?: string;
     interface?: string;
     conversationExternalId?: string;
@@ -141,53 +138,49 @@ export async function handleChannelInbound(
   } = body;
 
   if (!body.sourceChannel || typeof body.sourceChannel !== "string") {
-    return httpError("BAD_REQUEST", "sourceChannel is required", 400);
+    throw new BadRequestError("sourceChannel is required");
   }
   // Validate and narrow to canonical ChannelId at the boundary — the gateway
   // only sends well-known channel strings, so an unknown value is rejected.
   if (!isChannelId(body.sourceChannel)) {
-    return httpError(
-      "BAD_REQUEST",
+    throw new BadRequestError(
       `Invalid sourceChannel: ${
         body.sourceChannel
       }. Valid values: ${CHANNEL_IDS.join(", ")}`,
-      400,
     );
   }
 
   const sourceChannel = body.sourceChannel;
 
   if (!body.interface || typeof body.interface !== "string") {
-    return httpError("BAD_REQUEST", "interface is required", 400);
+    throw new BadRequestError("interface is required");
   }
   const sourceInterface = parseInterfaceId(body.interface);
   if (!sourceInterface) {
-    return httpError(
-      "BAD_REQUEST",
+    throw new BadRequestError(
       `Invalid interface: ${body.interface}. Valid values: ${INTERFACE_IDS.join(
         ", ",
       )}`,
-      400,
     );
   }
 
   if (!conversationExternalId || typeof conversationExternalId !== "string") {
-    return httpError("BAD_REQUEST", "conversationExternalId is required", 400);
+    throw new BadRequestError("conversationExternalId is required");
   }
   if (
     !body.actorExternalId ||
     typeof body.actorExternalId !== "string" ||
     !body.actorExternalId.trim()
   ) {
-    return httpError("BAD_REQUEST", "actorExternalId is required", 400);
+    throw new BadRequestError("actorExternalId is required");
   }
   if (!externalMessageId || typeof externalMessageId !== "string") {
-    return httpError("BAD_REQUEST", "externalMessageId is required", 400);
+    throw new BadRequestError("externalMessageId is required");
   }
 
   // Reject non-string content regardless of whether attachments are present.
   if (content != null && typeof content !== "string") {
-    return httpError("BAD_REQUEST", "content must be a string", 400);
+    throw new BadRequestError("content must be a string");
   }
 
   let trimmedContent = typeof content === "string" ? content.trim() : "";
@@ -203,11 +196,7 @@ export async function handleChannelInbound(
     !isEdit &&
     !hasCallbackData
   ) {
-    return httpError(
-      "BAD_REQUEST",
-      "content or attachmentIds is required",
-      400,
-    );
+    throw new BadRequestError("content or attachmentIds is required");
   }
 
   // Canonicalize the assistant ID so all DB-facing operations use the
@@ -253,7 +242,6 @@ export async function handleChannelInbound(
     actorUsername: body.actorUsername,
     sourceMetadata: body.sourceMetadata,
     replyCallbackUrl: body.replyCallbackUrl,
-    mintBearerToken,
     assistantId,
     externalMessageId,
   });
@@ -272,12 +260,11 @@ export async function handleChannelInbound(
     actorDisplayName: body.actorDisplayName,
     actorUsername: body.actorUsername,
     replyCallbackUrl: body.replyCallbackUrl,
-    mintBearerToken,
     assistantId,
     externalMessageId,
   });
   if (aclResult.earlyResponse) return aclResult.earlyResponse;
-  const { resolvedMember, guardianVerifyCode } = aclResult;
+  const { resolvedMember } = aclResult;
 
   // ── Slack delete propagation ──
   // Slack message_deleted events are forwarded by the gateway with the
@@ -300,7 +287,7 @@ export async function handleChannelInbound(
         { conversationExternalId },
         "Slack message_deleted event missing sourceMetadata.messageId; ignoring",
       );
-      return Response.json({ accepted: true, deleted: false });
+      return { accepted: true, deleted: false };
     }
 
     // Look up the stored message via the existing channel-event lookup.
@@ -314,7 +301,7 @@ export async function handleChannelInbound(
     // 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(
+      original = findMessageBySourceId(
         sourceChannel,
         conversationExternalId,
         deletedMessageTs,
@@ -341,7 +328,7 @@ export async function handleChannelInbound(
         { conversationExternalId, deletedMessageTs },
         "No stored message found for Slack delete after retries; ignoring",
       );
-      return Response.json({ accepted: true, deleted: false });
+      return { accepted: true, deleted: false };
     }
 
     // Merge deletedAt into the existing slackMeta sub-key. If the row has
@@ -359,7 +346,7 @@ export async function handleChannelInbound(
         },
         "Stored Slack message has no metadata; skipping delete marker",
       );
-      return Response.json({ accepted: true, deleted: false });
+      return { accepted: true, deleted: false };
     }
 
     let parentMetadata: Record<string, unknown>;
@@ -379,7 +366,7 @@ export async function handleChannelInbound(
         },
         "Failed to parse stored metadata; skipping delete marker",
       );
-      return Response.json({ accepted: true, deleted: false });
+      return { accepted: true, deleted: false };
     }
 
     const existingSlackMeta =
@@ -396,7 +383,7 @@ export async function handleChannelInbound(
         },
         "Stored Slack message has no slackMeta; skipping delete marker",
       );
-      return Response.json({ accepted: true, deleted: false });
+      return { accepted: true, deleted: false };
     }
 
     const updatedSlackMeta = mergeSlackMetadata(existingSlackMeta, {
@@ -418,21 +405,20 @@ export async function handleChannelInbound(
       "Marked Slack message as deleted",
     );
 
-    return Response.json({
+    return {
       accepted: true,
       deleted: true,
       messageId: original.messageId,
-    });
+    };
   }
 
   if (hasAttachments) {
-    const resolved = attachmentsStore.getAttachmentsByIds(attachmentIds);
+    const resolved = getAttachmentsByIds(attachmentIds);
     if (resolved.length !== attachmentIds.length) {
       const resolvedIds = new Set(resolved.map((a) => a.id));
       const missing = attachmentIds.filter((id) => !resolvedIds.has(id));
-      return Response.json(
-        { error: `Attachment IDs not found: ${missing.join(", ")}` },
-        { status: 400 },
+      throw new BadRequestError(
+        `Attachment IDs not found: ${missing.join(", ")}`,
       );
     }
   }
@@ -466,11 +452,7 @@ export async function handleChannelInbound(
       : undefined;
 
   if (isEdit && !sourceMessageId) {
-    return httpError(
-      "BAD_REQUEST",
-      "sourceMetadata.messageId is required for edits",
-      400,
-    );
+    throw new BadRequestError("sourceMetadata.messageId is required for edits");
   }
 
   // ── Edit path: update existing message content, no new agent loop ──
@@ -488,7 +470,7 @@ export async function handleChannelInbound(
   }
 
   // ── New message path ──
-  const result = deliveryCrud.recordInbound(
+  const result = recordInbound(
     sourceChannel,
     conversationExternalId,
     externalMessageId,
@@ -502,21 +484,15 @@ export async function handleChannelInbound(
   // gateway retries (duplicates) re-attempt delivery here. On success the
   // pending marker is cleared so further duplicates short-circuit normally.
   if (result.duplicate && replyCallbackUrl) {
-    const pendingReply = deliveryChannels.getPendingVerificationReply(
-      result.eventId,
-    );
+    const pendingReply = getPendingVerificationReply(result.eventId);
     if (pendingReply) {
       try {
-        await deliverChannelReply(
-          replyCallbackUrl,
-          {
-            chatId: pendingReply.chatId,
-            text: pendingReply.text,
-            assistantId: pendingReply.assistantId,
-          },
-          mintBearerToken(),
-        );
-        deliveryChannels.clearPendingVerificationReply(result.eventId);
+        await deliverChannelReply(replyCallbackUrl, {
+          chatId: pendingReply.chatId,
+          text: pendingReply.text,
+          assistantId: pendingReply.assistantId,
+        });
+        clearPendingVerificationReply(result.eventId);
         log.info(
           { eventId: result.eventId },
           "Retried pending verification reply: delivered",
@@ -527,11 +503,11 @@ export async function handleChannelInbound(
           "Retry of pending verification reply failed; will retry on next duplicate",
         );
       }
-      return Response.json({
+      return {
         accepted: true,
         duplicate: true,
         eventId: result.eventId,
-      });
+      };
     }
   }
 
@@ -546,7 +522,7 @@ export async function handleChannelInbound(
   // self so assistant-scoped legacy routes do not overwrite each other's
   // channel binding metadata for the same chat.
   if (canonicalAssistantId === DAEMON_INTERNAL_ASSISTANT_ID) {
-    externalConversationStore.upsertBinding({
+    upsertBinding({
       conversationId: result.conversationId,
       sourceChannel,
       externalChatId: conversationExternalId,
@@ -568,10 +544,10 @@ export async function handleChannelInbound(
   //      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.
+  //      through to `persistSlackReactionAsMessage` so Slack transcript
+  //      rendering 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
@@ -601,7 +577,6 @@ export async function handleChannelInbound(
         sourceChannel,
         actorExternalId: canonicalSenderId ?? rawSenderId,
         replyCallbackUrl,
-        bearerToken: mintBearerToken(),
         trustCtx: trustCtxForReaction,
         assistantId: canonicalAssistantId,
         approvalCopyGenerator,
@@ -614,12 +589,12 @@ export async function handleChannelInbound(
       // 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({
+        return {
           accepted: true,
           duplicate: false,
           eventId: result.eventId,
           approval: reactionApprovalResult.type,
-        });
+        };
       }
     }
 
@@ -632,11 +607,11 @@ export async function handleChannelInbound(
         { conversationId: result.conversationId, eventId: result.eventId },
         "Skipping reaction persistence: missing sourceMetadata.messageId",
       );
-      return Response.json({
+      return {
         accepted: result.accepted,
         duplicate: result.duplicate,
         eventId: result.eventId,
-      });
+      };
     }
 
     const threadTs =
@@ -662,11 +637,11 @@ export async function handleChannelInbound(
       );
     }
 
-    return Response.json({
+    return {
       accepted: result.accepted,
       duplicate: result.duplicate,
       eventId: result.eventId,
-    });
+    };
   }
 
   // ── Ingress escalation ──
@@ -698,6 +673,7 @@ export async function handleChannelInbound(
           typeof hint === "string" && hint.trim().length > 0,
       )
     : [];
+  let slackRuntimeContextNotice: string | undefined;
 
   // Inject channel-scoped permission hints for Slack channel messages
   if (sourceChannel === "slack") {
@@ -762,25 +738,6 @@ export async function handleChannelInbound(
   });
   if (bootstrapResponse) return bootstrapResponse;
 
-  // ── Guardian verification code intercept (deterministic) ──
-  const verificationResponse = await handleVerificationIntercept({
-    isDuplicate: result.duplicate,
-    guardianVerifyCode,
-    rawSenderId,
-    canonicalSenderId,
-    canonicalAssistantId,
-    sourceChannel,
-    conversationExternalId,
-    conversationId: result.conversationId,
-    eventId: result.eventId,
-    replyCallbackUrl,
-    mintBearerToken,
-    assistantId,
-    actorDisplayName: body.actorDisplayName,
-    actorUsername: body.actorUsername,
-  });
-  if (verificationResponse) return verificationResponse;
-
   // Legacy voice guardian action interception removed — all guardian reply
   // routing now flows through the canonical router below (routeGuardianReply),
   // which handles request code matching, callback parsing, and NL classification
@@ -812,7 +769,6 @@ export async function handleChannelInbound(
     conversationId: result.conversationId,
     eventId: result.eventId,
     replyCallbackUrl,
-    mintBearerToken,
     trustClass: trustCtx.trustClass,
     guardianPrincipalId: trustCtx.guardianPrincipalId,
     approvalConversationGenerator,
@@ -846,7 +802,6 @@ export async function handleChannelInbound(
       sourceChannel,
       actorExternalId: canonicalSenderId ?? rawSenderId,
       replyCallbackUrl,
-      bearerToken: mintBearerToken(),
       trustCtx,
       assistantId: canonicalAssistantId,
       approvalCopyGenerator,
@@ -893,12 +848,12 @@ export async function handleChannelInbound(
         }
       }
 
-      return Response.json({
+      return {
         accepted: true,
         duplicate: false,
         eventId: result.eventId,
         approval: approvalResult.type,
-      });
+      };
     }
 
     // When a callback payload was not handled by approval interception, it's
@@ -940,16 +895,12 @@ export async function handleChannelInbound(
       // and deliver an ephemeral error so the user gets visible feedback
       // instead of a silent no-op (JARVIS-299).
       if (sourceChannel === "slack" && replyCallbackUrl && approvalMessageTs) {
-        deliverChannelReply(
-          replyCallbackUrl,
-          {
-            chatId: conversationExternalId,
-            text: "This approval request has been resolved.",
-            messageTs: approvalMessageTs,
-            assistantId: canonicalAssistantId,
-          },
-          mintBearerToken(),
-        ).catch((err) => {
+        deliverChannelReply(replyCallbackUrl, {
+          chatId: conversationExternalId,
+          text: "This approval request has been resolved.",
+          messageTs: approvalMessageTs,
+          assistantId: canonicalAssistantId,
+        }).catch((err) => {
           log.error(
             { err, conversationId: result.conversationId },
             "Failed to edit stale Slack approval message",
@@ -957,18 +908,18 @@ export async function handleChannelInbound(
         });
       }
 
-      return Response.json({
+      return {
         accepted: true,
         duplicate: false,
         eventId: result.eventId,
         approval: "stale_ignored",
-      });
+      };
     }
   }
 
   // For new (non-duplicate) messages, run the secret ingress check
   // synchronously, then fire off the agent loop in the background.
-  if (!result.duplicate && processMessage) {
+  if (!result.duplicate) {
     const ingressResult = runSecretIngressCheck({
       eventId: result.eventId,
       sourceChannel,
@@ -989,7 +940,7 @@ export async function handleChannelInbound(
 
     if (ingressResult.blocked) {
       // Intentional block — mark the event as processed (not failed/dead-lettered).
-      deliveryStatus.markProcessed(result.eventId);
+      markProcessed(result.eventId);
       log.info(
         {
           eventId: result.eventId,
@@ -1067,25 +1018,27 @@ export async function handleChannelInbound(
         });
       }
 
-      // ── 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.
+      // ── Thread gap/delta backfill ──
+      // When a Slack thread reply arrives, compare the stored thread state
+      // with the inbound message's ts and fetch only the bounded unseen
+      // window. Initial late-join turns hydrate the earliest thread messages
+      // plus a recent window adjacent to the inbound reply; later turns use
+      // a delta window after the latest stored thread ts and before the
+      // inbound ts. Awaited (mirrors the DM cold-start path above) so the
+      // agent loop dispatched immediately afterwards observes hydrated
+      // context. A late-join notice is added only to the current turn's
+      // runtime context, not persisted as durable Slack metadata. Failures
+      // are swallowed inside the helper so they never block dispatch.
       if (slackThreadTs) {
-        await triggerSlackThreadBackfillIfNeeded({
+        const backfillResult = await triggerSlackThreadBackfillIfNeeded({
           conversationId: result.conversationId,
           channelId: conversationExternalId,
           threadTs: slackThreadTs,
           excludeChannelTs: slackInbound?.channelTs,
           account: slackAccount,
         });
+        const lateJoinNotice = buildSlackLateJoinNotice(backfillResult);
+        if (lateJoinNotice) slackRuntimeContextNotice = lateJoinNotice;
       }
 
       // Wrap non-guardian inbound content in external_content boundaries so
@@ -1113,11 +1066,11 @@ export async function handleChannelInbound(
         externalChatId: conversationExternalId,
         trustCtx,
         metadataHints,
+        slackRuntimeContextNotice,
         metadataUxBrief,
         commandIntent,
         sourceLanguageCode,
         replyCallbackUrl,
-        mintBearerToken,
         assistantId: canonicalAssistantId,
         approvalCopyGenerator,
         chatType: sourceChatType,
@@ -1126,11 +1079,11 @@ export async function handleChannelInbound(
     }
   }
 
-  return Response.json({
+  return {
     accepted: result.accepted,
     duplicate: result.duplicate,
     eventId: result.eventId,
-  });
+  };
 }
 
 /**
@@ -1229,8 +1182,8 @@ async function persistSlackReactionAsMessage(params: {
     },
   };
 
-  // Sentinel content — renderers (PR 18) read `slackMeta` to format the
-  // reaction line; the literal text is never displayed to the model.
+  // Sentinel content — Slack transcript renderers read `slackMeta` to format
+  // the reaction line; the literal text is never displayed to the model.
   const persisted = await addMessage(
     params.conversationId,
     "user",
@@ -1238,8 +1191,8 @@ async function persistSlackReactionAsMessage(params: {
     { slackMeta: writeSlackMetadata(slackMeta) },
     { skipIndexing: true },
   );
-  deliveryCrud.linkMessage(params.eventId, persisted.id);
-  deliveryStatus.markProcessed(params.eventId);
+  linkMessage(params.eventId, persisted.id);
+  markProcessed(params.eventId);
 }
 
 /**
@@ -1309,19 +1262,7 @@ function countSlackMetaMessages(conversationId: string): number {
     );
     if (candidates.length === 0) return count;
     for (const raw of candidates) {
-      let parent: Record<string, unknown> | null = null;
-      try {
-        const parsed = JSON.parse(raw) as unknown;
-        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
-          parent = parsed as Record<string, unknown>;
-        }
-      } catch {
-        continue;
-      }
-      if (!parent) continue;
-      const inner = parent.slackMeta;
-      if (typeof inner !== "string") continue;
-      if (readSlackMetadata(inner)) {
+      if (readSlackMetadataFromMessageMetadata(raw)) {
         count++;
         if (count >= SLACK_DM_BACKFILL_WARM_THRESHOLD) return count;
       }
@@ -1332,44 +1273,110 @@ function countSlackMetaMessages(conversationId: string): number {
   return count;
 }
 
+function readSlackMetadataFromMessageMetadata(
+  metadata: string | null | undefined,
+): SlackMessageMetadata | null {
+  if (!metadata) return null;
+  let parent: Record<string, unknown> | null = null;
+  try {
+    const parsed = JSON.parse(metadata) as unknown;
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      parent = parsed as Record<string, unknown>;
+    }
+  } catch {
+    return null;
+  }
+  if (!parent) return null;
+  const raw = parent.slackMeta;
+  if (typeof raw !== "string") return null;
+  return readSlackMetadata(raw);
+}
+
 /**
  * Build the set of `slackMeta.channelTs` values already stored on a
- * conversation. Used by both DM cold-start backfill and thread-ancestor
+ * conversation. Used by both DM cold-start backfill and thread gap/delta
  * 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);
+    const meta = readSlackMetadataFromMessageMetadata(row.metadata);
     // 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
+    // make a reaction on a thread parent wrongly short-circuit thread
     // backfill (the parent itself may still be unseen).
     if (meta && meta.eventKind === "message") seen.add(meta.channelTs);
   }
   return seen;
 }
 
+interface ParsedSlackTimestamp {
+  seconds: bigint;
+  micros: bigint;
+}
+
+function parseSlackTimestamp(
+  ts: string | undefined,
+): ParsedSlackTimestamp | null {
+  if (!ts) return null;
+  const match = /^(\d+)\.(\d{1,6})$/.exec(ts);
+  if (!match) return null;
+  const micros = BigInt(match[2]);
+  if (micros > 999_999n) return null;
+  return {
+    seconds: BigInt(match[1]),
+    micros,
+  };
+}
+
+function compareSlackTimestamps(left: string, right: string): number | null {
+  const parsedLeft = parseSlackTimestamp(left);
+  const parsedRight = parseSlackTimestamp(right);
+  if (!parsedLeft || !parsedRight) return null;
+  if (parsedLeft.seconds < parsedRight.seconds) return -1;
+  if (parsedLeft.seconds > parsedRight.seconds) return 1;
+  if (parsedLeft.micros < parsedRight.micros) return -1;
+  if (parsedLeft.micros > parsedRight.micros) return 1;
+  return 0;
+}
+
+interface StoredSlackThreadState {
+  storedChannelTs: Set<string>;
+  latestStoredThreadTs: string | undefined;
+}
+
+function readStoredSlackThreadState(
+  conversationId: string,
+  threadTs: string,
+): StoredSlackThreadState {
+  const storedChannelTs = new Set<string>();
+  let latestStoredThreadTs: string | undefined;
+
+  for (const row of getMessages(conversationId)) {
+    const meta = readSlackMetadataFromMessageMetadata(row.metadata);
+    if (!meta || meta.eventKind !== "message") continue;
+    if (meta.channelTs !== threadTs && meta.threadTs !== threadTs) continue;
+
+    storedChannelTs.add(meta.channelTs);
+    if (!parseSlackTimestamp(meta.channelTs)) continue;
+    if (
+      latestStoredThreadTs === undefined ||
+      compareSlackTimestamps(meta.channelTs, latestStoredThreadTs) === 1
+    ) {
+      latestStoredThreadTs = meta.channelTs;
+    }
+  }
+
+  return { storedChannelTs, latestStoredThreadTs };
+}
+
 /**
  * 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
+ * (DM cold-start backfill, thread gap/delta 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
@@ -1383,6 +1390,7 @@ async function persistBackfilledSlackMessage(params: {
   message: ProviderMessage;
 }): Promise<void> {
   const { message } = params;
+  const slackFiles = readSlackFilesFromProviderMetadata(message.metadata);
   const slackMeta: SlackMessageMetadata = {
     source: "slack",
     channelId: params.channelId,
@@ -1390,6 +1398,7 @@ async function persistBackfilledSlackMessage(params: {
     eventKind: "message",
     ...(message.threadId ? { threadTs: message.threadId } : {}),
     ...(message.sender?.name ? { displayName: message.sender.name } : {}),
+    ...(slackFiles.length > 0 ? { slackFiles } : {}),
   };
   const role = message.metadata?.isBot === true ? "assistant" : "user";
   await addMessage(params.conversationId, role, message.text ?? "", {
@@ -1397,6 +1406,32 @@ async function persistBackfilledSlackMessage(params: {
   });
 }
 
+function readSlackFilesFromProviderMetadata(
+  metadata: Record<string, unknown> | undefined,
+): SlackFileMetadata[] {
+  const raw = metadata?.slackFiles;
+  if (!Array.isArray(raw)) return [];
+  const files: SlackFileMetadata[] = [];
+  for (const item of raw) {
+    if (item === null || typeof item !== "object" || Array.isArray(item)) {
+      continue;
+    }
+    const record = item as Record<string, unknown>;
+    const name = typeof record.name === "string" ? record.name.trim() : "";
+    if (!name) continue;
+    files.push({
+      ...(typeof record.id === "string" && record.id.length > 0
+        ? { id: record.id }
+        : {}),
+      name,
+      ...(typeof record.mimetype === "string" && record.mimetype.length > 0
+        ? { mimetype: record.mimetype }
+        : {}),
+    });
+  }
+  return files;
+}
+
 /**
  * In-memory map of in-flight DM cold-start backfills keyed by conversationId.
  * Concurrent inbound DMs to the same cold conversation share a single
@@ -1539,13 +1574,11 @@ async function runBackfillSlackDmIfCold(params: {
 // ---------------------------------------------------------------------------
 
 /**
- * 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.
+ * In-memory TTL cache keyed by
+ * `<conversationId>:<threadTs>:<lowerBoundTs>:<upperBoundTs>`. Tracks recent
+ * thread-backfill windows so repeated triggers for the same Slack gap do not
+ * re-fetch identical rows while later replies in the same thread can still
+ * request newer unseen windows.
  *
  * Exported only for tests; production callers should use
  * {@link triggerSlackThreadBackfillIfNeeded}.
@@ -1554,6 +1587,39 @@ export const _backfillTriggerCache = new Map<string, number>();
 
 const BACKFILL_TRIGGER_TTL_MS = 10 * 60 * 1000; // 10 minutes
 const BACKFILL_TRIGGER_CACHE_MAX = 1_000;
+const SLACK_THREAD_INITIAL_EARLY_LIMIT = 25;
+const SLACK_THREAD_INITIAL_RECENT_LIMIT = 50;
+const SLACK_THREAD_INITIAL_RECENT_MAX_PAGES = 5;
+const SLACK_THREAD_DELTA_LIMIT = 50;
+const SLACK_THREAD_UPPER_ADJACENT_MAX_ATTEMPTS = 5;
+const MICROS_PER_SECOND = 1_000_000n;
+const SLACK_UPPER_ADJACENT_EXPANDING_WINDOWS_MICROS = [
+  5n * 60n * MICROS_PER_SECOND,
+  60n * 60n * MICROS_PER_SECOND,
+  24n * 60n * 60n * MICROS_PER_SECOND,
+  7n * 24n * 60n * 60n * MICROS_PER_SECOND,
+  30n * 24n * 60n * 60n * MICROS_PER_SECOND,
+];
+const SLACK_UPPER_ADJACENT_SHRINKING_WINDOWS_MICROS = [
+  60n * MICROS_PER_SECOND,
+  10n * MICROS_PER_SECOND,
+  MICROS_PER_SECOND,
+  100_000n,
+  1_000n,
+];
+
+export interface SlackThreadBackfillResult {
+  fetched: number;
+  persisted: number;
+  reason?: SlackBackfillReason;
+  omittedMiddle: boolean;
+}
+
+type SlackBackfillReason = "thread_late_join" | "thread_delta";
+
+function emptySlackThreadBackfillResult(): SlackThreadBackfillResult {
+  return { fetched: 0, persisted: 0, omittedMiddle: false };
+}
 
 function pruneBackfillCacheIfNeeded(): void {
   if (_backfillTriggerCache.size < BACKFILL_TRIGGER_CACHE_MAX) return;
@@ -1588,23 +1654,315 @@ function isBackfillRecentlyTriggered(cacheKey: string): boolean {
   return true;
 }
 
+interface SlackInitialThreadWindowsResult {
+  messages: ProviderMessage[];
+  omittedMiddle: boolean;
+}
+
+interface SlackUpperAdjacentWindowResult {
+  messages: ProviderMessage[];
+  omittedEarlierContent: boolean;
+  truncatedBeforeUpperBound: boolean;
+}
+
+function slackPageHasMore(page: SlackBackfillWindowPage): boolean {
+  return page.hasMore || page.nextCursor !== undefined;
+}
+
+function minSlackMessageTs(messages: ProviderMessage[]): string | undefined {
+  return sortSlackProviderMessages(messages)[0]?.id;
+}
+
+function maxSlackMessageTs(messages: ProviderMessage[]): string | undefined {
+  const sorted = sortSlackProviderMessages(messages);
+  return sorted[sorted.length - 1]?.id;
+}
+
+function slackTimestampToMicros(ts: string | undefined): bigint | null {
+  const parsed = parseSlackTimestamp(ts);
+  if (!parsed) return null;
+  return parsed.seconds * MICROS_PER_SECOND + parsed.micros;
+}
+
+function slackTimestampFromMicros(totalMicros: bigint): string | undefined {
+  if (totalMicros < 0n) return undefined;
+  const seconds = totalMicros / MICROS_PER_SECOND;
+  const micros = totalMicros % MICROS_PER_SECOND;
+  return `${seconds.toString()}.${micros.toString().padStart(6, "0")}`;
+}
+
+function didInitialWindowsLeaveGap(params: {
+  early: SlackBackfillWindowPage;
+  recent: SlackBackfillWindowPage;
+  recentScanTruncated: boolean;
+}): boolean {
+  if (params.recentScanTruncated) return true;
+  if (!slackPageHasMore(params.early)) return false;
+  const earlyMax = maxSlackMessageTs(params.early.messages);
+  const recentMin = minSlackMessageTs(params.recent.messages);
+  if (!earlyMax || !recentMin) return false;
+  const compared = compareSlackTimestamps(earlyMax, recentMin);
+  return compared !== null && compared < 0;
+}
+
+async function fetchSlackThreadUpperAdjacentWindow(params: {
+  channelId: string;
+  threadTs: string;
+  upperBoundTs: string;
+  lowerBoundTs?: string;
+  limit: number;
+  account?: string;
+  maxAttempts?: number;
+}): Promise<SlackUpperAdjacentWindowResult> {
+  // Slack returns bounded conversations.replies pages earliest-first. To keep
+  // the context closest to the inbound mention, narrow by timestamp instead
+  // of cursoring forward from the oldest page in the bounded range.
+  const upperMicros = slackTimestampToMicros(params.upperBoundTs);
+  if (upperMicros === null) {
+    const page = await backfillThreadWindowPage(
+      params.channelId,
+      params.threadTs,
+      {
+        limit: params.limit,
+        account: params.account,
+        before: params.upperBoundTs,
+        ...(params.lowerBoundTs !== undefined
+          ? { after: params.lowerBoundTs }
+          : {}),
+      },
+    );
+    return {
+      messages: page.messages,
+      omittedEarlierContent: slackPageHasMore(page),
+      truncatedBeforeUpperBound: slackPageHasMore(page),
+    };
+  }
+
+  const lowerMicros = slackTimestampToMicros(params.lowerBoundTs);
+  const maxAttempts =
+    params.maxAttempts ?? SLACK_THREAD_UPPER_ADJACENT_MAX_ATTEMPTS;
+  let attempts = 0;
+  let safePage: SlackBackfillWindowPage | undefined;
+  let safeAfterTs: string | undefined;
+  let truncatedBeforeUpperBound = false;
+
+  const fetchWindow = async (
+    windowMicros: bigint,
+  ): Promise<{
+    page: SlackBackfillWindowPage;
+    after?: string;
+    reachedLowerBound: boolean;
+  }> => {
+    let candidateMicros = upperMicros - windowMicros;
+    let reachedLowerBound = false;
+    if (lowerMicros !== null && candidateMicros <= lowerMicros) {
+      candidateMicros = lowerMicros;
+      reachedLowerBound = true;
+    }
+    const after = reachedLowerBound
+      ? params.lowerBoundTs
+      : slackTimestampFromMicros(candidateMicros);
+    const page = await backfillThreadWindowPage(
+      params.channelId,
+      params.threadTs,
+      {
+        limit: params.limit,
+        account: params.account,
+        before: params.upperBoundTs,
+        ...(after !== undefined ? { after } : {}),
+      },
+    );
+    attempts++;
+    return { page, after, reachedLowerBound };
+  };
+
+  const considerWindow = async (windowMicros: bigint): Promise<boolean> => {
+    const { page, after, reachedLowerBound } = await fetchWindow(windowMicros);
+    if (slackPageHasMore(page)) {
+      truncatedBeforeUpperBound = true;
+      return false;
+    }
+
+    safePage = page;
+    safeAfterTs = after;
+    return page.messages.length < params.limit && !reachedLowerBound;
+  };
+
+  for (const windowMicros of SLACK_UPPER_ADJACENT_EXPANDING_WINDOWS_MICROS) {
+    if (attempts >= maxAttempts) break;
+    const shouldExpand = await considerWindow(windowMicros);
+    if (!shouldExpand) break;
+  }
+
+  if (truncatedBeforeUpperBound && !safePage && attempts < maxAttempts) {
+    for (const windowMicros of SLACK_UPPER_ADJACENT_SHRINKING_WINDOWS_MICROS) {
+      if (attempts >= maxAttempts) break;
+      await considerWindow(windowMicros);
+      if (safePage) break;
+    }
+  }
+
+  if (!safePage) {
+    const after = slackTimestampFromMicros(upperMicros - 2n);
+    const page = await backfillThreadWindowPage(
+      params.channelId,
+      params.threadTs,
+      {
+        limit: params.limit,
+        account: params.account,
+        before: params.upperBoundTs,
+        ...(after !== undefined ? { after } : {}),
+      },
+    );
+    safePage = page;
+    safeAfterTs = after;
+    truncatedBeforeUpperBound =
+      truncatedBeforeUpperBound || slackPageHasMore(page);
+  }
+  if (!safePage) {
+    return {
+      messages: [],
+      omittedEarlierContent: true,
+      truncatedBeforeUpperBound: true,
+    };
+  }
+
+  let omittedEarlierContent = truncatedBeforeUpperBound;
+  if (
+    !omittedEarlierContent &&
+    params.lowerBoundTs !== undefined &&
+    safeAfterTs !== undefined &&
+    compareSlackTimestamps(params.lowerBoundTs, safeAfterTs) === -1
+  ) {
+    const coverageProbe = await backfillThreadWindowPage(
+      params.channelId,
+      params.threadTs,
+      {
+        limit: 1,
+        account: params.account,
+        after: params.lowerBoundTs,
+        before: safeAfterTs,
+      },
+    );
+    omittedEarlierContent =
+      coverageProbe.messages.length > 0 || slackPageHasMore(coverageProbe);
+  }
+
+  return {
+    messages: safePage.messages,
+    omittedEarlierContent,
+    truncatedBeforeUpperBound,
+  };
+}
+
+async function fetchInitialSlackThreadWindows(params: {
+  channelId: string;
+  threadTs: string;
+  upperBoundTs?: string;
+  account?: string;
+}): Promise<SlackInitialThreadWindowsResult> {
+  if (!params.upperBoundTs) {
+    const early = await backfillThreadWindowPage(
+      params.channelId,
+      params.threadTs,
+      {
+        limit: SLACK_THREAD_INITIAL_EARLY_LIMIT,
+        account: params.account,
+      },
+    );
+    return {
+      messages: sortSlackProviderMessages(
+        dedupeSlackProviderMessages(early.messages),
+      ),
+      omittedMiddle: slackPageHasMore(early),
+    };
+  }
+  const [early, recentResult] = await Promise.all([
+    backfillThreadWindowPage(params.channelId, params.threadTs, {
+      limit: SLACK_THREAD_INITIAL_EARLY_LIMIT,
+      account: params.account,
+    }),
+    fetchSlackThreadUpperAdjacentWindow({
+      channelId: params.channelId,
+      threadTs: params.threadTs,
+      account: params.account,
+      upperBoundTs: params.upperBoundTs,
+      limit: SLACK_THREAD_INITIAL_RECENT_LIMIT,
+      maxAttempts: SLACK_THREAD_INITIAL_RECENT_MAX_PAGES,
+    }),
+  ]);
+  const recent: SlackBackfillWindowPage = {
+    messages: recentResult.messages,
+    hasMore: recentResult.truncatedBeforeUpperBound,
+  };
+  return {
+    messages: sortSlackProviderMessages(
+      dedupeSlackProviderMessages([...early.messages, ...recent.messages]),
+    ),
+    omittedMiddle:
+      recentResult.omittedEarlierContent ||
+      didInitialWindowsLeaveGap({
+        early,
+        recent,
+        recentScanTruncated: recentResult.truncatedBeforeUpperBound,
+      }),
+  };
+}
+
+function dedupeSlackProviderMessages(
+  messages: ProviderMessage[],
+): ProviderMessage[] {
+  const byTs = new Map<string, ProviderMessage>();
+  for (const message of messages) {
+    if (!message.id || byTs.has(message.id)) continue;
+    byTs.set(message.id, message);
+  }
+  return [...byTs.values()];
+}
+
+function sortSlackProviderMessages(
+  messages: ProviderMessage[],
+): ProviderMessage[] {
+  return [...messages].sort((left, right) => {
+    const compared = compareSlackTimestamps(left.id, right.id);
+    if (compared !== null) return compared;
+    return left.id.localeCompare(right.id);
+  });
+}
+
+function buildSlackLateJoinNotice(
+  result: SlackThreadBackfillResult,
+): string | null {
+  if (result.reason !== "thread_late_join" || result.persisted === 0) {
+    return null;
+  }
+  const omitted = result.omittedMiddle
+    ? " Some middle thread messages were intentionally omitted from this turn's hydrated context to keep latency bounded."
+    : "";
+  return `Slack context note: this turn joined an existing thread. ${result.persisted} earlier thread message${result.persisted === 1 ? " was" : "s were"} backfilled before the current message.${omitted}`;
+}
+
 /**
- * Lazily backfill missing Slack thread ancestors for an inbound thread reply.
+ * Lazily backfill Slack thread gaps 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.
+ * When a reply arrives for a thread with unseen Slack history, the assistant
+ * fetches bounded `conversations.replies` pages via
+ * {@link backfillThreadWindowPage}, 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.
+ * - **Thread-state gap detection.** Looks up stored Slack message rows for
+ *   the same thread, excluding reactions, then fetches only the unseen
+ *   `(latestStoredThreadTs, excludeChannelTs)` window when the inbound Slack
+ *   timestamp is newer than local state.
+ * - **Upper-bound windows.** Initial late-join backfill combines an early
+ *   thread page with a recent page adjacent to the inbound ts; delta backfill
+ *   fetches the page nearest the inbound upper bound so the current turn sees
+ *   the most relevant context while keeping latency bounded.
+ * - **Exact-window TTL cache.** A 10-minute in-memory cache prevents repeated
+ *   fetches for the same exact lower/upper bounded window, without
+ *   suppressing later unseen windows in the same thread.
  * - **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.
@@ -1619,65 +1977,106 @@ export async function triggerSlackThreadBackfillIfNeeded(params: {
    * `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.
+   * in the DB when the thread-state scan 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.
+   * `backfillThreadWindowPage` page requests and then `resolveConnection`.
+   * Best-effort: if omitted, the resolver falls back to the default-active
+   * connection.
    */
   account?: string;
-}): Promise<void> {
+}): Promise<SlackThreadBackfillResult> {
   const { conversationId, channelId, threadTs, excludeChannelTs, account } =
     params;
-  const cacheKey = `${conversationId}:${threadTs}`;
 
   try {
-    if (isBackfillRecentlyTriggered(cacheKey)) {
-      return;
+    const upperBoundTs = parseSlackTimestamp(excludeChannelTs)
+      ? excludeChannelTs
+      : undefined;
+    const threadState = readStoredSlackThreadState(conversationId, threadTs);
+    const lowerBoundTs = threadState.latestStoredThreadTs;
+
+    // Pre-seed only after computing lowerBoundTs. The current inbound row
+    // may not have reached the DB yet, and treating it as stored state would
+    // hide the gap we need to fetch.
+    if (excludeChannelTs) threadState.storedChannelTs.add(excludeChannelTs);
+
+    if (upperBoundTs && lowerBoundTs) {
+      const lowerVsUpper = compareSlackTimestamps(lowerBoundTs, upperBoundTs);
+      if (lowerVsUpper !== null && lowerVsUpper >= 0) {
+        return emptySlackThreadBackfillResult();
+      }
+    } else if (!upperBoundTs && lowerBoundTs) {
+      return emptySlackThreadBackfillResult();
     }
 
-    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;
+    const cacheKey = `${conversationId}:${threadTs}:${
+      lowerBoundTs ?? "none"
+    }:${upperBoundTs ?? "unbounded"}`;
+    if (isBackfillRecentlyTriggered(cacheKey)) {
+      return emptySlackThreadBackfillResult();
     }
 
     // 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.
+    // means a second concurrent request for the same window 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 });
+    const isInitialLateJoin =
+      lowerBoundTs === undefined &&
+      threadState.storedChannelTs.size === (excludeChannelTs ? 1 : 0);
+    const reason: SlackBackfillReason = isInitialLateJoin
+      ? "thread_late_join"
+      : "thread_delta";
+    let omittedMiddle = false;
+    let fetched: ProviderMessage[];
+    if (isInitialLateJoin) {
+      const initial = await fetchInitialSlackThreadWindows({
+        channelId,
+        threadTs,
+        upperBoundTs,
+        account,
+      });
+      fetched = initial.messages;
+      omittedMiddle = initial.omittedMiddle;
+    } else {
+      const window = await fetchSlackThreadUpperAdjacentWindow({
+        channelId,
+        threadTs,
+        limit: SLACK_THREAD_DELTA_LIMIT,
+        account,
+        ...(lowerBoundTs !== undefined ? { lowerBoundTs } : {}),
+        upperBoundTs: upperBoundTs ?? threadTs,
+      });
+      fetched = window.messages;
+      omittedMiddle = window.omittedEarlierContent;
+    }
     if (fetched.length === 0) {
       log.debug(
         { conversationId, channelId, threadTs },
         "Slack thread backfill returned no messages",
       );
-      return;
+      return emptySlackThreadBackfillResult();
     }
 
     let persisted = 0;
     for (const message of fetched) {
       if (!message.id) continue;
-      if (storedChannelTs.has(message.id)) continue;
+      if (threadState.storedChannelTs.has(message.id)) continue;
       try {
         await persistBackfilledSlackMessage({
           conversationId,
           channelId,
           message,
         });
-        storedChannelTs.add(message.id);
+        threadState.storedChannelTs.add(message.id);
         persisted++;
       } catch (err) {
         log.warn(
@@ -1694,15 +2093,22 @@ export async function triggerSlackThreadBackfillIfNeeded(params: {
         threadTs,
         persisted,
         fetched: fetched.length,
+        omittedMiddle,
       },
-      "Slack thread backfill persisted ancestor messages",
+      "Slack thread backfill persisted thread messages",
     );
+    return {
+      fetched: fetched.length,
+      persisted,
+      reason,
+      omittedMiddle,
+    };
   } 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.
+    // transient blips and dispatch proceeds without the backfilled thread rows.
     const channelNotFound =
       err instanceof Error && /channel_not_found/i.test(err.message);
     const payload = { err, conversationId, channelId, threadTs, account };
@@ -1714,5 +2120,6 @@ export async function triggerSlackThreadBackfillIfNeeded(params: {
     } else {
       log.warn(payload, "Slack thread backfill failed; proceeding without it");
     }
+    return emptySlackThreadBackfillResult();
   }
 }