dsh-agent-board 1.7.7 → 1.7.9

package/lib/store.mjs

@@ -9,6 +9,11 @@ import path from 'node:path'
 import fsNode from 'node:fs'
 const { seed, normalizeBoard, vt, boardHome } = core
 
+// 进程内 tmp 序号（配合 pid + 时间戳拼出唯一 tmp 名）：并发 wt() 各自写各自的 tmp，
+// 消灭「两个 chunked 写在同一 p+'.tmp' 上交错 → rename 把拼接怪装上正位」的撕裂根因。
+// 模块级（而非 per-store）是为了同一进程内多个 store 实例（测试/热重载）也不会撞名。
+var tmpSeq = 0
+
 // 腐坏看板自动抢救（P0 根修 task-mv0bl9vg ③）：从撕裂/夹残片的 JSON 原文里截取**第一个完整 JSON 值**。
 // 手法 = JSON.parse 报错 position 截断法（本次事故人工恢复就是这招）：整串 parse 失败时，
 // V8 报错信息含 "position N"（实测 node v24：'{"a":1}{"b":2}' 报 position 18，即第二个值起点），
@@ -108,6 +113,11 @@ export function createStore(ctx, state, deps) {
       }
       return false
     }
+    // 锁感知写回（P1 根修 task-mv1e17x9）：locked=true（调用方已在 mutateLocked 锁内）→ 直接执行；
+    // locked=false（rt 被锁外直读触发，如 poolCycle/rpc/notify）→ 经 withLock 串行。
+    // 为什么不能一律 withLock：rt 在 mutateLocked 锁内被调用时，再套 withLock 会链到当前**未落定**的锁上
+    // （withLock 是简单 promise 链，不可重入）→ 死锁。故用 locked 标志位区分，锁内直跑、锁外补锁。
+    function lockAware(sid, locked, fn) { return locked ? fn() : withLock(sid, fn) }
     // 接管落盘：两条路径，都保证「接管后看板目录里只剩新 sid 那一个文件」（不残留 .adopt-/.tmp 之类残件——
     // 残留一份含全部历史卡的旧板 = 用户磁盘上多一份完整看板，下次继承还会把它算成候选）。
     //   ① 主路径 rename(p → np)：原子、复用 wt() 同款 EPERM/EBUSY 退避重试。注意 rename 只搬内容，
