thincoder 0.12.59 → 0.12.60

package/src/session-gc.mjs

@@ -0,0 +1,214 @@
+/**
+ * session-gc.mjs — 会话目录残留 GC + 冷 cwd 报告/删除（SESSION.md §12，2026-09-06）。
+ *
+ * F1 残留 GC（自动）：进程启动时对当前 cwd hash 前缀做一次轻量清理——.corrupted /
+ * .unreadable / .manifest.corrupted / .bak-* 保留 30 天，孤儿 .tmp 保留 7 天
+ *（mtime < now − retention 才删，等于保留期保留——older-than 边界语义）。
+ * 安全（N1）：活跃槽（主文件在 + manifest slotSessions[N] 属主活）的现场一律保留；
+ * manifest 主文件 / end marker / 数据主文件永不进入候选（后缀预过滤只匹配残留后缀）。
+ *
+ * F2 冷 cwd（手动——12.2.4 三步，v1 不自动删 manifest）：
+ *   判定：manifest mtime 距今 > 90 天 且 无任何活跃数据文件（.json.N 不存在或全部属死主）；
+ *   报告：thincoder session gc --dry-run（跨 cwd 枚举，不删除）；
+ *   删除：thincoder session gc --confirm <hash|--all>（整前缀清空——manifest+marker+
+ *         .json.N 死主数据+裸 v1 {hash}.json（§12.7 D-V1）+残留；删除前重校验冷态——
+ *         TOCTOU 防护 T12）。
+ *
+ * 拆分理由（§12.3 review #1）：session-slots.mjs 已在 500 行硬限零余量，GC 是独立决策
+ * （"何时清何种残留"），独立成模块；原语（sessionPath/isProcessAlive）自 session-slots
+ * import，启动钩子（session.mjs resumeSlot 包装）只一行调用。
+ */
+
+import { readdirSync, readFileSync, statSync, unlinkSync, existsSync } from "node:fs"
+import { join, dirname, basename } from "node:path"
+import { configDir } from "./config.mjs"
+import { sessionPath, isProcessAlive } from "./session-slots.mjs"
+
+/** 保留期（§12.2.2）：损坏现场（.corrupted/.unreadable/.manifest.corrupted）与并发轮转
+ *  备份（.bak-*）30 天；孤儿 .tmp 7 天（崩溃现场恢复窗口）。 */
+export const RESIDUE_RETENTION_MS = 30 * 24 * 3600 * 1000
+export const ORPHAN_TMP_RETENTION_MS = 7 * 24 * 3600 * 1000
+/** 冷 cwd 阈值（§12.2.4）：manifest mtime 距今 > 90 天（保守——正常开发会频繁触碰）。 */
+export const COLD_CWD_RETENTION_MS = 90 * 24 * 3600 * 1000
+
+function sessionsDir() { return join(configDir, "sessions") }
+
+/** 残留分类（§12.2.2 后缀表）：name 须以 `${prefix}.` 开头（prefix = `${hash}.json`）。
+ *  返回 { retention, slot, tmp } 或 null（主文件/end marker/他前缀——不动）。
+ *  slot = 关联槽号（`.N.` 段），无则 null（如 .manifest.corrupted）。 */
+function classifyResidue(name, prefix) {
+  if (!name.startsWith(prefix + ".")) return null
+  const slotMatch = name.slice(prefix.length).match(/^\.(\d+)\./)
+  const slot = slotMatch ? Number(slotMatch[1]) : null
+  if (name.endsWith(".corrupted") || name.endsWith(".unreadable")) return { retention: RESIDUE_RETENTION_MS, slot, tmp: false }
+  if (/\.bak-\d+$/.test(name)) return { retention: RESIDUE_RETENTION_MS, slot, tmp: false }
+  if (name.endsWith(".tmp")) return { retention: ORPHAN_TMP_RETENTION_MS, slot, tmp: true }
+  return null
+}
+
+/** 活跃槽集合（§12.4 T3/T12 操作定义）：.json.N 主文件存在 且 manifest slotSessions[N]
+ *  属主进程存活。manifest 缺失/损坏 → 空集（无活跃槽——不阻碍残留清理）。 */
+function liveSlots(dir, prefix, aliveFn) {
+  const active = new Set()
+  try {
+    const m = JSON.parse(readFileSync(join(dir, `${prefix}.manifest`), "utf8"))
+    for (const [n, owner] of Object.entries(m.slotSessions ?? {})) {
+      if (!/^\d+$/.test(n) || !owner) continue
+      if (!existsSync(join(dir, `${prefix}.${n}`))) continue
+      const pid = parseInt(String(owner).split("-")[0])
+      if (pid && aliveFn(pid)) active.add(Number(n))
+    }
+  } catch { /* manifest 不可读 → 无活跃槽 */ }
+  return active
+}
+
+/**
+ * 残留 GC（§12.2.3——单 cwd 前缀，不跨 cwd 扫描）：返回 { candidates, deleted }
+ * （dryRun 时 candidates 照列、deleted 为空——只列不删，N2 可预览）。
+ * 扫描先按后缀预过滤（N4——只 stat 残留候选），再对候选做活跃槽/孤儿/保留期判定。
+ */
+export function gcResidue({ dir = sessionsDir(), prefix, now = Date.now(), dryRun = false, aliveFn = isProcessAlive } = {}) {
+  const result = { candidates: [], deleted: [] }
+  let entries
+  try { entries = readdirSync(dir) } catch { return result }
+  const candidates = []
+  for (const name of entries) {
+    const c = classifyResidue(name, prefix)
+    if (c) candidates.push({ name, ...c })
+  }
+  if (!candidates.length) return result
+  const active = liveSlots(dir, prefix, aliveFn)
+  for (const c of candidates) {
+    if (c.slot !== null && active.has(c.slot)) continue // N1：活跃槽现场一律保留（T3）
+    const p = join(dir, c.name)
+    if (c.tmp && existsSync(p.slice(0, -".tmp".length))) continue // 非孤儿 .tmp（主文件在——写中/回退候选）
+    let st
+    try { st = statSync(p) } catch { continue }
+    if (st.mtimeMs >= now - c.retention) continue // 边界：older-than 才删，等于保留期保留（§12.4）
+    result.candidates.push(c.name)
+    if (!dryRun) {
+      try { unlinkSync(p); result.deleted.push(c.name) } catch { /* 占用/竞态——跳过 */ }
+    }
+  }
+  return result
+}
+
+const scheduledPrefixes = new Set()
+
+/** 启动钩子（§12 review #8——N4）：GC 延后到进程启动完成后空闲执行（setImmediate），
+ *  不阻塞启动路径；每进程每前缀一次（Set 去重——resumeSlot 可多次进入）。 */
+export function scheduleSessionGC(cwd) {
+  let base
+  try { base = sessionPath(cwd) } catch { return }
+  if (scheduledPrefixes.has(base)) return
+  scheduledPrefixes.add(base)
+  setImmediate(() => {
+    try { gcResidue({ dir: dirname(base), prefix: basename(base) }) } catch { /* 清理失败静默——不影响主流程 */ }
+  })
+}
+
+/**
+ * 冷 cwd 枚举（§12.2.4 步骤 1/2——跨 cwd 报告面，仅手动命令调用）：候选 =
+ * manifest mtime 距今 > 90 天 且 无活跃数据文件（.json.N 主文件不存在或全部属死主进程）。
+ * 返回 [{ hash, prefix, manifestMtime, dataFiles, files }]（files = 整前缀全部文件——
+ * 含裸 v1 `{hash}.json`，§12.7 D-V1——dataFiles 仅 .json.N，v1 不参与冷态判定）。
+ */
+export function listColdCwds({ dir = sessionsDir(), now = Date.now(), aliveFn = isProcessAlive } = {}) {
+  let entries
+  try { entries = readdirSync(dir) } catch { return [] }
+  const cold = []
+  for (const name of entries) {
+    if (!name.endsWith(".json.manifest")) continue // end marker（.manifest.cli/.vscode）与 .manifest.corrupted 天然排除
+    const prefix = name.slice(0, -".manifest".length) // `${hash}.json`
+    let st
+    try { st = statSync(join(dir, name)) } catch { continue }
+    if (st.mtimeMs >= now - COLD_CWD_RETENTION_MS) continue // 近期活跃（<90 天阈值——T10）
+    let m
+    try { m = JSON.parse(readFileSync(join(dir, name), "utf8")) } catch { continue } // 损坏 manifest 不判冷（.corrupted 归残留 GC）
+    const dataFiles = entries.filter((e) => e.startsWith(prefix + ".") && /^\d+$/.test(e.slice(prefix.length + 1)))
+    const hasLive = dataFiles.some((e) => {
+      const owner = m.slotSessions?.[e.slice(prefix.length + 1)]
+      const pid = parseInt(String(owner ?? "").split("-")[0])
+      return !!(pid && aliveFn(pid))
+    })
+    if (hasLive) continue // 有活跃数据文件 → 非冷（T12）
+    cold.push({
+      hash: prefix.slice(0, -".json".length),
+      prefix,
+      manifestMtime: st.mtimeMs,
+      dataFiles: dataFiles.length,
+      files: entries.filter((e) => e.startsWith(prefix + ".") || e === prefix), // 整前缀清空含裸 v1 {hash}.json（§12.7 D-V1）
+    })
+  }
+  return cold
+}
+
+/**
+ * 删除指定冷 cwd 的整个前缀（§12.2.4 步骤 3——manifest+end marker+.json.N 死主数据+
+ * 裸 v1 {hash}.json（§12.7 D-V1）+残留；只删 manifest 留数据文件会制造孤儿数据，整前缀清空才真正释放）。
+ * 删除前重跑冷 cwd 判定（TOCTOU 防护，T12——期间变活跃则拒绝）。
+ */
+export function deleteColdCwd(hash, { dir = sessionsDir(), now = Date.now(), aliveFn = isProcessAlive } = {}) {
+  const target = listColdCwds({ dir, now, aliveFn }).find((c) => c.hash === hash)
+  if (!target) return { ok: false, reason: "not-cold", deleted: [] }
+  const deleted = []
+  for (const name of target.files) {
+    try { unlinkSync(join(dir, name)); deleted.push(name) } catch { /* 占用/竞态——跳过 */ }
+  }
+  return { ok: true, deleted }
+}
+
+/**
+ * `thincoder session gc` 子命令分发（§12.2.3/12.2.4 手动面——F2 执行入口仅 CLI，
+ *  VS Code 端无 shell 子命令通道，review #7）：
+ *   --dry-run          报告当前 cwd 残留候选 + 跨 cwd 冷候选（只列不删，N2 预览）
+ *   --confirm <hash>   删除指定冷 cwd 整前缀（警告 + 文件清单 + TOCTOU 重校验）
+ *   --confirm --all    逐冷 cwd 同型警告删除
+ * 返回进程退出码（0/1）。dir/prefix/now/out/err/aliveFn 为测试注入缝（默认生产行为）。
+ */
+export function runSessionGc(args, { dir = sessionsDir(), prefix = null, cwd = process.cwd(), now = Date.now(), out = console.log, err = console.error, aliveFn = isProcessAlive } = {}) {
+  const dryRun = args.includes("--dry-run")
+  const confirmIdx = args.indexOf("--confirm")
+  const hasConfirm = confirmIdx >= 0
+  const confirmTarget = hasConfirm ? args[confirmIdx + 1] : null
+  // --dry-run 与 --confirm 互斥（review 🔵#4——同给时不得静默忽略 confirm；无值 --confirm 同为用法错误）
+  if (args[0] !== "gc" || (!dryRun && !hasConfirm) || (dryRun && hasConfirm) || (hasConfirm && !confirmTarget)) {
+    err("Usage: thincoder session gc --dry-run | --confirm <hash> | --confirm --all")
+    return 1
+  }
+
+  if (dryRun) {
+    out("Session GC dry-run — no files will be deleted.")
+    // 当前 cwd 残留（§12.2.3 删除面——自动 GC 的预览）
+    let p = prefix
+    if (!p) { try { p = basename(sessionPath(cwd)) } catch { p = null } }
+    const residue = p ? gcResidue({ dir, prefix: p, now, dryRun: true, aliveFn }) : { candidates: [] }
+    out(`Residue candidates for current project (${p ?? "unknown"}): ${residue.candidates.length}`)
+    for (const name of residue.candidates) out(`  ${name}`)
+  }
+
+  const cold = listColdCwds({ dir, now, aliveFn })
+  if (dryRun) {
+    out(`Cold project candidates (manifest idle > 90 days, no live data files): ${cold.length}`)
+    for (const c of cold) {
+      out(`  ${c.hash}  manifest mtime ${new Date(c.manifestMtime).toISOString()}  data files ${c.dataFiles}  total files ${c.files.length}`)
+    }
+    if (cold.length) out('Run "thincoder session gc --confirm <hash>" (or --confirm --all) to permanently delete a cold project prefix.')
+    return 0
+  }
+
+  // --confirm：删除前警告（N2 可逆——文件清单 + 永久删除提示）；deleteColdCwd 内部重校验冷态（TOCTOU）
+  const targets = confirmTarget === "--all" ? cold : cold.filter((c) => c.hash === confirmTarget)
+  if (!targets.length) {
+    err(`Refused: ${confirmTarget} is not a cold project (active, recent, or unknown) — nothing deleted.`)
+    return 1
+  }
+  for (const t of targets) {
+    out(`WARNING: 此操作永久删除该 cwd 的全部会话历史 (hash ${t.hash}, ${t.files.length} files):`)
+    for (const name of t.files) out(`  ${name}`)
+    const r = deleteColdCwd(t.hash, { dir, now, aliveFn })
+    if (!r.ok) { err(`Refused: ${t.hash} is no longer cold (became active) — skipped.`) ; continue }
+    out(`Deleted ${r.deleted.length} files for ${t.hash}.`)
+  }
+  return 0
+}

