thincoder 0.12.59 → 0.12.61

package/src/session.mjs

@@ -1,8 +1,10 @@
 /**
  * session.mjs — session persistence (slot-based model)
  * Each project (keyed by cwd hash) keeps unlimited session slots.
- * Every session lives in a numbered slot; the manifest tracks which slot is active.
- * There is no separate "current" file — the active slot IS the current session.
+ * Every session lives in a numbered slot; the manifest tracks the SHARED active pointer
+ * (2026-09-05 §10 D-6 修订：active = 旧版端/ACP 的恢复依据 + 无记录端的一次性继承源 +
+ * 列表回退高亮——本端恢复依据 = end marker `{manifest}.cli`，见 session-slots.mjs
+ * resumeSlot/readEndMarker，SESSION.md §1/§10）。
  *
  * File layout: {hash}.json.N (slots), {hash}.json.manifest (slot metadata + active pointer).
  * Legacy {hash}.json is migrated to a slot on first access.
@@ -13,17 +15,33 @@
 
 import { readFileSync, renameSync, existsSync, statSync } from "node:fs"
 import { basename } from "node:path"
+import { resolveCompactThreshold } from "./config.mjs"
 import {
   slotPath, writeSessionFile, loadManifest, saveManifest, slotDigest,
-  activeSlot, sessionPath, getSessionId, isProcessAlive,
+  activeSlot, getSessionId, isProcessAlive,
+  writeEndMarker, resumeSlot as slotsResumeSlot,
 } from "./session-slots.mjs"
+// F2 轮转守卫自 2026-09-08 迁至 session-guard.mjs（session-slots 再越 500 行硬限拆分）
+import { guardForeignSlotFile } from "./session-guard.mjs"
+import { scheduleSessionGC } from "./session-gc.mjs"
+import { engTokenSlotFields, restoreEngTokens } from "./token-ttl.mjs"
 
-// re-export slot 管理（保持既有 import session.mjs 的调用点不变）
+// re-export slot 管理（保持既有 import session.mjs 的调用点不变；resumeSlot 下方本地包装导出）
 export {
   getSessionId, normalizeCwd, sessionPath, slotPath, manifestPath, activePath,
   writeSessionFile, slotDigest, loadManifest, saveManifest, activeSlot, listSlots,
-  deleteSlot, renameSlot, isProcessAlive,
+  deleteSlot, isProcessAlive, END, endMarkerPath,
+  readEndMarker, writeEndMarker, claimSlot, allocateFresh,
 } from "./session-slots.mjs"
+// §12.2.5 契约改使 session-slots.mjs 超 500 行硬限 → renameSlot 拆至 session-rename.mjs（§12.3 授权）
+export { renameSlot } from "./session-rename.mjs"
+
+/** 恢复决策包装（SESSION.md §12 启动钩子，2026-09-06）：本端恢复入口触发一次残留 GC——
+ *  scheduleSessionGC 内部 setImmediate 空闲执行 + 每进程每前缀去重，不阻塞启动路径（N4）。 */
+export function resumeSlot(cwd) {
+  scheduleSessionGC(cwd)
+  return slotsResumeSlot(cwd)
+}
 
 // ========== legacy transient prefix cleanup ==========
 
