thincoder 0.12.59 → 0.12.60

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.
@@ -15,15 +17,30 @@ import { readFileSync, renameSync, existsSync, statSync } from "node:fs"
 import { basename } from "node:path"
 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 ==========
 
@@ -115,60 +132,29 @@ 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-slots.mjs——DESIGN-TOKEN-
+  // SETTLEMENT D1）——saveSession 与 token-ttl persistEngTokens（settle 当场落盘）
+  // 共用同一份（检查按 mtime 缓存 _slotMtime：自写未变跳过全量解析）。
+  // 守卫自 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 的完整值。
@@ -320,15 +282,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).
@@ -429,6 +384,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 +399,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
@@ -479,6 +436,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,273 @@
+/**
+ * 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,
+      activeModel: agent.activeModel ?? 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
+}

package/src/tools/checklist-sync.mjs

@@ -0,0 +1,181 @@
+/**
+ * checklist-sync.mjs — checklist 并发写同步机（R10 F4，MULTI-INSTANCE-COLLAB.md §2a.3
+ * ——2026-09-06，自 checklist.mjs 拆出：门控 + 合并 + 序列化——防 checklist.mjs 超 300
+ * 行 advisory 线；本模块为纯同步机制，不持 checklist 业务状态）。
+ *
+ * 双端 checklist 同路径 {cwd}/.thincoder/checklist.md——多实例并发写原为裸整文件覆盖
+ * （丢项）。写前 mtime 门控 + ID 键合并（评审修正 #6 基线规则：基线 = 本读-改-写链内
+ * 最近一次 stat 的 mtime；本进程自写后刷新——parse 规范化写回不误触发 merged/重分配）。
+ * .bak 不做（决策点② A：cwd 在 git 仓库内——git 兜底现场）。
+ *
+ * 冲突语义（flushWrite 内收口）：写前 stat ≠ 基线（对端并发写过）→ 重读磁盘 → 双方
+ * union by ID（本端新增 + 盘上他端新增都保留；同 ID 不同文本 → 盘上保留、本端重分配
+ * max+1 续分配；同 ID 仅状态不同 → in_progress 胜过 pending——标记不丢）；checklist
+ * 文件合并时按 done 文件归档 ID 排除（含子任务点号 ID——并发 mark-done 的"盘上有旧
+ * pending 副本"不复活已归档项——done 集合 union 的另一半）。checklist-done.md 自身
+ * 合并 = 纯 union（无归档排除）。
+ *
+ * 调用方（checklist.mjs）通过 flushWrite 的 opts 注入：reread（磁盘无写回重读）、
+ * doneFile 路径、isDone（目标文件是否为 done 文件）——避免本模块反向依赖 checklist
+ * 的 parse/树结构。
+ */
+import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs"
+
+const baselines = new Map() // filePath → 最近一次读的 stat mtime（null = 读时文件缺失）
+
+/** F4 测试缝（伪属主范式——T-F4a..d）：在每次写前门控处注入"对端写盘"钩子——模拟本链
+ *  parse 后、write 前对端实例的真实并发写。生产不设置（null → 零行为影响）。 */
+let writeGateHook = null
+export function _setWriteGateHookForTest(fn) { writeGateHook = fn }
+
+/** 文件缺失 → null（门控 t0 基线形态）。 */
+export function statMtime(p) {
+  try { return statSync(p).mtimeMs } catch { return null }
+}
+
+/** 调用方（parse 读链）登记基线——读后写链以它为门控比对基准。 */
+export function noteReadBaseline(filePath, mtime) {
+  baselines.set(filePath, mtime)
+}
+
+/** Done 文件归档根 ID 清单（含子任务点号 ID：T1 与 T1.2 都进——归档排除用；编号预留
+ *  nextRootId 的 /^T(\d+)$/ 过滤不受影响）。 */
+export function readDoneRoots(doneFile) {
+  if (!existsSync(doneFile)) return []
+  const roots = []
+  for (const line of readFileSync(doneFile, "utf-8").split("\n")) {
+    const m = line.match(/^- \[.\] ((?:T\d+)(?:\.\d+)*): /)
+    if (m) roots.push({ id: m[1] })
+  }
+  return roots
+}
+
+/** Serialize items to markdown lines (2-space indent per depth) — tree structure preserved. */
+function renderItems(nodes, depth, out) {
+  const indent = "  ".repeat(depth)
+  for (const item of nodes) {
+    const mark = item.status === "done" ? "x" : item.status === "in_progress" ? "~" : " "
+    const label = item.id ? `${item.id}: ${item.text}` : item.text
+    out.push(`${indent}- [${mark}] ${label}`)
+    if (item.children?.length) renderItems(item.children, depth + 1, out)
+  }
+}
+
+/**
+ * 门控 + 合并 + 写（F4 收口——parse 规范化写回 / add / mark 双写都经它）。
+ * @param filePath 目标文件（checklist.md 或 checklist-done.md）
+ * @param items 本端（读-改-写链产物）的顶层 items
+ * @param opts.reread 磁盘无写回重读函数（返回盘上顶层 items——合并触发时调用）
+ * @param opts.doneFile done 文件路径（checklist 合并的归档排除源）
+ * @param opts.isDone 目标文件是否为 done 文件（true = 纯 union，无归档排除）
+ * @returns { merged, items }——merged=true 时 items 为落盘真相（本端节点原地重分配——
+ *   调用方持有的引用/消息读到的即最终 ID）；merged=false 时 items 为原输入。
+ */
+export function flushWrite(filePath, items, { reread, doneFile, isDone }) {
+  if (writeGateHook) writeGateHook(filePath) // 测试缝：模拟对端此刻写盘
+  const base = baselines.get(filePath) // undefined = 本链无读（防御——无基线无从门控）
+  const now = statMtime(filePath)
+  let finalItems = items
+  let merged = false
+  if (base !== undefined && now !== base) {
+    // 磁盘被对端并发改过（本链读后）→ 重读磁盘 + 合并（ID union）
+    const diskItems = reread()
+    finalItems = mergeItems(diskItems, items, doneFile, isDone)
+    merged = true
+  }
+  const out = []
+  renderItems(finalItems, 0, out)
+  writeFileSync(filePath, out.join("\n") + "\n")
+  baselines.set(filePath, statMtime(filePath)) // 自写后刷新基线（防自写误判并发）
+  return { merged, items: finalItems }
+}
+
+// ── F4 合并（ID 键 union）─────────────────────────────────────────────────────
+
+function flattenTree(nodes, out = []) {
+  for (const n of nodes) {
+    out.push(n)
+    if (n.children?.length) flattenTree(n.children, out)
+  }
+  return out
+}
+
+/** 层内递归合并（磁盘序在前；本端独有/重分配项追加尾部）——规则见文件头注释。 */
+function mergeLevel(diskNodes, ourNodes, env) {
+  const diskById = new Map(diskNodes.filter((n) => n.id != null).map((n) => [n.id, n]))
+  const ourById = new Map(ourNodes.filter((n) => n.id != null).map((n) => [n.id, n]))
+  const result = []
+  const pending = [] // 本端独有 + 同 ID 异文本（待重分配）——追加在磁盘序之后
+  for (const d of diskNodes) {
+    if (d.id != null && !env.isDone && env.doneIds.has(d.id)) continue // 已归档（对端 mark-done）→ 不复活
+    const o = d.id != null ? ourById.get(d.id) : null
+    if (!o) { result.push(d); continue } // 盘上独有 → 整棵保留
+    const childEnv = { ...env, prefix: `${d.id}.` } // 子层重分配域 = 父 ID 前缀（"T1" → "T1."）
+    if (o.text === d.text && o.status === d.status) {
+      // 双端同一节点（parse 规范化幂等场景）→ 去重；子树仍逐层合并（防丢任一端子新增）
+      d.children = mergeLevel(d.children ?? [], o.children ?? [], childEnv)
+      result.push(d)
+      continue
+    }
+    if (o.text === d.text) {
+      // 仅状态不同 → in_progress 胜过 pending（标记意图不丢；同文本不可能 pending×pending）
+      const carry = d.status === "in_progress" ? d : o
+      carry.children = mergeLevel(d.children ?? [], o.children ?? [], childEnv)
+      result.push(carry)
+      continue
+    }
+    // 同 ID 不同文本（并发 add 各自从同基线分到同号）→ 盘上保留；本端项排队重分配
+    result.push(d)
+    pending.push(o)
+  }
+  for (const o of ourNodes) {
+    if (o.id == null) { pending.push(o); continue } // 无 ID 行（理论极少——parse 已归一）→ 原样追加
+    if (!env.isDone && env.doneIds.has(o.id)) continue // 本端项已被归档 → 丢弃（不复活）
+    if (!diskById.has(o.id)) pending.push(o) // 本端独有 → 保留（含子树）
+    // 共享 ID 已在磁盘循环处理（去重/状态/文本冲突排队）
+  }
+  for (const o of pending) {
+    if (o.id != null && diskById.has(o.id)) reassignNode(o, env) // 文本冲突项 → 重分配 max+1 续分配
+    result.push(o)
+  }
+  return result
+}
+
+/** 重分配：层前缀（根 "T" / 子树 `${parentId}.`）下 max+1；子树 ID 前缀同步换新
+ *  （"T4.1" → "T5.1"——ID 层级与父节点保持一致）。原地改——调用方引用即最终 ID。 */
+function reassignNode(node, env) {
+  let max = 0
+  for (const id of env.allIds) {
+    if (!id?.startsWith(env.prefix)) continue
+    const suffix = id.slice(env.prefix.length)
+    if (/^\d+$/.test(suffix)) max = Math.max(max, parseInt(suffix))
+  }
+  const oldId = node.id
+  const newId = `${env.prefix}${max + 1}`
+  node.id = newId
+  env.allIds.add(newId)
+  if (oldId) renameSubtreePrefixes(node, oldId, newId)
+}
+
+function renameSubtreePrefixes(node, oldId, newId) {
+  for (const c of node.children ?? []) {
+    if (c.id?.startsWith(`${oldId}.`)) {
+      c.id = newId + c.id.slice(oldId.length)
+      renameSubtreePrefixes(c, oldId, newId)
+    }
+  }
+}
+
+/** 合并入口：isDone = checklist-done 文件（纯 union——无归档排除）；否则按 done 文件
+ *  当前归档 ID 排除（含点号子 ID——对端 mark-done 归档的项不因本端旧 parse 复活）。 */
+function mergeItems(diskItems, ourItems, doneFile, isDone) {
+  const doneRoots = isDone ? [] : readDoneRoots(doneFile)
+  const doneIds = new Set(doneRoots.map((r) => r.id))
+  const allIds = new Set() // 重分配 max 计算域：双端全树 + 归档根（根层防撞）
+  for (const n of flattenTree(diskItems).concat(flattenTree(ourItems))) {
+    if (n.id != null) allIds.add(n.id)
+  }
+  for (const id of doneIds) allIds.add(id)
+  const env = { isDone, doneIds, allIds, prefix: "T" } // 根层前缀 "T"；子层在 mergeLevel 递归时推导
+  return mergeLevel(diskItems, ourItems, env)
+}