@thincoder/core 0.9.1 → 0.9.2

package/session-stale.mjs

@@ -0,0 +1,247 @@
+/**
+ * session-stale.mjs — sessions 存量治理（SESSION.md §6.17 · STARTUP-LATENCY 批，2026-09-21）。
+ *
+ * 职责 = 分组 / 三合取判据 / 回收（rename 进回收批）/ 清运（超期批）/ 有界逐扫。
+ * 全链异步（D-SE34）：本档零同步扫描——目录与逐文件面一律 `node:fs/promises`
+ * （同步 fs 面只留单条目 `existsSync`——本档不使用；bounded 单文件面归既有档）。
+ *
+ * 可清组 ⟺ 三合取（D-SE35；组 = sessions 根下同一 40 位 cwd 哈希前缀的全文件集合）：
+ *   ③ 安全窗：组内最新 mtime < now − STALE_SAFETY_WINDOW_MS（7 天——异常现场窗口）；
+ *   ① 无活属主：manifest `slotSessions` 全量经入口一次探测束 + `ownerState` 三态——
+ *      活 / 未知（探测失败 / 缺行）⇒ 保留；无 manifest ⇒ 无认领面 ⇒ 该条自动满足；
+ *   ② 内容面不可达或无内容：**T1** = 组内可读数据文件 `cwd` 全部不存在于磁盘（至少读到一份）；
+ *      **T2** = 组内无任何数据文件。数据文件不可读 / 无 `cwd` 字段 ⇒ T1 不成立 ⇒ 保留（fail-safe）。
+ * 求值序 = ③ → ① → ②（任一步不通过 ⇒ 保留并短路）；选取顺序 = 组最新 mtime 升序（最旧优先）。
+ * 预算（D-SE40）= **过 ③ 进 ① 即耗 1**（含 ① 面 manifest 读）——每 pass 总评估 ≤ `STALE_SWEEP_LIMIT`，
+ * 达上限即停、余量下一 pass 继续；③ 短路组零预算（未读盘），① / ② 短路组已耗 1（不退）；
+ * 显式面 limit = Infinity（全量）。
+ * 90 天冷 cwd 判据**不在本档**（cwd 存活组唯一出口——保持显式命令面；实现住 session-gc.mjs）。
+ *
+ * 回收（D-SE36）：判据窗 7 天 + 回收保留 7 天 ⇒ 不可逆删除最早 = 最后写入 + 14 天；
+ * 回收根 = 当次 sessions 根 `dir` 派生的同级 `sessions-trash/<批次时间戳>/`（sessions 根外——
+ * 不参与扫描 / 不入发现面；`dir` 注入缝因此覆盖回收批）；逐文件 rename（同卷元数据操作）——
+ * 单文件失败 / 回收根不可写 = 跳过并计数，**不 unlink 兜底**（零误删；部分移动态安全）。
+ */
+import { readdir, readFile, stat, rename, mkdir, rm } from "node:fs/promises"
+import { join, dirname } from "node:path"
+import { ownerPid } from "./session-slots-manifest.mjs"
+import { probeOwnersAsync, ownerState } from "./process-probe.mjs"
+
+export const STALE_SAFETY_WINDOW_MS = 7 * 24 * 3600 * 1000
+export const STALE_SWEEP_LIMIT = 500
+export const TRASH_RETENTION_MS = 7 * 24 * 3600 * 1000
+export const TRASH_DIR_NAME = "sessions-trash"
+
+/** 测试注入缝（`_traceHooks` 同惯例）：rename / mkdir / rm / stat / readdir 计数与失败注入。
+ *  生产永远走真实实现（本对象只在测试内 `Object.assign` + 还原）。 */
+export const _staleHooks = {
+  readdir: (dir) => readdir(dir),
+  readFile: (p) => readFile(p, "utf8"),
+  stat: (p) => stat(p),
+  rename: (from, to) => rename(from, to),
+  mkdir: (dir) => mkdir(dir, { recursive: true }),
+  rm: (dir) => rm(dir, { recursive: true, force: true }),
+}
+
+const GROUP_RE = /^([0-9a-f]{40})\.json(?:\.|$)/
+const DATA_SUFFIX_RE = /^(?:\.\d+)?$/
+const STAT_CHUNK = 128
+
+/** 回收根（D-SE36）= 当次 sessions 根的同级 `sessions-trash`。 */
+export function trashRootFor(dir) { return join(dirname(dir), TRASH_DIR_NAME) }
+
+/** 分组（纯函数）：entries（名串或 {name, mtimeMs}）→ Map<hash, {hash, prefix, files,
+ *  dataFiles, newestMtimeMs}>。只认 40 位哈希前缀族（非本族名一律不碰）；数据文件 =
+ *  裸 `{hash}.json` 与 `{hash}.json.N`（记录存储 sidecar `.N.d` 与残留随组处理，不计入）。 */
+export function groupSessionEntries(entries) {
+  const groups = new Map()
+  for (const e of entries) {
+    const name = typeof e === "string" ? e : e?.name
+    if (typeof name !== "string") continue
+    const m = GROUP_RE.exec(name)
+    if (!m) continue
+    const hash = m[1]
+    const prefix = `${hash}.json`
+    let g = groups.get(hash)
+    if (!g) { g = { hash, prefix, files: [], dataFiles: [], newestMtimeMs: 0 }; groups.set(hash, g) }
+    g.files.push(name)
+    if (DATA_SUFFIX_RE.test(name.slice(prefix.length))) g.dataFiles.push(name)
+    if (typeof e !== "string") g.newestMtimeMs = Math.max(g.newestMtimeMs, Number(e?.mtimeMs) || 0)
+  }
+  return groups
+}
+
+/** 三合取判定（**纯函数**——零 IO；入参 = 已取证事实）：
+ *  facts = { now, newestMtimeMs, ownerStates, dataFiles: [{readable, cwdExists}] }
+ *  → { cleanable, reason }（reason 面：window / live-owner / unknown-owner / no-content /
+ *  cwd-gone / cwd-exists / unreadable）。 */
+export function judgeStaleGroup(facts) {
+  const { now, newestMtimeMs = 0, ownerStates = [], dataFiles = [] } = facts
+  if (!(newestMtimeMs < now - STALE_SAFETY_WINDOW_MS)) return { cleanable: false, reason: "window" }
+  if (ownerStates.includes("alive")) return { cleanable: false, reason: "live-owner" }
+  if (ownerStates.includes("unknown")) return { cleanable: false, reason: "unknown-owner" }
+  if (!dataFiles.length) return { cleanable: true, reason: "no-content" } // T2
+  for (const f of dataFiles) { // T1：可读数据文件 cwd 全不在盘（至少一份；不可读 ⇒ fail-safe 保留）
+    if (!f.readable || f.cwdExists == null) return { cleanable: false, reason: "unreadable" }
+    if (f.cwdExists) return { cleanable: false, reason: "cwd-exists" }
+  }
+  return { cleanable: true, reason: "cwd-gone" }
+}
+
+/** 目录快照 → 组集合：本族名逐条目 `stat` 异步（分块——非阻塞、不进启动关键路径）。
+ *  names 缺省 = 自行 readdir（dir 注入缝；pass 编排可传共享快照——readdir 恰一次）。
+ *  `hashes` 在场 ⇒ **按前缀预筛后再 stat**（单组重校验面：逐组调用不随存量放大——
+ *  `--confirm <hash>` / 端侧命令面的逐组重校验成本 = O(该组文件数)）。 */
+async function snapshotGroups(dir, names, hashes = null) {
+  if (!names) {
+    try { names = await _staleHooks.readdir(dir) } catch { return new Map() }
+  }
+  const want = hashes ? hashes.map((h) => `${h}.json`) : null
+  const hit = names.map((n) => (typeof n === "string" ? n : n?.name))
+    .filter((n) => typeof n === "string" && GROUP_RE.test(n) && (!want || want.some((p) => n === p || n.startsWith(p + "."))))
+  const facts = []
+  for (let i = 0; i < hit.length; i += STAT_CHUNK) {
+    const chunk = await Promise.all(hit.slice(i, i + STAT_CHUNK).map(async (name) => {
+      try { return { name, mtimeMs: (await _staleHooks.stat(join(dir, name))).mtimeMs } } catch { return null }
+    }))
+    for (const f of chunk) if (f) facts.push(f)
+  }
+  return groupSessionEntries(facts)
+}
+
+/** ① 面入参：manifest `slotSessions` 属主 pid（manifest 缺失 / 损坏 ⇒ 空 ⇒ 该条自动满足）。 */
+async function manifestOwners(dir, prefix) {
+  let m
+  try { m = JSON.parse(await _staleHooks.readFile(join(dir, `${prefix}.manifest`))) } catch { return [] }
+  const pids = []
+  for (const owner of Object.values(m?.slotSessions ?? {})) {
+    const pid = typeof owner === "string" && owner ? ownerPid(owner) : 0
+    if (pid) pids.push(pid)
+  }
+  return pids
+}
+
+/** cwd 是否在盘（异步单条目）；非 ENOENT（权限 / 网络错）⇒ 不可判 ⇒ 视为存在（保守向）。 */
+async function pathExists(p) {
+  try { await _staleHooks.stat(p); return true } catch (e) { return e?.code !== "ENOENT" }
+}
+
+/** ② 面取证：逐数据文件（可读 ∧ cwd 字段在盘）。不可读 / 无 `cwd` ⇒ readable:false（fail-safe）。 */
+async function dataFileFacts(dir, group) {
+  const out = []
+  for (const name of group.dataFiles) {
+    let data = null
+    try { data = JSON.parse(await _staleHooks.readFile(join(dir, name))) } catch { data = null }
+    const cwd = typeof data?.cwd === "string" && data.cwd ? data.cwd : null
+    out.push(cwd ? { readable: true, cwdExists: await pathExists(cwd) } : { readable: false, cwdExists: null })
+  }
+  return out
+}
+
+/**
+ * 候选列举（显式面 / 自动面共用）：③（廉价——短路组零预算）→ ①（**过 ③ 进 ① 即耗 1 预算**——
+ * 该组 manifest 读与（若过 ① 的）② 内容读均在此预算内）→ ②（内容判据）。
+ * 预算闸 = 过 ③ 进 ① 的组数 ≤ `limit`（达上限即停——升序余量下一 pass 继续；显式面传 Infinity）。
+ * 返回 { candidates, evaluated, groups }——`evaluated` = 过 ③ 进 ① 的组数（= 预算消耗组数，
+ * 含 ① 面 manifest 读——D-SE40）。
+ * `hashes` 在场 ⇒ 只判这些 hash（单组重校验面——`deleteStaleCwd` 用）。
+ */
+export async function listStaleCwds({ dir, entries = null, now = Date.now(), probeFn = probeOwnersAsync, limit = STALE_SWEEP_LIMIT, hashes = null } = {}) {
+  const groups = await snapshotGroups(dir, entries, hashes)
+  const all = [...groups.values()]
+  const wanted = hashes ? all.filter((g) => hashes.includes(g.hash)) : all
+  const ordered = wanted.sort((a, b) => a.newestMtimeMs - b.newestMtimeMs || (a.hash < b.hash ? -1 : 1))
+  const ownersByHash = new Map()
+  const allPids = new Set()
+  let evaluated = 0
+  for (const g of ordered) {
+    if (!(g.newestMtimeMs < now - STALE_SAFETY_WINDOW_MS)) continue // ③ 短路（零预算——未读盘）
+    if (evaluated >= limit) break // 预算闸（过 ③ 进 ① 即耗——达上限即停；余量下一 pass 继续）
+    evaluated++ // 该组 ① manifest 读 +（若过 ① 的）② 内容读均在此预算内（D-SE40）
+    const pids = await manifestOwners(dir, g.prefix)
+    ownersByHash.set(g.hash, pids)
+    for (const pid of pids) allPids.add(pid)
+  }
+  const bundle = allPids.size ? await probeFn([...allPids]) : { aliveSet: null, cmds: null }
+  const candidates = []
+  for (const g of ordered) {
+    const pids = ownersByHash.get(g.hash)
+    if (!pids) continue // ③ 短路 / 预算外（未进 ①）
+    const states = pids.map((pid) => ownerState(pid, bundle))
+    if (states.some((s) => s !== "dead")) continue // ① 短路（活 / 未知 ⇒ 保留——预算已耗，不退）
+    const verdict = judgeStaleGroup({ now, newestMtimeMs: g.newestMtimeMs, ownerStates: states, dataFiles: await dataFileFacts(dir, g) })
+    if (verdict.cleanable) {
+      candidates.push({ hash: g.hash, prefix: g.prefix, reason: verdict.reason, dataFiles: g.dataFiles.length, newestMtime: g.newestMtimeMs, files: g.files })
+    }
+  }
+  return { candidates, evaluated, groups: ordered.length }
+}
+
+/** 回收序（§6.17 落地顺序）：残留 / 端标记 → manifest → 数据文件。 */
+function recycleRank(name, prefix) {
+  const rest = name.slice(prefix.length)
+  if (rest === ".manifest") return 1
+  if (rest === "" || /^\.\d+$/.test(rest) || /^\.\d+\.d$/.test(rest)) return 2
+  return 0
+}
+
+/** 逐组回收（组粒度——非事务）：逐文件 rename 进回收批。单文件失败 / 回收根不可写 = 跳过并计数，
+ *  不 unlink 兜底（原文件零删除）；返回 { moved, skipped, batch }（零移动 ⇒ batch:null）。 */
+export async function recycleGroup(group, { dir, now = Date.now() } = {}) {
+  const batch = join(trashRootFor(dir), String(now))
+  const out = { moved: [], skipped: [], batch: null }
+  const ordered = [...group.files].sort((a, b) => recycleRank(a, group.prefix) - recycleRank(b, group.prefix))
+  for (const name of ordered) {
+    try {
+      if (!out.batch) { await _staleHooks.mkdir(batch); out.batch = batch }
+      await _staleHooks.rename(join(dir, name), join(batch, name))
+      out.moved.push(name)
+    } catch { out.skipped.push(name) }
+  }
+  if (!out.moved.length) out.batch = null
+  return out
+}
+
+/** 单组回收（显式命令面 / 端侧命令面）：重校验（TOCTOU——单组重判三合取）→ 回收。
+ *  `entries` = 目录名快照（可选——命令面循环可传同一快照免逐组全目录 readdir；
+ *  mtime 事实同自动面 pass 模型，**① 面 manifest 读与探测束仍逐组新鲜**——变活组由 ① 拦截）。 */
+export async function deleteStaleCwd(hash, { dir, now = Date.now(), probeFn = probeOwnersAsync, entries = null } = {}) {
+  const { candidates } = await listStaleCwds({ dir, now, probeFn, limit: Infinity, hashes: [hash], entries })
+  const target = candidates.find((c) => c.hash === hash)
+  if (!target) return { ok: false, reason: "not-cold", deleted: [] } // 期间变活 / 出窗 ⇒ 拒绝（零删除）
+  const r = await recycleGroup(target, { dir, now })
+  if (!r.moved.length) return { ok: false, reason: "recycle-failed", deleted: [], skipped: r.skipped }
+  return { ok: true, reason: target.reason, deleted: r.moved, skipped: r.skipped, batch: r.batch }
+}
+
+/** 清运（D-SE36）：超期回收批整删（批名 = 批次时间戳，13 位 epoch ms ⇒ 到期可比）。失败静默跳过
+ *  （不误删在期批）；后续 pass 重试。非批次名（外来目录）一律不碰。 */
+export async function purgeTrash({ dir, now = Date.now(), retentionMs = TRASH_RETENTION_MS } = {}) {
+  const root = trashRootFor(dir)
+  const out = { purged: [], failed: [] }
+  let batches
+  try { batches = await _staleHooks.readdir(root) } catch { return out } // 无回收根 ⇒ 无事可做
+  for (const batch of batches) {
+    if (!/^\d{13}$/.test(batch)) continue // 批名形态锁（本档写入口 = String(Date.now())）——外来目录不碰
+    const ts = Number(batch)
+    if (!(ts + retentionMs <= now)) continue
+    try { await _staleHooks.rm(join(root, batch)); out.purged.push(batch) } catch { out.failed.push(batch) }
+  }
+  return out
+}
+
+/** 有界清立面 pass（**自动面**——绑启动**窗外延迟拍**（`scheduleSessionGC`），每进程一次）：
+ *  候选（**过 ③ 进 ① ≤ `limit`**——含 ① 面 manifest 读）→ 逐组回收 → 超期批清运。
+ *  全链异步；失败由调用面静默（本函数不抛——逐文件失败已计数）。 */
+export async function sweepStale({ dir, entries = null, now = Date.now(), probeFn = probeOwnersAsync, limit = STALE_SWEEP_LIMIT } = {}) {
+  const { candidates, evaluated, groups } = await listStaleCwds({ dir, entries, now, probeFn, limit })
+  let moved = 0
+  let skipped = 0
+  for (const c of candidates) {
+    const r = await recycleGroup(c, { dir, now })
+    moved += r.moved.length
+    skipped += r.skipped.length
+  }
+  const purged = await purgeTrash({ dir, now })
+  return { groups, evaluated, candidates: candidates.length, moved, skipped, purged: purged.purged.length, purgeFailed: purged.failed.length }
+}

