@modesto_ma/dsh-channels 0.3.0 → 0.4.0

package/src/service.ts

@@ -56,8 +56,8 @@ import {
 import type { CleanupDeps, CleanupRoute, CleanupTombstone, ScannedSessionDir, WorkspaceStats } from './cleanup.ts'
 import type {
   AccessGroupRecord, AccessRequestRecord, AccessUserRecord,
-  ExpiredRouteRecord, FeishuDomainGlobal, FeishuDomainHandle, InflightSnapshot, ProcessedRecord, RawDomainHandle,
-  RouteRecord,
+  ExpiredRouteRecord, FeishuDomainGlobal, FeishuDomainHandle, InflightSnapshot, PendingAttachmentRecord,
+  PendingAttachmentsTable, ProcessedRecord, RawDomainHandle, RouteRecord,
 } from './domain.ts'
 import { RouteStore } from './session/routes.ts'
 import { InflightRepair } from './session/repair.ts'
@@ -65,6 +65,17 @@ import { SessionManager } from './session/manager.ts'
 import type { LiveAgent, RenewCommit } from './session/manager.ts'
 import { CardDelivery } from './feishu/delivery.ts'
 import { AttachmentIntake } from './feishu/inbound-attachments.ts'
+import { InboundAttachmentStore, effectiveAttachmentMode, resolveAttachmentService } from './feishu/native-attachments.ts'
+import { PendingAttachmentStore } from './feishu/pending-attachments.ts'
+import { AttachmentFetchToolRuntime, TopicMessagesToolRuntime } from './feishu/tools.ts'
+import type { KnownAttachmentMessageInput, KnownAttachmentSource } from './feishu/tools.ts'
+import {
+  MessageReader, TOPIC_MESSAGES_MAX_LIMIT, buildHistoryContextBlock,
+  buildQuoteContextBlock, clampInt, knownMessageOfItems, knownMessagesOfHistory, quoteItemsOf,
+  readQuoteItems,
+} from './feishu/message-read.ts'
+import type { MessageReadRoute, RawMessageItem } from './feishu/message-read.ts'
+import type { AttachmentStore } from './host/attachments.ts'
 import { InboundRouter } from './routing/inbound.ts'
 import type { RequestPolicyController } from './session/request-policy.ts'
 import type { ChannelFactory, FeishuChannel, NormalizedMessage } from './feishu-channel.ts'
@@ -86,7 +97,8 @@ import type { FeishuConfig } from './config.ts'
 import type {
   AccessMutationResponse, AccessRequestWire, AccessWire,
 } from './settings/contract.ts'
-import type { OverlayStore } from './settings/overlay.ts'
+import { mergeOverlay } from './settings/overlay.ts'
+import type { OverlayPatch, OverlayStore } from './settings/overlay.ts'
 import { legacyTopicWorkspaceRoot } from './workspaces.ts'
 
 /** Periodic route-GC sweep cadence (a long-running instance also accumulates
@@ -127,6 +139,29 @@ async function openFeishuDomain(ctx: HostContext): Promise<FeishuDomainHandle> {
   const accessGroupsRaw = domain.table('access_groups')
   const accessUsersRaw = domain.table('access_users')
   const accessRequestsRaw = domain.table('access_requests')
+  // Pending attachment metadata is a table ADDED to the domain at the same
+  // version (see `pendingAttachmentRecordSchema`); hosts that cannot accept the
+  // addition leave this undefined and the registry degrades to its memory TTL
+  // fallback without taking the whole storage domain down.
+  let pendingAttachmentsRaw: ReturnType<RawDomainHandle['table']> | undefined
+  try {
+    pendingAttachmentsRaw = domain.table('pending_attachments')
+  } catch (error) {
+    ctx.logger?.warn?.('dsh-channels: pending attachment table unavailable: %s', String(error))
+  }
+  const pendingAttachments: PendingAttachmentsTable | undefined = pendingAttachmentsRaw === undefined
+    ? undefined
+    : {
+      get: key => pendingAttachmentsRaw.get(key) as PendingAttachmentRecord | undefined,
+      put: (key, value) => pendingAttachmentsRaw.put(key, value),
+      update: (key, fn) => pendingAttachmentsRaw.update(
+        key,
+        current => fn(current as PendingAttachmentRecord),
+      ),
+      delete: key => pendingAttachmentsRaw.delete(key),
+      entries: () =>
+        pendingAttachmentsRaw.entries() as IterableIterator<[string, PendingAttachmentRecord]>,
+    }
   return {
     routes: {
       get: key => table.get(key) as RouteRecord | undefined,
@@ -170,6 +205,7 @@ async function openFeishuDomain(ctx: HostContext): Promise<FeishuDomainHandle> {
       delete: key => accessRequestsRaw.delete(key),
       entries: () => accessRequestsRaw.entries() as IterableIterator<[string, AccessRequestRecord]>,
     },
+    pendingAttachments,
     getGlobal: () => (domain.global.get() ?? {}) as FeishuDomainGlobal,
     setGlobal: value => domain.global.set(value),
     close: () => domain.close(),
@@ -270,10 +306,36 @@ export class FeishuService {
   private readonly delivery: CardDelivery
   /** Inbound attachment archival (Feishu resources → workspace files). */
   private readonly attachments: AttachmentIntake
+  /**
+   * Backend-selecting inbound storage facade. The native path stays lazy in
+   * admission (prefetch images + manifest); this facade owns the legacy
+   * workspace download used by `attachmentStore: 'archive'` and by the
+   * fallback when the host does not mount `ctx.attachments`.
+   */
+  private readonly inboundAttachmentStore: InboundAttachmentStore
+  /**
+   * Silently registered attachment metadata (`pending_attachments` table):
+   * admission-layer registration, prompt manifest reads, fetch authorization
+   * whitelist, and the TTL/cap sweep wired into the periodic record GC.
+   */
+  private readonly pendingAttachments: PendingAttachmentStore
+  /**
+   * Read-only Feishu message access (P2): the quoted-message excerpt and the
+   * first-turn topic history. Constructed before the inbound router so the
+   * turn assembly can reach it; it resolves the live channel lazily.
+   */
+  private readonly messageReader = new MessageReader({ channel: () => this.channel })
   /** Inbound routing: dedup, admission, decision tree, session establishment. */
   private readonly inbound: InboundRouter
   /** Agent/session lifecycle: live registry, resume, presets, renew. */
   private readonly sessions: SessionManager
+  /**
+   * Model-facing Feishu tools. `feishu_attachment_fetch` plus the shared
+   * per-route known-message whitelist the admission, quote and history layers
+   * populate; `feishu_topic_messages` reads the current topic on demand.
+   */
+  private readonly attachmentFetchTools: AttachmentFetchToolRuntime
+  private readonly topicMessagesTools: TopicMessagesToolRuntime
   /** FIFO admission for ordinary turns and commands targeting one route. */
   private readonly routeOperations = new RouteOperationQueue()
   /** Active Host command executions, aborted before shutdown tears peers down. */
@@ -298,6 +360,10 @@ export class FeishuService {
   private runningConfig: FeishuConfig | undefined
   /** Guards overlapping panel-triggered reconnects. */
   private restarting = false
+  /** One-shot warning for a native deployment without the host attachment library. */
+  private warnedNativeAttachmentsUnmounted = false
+  /** One-shot warning for silently degraded quote/history reads (missing scope). */
+  private warnedPromptReadDegraded = false
   private unlisten: (() => void) | undefined
   /** Disposers for host-scoped listeners registered by `start()`. */
   private readonly unlistenHost: Array<() => boolean> = []
@@ -355,6 +421,24 @@ export class FeishuService {
       persistRoute: (key, record) => this.routes.put(key, record),
       started: () => this.started,
       detachStream: sessionId => this.streamer?.detach(sessionId),
+      mountTools: (agentCtx, sessionId) => {
+        // The fetch tool only makes sense for the lazy native backend: in
+        // archive deployments (explicit, missing host library, or fetch tool
+        // disabled) every attachment is downloaded before the turn and the
+        // Agent reads the workspace copy, so mounting the tool would only
+        // advertise an operation that can never be authorized.
+        //
+        // The topic-messages tool is backend-independent: quoted excerpts and
+        // topic history are read-only, so it is mounted for both backends and
+        // self-gates on `feishuTools.topicMessages`. Both mounts start
+        // together and resolve as one promise (no serial blocking).
+        const mounts: Array<Promise<void>> = []
+        if (this.effectiveAttachmentBackend() === 'native') {
+          mounts.push(this.attachmentFetchTools.mount(agentCtx, sessionId))
+        }
+        mounts.push(this.topicMessagesTools.mount(agentCtx, sessionId))
+        return Promise.all(mounts).then(() => undefined)
+      },
       warn: (message, ...args) => this.ctx.logger?.warn?.(message, ...args),
     })
     this.attachments = new AttachmentIntake({
@@ -362,6 +446,65 @@ export class FeishuService {
       channel: () => this.channel,
       warn: (message, ...args) => this.ctx.logger?.warn?.(message, ...args),
     })
+    this.inboundAttachmentStore = new InboundAttachmentStore({
+      enabled: () => this.config.acceptAttachments,
+      // Effective backend, not the raw config: `store()` is only called after
+      // admission already decided `archive`, so a native-configured deployment
+      // with the fetch tool disabled must download to the workspace here too.
+      mode: () => this.effectiveAttachmentBackend(),
+      service: () => this.nativeAttachmentService(),
+      channel: () => this.channel,
+      archive: this.attachments,
+      warn: (message, ...args) => this.ctx.logger?.warn?.(message, ...args),
+    })
+    this.pendingAttachments = new PendingAttachmentStore({
+      // Undefined storage domain/table → the registry's memory TTL fallback.
+      table: () => this.domain?.pendingAttachments,
+      enabled: () => this.config.acceptAttachments,
+      ttlMs: () => this.config.pendingAttachmentTtlMs,
+      maxPerScope: () => this.config.pendingAttachmentLimit,
+      warn: (message, ...args) => this.ctx.logger?.warn?.(message, ...args),
+    })
+    this.attachmentFetchTools = new AttachmentFetchToolRuntime({
+      config: () => this.config,
+      channel: () => this.channel,
+      pending: () => this.pendingAttachments,
+      routeOfSession: sessionId => {
+        const record = this.routes.findBySession(sessionId)
+        if (record === undefined) return undefined
+        return {
+          key: record.key,
+          kind: record.kind,
+          chatId: record.chatId,
+          chatType: record.chatType,
+          senderOpenId: record.senderOpenId,
+        }
+      },
+      warn: (message, ...args) => this.ctx.logger?.warn?.(message, ...args),
+    })
+    this.topicMessagesTools = new TopicMessagesToolRuntime({
+      config: () => this.config,
+      channel: () => this.channel,
+      routeOfSession: sessionId => {
+        const record = this.routes.findBySession(sessionId)
+        if (record === undefined) return undefined
+        return {
+          key: record.key,
+          kind: record.kind,
+          chatId: record.chatId,
+          chatType: record.chatType,
+          senderOpenId: record.senderOpenId,
+        }
+      },
+      noteKnownMessage: (route, message, source) => {
+        this.attachmentFetchTools.noteKnownMessage(route, message, source)
+      },
+      isKnownMessage: (route, messageId) => this.attachmentFetchTools.isKnownMessage(route, messageId),
+      // The tool description must not promise a fetch tool that archive
+      // deployments do not mount; the runtime appends a degradation note.
+      fetchAvailable: () => this.effectiveAttachmentBackend() === 'native',
+      warn: (message, ...args) => this.ctx.logger?.warn?.(message, ...args),
+    })
     this.delivery = new CardDelivery({
       channel: () => this.channel,
       started: () => this.started,
@@ -397,7 +540,23 @@ export class FeishuService {
       repair: this.repair,
       delivery: this.delivery,
       sessions: this.sessions,
-      attachments: this.attachments,
+      attachmentMode: () => this.config.attachmentStore,
+      nativeAttachments: () => this.nativeAttachmentService(),
+      attachmentStore: this.inboundAttachmentStore,
+      pendingAttachments: this.pendingAttachments,
+      noteKnownAttachments: (record, message, source) => {
+        this.noteKnownAttachmentMessage(record, message, source ?? 'trigger')
+      },
+      messageRead: {
+        quote: input => this.readQuoteContext(input),
+        history: input => this.readHistoryContext(input),
+      },
+      prefetchImages: () => ({
+        enabled: this.config.prefetchImages,
+        maxImageBytes: this.config.prefetchImageMaxBytes,
+        maxTotalBytes: this.config.prefetchTotalMaxBytes,
+        timeoutMs: this.config.prefetchTimeoutMs,
+      }),
       access: this.accessController,
       queue: this.routeOperations,
       streamer: () => this.streamer,
@@ -406,6 +565,222 @@ export class FeishuService {
     })
   }
 
+  /** Effective inbound attachment backend (matches the inbound router). */
+  private effectiveAttachmentBackend(): 'native' | 'archive' {
+    return effectiveAttachmentMode(
+      this.config.attachmentStore,
+      this.nativeAttachmentService(),
+      this.config.feishuTools.attachmentFetch,
+      this.config.acceptAttachments,
+    )
+  }
+
+  /**
+   * Resolve the host's native attachment library from the plugin scope.
+   *
+   * The service is registered host-wide (`@deepseek-ai/dsh-attachment-local`),
+   * so the safe `ctx.get` lookup resolves it even though this plugin does not
+   * declare `attachments` in its cordis `inject` list (the per-Agent scopes
+   * still inject it for the fetch tool). A missing service reads as
+   * `undefined` and switches admission to the legacy archive backend.
+   */
+  private nativeAttachmentService(): AttachmentStore | undefined {
+    const service = resolveAttachmentService(this.ctx)
+    if (service === undefined && this.config.attachmentStore === 'native'
+      && !this.warnedNativeAttachmentsUnmounted) {
+      // The facade now receives the effective backend, so its own downgrade
+      // warning cannot fire: report the missing library once from the resolver.
+      this.warnedNativeAttachmentsUnmounted = true
+      this.ctx.logger?.warn?.(
+        'dsh-channels: attachmentStore=native 但宿主未挂载 ctx.attachments，'
+        + '入站附件回退话题 attachments/ 工作区落盘',
+      )
+    }
+    return service
+  }
+
+  /**
+   * Pre-authorize one admitted Feishu message for `feishu_attachment_fetch`.
+   *
+   * The admission and quote layers call this after their access gates for the
+   * triggering / quoted message; the tool otherwise only authorizes messages
+   * visible in the durable pending-attachment registry. Registering is a pure
+   * in-memory operation (one LRU entry per route) and never fails the caller.
+   */
+  noteKnownAttachmentMessage(
+    record: RouteRecord,
+    message: KnownAttachmentMessageInput,
+    source: KnownAttachmentSource = 'trigger',
+  ): void {
+    this.attachmentFetchTools.noteKnownMessage({
+      key: record.key,
+      kind: record.kind,
+      chatId: record.chatId,
+      chatType: record.chatType,
+      senderOpenId: record.senderOpenId,
+    }, message, source)
+  }
+
+  // ---- read-only message context (quoted excerpt / topic history) -------
+
+  /**
+   * Channel-plane identity of one route for message reads (structurally the
+   * same as the attachment-tool route: key/kind/chat/sender).
+   */
+  private messageReadRouteOf(record: RouteRecord): MessageReadRoute {
+    return {
+      key: record.key,
+      kind: record.kind,
+      chatId: record.chatId,
+      chatType: record.chatType,
+      senderOpenId: record.senderOpenId,
+    }
+  }
+
+  /**
+   * Resolve one quoted message into the bounded `<feishu_quote>` block and the
+   * whitelist registration of the quoted message (merged-forward containers
+   * keep their container id, per the P0 download rule).
+   *
+   * The quoted message must belong to this route's visible container: another
+   * chat is always rejected; on a thread route a quoted message of a
+   * *different* topic is rejected as well (a main-timeline message carries no
+   * thread id and stays allowed — quotes happen before the bot owns a topic);
+   * on a degraded chat route any topic message is rejected (a chat route must
+   * not read another topic of the same group).
+   *
+   * The read budget is the short prompt-enrichment budget, never the model
+   * tool timeout. Read failures (missing scope, deleted message, channel down)
+   * degrade to `undefined`: the turn runs without an excerpt (AC6).
+   */
+  private async readQuoteContext(input: {
+    messageId: string
+    record: RouteRecord
+  }): Promise<{ block: string; message?: KnownAttachmentMessageInput } | undefined> {
+    try {
+      const result = await readQuoteItems(this.messageReader, input.messageId, {
+        timeoutMs: this.config.promptContextTimeoutMs,
+      })
+      if (!result.ok) {
+        this.reportDegradedRead('quoted message', input.messageId, result.reason)
+        return undefined
+      }
+      const container: RawMessageItem | undefined = quoteItemsOf(result.value)
+      if (container === undefined) return undefined
+      if (!this.quotedMessageBelongsToRoute(input.record, container)) {
+        this.ctx.logger?.debug?.(
+          'dsh-channels: dropping quoted message %s from another chat/topic', input.messageId,
+        )
+        return undefined
+      }
+      const block = buildQuoteContextBlock(result.value, {
+        attachmentFetchAvailable: this.attachmentFetchMounted(),
+      })
+      if (block === '') return undefined
+      const message = knownMessageOfItems(result.value)
+      return { block, ...(message === undefined ? {} : { message }) }
+    } catch (error) {
+      // Defensive: the reader reports structured failures; a raw throw is still
+      // only ever a missing excerpt, never a failed turn.
+      this.ctx.logger?.debug?.(
+        'dsh-channels: reading quoted message %s failed: %s', input.messageId, String(error),
+      )
+      return undefined
+    }
+  }
+
+  /** Whether one quoted message may be shown/authorized for one route. */
+  private quotedMessageBelongsToRoute(record: RouteRecord, container: RawMessageItem): boolean {
+    // Fail closed on a missing/foreign chat id: every real Feishu item carries
+    // one, so an absent id is a malformed response, never a legitimate quote.
+    if (container.chatId === undefined || container.chatId !== record.chatId) return false
+    // A main-timeline message has no thread id; a message of another topic must
+    // never leak into this route's excerpt or whitelist. A degraded chat route
+    // (no topic) must reject topic messages entirely, even in the same chat.
+    if (record.kind === 'thread') {
+      return container.threadId === undefined || container.threadId === record.key
+    }
+    return container.threadId === undefined
+  }
+
+  /**
+   * Resolve the bounded first-turn `<feishu_history>` block plus the whitelist
+   * registrations of the history messages (chronological order).
+   *
+   * `limit` is `historyBootstrapLimit` (0/negative → no read at all). The page
+   * is requested newest-first so a long topic yields the most recent messages;
+   * excluded ids (the trigger and the streaming card), deleted messages, and
+   * messages outside the route container are filtered before the newest
+   * `limit` rows are reversed into chronological order for rendering. The read
+   * uses the short prompt-enrichment budget and degrades to `undefined` (AC6).
+   */
+  private async readHistoryContext(input: {
+    record: RouteRecord
+    limit: number
+    excludeMessageIds: readonly string[]
+  }): Promise<{ block: string; messages: readonly KnownAttachmentMessageInput[] } | undefined> {
+    if (!Number.isFinite(input.limit) || input.limit <= 0) return undefined
+    try {
+      const route = this.messageReadRouteOf(input.record)
+      const pageSize = clampInt(
+        input.limit + input.excludeMessageIds.length,
+        1,
+        TOPIC_MESSAGES_MAX_LIMIT,
+      )
+      const result = await this.messageReader.listRoute(route, {
+        pageSize,
+        order: 'newest-first',
+        timeoutMs: this.config.promptContextTimeoutMs,
+      })
+      if (!result.ok) {
+        this.reportDegradedRead('topic history', input.record.key, result.reason)
+        return undefined
+      }
+      const excluded = new Set(input.excludeMessageIds)
+      const recent = result.value.items
+        .filter(item => !item.deleted && !excluded.has(item.messageId))
+        .slice(0, input.limit)
+        .reverse()
+      const block = buildHistoryContextBlock(recent, {
+        maxMessages: input.limit,
+        attachmentFetchAvailable: this.attachmentFetchMounted(),
+      })
+      if (block === '') return undefined
+      return { block, messages: knownMessagesOfHistory(recent) }
+    } catch (error) {
+      this.ctx.logger?.debug?.(
+        'dsh-channels: reading topic history of %s failed: %s', input.record.key, String(error),
+      )
+      return undefined
+    }
+  }
+
+  /** Whether this deployment mounts the lazy attachment fetch tool. */
+  private attachmentFetchMounted(): boolean {
+    return this.effectiveAttachmentBackend() === 'native'
+  }
+
+  /**
+   * Report one silently degraded prompt read: debug per occurrence (expected
+   * when a deployment misses a scope) plus ONE warn per service lifetime so an
+   * operator can find the cause without log spam.
+   */
+  private reportDegradedRead(kind: string, target: string, reason: string): void {
+    if (this.warnedPromptReadDegraded) {
+      this.ctx.logger?.debug?.(
+        'dsh-channels: %s read of %s failed (degraded): %s', kind, target, reason,
+      )
+      return
+    }
+    this.warnedPromptReadDegraded = true
+    this.ctx.logger?.warn?.(
+      'dsh-channels: %s（%s）读取失败，已静默降级（不带引用/历史上下文继续回合）：%s。'
+      + '如持续出现请检查飞书应用的消息读取权限（如 im:message:readonly / im:message.group_msg），'
+      + '或确认该消息未被撤回、网络正常',
+      kind, target, reason,
+    )
+  }
+
   // ---- lifecycle / Web settings panel ----------------------------------
 
   /**
@@ -511,7 +886,7 @@ export class FeishuService {
   /** Re-read the Web overlay over the profile config (no channel touch). */
   private async loadOverlay(): Promise<void> {
     const overlay = this.overlay === undefined ? {} : await this.overlay.load()
-    this.replaceConfig({ ...this.baseConfig, ...overlay })
+    this.replaceConfig(mergeOverlay(this.baseConfig, overlay))
   }
 
   /**
@@ -530,8 +905,8 @@ export class FeishuService {
    * Apply an already-validated overlay over the profile config. Fields read
    * per event/turn take effect immediately; `RESTART_KEYS` need `restart()`.
    */
-  applyOverlay(overlay: Partial<FeishuConfig>): void {
-    this.replaceConfig({ ...this.baseConfig, ...overlay })
+  applyOverlay(overlay: OverlayPatch): void {
+    this.replaceConfig(mergeOverlay(this.baseConfig, overlay))
     this.refreshRetentionTimer()
   }
 
@@ -880,6 +1255,7 @@ export class FeishuService {
       retireRoute: async route => {
         if (route.kind === 'thread') await this.routes.retire(route.key)
         else await this.routes.remove(route.key)
+        this.attachmentFetchTools.forgetRoute(route.key)
       },
       warn: message => this.ctx.logger?.warn?.(message),
     }
@@ -1258,6 +1634,7 @@ export class FeishuService {
       this.retentionTimer = undefined
     }
     await this.sessions.disposeAll()
+    this.attachmentFetchTools.clear()
     this.routeOperations.clear()
     this.inbound.clear()
     this.routes.clear()
@@ -2018,13 +2395,18 @@ export class FeishuService {
 
 
   /**
-   * GC pass over the routing domain. Two independent halves:
+   * GC pass over the routing domain. Three independent parts:
    *
    * 1. Dedup records (unconditional): `processed` records and in-process
    *    guard entries older than `PROCESSED_RETENTION_MS` are dropped —
    *    redelivery windows are minutes, so a day of retention is ample and
    *    keeps the table bounded regardless of the route TTL setting.
-   * 2. Route/inflight GC (`routeTtlMs > 0`): thread routes idle past the TTL
+   * 2. Pending attachment metadata (unconditional): rows past
+   *    `pendingAttachmentTtlMs` and rows above `pendingAttachmentLimit` per
+   *    `(chat, thread?, sender)` scope are removed. Independent of the route
+   *    TTL: the registry keeps its own 7-day default even when route retirement
+   *    is disabled.
+   * 3. Route/inflight GC (`routeTtlMs > 0`): thread routes idle past the TTL
    *    are retired into minimal persistent tombstones before their active
    *    records are deleted. A later message in that visible topic is then
    *    rejected instead of silently creating a context-free Session. Degraded
@@ -2057,6 +2439,18 @@ export class FeishuService {
     }
     this.inbound.pruneAccepted(processedCutoff)
 
+    try {
+      const pruned = await this.pendingAttachments.prune()
+      if (pruned.removedExpired > 0 || pruned.removedOverLimit > 0) {
+        this.ctx.logger?.info?.(
+          'dsh-channels: record GC removed %d expired and %d over-limit pending attachment record(s)',
+          pruned.removedExpired, pruned.removedOverLimit,
+        )
+      }
+    } catch (error) {
+      this.ctx.logger?.warn?.('dsh-channels: pending attachment GC failed: %s', String(error))
+    }
+
     const ttlMs = this.config.routeTtlMs
     if (ttlMs === 0) {
       if (removedProcessed > 0) {
@@ -2077,6 +2471,7 @@ export class FeishuService {
           } else {
             await this.routes.remove(key)
           }
+          this.attachmentFetchTools.forgetRoute(key)
           removedRoutes++
         } catch (error) {
           this.ctx.logger?.warn?.('dsh-channels: GC of route %s failed: %s', key, String(error))
@@ -2084,6 +2479,19 @@ export class FeishuService {
       }
     }
 
+    // Reconcile the attachment-fetch whitelist with the active route set: the
+    // inbound TTL path retires a thread route directly (tombstone), so its
+    // in-memory whitelist bucket would otherwise live until process exit.
+    const droppedToolRoutes = this.attachmentFetchTools.pruneRoutes(
+      routeKey => this.routes.get(routeKey) !== undefined,
+    )
+    if (droppedToolRoutes > 0) {
+      this.ctx.logger?.info?.(
+        'dsh-channels: record GC dropped %d stale attachment-tool route bucket(s)',
+        droppedToolRoutes,
+      )
+    }
+
     const inflight = this.domain?.inflight
     if (inflight !== undefined) {
       for (const [key, snapshot] of [...inflight.entries()]) {