@thincoder/core 0.9.5 → 0.10.1

package/session-slots.mjs

@@ -7,9 +7,15 @@
  * ⇒ 按 `CORE-UNIFICATION.md` §2.8.1 表第 3 行**随批**外提清单 / 认领 / 属主面至
  * `session-slots-manifest.mjs`（语义原样迁移；本档 re-export 该档导出保既有 import 面——
  * 消费档 import 路径与名面不动）。本档保留 = 存储原语（cwd 哈希 / 路径 / 原子写 / 进程
- * sessionId）· 端记录（end marker）· 列表面（listSlots / loadSlotMeta）· 删槽 · 恢复决策面
+ * sessionId）· 端记录（end marker）· 列表面（listSlots——条目集 = 盘面实读；扫描面住
+ * `session-slot-scan.mjs`）· 删槽 · 恢复决策面
  * （usableSlot / loadLegacyFile / resumeSlot）。
  *
+ * 端名缝（SESSION.md §6.20 D-SE50 · 2026-09-25 SLOT-END-PARAM 批）：端名 = **进程内的单值
+ * 声明**（`setSessionEnd` / `sessionEnd`；`END` 仅模块级初值——CLI 零声明即得「cli」）。
+ * marker 家族三式与写 marker 的核入口逐函数带**显式端参**（缺省 = 进程端名）——端壳经绑定
+ * 转口传本端常量（`(cwd) => coreX(cwd, END)`），核内零端名分支；未列写点一律走进程端名。
+ *
  * 模型：每个项目（cwd hash）拥有无限编号 slot；manifest 记录 active 指针 + 每个
  * slot 的属主进程（slotSessions: slot → "pid-timestamp-random"，CLI ↔ VS Code
  * 共享 manifest 以互斥认领）。
@@ -39,12 +45,17 @@ import { probeOwnersAsync, isProcessAlive } from "./process-probe.mjs"
 // 清单 / 认领 / 属主面（init-block 批外提——双向静态环见头注）：本档 import 取用 + re-export
 // 保既有 import 面（消费档路径与名面不动）。
 import {
-  extractSlotMeta, loadManifest, saveManifest, ownerPids, ownerStateOf, cleanDeadOwners,
-  allocateFresh, claimSlot, activeSlot,
+  loadManifest, saveManifest, ownerPids, ownerStateOf, cleanDeadOwners,
+  allocateFresh, claimSlot, activeSlot, healDigest, slotMtime,
 } from "./session-slots-manifest.mjs"
+// 盘面扫描面（SESSION-LIST-DISK 批 §6.22）：条目集 = 盘面实读——枚举 / 早键截读 / 取数链装配住
+// 新档；本档 listSlots 收敛为组合 + 条目投影。静态环（本档 ↔ 扫描档；环安全见头注同形）。
+import { scanSlotMetas } from "./session-slot-scan.mjs"
+// 读面懒核实面（§6.25 判据句 3 落点 B——不可信清单调度：纯内存登记 + 启动窗外延迟拍）；静态环同形。
+import { scheduleVerify } from "./session-slot-verify.mjs"
 export {
   slotDigest, loadManifest, saveManifest, ownerPid, ownerPids,
-  allocateFresh, claimSlot, activeSlot,
+  allocateFresh, claimSlot, activeSlot, ledgerHealth,
 } from "./session-slots-manifest.mjs"
 
 let currentSessionId = null
@@ -85,7 +96,7 @@ export function sessionPath(cwd) {
 }
 
 export function slotPath(cwd, n) { return sessionPath(cwd) + "." + n }
-export function manifestPath(cwd) { return sessionPath(cwd) + ".manifest" }
+export function manifestPath(cwd) { return sessionPath(cwd) + ".manifest" } // 会话级槽索引——≠ 项目级 PROJECT-MANIFEST.json
 
 // ========== end marker（SESSION.md §6.10 端分离恢复——本端"最后使用槽位"记录）==========
 
@@ -93,16 +104,28 @@ export function manifestPath(cwd) { return sessionPath(cwd) + ".manifest" }
  *  （NF1：本端记录是本端单写者文件——不新增跨端共享可变字段）。 */
 export const END = "cli"
 
-/** 本端记录路径：{manifest}.{END}（manifest 旁的独立小文件，非内嵌字段——NF1）。 */
-export function endMarkerPath(cwd) { return `${manifestPath(cwd)}.${END}` }
+/** 进程端名（SESSION.md §6.20 判据句 1 / D-SE50）：端名 = **端进程内的单值声明**——
+ *  模块级 `_end`，初值 = `END`；端壳（VS Code / 桌面）模块求值期一次 `setSessionEnd(<端名>)`，
+ *  CLI 进程零声明即得「cli」。marker 家族三式与写 marker 的核入口**逐函数缺省取本值**
+ *  （显式端参优先）；端名单源 = 本对函数，核内零端名分支（端名是值不是分支）。 */
+let _end = END
+/** 声明本进程端名（端壳一次；核不校验端名——拼错 = 该端退化为「缺失」，§6.20 边界行 4）。 */
+export function setSessionEnd(end) { _end = end }
+/** 本进程端名（marker 家族缺省参的单源）。 */
+export function sessionEnd() { return _end }
+
+/** 本端记录路径：{manifest}.{end}（manifest 旁的独立小文件，非内嵌字段——NF1）。端参三式
+ *  （本式 + `readEndMarker` / `writeEndMarker`）缺省 = 本进程端名（§6.20 判据句 2——显式参 >
+ *  进程端名）；端壳经绑定转口传本端常量。 */
+export function endMarkerPath(cwd, end = sessionEnd()) { return `${manifestPath(cwd)}.${end}` }
 
 /** 读本端记录：返回 { slot: <number|null>, updatedAt } 或 null。三态语义（D-1）：
  *  文件缺失 = 从未记录（升级/首用迁移窗口——可能触发一次性继承）；
  *  JSON 解析失败/结构非法（损坏）= 按"缺失"降级——不 rename 不 unlink（幂等、不误伤，
  *  T-M13）；`slot: null` = 显式置空（删过本端记录槽——绝不触发继承，T-M4）。 */
