@thincoder/core 0.9.4 → 0.10.1

package/session-slot-claims.mjs

@@ -0,0 +1,230 @@
+/**
+ * session-slot-claims.mjs — 认领面族（2026-09-28 拆分批 · R3——自 `session-slots-manifest.mjs`
+ * （421 > 300）外提认领面：`staleClaims` ∕ owner 三件（`ownerPid` / `ownerPids` /
+ * `ownerStateOf`）∕ `cleanDeadOwners` ∕ `ensureActive` ∕ `allocateFresh` ∕ `claimSlot` ∕
+ * `_releaseStats` ∕ `releaseClaimsAll` ∕ `activeSlot`；**逐字迁移**、零行为改——台账 #484
+ * 「认领面族拆分」顺延项落形）。
+ * 原档（`session-slots-manifest.mjs`）保留摘要 / 清单读写 / 属主健康面，并 re-export 本档
+ * 导出保既有 import 面（消费档路径与名面不动）。
+ *
+ * 静态环（与既有的 session.mjs ↔ session-slots.mjs 同形）：本档引 `session-slots.mjs` 的存储
+ * 原语（`getSessionId` / `manifestPath` / `slotPath`）与 `session-slots-manifest.mjs` 的清单
+ * 读写（`loadManifest` / `saveManifest`），后者反向 re-export 本档导出——函数声明在实例化期
+ * 已初始化、双方只在函数体内运行时使用（模块求值期零顶层调用 ⇒ 环安全）。
+ * 探测纪律（init-block 批 · F-MI7 / SESSION.md §6.2）：本档**零自有 exec、零逐 pid 探测**——
+ * 只消费调用面传入的**探测束**（`bundle`）；属主三态判据单源 = `process-probe.mjs`，
+ * `unknown`（探测失败 / 缺行）⇒ 不认领 / 不判死 / 不删（D-MI10）。
+ */
+import { existsSync } from "node:fs"
+// 探测束（判活）+ 属主三态判据 / 死主判定（本档零自有 exec——判据面与探测面分离）。
+import { probeOwnersSync, ownerState, filterDeadOwners } from "./process-probe.mjs"
+// 存储原语（路径 / 原子写 / 进程 sessionId）——静态环见头注。
+import { getSessionId, manifestPath, slotPath } from "./session-slots.mjs"
+// 清单读写（落盘单源住原档——静态环见头注；反向 re-export 保 import 面）。
+import { loadManifest, saveManifest } from "./session-slots-manifest.mjs"
+
+/** 本进程**残留认领集**（F-CR1 释放谓词 —— **判据单源** · SESSION.md §6.2 / §6.16）：
+ *  「释放 A ⟺ `slotSessions[A]` 为本进程 ∧ `A ∉ 保留集`」。`keep` = 保留集 = 落点槽 ∪ 本进程
+ *  其余活绑定槽（单绑定落点 ⇒ `{落点槽}`；被占落点 ⇒ 空集）。返回槽号（**字符串键**形态）。 */
+export function staleClaims(src, keep = []) {
+  const keepSet = new Set((keep ?? []).filter((s) => s != null).map(Number))
+  const mySessionId = getSessionId()
+  return Object.entries(src?.slotSessions ?? {})
+    .filter(([slot, owner]) => owner === mySessionId && !keepSet.has(Number(slot)))
+    .map(([slot]) => slot)
+}
+
+/** 属主串 → pid（`"pid-ts-rand"`——`owner.split("-")[0]` 格式判据单源：session-slots ↔
+ *  session-lifecycle 共用，防两处漂移）。不可解析 ⇒ NaN——判据层按 dead 处理
+ *  （见 process-probe `ownerState`）。 */
+export function ownerPid(owner) { return parseInt(owner.split("-")[0]) }
+
+/** manifest 属主 pid 全量清单（**非本进程**——束入参：一次探测覆盖所有待判 pid；
+ *  空清单 ⇒ 探测面零 exec 早退）。`exclude` 缺省 = 本进程 sessionId。 */
+export function ownerPids(m, exclude = getSessionId()) {
+  const pids = []
+  for (const owner of Object.values(m.slotSessions ?? {})) {
+    if (!owner || owner === exclude) continue
+    const pid = ownerPid(owner)
+    if (pid) pids.push(pid)
+  }
+  return pids
+}
+
+/** 束 → 属主三态（判据单源 = process-probe `ownerState`；束缺失 / 探测失败 ⇒ "unknown"——
+ *  保守保留，**不得**当全死）。 */
+export function ownerStateOf(owner, bundle) {
+  const pid = ownerPid(owner)
+  return ownerState(pid, { aliveSet: bundle?.aliveSet ?? null, cmds: bundle?.cmds ?? null })
+}
+
+/** 束 → `filterDeadOwners` 入参（清理面 API 保面——三态 `alive`：无束 / 失败 ⇒ undefined = 未知）。 */
+function ownerArgs(owner, bundle) {
+  const pid = ownerPid(owner)
+  const aliveSet = bundle?.aliveSet ?? null
+  return [pid, { alive: aliveSet ? aliveSet.has(pid) : undefined, cmdline: bundle?.cmds?.get?.(pid) }]
+}
+
+/** 死主条目清理（2026-08-31 会诊 F4 + 2026-09-01 会诊 deepseek/kimi 🔴 语义原样抽取——
+ *  ensureActive/resumeSlot 共用）：删除 owner 进程已死的 slotSessions 条目。死主判定必须跑
+ *  判据（不能以"文件缺失"短路——活进程在"认领 → 首次保存"窗口文件暂缺，误删会
+ *  致双进程同槽），但**不自行探测**：判活 / 命令行来自调用面同一探测束（F-MI7——
+ *  零逐 pid exec）。返回 deletions 计算函数（调用时按 m 当前状态过滤刚重新认领的槽——防删
+ *  掉自己的新属主），无清理返回 null。删除须经 saveManifest 的 deletions 显式落盘——条目级
+ *  合并会把磁盘死条目从 fresh 复活回写（N1 + 会诊 🔴）。
+ *
+ * 身份复核（批 1 · F-MI6 / D-MI11——判据单源 `filterDeadOwners`）：pid 活 + 命令行**明确
+ *  可得且非本产品** ⇒ 同判可删（pid 复用即此场景）；探测失败 / 缺行 ⇒ 保守保留（D-MI10）。 */
+export function cleanDeadOwners(m, bundle) {
+  const mySessionId = getSessionId()
+  const entries = Object.entries(m.slotSessions).filter(([, o]) => o && o !== mySessionId)
+  const deadSlots = []
+  for (const [slot, owner] of entries) {
+    const [pid, args] = ownerArgs(owner, bundle)
+    if (filterDeadOwners(pid, args)) {
+      delete m.slotSessions[slot]
+      deadSlots.push(slot)
+    }
+  }
+  return deadSlots.length === 0 ? null : () => ({ slotSessions: deadSlots.filter((s) => m.slotSessions[s] !== mySessionId) })
+}
+
+/**
+ * Claim a slot for this process and set it as active. Idempotent.
+ * Preference order:
+ *  1. The current active slot, if it is unowned / ours / its owner is dead — reuse it.
+ *  2. Any slot that is unowned or owned by a dead process (reclaim).  → allocateFresh
+ *  3. A brand-new slot when all are owned by live processes.          → allocateFresh
+ * The owner is recorded in m.slotSessions so other processes (CLI ↔ VS Code) can
+ * see which slots are taken and avoid them.
+ *
+ * F-MI7（同步例外收窄）：粘性早退（已拥有 active）**零探测**（无束、无 exec）；
+ * 冷路径 = 一次有界同步束（`probeOwnersSync`）——清理 / 占用 / 空闲全部查表。
+ */
+function ensureActive(cwd, m) {
+  const mySessionId = getSessionId()
+  if (!m.slotSessions) m.slotSessions = {}
+
+  // Already own the active slot — nothing to do. 粘性早退：**零探测**（死项清理交给
+  // 非粘性路径——resumeSlot 每次进程入口的异步束 / 冷路径同步束都会清并落盘）。
+  if (m.active && m.slotSessions[m.active] === mySessionId) return
+
+  // 冷路径：入口一次有界同步束（每 exec ≤ SYNC_PROBE_MS）覆盖全量属主 pid。
+  const bundle = probeOwnersSync(ownerPids(m))
+  const deadParam = cleanDeadOwners(m, bundle)
+
+  const isFree = (slot) => {
+    const owner = m.slotSessions[slot]
+    if (!owner || owner === mySessionId) return true
+    // 未知（探测失败 / 缺行）⇒ 不认为是空闲（不认领——D-MI10）
+    return ownerStateOf(owner, bundle) === "dead"
+  }
+
+  // 1. Prefer the current active slot if we can take it (preserves "resume where you left off").
+  if (m.active && m.slots[m.active] && isFree(m.active)) {
+    m.slotSessions[m.active] = mySessionId
+    saveManifest(cwd, m, deadParam?.() ?? null, { setActive: true })
+    return
+  }
+
+  // 2/3. 分支 2/3 已抽取为 allocateFresh（2026-09-05 §6.10 D-2——resumeSlot 全新分配复用）。
+  allocateFresh(cwd, m, deadParam, bundle)
+}
+
+/**
+ * Allocate a slot with ensureActive 分支 2/3 语义（2026-09-05 §6.10 D-2 抽取——resumeSlot
+ * 步骤③"其余一切 → 全新分配"复用；与 newSession 选号语义对齐）：
+ *  2. Reclaim a manifest slot whose FILE does not exist (never held a session)；
+ *  3. A brand-new slot when none is free / all numbers are taken.
+ * 记录所有权 + active 指针（setActive）并落盘。返回分配的槽号。
+ * F-MI7：占用 / 空闲判据全部查**调用面束**（`bundle`——零自有探测）；缺省 null ⇒
+ * 全部属主按 unknown 论（只可能取全新号——保守，不认领陌生人）。
+ */
+export function allocateFresh(cwd, m, deadParam = null, bundle = null) {
+  const mySessionId = getSessionId()
+  if (!m.slotSessions) m.slotSessions = {}
+  const isFree = (slot) => {
+    const owner = m.slotSessions[slot]
+    if (!owner || owner === mySessionId) return true
+    return ownerStateOf(owner, bundle) === "dead" // 未知 ⇒ 非空闲（不认领——D-MI10）
+  }
+
+  // 2. Reclaim a slot whose FILE does not exist (never held a session). 2026-08-31 会诊 F4：
+  //    原实现认领"编号最小的空闲 slot"——死主的旧 slot 文件仍在，新进程会 resume 进
+  //    陌生会话（"会话乱了"实锤）且退出时覆盖它。只有文件缺失的空 slot 才允许回收。
+  const allSlots = Object.keys(m.slots).filter((n) => /^\d+$/.test(n)).map(Number).sort((a, b) => a - b)
+  for (const slot of allSlots) {
+    if (isFree(slot) && !existsSync(slotPath(cwd, slot))) {
+      m.active = slot
+      m.slotSessions[slot] = mySessionId
+      saveManifest(cwd, m, deadParam?.() ?? null, { setActive: true })
+      return slot
+    }
+  }
+
+  // 3. All slots owned by live processes — allocate a new one (no limit).
+  // 2026-08-31 advisor round2 🟡：新号从 max+1 起逐号跳过"已被活进程认领但尚未落盘"
+  // 的号（认领→首次保存窗口：slotSessions 有条目、m.slots 无条目、文件不存在——
+  // 仅凭 m.slots/existsSync 查不到 → 双进程认领同一号 → 同槽双写/互旋）。
+  // 2026-09-01 会诊 kimi 🟡：同时跳过文件仍存在的号（与 newSession 对齐）——manifest
+  // 条目丢失/损坏时 max+1 会撞上孤儿槽文件 → F2 把真会话轮转成不可见的 .bak。
+  // 另：allSlots 已升序，取 max 用 allSlots[allSlots.length-1]（数万槽位时 Math.max
+  // spread 有 RangeError 风险）。
+  const liveClaimed = (n) => {
+    const owner = m.slotSessions?.[n]
+    if (!owner || owner === mySessionId) return false
+    return ownerStateOf(owner, bundle) !== "dead" // 活 / 未知 ⇒ 视为已占（跳号——保守）
+  }
+  let newSlot = allSlots.length > 0 ? allSlots[allSlots.length - 1] + 1 : 1
+  while (liveClaimed(newSlot) || existsSync(slotPath(cwd, newSlot))) newSlot++
+  m.active = newSlot
+  m.slotSessions[newSlot] = mySessionId
+  saveManifest(cwd, m, deadParam?.() ?? null, { setActive: true })
+  return newSlot
+}
+
+/** 认领指定槽为本进程所有并置为 active（2026-09-05 §6.10 D-2 resumeSlot 认领路径——调用方
+ *  已按"属主 空/死/本进程"判据校验可用性；幂等）。manifest active 保留为共享指针（D-6：
+ *  旧版端/ACP 恢复依据 + 无记录端一次性继承源 + 列表回退高亮——不再作本端恢复第一依据）。
+ *  deadParam 在写入所有权之后求值（防 deletions 删掉本调用刚认领的槽——ensureActive
+ *  deadParam 同型过滤）。
+ *  F-CR1（2026-09-21 · SESSION-CLAIM 批）：认领落点释放本进程残留认领（保留集 = {认领槽}——
+ *  §6.2 公式代入）；本函数 = 启动恢复 / 本端恢复落点（核 `resumeSlot` 与 VSC 端壳
+ *  `resumeSlot` 共用），落盘判据（fresh 快照 / 值条件删除 / 内存移除）见 `saveManifest`。 */
+export function claimSlot(cwd, slot, m = loadManifest(cwd), deadParam = null) {
+  m.slotSessions ??= {}
+  m.slotSessions[slot] = getSessionId()
+  m.active = slot // 认领即翻共享指针（setActive 写 m.active——不更新则落快照旧值）
+  saveManifest(cwd, m, deadParam?.() ?? null, { setActive: true, release: [slot] })
+}
+
+/** 观测计数（测试缝——`_storeStats` / `_staleHooks` 同惯例）：`releaseClaimsAll` 调用计数。
+ *  端壳「工作区转空 ⇒ 旧 cwd 释放恰一次」类断言以此为桩计数（生产零消费）。 */
+export const _releaseStats = { calls: 0 }
+
+/** 退出全释放（EXIT-CLAIM-RELEASE 批 · F-XR1 · SESSION.md §6.18 D-SE41）：优雅退出前释放
+ *  本进程**全部**槽认领（保留集空——`staleClaims` 释放谓词单源）；落盘判据 = `saveManifest`
+ *  `opts.release` 三条自动继承（fresh 同次快照取释放集 / 值条件删除——他人窗口内新认领不误删 /
+ *  内存认领表同步移除）。**零触碰 marker 面**（F-XR2 路标保留——下次启动经 `usableSlot`
+ *  无属主短路零探测直达恢复）；崩溃路径不经此（信号无 JS 钩子——F-XR3）。
+ *  早退面：磁盘无 manifest ⇒ `existsSync` 单条目早退**零写**（不造盘面）；本进程无认领 ⇒
+ *  零写返回 false。失败容忍（F-XR1「退出恒达」）：整体 try/catch **永不抛出**，返回 boolean
+ *  （true = 有释放且落盘成功；false = 早退 / 失败 / **写面拒写**——`saveManifest` 返回值透传，
+ *  §6.23 判据句 3——断言面）；写失败盘面 = 认领残留 →
+ *  恢复走既有探测面（现状形态，数据零险）。 */
+export function releaseClaimsAll(cwd) {
+  _releaseStats.calls += 1
+  try {
+    if (!existsSync(manifestPath(cwd))) return false // 无 manifest ⇒ 零写（不造盘面）
+    const m = loadManifest(cwd)
+    if (staleClaims(m, []).length === 0) return false // 无本进程认领 ⇒ 零写（免白刷共享 sessionId）
+    return saveManifest(cwd, m, null, { release: [] }) !== false // 保留集空 = 全释放；不 setActive；返回值透传（§6.23 判据句 3——拒写 ⇒ false）
+  } catch { return false } // F-XR1：退出恒达（写失败 = 认领残留 → 恢复走探测面）
+}
+
+/** Return the active slot number for this process, claiming one if necessary */
+export function activeSlot(cwd) {
+  const m = loadManifest(cwd)
+  ensureActive(cwd, m)
+  return m.active
+}

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
+}