@thincoder/core 0.9.1 → 0.9.3

package/session-index.mjs

@@ -0,0 +1,285 @@
+/**
+ * session-index.mjs — 会话派生索引库：打开 / DDL / schema / 行写入原语 / 测试缝（SESSION.md §6.19）。
+ *
+ * 机制契约全文 = `docs/core/design/SESSION.md` §6.19（D-SE43–D-SE47；D2 单一权威源）。
+ * 本档 = 「DB 打开 / DDL / schema / 测试缝」面；查询与 FTS 检索 = `session-index-query.mjs`；
+ * 写面（枚举 / 水位增量 / 会话重建 / 延迟拍 / 清行）= `session-index-build.mjs` +
+ * `session-index-pass.mjs`（>300 软线按设计「跨档线拆分预案」二分）；命令面 = `session-index-cmd.mjs`。
+ *
+ * **零权威**：主存（槽 JSON + `{槽}.d/` sidecar + manifest）= 真源；本库只读主存（整读 / 偏移
+ * `readSync`），**绝不写回** sessions 树；库丢 / 坏 = 重生成（D-SE46 打开即验 + 改名保留自愈）。
+ * **零第三方依赖**：仅 `node:` + 仓内相对 import（FTS5 同装配先例 = `memory/schema.mjs`）。
+ * 本档静态 import `node:sqlite` ⇒ **消费侧一律动态 import**（W8 契约②——`ledger-db.mjs` 同款：
+ * 静态 import 会把 node:sqlite 拉进 `read_history` 的装配期静态闭包）。
+ */
+import { DatabaseSync } from "node:sqlite"
+import { existsSync, mkdirSync, renameSync, rmSync, statSync } from "node:fs"
+import { dirname, join } from "node:path"
+import { configDir } from "./config-io.mjs"
+import { segmentCJK } from "./fts-text.mjs"
+
+/** 库名（单库——与 `memory.db` 同区 `~/.thincoder/`；D-SE43）。 */
+export const SESSION_INDEX_DB_NAME = "session-index.db"
+/** schema 版本（`index_meta.v` 不符 ⇒ 重建——不做迁移；D-SE46）。 */
+export const SESSION_INDEX_SCHEMA_VERSION = "1"
+/** 多进程（CLI + VSC 同启）竞争：WAL + busy_timeout（`memory/schema.mjs` 同值）。 */
+export const SESSION_INDEX_BUSY_TIMEOUT = 3000
+/** 水位 `tail_hash` 窗口 = 末段尾 4KB（D-SE45——等长改写检出）。 */
+export const TAIL_HASH_BYTES = 4096
+/** `tool_calls` 输出上限（= 存储面同值——`slimForDisplay` 截断面即精度上限；D-SE47）。 */
+export const ARG_MAX_CHARS = 300
+/** 延迟拍预算（D-SE45 触发点②：单趟 ≤ 2000ms 且 ≤ 40 会话）。 */
+export const INDEX_PASS_BUDGET_MS = 2000
+export const INDEX_PASS_MAX_SESSIONS = 40
+/** 查询窗口缺省 / 上限（与 read_history 参数面同值：缺省 50 / 上限 200）。 */
+export const DEFAULT_QUERY_LIMIT = 50
+export const MAX_QUERY_LIMIT = 200
+
+// ── 测试缝（`_setLedgerDirForTest` 同款：测试不碰真实用户目录）─────────────────
+let indexDirOverride = null
+export function _setSessionIndexDirForTest(dir) { indexDirOverride = dir }
+export function _resetSessionIndexDirForTest() { indexDirOverride = null }
+export function sessionIndexDir() { return indexDirOverride ?? configDir }
+export function sessionIndexDbPath() { return join(sessionIndexDir(), SESSION_INDEX_DB_NAME) }
+
+/** DDL（四表 + FTS + 元表；`UNIQUE(sid, idx)` 兼作查询主索引——同列序不重复建；D-SE44）。 */
+export const SESSION_INDEX_DDL = `
+CREATE TABLE IF NOT EXISTS sessions (
+  id INTEGER PRIMARY KEY,
+  cwd_key TEXT NOT NULL,
+  slot INTEGER NOT NULL,
+  file TEXT NOT NULL,
+  cwd TEXT,
+  title TEXT,
+  identity TEXT,
+  src TEXT NOT NULL,
+  updated_at INTEGER,
+  indexed_at INTEGER,
+  seg_n INTEGER NOT NULL DEFAULT 0,
+  seg_bytes INTEGER NOT NULL DEFAULT 0,
+  seg_mtime REAL NOT NULL DEFAULT 0,
+  tail_hash TEXT NOT NULL DEFAULT '',
+  UNIQUE(cwd_key, slot)
+);
+CREATE TABLE IF NOT EXISTS messages (
+  rowid INTEGER PRIMARY KEY,
+  sid INTEGER NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+  idx INTEGER NOT NULL,
+  seg INTEGER NOT NULL,
+  ts INTEGER,
+  role TEXT,
+  name TEXT,
+  tool_call_id TEXT,
+  content TEXT NOT NULL DEFAULT '',
+  UNIQUE(sid, idx)
+);
+CREATE INDEX IF NOT EXISTS messages_ts ON messages(ts);
+CREATE INDEX IF NOT EXISTS messages_name ON messages(name);
+CREATE TABLE IF NOT EXISTS tool_calls (
+  id INTEGER PRIMARY KEY,
+  sid INTEGER NOT NULL,
+  msg_idx INTEGER NOT NULL,
+  ord INTEGER NOT NULL,
+  call_id TEXT,
+  name TEXT,
+  args TEXT,
+  UNIQUE(sid, msg_idx, ord)
+);
+CREATE INDEX IF NOT EXISTS tool_calls_name ON tool_calls(name);
+CREATE VIRTUAL TABLE IF NOT EXISTS messages_fts USING fts5(seg_content, seg_name, tokenize='unicode61');
+CREATE TABLE IF NOT EXISTS index_meta (k TEXT PRIMARY KEY, v TEXT);
+`
+
+function openRaw(path) {
+  const db = new DatabaseSync(path)
+  try {
+    db.exec(`PRAGMA journal_mode = WAL`)
+    db.exec(`PRAGMA busy_timeout = ${SESSION_INDEX_BUSY_TIMEOUT}`)
+    db.exec(`PRAGMA foreign_keys = ON`)
+    db.exec(SESSION_INDEX_DDL)
+    const v = readMeta(db, "v")
+    if (v !== null && v !== SESSION_INDEX_SCHEMA_VERSION) throw new Error(`session index schema ${v} ≠ ${SESSION_INDEX_SCHEMA_VERSION}`)
+    if (v === null) {
+      writeMeta(db, "v", SESSION_INDEX_SCHEMA_VERSION)
+      writeMeta(db, "built_at", Date.now())
+    }
+  } catch (e) {
+    // 失败句柄必须关闭：Windows 上未关闭的句柄会让改名失败（现场保留 + 新建两步都落空）
+    try { db.close() } catch { /* ignore */ }
+    throw e
+  }
+  return db
+}
+
+/** 打开即验 + 开箱自愈（D-SE46）：缺失 ⇒ 建；打开 / DDL / 版本失败 ⇒ 现场改名
+ *  `session-index.db.corrupt-<epochms>`（连同 `-wal` / `-shm`——否则残 WAL 会挂到新库上）+ 新建空库。
+ *  仍失败（磁盘满 / 目录不可写 / 无 node:sqlite）⇒ **null = 静默降级**（查询回落主存路径，主存零险）。 */
+export function openSessionIndex({ path = sessionIndexDbPath() } = {}) {
+  try { mkdirSync(dirname(path), { recursive: true }) } catch { /* 已存在 / 并发建目录竞争 */ }
+  try { return openRaw(path) } catch { /* 缺失 / 坏库 / 版本不符 ⇒ 走自愈 */ }
+  const stamp = `${path}.corrupt-${Date.now()}`
+  for (const suffix of ["", "-wal", "-shm"]) {
+    try { if (existsSync(path + suffix)) renameSync(path + suffix, stamp + suffix) } catch { /* 现场保留尽力面 */ }
+  }
+  try { return openRaw(path) } catch { return null }
+}
+
+/** 元表读 / 写（`v` = schema 版本 · `built_at` = 首建 / 全量重建时刻 · `pass_at` = **最近一次
+ *  实际写入（变更）时刻**（无源变的 pass 零写、不推进）· 计数快照）。 */
+export function readMeta(db, k) {
+  try {
+    const row = db.prepare("SELECT v FROM index_meta WHERE k = ?").get(k)
+    return row ? row.v : null
+  } catch { return null }
+}
+
+export function writeMeta(db, k, v) {
+  db.prepare("INSERT INTO index_meta (k, v) VALUES (?, ?) ON CONFLICT(k) DO UPDATE SET v = excluded.v").run(k, String(v))
+}
+
+// ── 行形态（写入面与读出面共用同一口径）──────────────────────────────────────
+
+/** 消息文本（多模态数组取 text 部件拼接）。**与 `agent-tools/read-history.mjs` 的 JSON 面
+ *  `messageText` 同规则**——两面各自持有（索引面不得静态引 read-history 的装配面，反之亦然），
+ *  等价性由过滤矩阵对拍用例覆盖。 */
+export function messageText(m) {
+  if (typeof m?.content === "string") return m.content
+  if (Array.isArray(m?.content)) {
+    return m.content
+      .map((p) => (p && typeof p === "object" && p.type === "text" ? p.text ?? "" : ""))
+      .filter((t) => t.length > 0)
+      .join(" ")
+  }
+  return ""
+}
+
+/** 一次工具声明 → `{ name, args, call_id }`（`{function:{…}}` 与扁平两形兼容；`args` 逐字取存储串）。 */
+export function toolCallParts(tc) {
+  return {
+    call_id: tc?.id ?? null,
+    name: tc?.function?.name ?? tc?.name ?? "",
+    args: typeof tc?.function?.arguments === "string" ? tc.function.arguments
+      : typeof tc?.arguments === "string" ? tc.arguments : null,
+  }
+}
+
+/** 输出上限（= 存储面同值：≤300 原样，超限截 300 + `…`）。 */
+export function capArguments(s) {
+  const t = String(s ?? "")
+  return t.length <= ARG_MAX_CHARS ? t : t.slice(0, ARG_MAX_CHARS) + "…"
+}
+
+// ── 删除面单点（FTS 同删义务——无触发器：四条删除路径全部经此函数，同事务内同步删；§6.19）──
+
+/** 删行单点：`fromIdx = null` ⇒ 整会话（消息 + FTS + 工具声明 + 会话行）；给定 `fromIdx` ⇒ 区间
+ *  （`idx >= fromIdx` 的消息 / FTS 与 `msg_idx >= fromIdx` 的声明——段重写 / 重扫面）。 */
+export function deleteSessionRows(db, sid, { fromIdx = null } = {}) {
+  const range = fromIdx === null ? "" : " AND idx >= ?"
+  const mArgs = fromIdx === null ? [sid] : [sid, fromIdx]
+  const tRange = fromIdx === null ? "" : " AND msg_idx >= ?"
+  db.prepare(`DELETE FROM messages_fts WHERE rowid IN (SELECT rowid FROM messages WHERE sid = ?${range})`).run(...mArgs)
+  db.prepare(`DELETE FROM tool_calls WHERE sid = ?${tRange}`).run(...mArgs)
+  db.prepare(`DELETE FROM messages WHERE sid = ?${range}`).run(...mArgs)
+  if (fromIdx === null) db.prepare(`DELETE FROM sessions WHERE id = ?`).run(sid)
+}
+
+/** 单会话清行（源消失面——单事务；幂等）：删四表该会话行 + 推进 `pass_at`
+ *  （查询侧据此走回落路径——既有 `session file not found` 文案逐字保留）。 */
+export function dropSessionRows(db, sid, now = Date.now()) {
+  db.exec("BEGIN IMMEDIATE")
+  try {
+    deleteSessionRows(db, sid, { fromIdx: null })
+    writeMeta(db, "pass_at", now)
+    db.exec("COMMIT")
+  } catch (e) {
+    try { db.exec("ROLLBACK") } catch { /* ignore */ }
+    throw e
+  }
+}
+
+/** `--rebuild` 面：清四表（单事务）+ 刷新 `built_at`。 */
+export function clearIndex(db) {
+  db.exec("BEGIN IMMEDIATE")
+  try {
+    db.exec("DELETE FROM messages_fts")
+    db.exec("DELETE FROM tool_calls")
+    db.exec("DELETE FROM messages")
+    db.exec("DELETE FROM sessions")
+    writeMeta(db, "built_at", Date.now())
+    db.exec("COMMIT")
+  } catch (e) {
+    try { db.exec("ROLLBACK") } catch { /* 回滚尽力面 */ }
+    throw e
+  }
+}
+
+// ── 会话行 / 消息行 / 声明行写入 ─────────────────────────────────────────────
+
+export function findSessionByFile(db, file) {
+  try { return db.prepare("SELECT * FROM sessions WHERE file = ?").get(file) ?? null } catch { return null }
+}
+
+export function findSessionByCwdSlot(db, cwdKey, slot) {
+  try { return db.prepare("SELECT * FROM sessions WHERE cwd_key = ? AND slot = ?").get(cwdKey, slot) ?? null } catch { return null }
+}
+
+/** 建会话行（返回 sid）；同 `(cwd_key, slot)` 已占 ⇒ 先摘旧行（槽号回收 / 轮转 / 本行重建面——
+ *  新旧行不混，`UNIQUE(cwd_key, slot)` 零冲突）。 */
+export function insertSession(db, row) {
+  const old = findSessionByCwdSlot(db, row.cwd_key, row.slot)
+  if (old) deleteSessionRows(db, old.id, { fromIdx: null })
+  const r = db.prepare(
+    `INSERT INTO sessions (cwd_key, slot, file, cwd, title, identity, src, updated_at, indexed_at, seg_n, seg_bytes, seg_mtime, tail_hash)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+  ).run(row.cwd_key, row.slot, row.file, row.cwd ?? null, row.title ?? null, row.identity ?? null, row.src,
+    row.updated_at ?? null, row.indexed_at ?? null, row.seg_n ?? 0, row.seg_bytes ?? 0, row.seg_mtime ?? 0, row.tail_hash ?? "")
+  return Number(r.lastInsertRowid)
+}
+
+/** 会话级元数据 / 水位推进（单语句——写面在同一事务内调用）。 */
+export function updateSession(db, sid, patch) {
+  const cols = ["cwd", "title", "identity", "src", "updated_at", "indexed_at", "seg_n", "seg_bytes", "seg_mtime", "tail_hash"]
+  const set = cols.filter((c) => patch[c] !== undefined)
+  if (set.length === 0) return
+  db.prepare(`UPDATE sessions SET ${set.map((c) => `${c} = ?`).join(", ")} WHERE id = ?`).run(...set.map((c) => patch[c]), sid)
+}
+
+/** 插消息行（连同 FTS 行——同事务）。`rows` = `{ idx, seg, ts, role, name, tool_call_id, content }`。 */
+export function insertMessages(db, sid, rows) {
+  const msg = db.prepare(`INSERT INTO messages (sid, idx, seg, ts, role, name, tool_call_id, content) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+  const fts = db.prepare(`INSERT INTO messages_fts (rowid, seg_content, seg_name) VALUES (?, ?, ?)`)
+  for (const r of rows) {
+    const info = msg.run(sid, r.idx, r.seg, r.ts ?? null, r.role ?? null, r.name ?? null, r.tool_call_id ?? null, r.content ?? "")
+    fts.run(Number(info.lastInsertRowid), segmentCJK(r.content ?? ""), segmentCJK(r.name ?? ""))
+  }
+}
+
+/** 插声明行（`ord` = 该消息内声明序；`args` = 存储串逐字）。 */
+export function insertToolCalls(db, sid, rows) {
+  const stmt = db.prepare(`INSERT INTO tool_calls (sid, msg_idx, ord, call_id, name, args) VALUES (?, ?, ?, ?, ?, ?)`)
+  for (const r of rows) stmt.run(sid, r.msg_idx, r.ord, r.call_id ?? null, r.name ?? "", r.args ?? null)
+}
+
+/** `--status` 读数（行数 / 取源分布 / 库字节 / 水位覆盖 / 上次变更时刻）。 */
+export function indexSummary(db, { path = sessionIndexDbPath() } = {}) {
+  const one = (sql) => { try { return Number(Object.values(db.prepare(sql).get())[0] ?? 0) } catch { return 0 } }
+  let bytes = 0
+  try { bytes = statSync(path).size } catch { /* 库不在 / 不可读 ⇒ 0 */ }
+  return {
+    sessions: one("SELECT COUNT(*) FROM sessions"),
+    sidecar: one("SELECT COUNT(*) FROM sessions WHERE src = 'sidecar'"),
+    json: one("SELECT COUNT(*) FROM sessions WHERE src = 'json'"),
+    messages: one("SELECT COUNT(*) FROM messages"),
+    toolCalls: one("SELECT COUNT(*) FROM tool_calls"),
+    bytes,
+    builtAt: Number(readMeta(db, "built_at") ?? 0),
+    passAt: Number(readMeta(db, "pass_at") ?? 0),
+  }
+}
+
+/** 库侧清理（测试收尾 / 现场重置）：删库文件三件套（含 WAL / SHM）。 */
+export function removeIndexFiles(path = sessionIndexDbPath()) {
+  for (const suffix of ["", "-wal", "-shm"]) {
+    try { rmSync(path + suffix, { force: true }) } catch { /* 尽力面 */ }
+  }
+}

package/session-lifecycle.mjs

@@ -29,11 +29,12 @@ import { loadSlotFile } from "./session.mjs"
 import { mergeAdjacentAssistantEchoes } from "./context.mjs"
 import { scheduleSessionGC } from "./session-gc.mjs"
 import { restoreEngTokens } from "./token-ttl.mjs"
+import { clearPlanMode } from "./agent-tools/plan.mjs"
 import { bindRecordStore, unbindRecordStore, RECORD_WINDOW_MESSAGES } from "./session-store.mjs"
 
 /** 恢复决策包装（SESSION.md §6.12 启动钩子，2026-09-06）：本端恢复入口触发一次残留 GC——
- *  scheduleSessionGC 内部 setImmediate 空闲执行 + 每进程每前缀去重，不阻塞启动路径（N4）。
- *  **async**（F-MI7——整链异步：探测不阻塞事件循环；调用面必须 await）。 */
+ *  scheduleSessionGC 内部**启动窗外延迟拍**（`GC_PASS_DELAY_MS` = 3s）+ 每进程每前缀去重，
+ *  **异步非阻塞**启动路径（N4；§6.17 D-SE39）；**async**（F-MI7——调用面必须 await）。 */
 export async function resumeSlot(cwd) {
   scheduleSessionGC(cwd)
   return slotsResumeSlot(cwd)
@@ -112,6 +113,10 @@ export function applySession(agent, data, opts = {}) {
     agent.config.agent ??= {}
     agent.config.agent.engineering = data.engineering === true
   }
+  // ENG-PLAN-EXCLUSION（FR31 ③ / KD10——恢复点①·CLI `applySession`）：工程模式 ⇒ planMode 恒
+  // false（内存位 + 未注入的 plan 提示语）——防「工程纪律 × plan 只读」半状态随槽恢复复活。
+  // **槽不就地回写**：内存值在下一次 `saveSession` 随 `planMode` 字段自然收正（`session.mjs:128`）。
+  if (agent.config?.agent?.engineering === true) clearPlanMode(agent)
   if (data.advisor) {
     agent.config.advisor = { ...data.advisor }
   }
@@ -166,8 +171,11 @@ export function applySession(agent, data, opts = {}) {
  * write an empty session, and mark it as the active slot.
  * No limit on the number of sessions.
  * **async**（F-MI7：入口一次异步束——探测不阻塞事件循环；调用面必须 await）。
+ * `opts.releaseStale`（F-CR1 · SESSION.md §6.5 / §6.16）：**调用面 opt-in**——CLI `/new` 传
+ * （`cmd-new.mjs`），释放本进程残留认领（保留集 = {新槽}）；ACP 四点不传（多会话多认领属其
+ * 设计——F-CR3 零回归）。
  */
-export async function newSession(cwd) {
+export async function newSession(cwd, opts = {}) {
   const m = loadManifest(cwd)
 
   // 2026-09-01 advisor 🔵：先清理死主条目（与 ensureActive 分支2 语义一致）——否则
@@ -223,7 +231,9 @@ export async function newSession(cwd) {
         slots: deadSlots.filter((s) => !m.slots[s]),
       }
     : null
-  saveManifest(cwd, m, deletions, { setActive: true })
+  // F-CR1 认领释放（SESSION.md §6.5 / §6.16 公式代入）：保留集 = {新槽}——与既有死主
+  // deletions 合流（同一一次 saveManifest；落盘判据见核 `saveManifest`）。
+  saveManifest(cwd, m, deletions, opts.releaseStale ? { setActive: true, release: [slot] } : { setActive: true })
   // 2026-09-05 §6.10 D-4：/new 落点写本端记录（显式切换跟随——T-M8）
   writeEndMarker(cwd, slot)
   return slot
@@ -280,7 +290,10 @@ export function switchToSlot(cwd, slot) {
     m.slotSessions ??= {}
     m.slotSessions[slot] = getSessionId()
   }
-  saveManifest(cwd, m, null, { setActive: true })
+  // F-CR1 认领释放（SESSION.md §6.5 / §6.16 公式代入）：保留集 = 未占 ⇒ {目标}；**被占 ⇒ 空**
+  // （不认领目标 + 旧认领一并释放——下次保存经 `allocateFresh` fork，既有语义）。核受占 =
+  // 切换成立（D-SE33：指针 / 记录按 D-6 / D-4 落点——fork 面依赖指针翻至目标槽）。
+  saveManifest(cwd, m, null, { setActive: true, release: occ.occupied ? [] : [slot] })
   // 2026-09-05 §6.10 D-4：/session N 跟随"最后查看的槽"（成功切换才写）
   writeEndMarker(cwd, slot)
   return data

package/session-slots-manifest.mjs

@@ -4,7 +4,8 @@
  * `CORE-UNIFICATION.md` §2.8.1 表第 3 行随批执行外提；各函数语义**原样**迁移）：
  * 摘要面（`extractSlotMeta` / `slotDigest`）· 清单读写（`loadManifest` / `saveManifest`）·
  * 属主面（`ownerPid` / `ownerPids` / `ownerStateOf` / `ownerArgs` / `cleanDeadOwners`）·
- * 认领面（`ensureActive` / `allocateFresh` / `claimSlot` / `activeSlot`）。
+ * 认领面（`ensureActive` / `allocateFresh` / `claimSlot` / `activeSlot` / **认领释放集
+ * `staleClaims`**——F-CR1 · SESSION-CLAIM 批：判据单源，`saveManifest` 落盘 + 各落点共用）。
  *
  * 静态环（与既有的 session.mjs ↔ session-slots.mjs 同形）：本档引 `session-slots.mjs` 的
  * 存储原语（`getSessionId` / `manifestPath` / `slotPath` / `writeSessionFile`），
@@ -69,6 +70,10 @@ export function saveManifest(cwd, m, deletions = null, opts = {}) {
   // （ensureActive 分支、newSession、switchToSlot、deleteSlot 删到 active 时）传
   // opts.setActive；其余调用方（saveSession/ACP 认领/死项清理）默认保留磁盘 fresh 的
   // active，否则毫秒窗口内会把并发方刚翻的 active 回滚（F1 防漂移的反向变体）。
+  // F-CR1 认领释放（判据单源 · SESSION.md §6.2 / §6.16 落盘判据三条）：`opts.release` = 保留集
+  // （落点槽 ∪ 本进程其余活绑定槽；被占落点 ⇒ 空集）。③ 内存认领表先移除残留条目（否则下方
+  // 条目级合并会把它从内存复活回写）——先于 try（fresh 不可读时亦须生效）。
+  if (opts.release) dropStaleClaims(m, opts.release)
   try {
     const fresh = JSON.parse(readFileSync(manifestPath(cwd), "utf8"))
     if (fresh && typeof fresh === "object" && fresh.slots && typeof fresh.slots === "object") {
@@ -77,6 +82,14 @@ export function saveManifest(cwd, m, deletions = null, opts = {}) {
       merged.slots = { ...fresh.slots, ...(m.slots ?? {}) }
       merged.slotSessions = { ...(fresh.slotSessions ?? {}), ...(m.slotSessions ?? {}) }
       if (m.sessionId) merged.sessionId = m.sessionId
+      // ① 释放集按**本次 fresh 快照**取值（不得以陈旧内存 manifest 构 deletions）；② **值条件删除**
+      // （仅当 fresh 属主仍为本进程——窗口内他人的新认领不在集内、不被误删）⇒ 并入本次 deletions。
+      if (opts.release) {
+        const released = staleClaims(fresh, opts.release)
+        if (released.length > 0) {
+          deletions = { ...(deletions ?? {}), slotSessions: [...(deletions?.slotSessions ?? []), ...released] }
+        }
+      }
       if (deletions) {
         for (const [section, keys] of Object.entries(deletions)) {
           for (const k of keys) delete merged[section]?.[k]
@@ -95,6 +108,23 @@ export function saveManifest(cwd, m, deletions = null, opts = {}) {
   writeSessionFile(manifestPath(cwd), m)
 }
 
+/** 本进程**残留认领集**（F-CR1 释放谓词 —— **判据单源** · SESSION.md §6.2 / §6.16）：
+ *  「释放 A ⟺ `slotSessions[A]` 为本进程 ∧ `A ∉ 保留集`」。`keep` = 保留集 = 落点槽 ∪ 本进程
+ *  其余活绑定槽（单绑定落点 ⇒ `{落点槽}`；被占落点 ⇒ 空集）。返回槽号（**字符串键**形态）。 */
+export function staleClaims(src, keep = []) {
+  const keepSet = new Set((keep ?? []).filter((s) => s != null).map(Number))
+  const mySessionId = getSessionId()
+  return Object.entries(src?.slotSessions ?? {})
+    .filter(([slot, owner]) => owner === mySessionId && !keepSet.has(Number(slot)))
+    .map(([slot]) => slot)
+}
+
+/** 从**内存**认领表移除本进程残留条目（判据③——与写盘同一时机；见 `saveManifest`）。 */
+function dropStaleClaims(m, keep) {
+  if (!m?.slotSessions) return
+  for (const slot of staleClaims(m, keep)) delete m.slotSessions[slot]
+}
+
 /** 属主串 → pid（`"pid-ts-rand"`——`owner.split("-")[0]` 格式判据单源：session-slots ↔
  *  session-lifecycle 共用，防两处漂移）。不可解析 ⇒ NaN——判据层按 dead 处理
  *  （见 process-probe `ownerState`）。 */
@@ -248,12 +278,34 @@ export function allocateFresh(cwd, m, deadParam = null, bundle = null) {
  *  已按"属主 空/死/本进程"判据校验可用性；幂等）。manifest active 保留为共享指针（D-6：
  *  旧版端/ACP 恢复依据 + 无记录端一次性继承源 + 列表回退高亮——不再作本端恢复第一依据）。
  *  deadParam 在写入所有权之后求值（防 deletions 删掉本调用刚认领的槽——ensureActive
- *  deadParam 同型过滤）。 */
+ *  deadParam 同型过滤）。
+ *  F-CR1（2026-09-21 · SESSION-CLAIM 批）：认领落点释放本进程残留认领（保留集 = {认领槽}——
+ *  §6.2 公式代入）；本函数 = 启动恢复 / 本端恢复落点（核 `resumeSlot` 与 VSC 端壳
+ *  `resumeSlot` 共用），落盘判据（fresh 快照 / 值条件删除 / 内存移除）见 `saveManifest`。 */
 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 })
+  saveManifest(cwd, m, deadParam?.() ?? null, { setActive: true, release: [slot] })
+}
+
+/** 退出全释放（EXIT-CLAIM-RELEASE 批 · F-XR1 · SESSION.md §6.18 D-SE41）：优雅退出前释放
+ *  本进程**全部**槽认领（保留集空——`staleClaims` 释放谓词单源）；落盘判据 = `saveManifest`
+ *  `opts.release` 三条自动继承（fresh 同次快照取释放集 / 值条件删除——他人窗口内新认领不误删 /
+ *  内存认领表同步移除）。**零触碰 marker 面**（F-XR2 路标保留——下次启动经 `usableSlot`
+ *  无属主短路零探测直达恢复）；崩溃路径不经此（信号无 JS 钩子——F-XR3）。
+ *  早退面：磁盘无 manifest ⇒ `existsSync` 单条目早退**零写**（不造盘面）；本进程无认领 ⇒
+ *  零写返回 false。失败容忍（F-XR1「退出恒达」）：整体 try/catch **永不抛出**，返回 boolean
+ *  （true = 有释放且落盘成功；false = 早退 / 失败——断言面）；写失败盘面 = 认领残留 →
+ *  恢复走既有探测面（现状形态，数据零险）。 */
+export function releaseClaimsAll(cwd) {
+  try {
+    if (!existsSync(manifestPath(cwd))) return false // 无 manifest ⇒ 零写（不造盘面）
+    const m = loadManifest(cwd)
+    if (staleClaims(m, []).length === 0) return false // 无本进程认领 ⇒ 零写（免白刷共享 sessionId）
+    saveManifest(cwd, m, null, { release: [] }) // 保留集空 = 全释放；不 setActive（active 共享指针不动）
+    return true
+  } catch { return false } // F-XR1：退出恒达（写失败 = 认领残留 → 恢复走探测面）
 }
 
 /** Return the active slot number for this process, claiming one if necessary */