@@ -106,8 +124,10 @@ export function saveSession(agent) {
     version: 2,
     cwd: agent.cwd,
     title: agent.title ?? "",
-    activeProvider: agent.activeProvider ?? agent.provider?.name,
-    activeModel: agent.activeModel ?? null,
+    // MODEL-MERGE-SESSION 槽双字段恒非空（裁定 a）：有 provider 即携带具体复合值——
+    // 恢复不看 config（F-4）——无渠道默认可回落 ""/null（全新未配态——读侧容忍）
+    activeProvider: agent.activeProvider ?? agent.provider?.name ?? "",
+    activeModel: agent.activeModel ?? agent.provider?.model ?? null,
     updatedAt: Date.now(),
     history,
     contextHistory,
@@ -115,60 +135,26 @@ export function saveSession(agent) {
     planMode: agent.planMode ?? false,
     autoApprove: agent.autoApprove ?? false,
     engineering: agent.config?.agent?.engineering ?? false,
-    engDesignToken: agent._engDesignToken ?? null,
-    // Multi-design slots ride the same round-trip (2026-09-01 audit #1): Map → {designId: token}
-    // (JSON-safe). Empty/absent Map → undefined → the key is dropped by JSON.stringify, so a
-    // cleared session writes NO field instead of resurrecting slots from the previous save.
-    engDesignTokens: agent._engDesignTokens instanceof Map && agent._engDesignTokens.size > 0
-      ? Object.fromEntries(agent._engDesignTokens)
-      : undefined,
+    ...engTokenSlotFields(agent),
     goal: agent.goal ?? null,
     advisor: agent.config?.advisor ?? null,
     pendingReminders: agent._pendingReminders ?? [],
     sessionStart: agent._sessionStart ?? null,
   }
+  // 2026-09-05 §10 D-4：首认领（_slot 为 null——如 /session 切换后首保存、"查看对方活槽 →
+  // 保存 fork 新槽"的落盘槽跟随）写本端记录——marker = 端内最后认领者；粘性 _slot 期间
+  // 的日常保存不写（F1：保存永不参与竞争）
+  const claimedNow = agent._slot == null
   const slot = agent._slot ??= activeSlot(agent.cwd)
+  if (claimedNow) writeEndMarker(agent.cwd, slot)
   const p = slotPath(agent.cwd, slot)
   // 2026-08-31 会诊 F2 🔴：写前校验磁盘文件的 sessionStart——与本进程会话不符（另一
   // 进程/会话的现场）→ 先轮转 .bak 保留再写（11311 条历史被新进程覆盖的实锤场景）。
-  // 检查按 mtime 缓存（_slotMtime）：文件自上次检查/自写未变就跳过全量解析——
-  // 每次保存都 readFileSync+JSON.parse 多 MB 会话 → O(n²) 退化。
-  let rotated = null
-  try {
-    if (existsSync(p)) {
-      const st = statSync(p)
-      let disk = null
-      if (st.mtimeMs !== (agent._slotMtime ?? -1)) {
-        disk = JSON.parse(readFileSync(p, "utf8"))
-        // 2026-08-31 会诊 deepseek 🟡：version>2 的新版文件无论 sessionStart 一律轮转
-        // （loadSlotFile 对 v3 返回 null 不动文件——若其 sessionStart 为 null，旧版首次
-        // 保存会静默覆盖；轮转 .bak 保证新版文件保留）。
-        // 2026-09-01 advisor 🔵：磁盘文件 cwd 不匹配（异项目文件误落本路径）同样轮转——
-        // 与 loadSlotFile/legacy 读的"别人的文件不动"原则对齐（否则 sessionStart null +
-        // version≤2 的异项目文件被静默覆盖且无 .bak）。
-        const diskIsNewer = typeof disk?.version === "number" && disk.version > 2
-        const diskStart = disk?.sessionStart ?? null
-        const myStart = agent._sessionStart ?? null
-        const diskForeign = typeof disk?.cwd === "string" && disk.cwd.toLowerCase() !== agent.cwd.toLowerCase()
-        if (diskIsNewer || diskForeign || (diskStart && diskStart !== myStart)) {
-          const bak = `${p}.bak-${Date.now()}`
-          renameSync(p, bak)
-          rotated = bak
-          console.error(`[session] slot ${slot} holds ${diskIsNewer ? `a newer-version file (v${disk.version})` : diskForeign ? `a foreign-cwd file (${disk.cwd})` : `another session (start ${diskStart}, ours ${myStart})`} — preserved as ${basename(bak)}`)
-        }
-        agent._slotMtime = st.mtimeMs
-      }
-    }
-  } catch {
-    // 文件存在但不可读（损坏/半写）：改名 .corrupted 保留现场（2026-09-01 advisor 🔵——
-    // 与自身 loadSlotFile 的 .corrupted 约定 + VS Code saveSessionToSlot 对齐；.bak 保留
-    // 给 F2 轮转路径，损坏现场不再混入轮转后缀，恢复/清理工具按后缀分类不误判）
-    if (existsSync(p)) {
-      try {
-        renameSync(p, `${p}.corrupted`)
-      } catch {}
-    }
-  }
+  // 守卫自 2026-09-08 提取为 guardForeignSlotFile（session-guard.mjs——DESIGN-TOKEN-
+  // SETTLEMENT D1 二次拆分：先入 session-slots、再因 500 行硬限迁 session-guard）——
+  // saveSession 与 token-ttl persistEngTokens（settle 当场落盘）共用同一份（检查按
+  // mtime 缓存 _slotMtime：自写未变跳过全量解析）。
+  const rotated = guardForeignSlotFile(agent, p, slot)
   writeSessionFile(p, data)
   // 记录我们刚写的 mtime——下次保存跳过重复解析
   try { agent._slotMtime = statSync(p).mtimeMs } catch {}
@@ -245,36 +231,12 @@ export function loadSlotFile(cwd, slot) {
   return null
 }
 
-/** Load session data from the active slot; returns null if missing, corrupted, or version mismatch */
+/** Load session data for this cwd — 2026-09-05 §10 D-2：平移为 resumeSlot 的数据包装
+ *  （签名不变——测试兼容；读槽校验/.tmp 回退/legacy 兜底语义原样保留在 resumeSlot 的
+ *  data 层）。恢复目标选择按本端记录（end marker）——manifest active 仅作无记录端的
+ *  一次性继承源（D-6），不再作本端恢复第一依据。 */
 export function loadSession(cwd) {
-  // Try the active slot first (post-migration, legacy file may be stale)
-  const slot = activeSlot(cwd)
-  let result = loadSlotFile(cwd, slot)
-  if (result) return result
-
-  // Fallback: try the legacy current file (pre-migration, or migration failed to clean up)
-  const legacy = sessionPath(cwd)
-  try {
-    if (existsSync(legacy)) {
-      const data = JSON.parse(readFileSync(legacy, "utf8"))
-      // cwd 不匹配是别人的文件——与 loadSlotFile 一致直接 return null 不改名
-      // （"别人的文件不动"原则，2026-08-31 advisor round2 🟡）
-      if (data.cwd && data.cwd.toLowerCase() !== cwd.toLowerCase()) return null
-      if ((data?.version === 1 || data?.version === 2) && Array.isArray(data.history)) {
-        data.history = data.history.filter((m) => !isLegacyTransient(m))
-        return data
-      }
-      // 结构不匹配：保留现场（version>2 的新版文件不动）
-      if (!(typeof data?.version === "number" && data.version > 2)) {
-        try { renameSync(legacy, `${legacy}.unreadable`) } catch {}
-        console.error(`[session] legacy file ${legacy}: invalid structure — preserved as ${basename(legacy)}.unreadable`)
-      }
-    }
-  } catch (e) {
-    console.error(`[session] failed to load legacy ${legacy}: ${e.message}`)
-    try { renameSync(legacy, `${legacy}.corrupted`) } catch {}
-  }
-  return null
+  return resumeSlot(cwd).data
 }
 
 /** slimForDisplay 截断的 arguments 以 U+2026（…）结尾——不是合法 JSON 的完整值。
@@ -293,22 +255,38 @@ function stripTruncatedToolArgs(m) {
   return changed ? { ...m, tool_calls } : m
 }
 
-/** Apply loaded session data onto an agent object; returns true if provider was switched.
- *  2026-08-31 会诊 F1：清空 _slot/_slotMtime 缓存——切换后下次保存重新认领（F1b 回归：
- *  switchToSlot 后保存必须落新槽而非旧槽）。 */
+/** Apply loaded session data onto an agent object; returns true if the runtime composite
+ *  was switched. 2026-08-31 会诊 F1：清空 _slot/_slotMtime 缓存——切换后下次保存重新认领。
+ *
+ *  MODEL-MERGE-SESSION（F-4）applySession 重写为两支 + 删旧支（评审 #7/#9 措辞——防
+ *  "三支"误读）：
+ *  ① 槽 provider 存在 → provider/model 按槽值设（双字段恒非空——模型取 data.activeModel，
+ *     legacy 槽 null/空串回该渠道默认模型 `providers[].model`（单值——2026-09-10 MODEL-SELECTION
+ *     v2；老 models[] 首候选形态已退场））+ 重算
+ *     compactThreshold（auto 时——按恢复后模型）——不看 config（defaultModel 只是新会话起点）；
+ *  ② 槽 provider 没了 → D-S3 保留——静默保持现状（config 有效则有效——两方都无效由调用侧
+ *     复验 validateProvider 弹重选）。
+ *  删旧支："activeModel==null 清 stale override 回渠道默认"——前提 = 渠道默认字段——已随
+ *  三旧层删除消失——双字段恒非空故不可能触发（评审 #7）。 */
 export function applySession(agent, data) {
-  // data.history is the FULL never-compacted record (human line); data.contextHistory is the
-  // (possibly compacted) machine line. Restore each line from its own source — the machine
-  // context keeps its compaction savings across resume. Legacy files without contextHistory
-  // fall back to seeding the machine line from the full history (it re-compacts when needed).
-  // 2026-08-31 会诊 deepseek 🟡：机读线必须从 contextHistory 恢复而非从完整 history 重建——
-  // 后者会把已压缩的中间过程塞回上下文（实测 prompt 膨胀到 283%）。compactThresholdAuto 时
-  // 按恢复后的模型重新推导阈值（bin/thincoder.mjs）。v1 老文件（无 contextHistory）回退
-  // 播种时剥离被 slimForDisplay 截断的 tool_calls.arguments（以 … 结尾 → 置 {}；会诊 F6——
-  // 截断可劈断 \\uXXXX 产生 400 毒载荷）。2026-09-01 会诊三家：length > 0 才当机读线
-  // （contextHistory: [] 是"无机读线"而非空机器线——空机器线会静默丢全部上下文）。
+  // 机读线语义（历史注释保留）：data.history = FULL 未压缩记录（人读线）；data.contextHistory =
+  // 压缩后机器线——恢复各从其源（保留压缩收益——从完整 history 重建会塞回中间过程——实测
+  // prompt 膨胀 283%）。v1 老文件（无 contextHistory）回退播种，剥离被 slimForDisplay 截断的
+  // tool_calls.arguments（… 结尾 → 置 {}——截断可劈断 \\uXXXX 产生 400 毒载荷）。length > 0 才
+  // 当机读线（contextHistory: [] 是"无机读线"而非空机器线——空机器线静默丢全部上下文）。
   agent.config ??= {} // ACP test mocks may omit config; be defensive like the ??= below
   const full = Array.isArray(data.history) ? data.history : []
+  // SESSION.md §11.2（2026-09-08——F2/F3）：恢复事件按当前 data 重定——载入历史非空 = 会话
+  // 恢复 → 下个 depth-0 回合 env-state resumed:yes 一次（pushEnvStateReminder 读即清——每次恢复
+  // 一次）。/new 与空历史槽切换不武装（显式清 false）——无恢复事件恒 no（F3 伪触发消除——不再靠
+  // _sessionStart != null 推断；已武装 agent 切到空历史槽也不残留上次恢复事件——评审 round2 🟡）。
+  // _processRestartPending 不在此清——由启动路径（bin/thincoder.mjs）设、prepareRun 发句清
+  // （N6——双信号独立：切槽不报进程重启）。
+  // 跨端异名互指（结构债批 5 N7——双端同语义各自独立实现、命名不统一是刻意——SESSION.md
+  // §11.2）：VSC 端同机制载体异名 = agent._resumedPending（src/agent/setup.mjs hydrateRun——
+  // restore:true 工厂 + fullHistory 非空时武装——每槽恢复一次）+ 模块级 restartDetectionDone
+  // 一次性闸（src/agent/setup-reminders.mjs——process restarted 句的进程级信号）。
+  agent._envResumed = full.length > 0
   const ch = data.contextHistory
   const machine = (Array.isArray(ch) && ch.length > 0) ? ch : full.map(stripTruncatedToolArgs)
   agent._fullHistory = [...full]
@@ -320,15 +298,8 @@ export function applySession(agent, data) {
   agent.goal = data.goal ?? null
   agent._pendingReminders = data.pendingReminders ?? []
   agent._sessionStart = data.sessionStart ?? null
-  agent._engDesignToken = data.engDesignToken ?? null
-  // Multi-design slots restore from the {designId: token} object (2026-09-01 audit #1). A legacy
-  // slot without the field restores NO Map (fresh state) — never resurrect slots the writer did
-  // not have. Expired tokens are rejected downstream by validateDesignToken (fail-closed, TTL).
-  if (data.engDesignTokens && typeof data.engDesignTokens === "object" && !Array.isArray(data.engDesignTokens)) {
-    agent._engDesignTokens = new Map(Object.entries(data.engDesignTokens))
-  } else {
-    delete agent._engDesignTokens
-  }
+  // R16 token 字段恢复（过期过滤——见 token-ttl.mjs restoreEngTokens）
+  restoreEngTokens(agent, data)
   // engineering is session-level (2026-08-29): the slot value is the CLI session's authority
   // — config.json is only the initial default / cross-end mirror. A legacy slot without the
   // field keeps whatever config.json seeded (unchanged behavior).
@@ -345,27 +316,29 @@ export function applySession(agent, data) {
   agent._verifyPassed = false
   agent._slot = null // 粘性缓存清空——切换后重新认领（F1b）
   agent._slotMtime = null
-  if (data.activeProvider && data.activeProvider !== agent.activeProvider) {
-    const p = agent.providers?.find((pr) => pr.name === data.activeProvider)
-    if (p) {
-      agent.provider = { ...p }
-      agent.activeProvider = p.name
-      agent.activeModel = data.activeModel ?? null
-      if (agent.activeModel) agent.provider.model = agent.activeModel
-      return true
-    }
-  } else if (data.activeModel != null) {
-    // Same provider, different model
-    agent.activeModel = data.activeModel
-    if (agent.activeModel && agent.provider) agent.provider.model = agent.activeModel
-  } else if (data.activeProvider && data.activeProvider === agent.activeProvider) {
-    // Same provider, session has no activeModel → clear stale override
-    agent.activeModel = null
-    if (agent.provider) {
-      const p = agent.providers?.find((pr) => pr.name === agent.activeProvider)
-      if (p) agent.provider.model = p.model
+  // ── MODEL-MERGE-SESSION 恢复（F-4——两支）──
+  const slotProvider = data.activeProvider ? agent.providers?.find((pr) => pr.name === data.activeProvider) : null
+  if (slotProvider) {
+    // ① 槽 provider 存在 → 按槽值设（不看 config）：双字段恒非空——legacy 槽 activeModel
+    //    null/空串 = 无 override——回该渠道默认模型（`providers[].model` 单值——M3）。
+    //    F-2d（MODEL-400-FIX）：`||` 非 `??`——空串也兜（activeModel="" 的槽会让 `??` 不落链 →
+    //    空槽 model 恒有值，provider.model 键不缺失）
+    const prevName = agent.activeProvider
+    const prevModel = agent.activeModel ?? null
+    const slotModel = data.activeModel || slotProvider.model
+    const switched = prevName !== slotProvider.name || prevModel !== slotModel
+    agent.activeProvider = slotProvider.name
+    agent.activeModel = slotModel
+    agent.provider = { ...slotProvider }
+    if (slotModel) agent.provider.model = slotModel
+    // 重算 compactThreshold（auto 时——阈值跟模型走；原在 bin 的 switched 分支——收拢本处）
+    if (switched && agent.config?.agent?.compactThresholdAuto && agent.provider.model) {
+      agent.config.agent.compactThreshold = resolveCompactThreshold(null, agent.provider).value
     }
+    return switched
   }
+  // ② 槽 provider 没了 → D-S3 保留——静默保持现状（不报错不纠正——config 有效则静默用
+  //    config/defaultModel 运行时；两方都无效由调用侧复验 validateProvider 弹重选）
   return false
 }
 
@@ -429,6 +402,8 @@ export function newSession(cwd) {
       }
     : null
   saveManifest(cwd, m, deletions, { setActive: true })
+  // 2026-09-05 §10 D-4：/new 落点写本端记录（显式切换跟随——T-M8）
+  writeEndMarker(cwd, slot)
   return slot
 }
 
@@ -442,7 +417,7 @@ export function resetSessionState(agent) {
   agent.title = ""
   agent.tasks = []
   agent._sessionStart = null
-  agent._engDesignToken = null
+  // DESIGN-TOKEN-SETTLEMENT D3（2026-09-08）：单值镜像 `_engDesignToken` 退役——不再维护
   agent._engDesignTokens = new Map() // multi-design slots die with the session (2026-09-01 fix #2)
   agent._compressFailures = 0
   agent._verifyRetries = 0
@@ -456,7 +431,10 @@ export function resetSessionState(agent) {
   agent._slot = null
   agent._slotMtime = null
   agent._osReminderInjected = false
-  agent._restartReminderInjected = false
+  // §11.2（2026-09-08）：一次性注入标志换名——_restartReminderInjected 推断退役（F3——
+  // _sessionStart != null 伪触发）；/new 清零新标记——恢复武装/启动句标志不跨会话复活
+  agent._envResumed = false
+  agent._processRestartPending = false
   agent._lastEngState = false
 }
 
@@ -479,6 +457,8 @@ export function switchToSlot(cwd, slot) {
     m.slotSessions[slot] = getSessionId()
   }
   saveManifest(cwd, m, null, { setActive: true })
+  // 2026-09-05 §10 D-4：/session N 跟随"最后查看的槽"（成功切换才写）
+  writeEndMarker(cwd, slot)
   return data
 }
 

package/src/token-ttl.mjs

@@ -0,0 +1,274 @@
+/**
+ * token-ttl.mjs — design-token TTL 语义 + 槽位清理 + 会话槽权威台账 I/O（R16——2026-09-06；
+ * DESIGN-TOKEN-SETTLEMENT D1-D3——2026-09-08）。
+ *
+ * 共享目标（D-R16b）：过期判定语义在此定义一次，validateDesignToken
+ * （agent-tools/design-token.mjs）、恢复过滤（session.mjs applySession）、开模式清理
+ * （agent-tools/eng.mjs + tui/cmd-eng.mjs ON 路径）、spawn 门禁过期拒删槽
+ * （subagent-spawn.mjs）共引。
+ *
+ * token 格式 = `uuid:expiresAt`（无签名流程凭证——HMAC 防伪层已删——见
+ * ENGINEERING-MODE.md 2026-09-06 段）。过期判定只对**格式合法**的 token 判
+ * 过期：格式/畸形串不在此清理（恢复时读回由门禁格式拒、门禁拒时也不删槽——
+ * 防误删有效槽——F-R16b ①③）。
+ *
+ * DESIGN-TOKEN-SETTLEMENT（2026-09-08）：
+ * - **D1**：persistEngTokens = settle 当场落盘的可复用函数（engTokenSlotFields 序列化 +
+ *   session 安全写/轮转——guardForeignSlotFile 与 saveSession 共用同一份守卫）。
+ * - **D2/D3**：readEngTokensFromSlot / reconcileEngTokensFromSlot = 门禁 miss 回读权威
+ *   槽（spawn 门 D2 与 dispatch 写门 D3 同源 reconcile）。
+ * - **D3**：**单值镜像 `_engDesignToken` 退役**——AC3 零写 + 仅一次性迁移读。本模块
+ *   不再写镜像（engTokenSlotFields 只产多槽表）；restoreEngTokens 是唯一迁移读点（旧
+ *   slot 残留 engDesignToken → 迁入 Map，此后不写不读镜像）。
+ *
+ * 依赖方向：本模块只 import 底层槽 I/O（session-slots.mjs 原语 + session-guard.mjs 轮转
+ * 守卫）——session.mjs 同时 import 本模块（engTokenSlotFields/restoreEngTokens），形成
+ * 静态环，与既有的 session ↔ session-slots 环同构（函数声明实例化期已初始化、只函数体
+ * 内运行时使用——环安全）。
+ */
+
+import { existsSync, readFileSync, statSync } from "node:fs"
+import {
+  slotPath, writeSessionFile, activeSlot, loadManifest, saveManifest, slotDigest,
+  writeEndMarker,
+} from "./session-slots.mjs"
+// F2 轮转守卫自 2026-09-08 迁至 session-guard.mjs（session-slots 再越 500 行硬限拆分）
+import { guardForeignSlotFile } from "./session-guard.mjs"
+
+const DESIGN_TOKEN_UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+/** 格式校验 + 数值过期时刻：格式合法 → expiresAt 数值；格式/畸形 → null
+ *  （与 validateDesignToken 的 fail-closed 判定同源——单一权威）。 */
+export function tokenExpiryMs(token) {
+  if (!token || typeof token !== "string") return null
+  const parts = token.split(":")
+  if (parts.length !== 2) return null
+  const [uuid, expiresAt] = parts
+  if (!DESIGN_TOKEN_UUID_RE.test(uuid)) return null
+  if (!/^\d+$/.test(expiresAt)) return null
+  const expiry = parseInt(expiresAt, 10)
+  if (isNaN(expiry)) return null
+  return expiry
+}
+
+/** 过期判定——仅格式合法的 token 可判过期（畸形 → false，由门禁格式拒）。 */
+export function tokenExpired(token, now = Date.now()) {
+  const expiry = tokenExpiryMs(token)
+  return expiry !== null && now > expiry
+}
+
+/** 删一个 designId 槽（R16 D-R16c ③——spawn 门禁过期拒的清理面）。
+ *  条件由调用方保证（槽在位且槽值 === token 且已过期）：Map 无该 id / 值不符 →
+ *  不删（防误删有效槽）；designId 缺省（单槽省略 designId 路径）→ 按 token 扫删。
+ *  DESIGN-TOKEN-SETTLEMENT D3（2026-09-08）：单值镜像已退役——不再同步清镜像。
+ *  返回是否删了槽。 */
+export function removeDesignTokenSlot(agent, designId, token) {
+  const map = agent?._engDesignTokens
+  let slotRemoved = false
+  if (map instanceof Map && token) {
+    if (designId) {
+      if (map.get(designId) === token) {
+        map.delete(designId)
+        slotRemoved = true
+      }
+    } else {
+      for (const [id, t] of map) {
+        if (t === token) {
+          map.delete(id)
+          slotRemoved = true
+          break
+        }
+      }
+    }
+  }
+  return slotRemoved
+}
+
+/** 遍历删过期槽（R16 F-R16b ②——eng enter / cmd-eng ON 真转换路径）：Map 只留
+ *  有效 token。DESIGN-TOKEN-SETTLEMENT D3（2026-09-08）：单值镜像已退役——无
+ *  legacy 镜像分支。返回清理个数。 */
+export function purgeExpiredDesignTokens(agent) {
+  const map = agent?._engDesignTokens
+  let cleared = 0
+  if (map instanceof Map) {
+    for (const [id, t] of [...map]) {
+      if (typeof t === "string" && tokenExpired(t)) {
+        map.delete(id)
+        cleared++
+      }
+    }
+  }
+  return cleared
+}
+
+// ── 会话槽序列化/恢复面（session.mjs saveSession/applySession 的 token 字段——
+//    2026-09-06 R16：slot 持久化 = 跨重启/跨模式恢复的有意载体） ──
+
+/** saveSession 数据面：token 的序列化形态。多槽 Map → {designId: token}
+ *  （JSON-safe）；空/缺 Map → undefined → JSON.stringify 丢 key——清过的会话写
+ *  NO field，不从上次 save 复活槽。
+ *  DESIGN-TOKEN-SETTLEMENT D3（2026-09-08）：单值镜像 `engDesignToken` 退役——
+ *  saveSession 不再写镜像字段（AC3 零写）；只产多槽表 engDesignTokens。 */
+export function engTokenSlotFields(agent) {
+  return {
+    engDesignTokens: agent._engDesignTokens instanceof Map && agent._engDesignTokens.size > 0
+      ? Object.fromEntries(agent._engDesignTokens)
+      : undefined,
+  }
+}
+
+/** applySession 恢复面（F-R16b ①——恢复 TTL 过滤）：EXPIRED token 不读回（丢弃——
+ *  下次 save 自然清字段，清盘闭环）；格式/畸形串读回（门禁拒——不主动删——恢复不
+ *  得销毁它无法判定的槽数据）。
+ *  DESIGN-TOKEN-SETTLEMENT D3（2026-09-08）：单值镜像 `_engDesignToken` 退役——
+ *  本函数是**唯一镜像迁移读点**（AC3）：旧 slot 文件可能残留 engDesignToken 单值
+ *  （D3 前 saveSession 写的 legacy 字段）。当多槽表缺失/为空（Map 空）且残留镜像为
+ *  **格式合法且未过期** token 时 → 一次性迁入 Map（标 legacy——以 token 自身 uuid
+ *  为 designId——确定性、可复现、不依赖曾回显的原 designId）。此后该字段随下次
+ *  saveSession/persistEngTokens（不再写镜像）自然从槽文件消失，本函数不再读到
+ *  残留——一次性语义。镜像若已过期/畸形 → 不迁移（drop——与 Map 过期项同处理，
+ *  清盘闭环）。永不写 agent._engDesignToken。 */
+export function restoreEngTokens(agent, data) {
+  const map = new Map()
+  if (data.engDesignTokens && typeof data.engDesignTokens === "object" && !Array.isArray(data.engDesignTokens)) {
+    for (const [id, t] of Object.entries(data.engDesignTokens)) {
+      if (!(typeof t === "string" && tokenExpired(t))) map.set(id, t)
+    }
+  }
+  // legacy 单值镜像一次性迁移读（唯一镜像读点——AC3）：Map 空且残留为格式合法未过期 token
+  if (map.size === 0) {
+    const storedMirror = data.engDesignToken
+    if (typeof storedMirror === "string" && tokenExpiryMs(storedMirror) !== null && !tokenExpired(storedMirror)) {
+      map.set(storedMirror.split(":")[0], storedMirror)
+    }
+  }
+  if (map.size > 0) agent._engDesignTokens = map
+  else delete agent._engDesignTokens
+}
+
+// ── 会话槽权威台账 I/O（DESIGN-TOKEN-SETTLEMENT D1/D2/D3——槽文件 = 权威结算台账） ──
+
+/** 当前会话槽号（读侧——无认领副作用）：粘性 _slot 优先；未钉槽时读 manifest active
+ *  （loadManifest 只读——不在门禁路径触发认领写）。无槽 → null。 */
+function currentSlotNoReadOnly(agent) {
+  const slot = agent?._slot
+  if (Number.isInteger(slot)) return slot
+  const active = loadManifest(agent?.cwd)?.active
+  return Number.isInteger(active) ? active : null
+}
+
+/** 读当前会话槽文件的权威台账（engDesignTokens 多槽表——不做 TTL 过滤，判定由调用方）。
+ *  门禁侧轻读：JSON.parse 只读不改文件（.tmp 回退/改名等 loadSlotFile 副作用不引入）。
+ *  单值镜像 engDesignToken 字段已退役——此处不读（AC3——运行时零镜像读；唯一镜像
+ *  迁移读在 restoreEngTokens）。返回 {designId: token} 对象或 null（无槽/无文件/不可读）。 */
+export function readEngTokensFromSlot(agent) {
+  try {
+    const slot = currentSlotNoReadOnly(agent)
+    if (slot == null) return null
+    const p = slotPath(agent.cwd, slot)
+    if (!existsSync(p)) return null
+    const data = JSON.parse(readFileSync(p, "utf8"))
+    return (data && typeof data === "object" && !Array.isArray(data.engDesignTokens)
+      && data.engDesignTokens && typeof data.engDesignTokens === "object")
+      ? data.engDesignTokens
+      : null
+  } catch { return null }
+}
+
+/** 内存 miss 时从权威槽 reconcile（D2 spawn 门 + D3 dispatch 写门同源）：把槽文件中
+ *  **未过期**项并进内存 Map（TTL 过滤保留——expired 不并入，fail-closed；格式/畸形串
+ *  与 restoreEngTokens 同语义读回——门禁格式拒）；槽无活项 → 内存原样。返回判定用 Map。 */
+export function reconcileEngTokensFromSlot(agent) {
+  const slots = agent?._engDesignTokens
+  const obj = readEngTokensFromSlot(agent)
+  if (!obj) return slots instanceof Map ? slots : new Map()
+  const live = new Map()
+  for (const [id, t] of Object.entries(obj)) {
+    if (typeof t === "string" && !tokenExpired(t)) live.set(id, t)
+  }
+  if (live.size === 0) return slots instanceof Map ? slots : new Map()
+  const merged = slots instanceof Map ? slots : new Map()
+  for (const [id, t] of live) merged.set(id, t)
+  agent._engDesignTokens = merged
+  return merged
+}
+
+/** 是否存在任一活槽（DESIGN-TOKEN-SETTLEMENT D3——dispatch 写门判定"任一活槽存在"；
+ *  AC4）。先问内存 Map（当前进程活缓存）；miss 回读权威槽文件 reconcile（与 spawn 门
+ *  D2 同源）。判定 fail-closed：格式合法且未过期才算活槽（畸形/过期不构成活槽——不
+ *  授权产品代码写）。 */
+export function anyLiveDesignSlot(agent) {
+  const live = (m) => {
+    for (const t of m.values()) {
+      if (typeof t === "string" && tokenExpiryMs(t) !== null && !tokenExpired(t)) return true
+    }
+    return false
+  }
+  const m = agent?._engDesignTokens
+  if (m instanceof Map && live(m)) return true
+  const rec = reconcileEngTokensFromSlot(agent)
+  return rec instanceof Map && live(rec)
+}
+
+/**
+ * D1（DESIGN-TOKEN-SETTLEMENT，2026-09-08）：settle 当场同步落盘——把当前内存多槽
+ * Map 写入会话槽文件的权威台账，消除 settle→回合尾 saveSession 间的重启丢 token 窗口。
+ * 复用 engTokenSlotFields 序列化 + session 安全写/轮转（guardForeignSlotFile =
+ * saveSession 同一份守卫——勿裸写文件）。槽文件缺失（本会话首次落盘）→ 写最小全新
+ * 记录（字段形状同 saveSession——loadSlotFile 可读）；既有文件 → 读-改-写（只动 token
+ * 字段，历史等其他字段原样保留）。写失败（writeSessionFile/parse 抛错）→ 抛出/返回
+ * false——调用方（settle）失败即 settle 失败（token 不注册、可重评——评审 #1 语义）。
+ */
+export function persistEngTokens(agent) {
+  const claimedNow = agent._slot == null
+  const slot = agent._slot ??= activeSlot(agent.cwd)
+  if (claimedNow) writeEndMarker(agent.cwd, slot)
+  const p = slotPath(agent.cwd, slot)
+  guardForeignSlotFile(agent, p, slot)
+  let data = null
+  if (existsSync(p)) {
+    data = JSON.parse(readFileSync(p, "utf8"))
+  } else {
+    // 全新槽（claim 先行、首保存落盘前）——最小记录（VSC newSlotData 同构——字段形状
+    // 同 saveSession 数据面，loadSlotFile 校验可读；历史留空——本会话首保存尚未发生，
+    // 此前历史本就未落盘，token 台账先行落盘不制造任何额外损失）。
+    data = {
+      version: 2,
+      cwd: agent.cwd,
+      title: agent.title ?? "",
+      activeProvider: agent.activeProvider ?? agent.provider?.name,
+      // MODEL-MERGE-SESSION 恒非空形态：随 saveSession 同款回落链（无渠道仍容忍 null）
+      activeModel: agent.activeModel ?? agent.provider?.model ?? null,
+      history: [],
+      contextHistory: [],
+      tasks: agent.tasks ?? [],
+      planMode: agent.planMode ?? false,
+      autoApprove: agent.autoApprove ?? false,
+      engineering: agent.config?.agent?.engineering ?? false,
+      goal: agent.goal ?? null,
+      advisor: agent.config?.advisor ?? null,
+      pendingReminders: agent._pendingReminders ?? [],
+      sessionStart: agent._sessionStart ?? null,
+    }
+  }
+  const fields = engTokenSlotFields(agent)
+  if (fields.engDesignTokens !== undefined) data.engDesignTokens = fields.engDesignTokens
+  else delete data.engDesignTokens
+  // 单值镜像字段永不复写（D3 零写）——残留 engDesignToken 随本次写一并清（更快退役，
+  // 杜绝 stale 镜像 + 空 Map 组合在下次 restore 二次迁移复活死 token 的边角）。
+  delete data.engDesignToken
+  data.updatedAt = Date.now()
+  writeSessionFile(p, data)
+  // 记录我们刚写的 mtime——下次保存/守卫跳过重复解析（saveSession 同款）
+  try { agent._slotMtime = statSync(p).mtimeMs } catch {}
+  // Update slot metadata in manifest（saveSession 同款尾——非致命：数据已安全，
+  // metadata 下次 listSlots 惰性恢复）
+  try {
+    const m = loadManifest(agent.cwd)
+    m.slots[slot] = slotDigest(data)
+    saveManifest(agent.cwd, m)
+  } catch (e) {
+    console.error(`[session] manifest metadata update failed for slot ${slot}: ${e.message}`)
+  }
+  return true
+}