@thincoder/core 0.9.4 → 0.10.1

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

package/session-slot-write.mjs

@@ -1,6 +1,7 @@
 /**
  * session-slot-write.mjs — 会话槽「元数据开关」写面（Parnas 边界：开关写决策组——
- * autoApprove / planMode / engineering / advisor guard，外加全新槽默认记录与落盘单点）。
+ * autoApprove / planMode / engineering / advisor guard / 会话级偏好三键
+ * （provider / model / effort——§6.21），外加全新槽默认记录与落盘单点）。
  *
  * 归属：会话数据面（同上位 `session.mjs` / `session-slots.mjs` / `session-store.mjs`）。
  * 本档 = **（cwd, slot）形态**的槽写入面（读-改-写）；另一形态 = `session.mjs` 的
@@ -23,10 +24,14 @@
 
 import { existsSync, readFileSync, renameSync, statSync } from "node:fs"
 
-import { getSessionId, loadManifest, saveManifest, slotDigest, slotPath, writeSessionFile } from "./session-slots.mjs"
-import { loadSlotFile } from "./session.mjs"
+import { getSessionId, loadManifest, saveManifest, slotDigest, slotPath, writeSessionFile, sessionEnd } from "./session-slots.mjs"
+import { loadSlotFile, isLegacyTransient } from "./session.mjs"
 // token 形态单源（格式校验 + 到期时刻）——本档的保存面合并规则复用同一判定。
 import { tokenExpiryMs } from "./token-ttl.mjs"
+// 会话级偏好写面（§6.21 判据句 3）的判据单源——档位值域（`specForModel(...).reasoningEffortEnum`）
+// 与 off 可达性（`thinkOffPath`）；两叶档（零 import）⇒ 不涉环，核内零第二份族别 / 枚举表。
+import { specForModel } from "./model-specs.mjs"
+import { thinkOffPath } from "./think-off.mjs"
 
 /** mtime 缓存（键 = 槽文件路径 → 上次所见 mtimeMs）：同一槽连写时跳过重复解析。
  *  测试复位缝（与 `_setSessionsDirForTest` 同款）：缓存为进程级单例，用例间需可复位
@@ -34,13 +39,17 @@ import { tokenExpiryMs } from "./token-ttl.mjs"
 const slotMtimeCache = new Map()
 export function _resetSlotMtimeCacheForTest() { slotMtimeCache.clear() }
 
-/** Fresh slot data default：全新空槽的规范结构（`newSession` 写盘面同形）。 */
+/** Fresh slot data default：全新空槽的规范结构（`newSession` 写盘面**同源**——SLOT-END-PARAM
+ *  批起 `newSession` 与本构造器单源；`effort: null` = 会话级档位未设态——§6.21 判据句 5 规范
+ *  结构同源；老槽无该键由读侧按 `null` 容忍）。首物化即记创建端（§6.20 判据句 4 写面：本端
+ *  物化者 = 进程端名；「禁回填」不适用——本构造器只产全新槽）。 */
 export function newSlotData(cwd) {
   return {
     version: 2, cwd, title: "", updatedAt: Date.now(),
     history: [], contextHistory: [], tasks: [],
-    planMode: false, goal: null, autoApprove: false, advisor: null,
+    planMode: false, goal: null, autoApprove: false, advisor: null, effort: null,
     pendingReminders: [], sessionStart: null,
+    createdBy: sessionEnd(),
   }
 }
 
