@thincoder/core 0.9.5 → 0.10.2

package/session-slot-scan.mjs

@@ -0,0 +1,299 @@
+/**
+ * session-slot-scan.mjs — 会话槽盘面扫描（SESSION.md §6.22 · SESSION-LIST-DISK 批 · 2026-09-28）。
+ *
+ * 条目集单源 = 盘面实读（判据句 1）：sessions 根下 `^<hash>\.json\.(\d+)$` 的**普通文件**——
+ * 逐条出槽号 N；manifest `m.slots` 不参与条目集（既不筛也不补），只作判据句 2 取数链的
+ * **摘要缓存**（叠加源）。后缀闭集（`.manifest` / `.manifest.<端名>` / `.tmp` / `.corrupted` /
+ * `.unreadable` / `.bak-<ts>` / `.d` 目录 / `.stale-<ts>` / 遗留单档 `<hash>.json`）由
+ * 「数字槽号全锚 + 普通文件」两个判据一并排除——零伪槽号、零目录误收。
+ *
+ * 取数链（判据句 2 · 免费先行）：① 摘要快路（摘要在场且 **`ts`（摘要落盘时刻）≥ 文件 mtime** ⇒
+ * 整条由摘要供给、**槽文件零字节读**——设计档 §6.22 判据句 2 快路比较口径**已收正为 `ts` 单源**；
+ * `updatedAt`（会话逻辑时，取于写槽文件之前）恒早于 mtime ⇒ 按之快路生产永不命中）② 小档全读
+ * （`size ≤ SCAN_FULL_MAX` = 256 KiB ⇒ JSON 全解析、全字段）③ 大档早键截读（读头 `min(size,
+ * SCAN_HEAD_BYTES)` = 64 KiB——**结构感知扫描**：键值边界由结构定界、小值解码走 `JSON.parse`
+ * 切片，零正则、零整档物化；遇顶层键 `history` 即停，其后的键不读）④ stat 兜底（`updatedAt` =
+ * mtime）。字段优先级 = **盘面实读值 > 摘要值（任意新鲜度）> 缺省**（`""` / `null` / mtime）；单次
+ * 调用槽文件读 ≤ `SCAN_BUDGET_BYTES`（4 MiB）——预算按 mtime 降序耗用（最上面 = 用户最可能看
+ * 的行），越预算条目退 ④。计数两字段**不可得 = `null`**（真 0 与未知可分——§6.25 判据句 4）。
+ *
+ * 降级阶梯（判据句 3 · 入列不筛）：坏 JSON / 半写 / `version > 2` / 异 cwd 内容档一律入列
+ * （存在性 ≠ 可读性）——内容面不可用 ⇒ 该档退摘要 ∪ 缺省、日期退 mtime；点开走既有失败面。
+ *
+ * 静态环（与 session-slots.mjs ↔ session-slots-manifest.mjs 同形）：本档引 `sessionPath`
+ * （前缀 / 目录单源——先短哈希迁移、后枚举）与 `extractSlotMeta`（② 全读面摘要单源）；两侧只在
+ * 函数体内运行时使用（模块求值期零顶层调用 ⇒ 环安全）。`SCAN_*` 三常量单源住本档。
+ */
+import { closeSync, openSync, readSync, readFileSync, readdirSync, statSync } from "node:fs"
+import { basename, dirname, join } from "node:path"
+// 环 import：见头注（前缀 = `sessionPath` 的 basename——与 `slotPath` 同源）。
+import { sessionPath } from "./session-slots.mjs"
+// ② 全读面摘要单源（计数 / 首条真实用户消息 / 字段缺省口径——与槽摘要写面同函数）。
+import { extractSlotMeta } from "./session-slots-manifest.mjs"
+// 「真实用户消息」谓词单源（人读线窗口 / 槽摘要 / ③ 早键截读三面同判据）。
+import { isRealUserMsg } from "./history-window.mjs"
+
+/** ② 小档全读上界（判据句 2）。 */
+export const SCAN_FULL_MAX = 256 * 1024
+/** ③ 大档早键截读窗口（判据句 2）。 */
+export const SCAN_HEAD_BYTES = 64 * 1024
+/** 单次扫描的槽文件读预算（判据句 2——按 mtime 降序耗用，越预算退 ④）。 */
+export const SCAN_BUDGET_BYTES = 4 * 1024 * 1024
+
+/** 观测计数（测试缝——`_storeStats` / `_releaseStats` 同惯例）：读放大上界的断言语料。
+ *  `bytes` = 本进程槽文件读累计字节；`reads` = 逐次读 `{ slot, bytes, window }`（window =
+ *  `"full"` ② / `"head"` ③）；`fastPath` = ① 命中次数。生产零消费。 */
+export const _scanStats = { calls: 0, bytes: 0, fastPath: 0, reads: [] }
+/** 测试缝复位（跨用例隔离——`_resetSessionsDirForTest` 同惯例）。 */
+export function _resetScanStats() {
+  _scanStats.calls = 0; _scanStats.bytes = 0; _scanStats.fastPath = 0; _scanStats.reads.length = 0
+}
+
+const SLOT_SUFFIX = /^\d+$/
+const HEAD_KEYS = new Set(["title", "activeProvider", "activeModel", "createdBy", "cwd", "updatedAt", "version"])
+const isNum = (v) => typeof v === "number" && Number.isFinite(v)
+const isStr = (v) => typeof v === "string"
+const isWs = (c) => c === " " || c === "\n" || c === "\r" || c === "\t"
+
+/** JSON 切片解码（结构定界的**小值**：键 / 短串 / 数字）；不可解析 ⇒ `undefined`。 */
+function parseSlice(text, start, end) { try { return JSON.parse(text.slice(start, end)) } catch { return undefined } }
+
+/** JSON 字符串跳过（不建值——大串零分配）。返回闭引号后一位置；窗截断 ⇒ `null`。 */
+function skipJsonString(text, i) {
+  const n = text.length
+  let j = i + 1
+  while (j < n) {
+    const c = text[j]
+    if (c === "\\") { j += 2; continue }
+    if (c === '"') return j + 1
+    j++
+  }
+  return null
+}
+
+/** 结构化跳过任意 JSON 值（对象 / 数组按深度配对，字符串走 `skipJsonString`）。窗截断 ⇒ `null`。 */
+function skipJsonValue(text, i) {
+  const n = text.length
+  const c = text[i]
+  if (c === '"') return skipJsonString(text, i)
+  if (c === "{" || c === "[") {
+    let depth = 0
+    let j = i
+    while (j < n) {
+      const ch = text[j]
+      if (ch === '"') {
+        const end = skipJsonString(text, j)
+        if (end === null) return null
+        j = end
+        continue
+      }
+      if (ch === "{" || ch === "[") depth++
+      else if (ch === "}" || ch === "]") {
+        depth--
+        if (depth === 0) return j + 1
+      }
+      j++
+    }
+    return null
+  }
+  let j = i
+  while (j < n && !isWs(text[j]) && text[j] !== "," && text[j] !== "}" && text[j] !== "]") j++
+  return j === i ? null : j
+}
+
+/** ③ 供给面：窗内首个真实用户消息（谓词单源 = history-window.mjs）。`i` = `history` 数组起点。
+ *  逐条结构定界 + `JSON.parse` 切片（谓词拿整条对象）；窗截断 ⇒ 停（已得部分照给）。 */
+function firstUserMessage(text, i) {
+  const n = text.length
+  if (text[i] !== "[") return null
+  let j = i + 1
+  while (j < n) {
+    const c = text[j]
+    if (isWs(c) || c === ",") { j++; continue }
+    if (c !== "{") return null // 数组尾 / 非对象条 ⇒ 不再走（保守）
+    const end = skipJsonValue(text, j)
+    if (end === null) return null
+    const m = parseSlice(text, j, end)
+    if (isRealUserMsg(m)) return m.content.slice(0, 80)
+    j = end
+  }
+  return null
+}
+
+/** ③ 早键截读（判据句 2）：自首字节走 JSON **顶层键**——供给面键取值、遇 `history` 置
+ *  `historySeen` 并取首条真实用户消息后**即停**（其后的键不读）。窗口截断 / 结构不符 ⇒ 已得
+ *  部分照给（缺键由摘要补位）；值跳过一律结构定界（非正则）。 */
+function scanHeadKeys(text) {
+  const out = {}
+  const n = text.length
+  let i = 0
+  while (i < n && isWs(text[i])) i++
+  if (text[i] !== "{") return out
+  i++
+  while (i < n) {
+    while (i < n && isWs(text[i])) i++
+    const c = text[i]
+    if (c === "}" || c === undefined) break
+    if (c === ",") { i++; continue }
+    if (c !== '"') break
+    const keyEnd = skipJsonString(text, i)
+    if (keyEnd === null) break
+    const key = parseSlice(text, i, keyEnd)
+    if (!isStr(key)) break
+    i = keyEnd
+    while (i < n && isWs(text[i])) i++
+    if (text[i] !== ":") break
+    i++
+    while (i < n && isWs(text[i])) i++
+    if (key === "history") {
+      out.historySeen = text[i] === "[" // 数组起点 = ③ 面「history 数组」判据（② 面 = Array.isArray）
+      const first = firstUserMessage(text, i)
+      if (first !== null) out.firstMessage = first
+      break // 判据：遇 history 即停（其后的键不读——大数组不跳跃、不物化）
+    }
+    const valEnd = skipJsonValue(text, i)
+    if (valEnd === null) break // 窗截断 ⇒ 停（已得键照给）
+    if (HEAD_KEYS.has(key)) {
+      const v = parseSlice(text, i, valEnd)
+      if (isStr(v) || isNum(v)) out[key] = v
+    }
+    i = valEnd
+  }
+  return out
+}
+
+/** 内容面可用性（判据句 3 降级阶梯）：`history` **数组**已见（② = `Array.isArray` · ③ = 值以 `[`
+ *  起）∧ version ∈ {1,2} ∧ cwd 一致（缺键 = 本档）。坏 JSON / 半写 / `version > 2` / 异 cwd ⇒
+ *  内容面不可用（该档退摘要 ∪ 缺省、日期退 mtime）。 */
+function contentUsable(version, fileCwd, hasHistory, cwd) {
+  if (!hasHistory) return false
+  if (version !== 1 && version !== 2) return false
+  return !(isStr(fileCwd) && fileCwd.toLowerCase() !== cwd.toLowerCase())
+}
+
+/** ② 小档全读：JSON 全解析 ⇒ 全字段（② 供给面含计数两字段）。 */
+function fullDisk(text, cwd) {
+  let data
+  try { data = JSON.parse(text) } catch { return null }
+  if (!data || typeof data !== "object" || Array.isArray(data)) return null
+  if (!contentUsable(data.version, data.cwd, Array.isArray(data.history), cwd)) return null
+  const meta = extractSlotMeta(data.history, data.activeProvider, data.updatedAt, isStr(data.title) ? data.title : "")
+  if (isNum(data.updatedAt)) meta.updatedAt = data.updatedAt
+  else delete meta.updatedAt // 缺键 ⇒ 退摘要 / mtime（缺省链；extractSlotMeta 的 now() 兜底在此不适用）
+  if (data.activeModel) meta.activeModel = data.activeModel
+  if (data.createdBy) meta.createdBy = data.createdBy
+  return meta
+}
+
+/** ③ 头窗供给面 → 盘面元数据（门不过 ⇒ `null`；`historySeen` 是内部标记，不入供给面）。 */
+function headDisk(head, cwd) {
+  if (!contentUsable(head.version, head.cwd, head.historySeen === true, cwd)) return null
+  delete head.version
+  delete head.cwd
+  delete head.historySeen
+  return head
+}
+
+/** 盘面枚举（判据句 1）：普通文件 + 数字槽号全锚；目录不存在 / 不可读 ⇒ `[]`。
+ *  `sessionPath` 先行 = 短哈希迁移随该调用先行（先迁移、后枚举）。 */
+function enumerateSlots(cwd) {
+  const base = sessionPath(cwd)
+  const dir = dirname(base)
+  const prefix = `${basename(base)}.`
+  let entries
+  try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return [] }
+  const found = []
+  for (const e of entries) {
+    if (!e.isFile() || !e.name.startsWith(prefix)) continue
+    const suffix = e.name.slice(prefix.length)
+    if (!SLOT_SUFFIX.test(suffix)) continue
+    const path = join(dir, e.name)
+    try {
+      const st = statSync(path)
+      found.push({ slot: Number(suffix), path, size: st.size, mtime: st.mtimeMs })
+    } catch { /* 枚举与 stat 之间被删 / 不可达 ⇒ 视同不在盘 */ }
+  }
+  return found
+}
+
+/** ③ 头窗读（只读 `min(size, SCAN_HEAD_BYTES)` 字节——大档绝不整档读）。 */
+function readHeadText(path) {
+  const fd = openSync(path, "r")
+  try {
+    const buf = Buffer.allocUnsafe(SCAN_HEAD_BYTES)
+    const size = readSync(fd, buf, 0, SCAN_HEAD_BYTES, 0)
+    return buf.subarray(0, size).toString("utf8")
+  } finally {
+    try { closeSync(fd) } catch { /* 关闭失败不影响读结果 */ }
+  }
+}
+
+/** 字段装配（判据句 2 优先级）：盘面实读值 > 摘要值（任意新鲜度）> 缺省（`""` / `null` / mtime）；计数两字段
+ *  **不可得 = `null`**（非 `0`——真 0 与「不知道」可分；§6.25 判据句 4 / D-SE62）。`disk` = ②/③ 盘面供给面；
+ *  `digest` = manifest 摘要；`dateFromStat` = 日期取 stat mtime（判据句 2 ④ 与判据句 3 降级档）。 */
+function mergeFields(disk, digest, mtime, tsBase, dateFromStat) {
+  const d = disk ?? {}
+  const g = digest ?? {}
+  const num = (a, b, fallback) => isNum(a) ? a : (isNum(b) ? b : fallback)
+  const str = (a, b, fallback) => isStr(a) ? a : (isStr(b) ? b : fallback)
+  const meta = {
+    ts: tsBase,
+    messageCount: num(d.messageCount, g.messageCount, null),
+    turnCount: num(d.turnCount, g.turnCount, null),
+    firstMessage: str(d.firstMessage, g.firstMessage, ""),
+    activeProvider: str(d.activeProvider, g.activeProvider, ""),
+    updatedAt: dateFromStat ? mtime : num(d.updatedAt, g.updatedAt, mtime),
+    title: str(d.title, g.title, ""),
+    createdBy: str(d.createdBy, g.createdBy, ""),
+  }
+  const model = str(d.activeModel, g.activeModel, null)
+  if (model !== null) meta.activeModel = model
+  return meta
+}
+
+/** 行时间标基准：摘要 `ts` > 数字形旧条目值 > mtime（判据句 2 缺省链）。 */
+function tsBaseOf(entry, mtime) {
+  if (isNum(entry?.ts)) return entry.ts
+  if (isNum(entry)) return entry
+  return mtime
+}
+
+/** 单档取数（判据句 2 四级的装配点）：返回 `{ meta, spent }`——`spent` = 本次占用的预算字节。 */
+function readSlot(f, entry, budget, cwd) {
+  const mtime = f.mtime
+  const digest = entry && typeof entry === "object" ? entry : null
+  const tsBase = tsBaseOf(entry, mtime)
+  // ① 摘要快路：摘要在场且 `ts`（摘要落盘时刻）≥ 文件 mtime ⇒ 整条由摘要供给、槽文件零字节读
+  if (digest && isNum(digest.ts) && digest.ts >= mtime) {
+    _scanStats.fastPath++
+    return { meta: mergeFields(null, digest, mtime, tsBase, false), spent: 0 }
+  }
+  // ②/③：预算内读盘；越预算 / 读失败 / 内容不可用 ⇒ 盘面缺位（日期退 mtime——判据句 2 ④ / 判据句 3）
+  const full = f.size <= SCAN_FULL_MAX
+  const cost = full ? f.size : SCAN_HEAD_BYTES
+  if (cost > budget) return { meta: mergeFields(null, digest, mtime, tsBase, true), spent: 0 }
+  let disk = null
+  try {
+    const text = full ? readFileSync(f.path, "utf8") : readHeadText(f.path)
+    _scanStats.bytes += cost
+    _scanStats.reads.push({ slot: f.slot, bytes: cost, window: full ? "full" : "head" })
+    disk = full ? fullDisk(text, cwd) : headDisk(scanHeadKeys(text), cwd)
+  } catch { /* 并发删除 / EPERM ⇒ 盘面缺位 */ }
+  return { meta: mergeFields(disk, digest, mtime, tsBase, disk === null), spent: cost }
+}
+
+/** 扫描本 cwd 的槽文件并装配每档元数据（判据句 1 + 2）：返回 `[{ slot, meta, mtime }]`（序 = 枚举序——
+ *  行序归调用面投影；`mtime` = 文件 mtime，判定链 / 核实面新鲜度判据入参）。`digests` = manifest `m.slots`。 */
+export function scanSlotMetas(cwd, digests = {}) {
+  _scanStats.calls++
+  const found = enumerateSlots(cwd)
+  found.sort((a, b) => b.mtime - a.mtime) // 预算耗用序 = mtime 降序
+  let budget = SCAN_BUDGET_BYTES
+  const out = []
+  for (const f of found) {
+    const { meta, spent } = readSlot(f, digests[f.slot], budget, cwd)
+    budget -= spent
+    out.push({ slot: f.slot, meta, mtime: f.mtime })
+  }
+  return out
+}