package/src/session-guard.mjs

@@ -0,0 +1,47 @@
+/**
+ * session-guard.mjs — F2 轮转守卫（2026-08-31 会诊 F2 🔴；2026-09-08 DESIGN-TOKEN-
+ * SETTLEMENT D1 自 session-slots.mjs 提取——session-slots 再越 500 行硬限，本守卫约 41
+ * 行随迁，verbatim 零语义变）：saveSession 与 token-ttl persistEngTokens 共用同一份。
+ * 写前校验磁盘槽文件是否本进程会话的现场——磁盘文件 sessionStart 与本进程会话不符
+ * （另一进程/会话的现场）/版本更新/异 cwd → 先轮转 .bak 保留再写。检查按 mtime 缓存
+ * （agent._slotMtime）：文件自上次检查/自写未变就跳过全量解析——每次保存都
+ * readFileSync+JSON.parse 多 MB 会话 → O(n²) 退化。文件存在但不可读（损坏/半写）→
+ * 改名 .corrupted 保留现场。返回轮转的 .bak 路径或 null。
+ */
+
+import { existsSync, readFileSync, renameSync, statSync } from "node:fs"
+import { basename } from "node:path"
+
+export function guardForeignSlotFile(agent, p, slot) {
+  try {
+    if (!existsSync(p)) return null
+    const st = statSync(p)
+    if (st.mtimeMs === (agent._slotMtime ?? -1)) return null
+    const disk = JSON.parse(readFileSync(p, "utf8"))
+    // version>2 的新版文件无论 sessionStart 一律轮转（loadSlotFile 对 v3 返回 null 不动
+    // 文件——若其 sessionStart 为 null，旧版首次保存会静默覆盖；轮转 .bak 保证新版文件
+    // 保留）。磁盘文件 cwd 不匹配（异项目文件误落本路径）同样轮转——与 loadSlotFile/
+    // legacy 读的"别人的文件不动"原则对齐。
+    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)
+      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
+      return bak
+    }
+    agent._slotMtime = st.mtimeMs
+    return null
+  } catch {
+    // 文件存在但不可读（损坏/半写）：改名 .corrupted 保留现场（2026-09-01 advisor 🔵——
+    // 与自身 loadSlotFile 的 .corrupted 约定 + VS Code saveSessionToSlot 对齐；.bak 保留
+    // 给 F2 轮转路径，损坏现场不再混入轮转后缀）。
+    if (existsSync(p)) {
+      try { renameSync(p, `${p}.corrupted`) } catch {}
+    }
+    return null
+  }
+}

