dsh-conversation-recycle-bin 0.3.9 → 0.3.10

package/CHANGELOG.md

@@ -3,6 +3,25 @@
 All notable changes to `dsh-conversation-recycle-bin` are documented here.
 The format follows Keep a Changelog; the project uses Semantic Versioning.
 
+## [0.3.10] — 2026-10-27
+
+回收站「30 天后自动清理」。这一版把一个**从 0.3.0 起就写在配置里、但从来没人读**的旋钮（`trashRetentionDays`）真正接上了逻辑。
+
+### Added
+
+- **`lib/core/retention.js`**：纯函数选期 —— `selectExpired(entries, { retentionDays, now, limit })` 只挑 `status: 'trashed'`、`deletedAt` 可解析且早于窗口的条目，最旧优先；`daysUntilExpiry()` 供 UI 显示剩余天数。任何"说不准"的输入（`retentionDays <= 0`、`deletedAt` 缺失/非法、`trashId` 为空、`now` 非有限值）一律**不清**，宁可留着让人自己删。
+- **Host 侧清扫**：`lib/host/api.js` 新增 `sweepExpiredTrash({ force })`，`trashList()` 每次先扫（5 分钟节流）；`lib/index.js` 另加 6 小时定时（启动后 60 秒先扫一次，`unref` 不影响退出）。清扫走与「永久清除」**完全相同**的 `performPurge`，并且在跨进程 mutation 锁内**重新读 manifest、复判 `entryCapabilities().canPurge`**（scan 发生在锁外，期间条目可能已被恢复），单次最多 20 条，单条失败不中断整轮。
+- **UI**：回收站面板顶部写明"条目在删除 N 天后自动清理"（`trashRetentionDays: 0` 时不显示），每行显示"N 天后自动清理"。
+- 审计：自动清理的记录与手动彻底删除同形，额外带 `source: 'retention'`，可与用户操作区分。
+
+### Changed
+
+- `config.schema.json` 里 `trashRetentionDays` 的说明改为实际行为（每 6 小时 + 每次列表时检查，0 = 关闭）。
+
+### Tests
+
+- 新增 `test/retention.test.mjs`（8 条纯函数用例），`test/api.test.mjs` 追加 3 条集成用例（过期条目被下一次列表清掉、`0` 关闭清扫、从未提交的残留条目永不清扫）。测试 153 → **164**。
+
 ## [0.3.9] — 2026-10-27
 
 0.3.8 的紧急修复：**所有删除都会被拒绝**，返回 `409 E_ABANDONED`（"The client disconnected before this request ran; nothing was changed."）。0.3.8 发布后不到一天即被用户在使用中撞到。

package/README.md