package/session-slot-verify.mjs

@@ -0,0 +1,304 @@
+/**
+ * session-slot-verify.mjs — 读面懒核实面（SESSION.md §6.25 判据句 3 · LEDGER-RELIABILITY 批 · 2026-09-28）。
+ * 触发 = 读面交来的**不可信档清单**（谓词单源 `needsVerify`）。**调度 = 纯内存登记 + 启动窗外延迟拍**（`VERIFY_TICK_DELAY_MS` = 3s，`setTimeout` + `unref`——承 D-SE39：`setImmediate` 点火与启动链同循环）
+ * ⇒ 零 I/O / 零同步阻塞（首答 F-SL1 50 ms 不被拖慢）。核实 = 单档整档**分块流式**（计数只能全读获得——
+ * D-SE56）：1 MiB 分块 + 逐块宏任务让出（零 ≥50 ms 连续同步段）；**不整档物化**——走顶层键 + 逐元素结构
+ * 定界计数 / 切片解析（`jump` 每字符只扫一次；跨块续读、零正则）。预算 = 每轮 ≤ `SCAN_BUDGET_BYTES`（4 MiB
+ * ——单源住 `session-slot-scan.mjs`）∨ **超预算大档该轮至多一档**；未覆盖者留待下次列表调用；**不做全量扫**
+ * （D-SE67）。不重复三条：① 核完即回写摘要（`ts` 地板 = 该档 mtime——平台时间戳可领先 `Date.now()`，见回写行注释）⇒ 回快路；② **单飞**；③ **负缓存**（同 mtime 不重试）。
+ * 回写 = 尾部**一次合并写**（仅摘要条目）；校验门不过（坏 JSON / 异 cwd / `version > 2`）⇒ **不写回**。
+ * 缝：`_verifyState` · `_verifyIdle()`（**禁时间等待**）· `_setVerifyDelayForTest` · `_resetVerifyStateForTest`。
+ * 在飞轮去向：目录切换 ⇒ **弃轮**（零跨根写）；进程退出 ⇒ 拍 `unref` 不持活、在飞轮随终止丢弃；静态环：核内四引求值期零顶层调用 ⇒ 环安全。
+ */
+import { closeSync, openSync, readSync, statSync } from "node:fs"
+import { SCAN_BUDGET_BYTES } from "./session-slot-scan.mjs" // 预算常量单源
+import { sessionPath, slotPath } from "./session-slots.mjs" // 槽前缀 / 路径单源
+import { loadManifest, saveManifest } from "./session-slots-manifest.mjs" // 清单面单源
+import { isRealUserMsg } from "./history-window.mjs" // 「真实用户消息」谓词单源（turnCount / firstMessage）
+/** 启动窗外延迟拍（D-SE64 · 承 D-SE39）：自调度点起 3s ⇒ 核实起点落于启动窗外。 */
+export const VERIFY_TICK_DELAY_MS = 3000
+/** 分块粒度（判据句 3）：1 MiB + 逐块让出。 */
+export const VERIFY_CHUNK_BYTES = 1024 * 1024
+const HEAD_KEYS = new Set(["title", "activeProvider", "activeModel", "createdBy", "updatedAt", "version", "cwd"])
+const isNum = (v) => typeof v === "number" && Number.isFinite(v)
+const isStr = (v) => typeof v === "string"
+const isWs = (c) => c === " " || c === "\n" || c === "\r" || c === "\t"
+const isDelim = (c) => c === undefined || isWs(c) || c === "," || c === "}" || c === "]"
+const isBlank = (s) => { for (let i = 0; i < s.length; i++) if (!isWs(s[i])) return false; return true } // 尾随只许空白
+const yieldToLoop = () => new Promise((resolve) => setImmediate(resolve)) // 逐块让出（唯一 setImmediate——非点火）
+/** 观测计数（`_scanStats` 同惯例——生产零消费）：`ticks` / `verified` 成功回写档数 / `failed` 门不过档数 /
+ *  `skipped` 跳过档数（不在盘 / 负缓存 / 余量不足）/ `chunks` 分块读次数 / `bytes` 分块读字节。 */
+export const _verifyState = { ticks: 0, verified: 0, failed: 0, skipped: 0, chunks: 0, bytes: 0 }
+let verifyDelayMs = VERIFY_TICK_DELAY_MS
+/** 延迟拍缝（置 0 点火勿真等；还原 = 置回 `VERIFY_TICK_DELAY_MS`）。 */
+export function _setVerifyDelayForTest(ms) { verifyDelayMs = ms }
+/** 不可信谓词（判据句 3 · **单源**）：缺失 ∨ `ts < mtime`（陈旧）∨ 计数两字段任一非数（不可得）；真 0
+ *  不触发（数值 0 = 可信）；`mtime` 非数（stat 失败）⇒ 不妄断陈旧。 */
+export function needsVerify(entry, mtime) {
+  if (!entry || typeof entry !== "object") return true
+  if (!isNum(entry.messageCount) || !isNum(entry.turnCount)) return true
+  if (!isNum(entry.ts)) return true
+  return isNum(mtime) ? entry.ts < mtime : false
+}
+const pending = new Map() // cwd → Set(slot)：待核（拍在途——纯内存登记）
+const timers = new Map() // cwd → Timeout：拍句柄（去重 / 复位）
+const running = new Set() // cwd：在飞轮（单飞）
+const failedCache = new Map() // cwd → Map(slot → mtime)：负缓存
+
+/** 读面交付点（`listSlots` 同步返回前调用——纯内存登记 + 延迟拍：零 I/O / 零同步阻塞）：`scanned` = 扫描行
+ *  `[{ slot, meta, mtime }]`；不可信档按 **mtime 降序**入队（用户最可能看的行先核）；同档不重复入队；
+ *  已有拍 ⇒ 并入待核集（不重复点火）。 */
+export function scheduleVerify(cwd, scanned, digests = {}) {
+  const targets = scanned.filter((s) => needsVerify(digests?.[s.slot], s.mtime)).sort((a, b) => b.mtime - a.mtime)
+  if (targets.length === 0) return
+  let prefix
+  try { prefix = sessionPath(cwd) } catch { return } // 前缀不可解析 ⇒ 不排
+  const list = pending.get(cwd) ?? new Set()
+  for (const s of targets) list.add(s.slot)
+  pending.set(cwd, list)
+  if (timers.has(cwd)) return
+  const t = setTimeout(() => { timers.delete(cwd); runPass(cwd, prefix).catch(() => { /* 静默：下轮重核 */ }) }, verifyDelayMs)
+  t.unref?.() // 不持活（进程退出随终止）
+  timers.set(cwd, t)
+}
+
+/** 一轮核实（拍点火）：捕获前缀校验（目录切换 ⇒ 弃轮——零跨根写）→ 逐档（mtime 降序）分块流式核实 →
+ *  尾部一次合并写（仅摘要条目）。 */
+async function runPass(cwd, prefix) {
+  const slots = pending.get(cwd)
+  pending.delete(cwd)
+  if (!slots || running.has(cwd)) return // 单飞：在飞即返（余档留待下次列表调用）
+  if (sessionPath(cwd) !== prefix) return
+  running.add(cwd)
+  _verifyState.ticks += 1
+  try {
+    const results = new Map() // slot → { meta, mtime }（meta 不含 ts——ts 写回时打点）
+    let budget = SCAN_BUDGET_BYTES
+    let oversizeTaken = false
+    for (const slot of slots) {
+      let st
+      try { st = statSync(slotPath(cwd, slot)) } catch { _verifyState.skipped += 1; continue } // 不在盘 ⇒ 跳
+      if (failedCache.get(cwd)?.get(slot) === st.mtimeMs) { _verifyState.skipped += 1; continue } // 负缓存
+      if (st.size > SCAN_BUDGET_BYTES) {
+        if (oversizeTaken) continue // 超预算大档该轮至多一档
+        oversizeTaken = true
+      } else if (st.size > budget) continue // 余量不足 ⇒ 留待下次列表调用
+      const meta = await scanOne(slotPath(cwd, slot), st.size, cwd)
+      budget = Math.max(0, budget - st.size)
+      if (meta) { results.set(slot, { meta, mtime: st.mtimeMs }); continue }
+      _verifyState.failed += 1 // 门不过 ⇒ 负缓存（不发明摘要）
+      const neg = failedCache.get(cwd) ?? new Map()
+      neg.set(slot, st.mtimeMs)
+      failedCache.set(cwd, neg)
+    }
+    // 回写：尾部一次合并写——仅摘要条目；写回前再校验捕获前缀（零跨根写）
+    if (results.size > 0 && sessionPath(cwd) === prefix) {
+      const m = loadManifest(cwd)
+      m.slots ??= {}
+      // `ts` 地板 = 该档 mtime（平台文件时间戳可领先 `Date.now()` 数 ms——延迟盖章）：无地板则刚核完的档被判「陈旧」再读；判据比较（`ts ≥ mtime`）零改。
+      for (const [slot, r] of results) m.slots[slot] = { ts: Math.max(Date.now(), r.mtime), ...r.meta }
+      if (saveManifest(cwd, m) !== false) _verifyState.verified += results.size // 拒写（边界 ⑩）不计
+    }
+  } finally {
+    running.delete(cwd)
+  }
+}
+
+/** 可等待句柄（判据句 3 缝）：「无 pending 拍 ∧ 无在飞轮」即决。 */
+export async function _verifyIdle() {
+  while (pending.size > 0 || running.size > 0) await yieldToLoop()
+}
+
+/** 复位（用例跨例隔离）：清 pending 拍 + 在飞登记 + 负缓存 + 观测计数。 */
+export function _resetVerifyStateForTest() {
+  for (const t of timers.values()) clearTimeout(t)
+  timers.clear(); pending.clear(); running.clear(); failedCache.clear()
+  for (const k of Object.keys(_verifyState)) _verifyState[k] = 0
+}
+
+/** 单档分块流式核实：1 MiB 分块读 + 逐块让出；返回摘要字段（不含 `ts`）或 `null`（门不过）。 */
+async function scanOne(path, size, cwd) {
+  const buf = Buffer.allocUnsafe(VERIFY_CHUNK_BYTES)
+  const dec = new TextDecoder("utf-8") // 流式解码：多字节字符跨块不劈
+  const scan = new StreamScan()
+  let fd
+  try { fd = openSync(path, "r") } catch { return null } // 打开失败（并发删除等）⇒ 门不过（负缓存）
+  try {
+    let pos = 0
+    while (pos < size) { // 读到文件末（`done` 后仍读——尾随非空白等于坏 JSON，见 `feed` / `result`）
+      const n = readSync(fd, buf, 0, Math.min(VERIFY_CHUNK_BYTES, size - pos), pos)
+      if (n <= 0) break // 截断（读不到声明长度）⇒ 门不过
+      pos += n
+      _verifyState.chunks += 1
+      _verifyState.bytes += n
+      scan.feed(dec.decode(buf.subarray(0, n), { stream: true }))
+      await yieldToLoop() // 逐块宏任务让出（零 ≥50 ms 连续同步段）
+    }
+    // EOF 尾段冲洗（#499）：流式解码器在文件末滞留的**不完整 UTF-8 序列**（≤3 字节）不冲洗就
+    // 丢失——坏档尾段会逃过「尾随非空白 = 坏 JSON」门；无参 `decode()` 收尾 ⇒ 残缺字节出 U+FFFD
+    // ⇒ 按坏档门不过（完整多字节字符照常解码，零影响）。
+    scan.feed(dec.decode())
+  } catch {
+    return null // 读失败 ⇒ 门不过（负缓存）
+  } finally {
+    try { closeSync(fd) } catch { /* 关闭失败不影响读结果 */ }
+  }
+  return scan.result(cwd)
+}
+
+/** 跨块流式结构扫描器（判据句 3）：顶层键取值 + `history` 逐元素定界计数；**消费段即时丢弃**（内存 =
+ *  未完成 token）；零正则、零整档物化。**严格 JSON**（容器分隔态 `sep`；结构违规 ⇒ `corrupt()`）。
+ *  st：key → value → after ∨ item（history 内）；sep：start 首元素位 / need 刚吃 `,` / after 刚完一元素；
+ *  k：跳跃态（1 串 / 2 结构 / 3 标量 / null 无）、p 跳跃位置（buf 内）、d 深度、inStr / esc 串与转义态
+ *  （跨块保留——续扫不重扫）；cursor = 已消费位置（在飞值时 = 值起点）；open = 顶层 `{` 未取。 */
+class StreamScan {
+  constructor() {
+    this.buf = ""; this.cursor = 0; this.st = "key"; this.open = true; this.sep = "start"; this.key = null
+    this.k = null; this.p = 0; this.d = 0; this.inStr = false; this.esc = false
+    this.count = 0; this.turns = 0; this.first = null; this.head = {}
+    this.historySeen = false; this.done = false; this.bad = false
+  }
+  /** 喂入一块文本（终结后只许空白——尾随非空白 = 坏 JSON，判据句 3 门面）。 */
+  feed(text) {
+    if (this.done) { if (!isBlank(text)) this.bad = true; return }
+    if (this.cursor > 0) {
+      this.buf = this.buf.slice(this.cursor)
+      if (this.k !== null) this.p -= this.cursor
+      this.cursor = 0
+    }
+    this.buf += text
+    while (this.done === false) {
+      const next = this.step(this.buf, this.cursor)
+      if (next === null) break // 请示更多输入（不完整 token——含坏档停滞）
+      this.cursor = next
+    }
+  }
+  /** 单步（返回新位置 / `null` = 请示更多输入）；结构违规 ⇒ `corrupt()`（门不过）。 */
+  step(b, i) {
+    const n = b.length
+    while (i < n && isWs(b[i])) i++
+    if (this.st === "key") {
+      if (i >= n) return null
+      const c = b[i]
+      if (this.open) { // 顶层 `{`（首字符）
+        if (c !== "{") return this.corrupt()
+        this.open = false
+        return i + 1
+      }
+      if (c === "}") { if (this.sep === "need") return this.corrupt(); this.done = true; return i + 1 } // 尾逗号 ⇒ 违规
+      if (c !== '"') return this.corrupt() // 空键位 / 双逗号 / 非串键
+      const end = this.jump(b, i)
+      if (end === null) return null
+      try { this.key = JSON.parse(b.slice(i, end)) } catch { return this.corrupt() }
+      if (!isStr(this.key)) return this.corrupt()
+      let k = end
+      while (k < n && isWs(b[k])) k++
+      if (k >= n) return null // 冒号未到（键重扫——键短，零成本）
+      if (b[k] !== ":") return this.corrupt()
+      this.st = "value"
+      return k + 1
+    }
+    if (this.st === "value") {
+      if (i >= n) return null
+      const c = b[i]
+      if (this.key === "history") { // history 非数组 ⇒ 内容面不可用（门不过）
+        if (c !== "[") return this.corrupt()
+        this.historySeen = true
+        this.sep = "start"
+        this.st = "item"
+        return i + 1
+      }
+      const end = this.jump(b, i)
+      if (end === null) return null
+      if (end <= i) return this.corrupt() // 空值（无进展）⇒ 结构违规（防死循环）
+      if (HEAD_KEYS.has(this.key) && c !== "{" && c !== "[") {
+        try { this.head[this.key] = JSON.parse(b.slice(i, end)) } catch { return this.corrupt() }
+      }
+      this.st = "after"
+      return end
+    }
+    if (this.st === "after") { // 顶层：刚完一值 ⇒ 须是 `,` 或 `}`
+      if (i >= n) return null
+      if (b[i] === ",") { this.sep = "need"; this.st = "key"; return i + 1 }
+      if (b[i] === "}") { this.done = true; return i + 1 }
+      return this.corrupt()
+    }
+    // item：history 数组内（元素结构定界——逐元素切片解析）
+    if (i >= n) return null
+    const c = b[i]
+    if (c === "]") { if (this.sep === "need") return this.corrupt(); this.st = "after"; return i + 1 } // 尾逗号
+    if (c === ",") { if (this.sep !== "after") return this.corrupt(); this.sep = "need"; return i + 1 }
+    if (this.sep === "after") return this.corrupt() // 缺分隔符
+    const end = this.jump(b, i) // 值闭界（不完整 ⇒ 留值文本于 buf，续扫）
+    if (end === null) return null
+    if (end <= i) return this.corrupt() // 空值元素（无进展）⇒ 结构违规（防死循环）
+    this.sep = "after"
+    this.count += 1 // messageCount = history.length（逐元素计数——含非对象元素）
+    if (c === "{") {
+      let m
+      try { m = JSON.parse(b.slice(i, end)) } catch { return this.corrupt() }
+      if (isRealUserMsg(m)) {
+        this.turns += 1 // turnCount = 真实用户消息数（谓词单源 = history-window.mjs）
+        if (this.first === null) this.first = m.content.slice(0, 80)
+      }
+    }
+    return end
+  }
+  /** 跨块可续的值跳跃（「字符串 / 转义跨块续读」）：自 `i` 跳到值末（回值后一位）；输入不足 ⇒ `null`
+   *  （**状态保留**——下次自 `this.p` 续扫，每字符只扫一次）；标量**不吃分隔符**（切片 `[i, end)`）。 */
+  jump(b, i) {
+    if (this.k === null) {
+      const c = b[i]
+      if (c === undefined) return null
+      if (c === '"') { this.k = 1; this.p = i + 1; this.esc = false }
+      else if (c === "{" || c === "[") { this.k = 2; this.p = i + 1; this.d = 1; this.inStr = false; this.esc = false }
+      else { this.k = 3; this.p = i }
+    }
+    let j = this.p
+    if (this.k === 1) {
+      while (j < b.length) {
+        const c = b[j]
+        if (this.esc) { this.esc = false; j++; continue }
+        if (c === "\\") { this.esc = true; j++; continue }
+        if (c === '"') { this.k = null; return j + 1 }
+        j++
+      }
+    } else if (this.k === 2) {
+      while (j < b.length) {
+        const c = b[j]
+        if (this.inStr) {
+          if (this.esc) this.esc = false
+          else if (c === "\\") this.esc = true
+          else if (c === '"') this.inStr = false
+        } else if (c === '"') this.inStr = true
+        else if (c === "{" || c === "[") this.d += 1
+        else if ((c === "}" || c === "]") && --this.d === 0) { this.k = null; return j + 1 }
+        j++
+      }
+    } else {
+      while (j < b.length && !isDelim(b[j])) j++
+      if (j < b.length) { this.k = null; return j } // 标量末（不吃分隔符）
+    }
+    this.p = j // 输入不足 ⇒ 记位置续扫（触底 = 可能截断）
+    return null
+  }
+  corrupt() { this.bad = true; this.done = true; return null }
+  /** 校验门 + 摘要字段：结构完整（顶层配平 ∧ 见 `history` 数组）∧ `version ∈ {1,2}` ∧ cwd 一致（缺键 =
+   *  本档）⇒ 字段（不含 `ts`）；否则 `null`（不发明摘要）。字段缺省与 `slotDigest` / `extractSlotMeta`
+   *  逐条同口径（单源判据 = 用例强制逐字段相等）。 */
+  result(cwd) {
+    if (this.bad || !this.done || !this.historySeen) return null
+    if (!isBlank(this.buf.slice(this.cursor))) return null // 顶层配平后非空白残留（未过 `feed` 的那段）⇒ 门不过
+    if (this.head.version !== 1 && this.head.version !== 2) return null
+    const fc = this.head.cwd
+    if (isStr(fc) && fc.toLowerCase() !== cwd.toLowerCase()) return null
+    const meta = {
+      messageCount: this.count, turnCount: this.turns, firstMessage: this.first ?? "",
+      activeProvider: this.head.activeProvider ?? "", updatedAt: this.head.updatedAt ?? Date.now(),
+      title: this.head.title ?? "",
+    }
+    if (this.head.activeModel) meta.activeModel = this.head.activeModel
+    if (this.head.createdBy) meta.createdBy = this.head.createdBy
+    return meta
+  }
+}