@modesto_ma/dsh-channels 0.2.0 → 0.4.0

package/src/service.ts

@@ -6,6 +6,10 @@
  *  - p2p:   one workspace per (bot, user), all of that user's sessions inside;
  *  - group: one workspace per (chat, user), sessions grouped per user.
  *
+ * Every topic's Session works in its own directory inside that workspace
+ * (`topics/<token>` or a Git worktree), so topics never mix files while the
+ * workspace list grows with users instead of conversations.
+ *
  * Routing model:
  *  - `thread_id` → bound session (no @ needed inside an owned topic);
  *  - degraded chat-scoped keys when Feishu refuses topic replies;
@@ -45,15 +49,15 @@ import type { EffortCommandAction, ParsedSlashCommand } from './commands.ts'
 import { commandSpec } from './commands/registry.ts'
 import type { ChannelCommandSpec } from './commands/registry.ts'
 import type { PermissionPresets, SessionQuery } from './dsh-types.ts'
-import { feishuDomain } from './domain.ts'
+import { feishuDomain, sessionDirOf } from './domain.ts'
 import {
   applyWorkspaceCleanup, isPathInside, planWorkspaceCleanup, retentionMs,
 } from './cleanup.ts'
-import type { CleanupDeps, WorkspaceStats } from './cleanup.ts'
+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'
@@ -61,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'
@@ -82,7 +97,9 @@ 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
  *  dead records; TTL semantics make 6 h granularity more than sufficient). */