@@ -116,32 +126,37 @@ export function createStore(ctx, state, deps) {
     //      读到 ownerSession 不匹配会退回空板，用户视角仍是「看板被清空」）。
     //   ② 兜底 rename 走不通（跨设备/顽固占用）→ wt() 写新板 + unlinkRetry 删旧板。先写后删：
     //      任何时刻磁盘上至少有一份完整看板。
-    async function adoptBoard(sid, cand, cwd) {
-      var p = boardPath(cand.sid), np = boardPath(sid)
-      // 目标名已被占用 → 绝不接管（防覆盖：本会话看板若只是「这一刻读不到」，覆盖等于把本板换成孤儿板）
-      if (cand.sid === sid || fsNode.existsSync(np)) return false
-      var c = null
-      try { c = JSON.parse(await fsNode.promises.readFile(p, 'utf8')) } catch (e) { console.error('[task-board] 继承失败（读旧板）:', String(e)); return false }
-      if (!vt(c)) return false
-      c.ownerSession = sid
-      if (typeof cwd === 'string' && cwd) c.ownerCwd = cwd
-      if (await renameRetry(p, np)) {                            // ① 主路径：先改名，再把 ownerSession 改写写回
-        try {
-          await wt(sid, c)
-          console.error('[task-board] 继承看板 ' + cand.sid + ' → ' + sid + '（工作区 ' + cwd + '，原主已不在 roots）')
-          return true
-        } catch (e) {
-          console.error('[task-board] 继承失败（改写 ownerSession）:', String(e))
-          await renameRetry(np, p)                               // 回滚到旧名：下次 rt 还能再试，且不留半成品
-          return false
+    // 整段经 lockAware 串行（继承写回归一进锁）：locked=false 时并发继承/写盘不会互相交错。
+    async function adoptBoard(sid, cand, cwd, locked) {
+      return lockAware(sid, locked, async function () {
+        var p = boardPath(cand.sid), np = boardPath(sid)
+        // 目标名已被占用 → 绝不接管（防覆盖：本会话看板若只是「这一刻读不到」，覆盖等于把本板换成孤儿板）
+        if (cand.sid === sid || fsNode.existsSync(np)) return false
+        var c = null
+        try { c = JSON.parse(await fsNode.promises.readFile(p, 'utf8')) } catch (e) { console.error('[task-board] 继承失败（读旧板）:', String(e)); return false }
+        if (!vt(c)) return false
+        c.ownerSession = sid
+        if (typeof cwd === 'string' && cwd) c.ownerCwd = cwd
+        if (await renameRetry(p, np)) {                            // ① 主路径：先改名，再把 ownerSession 改写写回
+          try {
+            await wt(sid, c)
+            console.error('[task-board] 继承看板 ' + cand.sid + ' → ' + sid + '（工作区 ' + cwd + '，原主已不在 roots）')
+            return true
+          } catch (e) {
+            console.error('[task-board] 继承失败（改写 ownerSession）:', String(e))
+            await renameRetry(np, p)                               // 回滚到旧名：下次 rt 还能再试，且不留半成品
+            return false
+          }
         }
-      }
-      try { await wt(sid, c) } catch (e) { console.error('[task-board] 继承失败（写新板）:', String(e)); return false }
-      await unlinkRetry(p)
-      console.error('[task-board] 继承看板 ' + cand.sid + ' → ' + sid + '（工作区 ' + cwd + '，原主已不在 roots；rename 不通，走写新+删旧）')
-      return true
+        try { await wt(sid, c) } catch (e) { console.error('[task-board] 继承失败（写新板）:', String(e)); return false }
+        await unlinkRetry(p)
+        console.error('[task-board] 继承看板 ' + cand.sid + ' → ' + sid + '（工作区 ' + cwd + '，原主已不在 roots；rename 不通，走写新+删旧）')
+        return true
+      })
     }
-    async function rt(sid) {
+    // locked（内部参数）：true=调用方已在 mutateLocked 锁内（继承/抢救写回不得再套 withLock，防死锁）；
+    // 缺省 false=锁外直读（写回经 lockAware 补锁串行）。对外只暴露 rt(sid)，锁内调用由 mutateLocked 传 true。
+    async function rt(sid, locked) {
       var r = null
       try { r = await fsNode.promises.readFile(boardPath(sid), 'utf8') } catch (e) {
         // 只有「文件确实不存在（ENOENT）」才触发继承：EACCES/EPERM/被占 等说明本会话看板很可能存在、
@@ -151,7 +166,7 @@ export function createStore(ctx, state, deps) {
         try {
           var cwd0 = sessionCwd(sid)
           var cand = findAdoptableBoardFile(sid, cwd0)
-          if (cand && await adoptBoard(sid, cand, cwd0)) r = await fsNode.promises.readFile(boardPath(sid), 'utf8')
+          if (cand && await adoptBoard(sid, cand, cwd0, locked)) r = await fsNode.promises.readFile(boardPath(sid), 'utf8')
         } catch (e2) { console.error('[task-board] 继承流程异常（降级为空板）:', String(e2)) }
         if (r === null) return seed(sid, sessionCwd(sid))
       }
@@ -167,45 +182,49 @@ export function createStore(ctx, state, deps) {
         return seed(sid, sessionCwd(sid))
       } catch (_) {
         // JSON 截断/损坏（如强杀打断写盘、中部夹杂另一版本残片）→ 抢救 + 隔离 + 可见化（P0 根修）
-        return recoverCorrupt(sid, r)
+        return recoverCorrupt(sid, r, locked)
       }
     }
     // ===== 腐坏看板：自动 salvage + 隔离可见化（task-mv0bl9vg ②③）=====
     // 三件套：① 隔离前先 trySalvage 截断抢救（成功则以抢救出的完整 JSON 为底继续）；
     // ② 原始坏文件一律 .corrupt-<ts> 留档（抢救成功=复制留档+写回覆盖，抢救失败=改名隔离；撕裂尾部都不丢）；
     // ③ 追加 healthHints err 级 hint（写 poolHealth[sid].corruptNote）+ notify 通知 owner——不再静默。
-    async function recoverCorrupt(sid, raw) {
-      var p = boardPath(sid)
-      var ts = Date.now()
-      var corruptPath = p + '.corrupt-' + ts
-      var salv = trySalvage(raw)
-      var salvaged = null, kept = 0
-      if (salv.ok && vt(salv.board)) {
-        salvaged = normalizeBoard(salv.board)
-        salvaged.ownerSession = sid                              // 抢救出的板归属本 sid（与 adoptBoard 同口径）
-        var cw = sessionCwd(sid)
-        if (!salvaged.ownerCwd && cw) salvaged.ownerCwd = cw
-        kept = (salvaged.tasks || []).length
-      }
-      if (salvaged) {
-        // 抢救成功：原始坏内容**复制**留档 .corrupt-<ts>（不动主板，撕裂尾部不丢），
-        // 再以截断后的完整 JSON 为底原子写回主板继续用；写回失败则下次读盘再抢救（幂等，不留空板空档）。
-        try { await fsNode.promises.copyFile(p, corruptPath) } catch (e) { console.error('[task-board] 腐坏看板复制留档失败:', String(e)) }
-        try {
-          await wt(sid, salvaged)
-          teamModeCache[sid] = !!salvaged.teamMode
-          feedbackCache[sid] = salvaged.feedbackEnabled !== false
-          epicSplitCache[sid] = salvaged.epicSplit !== false
-        } catch (e) { console.error('[task-board] 抢救写回失败（原始文件已留档 ' + corruptPath + '）:', String(e)) }
-        recordCorruptNote(sid, { at: ts, salvage: true, kept: kept, file: path.basename(corruptPath) })
-        console.error('[task-board] board file corrupt, salvaged (kept ' + kept + ' tasks), original quarantined: ' + corruptPath)
-        return salvaged
-      }
-      // 抢救失败：坏文件改名 .corrupt-<ts> 隔离（防反复 poison）+ 空板重启（禁止回写）+ 可见 hint + notify
-      try { await fsNode.promises.rename(p, corruptPath) } catch (e) { console.error('[task-board] 腐坏看板隔离改名失败（下次读盘重试）:', String(e)) }
-      recordCorruptNote(sid, { at: ts, salvage: false, kept: 0, file: path.basename(corruptPath) })
-      console.error('[task-board] board file corrupt, quarantined: ' + corruptPath)
-      return seedNoPersist(sid)
+    // locked 语义同 adoptBoard：锁外直读触发 → 经 withLock 串行（双生 .corrupt 对已实证读路径并发触发写真实存在）；
+    // mutateLocked 锁内触发 → 直跑。整段（含 copyFile 留档 + wt 写回 / rename 隔离）归一进锁，写回不再 bypass withLock。
+    async function recoverCorrupt(sid, raw, locked) {
+      return lockAware(sid, locked, async function () {
+        var p = boardPath(sid)
+        var ts = Date.now()
+        var corruptPath = p + '.corrupt-' + ts
+        var salv = trySalvage(raw)
+        var salvaged = null, kept = 0
+        if (salv.ok && vt(salv.board)) {
+          salvaged = normalizeBoard(salv.board)
+          salvaged.ownerSession = sid                              // 抢救出的板归属本 sid（与 adoptBoard 同口径）
+          var cw = sessionCwd(sid)
+          if (!salvaged.ownerCwd && cw) salvaged.ownerCwd = cw
+          kept = (salvaged.tasks || []).length
+        }
+        if (salvaged) {
+          // 抢救成功：原始坏内容**复制**留档 .corrupt-<ts>（不动主板，撕裂尾部不丢），
+          // 再以截断后的完整 JSON 为底原子写回主板继续用；写回失败则下次读盘再抢救（幂等，不留空板空档）。
+          try { await fsNode.promises.copyFile(p, corruptPath) } catch (e) { console.error('[task-board] 腐坏看板复制留档失败:', String(e)) }
+          try {
+            await wt(sid, salvaged)
+            teamModeCache[sid] = !!salvaged.teamMode
+            feedbackCache[sid] = salvaged.feedbackEnabled !== false
+            epicSplitCache[sid] = salvaged.epicSplit !== false
+          } catch (e) { console.error('[task-board] 抢救写回失败（原始文件已留档 ' + corruptPath + '）:', String(e)) }
+          recordCorruptNote(sid, { at: ts, salvage: true, kept: kept, file: path.basename(corruptPath) })
+          console.error('[task-board] board file corrupt, salvaged (kept ' + kept + ' tasks), original quarantined: ' + corruptPath)
+          return salvaged
+        }
+        // 抢救失败：坏文件改名 .corrupt-<ts> 隔离（防反复 poison）+ 空板重启（禁止回写）+ 可见 hint + notify
+        try { await fsNode.promises.rename(p, corruptPath) } catch (e) { console.error('[task-board] 腐坏看板隔离改名失败（下次读盘重试）:', String(e)) }
+        recordCorruptNote(sid, { at: ts, salvage: false, kept: 0, file: path.basename(corruptPath) })
+        console.error('[task-board] board file corrupt, quarantined: ' + corruptPath)
+        return seedNoPersist(sid)
+      })
     }
     // 腐坏/抢救 hint 落 poolHealth（get-tasks 现算透出 err 级 hint）+ notify 通知 owner
     function recordCorruptNote(sid, note) {
@@ -237,7 +256,11 @@ export function createStore(ctx, state, deps) {
       finally { await fh.close().catch(function () {}) }
     }
     async function wt(sid, d) {
-      var c = JSON.stringify(d); var p = boardPath(sid); var tmp = p + '.tmp'
+      var c = JSON.stringify(d); var p = boardPath(sid)
+      // tmp 唯一名（P1 根修 task-mv1e17x9）：pid + 时间戳 + 进程内自增序号——并发 wt() 各自写各自的 tmp，
+      // rename 装上的永远是**某一份**完整 JSON（旧实现共享 p+'.tmp'：两个并发 chunked 写在同一 tmp 交错，
+      // rename 把拼接怪原子装上正位——原子 rename 防写一半，防不住 tmp 本身是拼的）。
+      var tmp = p + '.' + process.pid + '.' + Date.now() + '-' + (++tmpSeq) + '.tmp'
       for (var attempt = 0; attempt < 6; attempt++) {
         try { await writeTmpFsync(tmp, c); await fsNode.promises.rename(tmp, p); return }
         catch (e) {
@@ -246,14 +269,15 @@ export function createStore(ctx, state, deps) {
             await new Promise(function (r) { setTimeout(r, 60 * (attempt + 1)) })
             continue
           }
+          await unlinkRetry(tmp, 2)                                 // 非瞬时错误：清掉自己的 tmp 残件再抛（不堆积）
           console.error('[task-board] write:', String(e)); throw e
         }
       }
       // 退避重试耗尽（顽固瞬时占用）→ 降级「先 unlink 目标再 rename」并记录；最后一步失败则抛（不吞）
       console.error('[task-board] write: rename 直覆失败（重试耗尽），降级 unlink+rename: ' + p)
-      try { await writeTmpFsync(tmp, c) } catch (e) { console.error('[task-board] write:', String(e)); throw e }
+      try { await writeTmpFsync(tmp, c) } catch (e) { await unlinkRetry(tmp, 2); console.error('[task-board] write:', String(e)); throw e }
       await unlinkRetry(p, 6)
-      await fsNode.promises.rename(tmp, p)
+      try { await fsNode.promises.rename(tmp, p) } catch (e) { await unlinkRetry(tmp, 2); console.error('[task-board] write:', String(e)); throw e }
     }
     // 每会话一条 promise 链，串行化所有 读-改-写，消除并发写竞争
     function withLock(sid, fn) { var prev = fileLocks[sid] || Promise.resolve(); var p = prev.then(function () { return fn() }); fileLocks[sid] = p.catch(function () {}); return p }
@@ -285,7 +309,7 @@ export function createStore(ctx, state, deps) {
       }
       if (tm) tm.timeout(50).then(go, go); else Promise.resolve().then(go)
     }
-    function mutateLocked(sid, mutate, skipKick) { return withLock(sid, async function () { var d = await rt(sid); if (d && d.__noPersist) { console.error('[task-board] 看板暂时不可读，拒绝在空板上覆写（防瞬时读失败清板）: ' + sid); return { ok: false, error: '看板暂时不可读，请重试' } } var r = await mutate(d); if (r !== null && r !== undefined) { await wt(sid, d); if (!skipKick) kickCycle(sid); return r } return r }) }
+    function mutateLocked(sid, mutate, skipKick) { return withLock(sid, async function () { var d = await rt(sid, true); if (d && d.__noPersist) { console.error('[task-board] 看板暂时不可读，拒绝在空板上覆写（防瞬时读失败清板）: ' + sid); return { ok: false, error: '看板暂时不可读，请重试' } } var r = await mutate(d); if (r !== null && r !== undefined) { await wt(sid, d); if (!skipKick) kickCycle(sid); return r } return r }) }
 
     return { rt: rt, wt: wt, kickCycle: kickCycle, mutateLocked: mutateLocked }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-agent-board",
   "description": "DeepSeek Harness 智能看板：任务卡片 + 一次性 Worker/Verifier 派发 + 依赖调度 + 管线分档 + Team 模式（歧义上报主窗口裁决）",
-  "version": "1.7.7",
+  "version": "1.7.9",
   "type": "module",
   "main": "./index.mjs",
   "scripts": {

package/test/cleanup.test.mjs

@@ -0,0 +1,341 @@
+// dsh-agent-board — 已结算会话清理套件（task-mv2131cz → 卡龄主闸重构 task-mv22cd5m）：
+//   ① 可删判定：卡龄主闸（archived + 满保留天数）+ 三底闸（落定 / 不活跃 / 路径安全）
+//   ② preview 不动盘（dry-run 零副作用）
+//   ③ run 真删会话目录 + projcache json（临时 HOME 构造，与真实布局一致）
+//   ④ 路径逃逸防护（id 含 ../ 之类拒 + rm 前 isWithin 再验）
+//   ⑤ cleanupRetentionDays 设置项读写（缺省 7 / 钳 1-90 / get-tasks 透出 / 客户端文案）
+//   ⑥ 体积估算双轨（task-mv39ag1e）：stat().sizeBytes 快照主源优先（不走目录遍历）+ stat 缺失/异常回退目录遍历
+// 纯函数断言直接 import lib/cleanup.mjs；RPC 端到端跑真实 index.mjs apply(mockCtx)。
+// 口径重构（task-mv22cd5m，2026-10-10 用户指令「回收与归档状态一致，归档后 X 天可完全回收」）：
+//   旧四闸（落定+已记账+非 continuable+不活跃）→ 卡龄主闸（卡归档满 X 天）+ 三底闸（落定/不活跃/路径安全）。
+//   continuable/usageRecorded 两闸撤除：归档满 X 天 = 账本封存 + 续跑意愿过期，恢复待办回落新 spawn（零新逻辑）。
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { createMockCtx } from './helpers/mock-ctx.mjs'
+import * as plugin from '../index.mjs'
+import { isSafeSessionId, classifyRun, scanDeletable, previewCleanup, runCleanup, isWithin, buildSessionDirIndex } from '../lib/cleanup.mjs'
+
+// ===== ① 会话 id 白名单（路径逃逸第一道闸）=====
+test('isSafeSessionId：合法 id 放行、路径字符/空值拒', function () {
+  assert.equal(isSafeSessionId('5c912460-ddd0-45f2-8298-717b2cfd6a25'), true, '裸 UUID 放行')
+  assert.equal(isSafeSessionId('session-55b0879a-b266-434e-98e2-5d2ba6ee85f6'), true, 'session-<uuid> 放行')
+  assert.equal(isSafeSessionId('import-sess_df0837fa-9e89-465b-9962-dd61e481c87e'), true, 'import-sess_ 放行')
+  assert.equal(isSafeSessionId('child-abc123'), true, 'child- 放行')
+  assert.equal(isSafeSessionId('../evil'), false, '父路径段拒')
+  assert.equal(isSafeSessionId('a/b'), false, '正斜杠拒')
+  assert.equal(isSafeSessionId('a\\b'), false, '反斜杠拒')
+  assert.equal(isSafeSessionId('.'), false, '单点拒')
+  assert.equal(isSafeSessionId('..'), false, '双点拒')
+  assert.equal(isSafeSessionId(''), false, '空串拒')
+  assert.equal(isSafeSessionId('  padded  '), false, '首尾空白拒')
+  assert.equal(isSafeSessionId('a.b'), false, '含点拒（会话 id 不应含点）')
+})
+
+// ===== ② 可删判定：卡龄主闸 + 三底闸 =====
+test('classifyRun：卡龄主闸（非归档拒/未满天数拒/满天数放）+ 三底闸（落定/不活跃/路径安全）', function () {
+  var none = new Set()
+  var now = Date.now()
+  var DAY = 86400000
+  function aged(days) { return new Date(now - days * DAY).toISOString() }
+  var oldCard = { id: 'c1', status: 'archived', archivedAt: aged(8) }
+  var youngCard = { id: 'c2', status: 'archived', archivedAt: aged(3) }
+  var liveCard = { id: 'c3', status: 'resolved', archivedAt: aged(8) }
+  var opts = { now: now }
+  // 卡龄主闸：非 archived 拒 / 缺卡拒
+  assert.equal(classifyRun({ id: 'a', outcome: 'completed' }, liveCard, none, opts).reason, 'not-archived', '主闸：非 archived 卡拒（resolved 不放行）')
+  assert.equal(classifyRun({ id: 'a', outcome: 'completed' }, null, none, opts).reason, 'not-archived', '主闸：缺卡拒')
+  // 卡龄主闸：归档未满 7 天拒 / archivedAt 缺失拒 / 满 7 天放 / 恰好 7 天放（闭区间）
+  assert.equal(classifyRun({ id: 'a', outcome: 'completed' }, youngCard, none, opts).reason, 'too-young', '主闸：归档 3 天（<7）拒')
+  assert.equal(classifyRun({ id: 'a', outcome: 'completed' }, { id: 'c4', status: 'archived', archivedAt: '' }, none, opts).reason, 'too-young', '主闸：archivedAt 缺失拒（宁漏勿错删）')
+  assert.equal(classifyRun({ id: 'a', outcome: 'completed' }, { id: 'c5', status: 'archived', archivedAt: 'not-a-date' }, none, opts).reason, 'too-young', '主闸：archivedAt 非法拒')
+  assert.equal(classifyRun({ id: 'a', outcome: 'completed' }, oldCard, none, opts).deletable, true, '主闸：归档 8 天（≥7）放')
+  assert.equal(classifyRun({ id: 'a', outcome: 'completed' }, { id: 'c6', status: 'archived', archivedAt: aged(7) }, none, opts).deletable, true, '主闸：恰好 7 天放（≥ 闭区间）')
+  // continuable 死会话归档超期后可删（旧 continuable 闸已撤——Verifier 钓出的 151 个死持久会话回归）
+  assert.equal(classifyRun({ id: 'a', outcome: 'timeout/error', continuable: true, noResume: true }, oldCard, none, opts).deletable, true, 'continuable 死会话归档超期可删')
+  assert.equal(classifyRun({ id: 'a', outcome: 'completed', usageRecorded: false }, oldCard, none, opts).deletable, true, 'usageRecorded 闸已撤：未记账也放')
+  // 三底闸不回归：outcome 未落定 / 活跃血统 / 路径逃逸
+  assert.equal(classifyRun({ id: 'a', outcome: 'running' }, oldCard, none, opts).reason, 'not-settled', '底闸：running 拒')
+  assert.equal(classifyRun({ id: 'a' }, oldCard, none, opts).reason, 'not-settled', '底闸：缺 outcome 拒')
+  assert.equal(classifyRun({ id: 'a', outcome: 'completed' }, oldCard, new Set(['a']), opts).reason, 'active', '底闸：活跃/血统拒')
+  assert.equal(classifyRun({ id: '../x', outcome: 'completed' }, oldCard, none, opts).reason, 'id-invalid', '底闸：路径逃逸优先拒')
+})
+
+// ===== ③ scanDeletable：同 id 任一条不可删则整组不可删 =====
+test('scanDeletable：按 id 聚合、任一条不可删整组拒（卡龄口径）', function () {
+  var now = Date.now()
+  var DAY = 86400000
+  function aged(days) { return new Date(now - days * DAY).toISOString() }
+  var tasks = [
+    { id: 't1', title: 't1', status: 'archived', archivedAt: aged(8), runs: [{ id: 'ok', role: 'worker', outcome: 'completed' }, { id: 'dup', role: 'worker', outcome: 'completed' }] },
+    { id: 't2', title: 't2', status: 'resolved', archivedAt: aged(8), runs: [{ id: 'dup', role: 'worker', outcome: 'completed' }] }
+  ]
+  var r = scanDeletable(tasks, new Set(), { now: now })
+  assert.deepEqual(r.items.map(function (x) { return x.id }), ['ok'], '只 ok 可删')
+  assert.equal(r.skipped.length, 1)
+  assert.equal(r.skipped[0].id, 'dup')
+  assert.equal(r.skipped[0].reason, 'not-archived', 'dup 任一条所属卡非 archived 即整组拒')
+})
+
+// ===== ④ preview 无副作用 + run 真删（临时 HOME 构造）=====
+test('previewCleanup 只读不删、runCleanup 真删目录+projcache', async function () {
+  var tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'dsh-cleanup-'))
+  try {
+    var sessionsRoot = path.join(tmp, 'sessions')
+    var bucket = path.join(sessionsRoot, 'b1')
+    var sessionDir = path.join(bucket, 'child-ok')
+    fs.mkdirSync(sessionDir, { recursive: true })
+    fs.writeFileSync(path.join(sessionDir, 'session.v4.jsonl.zstd'), 'x'.repeat(1000))
+    var projcacheDir = path.join(tmp, 'projcache')
+    fs.mkdirSync(projcacheDir, { recursive: true })
+    var pcPath = path.join(projcacheDir, 'child-ok.json')
+    fs.writeFileSync(pcPath, 'y'.repeat(500))
+    var roots = { sessions: sessionsRoot, projcacheDir: projcacheDir }
+    var agedAt = new Date(Date.now() - 8 * 86400000).toISOString()
+    var tasks = [{ id: 't1', title: 't1', status: 'archived', archivedAt: agedAt, runs: [{ id: 'child-ok', role: 'worker', outcome: 'completed' }] }]
+    // preview：dry-run，估体积 + 不动盘
+    var pv = await previewCleanup(tasks, { blockedIds: new Set(), roots: roots })
+    assert.equal(pv.total, 1)
+    assert.ok(pv.totalBytes >= 1500, '体积估算含目录+projcache')
+    assert.ok(fs.existsSync(sessionDir), 'preview 后会话目录仍在（零副作用）')
+    assert.ok(fs.existsSync(pcPath), 'preview 后 projcache 仍在（零副作用）')
+    // run：真删
+    var rep = await runCleanup(pv.items, { roots: roots })
+    assert.equal(rep.deleted, 1)
+    assert.ok(!fs.existsSync(sessionDir), 'run 后会话目录已删')
+    assert.ok(!fs.existsSync(pcPath), 'run 后 projcache 已删')
+    assert.equal(rep.freedBytes, pv.totalBytes, '释放字节与预览一致')
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true })
+  }
+})
+
+// ===== ④b 体积估算主源（task-mv39ag1e）：snapshot sizeBytes 优先，不走目录遍历 =====
+test('previewCleanup：stat 返回 sizeBytes 时体积取自快照（不走目录遍历）', async function () {
+  var tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'dsh-cleanup-snap-'))
+  try {
+    var sessionsRoot = path.join(tmp, 'sessions')
+    var sessionDir = path.join(sessionsRoot, 'b1', 'child-snap')
+    fs.mkdirSync(sessionDir, { recursive: true })
+    fs.writeFileSync(path.join(sessionDir, 'session.v4.jsonl.zstd'), 'x'.repeat(1000)) // 盘上真实 1000 字节
+    var projcacheDir = path.join(tmp, 'projcache')
+    fs.mkdirSync(projcacheDir, { recursive: true })
+    fs.writeFileSync(path.join(projcacheDir, 'child-snap.json'), 'y'.repeat(500))
+    var roots = { sessions: sessionsRoot, projcacheDir: projcacheDir }
+    var agedAt = new Date(Date.now() - 8 * 86400000).toISOString()
+    var tasks = [{ id: 't1', title: 't1', status: 'archived', archivedAt: agedAt, runs: [{ id: 'child-snap', role: 'worker', outcome: 'completed' }] }]
+    // mock 官方快照面：sizeBytes=77777（与盘上 1000 不同——体积等于 77777+500 即证未走目录遍历）
+    var statCalls = []
+    var statSession = async function (id) { statCalls.push(id); return { header: { id: id }, revision: 'r1', sizeBytes: 77777 } }
+    var pv = await previewCleanup(tasks, { blockedIds: new Set(), roots: roots, statSession: statSession })
+    assert.equal(pv.total, 1)
+    assert.equal(pv.items[0].bytes, 77777 + 500, '体积=快照 sizeBytes + projcache（目录遍历口径应为 1000+500）')
+    assert.equal(pv.totalBytes, 77777 + 500)
+    assert.deepEqual(statCalls, ['child-snap'], 'stat 只查可删项（跳过项不查）')
+    assert.ok(fs.existsSync(sessionDir), 'preview 后会话目录仍在（零副作用）')
+    // run 同走快照主源：释放字节 = 快照口径
+    var rep = await runCleanup(pv.items, { roots: roots, statSession: statSession })
+    assert.equal(rep.deleted, 1)
+    assert.equal(rep.freedBytes, 77777 + 500, 'run 释放字节与快照预览一致')
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true })
+  }
+})
+
+// ===== ④c 体积估算回退（task-mv39ag1e）：stat 缺失/异常/无 sizeBytes → 目录遍历兜底 =====
+test('previewCleanup：stat 回退路径（undefined/异常/无 sizeBytes）一律目录遍历兜底', async function () {
+  var tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'dsh-cleanup-fb-'))
+  try {
+    var sessionsRoot = path.join(tmp, 'sessions')
+    var sessionDir = path.join(sessionsRoot, 'b1', 'child-fb')
+    fs.mkdirSync(sessionDir, { recursive: true })
+    fs.writeFileSync(path.join(sessionDir, 'session.v4.jsonl.zstd'), 'x'.repeat(1000))
+    var projcacheDir = path.join(tmp, 'projcache')
+    fs.mkdirSync(projcacheDir, { recursive: true })
+    fs.writeFileSync(path.join(projcacheDir, 'child-fb.json'), 'y'.repeat(500))
+    var roots = { sessions: sessionsRoot, projcacheDir: projcacheDir }
+    var agedAt = new Date(Date.now() - 8 * 86400000).toISOString()
+    var tasks = [{ id: 't1', title: 't1', status: 'archived', archivedAt: agedAt, runs: [{ id: 'child-fb', role: 'worker', outcome: 'completed' }] }]
+    // A：stat 返回 undefined（会话不在持久层）→ 目录遍历
+    var pvA = await previewCleanup(tasks, { blockedIds: new Set(), roots: roots, statSession: async function () { return undefined } })
+    assert.equal(pvA.items[0].bytes, 1500, 'stat undefined → 目录遍历兜底（1000+500）')
+    // B：stat 抛异常 → 目录遍历
+    var pvB = await previewCleanup(tasks, { blockedIds: new Set(), roots: roots, statSession: async function () { throw new Error('backend down') } })
+    assert.equal(pvB.items[0].bytes, 1500, 'stat 异常 → 目录遍历兜底')
+    // C：snapshot 无 sizeBytes（未物化会话/非 JSONL 后端缺省字段）→ 目录遍历
+    var pvC = await previewCleanup(tasks, { blockedIds: new Set(), roots: roots, statSession: async function (id) { return { header: { id: id }, revision: 'r1' } } })
+    assert.equal(pvC.items[0].bytes, 1500, 'sizeBytes 缺省 → 目录遍历兜底')
+    // D：非法 sizeBytes（负值/NaN 脏值）→ 目录遍历
+    var pvD = await previewCleanup(tasks, { blockedIds: new Set(), roots: roots, statSession: async function (id) { return { header: { id: id }, sizeBytes: -3 } } })
+    assert.equal(pvD.items[0].bytes, 1500, 'sizeBytes 脏值 → 目录遍历兜底')
+    assert.ok(fs.existsSync(sessionDir), '回退路径 preview 同样零副作用')
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true })
+  }
+})
+
+// ===== ⑤ 路径逃逸防护：rm 前 isWithin 再验 + id 白名单 =====
+test('路径逃逸：isWithin 拒绝桶外路径、runCleanup 拒删逃逸目标', async function () {
+  var tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'dsh-cleanup-esc-'))
+  try {
+    var sessionsRoot = path.join(tmp, 'sessions')
+    var projcacheDir = path.join(tmp, 'projcache')
+    fs.mkdirSync(sessionsRoot, { recursive: true })
+    fs.mkdirSync(projcacheDir, { recursive: true })
+    // isWithin 纯函数：根内放行、根外/根本身拒绝
+    assert.equal(isWithin(sessionsRoot, path.join(sessionsRoot, 'b1', 'x')), true, '桶内放行')
+    assert.equal(isWithin(sessionsRoot, path.join(tmp, 'outside')), false, '桶外拒绝')
+    assert.equal(isWithin(sessionsRoot, sessionsRoot), false, '根本身拒绝')
+    // runCleanup：sessionDir 指向桶外 → 跳过并拒绝删除
+    var outside = path.join(tmp, 'outside-dir')
+    fs.mkdirSync(outside, { recursive: true })
+    fs.writeFileSync(path.join(outside, 'keep.txt'), 'do-not-delete')
+    var rep = await runCleanup([{ id: 'evil', sessionDir: outside, projcachePath: null }], { roots: { sessions: sessionsRoot, projcacheDir: projcacheDir } })
+    assert.equal(rep.deleted, 0)
+    assert.equal(rep.skipped.length, 1)
+    assert.equal(rep.skipped[0].reason, 'path-escape')
+    assert.ok(fs.existsSync(path.join(outside, 'keep.txt')), '桶外目录未被删')
+    // 含 ../ 的 id 在 runCleanup 层也被 id-invalid 拦下（即使给了合法 sessionDir）
+    var rep2 = await runCleanup([{ id: '../evil', sessionDir: path.join(sessionsRoot, 'b1', 'x'), projcachePath: null }], { roots: { sessions: sessionsRoot, projcacheDir: projcacheDir } })
+    assert.equal(rep2.deleted, 0)
+    assert.equal(rep2.skipped[0].reason, 'id-invalid')
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true })
+  }
+})
+
+// ===== ⑥ RPC 端到端：cleanup-preview / cleanup-run（真实 apply + 临时 HOME，卡龄主闸口径）=====
+test('RPC cleanup-preview/run 端到端 + 留痕 + 活跃/逃逸跳过', async function () {
+  var env = createMockCtx()
+  plugin.apply(env.ctx)
+  try {
+    // 可删会话：on-disk 会话目录 + projcache
+    var sessionDir = path.join(env.home, '.dsh', 'sessions', 'b1', 'child-abc')
+    fs.mkdirSync(sessionDir, { recursive: true })
+    fs.writeFileSync(path.join(sessionDir, 'session.v4.jsonl.zstd'), 'z'.repeat(2000))
+    var projDir = path.join(env.home, '.dsh', 'storages', 'session_projcache', 'sessions')
+    fs.mkdirSync(projDir, { recursive: true })
+    var pcPath = path.join(projDir, 'child-abc.json')
+    fs.writeFileSync(pcPath, 'w'.repeat(600))
+    // 先建一张卡落出看板文件（patchBoard 需文件已存在），再整体覆盖 runs 场景
+    await env.rpc('create-task', { sessionId: env.sid, id: 'seed', title: 'seed', description: 'x' })
+    var agedAt = new Date(Date.now() - 8 * 86400000).toISOString()
+    env.patchBoard(function (d) {
+      d.tasks = [
+        { id: 't1', title: 't1', status: 'archived', archivedAt: agedAt, runs: [{ id: 'child-abc', role: 'worker', outcome: 'completed' }] },
+        { id: 't2', title: 't2', status: 'archived', archivedAt: agedAt, runs: [{ id: 'child-active', role: 'worker', outcome: 'completed' }] },
+        { id: 't3', title: 't3', status: 'archived', archivedAt: agedAt, runs: [{ id: '../escape', role: 'worker', outcome: 'completed' }] }
+      ]
+    })
+    // 活跃会话：child-active 塞进活跃树（agents.list 会返回它）→ 应被「不活跃」底闸跳过
+    env.setRoots([env.root, { id: 'child-active' }])
+    var pv = await env.rpc('cleanup-preview', { sessionId: env.sid })
+    assert.equal(pv.ok, true)
+    assert.equal(pv.total, 1, '只 child-abc 可删（卡龄主闸 + 三底闸全过）')
+    assert.ok(pv.totalBytes >= 2600)
+    var skipIds = (pv.skipped || []).map(function (s) { return s.id })
+    assert.ok(skipIds.indexOf('child-active') >= 0, '活跃会话进跳过清单')
+    assert.ok(skipIds.indexOf('../escape') >= 0, '路径逃逸 id 进跳过清单')
+    assert.ok(fs.existsSync(sessionDir), 'preview 后会话目录仍在（零副作用）')
+    assert.ok(fs.existsSync(pcPath), 'preview 后 projcache 仍在（零副作用）')
+    // run：confirm:false 拒、confirm:true 真删
+    var noConfirm = await env.rpc('cleanup-run', { sessionId: env.sid })
+    assert.equal(noConfirm.ok, false, '无 confirm 拒绝')
+    var rep = await env.rpc('cleanup-run', { sessionId: env.sid, confirm: true })
+    assert.equal(rep.ok, true)
+    assert.equal(rep.deleted, 1)
+    assert.ok(!fs.existsSync(sessionDir), 'run 后会话目录已删')
+    assert.ok(!fs.existsSync(pcPath), 'run 后 projcache 已删')
+    var board = env.board()
+    assert.ok(Array.isArray(board.cleanupLog) && board.cleanupLog.length === 1, 'cleanupLog 留痕')
+    assert.equal(board.cleanupLog[0].deleted, 1)
+  } finally {
+    await env.cleanup()
+  }
+})
+
+// ===== ⑥b RPC 端到端（task-mv39ag1e）：snapshot sizeBytes 主源经真实接线生效 =====
+test('RPC cleanup-preview/run：sessionPersistence.stat sizeBytes 主源经真实接线生效', async function () {
+  var env = createMockCtx()
+  plugin.apply(env.ctx)
+  try {
+    // 盘上真实会话目录 2000 字节 + projcache 600
+    var sessionDir = path.join(env.home, '.dsh', 'sessions', 'b1', 'child-snap')
+    fs.mkdirSync(sessionDir, { recursive: true })
+    fs.writeFileSync(path.join(sessionDir, 'session.v4.jsonl.zstd'), 'z'.repeat(2000))
+    var projDir = path.join(env.home, '.dsh', 'storages', 'session_projcache', 'sessions')
+    fs.mkdirSync(projDir, { recursive: true })
+    fs.writeFileSync(path.join(projDir, 'child-snap.json'), 'w'.repeat(600))
+    await env.rpc('create-task', { sessionId: env.sid, id: 'seed', title: 'seed', description: 'x' })
+    var agedAt = new Date(Date.now() - 8 * 86400000).toISOString()
+    env.patchBoard(function (d) {
+      d.tasks = [{ id: 't1', title: 't1', status: 'archived', archivedAt: agedAt, runs: [{ id: 'child-snap', role: 'worker', outcome: 'completed' }] }]
+    })
+    // 官方快照面登记：header 入持久表 + sizeBytes=88888（≠盘上 2000——体积取自快照即证主源生效）
+    env.persistedHeaders['child-snap'] = { id: 'child-snap', parentSession: undefined }
+    env.persistedSizes['child-snap'] = 88888
+    var pv = await env.rpc('cleanup-preview', { sessionId: env.sid })
+    assert.equal(pv.ok, true)
+    assert.equal(pv.total, 1)
+    assert.equal(pv.totalBytes, 88888 + 600, 'preview 体积=快照 sizeBytes+projcache（目录遍历口径为 2600，不等即证主源）')
+    assert.ok(fs.existsSync(sessionDir), 'preview 零副作用不动盘')
+    var rep = await env.rpc('cleanup-run', { sessionId: env.sid, confirm: true })
+    assert.equal(rep.ok, true)
+    assert.equal(rep.deleted, 1)
+    assert.equal(rep.freedBytes, 88888 + 600, 'run 释放字节同走快照主源')
+    assert.ok(!fs.existsSync(sessionDir), 'run 后目录真删')
+    var board = env.board()
+    assert.ok(Array.isArray(board.cleanupLog) && board.cleanupLog.length === 1, 'cleanupLog 留痕')
+  } finally {
+    await env.cleanup()
+  }
+})
+
+// ===== ⑦ buildSessionDirIndex：一次性索引可定位目录（preview 用）=====
+test('buildSessionDirIndex：id → 目录路径 索引', function () {
+  var tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'dsh-cleanup-idx-'))
+  try {
+    var sessionsRoot = path.join(tmp, 'sessions')
+    var b1 = path.join(sessionsRoot, 'b1')
+    var b2 = path.join(sessionsRoot, 'b2')
+    fs.mkdirSync(path.join(b1, 'aaa'), { recursive: true })
+    fs.mkdirSync(path.join(b2, 'bbb'), { recursive: true })
+    fs.writeFileSync(path.join(b1, 'aaa', 'session.jsonl.zstd'), 'x') // 目录里放个文件确保是目录
+    fs.writeFileSync(path.join(b2, 'bbb', 'session.jsonl.zstd'), 'y')
+    var idx = buildSessionDirIndex(sessionsRoot)
+    assert.equal(idx['aaa'], path.join(b1, 'aaa'))
+    assert.equal(idx['bbb'], path.join(b2, 'bbb'))
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true })
+  }
+})
+
+// ===== ⑧ cleanupRetentionDays：设置项读写（缺省/钳制/get-tasks 透出）+ 客户端文案 =====
+test('cleanupRetentionDays：设置项读写 + 缺省/钳制 + 客户端文案', async function () {
+  var env = createMockCtx()
+  plugin.apply(env.ctx)
+  try {
+    await env.rpc('create-task', { sessionId: env.sid, id: 'seed', title: 'seed', description: 'x' })
+    // 缺省 7
+    var g0 = await env.rpc('get-tasks', { sessionId: env.sid })
+    assert.equal(g0.cleanupRetentionDays, 7, '缺省 7（get-tasks 透出）')
+    // 写入 3 → 透出 3
+    await env.rpc('set-board-config', { sessionId: env.sid, key: 'cleanupRetentionDays', value: 3 })
+    var g1 = await env.rpc('get-tasks', { sessionId: env.sid })
+    assert.equal(g1.cleanupRetentionDays, 3, '写入 3 透出 3')
+    // 钳制：999 → 90（上限）；0 → 7（脏值回默认）
+    await env.rpc('set-board-config', { sessionId: env.sid, key: 'cleanupRetentionDays', value: 999 })
+    assert.equal((await env.rpc('get-tasks', { sessionId: env.sid })).cleanupRetentionDays, 90, '上限钳 90')
+    await env.rpc('set-board-config', { sessionId: env.sid, key: 'cleanupRetentionDays', value: 0 })
+    assert.equal((await env.rpc('get-tasks', { sessionId: env.sid })).cleanupRetentionDays, 7, '0 回默认 7')
+    // 客户端文案（产物 lib/client.js）：设置区「存储清理」小节 + 卡龄口径注释 + 动态天数
+    var cli = fs.readFileSync(new URL('../lib/client.js', import.meta.url), 'utf8')
+    assert.match(cli, /'归档保留'/)
+    assert.match(cli, /cleanupRetentionDays/)
+    assert.match(cli, /归档超过 ' \+ \(state\.cleanupRetentionDays \|\| 7\) \+ ' 天/)
+  } finally {
+    await env.cleanup()
+  }
+})