@@ -62,8 +71,11 @@ function rotateIfForeign(p, slot, data) {
       disk.cwd.toLowerCase() !== data.cwd.toLowerCase()
     const diskStart = disk?.sessionStart ?? null
     const myStart = data?.sessionStart ?? null
+    // 盘面长度与快照**同口径**（#441①）：快照 `data` 来自读槽回放（`loadSlotFile` 已按
+    // `isLegacyTransient` 过滤，`session.mjs` 读面）⇒ 盘侧同滤——否则坏档里的 legacy 注入
+    // 条目会凭空把盘面算长，无并发追加也误判轮转（.bak 白产 + 误报 concurrent append）。
     const diskLonger = Array.isArray(disk?.history) && Array.isArray(data?.history) &&
-      disk.history.length > data.history.length
+      disk.history.filter((m) => !isLegacyTransient(m)).length > data.history.length
     if (!(diskIsNewer || diskForeign || (diskStart && diskStart !== myStart) || diskLonger)) return null
     const bak = `${p}.bak-${Date.now()}`
     renameSync(p, bak)
@@ -84,16 +96,24 @@ function rotateIfForeign(p, slot, data) {
 /**
  * 槽落盘单点（读-改-写面共用）：轮转判定 → 写槽文件 → 回写 manifest 摘要。
  * 返回轮转出的 `.bak` 路径或 null（调用方按需透出）。
+ *
+ * 创建端（SLOT-END-PARAM 批 §6.20 判据句 4 写面）：入参无 `createdBy` **且**槽文件不在盘
+ * （**轮转后**判据——`rotateIfForeign` 已让位现场）⇒ 本端即将首物化 ⇒ 落进程端名；
+ * 文件在盘（含老槽无键）⇒ 不动（禁回填）。
  */
 export function saveSlotData(cwd, slot, data) {
   data.updatedAt = Date.now()
   const p = slotPath(cwd, slot)
   const rotated = rotateIfForeign(p, slot, data)
+  if (data.createdBy === undefined && !existsSync(p)) data.createdBy = sessionEnd()
   writeSessionFile(p, data)
-  slotMtimeCache.set(p, (() => { try { return statSync(p).mtimeMs } catch { return 0 } })())
+  // 写后取 mtime 单次采集（读失败 ⇒ `0` = 不可得）：缓存（本档路径键）+ 摘要 `ts` 地板入参
+  // （#503——保存面写后取 mtime，同族先例 `session-slot-verify.mjs:99`）。
+  const wroteMtime = (() => { try { return statSync(p).mtimeMs } catch { return 0 } })()
+  slotMtimeCache.set(p, wroteMtime)
   try {
     const m = loadManifest(cwd)
-    m.slots[slot] = slotDigest(data)
+    m.slots[slot] = slotDigest(data, wroteMtime)
     saveManifest(cwd, m)
   } catch { /* 摘要失败非致命——数据已安全，元数据下次 listSlots 惰性恢复 */ }
   return rotated
@@ -166,3 +186,49 @@ export function mergeEngTokensForSave(incoming, existing) {
   }
   return out
 }
+
+/** 会话级偏好（§6.21）键闭集——表外键 = 整 patch 拒（写未发生）。 */
+const SLOT_PREF_KEYS = new Set(["provider", "model", "effort"])
+
+/**
+ * 会话级档位归一（§6.21 判据句 3——纯函数、不抛）：`level` → 槽 `effort` 值。
+ *  - `null` / `undefined` / `"auto"` ⇒ `null`（未设 ⇒ 回落配置面 / 渠道默认）；
+ *  - `"off"` ⇒ 该模型**有 off 路径**（判据单源 = `thinkOffPath`，勿在本档重写族别判定）
+ *    ⇒ `"off"`、否则 `null`；
+ *  - 其余 ⇒ 逐模型枚举（单源 = `specForModel(model).reasoningEffortEnum`）含之 ⇒ 原字面、
+ *    不含 / 无枚举 ⇒ `null`。
+ *  `model` 非串（外端脏载 / 手工档）⇒ 按**未登记**归一（`DEFAULT_SPEC` 径）——「不抛」契约。
+ *  写面归一只此一处；读侧另容忍表外串（applySession 边界表——不设，不静默改写）。
+ */
+export function resolveEffortPatch(level, model) {
+  if (level == null || level === "auto") return null
+  const spec = specForModel(typeof model === "string" ? model : "")
+  if (level === "off") return thinkOffPath(spec) ? "off" : null
+  return (spec?.reasoningEffortEnum ?? []).includes(level) ? level : null
+}
+
+/**
+ * 会话级偏好写出口（§6.21 判据句 2——沿 `setSlotAutoApprove` 同形，复用 `writeFlag` 单点）：
+ * `patch` 键闭集 = `provider` / `model` / `effort`，**至少一键**（零键 / 表外键 ⇒ `false`，写未
+ * 发生）；槽不可读 ⇒ `false`。`provider` / `model` 键入参映射既有槽字段 `activeProvider` /
+ * `activeModel`（不新增字段；`null` = 缺键语义——`provider` / `model` 无「未设」态）；`effort` 经
+ * `resolveEffortPatch` 归一（`model` 取 `patch.model ?? 槽现值 activeModel`），归一 `null` = 未设
+ * （回落配置面 / 渠道默认）——**值置 `null` 不删键**（与 `newSlotData` 规范结构同源）。
+ * 只写盘：不碰当前内存态（施加面唯一 = `applySession`——§6.21 判据句 4 / 边界表第 5 行）。
+ *
+ * **值域面（#441② 明文——核侧有意不校）**：本出口只校**键闭集**，**不校值域**——`provider` /
+ * `model` 传 `null`（或表外字面）按**缺键语义**零改（不报错；`null` 仅对 `effort` 有「未设」
+ * 语义）；值域名（`null` 仅 `effort` + `provider` / `model` 非空）由**端侧契约**把守
+ * （桌面 IPC「会话级偏好注」；端侧拒例 = `thincoder-desktop/src/main/agent-host.mjs`
+ * `prefsPatchFailure`）——读侧容忍为有意（跨端 / 手工改写档零行为变更），核内不立第二份值域校验。
+ */
+export function setSlotPrefs(cwd, slot, patch) {
+  if (!patch || typeof patch !== "object" || Array.isArray(patch)) return false
+  const keys = Object.keys(patch)
+  if (keys.length === 0 || keys.some((k) => !SLOT_PREF_KEYS.has(k))) return false
+  return writeFlag(cwd, slot, (d) => {
+    if (patch.provider != null) d.activeProvider = patch.provider
+    if (patch.model != null) d.activeModel = patch.model
+    if ("effort" in patch) d.effort = resolveEffortPatch(patch.effort, patch.model ?? d.activeModel)
+  })
+}