@@ -149,6 +149,8 @@ memory  →  messages  →  session/catalog
       files/<nodeId>.content
 ```
 
+**保留期（自动清理）**：`trashRetentionDays`（默认 **30**）现在真的生效 —— Host 每 6 小时清扫一次（启动后 60 秒先扫一次），并且**每次打开回收站列表前也会扫一次**（5 分钟内不重复）。只有 `status: 'trashed'` 且 `deletedAt` 可解析、且早于 `now - trashRetentionDays` 的条目会被清走，走的是与「永久清除」**完全相同**的 `performPurge` 路径（重新读 manifest、复判 `capabilities.canPurge`、写审计 `action: 'purge'` + `source: 'retention'`），单次最多 20 条、最旧优先。`pending`/`restoring`/`restored`/`purging` 与"从未提交"的残留条目**永不自动清**（那是 bug 现场，留给设置页的「恢复」/「discard」出口）。`trashRetentionDays: 0` 关闭清扫，条目一直留到你自己删。回收站列表里会写明"删除 N 天后自动清理"，每条还显示剩余天数。
+
 `manifest.status` 只允许 `pending → trashed → restoring/restored / purging`。`GET /trash` 把**所有**条目都返回：`trashed` 进 `entries`（回收站 UI，可恢复/彻底删除），其余状态进 `incomplete`（设置页单独列出，提供「恢复」与「discard」两个出口，不再出现"失败了却没有任何清理入口"的死条目）。恢复顺序是删除的逆序：日志 → catalog → 记忆。
 
 ---

package/client.js

@@ -112,6 +112,8 @@ window.__ModuleLoader__.load({
         'trash.title': 'Recycle bin',
         'trash.empty': 'The recycle bin is empty.',
         'trash.deletedAt': 'Deleted {time}',
+        'trash.retention': 'Entries are purged automatically {days} days after deletion. Set trashRetentionDays to 0 to keep them until you purge them yourself.',
+        'trash.expiresIn': 'auto-purged in {days} d',
         'trash.modeSoft': 'soft',
         'trash.modeHard': 'permanent',
         'trash.items': '{sessions} conversation(s) · {memories} memory entries',
@@ -268,6 +270,8 @@ window.__ModuleLoader__.load({
         'trash.title': '回收站',
         'trash.empty': '回收站为空。',
         'trash.deletedAt': '删除于 {time}',
+        'trash.retention': '条目在删除 {days} 天后自动清理。把 trashRetentionDays 设为 0 可改为一直保留、由你自己彻底删除。',
+        'trash.expiresIn': '{days} 天后自动清理',
         'trash.modeSoft': '软删除',
         'trash.modeHard': '彻底',
         'trash.items': '{sessions} 个对话 · {memories} 条记忆',
@@ -1804,6 +1808,15 @@ window.__ModuleLoader__.load({
         ? state.limits.effectiveBatch
         : (state?.limits?.maxBatchSessions ?? 0)
       const overLimit = effectiveBatch > 0 && selectedIds.length > effectiveBatch
+      // The Host purges entries on its own after `trashRetentionDays`; the row
+      // hint has to be computed from the same number or it would promise a
+      // window the Host does not keep.
+      const retentionDays = Number(state?.trashRetentionDays) > 0 ? Number(state.trashRetentionDays) : 0
+      const daysLeft = (entry) => {
+        if (retentionDays <= 0 || !Number.isFinite(entry?.deletedAt) || entry.deletedAt <= 0) return null
+        const left = entry.deletedAt + retentionDays * 86_400_000 - Date.now()
+        return left <= 0 ? 0 : Math.ceil(left / 86_400_000)
+      }
 
       const openFeedback = () => dialogStore.open({
         kind: 'feedback',
@@ -1868,12 +1881,13 @@ window.__ModuleLoader__.load({
           : null,
 
         tab === 'trash' ? h('div', { id: 'dc-panel-trash', role: 'tabpanel', 'aria-labelledby': 'dc-tab-trash', className: 'dc-panel' },
+          retentionDays > 0 ? h('div', { className: 'dc-hint dc-hint-block' }, t('trash.retention', { days: retentionDays })) : null,
           trash.length === 0 ? h('div', { className: 'dc-empty' }, t('trash.empty')) : null,
           ...trash.map((entry) => h('div', { key: entry.trashId, className: 'dc-row' },
             h('div', { className: 'dc-row-main' },
               h('div', { className: 'dc-row-title' }, entry.title || entry.sessionId),
               h('div', { className: 'dc-hint' },
-                `${t('trash.deletedAt', { time: formatTime(entry.deletedAt) })} · ${entry.mode === 'hard' ? t('trash.modeHard') : t('trash.modeSoft')} · ${t('trash.items', { sessions: 1, memories: entry.memory ?? 0 })}`)),
+                `${t('trash.deletedAt', { time: formatTime(entry.deletedAt) })} · ${entry.mode === 'hard' ? t('trash.modeHard') : t('trash.modeSoft')} · ${t('trash.items', { sessions: 1, memories: entry.memory ?? 0 })}${daysLeft(entry) === null ? '' : ` · ${t('trash.expiresIn', { days: daysLeft(entry) })}`}`)),
             h('div', { className: 'dc-row-actions' },
               h(Button, { onClick: () => { void restore(entry.trashId) } }, t('action.restore')),
               purgeTarget === entry.trashId

package/config.schema.json

@@ -28,7 +28,7 @@
       "description": "When non-empty, a session may only be deleted when its workspace path is inside one of these roots."
     },
     "defaultMode": { "enum": ["soft", "hard"], "default": "soft", "description": "Initial mode selected in the confirmation dialog." },
-    "trashRetentionDays": { "type": "number", "minimum": 0, "maximum": 3650, "default": 30, "description": "Informational retention shown in the recycle bin; purging is always explicit." },
+    "trashRetentionDays": { "type": "number", "minimum": 0, "maximum": 3650, "default": 30, "description": "Days a committed recycle-bin entry is kept before the Host purges it automatically (checked every six hours and whenever /trash is listed). 0 disables the sweep, leaving entries until the user purges them." },
     "maxBatchSessions": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 50, "description": "Upper bound on one batch. The effective limit is min(this, remaining deletions in the current minute), so a batch can never exceed the rate budget." },
     "maxDeletesPerMinute": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 20, "description": "Sliding-window limit for conversation deletions (single and batch items count individually)." },
     "confirmTokenTtlMs": { "type": "integer", "minimum": 5000, "maximum": 3600000, "default": 120000 },

package/lib/core/config.js

@@ -40,6 +40,9 @@ export const DEFAULTS = deepFreeze({
   protectedSessionIds: [],
   allowedWorkspaceRoots: [],
   defaultMode: 'soft',
+  // Days a committed entry may stay in the recycle bin before the Host purges
+  // it on its own (see `core/retention.js`). 0 disables the sweep: entries then
+  // stay until the user purges or discards them.
   trashRetentionDays: 30,
   maxBatchSessions: 50,
   maxDeletesPerMinute: 20,

package/lib/core/retention.js

@@ -0,0 +1,74 @@
+/**
+ * Recycle-bin retention policy.
+ *
+ * `trashRetentionDays` used to be informational only: it was validated, shown
+ * in `state()` and then never read again, so an entry stayed on disk forever
+ * and the documented "30 days" never happened. This module is the single
+ * predicate behind the automatic sweep, kept pure so the rule can be tested
+ * without a filesystem.
+ *
+ * Two deliberate refusals:
+ *   - only `trashed` entries expire. `pending` / `failed` / `restoring` /
+ *     `purging` are mid-transaction or unreadable states: their age says
+ *     nothing about whether the transaction committed, so they are surfaced to
+ *     the user for an explicit discard instead of being swept.
+ *   - an entry whose `deletedAt` is missing, zero or not a finite number is
+ *     never treated as "old". Guessing an age would silently destroy data that
+ *     a corrupt or hand-edited manifest could not date.
+ */
+
+/** Milliseconds in one day; exported so the Client-facing math can reuse it. */
+export const DAY_MS = 86_400_000
+
+/**
+ * Entries that are past the retention window, oldest first.
+ *
+ * @param {object[]} entries manifests from `trash.scanAll()`
+ * @param {object} options
+ * @param {number} options.retentionDays 0 (or negative/NaN) disables the sweep
+ * @param {() => number|number} [options.now]
+ * @param {number} [options.limit] cap per run so a huge bin cannot stall one sweep
+ * @returns {object[]}
+ */
+export function selectExpired(entries, { retentionDays, now = Date.now, limit = 20 } = {}) {
+  const days = Number(retentionDays)
+  if (!Number.isFinite(days) || days <= 0) return []
+  const at = typeof now === 'function' ? now() : Number(now)
+  if (!Number.isFinite(at)) return []
+  const cutoff = at - days * DAY_MS
+  const expired = []
+  for (const entry of Array.isArray(entries) ? entries : []) {
+    if (entry === null || typeof entry !== 'object') continue
+    if (entry.status !== 'trashed') continue
+    if (typeof entry.trashId !== 'string' || entry.trashId === '') continue
+    const deletedAt = entry.deletedAt
+    if (!Number.isFinite(deletedAt) || deletedAt <= 0) continue
+    if (deletedAt > cutoff) continue
+    expired.push(entry)
+  }
+  expired.sort((left, right) => left.deletedAt - right.deletedAt)
+  const max = Number.isFinite(limit) ? Math.max(0, Math.trunc(limit)) : 20
+  return expired.slice(0, max)
+}
+
+/**
+ * Whole days left before an entry expires, for the Client's per-row hint.
+ * `null` when retention is off or the entry cannot be dated.
+ *
+ * @param {object} entry
+ * @param {object} options
+ * @param {number} options.retentionDays
+ * @param {() => number|number} [options.now]
+ * @returns {number|null}
+ */
+export function daysUntilExpiry(entry, { retentionDays, now = Date.now } = {}) {
+  const days = Number(retentionDays)
+  if (!Number.isFinite(days) || days <= 0) return null
+  const deletedAt = entry?.deletedAt
+  if (!Number.isFinite(deletedAt) || deletedAt <= 0) return null
+  const at = typeof now === 'function' ? now() : Number(now)
+  if (!Number.isFinite(at)) return null
+  const left = deletedAt + days * DAY_MS - at
+  if (left <= 0) return 0
+  return Math.ceil(left / DAY_MS)
+}

package/lib/host/api.js

@@ -44,6 +44,7 @@ import { join } from 'node:path'
 import { DeleteError, ERROR_STATUS, asDeleteError, toWireError } from '../core/errors.js'
 import { redactDetails } from '../core/redact.js'
 import { createAuditLog } from '../core/audit.js'
+import { selectExpired } from '../core/retention.js'
 import { createTrashStore, isTrashId } from '../core/trash.js'
 import { createMemoryService } from '../core/memory/registry.js'
 import { performSessionDelete, performPurge, performRestore, performDiscard, entryCapabilities } from '../core/cascade.js'
@@ -410,6 +411,14 @@ export function createDeleteApi({ ctx, config, paths, now = Date.now, logger = c
   // the settings page responsive while every mutation invalidates it, so the
   // user never sees a stale list after their own action.
   const TRASH_CACHE_TTL_MS = 1_500
+  // Retention is a background chore, not a request: at most one sweep every
+  // five minutes (a `/trash` poll must not rescan the whole bin each time), and
+  // at most this many entries per sweep so one huge bin cannot hold the
+  // mutation lock for minutes.
+  const RETENTION_SWEEP_THROTTLE_MS = 300_000
+  const RETENTION_MAX_PER_RUN = 20
+  let lastRetentionSweepAt = 0
+  let retentionSweepInFlight = null
   let trashCache = null
   let trashCachedAt = 0
   function invalidateTrashCache() {
@@ -956,6 +965,10 @@ export function createDeleteApi({ ctx, config, paths, now = Date.now, logger = c
   }
 
   async function trashList() {
+    // Sweep before reading so the rows the user sees are the ones that survived
+    // the retention window, not entries this very listing is about to purge.
+    // The call is throttled and returns immediately when retention is off.
+    await sweepExpiredTrash()
     if (trashCache !== null && now() - trashCachedAt < TRASH_CACHE_TTL_MS) return trashCache
     // Every readable manifest is returned: `trashed` entries are the usable
     // recycle bin, while failed/pending/restoring/purging entries used to be
@@ -991,6 +1004,70 @@ export function createDeleteApi({ ctx, config, paths, now = Date.now, logger = c
     return result
   }
 
+  /**
+   * Automatic retention: purge entries that have been in the recycle bin for
+   * more than `trashRetentionDays` days.
+   *
+   * The sweep runs under the same `serialize` lock as a user mutation, so it
+   * can never interleave with a restore/purge of the same entry, and it re-reads
+   * each manifest under that lock (the scan that selected the candidates ran
+   * outside it). `force` exists for tests and for a Host that just started;
+   * production callers use the throttle so a `/trash` poll cannot turn into a
+   * scan-and-purge loop.
+   *
+   * Failure policy: one un-purgeable entry never aborts the sweep. The cascade
+   * already wrote its own `purge:failed` audit record, and the entry stays in
+   * the bin for the next run or for the user.
+   */
+  async function sweepExpiredTrash({ force = false } = {}) {
+    const retentionDays = config.trashRetentionDays
+    if (!(Number(retentionDays) > 0)) return { enabled: false, purged: [], failed: [], retentionDays: 0 }
+    if (retentionSweepInFlight !== null) return retentionSweepInFlight
+    if (force !== true && now() - lastRetentionSweepAt < RETENTION_SWEEP_THROTTLE_MS) {
+      return { skipped: true, purged: [], failed: [], retentionDays }
+    }
+    const run = (async () => {
+      const scannedAt = now()
+      const { entries } = await trash.scanAll()
+      const expired = selectExpired(entries, { retentionDays, now: scannedAt, limit: RETENTION_MAX_PER_RUN })
+      if (expired.length === 0) return { purged: [], failed: [], retentionDays }
+      return serialize(async () => {
+        const purged = []
+        const failed = []
+        for (const candidate of expired) {
+          const entry = await trash.read(candidate.trashId)
+          if (entry === null || !entryCapabilities(entry).canPurge) continue
+          try {
+            await performPurge({ entry, ops, trash, audit, now, actor: 'local-user', source: 'retention', requestId: requestId() })
+            purged.push(entry.trashId)
+          } catch (error) {
+            const normalized = asDeleteError(error)
+            failed.push({ trashId: candidate.trashId, code: normalized.code })
+            logger.warn?.(`[conversation-recycle-bin] retention: ${candidate.trashId} could not be purged (${normalized.code})`)
+          }
+        }
+        if (purged.length > 0) {
+          gateway.invalidate()
+          invalidateTrashCache()
+        }
+        return { purged, failed, retentionDays }
+      }, { lockTimeoutMs: TRASH_LOCK_BUDGET_MS })
+    })()
+      .catch((error) => {
+        // A busy lock or a crashed scan is not an error the user can act on:
+        // record it and let the next sweep try again.
+        const normalized = asDeleteError(error)
+        logger.warn?.(`[conversation-recycle-bin] retention sweep skipped (${normalized.code})`)
+        return { purged: [], failed: [{ trashId: null, code: normalized.code }], retentionDays }
+      })
+      .finally(() => {
+        retentionSweepInFlight = null
+        lastRetentionSweepAt = now()
+      })
+    retentionSweepInFlight = run
+    return run
+  }
+
   async function auditTail(limit) {
     const parsed = Number.parseInt(String(limit ?? '50'), 10)
     const safe = Number.isFinite(parsed) ? Math.min(Math.max(parsed, 1), 200) : 50
@@ -1214,8 +1291,14 @@ export function createDeleteApi({ ctx, config, paths, now = Date.now, logger = c
   return {
     handler,
     routePrefix: ROUTE_PREFIX,
+    /**
+     * Run one retention sweep. Called by the Host timer in `index.js` and by
+     * `/trash` (throttled); exposed so the entry point does not need to know
+     * how the sweep selects its candidates.
+     */
+    sweepExpiredTrash,
     handler_services: { gateway, memoryService, trash, audit, limiter, feedbackService },
     // exported for tests
-    __test: { preview, deletePlan, restoreEntry, purgeEntry, discardEntry, state, sessionsForUi, trashList, auditTail, issueConfirmation, validateConfirmation, markConfirmationUsed, expectedPhrase, effectiveBatchLimit, feedbackService },
+    __test: { preview, deletePlan, restoreEntry, purgeEntry, discardEntry, state, sessionsForUi, trashList, auditTail, sweepExpiredTrash, issueConfirmation, validateConfirmation, markConfirmationUsed, expectedPhrase, effectiveBatchLimit, feedbackService },
   }
 }

package/lib/index.js

@@ -5,8 +5,11 @@
  *   - it depends on nothing but `webServer` (the only service needed to reach
  *     the UI); every data service is probed per request so a slimmer profile
  *     degrades to a readable error instead of a failed plugin fiber;
- *   - it performs NO deletion work in `apply`; all authority lives behind the
- *     user-confirmed HTTP plan (see `host/api.js`);
+ *   - `apply` itself deletes nothing. The only autonomous work it schedules is
+ *     the recycle-bin retention sweep (`trashRetentionDays`, default 30 days),
+ *     which is the documented promise of that setting and is switched off with
+ *     `trashRetentionDays: 0`. Everything else lives behind the user-confirmed
+ *     HTTP plan (see `host/api.js`);
  *   - it registers no agent tool: deleting conversations is a user-only
  *     authority and the model must not be able to execute or authorize it.
  *
@@ -32,6 +35,14 @@ export { PLUGIN_VERSION }
 
 export { ROUTE_PREFIX }
 
+/**
+ * Retention cadence. The first sweep waits a minute so a Host start does not
+ * compete with boot; afterwards six hours is frequent enough for a
+ * day-granularity window and cheap enough to ignore.
+ */
+const RETENTION_FIRST_SWEEP_MS = 60_000
+const RETENTION_SWEEP_INTERVAL_MS = 6 * 60 * 60 * 1000
+
 /**
  * Cordis entry point.
  * @param {import('@deepseek-ai/cordis').Context} ctx
@@ -44,7 +55,6 @@ export function apply(ctx, rawConfig) {
   const dshHome = resolveDshHome()
   const paths = resolveDataPaths(dshHome)
   const api = createDeleteApi({ ctx, config, paths })
-
   ctx.effect(() => {
     const dispose = ctx.webServer.register({ kind: 'prefix', path: ROUTE_PREFIX, handler: api.handler })
     console.info(
@@ -60,4 +70,24 @@ export function apply(ctx, rawConfig) {
       }
     }
   })
+
+  // Recycle-bin retention. The sweep is idempotent and takes the same mutation
+  // lock as a user action, so a Host that restarts mid-sweep simply resumes on
+  // the next tick. Both timers are unref'd: a Host that is otherwise done must
+  // still be able to exit.
+  ctx.effect(() => {
+    const sweep = () => {
+      void api.sweepExpiredTrash().catch((error) => {
+        console.warn('[conversation-recycle-bin] retention sweep failed:', error)
+      })
+    }
+    const first = setTimeout(sweep, RETENTION_FIRST_SWEEP_MS)
+    const timer = setInterval(sweep, RETENTION_SWEEP_INTERVAL_MS)
+    first.unref?.()
+    timer.unref?.()
+    return () => {
+      clearTimeout(first)
+      clearInterval(timer)
+    }
+  })
 }

package/lib/version.js

@@ -5,4 +5,4 @@
  * asserted against it by `test/manifest.test.mjs` so the two can never drift
  * (they did: the constant stayed at 0.1.0 while the package reached 0.1.4).
  */
-export const PLUGIN_VERSION = '0.3.9'
+export const PLUGIN_VERSION = '0.3.10'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-conversation-recycle-bin",
-  "version": "0.3.9",
+  "version": "0.3.10",
   "description": "DSH conversation deletion with an optional, previewed cascade into conversation-associated memory: soft delete + recycle bin, audit trail, batch rate limits and per-session rollback. 删除对话（可选一并删除关联记忆）：软删除与回收站、审计留痕、批量限流、失败回滚。",
   "repository": {
     "type": "git",
@@ -57,7 +57,7 @@
     "description": "删除对话并可选择一并删除该对话的关联记忆；支持软删除、回收站、审计、批量限流与失败回滚。"
   },
   "scripts": {
-    "test": "node test/manifest.test.mjs && node test/client-module.test.mjs && node test/core.test.mjs && node test/cascade.test.mjs && node test/memory.test.mjs && node test/trash-audit.test.mjs && node test/feedback.test.mjs && node test/api.test.mjs",
+    "test": "node test/manifest.test.mjs && node test/client-module.test.mjs && node test/core.test.mjs && node test/retention.test.mjs && node test/cascade.test.mjs && node test/memory.test.mjs && node test/trash-audit.test.mjs && node test/feedback.test.mjs && node test/api.test.mjs",
     "check": "node scripts/check-syntax.mjs && node test/manifest.test.mjs"
   },
   "dsh": {