package/src/session-rename.mjs

@@ -0,0 +1,38 @@
+/**
+ * session-rename.mjs — 槽位重命名（标题写路径）。2026-09-06 自 session-slots.mjs 拆出：
+ * §12.2.5 契约改（boolean → { ok, reason }）使 session-slots.mjs 超 500 行硬限
+ *（§12.3 授权——"若 >500 则按 §10.6 先例拆文件，一并拆出 renameSlot"）。
+ * 原语（slotPath/manifest 读写）自 session-slots.mjs import；session.mjs re-export
+ * renameSlot 保持既有调用点（cmd-session.mjs / 测试经 session.mjs）不变。
+ */
+
+import { readFileSync, existsSync, statSync } from "node:fs"
+import { slotPath, loadManifest, saveManifest, slotDigest, writeSessionFile } from "./session-slots.mjs"
+
+/** Rename a slot: update the slot file's title + the manifest metadata (shared with VS Code).
+ *  2026-09-01 会诊 glm 🟡：写回前按 mtime 门控重读——原实现读全量→改 title→整文件写回，
+ *  窗口内并发方的最新保存会被旧数据覆盖（丢消息）；mtime 变了即放弃本次重命名。
+ *  2026-09-06 §12.2.5：契约 boolean → { ok, reason? }（file-missing/parse-failure/mtime-conflict/invalid-slot，F3 失败可见）；_stat = mtime-conflict 测试缝（默认 statSync）。 */
+export function renameSlot(cwd, slot, title, _stat = statSync) {
+  const n = Number(slot)
+  if (!Number.isInteger(n) || n < 1) return { ok: false, reason: "invalid-slot" }
+  const p = slotPath(cwd, n)
+  if (!existsSync(p)) return { ok: false, reason: "file-missing" }
+  let data
+  try {
+    data = JSON.parse(readFileSync(p, "utf8"))
+  } catch {
+    return { ok: false, reason: "parse-failure" }
+  }
+  const t0 = _stat(p).mtimeMs
+  data.title = title
+  // 读与写之间文件被并发方改过 → 放弃（保留并发内容，重命名下次重试）
+  if (_stat(p).mtimeMs !== t0) return { ok: false, reason: "mtime-conflict" }
+  writeSessionFile(p, data)
+  const m = loadManifest(cwd)
+  if (m.slots[n]) {
+    m.slots[n] = slotDigest(data)
+    saveManifest(cwd, m)
+  }
+  return { ok: true }
+}