@@ -122,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,
@@ -165,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(),
@@ -265,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. */
@@ -293,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> = []
@@ -350,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({
@@ -357,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,
@@ -392,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,
@@ -401,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 ----------------------------------
 
   /**
@@ -506,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))
   }
 
   /**
@@ -525,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()
   }
 
@@ -716,12 +1096,12 @@ export class FeishuService {
     return value
   }
 
-  // ---- workspace retention cleanup -------------------------------------
+  // ---- retention cleanup ------------------------------------------------
 
   /**
-   * Workspace-retention preview for the Web panel: how many plugin-created
-   * workspaces exist, how many are past the configured window, and their
-   * measured footprint. Never deletes anything.
+   * Retention preview for the Web panel: how many plugin workspaces exist,
+   * how many directories are past the configured window, and their measured
+   * footprint. Never deletes anything.
    */
   async cleanupPreview(): Promise<{
     retention: string
@@ -741,7 +1121,7 @@ export class FeishuService {
     }
     if (this.domain === undefined) {
       // No connection: routes live in the closed storage domain, so a preview
-      // would mistake every workspace for a candidate. Report why instead.
+      // would mistake every directory for a candidate. Report why instead.
       return {
         ...base,
         workspaces: 0,
@@ -765,43 +1145,57 @@ export class FeishuService {
   }
 
   /**
-   * Delete every stale plugin workspace the configured retention allows.
-   * Routes bound to a removed workspace are retired first (thread routes leave
-   * a tombstone), so an old topic fails with the explicit expired card instead
-   * of resuming into a missing directory. DSH Session logs are not touched.
+   * Delete every stale plugin directory the configured retention allows: the
+   * per-topic working directories of current conversations and the legacy
+   * one-workspace-per-topic directories of older versions. User workspaces are
+   * never deleted.
+   *
+   * Active routes bound to a removed directory are retired first (thread
+   * routes leave a tombstone), so an old topic fails with the explicit expired
+   * card instead of resuming into a missing directory. DSH Session logs are not
+   * touched.
    */
   async runWorkspaceCleanup(): Promise<{
     ok: boolean
     deletedWorkspaces: number
+    deletedSessionDirs: number
     retiredRoutes: number
     freedBytes: number
     failures: string[]
     error?: string
   }> {
-    const empty = { ok: false, deletedWorkspaces: 0, retiredRoutes: 0, freedBytes: 0, failures: [] as string[] }
+    const empty = {
+      ok: false,
+      deletedWorkspaces: 0,
+      deletedSessionDirs: 0,
+      retiredRoutes: 0,
+      freedBytes: 0,
+      failures: [] as string[],
+    }
     if (this.domain === undefined) {
       // Without the storage domain the route table is unreadable, so a cleanup
-      // could mistake live workspaces for candidates and fail to retire their
+      // could mistake live directories for candidates and fail to retire their
       // routes. Refuse rather than rely on the panel disabling the button.
       return { ...empty, error: '飞书连接建立后才能清理工作区' }
     }
     if (retentionMs(this.config.workspaceRetention) === undefined) {
-      return { ...empty, error: '未启用工作区清理阈值（workspaceRetention 为 off）' }
+      return { ...empty, error: '未启用目录清理阈值（workspaceRetention 为 off）' }
     }
-    if (this.cleanupRunning) return { ...empty, error: '工作区清理正在进行中，请稍候' }
+    if (this.cleanupRunning) return { ...empty, error: '目录清理正在进行中，请稍候' }
     this.cleanupRunning = true
     try {
       const deps = this.cleanupDeps()
       const plan = await planWorkspaceCleanup(deps)
-      if (plan === undefined) return { ...empty, error: '工作区清理不可用：baseDir 配置无效' }
+      if (plan === undefined) return { ...empty, error: '目录清理不可用：baseDir 配置无效' }
       const outcome = await applyWorkspaceCleanup(deps, plan)
       this.ctx.logger?.info?.(
-        'dsh-channels: workspace cleanup removed %d workspace(s), retired %d route(s), freed %d bytes',
-        outcome.deletedWorkspaces, outcome.retiredRoutes, outcome.freedBytes,
+        'dsh-channels: retention cleanup removed %d legacy workspace(s) and %d topic dir(s), retired %d route(s), freed %d bytes',
+        outcome.deletedWorkspaces, outcome.deletedSessionDirs, outcome.retiredRoutes, outcome.freedBytes,
       )
       return {
         ok: true,
         deletedWorkspaces: outcome.deletedWorkspaces,
+        deletedSessionDirs: outcome.deletedSessionDirs,
         retiredRoutes: outcome.retiredRoutes,
         freedBytes: outcome.freedBytes,
         failures: outcome.failures.map(failure => `${failure.path}: ${failure.message}`),
@@ -826,39 +1220,27 @@ export class FeishuService {
       baseDir,
       retention: this.config.workspaceRetention,
       listWorkspaces: () => this.ctx.workspaceRegistry.list(),
-      activeRoutes: () => [...(this.domain?.routes.entries() ?? [])].map(([key, record]) => ({
+      listSessionDirs: () => this.listCleanableSessionDirs(baseDir),
+      activeRoutes: () => [...(this.domain?.routes.entries() ?? [])].map(([key, record]): CleanupRoute => ({
         key,
         kind: record.kind,
         workspacePath: record.workspacePath,
+        ...(record.sessionDir === undefined ? {} : { sessionDir: record.sessionDir }),
         sessionId: record.sessionId,
         lastActivityAt: record.lastActivityAt,
       })),
-      tombstones: () => [...(this.domain?.expiredRoutes.entries() ?? [])].map(([key, record]) => ({
+      tombstones: () => [...(this.domain?.expiredRoutes.entries() ?? [])].map(([key, record]): CleanupTombstone => ({
         key,
         ...(record.workspacePath === undefined ? {} : { workspacePath: record.workspacePath }),
+        ...(record.sessionDir === undefined ? {} : { sessionDir: record.sessionDir }),
         expiredAt: record.expiredAt,
         ...(record.lastActivityAt === undefined ? {} : { lastActivityAt: record.lastActivityAt }),
       })),
       isLive: sessionId => this.sessions.get(sessionId) !== undefined
         || this.ctx.agents.get(sessionId as SessionId) !== undefined,
-      statWorkspace: workspacePath => measureWorkspace(workspacePath),
+      statWorkspace: directory => measureWorkspace(directory),
       removeWorkspace: async workspace => {
-        const target = path.resolve(workspace.path)
-        if (!isPathInside(baseDir, target)) {
-          throw new Error(`refusing to delete a path outside baseDir (${target})`)
-        }
-        // Re-verify the physical path: a symlinked ancestor inside baseDir
-        // must not let the recursive delete escape it.
-        try {
-          const [physicalBase, physicalTarget] = await Promise.all([realpath(baseDir), realpath(target)])
-          if (!isPathInside(physicalBase, physicalTarget)) {
-            throw new Error(`refusing to delete a symlink escape outside baseDir (${physicalTarget})`)
-          }
-        } catch (error) {
-          if (error instanceof Error && error.message.startsWith('refusing to delete a symlink escape')) throw error
-          // A missing workspace is already effectively removed (rm is idempotent).
-        }
-        await rm(target, { recursive: true, force: true })
+        await this.deleteDirectoryInsideBase(baseDir, workspace.path)
         try {
           await this.ctx.workspaceRegistry.delete(workspace.id)
         } catch (error) {
@@ -867,14 +1249,83 @@ export class FeishuService {
           )
         }
       },
+      removeSessionDir: async directory => {
+        await this.deleteDirectoryInsideBase(baseDir, directory)
+      },
       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),
     }
   }
 
+  /**
+   * Scan the live user workspaces for per-topic working directories that no
+   * route record points at anymore (for example the old route of a degraded
+   * chat conversation was deleted by TTL retirement). Route/tombstone evidence
+   * wins for age; the scan mtime only covers true orphans.
+   */
+  private async listCleanableSessionDirs(baseDir: string): Promise<ScannedSessionDir[]> {
+    const legacyRoot = legacyTopicWorkspaceRoot(baseDir)
+    const roots: string[] = []
+    for (const workspace of this.ctx.workspaceRegistry.list()) {
+      if (!this.isPluginWorkspace(workspace)) continue
+      const resolved = path.resolve(workspace.path)
+      // Legacy per-topic workspaces are cleaned as workspaces, not scanned here.
+      if (isPathInside(legacyRoot, resolved)) continue
+      roots.push(resolved)
+    }
+    const scanned: ScannedSessionDir[] = []
+    for (const root of roots) {
+      for (const relative of ['topics', path.join('.agents', 'worktrees')]) {
+        const directory = path.join(root, relative)
+        let entries
+        try {
+          entries = await readdir(directory, { withFileTypes: true })
+        } catch {
+          continue
+        }
+        for (const entry of entries) {
+          if (!entry.isDirectory()) continue
+          const candidate = path.join(directory, entry.name)
+          try {
+            const info = await lstat(candidate)
+            if (info.isDirectory()) scanned.push({ path: candidate, mtimeMs: info.mtimeMs })
+          } catch {
+            // Removed or unreadable between readdir and lstat; skip it.
+          }
+        }
+      }
+    }
+    return scanned
+  }
+
+  /**
+   * Recursively delete one plugin directory below `baseDir`.
+   *
+   * The lexical check refuses paths outside `baseDir`; the realpath check then
+   * refuses a symlinked ancestor that would let the recursive delete escape
+   * the plugin root. A missing directory is already effectively removed.
+   */
+  private async deleteDirectoryInsideBase(baseDir: string, target: string): Promise<void> {
+    const resolved = path.resolve(target)
+    if (!isPathInside(baseDir, resolved)) {
+      throw new Error(`refusing to delete a path outside baseDir (${resolved})`)
+    }
+    try {
+      const [physicalBase, physicalTarget] = await Promise.all([realpath(baseDir), realpath(resolved)])
+      if (!isPathInside(physicalBase, physicalTarget)) {
+        throw new Error(`refusing to delete a symlink escape outside baseDir (${physicalTarget})`)
+      }
+    } catch (error) {
+      if (error instanceof Error && error.message.startsWith('refusing to delete a symlink escape')) throw error
+      // A missing directory is already effectively removed (rm is idempotent).
+    }
+    await rm(resolved, { recursive: true, force: true })
+  }
+
   /**
    * (Re)arm the daily retention timer to match the live config. `runNow`
    * performs one pass immediately; it is only used at startup so saving any
@@ -890,7 +1341,7 @@ export class FeishuService {
       || retentionMs(this.config.workspaceRetention) === undefined) return
     const sweep = (): void => {
       void this.runWorkspaceCleanup().then(result => {
-        if (!result.ok && result.error !== '工作区清理正在进行中，请稍候') {
+        if (!result.ok && result.error !== '目录清理正在进行中，请稍候') {
           this.ctx.logger?.warn?.('dsh-channels: automatic workspace cleanup failed: %s', result.error)
         }
       })
@@ -1183,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()
@@ -1724,7 +2176,7 @@ export class FeishuService {
       await this.delivery.standaloneReply(msg, buildRenewCard({
         previousSessionId: renewAdmission.commit.previous.sessionId,
         currentSessionId: renewAdmission.commit.current.sessionId,
-        workspacePath: renewAdmission.commit.current.workspacePath,
+        sessionDir: sessionDirOf(renewAdmission.commit.current),
       }))
       return
     }
@@ -1744,7 +2196,7 @@ export class FeishuService {
         context,
         extras: {
           permissionPreset: this.permissionPresetOf(session),
-          workspacePath: current.workspacePath,
+          sessionDir: sessionDirOf(current),
           uptimeMs: this.startedAt === undefined ? undefined : Date.now() - this.startedAt,
           liveAgents: this.sessions.liveCount(),
           routeCount: this.routes.size(),
@@ -1753,7 +2205,10 @@ export class FeishuService {
       return
     }
     if (spec.name === 'workspace' && result.kind === 'success') {
-      const resolved = resolveWorkDir(live.agent.session.header.cwd, current.workspacePath)
+      const resolved = resolveWorkDir(live.agent.session.header.cwd, {
+        workspacePath: current.workspacePath,
+        ...(current.sessionDir === undefined ? {} : { sessionDir: current.sessionDir }),
+      })
       if (resolved.kind === 'success') {
         await this.delivery.standaloneReply(msg, buildWorkDirCard(current.sessionId, resolved.path))
         return
@@ -1940,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
@@ -1979,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) {
@@ -1999,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))
@@ -2006,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()]) {