package/tools/git.mjs

@@ -42,10 +42,14 @@ function resolveBaseDir(cwd, workdir) {
  *  二者仍可经显式 `workdir` 指落点。 */
 const NO_REPO_DISCOVERY = new Set(["init", "clone"])
 
-/** 歧义（多态）消息：候选全列（绝对路径、按名排序）+ 指引显式 `workdir`——不猜（§6.13 解析序行 5）。 */
-function ambiguousRepoMessage(candidates, cwd) {
-  return `Ambiguous git repo at ${cwd}: ${candidates.length} subdirectories carry .git and ${MANIFEST_REL} — ` +
-    `pass workdir to run git in the intended one (no silent pick):\n` + candidates.map((c) => `- ${c}`).join("\n")
+/** 歧义（多态）消息：候选全列（绝对路径、按名排序）+ 指引显式 `workdir`——不猜（§6.13 解析序行 5）；
+ *  **两档变体**（#188——按 `matched`）：带档级 ⇒ 「.git ∧ PROJECT-MANIFEST.json」；裸仓级 ⇒ 「.git」
+ *  且注明 none carries …（不书带档句——§6.13 A22）。 */
+function ambiguousRepoMessage(candidates, cwd, matched) {
+  const head = matched === "git"
+    ? `Ambiguous git repo at ${cwd}: ${candidates.length} subdirectories carry .git (none carries ${MANIFEST_REL})`
+    : `Ambiguous git repo at ${cwd}: ${candidates.length} subdirectories carry .git and ${MANIFEST_REL}`
+  return `${head} — pass workdir to run git in the intended one (no silent pick):\n` + candidates.map((c) => `- ${c}`).join("\n")
 }
 
 // ─── 审批门注入缝（#59——「只读判定 / 审批门按端注入」，形态参 §2.13.5 注入缝）────────
@@ -108,14 +112,15 @@ export const gitTool = {
     // workdir: run git in a subdirectory (monorepo / multi-repo). Shadow ctx.cwd so
     // every action + snapshotBefore + checkpoint resolves against the workdir.
     if (args.workdir) ctx = { ...ctx, cwd: resolveBaseDir(ctx.cwd, args.workdir) }
-    // 仓发现（§6.13 · #62）：缺省路径（无 workdir）⇒ 单源 = `discoverRepos`——工作区根（非仓）⇒
-    // 唯一带 manifest 子仓：重定向 `ctx.cwd` + 结果首行注记；零 ⇒ 原值落 §6.12 fail-closed（零
-    // 行为变）；多 ⇒ throw（列候选 + 指 workdir，不猜）。判据 = workdir 真值在场（与上行同源——
-    // 空串与缺省同判）；`init` / `clone` 例外不做发现。self / none 态 ctx 对象引用透传（不 clone）。
+    // 仓发现（§6.13 · #62）：缺省路径（无 workdir）⇒ 单源 = `discoverRepos`（仓梯——#188 含裸仓级）
+    // ——工作区根（非仓）⇒ 唯一带档子仓 / 零档时唯一裸仓：重定向 `ctx.cwd` + 结果首行注记；零 ⇒ 原值
+    // 落 §6.12 fail-closed（零行为变）；多 ⇒ throw（列该级候选 + 指 workdir，不猜——消息按 `matched`
+    // 两档变体）。判据 = workdir 真值在场（与上行同源——空串与缺省同判）；`init` / `clone` 例外
+    // 不做发现。self / none 态 ctx 对象引用透传（不 clone）。
     let repoNote = ""
     if (!args.workdir && !NO_REPO_DISCOVERY.has(args.action)) {
       const discovered = discoverRepos(ctx.cwd)
-      if (discovered.kind === "ambiguous") throw new Error(ambiguousRepoMessage(discovered.candidates, ctx.cwd))
+      if (discovered.kind === "ambiguous") throw new Error(ambiguousRepoMessage(discovered.candidates, ctx.cwd, discovered.matched))
       if (discovered.kind === "unique") {
         ctx = { ...ctx, cwd: discovered.root }
         repoNote = `(repo: ${discovered.root})`

package/traces/trace-cleanup.mjs

@@ -0,0 +1,109 @@
+/**
+ * trace-cleanup.mjs — 轨迹清理执行面（TRACES.md §6.4 · STARTUP-LATENCY 批，2026-09-21）。
+ *
+ * 判据 = **目录级三段梯**（D-TR11）：设 `D` = 日目录（`YYYY-MM-DD`——本地时区，与
+ * `localDateStr` 同口径）、`retention` = `traces.retentionHours`：
+ *   ① `dayEnd(D) + retention ≤ now` **且目录内全部条目为 `.jsonl`** ⇒ **整目录删**
+ *      （递归 rm，零逐文件 stat）；
+ *   ② `dayStart(D) + retention > now` ⇒ **整目录跳过**（正常写入下目录内无可过期文件）；
+ *   ③ 其余（含非 `.jsonl` 条目的目录；非日期名目录——日期解析 NaN ⇒ ①② 两条件恒假 ⇒ 自然落 ③）
+ *      ⇒ 逐文件 `stat` 判定 + unlink（现行语义；非 `.jsonl` 一律不碰）。
+ *   空日目录在任何分支后按现法移除。
+ *
+ * 计数口径（D-TR11）：整删支的 `removed` = 该批内 `.jsonl` 条目数（与 ③ 支逐文件计入同口径；
+ * 非 `.jsonl` 不计数）——既有断言面保持。
+ * 语义 delta（登记）：整删不逐文件核 mtime（人为回拨 mtime 的文件随目录清理——正常写入
+ * mtime ∈ 目录日 ⇒ 无差异）；② 支跳过时人为前拨（超期）文件暂留（宽容向）——保留期主粒度
+ * 改为**目录日**（与 §6.1 的 24h 保留期并读）。
+ *
+ * 本体**无状态**（手动面 / 每写节流面直调——启动面经 `scheduleTraceCleanup`）；每写节流住
+ * `trace-store.mjs`（`maybePruneTraces`——D-TR12：10 分钟窗 + 在飞合并）。启动面 = **启动窗外
+ * 延迟拍**（D-TR13）：`scheduleTraceCleanup` + `TRACE_CLEANUP_DELAY_MS`（3s）住本档、由 CLI
+ * 直引（白名单 / 闸位住调用面）；`_setTraceCleanupDelayForTest` = 延迟测试缝。
+ * `_cleanupHooks` = 测试注入缝（`_traceHooks` 同惯例——stat 计数 / 失败注入；生产永远走真实实现）。
+ */
+import { readdir, stat, unlink, rmdir, rm } from "node:fs/promises"
+import { join } from "node:path"
+
+export const _cleanupHooks = {
+  readdir: (dir) => readdir(dir),
+  stat: (p) => stat(p),
+  unlink: (p) => unlink(p),
+  rmdir: (d) => rmdir(d),
+  rm: (d) => rm(d, { recursive: true, force: true }),
+}
+
+const DAY_RE = /^(\d{4})-(\d{2})-(\d{2})$/
+
+/** 日目录边界（本地时区——`localDateStr` 同口径）；非日期名 / 非法日（如 2026-02-31）
+ *  ⇒ null（⇒ ①② 两条件恒假 ⇒ 落 ③ 逐文件支）。 */
+export function dayBounds(name) {
+  const m = DAY_RE.exec(name)
+  if (!m) return null
+  const y = Number(m[1])
+  const mo = Number(m[2])
+  const d = Number(m[3])
+  const start = new Date(y, mo - 1, d).getTime()
+  if (Number.isNaN(start) || new Date(start).getDate() !== d) return null // 2026-02-31 归一为 03-03 ⇒ 非日期名
+  return { start, end: new Date(y, mo - 1, d, 23, 59, 59, 999).getTime() }
+}
+
+/**
+ * D-TR10 保留期语义 + D-TR11 目录级判据：删除 traces 根下 mtime 超过保留期的轨迹文件
+ * （保留期 = config.traces.retentionHours，默认 24h）；删空的日期目录（YYYY-MM-DD）。
+ * 目录里非 .jsonl 文件不碰。返回删除文件数（整删支 = 批内 `.jsonl` 条目数）。
+ */
+export async function cleanupTraces({ dir, retentionHours = 24 } = {}) {
+  const now = Date.now()
+  const cutoff = now - retentionHours * 3_600_000
+  const window = retentionHours * 3_600_000
+  let days
+  try { days = await _cleanupHooks.readdir(dir) } catch { return 0 } // 目录不存在/不可读 → 无事可做
+  let removed = 0
+  for (const day of days) {
+    const dayDir = join(dir, day)
+    let names
+    try { names = await _cleanupHooks.readdir(dayDir) } catch { continue } // 非目录 / 不可读 → 跳过
+    const bounds = dayBounds(day)
+    if (bounds && bounds.end + window <= now && names.every((n) => n.endsWith(".jsonl"))) {
+      // ① 整目录删（纯 .jsonl 且全目录过期——零逐文件 stat；批内条目全计入）
+      try { await _cleanupHooks.rm(dayDir); removed += names.length } catch { /* 占用/竞态——跳过 */ }
+      continue
+    }
+    if (bounds && bounds.start + window > now) {
+      // ② 整目录跳过（未到期——空日目录仍按现法移除）
+      try { if (!names.length) await _cleanupHooks.rmdir(dayDir) } catch { /* 跳过 */ }
+      continue
+    }
+    // ③ 逐文件（现行语义——非 .jsonl 一律不碰）
+    for (const n of names) {
+      if (!n.endsWith(".jsonl")) continue
+      try {
+        if ((await _cleanupHooks.stat(join(dayDir, n))).mtimeMs < cutoff) { await _cleanupHooks.unlink(join(dayDir, n)); removed++ }
+      } catch { /* 单个文件失败不影响其余 */ }
+    }
+    try { if ((await _cleanupHooks.readdir(dayDir)).length === 0) await _cleanupHooks.rmdir(dayDir) } catch { /* 跳过 */ }
+  }
+  return removed
+}
+
+// ─── 启动窗外延迟拍（D-TR13 · 2026-09-21 收口前机制微修 2）────────────────────────────────
+
+/** 延迟（自**调度点**起）：与 D-SE39 的 `GC_PASS_DELAY_MS` 同值同形态——3s ⇒ 清理起点落于
+ *  启动窗（TTY 门 ≤2s）之外，启动链不因本清理的 fs 爆发与自身争同一事件循环。 */
+export const TRACE_CLEANUP_DELAY_MS = 3000
+let traceCleanupDelayMs = TRACE_CLEANUP_DELAY_MS
+
+/** 测试缝（`_setSessionGcDelayForTest` 同款）：用例置 0–短值即可点火（勿真等 3s）；
+ *  还原 = `_setTraceCleanupDelayForTest(TRACE_CLEANUP_DELAY_MS)`。 */
+export function _setTraceCleanupDelayForTest(ms) { traceCleanupDelayMs = ms }
+
+/** 启动面调度器（CLI 会话型命令白名单闸内直引——`thincoder-cli/bin/thincoder.mjs`）：
+ *  `dir` / `retentionHours` 由**调度点**捕获（调用面取 `tracesRoot()`）；延迟
+ *  `TRACE_CLEANUP_DELAY_MS` 后点火。失败静默（`.catch` 在此——fire-and-forget 语义不变）；
+ *  **不 unref**（保后台排空现状——同 D-SE39）。**无去重闸**：白名单 / 闸位 / 每进程一次语义
+ *  住调用面（启动面恰一处调用）；进程早退（显式 `process.exit`）未及拍 ⇒ 本次不执行
+ *  （幂等——下次会话型命令照常清理）。 */
+export function scheduleTraceCleanup({ dir, retentionHours = 24 } = {}) {
+  setTimeout(() => { cleanupTraces({ dir, retentionHours }).catch(() => { /* 失败静默——同上 */ }) }, traceCleanupDelayMs)
+}

package/traces/trace-store.mjs

@@ -20,8 +20,9 @@
  *   **单遍序列化**：脱敏内联进输出缓冲（不构造复制图 + 二次全量字符串）——字段名/次序
  *   与 `JSON.stringify` 形态同构（T-TR1 等价断言）。
  * - 容量 / 清理（§2.5 #116 / A21 已裁 · 按建议——取 VSC 侧）：**完整落盘**（不截断、
- *   不丢行、不丢记录）；**清理 = 每写一次 prune**（写盘成功后顺带 `cleanupTraces`——
- *   与写盘同在 fire-and-forget 异步体内）。目录按日组织（YYYY-MM-DD），可按日/会话过滤。
+ *   不丢行、不丢记录）；**清理 = 每写一次 prune**（写盘成功后顺带 `maybePruneTraces`——
+ *   与写盘同在 fire-and-forget 异步体内）。2026-09-21（TRACES.md §6.4）：判据改**目录级三段梯**
+ *   + 每写 prune **节流**；清理实现外提 `trace-cleanup.mjs`（本档包装保既有 import 面）。
  * - seq = 当日目录内最大已有 seq + 1（D-TR3——跨会话/进程重启不覆写既有旧轨迹——
  *   18.6.1 评审 #3）；**进程内 seqCache（§23.3.2——消除逐调用同步扫目录）**：首次
  *   readdirSync 后进程内递增预留，目录被清理（retention）后取下界重扫一次（防御）。
@@ -35,7 +36,8 @@
  *   记录不输出 round 字段（全设计无 round 定义——删——不发明无来源字段）。
  */
 import { readdirSync, existsSync } from "node:fs"
-import { appendFile, mkdir, readdir, stat, unlink, rmdir } from "node:fs/promises"
+import { appendFile, mkdir } from "node:fs/promises"
+import { cleanupTraces as cleanupTracesImpl } from "./trace-cleanup.mjs"
 import { join } from "node:path"
 import { createHash } from "node:crypto"
 import { configDir, loadConfig } from "../config.mjs"
@@ -87,17 +89,33 @@ export function tracesDirFor(dateStr) {
   return join(tracesRoot(), dateStr)
 }
 
-// ─── 容量 / 清理策略（§2.5 #116 / A21 已裁 · 按建议——取 VSC 侧）───────────────
+// ─── 容量 / 清理策略（§2.5 #116 / A21 已裁 · 按建议——取 VSC 侧）（§6.4 判据面）─────────
 // 完整落盘：不截断、不丢行（无单消息/单记录额度，无在途丢弃）；清理 = 每写一次 prune
-// （写盘成功后顺带 cleanupTraces——与写盘同在 fire-and-forget 异步体内，永不阻塞 chat）。
+// （写盘成功后顺带清理——与写盘同在 fire-and-forget 异步体内，永不阻塞 chat）。
 
-// 进程内 seq 缓存（§23.3.2：dir → 已见/已预留 max——首次 readdirSync 后递增预留；
-// 目录被清理（retention）后取下界重扫一次（防御））。
+// 进程内 seq 缓存（§23.3.2：dir → 已预留 max；首次读盘后递增预留，目录被清理后取下界重扫一次）。
 const _seqCache = new Map()
+// 每写 prune 节流（D-TR12 · §6.4）：窗 = 10 分钟 + 在飞合并（同窗 3 连写 ⇒ 扫描 ≤1 次）。
+export const PRUNE_THROTTLE_MS = 10 * 60_000
+let _pruneAt = 0, _pruneInFlight = null
 
-/** 测试缝：清进程内状态（seqCache）。 */
+/** 测试缝：清进程内状态（seqCache + 节流窗/在飞——**跨用例残留**，用例须显式复位）。 */
 export function _resetTraceStateForTest() {
   _seqCache.clear()
+  _pruneAt = 0
+  _pruneInFlight = null
+}
+
+/** 每写 prune（`recordChatTrace` 写盘成功后调用）：窗内 / 在飞 ⇒ 不发起新扫描。
+ *  返回 = 新扫描 promise（首次发起）/ `false`（窗内 / 在飞——不重复扫）；`now` = 测试注入缝。 */
+export function maybePruneTraces({ dir = tracesRoot(), retentionHours = 24, now = Date.now() } = {}) {
+  if (_pruneInFlight) return false // 在飞合并：同窗并发不重复发起扫描
+  if (now - _pruneAt < PRUNE_THROTTLE_MS) return false
+  _pruneAt = now
+  _pruneInFlight = cleanupTracesImpl({ dir, retentionHours })
+    .catch(() => 0) // 清理失败静默——不影响写盘（fire-and-forget 同纪律）
+    .finally(() => { _pruneInFlight = null })
+  return _pruneInFlight
 }
 
 function scanMaxSeq(dir) {
@@ -266,38 +284,16 @@ export function recordChatTrace(provider, opts = {}, result = null, error = null
       await _traceHooks.append(join(dir, `${sessionKey}-${seq}.jsonl`), record + "\n")
       let retentionHours = 24
       try { retentionHours = loadConfig()?.traces?.retentionHours ?? 24 } catch { /* 默认 24h */ }
-      await cleanupTraces({ dir: tracesRoot(), retentionHours })
+      await maybePruneTraces({ dir: tracesRoot(), retentionHours }) // D-TR12：每写节流（窗内 ⇒ false 即返）
     } catch {
       // F-TR3：落盘/prune 失败静默降级——不抛错、不阻塞 chat() 返回
     }
   })()
 }
 
-/**
- * D-TR10（用户裁定——发布隐私 + 磁盘卫生）：清理——删除 traces 根下
- * mtime 超过保留期的轨迹文件（保留期 = config.traces.retentionHours，默认 24h）；
- * 删空的日期目录（YYYY-MM-DD）。目录里非 .jsonl 文件不碰。
- * §2.5 #116 / A21（已裁 · 按建议）：调用点 = 每写一次 prune（`recordChatTrace` 写盘成功
- * 后顺带调用——fire-and-forget 异步体内）；CLI 启动点的启动清理保留（本端不动）。
- * 返回删除文件数。
- */
-export async function cleanupTraces({ dir = tracesRoot(), retentionHours = 24 } = {}) {
-  const cutoff = Date.now() - retentionHours * 3_600_000
-  let days
-  try { days = await readdir(dir) } catch { return 0 } // 目录不存在/不可读 → 无事可做
-  let removed = 0
-  for (const day of days) {
-    const dayDir = join(dir, day)
-    try { if (!(await stat(dayDir)).isDirectory()) continue } catch { continue }
-    let names
-    try { names = await readdir(dayDir) } catch { continue }
-    for (const n of names) {
-      if (!n.endsWith(".jsonl")) continue
-      try {
-        if ((await stat(join(dayDir, n))).mtimeMs < cutoff) { await unlink(join(dayDir, n)); removed++ }
-      } catch { /* 单个文件失败不影响其余 */ }
-    }
-    try { if ((await readdir(dayDir)).length === 0) await rmdir(dayDir) } catch {}
-  }
-  return removed
+/** D-TR10 清理面（D-TR11 目录级三段梯）——实现外提 `traces/trace-cleanup.mjs`；此处包装保
+ *  既有 import 面与缺省 `dir`（`tracesRoot()` 单源——测试经 `THINCODER_TRACES_DIR` 隔离）。
+ *  调用点 = 每写 prune（经 `maybePruneTraces`）+ 启动清理（壳侧）；返回删除文件数。 */
+export function cleanupTraces({ dir = tracesRoot(), retentionHours = 24 } = {}) {
+  return cleanupTracesImpl({ dir, retentionHours })
 }