package/src/session-slots.mjs

@@ -9,11 +9,15 @@
  */
 
 import { createHash } from "node:crypto"
-import { mkdirSync, readFileSync, writeFileSync, renameSync, unlinkSync, existsSync, statSync } from "node:fs"
-import { join, dirname } from "node:path"
+import { mkdirSync, readFileSync, writeFileSync, renameSync, unlinkSync, existsSync } from "node:fs"
+import { join, dirname, basename } from "node:path"
 import { execSync } from "node:child_process"
 import { configDir } from "./config.mjs"
 import { migrateHashLength } from "./session-migrate.mjs"
+// §10 D-2（2026-09-05）：resumeSlot 决策归本文件（slot/claim 层）；data 层读（loadSlotFile/
+// legacy 过滤）属 session.mjs（500 行内不迁移）——静态环仅此一处：函数声明实例化期已初始化、
+// 只函数体内运行时使用（环安全）；VS Code 端 session-slots ↔ session-io 同构镜像。
+import { loadSlotFile, isLegacyTransient } from "./session.mjs"
 
 let currentSessionId = null
 
@@ -36,16 +40,57 @@ function cwdHash(cwd) {
   return createHash("sha1").update(normalizeCwd(cwd)).digest("hex")
 }
 
+/** sessions 根目录隔离缝（2026-09-08 DESIGN-TOKEN-SETTLEMENT 测试——VSC 端
+ *  _setSessionsDirForTest 同构）：默认 null 走真实 configDir；测试指向临时目录
+ *  （beforeEach 设、afterEach 复位）。migrateHashLength 的 legacy 迁移仍查真实
+ *  目录（temp 哈希无 legacy 文件——no-op 无害）。 */
+let sessionsDirOverride = null
+export function _setSessionsDirForTest(dir) { sessionsDirOverride = dir }
+export function _resetSessionsDirForTest() { sessionsDirOverride = null }
+function sessionsBase() { return sessionsDirOverride ?? join(configDir, "sessions") }
+
 /** Derive base session path from cwd hash. Migrates legacy short-hash files on first access. */
 export function sessionPath(cwd) {
   const hash = cwdHash(cwd)
   migrateHashLength(cwd, hash)
-  return join(configDir, "sessions", `${hash}.json`)
+  return join(sessionsBase(), `${hash}.json`)
 }
 
 export function slotPath(cwd, n) { return sessionPath(cwd) + "." + n }
 export function manifestPath(cwd) { return sessionPath(cwd) + ".manifest" }
 