-export function readEndMarker(cwd) {
+export function readEndMarker(cwd, end = sessionEnd()) {
   try {
-    const p = endMarkerPath(cwd)
+    const p = endMarkerPath(cwd, end)
     if (!existsSync(p)) return null
     const m = JSON.parse(readFileSync(p, "utf8"))
     if (m && m.slot === null) return { slot: null, updatedAt: m.updatedAt ?? null }
@@ -113,9 +136,9 @@ export function readEndMarker(cwd) {
 
 /** 写本端记录（原子 .tmp+rename，复用 writeSessionFile）：slot = 目标槽号或 null（显式置空）。
  *  失败容忍（NF2）：写失败按无记录路径降级——不抛错，不影响会话数据（T-M14）。 */
-export function writeEndMarker(cwd, slot) {
+export function writeEndMarker(cwd, slot, end = sessionEnd()) {
   try {
-    writeSessionFile(endMarkerPath(cwd), { slot, updatedAt: Date.now() })
+    writeSessionFile(endMarkerPath(cwd, end), { slot, updatedAt: Date.now() })
   } catch { /* NF2：失败容忍 */ }
 }
 
@@ -124,10 +147,13 @@ export function activePath(cwd) {
   return slotPath(cwd, activeSlot(cwd))
 }
 
-/** Atomic write: write to temp file then rename to replace, preventing truncated JSON from mid-write crash. */
-export function writeSessionFile(p, data) {
+/** Atomic write: write to temp file then rename to replace, preventing truncated JSON from mid-write crash.
+ *  `opts.tmpUnique`（§6.25 判据句 5 · D-SE65——**账本面专用**）：临时名 = `${p}.${pid}-${seq}.tmp`
+ *  （进程内自增）⇒ 清「并发写者共用 `${p}.tmp` ⇒ 互覆 / 混写」；槽文件 / 端标记面零改。返回所用临时名。 */
+let tmpSeq = 0
+export function writeSessionFile(p, data, { tmpUnique = false } = {}) {
   mkdirSync(dirname(p), { recursive: true })
-  const tmp = `${p}.tmp`
+  const tmp = tmpUnique ? `${p}.${process.pid}-${++tmpSeq}.tmp` : `${p}.tmp`
   writeFileSync(tmp, JSON.stringify(data), "utf8")
   try {
     renameSync(tmp, p)
@@ -140,6 +166,7 @@ export function writeSessionFile(p, data) {
       writeFileSync(p, readFileSync(tmp, "utf8"), "utf8")
     }
   }
+  return tmp
 }
 
 // ========== 清单 / 认领 / 属主面（init-block 批外提——见头注）==========
@@ -152,60 +179,50 @@ export function writeSessionFile(p, data) {
  *  **三态**：`true` 活 / `false` 死 / `undefined` 未知——未知不作死判据（D-MI10）。 */
 export { isProcessAlive }
 
-/** Lazy-load slot metadata from slot file (for old-format manifest entries that lack metadata) */
-function loadSlotMeta(cwd, slot, v) {
-  if (typeof v === "object" && v !== null && "ts" in v) return v
-  const ts = typeof v === "number" ? v : 0
-  try {
-    const p = slotPath(cwd, slot)
-    if (!existsSync(p)) return { ts }
-    const data = JSON.parse(readFileSync(p, "utf8"))
-    const history = data.history ?? []
-    const meta = extractSlotMeta(history, data.activeProvider, data.updatedAt ?? ts, data.title ?? "")
-    if (data.activeModel) meta.activeModel = data.activeModel
-    return { ts, ...meta }
-  } catch {
-    return { ts }
-  }
-}
-
-/** List all slots, newest first. Includes isActive flag.
- *  2026-09-01 会诊 🟢：只读操作不认领——原实现 active 缺失时调 activeSlot（写 manifest
- *  副作用，ACP session/list 可触发）。m.active 缺失时全部 isActive=false，由下一次
- *  activeSlot 正常认领。 */
+/** List all slots **from disk**, newest first. Includes isActive flag.
+ *  §6.22（SESSION-LIST-DISK 批 · 2026-09-28）：条目集 = **盘面实读**（sessions 根下槽文件枚举 /
+ *  取数链装配住 `session-slot-scan.mjs`）——manifest `m.slots` 只作摘要缓存，不参与条目集
+ *  （既不筛也不补）；排序 = `updatedAt` 降序（同值按槽号降序）；行形态逐字段零改。
+ *  计数不可得 = `null`（§6.25 判据句 4——非 0：真 0 与未知可分）；**读面懒核实**（判据句 3 落点 B）：
+ *  不可信档清单交核实面（纯内存登记 + 延迟拍——调用本体零写；核完回写 ⇒ 下次列表回快路）。
+ *  2026-09-01 会诊 🟢：只读操作不认领（清单链**零写**——不认领、不写 manifest、零探测）——
+ *  原实现 active 缺失时调 activeSlot（写 manifest 副作用，ACP session/list 可触发）。
+ *  m.active 缺失时全部 isActive=false，由下一次 activeSlot 正常认领。 */
 export function listSlots(cwd) {
   const m = loadManifest(cwd)
   const active = m.active ?? null
-  return Object.entries(m.slots)
-    .filter(([n]) => /^\d+$/.test(n))
-    .map(([n, v]) => {
-      const meta = loadSlotMeta(cwd, Number(n), v)
-      return {
-        slot: Number(n),
-        isActive: Number(n) === active,
-        timestamp: meta.ts,
-        date: new Date(meta.ts).toLocaleString(),
-        messageCount: meta.messageCount ?? 0,
-        turnCount: meta.turnCount ?? 0,
-        firstMessage: meta.firstMessage ?? "",
-        // MODEL-MERGE-SESSION 摘要 "p:m"：activeProvider 保持裸渠道名——列表消费面显复合
-        // （旧摘要无 activeModel → 回退裸渠道名——新老兼容；cmd-session/VSC sessions 行免改）
-        activeProvider: meta.activeProvider ? (meta.activeModel ? `${meta.activeProvider}:${meta.activeModel}` : meta.activeProvider) : "",
-        updatedAt: meta.updatedAt ?? meta.ts,
-        updatedDate: new Date(meta.updatedAt ?? meta.ts).toLocaleString(),
-        title: meta.title ?? "",
-      }
-    })
-    .sort((a, b) => b.updatedAt - a.updatedAt)
+  const scanned = scanSlotMetas(cwd, m.slots ?? {})
+  scheduleVerify(cwd, scanned, m.slots ?? {})
+  return scanned
+    .map(({ slot, meta }) => ({
+      slot,
+      isActive: slot === active,
+      timestamp: meta.ts,
+      date: new Date(meta.ts).toLocaleString(),
+      messageCount: meta.messageCount ?? null,
+      turnCount: meta.turnCount ?? null,
+      firstMessage: meta.firstMessage ?? "",
+      // MODEL-MERGE-SESSION 摘要 "p:m"：activeProvider 保持裸渠道名——列表消费面显复合
+      // （旧摘要无 activeModel → 回退裸渠道名——新老兼容；cmd-session/VSC sessions 行免改）
+      activeProvider: meta.activeProvider ? (meta.activeModel ? `${meta.activeProvider}:${meta.activeModel}` : meta.activeProvider) : "",
+      updatedAt: meta.updatedAt ?? meta.ts,
+      updatedDate: new Date(meta.updatedAt ?? meta.ts).toLocaleString(),
+      title: meta.title ?? "",
+      // 创建端（§6.20 判据句 4 读面——缺键/老槽 ⇒ "" = 未知；「未知」的渲染文案归消费面）
+      createdBy: meta.createdBy ?? "",
+    }))
+    .sort((a, b) => b.updatedAt - a.updatedAt || b.slot - a.slot)
 }
 
 /** Delete a slot: remove its file and manifest entry. Deleting the active slot
  *  resets the manifest active pointer (the next claim re-creates one). */
-export function deleteSlot(cwd, slot) {
+export function deleteSlot(cwd, slot, { end = sessionEnd() } = {}) {
   const n = Number(slot)
   if (!Number.isInteger(n) || n < 1) return false
   const m = loadManifest(cwd)
-  if (!m.slots[n]) return false
+  // §6.22 判据句 4（SESSION-LIST-DISK 批）：准入 = 盘面文件存在 ∨ manifest 有条目——盘上独有槽
+  // （文件在盘、条目缺失）可删；旧分支逐字保留（有条目无文件 ⇒ 仍清条目，行为同今日）。
+  if (!m.slots[n] && !existsSync(slotPath(cwd, n))) return false
   delete m.slots[n]
   delete m.slotSessions?.[n] // orphan session-id entries bloat the manifest forever
   try { unlinkSync(slotPath(cwd, n)) } catch { /* missing file is fine */ }
@@ -215,7 +232,7 @@ export function deleteSlot(cwd, slot) {
   // 保留 fresh.active，2026-09-01 会诊三家 🟡）
   saveManifest(cwd, m, { slots: [n], slotSessions: [n] }, { setActive: true })
   // 2026-09-05 §6.10 D-4/F4：删到本端记录槽 → 记录显式置空（文件保留 + slot:null——下次全新起步，不复活——T-M4/T-M8）
-  if (readEndMarker(cwd)?.slot === n) writeEndMarker(cwd, null)
+  if (readEndMarker(cwd, end)?.slot === n) writeEndMarker(cwd, null, end)
   return true
 }
 
@@ -224,11 +241,12 @@ export function deleteSlot(cwd, slot) {
 
 // ========== resumeSlot（SESSION.md §6.10 D-2——端分离恢复决策）==========
 
-/** 本端记录槽可用判据（D-2）：slot ∈ m.slots + 槽文件在盘 + 属主 空、死、本进程。
+/** 本端记录槽可用判据（D-2）：**槽文件在盘**（§6.22 判据句 4——条目缺失不作门）+ 属主
+ *  空、死、本进程。
  *  F-MI7：占用判据查调用面束（零自有探测）；属主 unknown（探测失败 / 缺行）⇒ **不可用**
  *  （不认领——保守：回落到 allocateFresh 取全新号，绝不与"可能活着"的属主同槽）。 */
 function usableSlot(cwd, m, slot, bundle = null) {
-  if (!m.slots[slot] || !existsSync(slotPath(cwd, slot))) return false
+  if (!existsSync(slotPath(cwd, slot))) return false
   const owner = m.slotSessions?.[slot]
   if (!owner || owner === getSessionId()) return true
   return ownerStateOf(owner, bundle) === "dead"
@@ -266,33 +284,43 @@ function loadLegacyFile(cwd) {
  * 恢复决策（SESSION.md §6.10 D-2）——TUI 启动的本端恢复入口（VS Code 面板同构镜像）。
  * **async**（F-MI7：入口一次异步束——探测不阻塞事件循环；调用面必须 await）。
  * 返回 { slot, data }（data 可为 null——全新起步或读槽失败）。判据：
- *   ① 本端记录可用（slot ≠ null 且 ∈ m.slots 且槽文件在盘 且属主 空/死/本进程）→ claimSlot；
+ *   ① 本端记录可用（slot ≠ null 且槽文件在盘 且属主 空/死/本进程——§6.22 判据句 4：manifest
+ *      条目缺失不作门）→ claimSlot；
  *   ② 记录缺失（从未记录 = 升级/首用迁移窗口）：②a active 属主 = 本进程（同进程重入——
  *      ensureActive 早退语义镜像：认领后尚未写 slots 条目/文件的窗口）→ 直接沿用；
  *      ②b 否则一次性继承 manifest.active（同判据；活属主绝不继承——全新槽起步，T-M3）；
  *   ③ 其余一切（slot:null 显式置空 / 槽被删 / 属主为活外人 / 继承失败）→ allocateFresh。
- * 每次落点都写本端记录；claim 后读槽失败（.corrupted/.unreadable——loadSlotFile 既有改名
- * 保全语义）→ 保持已 claim 槽 + data:null——不改 marker——下次保存原地重建（T-M15）。
+ * 每次落点都写本端记录；**读序前移**（§6.25 判据句 3 落点 A）：槽数据读先于认领落盘——读槽失败
+ * （.corrupted/.unreadable——loadSlotFile 既有改名保全语义）→ 仍按上述判据落点 + data:null——不改
+ * marker——下次保存原地重建（T-M15）；数据在手 ⇒ 摘要顺手补写随认领那次 saveManifest 落。
+ * `opts.end`（§6.20 判据句 2——显式端参 > 进程端名）：本端记录的读写端名——端壳经绑定转口
+ * 传本端常量（消费核本体的端壳零副本）；缺省 = 进程端名（CLI 全调用点零改）。
  */
-export async function resumeSlot(cwd) {
+export async function resumeSlot(cwd, { end = sessionEnd() } = {}) {
   const m = loadManifest(cwd)
   m.slotSessions ??= {}
   // 入口一次**异步束**（F-MI7——整链 async）：清理 / 可用 / 空闲全部查表，零逐 pid 探测。
   const bundle = await probeOwnersAsync(ownerPids(m))
   // 与 ensureActive 同型的死主清理（认领路径持久化——F5a 纪律：仅传 m 等于没删）
   const deadParam = cleanDeadOwners(m, bundle)
-  const rec = readEndMarker(cwd) // null = 缺失/损坏；{slot:null|N} = 文件在（D-1）
+  const rec = readEndMarker(cwd, end) // null = 缺失/损坏；{slot:null|N} = 文件在（D-1）
   let slot = null
   if (rec?.slot != null && usableSlot(cwd, m, rec.slot, bundle)) slot = rec.slot // ① 本端记录可用
   else if (rec === null) {
     if (m.active && m.slotSessions?.[m.active] === getSessionId()) slot = m.active // ②a 同进程重入
     else if (m.active && usableSlot(cwd, m, m.active, bundle)) slot = m.active // ②b 一次性继承
   }
-  if (slot !== null) claimSlot(cwd, slot, m, deadParam)
-  else slot = allocateFresh(cwd, m, deadParam, bundle) // ③ 全新分配（slot:null 绝不继承——T-M4）
-  // data 层：读已认领槽（loadSlotFile 自 session.mjs——环 import 见文件头）；读失败/槽文件不在 → legacy 单文件兜底（仅 data）
-  let data = loadSlotFile(cwd, slot)
+  // 落点 A（§6.25 判据句 3）：**读序前移**——纯读先于认领落盘 ⇒ 数据在手，摘要补写随认领那次 saveManifest 落
+  // （零额外读 + 零额外写）；认领决策树 / 保留集 / 端标记 / 改名语义逐条零变。
+  let data = slot !== null ? loadSlotFile(cwd, slot) : null
+  if (slot !== null) {
+    if (data) healDigest(m, slot, data, slotMtime(cwd, slot))
+    claimSlot(cwd, slot, m, deadParam)
+  } else {
+    slot = allocateFresh(cwd, m, deadParam, bundle) // ③ 全新分配（slot:null 绝不继承——T-M4）
+  }
+  // data 层：读已认领槽（loadSlotFile 自 session.mjs——环 import 见文件头）；读失败/槽文件不在 → legacy 兑底（仅 data）
   if (!data) data = loadLegacyFile(cwd)
-  writeEndMarker(cwd, slot)
+  writeEndMarker(cwd, slot, end)
   return { slot, data }
 }

package/session.mjs

@@ -22,6 +22,8 @@ import {
   slotPath, writeSessionFile, loadManifest, saveManifest, slotDigest,
   activeSlot, writeEndMarker,
 } from "./session-slots.mjs"
+// 摘要打点单源（#503 地板——与 session-lifecycle 同径直引；静态环同族，函数体内运行时使用）。
+import { digestTs } from "./session-slots-manifest.mjs"
 // F2 轮转守卫自 2026-09-08 迁至 session-guard.mjs（session-slots 再越 500 行硬限拆分）
 import { guardForeignSlotFile } from "./session-guard.mjs"
 import { engTokenSlotFields } from "./token-ttl.mjs"
@@ -40,16 +42,18 @@ export {
   writeSessionFile, slotDigest, loadManifest, saveManifest, activeSlot, listSlots,
   deleteSlot, isProcessAlive, END, endMarkerPath,
   readEndMarker, writeEndMarker, claimSlot, allocateFresh,
+  // §6.25 判据句 4：账本健康出口随动（端壳警示面消费——CLI / VSC 接线另座）
+  ledgerHealth,
 } from "./session-slots.mjs"
 // §6.12 标题写契约使 session-slots.mjs 超 500 行硬限 → renameSlot 拆至 session-rename.mjs（§6.12 模块与实现约束）
 export { renameSlot } from "./session-rename.mjs"
 // 人读线惰性窗口面（`history-window.mjs`）——re-export 保调用方单一路径。
 export { historyWindow, HISTORY_PAGE_SIZE, isRealUserMsg } from "./history-window.mjs"
 // 会话生命周期面（init-block 批 · F-MI7 拆分——语义原样外提）：本端恢复入口包装（含残留 GC
-// 钩子）/ 槽数据应用 / 新建 / 运行态清空 / 槽切换 / 占用查询。**resumeSlot/newSession 为 async**
-// （入口一次异步探测束——调用面必须 await）。
+// 钩子）/ 槽数据应用 / 新建 / 运行态清空 / 槽切换 / 占用查询 / 打开态读数（桌面残余批 · §6.24——
+// 只读纯投影）。**resumeSlot/newSession 为 async**（入口一次异步探测束——调用面必须 await）。
 export {
-  resumeSlot, applySession, newSession, resetSessionState, switchToSlot, slotOccupancy,
+  resumeSlot, applySession, newSession, resetSessionState, switchToSlot, slotOccupancy, sessionReading,
 } from "./session-lifecycle.mjs"
 import { resumeSlot as lifecycleResumeSlot } from "./session-lifecycle.mjs"
 
@@ -79,8 +83,9 @@ export function sessionDescriptor(agent, data) {
   return { history: full, total: full.length, base: 0 }
 }
 
-/** 槽摘要（记录存储绑定路径——history 不物化）：与 slotDigest(extractSlotMeta) 同形。 */
-function digestFromStore(fields, counters) {
+/** 槽摘要（记录存储绑定路径——history 不物化）：与 slotDigest(extractSlotMeta) 同形（含
+ *  `ts` 打点单源 `digestTs`——#503：`mtimeMs` 为该档写后取（缺省 ⇒ 裸墙钟回溯）。 */
+function digestFromStore(fields, counters, mtimeMs) {
   const meta = {
     messageCount: counters.total,
     turnCount: counters.userReal,
@@ -90,7 +95,9 @@ function digestFromStore(fields, counters) {
     title: fields.title ?? "",
   }
   if (fields.activeModel) meta.activeModel = fields.activeModel
-  return { ts: Date.now(), ...meta }
+  // 创建端（SLOT-END-PARAM 批 §6.20 判据句 4 读面——有值才带；老槽无键 ⇒ 键缺席 = 未知）
+  if (fields.createdBy) meta.createdBy = fields.createdBy
+  return { ts: digestTs(mtimeMs), ...meta }
 }
 
 /** Save agent state to the active slot file (atomic write). `display` (the old
@@ -153,17 +160,30 @@ export function saveSession(agent) {
   // saveSession 与 token-ttl persistEngTokens（settle 当场落盘）共用同一份（检查按
   // mtime 缓存 _slotMtime：自写未变跳过全量解析）。
   const rotated = guardForeignSlotFile(agent, p, slot)
+  // 创建端（SLOT-END-PARAM 批 §6.20 判据句 4 写面）：取值链在守卫内顺带解析（轮转/损坏/文件
+  // 不在盘 ⇒ 进程端名；解析通过 ⇒ 盘上键或 null）——**守卫之后**注入，本端首物化写一次，
+  // 此后透传盘上键；盘上无键（老槽）⇒ null ⇒ 键不落盘（禁回填）。
+  if (agent._slotCreatedBy != null) fields.createdBy = agent._slotCreatedBy
+  // 会话级档位携带（§6.21 判据句 5 · 防整对象抹除）：值 = 当前生效档位（`applySession` 携带的槽
+  // 原值——`"off"` 记号原样写盘，不回填为具体档）；缺之 ⇒ 下一次回合保存把槽写面结果整对象抹除。
+  // `undefined` = 本会话未携带（老槽无该键 / 未经 `applySession`）⇒ 键不落盘（禁回填）。
+  if (agent._slotEffort !== undefined) fields.effort = agent._slotEffort
   // 绑定态 → 流式投影（段原文拼接——VSC 兼容面逐字同形）；未绑定 → 既有全量物化写
   if (agent._recordStore) saveProjectedSlot(agent, p, fields, contextHistory)
   else writeSessionFile(p, { ...fields, history: legacyHistory(agent), contextHistory })
-  // 记录我们刚写的 mtime——下次保存跳过重复解析
-  try { agent._slotMtime = statSync(p).mtimeMs } catch {}
+  // 记录我们刚写的 mtime——下次保存跳过解析（缓存 = `{p, mtimeMs}` 按路径命中：#386）+
+  // 摘要 `ts` 地板入参（#503：保存面**写后取** mtime——同族先例 session-slot-verify.mjs:99）。
+  let wroteMtimeMs
+  try {
+    wroteMtimeMs = statSync(p).mtimeMs
+    agent._slotMtime = { p, mtimeMs: wroteMtimeMs }
+  } catch { /* stat 失败 ⇒ 缓存不动 / 摘要裸墙钟回溯 */ }
   // Update slot metadata in manifest
   try {
     const m = loadManifest(agent.cwd)
     m.slots[slot] = agent._recordStore
-      ? digestFromStore(fields, agent._recordStore.counters())
-      : slotDigest({ ...fields, history: legacyHistory(agent) })
+      ? digestFromStore(fields, agent._recordStore.counters(), wroteMtimeMs)
+      : slotDigest({ ...fields, history: legacyHistory(agent) }, wroteMtimeMs)
     saveManifest(agent.cwd, m)
   } catch (e) {
     // Manifest update failure is non-fatal — data is safe, metadata will lazy-recover on next listSlots

package/shell-candidates.mjs

@@ -0,0 +1,78 @@
+/**
+ * shell-candidates.mjs — 平台 shell 候选探测**单源**（B10 S17 收编：桌面 `settings-env.mjs:27-62` ∥
+ * VSC `src/extension/settings.mjs:72-115` 两造 ≈逐字 ⇒ 候选表 ∕ 探测序 ∕ 超时 ∕ memo 上提本档；
+ * 两端薄壳只留 re-export —— 端侧零自持候选表）。
+ *
+ * 面：`shellCandidates()` ⇒ `Promise<{ name, value }[]>`——「System default」恒首 + 平台候选
+ * （`where` ∕ `sh -c 'command -v'` 探存）；进程内 memo（成功结果缓存：本进程生命周期内 shell 路径
+ * 不热变化）+ 在飞去重（同一时刻重复请求共享同一批 —— 不叠发子进程）。
+ * 探测面 = **异步非阻塞**（`execFile` + `Promise.all` 并发；同步探测会占住宿主事件循环 ⇒ UI 假死 ——
+ * VSC F-W18 口径）；本函数**绝不抛出**（探测失败 = 该候选缺席）。
+ * 测试缝（先例 = 核 `_setProbeImplForTest`）：`_setShellDetectForTest` 替换真实 `execFile` 探测；
+ * 注入即清 memo ∕ 在飞态（免旧批结果串味）；复位 = `null`。
+ * 纪律：零第三方依赖；本档只 probe 存在性 —— 不读配置、不出文案（候选名面 = 两端既有显示源）。
+ */
+import { execFile } from "node:child_process"
+import { existsSync } from "node:fs"
+
+/** 探测超时（ms）—— 两端原值单源（VSC `settings.mjs` ∕ 桌面 `settings-env.mjs` 同值 3000）。 */
+const PROBE_TIMEOUT_MS = 3000
+
+/** Git Bash 安装路径表（Windows 候选面 —— 表序 = 探测优先序，首命中即取）。 */
+const GIT_BASH_PATHS = Object.freeze([
+  "C:\\Program Files\\Git\\bin\\bash.exe",
+  "C:\\Program Files (x86)\\Git\\bin\\bash.exe",
+  `${process.env.LOCALAPPDATA ?? ""}\\Programs\\Git\\bin\\bash.exe`,
+])
+
+/** memo（成功结果缓存）∕ 在飞（同批共享）—— 本档单点持有。 */
+let _cache = null
+let _inFlight = null
+
+/** 测试缝：伪探测替掉真实 `execFile` 探测（可返 Promise——异步面同形）；注入即清 memo ∕ 在飞态。 */
+let _detectImpl = null
+export function _setShellDetectForTest(fn) {
+  _detectImpl = typeof fn === "function" ? fn : null
+  _cache = null
+  _inFlight = null
+}
+
+/** 候选命令是否存在（异步探测：Windows `where` / POSIX `sh -c 'command -v'`；失败或超时 ⇒ false）。 */
+function commandExists(cmd) {
+  return new Promise((resolve) => {
+    if (_detectImpl) { resolve(_detectImpl(cmd)); return }
+    const win = process.platform === "win32"
+    try {
+      execFile(win ? "where" : "sh", win ? [cmd] : ["-c", `command -v ${cmd}`], { timeout: PROBE_TIMEOUT_MS }, (err, stdout) => {
+        resolve(!err && String(stdout ?? "").trim().length > 0)
+      })
+    } catch { resolve(false) }
+  })
+}
+
+/** 平台候选表（「System default」恒首；`detect` 只作探测用 —— 出口两键 `{ name, value }` 不外发函数）。 */
+function candidateTable() {
+  const candidates = [{ name: "System default", value: null, detect: () => true }]
+  if (process.platform === "win32") {
+    candidates.push({ name: "PowerShell (pwsh)", value: "pwsh", detect: () => commandExists("pwsh") })
+    candidates.push({ name: "Windows PowerShell (powershell)", value: "powershell", detect: () => commandExists("powershell") })
+    const gb = GIT_BASH_PATHS.find((p) => p && existsSync(p))
+    if (gb) candidates.push({ name: `Git Bash (${gb})`, value: gb, detect: () => true })
+    candidates.push({ name: "WSL bash (wsl)", value: "wsl", detect: () => commandExists("wsl") })
+  } else {
+    for (const sh of ["bash", "zsh", "fish"]) candidates.push({ name: sh, value: sh, detect: () => commandExists(sh) })
+  }
+  return candidates
+}
+
+/** 平台 shell 候选读数（memo + 在飞去重）：候选集 = 探存命中项 `{ name, value }`（平台序）。 */
+export function shellCandidates() {
+  if (_cache !== null) return Promise.resolve(_cache)
+  if (_inFlight) return _inFlight
+  const candidates = candidateTable()
+  const p = Promise.all(candidates.map(async (c) => ((await c.detect()) ? { name: c.name, value: c.value } : null)))
+    .then((hits) => { _cache = hits.filter(Boolean); return _cache })
+    .finally(() => { if (_inFlight === p) _inFlight = null })
+  _inFlight = p
+  return p
+}

package/text-budget.mjs

@@ -1,12 +1,12 @@
 /**
- * text-budget.mjs — 文本额度纯函数（零依赖——TUI-OOM-ROOTCAUSE 批，AGENT-LOOP.md §23.3.1 / TUI.md §15.3.2）。
+ * text-budget.mjs — 文本额度纯函数（零依赖——TUI-OOM-ROOTCAUSE 批，AGENT-LOOP.md §6.15 / TUI-SESSION-VIEW.md §5.2）。
  *
  * 单一来源（D2）：agent 侧捕获截断（spawn-child.mjs——子代理 `_capturedOutput`）与 TUI 面
  * 载体额度（tui/display-budget.mjs）共用本体的 `capText` / `appendCappedText`——两处各自
  * 复制截断逻辑的漂移面被消除。本模块零 import（可被任意层直接引用）。
  *
  * 计量口径 = **UTF-16 码元**（`String.length`——与 JS 字符串内存近似、确定、O(1) 计长；
- * TUI.md §15.2 表 1）。截断形态 = 头保 + 中段标记 + 尾保（标记含真实省略数 N）。
+ * TUI-SESSION-VIEW.md §5.1）。截断形态 = 头保 + 中段标记 + 尾保（标记含真实省略数 N）。
  *
  * 标记串约定：`marker` 模板中以字面 `N` 为省略数占位（逐字进测试断言——如
  * `… [captured output truncated: N chars omitted] …`）。

package/think-off.mjs

@@ -0,0 +1,49 @@
+/**
+ * think-off.mjs — off 形族的单一实现源（叶档：零 import 纯函数）。
+ *
+ * 单一来源 = `docs/core/design/MODEL-SPECS.md`：写面取形 = §16.2 / §15.4-2 族别判据表；
+ * 「有效 off 路径」判据 = §16.4。四处生产者（CLI `/think` · CLI `/advisor` · VSC 主模型面
+ * `reasoning-mode.mjs` · VSC 面板写面 `settings-panel-write.mjs`）一律消费本档（端引核零副本——
+ * 副本即漂移源：VSC 全族一形 `null` 与 CLI 自定义族支 `undefined` 两处漂移已实证，§16.1-③）。
+ */
+
+/** 写面取形（§15.4-2 族别判据的单一实现）：`spec → null | { type:"disabled" }`。
+ *  effort 族（`thinkApi === "effort"`）⇒ `null`——载荷层 off 门首款要求 `thinking === null`
+ *  （单源 = `doc:PROVIDER.md:§6.12`；`{type:"disabled"}` 不开门 ⇒ 关思考静默失效）；
+ *  其余（type 族默认 / 自定义开值族）⇒ `{ type: "disabled" }`——type 机制原生 off 形。 */
+export function thinkOffShape(spec) {
+  return spec?.thinkApi === "effort" ? null : { type: "disabled" }
+}
+
+/** 有效 off 路径（「何时可宣称 OFF」判据本体 = §16.4）——由 `thinkOffShape` 派生（防两处漂移）：
+ *  `null` 形只有 effort 族的载荷门据它补发 `reasoning_effort:"none"` ⇒ 须枚举含 `"none"`
+ *  （无枚举 / 无 `none` ⇒ 形不发任何字段，§16.4 表第 1 行）；`{type:"disabled"}` 形 ⇒ 达载荷层。
+ *  两形共门 = `thinkAlwaysOn !== true`（服务端强制族：形被拒 / 恒思考 ⇒ 无效，§16.3 / §16.4 表第 2 行）。 */
+export function thinkOffPath(spec) {
+  if (spec?.thinkAlwaysOn === true) return false
+  if (thinkOffShape(spec) === null) return (spec?.reasoningEffortEnum ?? []).includes("none")
+  return true
+}
+
+/** advisor 推理档写面三态（**写语义单源** —— 由 VSC `settings-panel-write.mjs:149-164` 上提；B10 S11：
+ *  桌面主侧 ∕ VSC 写面两端同引，零副本）：`advisor` 对象原地作用于 `{ thinking, reasoningEffort }` 两键 ——
+ *  ① `"none"`（关思考）⇒ `thinking = thinkOffShape(spec)`（族别 off 形）+ 删 `reasoningEffort`；
+ *  ② 非空档字面 ⇒ `reasoningEffort = 值` + 清 off 形残记（`thinking` 为 `null` 字面 ∕ `{type:"disabled"}`
+ *     两 off 形皆清 —— 选档即要思考，B10 S11 收正：源式只清 `null` 字面，type 族 off 形残留会压过档位读回）；
+ *  ③ 其余（空 ∕ 非串 = 中性）⇒ 删 `reasoningEffort` + 清 off 形残记（读回中性 —— 同上收正）。
+ *  写后投影恒等（读回 = 所选：off 形 ⇒ `"none"`；字面档 ⇒ 该档；两清 ⇒ 中性）。*/
+export function applyAdvisorEffort(advisor, value, spec) {
+  const target = advisor !== null && typeof advisor === "object" && !Array.isArray(advisor) ? advisor : {}
+  const offish = target.thinking === null || target.thinking?.type === "disabled"
+  if (value === "none") {
+    target.thinking = thinkOffShape(spec)
+    delete target.reasoningEffort
+  } else if (typeof value === "string" && value.trim()) {
+    target.reasoningEffort = value.trim()
+    if (offish) delete target.thinking
+  } else {
+    delete target.reasoningEffort
+    if (offish) delete target.thinking
+  }
+  return target
+}

package/token-ttl.mjs

@@ -30,7 +30,7 @@
 import { existsSync, readFileSync, statSync } from "node:fs"
 import {
   slotPath, writeSessionFile, activeSlot, loadManifest, saveManifest, slotDigest,
-  writeEndMarker,
+  writeEndMarker, sessionEnd,
 } from "./session-slots.mjs"
 // F2 轮转守卫自 2026-09-08 迁至 session-guard.mjs（session-slots 再越 500 行硬限拆分）
 import { guardForeignSlotFile } from "./session-guard.mjs"
@@ -258,8 +258,14 @@ export function persistEngTokens(agent) {
       engineering: agent.config?.agent?.engineering ?? false,
       goal: agent.goal ?? null,
       advisor: agent.config?.advisor ?? null,
+      // 会话级档位（#441③ 键齐——与 `newSlotData` 规范结构 / `saveSession` 携带面同源：
+      // 实况有值携带、无则 `null`；老槽禁回填不适用——本分支只产全新槽）。
+      effort: agent._slotEffort ?? null,
       pendingReminders: agent._pendingReminders ?? [],
       sessionStart: agent._sessionStart ?? null,
+      // 创建端（SLOT-END-PARAM 批 §6.20 判据句 4 写面——全新分支）：取值链已由守卫（上方
+      // `guardForeignSlotFile`）解析入 `agent._slotCreatedBy`（文件不在盘 ⇒ 进程端名）。
+      createdBy: agent._slotCreatedBy ?? sessionEnd(),
     }
   }
   const fields = engTokenSlotFields(agent)
@@ -270,13 +276,18 @@ export function persistEngTokens(agent) {
   delete data.engDesignToken
   data.updatedAt = Date.now()
   writeSessionFile(p, data)
-  // 记录我们刚写的 mtime——下次保存/守卫跳过重复解析（saveSession 同款）
-  try { agent._slotMtime = statSync(p).mtimeMs } catch {}
+  // 记录我们刚写的 mtime——下次保存/守卫跳过重复解析（saveSession 同款；缓存按路径命中 #386）
+  // + 摘要 `ts` 地板入参（#503：保存面写后取 mtime——同族先例 session-slot-verify.mjs:99）。
+  let wroteMtimeMs
+  try {
+    wroteMtimeMs = statSync(p).mtimeMs
+    agent._slotMtime = { p, mtimeMs: wroteMtimeMs }
+  } catch { /* stat 失败 ⇒ 缓存不动 / 摘要裸墙钟回溯 */ }
   // Update slot metadata in manifest（saveSession 同款尾——非致命：数据已安全，
   // metadata 下次 listSlots 惰性恢复）
   try {
     const m = loadManifest(agent.cwd)
-    m.slots[slot] = slotDigest(data)
+    m.slots[slot] = slotDigest(data, wroteMtimeMs)
     saveManifest(agent.cwd, m)
   } catch (e) {
     console.error(`[session] manifest metadata update failed for slot ${slot}: ${e.message}`)