+// ========== end marker（SESSION.md §10 端分离恢复——本端"最后使用槽位"记录）==========
+
+/** 端常量：本端记录文件后缀——CLI 写 .cli、VS Code 写 .vscode，互不触碰
+ *  （NF1：本端记录是本端单写者文件——不新增跨端共享可变字段）。 */
+export const END = "cli"
+
+/** 本端记录路径：{manifest}.{END}（manifest 旁的独立小文件，非内嵌字段——NF1）。 */
+export function endMarkerPath(cwd) { return `${manifestPath(cwd)}.${END}` }
+
+/** 读本端记录：返回 { slot: <number|null>, updatedAt } 或 null。三态语义（D-1）：
+ *  文件缺失 = 从未记录（升级/首用迁移窗口——可能触发一次性继承）；
+ *  JSON 解析失败/结构非法（损坏）= 按"缺失"降级——不 rename 不 unlink（幂等、不误伤，
+ *  T-M13）；`slot: null` = 显式置空（删过本端记录槽——绝不触发继承，T-M4）。 */
+export function readEndMarker(cwd) {
+  try {
+    const p = endMarkerPath(cwd)
+    if (!existsSync(p)) return null
+    const m = JSON.parse(readFileSync(p, "utf8"))
+    if (m && m.slot === null) return { slot: null, updatedAt: m.updatedAt ?? null }
+    if (m && Number.isInteger(m.slot) && m.slot >= 1) return { slot: m.slot, updatedAt: m.updatedAt ?? null }
+    return null
+  } catch { return null }
+}
+
+/** 写本端记录（原子 .tmp+rename，复用 writeSessionFile）：slot = 目标槽号或 null（显式置空）。
+ *  失败容忍（NF2）：写失败按无记录路径降级——不抛错，不影响会话数据（T-M14）。 */
+export function writeEndMarker(cwd, slot) {
+  try {
+    writeSessionFile(endMarkerPath(cwd), { slot, updatedAt: Date.now() })
+  } catch { /* NF2：失败容忍 */ }
+}
+
 /** Path to the active slot's file */
 export function activePath(cwd) {
   return slotPath(cwd, activeSlot(cwd))
@@ -143,27 +188,14 @@ export function saveManifest(cwd, m, deletions = null, opts = {}) {
   writeSessionFile(manifestPath(cwd), m)
 }
 
-/**
- * Claim a slot for this process and set it as active. Idempotent.
- * Preference order:
- *  1. The current active slot, if it is unowned / ours / its owner is dead — reuse it.
- *  2. Any slot that is unowned or owned by a dead process (reclaim).
- *  3. A brand-new slot when all are owned by live processes.
- * The owner is recorded in m.slotSessions so other processes (CLI ↔ VS Code) can
- * see which slots are taken and avoid them.
- */
-function ensureActive(cwd, m) {
+/** 死主条目清理（2026-08-31 会诊 F4 + 2026-09-01 会诊 deepseek/kimi 🔴 语义原样抽取——
+ *  ensureActive/resumeSlot 共用）：删除 owner 进程已死的 slotSessions 条目。死主判定必须跑
+ *  isProcessAlive——不能以"文件缺失"短路（活进程在"认领 → 首次保存"窗口文件暂缺，误删会
+ *  致双进程同槽）。返回 deletions 计算函数（调用时按 m 当前状态过滤刚重新认领的槽——防删
+ *  掉自己的新属主），无清理返回 null。删除须经 saveManifest 的 deletions 显式落盘——条目级
+ *  合并会把磁盘死条目从 fresh 复活回写（N1 + 会诊 🔴）。 */
+function cleanDeadOwners(m) {
   const mySessionId = getSessionId()
-  if (!m.slotSessions) m.slotSessions = {}
-
-  // 2026-08-31 会诊 F4：顺手清理死主条目——owner 进程已死的 slot 标记不再占用
-  // （原实现死项永不清理，空闲 slot 越来越少 → 新号滥发；且每次 save 对每 slot 跑
-  // tasklist，延迟随 slot 数增长）。
-  // advisor round2 #10：不能加 "文件缺失即删" 的短路——活进程在"认领 → 首次保存"窗口
-  // （新项目首跑：启动认领 slot、回合末才落盘）文件暂缺，误删其条目会被另一进程当
-  // 空闲认领 → 双进程永久写同一槽（F2 轮转互旋）。死主判定必须跑 tasklist；
-  // ensureActive 因 F1 粘性每次进程只跑几次，全量 tasklist 成本可接受。
-  let cleaned = false
   const deadSlots = []
   for (const [slot, owner] of Object.entries(m.slotSessions)) {
     if (owner && owner !== mySessionId) {
@@ -171,24 +203,33 @@ function ensureActive(cwd, m) {
       if (!pid || !isProcessAlive(pid)) {
         delete m.slotSessions[slot]
         deadSlots.push(slot)
-        cleaned = true
       }
     }
   }
+  return deadSlots.length === 0 ? null : () => ({ slotSessions: deadSlots.filter((s) => m.slotSessions[s] !== mySessionId) })
+}
 
-  // 2026-09-01 会诊三家：deadSlots 里可能含分支 1/2 刚重新认领的槽（m.slotSessions[s]
-  // 已被覆盖为 mySessionId）——deletions 若删除它会把自己的认领抹掉（下次 ensureActive
-  // 重新认领，但窗口内属主真空）。过滤在每次调用时按当前 m 状态计算。
-  const deadParam = () => (cleaned ? { slotSessions: deadSlots.filter((s) => m.slotSessions[s] !== mySessionId) } : null)
+/**
+ * Claim a slot for this process and set it as active. Idempotent.
+ * Preference order:
+ *  1. The current active slot, if it is unowned / ours / its owner is dead — reuse it.
+ *  2. Any slot that is unowned or owned by a dead process (reclaim).  → allocateFresh
+ *  3. A brand-new slot when all are owned by live processes.          → allocateFresh
+ * The owner is recorded in m.slotSessions so other processes (CLI ↔ VS Code) can
+ * see which slots are taken and avoid them.
+ */
+function ensureActive(cwd, m) {
+  const mySessionId = getSessionId()
+  if (!m.slotSessions) m.slotSessions = {}
+  // 顺手清理死主条目（见 cleanDeadOwners）。ensureActive 因 F1 粘性每次进程只跑几次，
+  // 全量 tasklist 成本可接受；清理结果必须落盘——早退 + 分支 1/2/3 全部传 deletions。
+  const deadParam = cleanDeadOwners(m)
 
   // Already own the active slot — nothing to do.
   // 2026-08-31 advisor round2 🔵：清理结果此时落盘（否则死项清理只在内存生效，早退
   // 路径永不持久化——死条目一直滞留到其他路径保存才消失）。
-  // advisor round3 N1 + 2026-09-01 会诊 deepseek/kimi 🔴：必须传 deletions——saveManifest
-  // 的条目级合并（{...fresh, ...m}）会把磁盘上仍存在的死条目从 fresh 复活回写，仅传 m
-  // 等于没删。N1 当时只修了早退路径，分支 1/2/3 漏了（认领主路径上死项清理是死代码）。
   if (m.active && m.slotSessions[m.active] === mySessionId) {
-    if (cleaned) saveManifest(cwd, m, deadParam())
+    if (deadParam) saveManifest(cwd, m, deadParam())
     return
   }
 
@@ -201,20 +242,40 @@ function ensureActive(cwd, m) {
   // 1. Prefer the current active slot if we can take it (preserves "resume where you left off").
   if (m.active && m.slots[m.active] && isFree(m.active)) {
     m.slotSessions[m.active] = mySessionId
-    saveManifest(cwd, m, deadParam(), { setActive: true })
+    saveManifest(cwd, m, deadParam?.() ?? null, { setActive: true })
     return
   }
 
+  // 2/3. 分支 2/3 已抽取为 allocateFresh（2026-09-05 §10 D-2——resumeSlot 全新分配复用）。
+  allocateFresh(cwd, m, deadParam)
+}
+
+/**
+ * Allocate a slot with ensureActive 分支 2/3 语义（2026-09-05 §10 D-2 抽取——resumeSlot
+ * 步骤③"其余一切 → 全新分配"复用；与 newSession 选号语义对齐）：
+ *  2. Reclaim a manifest slot whose FILE does not exist (never held a session)；
+ *  3. A brand-new slot when none is free / all numbers are taken.
+ * 记录所有权 + active 指针（setActive）并落盘。返回分配的槽号。
+ */
+export function allocateFresh(cwd, m, deadParam = null) {
+  const mySessionId = getSessionId()
+  if (!m.slotSessions) m.slotSessions = {}
+  const isFree = (slot) => {
+    const owner = m.slotSessions[slot]
+    if (!owner || owner === mySessionId) return true
+    return !isProcessAlive(parseInt(owner.split("-")[0]))
+  }
+
   // 2. Reclaim a slot whose FILE does not exist (never held a session). 2026-08-31 会诊 F4：
   //    原实现认领"编号最小的空闲 slot"——死主的旧 slot 文件仍在，新进程会 resume 进
   //    陌生会话（"会话乱了"实锤）且退出时覆盖它。只有文件缺失的空 slot 才允许回收。
-  const allSlots = Object.keys(m.slots).filter(n => /^\d+$/.test(n)).map(Number).sort((a, b) => a - b)
+  const allSlots = Object.keys(m.slots).filter((n) => /^\d+$/.test(n)).map(Number).sort((a, b) => a - b)
   for (const slot of allSlots) {
     if (isFree(slot) && !existsSync(slotPath(cwd, slot))) {
       m.active = slot
       m.slotSessions[slot] = mySessionId
-      saveManifest(cwd, m, deadParam(), { setActive: true })
-      return
+      saveManifest(cwd, m, deadParam?.() ?? null, { setActive: true })
+      return slot
     }
   }
 
@@ -234,7 +295,20 @@ function ensureActive(cwd, m) {
   while (liveClaimed(newSlot) || existsSync(slotPath(cwd, newSlot))) newSlot++
   m.active = newSlot
   m.slotSessions[newSlot] = mySessionId
-  saveManifest(cwd, m, deadParam(), { setActive: true })
+  saveManifest(cwd, m, deadParam?.() ?? null, { setActive: true })
+  return newSlot
+}
+
+/** 认领指定槽为本进程所有并置为 active（2026-09-05 §10 D-2 resumeSlot 认领路径——调用方
+ *  已按"属主 空/死/本进程"判据校验可用性；幂等）。manifest active 保留为共享指针（D-6：
+ *  旧版端/ACP 恢复依据 + 无记录端一次性继承源 + 列表回退高亮——不再作本端恢复第一依据）。
+ *  deadParam 在写入所有权之后求值（防 deletions 删掉本调用刚认领的槽——ensureActive
+ *  deadParam 同型过滤）。 */
+export function claimSlot(cwd, slot, m = loadManifest(cwd), deadParam = null) {
+  m.slotSessions ??= {}
+  m.slotSessions[slot] = getSessionId()
+  m.active = slot // 认领即翻共享指针（setActive 写 m.active——不更新则落快照旧值）
+  saveManifest(cwd, m, deadParam?.() ?? null, { setActive: true })
 }
 
 /**
@@ -330,32 +404,81 @@ export function deleteSlot(cwd, slot) {
   // setActive: true —— 显式表达"删到 active 时 active 置空"的意图（saveManifest 默认
   // 保留 fresh.active，2026-09-01 会诊三家 🟡）
   saveManifest(cwd, m, { slots: [n], slotSessions: [n] }, { setActive: true })
+  // 2026-09-05 §10 D-4/F4：删到本端记录槽 → 记录显式置空（文件保留 + slot:null——下次全新起步，不复活——T-M4/T-M8）
+  if (readEndMarker(cwd)?.slot === n) writeEndMarker(cwd, null)
   return true
 }
 
-/** Rename a slot: update the slot file's title + the manifest metadata (shared with VS Code).
- *  2026-09-01 会诊 glm 🟡：写回前按 mtime 门控重读——原实现读全量→改 title→整文件写回，
- *  窗口内并发方的最新保存会被旧数据覆盖（丢消息）；mtime 变了即放弃本次重命名。 */
-export function renameSlot(cwd, slot, title) {
-  const n = Number(slot)
-  if (!Number.isInteger(n) || n < 1) return false
-  const p = slotPath(cwd, n)
-  if (!existsSync(p)) return false
-  let data
+// renameSlot 已拆至 session-rename.mjs（2026-09-06 §12.2.5 契约改使本文件超 500 行硬限，
+// §12.3 授权拆分）；session.mjs re-export 保持调用点不变。
+
+// ========== resumeSlot（SESSION.md §10 D-2——端分离恢复决策）==========
+
+/** 本端记录槽可用判据（D-2）：slot ∈ m.slots + 槽文件在盘 + 属主 空/死/本进程。 */
+function usableSlot(cwd, m, slot) {
+  if (!m.slots[slot] || !existsSync(slotPath(cwd, slot))) return false
+  const owner = m.slotSessions?.[slot]
+  if (!owner || owner === getSessionId()) return true
+  const pid = parseInt(owner.split("-")[0])
+  return !pid || !isProcessAlive(pid)
+}
+
+/** legacy 单文件兜底（v1/v2 单会话 {hash}.json——迁移前残留；仅 data 层——2026-09-05 §10
+ *  D-2：恢复数据兜底不改变 claim 落点，T-M10）。纪律与 loadSlotFile 一致：cwd 不匹配（别人的文件）
+ *  直接 null 不改名；坏结构改名 .unreadable 保留（version>2 不动）；解析失败 .corrupted 保留。 */
+function loadLegacyFile(cwd) {
+  const legacy = sessionPath(cwd)
   try {
-    data = JSON.parse(readFileSync(p, "utf8"))
-  } catch {
-    return false
+    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 {}
   }
-  const t0 = statSync(p).mtimeMs
-  data.title = title
-  // 读与写之间文件被并发方改过 → 放弃（保留并发内容，重命名下次重试）
-  if (statSync(p).mtimeMs !== t0) return false
-  writeSessionFile(p, data)
+  return null
+}
+
+/**
+ * 恢复决策（SESSION.md §10 D-2）——TUI 启动的本端恢复入口（VS Code 面板同构镜像）。
+ * 返回 { slot, data }（data 可为 null——全新起步或读槽失败）。判据：
+ *   ① 本端记录可用（slot ≠ null 且 ∈ m.slots 且槽文件在盘 且属主 空/死/本进程）→ claimSlot；
+ *   ② 记录缺失（从未记录 = 升级/首用迁移窗口）：②a active 属主 = 本进程（同进程重入——
+ *      ensureActive 早退语义镜像：认领后尚未写 slots 条目/文件的窗口）→ 直接沿用；
+ *      ②b 否则一次性继承 manifest.active（同判据；活属主绝不继承——全新槽起步，T-M3）；
+ *   ③ 其余一切（slot:null 显式置空 / 槽被删 / 属主为活外人 / 继承失败）→ allocateFresh。
+ * 每次落点都写本端记录；claim 后读槽失败（.corrupted/.unreadable——loadSlotFile 既有改名
+ * 保全语义）→ 保持已 claim 槽 + data:null——不改 marker——下次保存原地重建（T-M15）。
+ */
+export function resumeSlot(cwd) {
   const m = loadManifest(cwd)
-  if (m.slots[n]) {
-    m.slots[n] = slotDigest(data)
-    saveManifest(cwd, m)
+  m.slotSessions ??= {}
+  // 与 ensureActive 同型的死主清理（认领路径持久化——F5a 纪律：仅传 m 等于没删）
+  const deadParam = cleanDeadOwners(m)
+  const rec = readEndMarker(cwd) // null = 缺失/损坏；{slot:null|N} = 文件在（D-1）
+  let slot = null
+  if (rec?.slot != null && usableSlot(cwd, m, rec.slot)) 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)) slot = m.active // ②b 一次性继承
   }
-  return true
+  if (slot !== null) claimSlot(cwd, slot, m, deadParam)
+  else slot = allocateFresh(cwd, m, deadParam) // ③ 全新分配（slot:null 绝不继承——T-M4）
+  // data 层：读已认领槽（loadSlotFile 自 session.mjs——环 import 见文件头）；读失败/槽文件不在 → legacy 单文件兜底（仅 data）
+  let data = loadSlotFile(cwd, slot)
+  if (!data) data = loadLegacyFile(cwd)
+  writeEndMarker(cwd, slot)
+  return { slot, data }
 }