thincoder 0.12.68 → 0.12.70

package/src/acp/read-data.mjs

@@ -0,0 +1,127 @@
+/**
+ * read-data.mjs — ACP read-only data interfaces (READ-DATA-INTERFACE.md §2.6 / §3.3 / §3.4):
+ * `ledger/list` · `ledger/count` · `batch/list` + change notifications
+ * (`ledger/changed` / `batch/changed`, params `{ cwd }` — 信号面，数据经拉取方法取).
+ *
+ * 核模块一律**动态 import**（W8 契约②——台账链静态入 node:sqlite；且装载期零开销）。
+ * 观察器 = 5s 指纹轮询（注入面 `intervalMs`；测试直驱 `watcher.check()`——零定时器依赖）：
+ * 观察域 = 服务进程 cwd（每轮 `ctx.getCwd()` 求值——与 `params.cwd` 缺省同取值；非观察项目不通知）；
+ * 首查立基线（静默）；此后差分 ⇒ 对应通知；`start()` 挂 unref 定时器（先例 = 核 ledger-surface.mjs）。
+ * 凭据门 = `ctx.requireConfigured`（与既有四族同门——D-8；只读性不改通道门）。
+ */
+import { statSync } from "node:fs"
+
+import { ACP_ERRORS } from "./transport.mjs"
+
+/** 观察周期（D-7——5s；注入面 = `createReadDataHandlers(ctx, { intervalMs })`）。 */
+export const WATCH_INTERVAL_MS = 5000
+
+/** 核模块惰性装载（单次——W8 契约②：消费侧动态 import）。 */
+let corePromise = null
+function core() {
+  corePromise ??= Promise.all([
+    import("@thincoder/core/ledger-read.mjs"),
+    import("@thincoder/core/ledger-cmd.mjs"),
+    import("@thincoder/core/ledger-db.mjs"),
+    import("@thincoder/core/agent-tools/batch-read.mjs"),
+  ]).then(([ledgerRead, ledgerCmd, ledgerDb, batchRead]) => ({ ledgerRead, ledgerCmd, ledgerDb, batchRead }))
+  return corePromise
+}
+
+const badParams = (message) => ({ error: { ...ACP_ERRORS.INVALID_PARAMS, message } })
+
+/** `params.cwd` → 取值（缺省 = 服务进程 cwd，`ctx.getCwd()`）；非字符串 ⇒ 错误对象。 */
+function resolveCwd(params, ctx) {
+  const cwd = params?.cwd
+  if (cwd === undefined) return { cwd: ctx.getCwd() }
+  if (typeof cwd !== "string") return { error: badParams(`cwd must be a string (got ${typeof cwd})`) }
+  return { cwd }
+}
+
+/** 指纹（台账库单档 / 批次档逐档）——`exists:mtimeMs:size`；缺失 ⇒ `0`。 */
+function fileSig(file) {
+  try { const st = statSync(file); return `1:${st.mtimeMs}:${st.size}` } catch { return "0" }
+}
+
+/**
+ * Build the read-data handlers + the change watcher. Shared state arrives via the single
+ * `ctx` (§3.5); `intervalMs` is the injection face for the watch period.
+ * @returns {{ handlers: Record<string, (params: object) => Promise<object>>,
+ *             watcher: { check: () => Promise<string[]>, start: () => void, stop: () => void } }}
+ */
+export function createReadDataHandlers(ctx, { intervalMs = WATCH_INTERVAL_MS } = {}) {
+  const { requireConfigured } = ctx
+
+  const handlers = {
+    "ledger/list": async (params) => {
+      const gate = requireConfigured()
+      if (gate.error) return gate
+      const c = resolveCwd(params, ctx)
+      if (c.error) return c.error
+      for (const f of ["family", "full"]) {
+        if (params?.[f] !== undefined && typeof params[f] !== "boolean") return badParams(`${f} must be a boolean (got ${typeof params[f]})`)
+      }
+      const { ledgerRead } = await core()
+      try {
+        return ledgerRead.ledgerExport({ cwd: c.cwd, family: params?.family === true, full: params?.full === true })
+      } catch (e) { return badParams(e?.message ?? String(e)) }
+    },
+
+    "ledger/count": async (params) => {
+      const gate = requireConfigured()
+      if (gate.error) return gate
+      const c = resolveCwd(params, ctx)
+      if (c.error) return c.error
+      const { ledgerCmd } = await core()
+      try { return { count: ledgerCmd.ledgerCount({ cwd: c.cwd }) } } catch (e) { return badParams(e?.message ?? String(e)) }
+    },
+
+    "batch/list": async (params) => {
+      const gate = requireConfigured()
+      if (gate.error) return gate
+      const c = resolveCwd(params, ctx)
+      if (c.error) return c.error
+      const { batchRead } = await core()
+      try { return batchRead.listBatchRecords({ cwd: c.cwd }) } catch (e) { return badParams(e?.message ?? String(e)) }
+    },
+  }
+
+  // ── 变更观察器（轮询指纹；起停 = runAcpServer 启、进程终灭）─────────────────
+  let last = null
+  let timer = null
+  let inflight = false // 重叠防衛（先例 = 核 ledger-surface.mjs）：上一拍未落定 ⇒ 跳过本拍
+
+  async function check() {
+    if (inflight) return []
+    inflight = true
+    try {
+      const cwd = ctx.getCwd()
+      const { ledgerDb, batchRead } = await core()
+      const ledgerSig = fileSig(ledgerDb.ledgerDbPath(cwd))
+      const batchSig = batchRead.listBatchRecords({ cwd }).batches.map((b) => `${b.path}:${fileSig(b.path)}`).join("|")
+      if (!last || last.cwd !== cwd) { last = { cwd, ledgerSig, batchSig }; return [] } // 首查 / 观察域切换 ⇒ 立基线（静默）
+      const fired = []
+      if (ledgerSig !== last.ledgerSig) fired.push("ledger/changed")
+      if (batchSig !== last.batchSig) fired.push("batch/changed")
+      last = { cwd, ledgerSig, batchSig }
+      for (const method of fired) ctx.notifyRef.current(method, { cwd })
+      return fired
+    } finally { inflight = false }
+  }
+
+  /** 启动：立即首查（立基线——静默）+ 周期轮询；unref 定时器（不阻塞进程退出）。 */
+  function start() {
+    if (timer) return
+    void check().catch(() => {})
+    timer = setInterval(() => { void check().catch(() => {}) }, intervalMs)
+    timer.unref?.()
+  }
+
+  /** 停表（进程终灭即止的显式面——测试 / 收尾用）。 */
+  function stop() {
+    if (timer) clearInterval(timer)
+    timer = null
+  }
+
+  return { handlers, watcher: { check, start, stop } }
+}

package/src/acp/resource-link.mjs

@@ -0,0 +1,124 @@
+/**
+ * resource-link.mjs — `session/prompt` 的 `resource_link` 内容块（ACP v1 基线 MUST：
+ * 「All agents MUST support resource links in prompts」）。
+ *
+ * 判定树与验收 = `docs/cli/design/ACP-PROTOCOL-COMPLIANCE.md` §2.5（逐态可机检）：
+ *   uri 解析（file: ⇒ 解码 + UNC/盘符收正；非 file ⇒ `unsupported scheme`；解析失败 ⇒ 纯路径
+ *   按 cwd）→ 选区（`#L<a>` / `#L<a>-<b>` / `#L<a>:<b>`——1 基闭区间）→ 读面（`unreadable` /
+ *   `not a regular file` / `too large (>10MB)`——文件级先于读取）→ NUL（`binary (NUL byte)`）→
+ *   载荷上限（`too many lines (>2000)` / `too long (>100000 chars)`）→ 成功形（`[File: …]` +
+ *   无语言标记围栏）。
+ *
+ * 语义裁定（设计档 §2.5 三条）：**无 cwd confine**（用户显式 @ 引用可读任意绝对路径——与
+ * `read` 工具同界：confine 已撤除，读操作只读、不触发审批）；**零能力门控**（resource_link 属
+ * 基线 MUST，非 `PromptCapabilities` 项——`embeddedContext` 维持 false）；**上限量级与 `read`
+ * 同源**（行上限直引核 `MAX_READ_LINES`——零副本）。
+ *
+ * 降级标记 = 单行固定词表（11 词——机检面锚；块间独立，单块失败不影响他块）。
+ */
+import { readFile, stat } from "node:fs/promises"
+import { resolve as resolvePath } from "node:path"
+// 行上限与 read 工具同源（设计档 §2.5「上限量级与 read 同源」——直引，零副本）。
+import { MAX_READ_LINES } from "@thincoder/core/tools/shared.mjs"
+
+/** 文件级字节闸（10MB——先于读取；D-9：字节闸 = 文件级 ∥ 行/字符闸 = 载荷级）。 */
+export const MAX_INLINE_BYTES = 10 * 1024 * 1024
+/** 载荷级行闸（直引 `read` 工具同源值）。 */
+export const MAX_INLINE_LINES = MAX_READ_LINES
+/** 载荷级字符闸（100k 字符）。 */
+export const MAX_INLINE_CHARS = 100_000
+
+/** 降级标记形：单行、无围栏——`<reason>` ∈ 固定词表（设计档 §2.5 第 7 段）。 */
+const marker = (path, reason) => `[File reference: ${path} — ${reason}]`
+
+/** 选区文法：`#L<a>` ∥ `#L<a>-<b>` ∥ `#L<a>:<b>`（`b` 可带 `L` 前缀——含 `#L5:15` / `#L10-L20` 两观察形）。 */
+const SELECTION_RE = /^#L(\d+)(?:[-:]L?(\d+))?$/
+
+/** 成功形：头行 + 无语言标记围栏（内容原样；缺尾换行时补一终止换行，围栏不粘连正文）。 */
+function fenced(header, content) {
+  const body = content.endsWith("\n") ? content : `${content}\n`
+  return `${header}\n\`\`\`\n${body}\`\`\``
+}
+
+/** 单块 → 内联段或降级标记（块间独立）。 */
+export async function resolveResourceLink(block, { cwd } = {}) {
+  // ① uri 非字符串 ⇒ missing uri（路径位 = block.name ?? "unknown"）
+  const raw = block?.uri
+  if (typeof raw !== "string") return marker(block?.name ?? "unknown", "missing uri")
+
+  // ② uri 解析：file: ⇒ 解码 + UNC/盘符收正；非 file ⇒ unsupported scheme；解析失败 ⇒ 纯路径
+  let path = null
+  let hash = ""
+  let url = null
+  try { url = new URL(raw) } catch { url = null }
+  if (url) {
+    if (url.protocol !== "file:") return marker(raw, "unsupported scheme")
+    try { path = decodeURIComponent(url.pathname) } catch { return marker(raw, "invalid percent-encoding") }
+    if (url.hostname && url.hostname !== "localhost") path = `//${url.hostname}${path}` // UNC 主机
+    else if (/^\/[A-Za-z]:/.test(path)) path = path.slice(1) // Windows 盘符（/C:/… → C:/…）
+    hash = url.hash
+  } else {
+    try { path = decodeURIComponent(raw) } catch { return marker(raw, "invalid percent-encoding") }
+  }
+  path = resolvePath(cwd ?? process.cwd(), path) // 相对路径按 cwd；已在盘面形则归一平台原生分隔符
+
+  // ③ 选区解析（仅 url.hash；非选区哈希 = 锚点 ⇒ 整文）
+  let sel = null
+  if (hash) {
+    const m = SELECTION_RE.exec(hash)
+    if (m) {
+      const a = Number(m[1])
+      const b = m[2] === undefined ? a : Number(m[2])
+      if (a < 1 || b < 1 || b < a) return marker(path, "invalid selection")
+      sel = { a, b }
+    }
+  }
+
+  // ④ 读面：stat（unreadable / not a regular file / too large——文件级先于读取）→ 读取 → NUL
+  let st
+  try { st = await stat(path) } catch { return marker(path, "unreadable") }
+  if (!st.isFile()) return marker(path, "not a regular file")
+  if (st.size > MAX_INLINE_BYTES) return marker(path, "too large (>10MB)")
+  let buf
+  try { buf = await readFile(path) } catch { return marker(path, "unreadable") }
+  if (buf.includes(0)) return marker(path, "binary (NUL byte)")
+  const content = buf.toString("utf8")
+
+  // ⑤ 选区内容检查：a > 总行数 ⇒ lines out of range；b 超尾 ⇒ 截到总行数。
+  //    行模型 = `\n` 分界；文末换行符 = 终止符（不计行）——编辑器行号语义。
+  const lines = content.split("\n")
+  if (content.endsWith("\n")) lines.pop()
+  let slice = content
+  let lineCount = lines.length
+  let header = `[File: ${path}]`
+  if (sel) {
+    if (sel.a > lines.length) return marker(path, "lines out of range")
+    const b = Math.min(sel.b, lines.length)
+    slice = lines.slice(sel.a - 1, b).join("\n")
+    lineCount = b - sel.a + 1
+    header = `[File: ${path} lines ${sel.a}–${b}]`
+  }
+
+  // ⑥ 载荷级上限（选区时作用于选区切片，整文时作用于全篇）
+  if (lineCount > MAX_INLINE_LINES) return marker(path, "too many lines (>2000)")
+  if (slice.length > MAX_INLINE_CHARS) return marker(path, "too long (>100000 chars)")
+
+  // ⑦ 成功形
+  return fenced(header, slice)
+}
+
+/** 聚合（设计档 §2.5 目标形）：文本段 = 首个 `type:"text"` 且 `text` 为字符串的块（首块策略；
+ *  「首块」判据 = 首个**合法** text 块——畸形首块不再吞掉后续合法块）；资源段按数组序逐
+ *  `resource_link` 块解析；段间 `\n\n` 连接；文本段在前、资源段随后（保序）。
+ *  空结果 ⇒ 调用方走既有 `-32602` 通道。 */
+export async function buildPromptText(blocks, { cwd } = {}) {
+  const list = Array.isArray(blocks) ? blocks : []
+  const segments = []
+  const text = list.find((b) => b?.type === "text" && typeof b?.text === "string")?.text
+  if (text) segments.push(text)
+  for (const b of list) {
+    if (b?.type !== "resource_link") continue
+    segments.push(await resolveResourceLink(b, { cwd }))
+  }
+  return segments.join("\n\n")
+}

package/src/acp/session.mjs

@@ -19,7 +19,7 @@ import { buildAcpCallbacks } from "./bridge.mjs"
 
 export function createAcpSession({ id, agent, notify, request = async () => { throw new Error("no request channel") }, log = () => {}, run = runAgent, save = saveSession, clientCaps = {} }) {
   let controller = new AbortController()
-  const callbacks = buildAcpCallbacks({ sessionId: id, notify, request, log, clientCaps })
+  const callbacks = buildAcpCallbacks({ sessionId: id, agent, notify, request, log, clientCaps })
   let queue = Promise.resolve()
   let busy = false
 

package/src/acp.mjs

@@ -3,15 +3,16 @@
  * Agent Client Protocol (schema v1) on stdio, so ACP clients (Zed, JetBrains
  * AI Chat, Paseo) can drive sessions directly.
  *
- * Handler bodies live in four modules (division + criteria = docs/cli/design/ACP-CLIENT.md
+ * Handler bodies live in five modules (division + criteria = docs/cli/design/ACP-CLIENT.md
  * §3.5 — the former 368-line single-function `buildAcpHandlers` split by method family):
  *   acp/client-caps.mjs       initialize / authenticate（版本协商 · 能力快照 · authMethods 构造）
  *   acp/handlers-session.mjs  session/{new,prompt,cancel,close,set_mode,set_config_option} + 门助手
  *   acp/handlers-slots.mjs    session/{list,load,resume,delete}（持久化槽族）
  *   acp/ext.mjs               checkpoint/* · memory/*
+ *   acp/read-data.mjs         ledger/list · ledger/count · batch/list + ledger/changed · batch/changed（只读数据接口）
  *   acp/login.mjs             `--login` terminal auth flow (non-stdio)
  * This file keeps constants, the injectable defaults and the assembly — the seam
- * `buildAcpHandlers(deps)` (signature + `{ handlers, sessions, notifyRef, requestRef }`)
+ * `buildAcpHandlers(deps)` (signature + `{ handlers, sessions, notifyRef, requestRef, watcher }`)
  * is the only external contract (both existing ACP test files drive it directly).
  *
  * #41（2026-09-18）：`session/load` / `session/resume` 两路工程模式会话改「先判后装载」
@@ -29,9 +30,10 @@ import { assembleAgent } from "./cli/make-agent.mjs"
 import { createAcpServer } from "./acp/transport.mjs"
 import { createAcpSession } from "./acp/session.mjs"
 import { createCapsHandlers } from "./acp/client-caps.mjs"
-import { createRequireConfigured, createSessionHandlers } from "./acp/handlers-session.mjs"
+import { createRequireConfigured, createSessionHandlers, createSlotReleaser } from "./acp/handlers-session.mjs"
 import { createSlotsHandlers } from "./acp/handlers-slots.mjs"
 import { createExtHandlers } from "./acp/ext.mjs"
+import { createReadDataHandlers } from "./acp/read-data.mjs"
 
 const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version
 
@@ -96,33 +98,39 @@ export function buildAcpHandlers({
   const notifyRef = { current: notify }
   const requestRef = { current: async () => { throw new Error("no request channel") } }
   const sessions = new Map()
-  let nextId = 1
   /** §3.4 客户端能力快照：`initialize` 单次写入，之后只读（快照丢失 ⇒ 全取 false ⇒ 本地兜底）。 */
   const clientCaps = { current: {} }
-  /** 共享态经单一 `ctx` 传入（§3.5）——id 分配器与槽族共享，命名空间不因拆分而裂。 */
+  /** 共享态经单一 `ctx` 传入（§3.5）——会话 id = 持久槽位号串（load/new 同命名空间——G5 收正）；
+   *  `releaseClosedSlot` = 认领释放单点（close ∥ load/resume 替换 三处同源消费）。 */
   const ctx = {
     getCwd: cwd,
     sessions,
-    allocSessionId: () => String(nextId++),
     notifyRef,
     requestRef,
     // 能力位按「session/new 时刻取值」注入每个会话（§11.4——会话生命周期内不变）
     createSession: (opts) => createSession({ ...opts, clientCaps: clientCaps.current }),
     // 门助手由入口建一次、按引用传（§11.5——`session/new` 是门链首个触点）
     requireConfigured: createRequireConfigured({ isConfigured, providerStatus }),
+    // 认领释放单点由入口建一次、按引用传（§2.4——close ∥ load 替换 ∥ resume 替换同源）
+    releaseClosedSlot: createSlotReleaser({ getCwd: cwd, sessions }),
     log,
   }
 
+  // 只读数据接口族（read-data-interface 批）：三方法 + 变更观察器（`runAcpServer` 启动）。
+  const readData = createReadDataHandlers(ctx)
+
   return {
     handlers: {
       ...createCapsHandlers({ version, clientCaps, requireConfigured: ctx.requireConfigured, log }),
       ...createSessionHandlers(ctx),
       ...createSlotsHandlers(ctx),
       ...createExtHandlers(ctx),
+      ...readData.handlers,
     },
     sessions,
     notifyRef,
     requestRef,
+    watcher: readData.watcher,
   }
 }
 
@@ -138,6 +146,7 @@ export async function runAcpServer() {
   const server = createAcpServer(built.handlers, { log })
   built.notifyRef.current = server.notify
   built.requestRef.current = server.request
+  built.watcher.start() // 变更观察器：首查立基线（静默）+ 5s 指纹轮询（进程终灭即止）
   log(`[acp] thincoder ${VERSION} — ACP v1 over stdio, waiting for initialize`)
   server.start()
 }

package/src/command-interactive.mjs

@@ -30,14 +30,23 @@ export async function chatCommand(args, ctx) {
   if (crashNotice) console.error(crashNotice)
 
   const agent = await assembleAgent()
-  // SESSION.md §6.8 D-S4（F4）+ MODEL-MERGE-SESSION：headless 无 TUI —— 可读错误 + 退出码 1，
-  // 不弹 UI、不崩溃；文案改引 defaultModel（F-6 引导 A headless 面——/config → 默认模型）
-  if (agent._providerInvalid) {
-    const dm = agent.config?.defaultModel
-    console.error(`[error] 未配置有效模型（defaultModel "${dm ?? "(not set)"}"：${agent._providerInvalidReason}）。请运行 thincoder 进入 TUI 设置（/config → 默认模型；或 /model 选择后以会话槽生效），或编辑 ${configPath}`)
+  // SESSION.md §6.8 D-S4（#841 收正）：headless 无 TUI——按**核统一态分流**（判据单源 = PROVIDER.md §6.22，
+  // 与 TUI 面同式）：**invalid 类**（`state === "invalid"` ∨ `providerInvalidReason` 非空——无渠/key
+  // ⇒ 不可运行）⇒ 可读错误 + 退出码 1（不弹 UI、不崩溃）；**fallback**（无有效 defaultModel 但可运行）
+  // ⇒ stderr 一行明示 + 继续运行（不退出——D-S2 同态同解）。条目结构不全不在本门（负向锁 =
+  // PROVIDER.md:437）——归运行期失败径（stderr + 非 0 退出）。
+  const headlessCfg = agent.config ?? {}
+  const invalidClass = headlessCfg.providerState === "invalid"
+    || (typeof headlessCfg.providerInvalidReason === "string" && headlessCfg.providerInvalidReason !== "")
+  if (invalidClass) {
+    console.error(`[error] 未配置有效渠道（${agent._providerInvalidReason ?? headlessCfg.providerStateReason ?? "provider unavailable"}）。请运行 thincoder 进入 TUI 设置（/config 设置渠道与密钥；或 /model 选择后以会话槽生效），或编辑 ${configPath}`)
     exitSoon(1)
     return
   }
+  if (headlessCfg.providerState === "fallback" && agent.provider?.name) {
+    const m = typeof agent.provider.model === "string" && agent.provider.model ? `:${agent.provider.model}` : ""
+    console.error(`尚未设置默认模型：本次使用 \`${agent.provider.name}${m}\`——/config → 默认模型 设置一次（或 /model 选定即成为默认模型）`)
+  }
   if (!agent.provider.apiKey) {
     if (!process.stdin.isTTY) {
       console.error(noKeyMessage())
@@ -121,9 +130,10 @@ export async function tuiCommand(ctx) {
   // F-MI7：resumeSlot = async（探测束不阻塞事件循环）——此处必须 await
   const { slot, data } = await resumeSlot(process.cwd())
   const agent = await assembleAgent({ slotData: data })
-  // SESSION.md §6.8 D-S1：TUI 路径在 startTUI 前清空无效 provider——空 provider 不流入 runAgent
-  // （崩溃源：chat() 缺 model → 网关 400 或 fetch("undefined/...") TypeError）
-  if (agent._providerInvalid) agent.provider = null
+  // SESSION.md §6.8 D-S1（#841 收正）：TUI 路径**仅在 `state === "invalid"`**（无渠/key）于 startTUI
+  // 前置 `agent.provider = null`——空 provider 不流入 runAgent（崩溃源：chat() 缺 model → 网关 400
+  // 或 fetch("undefined/...") TypeError）；`fallback` 态 provider 有效——不清（可运行 + 明示）。
+  if (agent.config?.providerState === "invalid") agent.provider = null
   const config = loadConfig()
   if (data) {
     // applySession 内部已按槽复合重算 compactThreshold（auto 时）——不再需要 switched 分支

package/src/command-table.mjs

@@ -159,7 +159,14 @@ export async function runCommandTable(command, args, ctx) {
         process.exitCode = await (args[0] === "migrate" ? m.runLedgerMigrate(args) : m.runLedgerAudit(args))
         break
       }
-      console.error("Usage: thincoder ledger migrate --dry-run | --confirm [--from <key>] | thincoder ledger audit [--root <dir>]")
+      // 只读数据接口（read-data-interface 批）：`ledger list --json [--full] [--family] [--cwd <dir>]`——
+      // 核内 runner（ledger-read.mjs）严格解析（缺 --json / 未知参 ⇒ usage + exit 1）；壳侧只分发。
+      if (args[0] === "list") {
+        const m = await import("@thincoder/core/ledger-read.mjs")
+        process.exitCode = m.runLedgerList(args.slice(1))
+        break
+      }
+      console.error("Usage: thincoder ledger migrate --dry-run | --confirm [--from <key>] | thincoder ledger audit [--root <dir>] | thincoder ledger list --json [--full] [--family] [--cwd <dir>]")
       exitSoon(1)
       break
     }

package/src/completions.mjs

@@ -24,9 +24,10 @@ export function printCompletion(shell) {
         sweep)  COMPREPLY=( $(compgen -W "--origin= --dry-run --confirm" -- "$cur") ) ;;
       esac ;;
     ledger) case "$prev" in
-        ledger)  COMPREPLY=( $(compgen -W "migrate audit" -- "$cur") ) ;;
+        ledger)  COMPREPLY=( $(compgen -W "migrate audit list" -- "$cur") ) ;;
         migrate) COMPREPLY=( $(compgen -W "--dry-run --confirm --from" -- "$cur") ) ;;
         audit)   COMPREPLY=( $(compgen -W "--root" -- "$cur") ) ;;
+        list)    COMPREPLY=( $(compgen -W "--json --full --family --cwd" -- "$cur") ) ;;
       esac ;;
     distill) COMPREPLY=( $(compgen -W "--yes --layer=" -- "$cur") ) ;;
     completion) COMPREPLY=( $(compgen -W "bash zsh fish" -- "$cur") ) ;;
@@ -59,7 +60,7 @@ _thincoder() {
         'upgrade[Update to latest version from npm]' \\
         'completion[Generate shell completion script]' \\
         'session[Session dir GC: session gc --dry-run|--confirm]' \\
-        'ledger[Ledger variants: migrate / audit]'
+        'ledger[Ledger variants: migrate / audit / list]'
       ;;
     args)
       case "$words[1]" in
@@ -72,6 +73,7 @@ _thincoder() {
           esac ;;
         ledger) case "$words[2]" in
             migrate) _arguments '--dry-run[Report only]' '--confirm[Apply migration]' '--from:Source key:' ;;
+            list)    _arguments '--json[Single-segment JSON output]' '--full[Include evidence]' '--family[Family scope]' '--cwd:Project anchor:' ;;
             audit)   _arguments '--root:Scan root dir:' ;; esac ;;
         distill) _arguments '--yes[Skip confirmation]' '--layer=[Layer filter]' ;;
         completion) _values 'shell' 'bash' 'zsh' 'fish' ;;
@@ -94,7 +96,7 @@ complete -c thincoder -a distill  -d 'Extract knowledge from session'
 complete -c thincoder -a upgrade  -d 'Update to latest version'
 complete -c thincoder -a completion -d 'Shell completion'
 complete -c thincoder -a session -d 'Session dir GC (session gc --dry-run|--confirm)'
-complete -c thincoder -a ledger -d 'Ledger variants: migrate / audit'
+complete -c thincoder -a ledger -d 'Ledger variants: migrate / audit / list'
 complete -c thincoder -a acp -d 'Agent Client Protocol server for IDEs'
 
 # Flags
@@ -133,8 +135,9 @@ complete -c thincoder -n '__fish_seen_subcommand_from distill' -l layer -d 'Laye
 complete -c thincoder -n '__fish_seen_subcommand_from completion' -a bash -d 'Bash completions'
 complete -c thincoder -n '__fish_seen_subcommand_from completion' -a zsh  -d 'Zsh completions'
 complete -c thincoder -n '__fish_seen_subcommand_from completion' -a fish -d 'Fish completions'
-complete -c thincoder -n '__fish_seen_subcommand_from ledger' -a 'migrate audit' -d 'Ledger variants: migrate / audit'
+complete -c thincoder -n '__fish_seen_subcommand_from ledger' -a 'migrate audit list' -d 'Ledger variants: migrate / audit / list'
 complete -c thincoder -n '__fish_seen_subcommand_from ledger' -l dry-run -l confirm -l from -l root -d 'Ledger flags'
+complete -c thincoder -n '__fish_seen_subcommand_from ledger; and __fish_seen_subcommand_from list' -l json -l full -l family -l cwd -d 'Ledger list flags'
 `)
     }
 }

package/src/tui/cmd-model.mjs

@@ -5,7 +5,8 @@ import { parseModelRef } from "@thincoder/core/config.mjs"
  *  `/model <provider>:<model>`（MODEL-MERGE-SESSION——裁定③：裸 provider 拒——显式 p:m；
  *  MODEL-SELECTION v2：显式复合一律放行——仅[空值/裸值/未知 provider]无效（M4），候选清单
  *  由运行期拉取决定——不再有成员校验）。
- *  /model 是会话级操作（写槽——不写 config）——config 默认模型走 /config → 默认模型。
+ *  /model 是会话级操作（写槽）——选定实变即同拍写回 config.defaultModel（判据句 6——新会话
+ *  起点随动）。config 默认模型显式设置走 /config → 默认模型。
  *  ctx: { agent, openModelPicker, selectModel, pushLine } */
 export async function handleModelCommand(ctx, args = []) {
   const raw = args[0]?.trim()
@@ -18,7 +19,7 @@ export async function handleModelCommand(ctx, args = []) {
   const parsed = parseModelRef(raw, ctx.agent.providers)
   if (!parsed.ok) {
     ctx.pushLine(`[error] ${parsed.reason}`, C.error)
-    ctx.pushLine(`/model 用法: /model provider:model（会话级——config 默认走 /config → 默认模型）`, C.dim)
+    ctx.pushLine(`/model 用法: /model provider:model（会话级——选定即成为默认模型）`, C.dim)
     return
   }
   await ctx.selectModel({ provider: parsed.provider.name, model: parsed.model }).catch((e) => ctx.pushLine(`[error] ${e.message}`, C.error))

package/src/tui/cmd-reindex.mjs

@@ -1,9 +1,19 @@
+import { homedir } from "node:os"
+import { resolve } from "node:path"
 import { C } from "./ansi.mjs"
 
+/** home 根防护（#867 · `MEMORY.md` §6.14 L-④ · 同 startup.mjs）：`cwd` = 用户主目录（resolve 后；win32 大小写不敏感）。 */
+const isHomeDir = (dir) => typeof dir === "string" && dir !== "" &&
+  (process.platform === "win32" ? resolve(dir).toLowerCase() === resolve(homedir()).toLowerCase() : resolve(dir) === resolve(homedir()))
+
 /** /reindex command: rebuild memory index (files + code_chunks + doc_chunks).
  *  ctx: { agent, distillOpts, pushLine } */
 export async function handleReindexCommand(ctx) {
   const { agent, distillOpts, pushLine } = ctx
+  if (isHomeDir(agent.cwd)) { // #867：home 根 ⇒ 跳过（零表删 ∥ 三 sync 零调用；含出路提示）
+    pushLine("[reindex] Skipped: working directory is the home directory — start in a project dir", C.warn)
+    return
+  }
   const { syncDir, codeSync, docSync } = await import("@thincoder/core/memory.mjs")
   pushLine("[reindex] Rebuilding index...", C.tool)
   agent.memory.db.prepare("DELETE FROM files").run()

package/src/tui/cmd-undo.mjs

@@ -1,46 +1,17 @@
 /**
  * cmd-undo.mjs — /undo command: revert recent file modifications
  *
- * Tracks write/edit/delete/hashline_edit/apply_patch operations in agent._undoStack.
- * /undo opens a picker to select and revert an operation.
+ * Reads the snapshot stack (`agent._undoStack`) — snapshot single point = `thincoder-core/undo-stack.mjs`
+ * (`snapshotForUndo`；CLI 侧旧副本已删 —— 单源 = 核档 · CORE-UNIFICATION §2.5 #149）。
+ * /undo opens a picker to select and revert an operation; **oversize 占位**（无快照 —— 备份超
+ * `MAX_UNDO_BYTES`）**列表可见 · 不可回退**（#863 · `docs/cli/design/TUI-COMMANDS.md` §5.3）。
  */
 
-import { existsSync, writeFileSync, unlinkSync, readFileSync } from "node:fs"
+import { existsSync, writeFileSync, unlinkSync } from "node:fs"
 import { isAbsolute, join } from "node:path"
+import { MAX_UNDO_BYTES } from "@thincoder/core/undo-stack.mjs"
 import { ansi, C } from "./ansi.mjs"
 
-const MAX_UNDO = 50
-
-/**
- * Snapshot a file before a side-effect tool modifies it.
- * Called from dispatch.mjs before each write/edit/delete/apply_patch/hashline_edit.
- */
-export function snapshotForUndo(agent, toolName, args, cwd) {
-  if (!agent._undoStack) agent._undoStack = []
-  const path = args.path ?? args.file
-  if (!path || typeof path !== "string") return
-
-  // 绝对路径直接用（path.join 对绝对段不重置——Windows 反斜杠路径也不按 "/" 切分）；相对路径整段 join(cwd)。
-  const abs = isAbsolute(path) ? path : join(cwd, path)
-  let backup = null
-  try {
-    if (existsSync(abs)) {
-      backup = readFileSync(abs, "utf8")
-    }
-  } catch {
-    // can't read — maybe binary, skip
-    return
-  }
-
-  agent._undoStack.push({
-    tool: toolName,
-    path,
-    backup,
-    timestamp: Date.now(),
-  })
-  if (agent._undoStack.length > MAX_UNDO) agent._undoStack.shift()
-}
-
 export async function handleUndoCommand(ctx) {
   const { agent, pushLine, showPicker } = ctx
   const stack = agent._undoStack ?? []
@@ -55,9 +26,11 @@ export async function handleUndoCommand(ctx) {
     ...stack.map((item, i) => {
       const relIdx = stack.length - i
       const time = new Date(item.timestamp).toLocaleTimeString()
-      const preview = item.backup === null
-        ? "(was created — undo will delete)"
-        : `(${item.backup.split("\n").length} lines — undo will restore)`
+      const preview = item.oversize === true
+        ? "(no snapshot — too large to undo)"
+        : item.backup === null
+          ? "(was created — undo will delete)"
+          : `(${item.backup.split("\n").length} lines — undo will restore)`
       return {
         type: "item",
         text: `#${relIdx} ${item.tool}: ${item.path} ${preview} — ${time}`,
@@ -69,6 +42,11 @@ export async function handleUndoCommand(ctx) {
   const e = await showPicker("Undo", entries)
   if (!e) return
   const item = stack[e.idx]
+  if (item.oversize === true) {
+    // #863：oversize 占位（无快照）——须先判 `oversize` 再判 `backup === null`，否则被当「文件创建」态误删档。
+    pushLine(`[undo] Cannot revert ${item.tool} ${item.path} — no snapshot (file larger than ${MAX_UNDO_BYTES / 1_000_000} MB)`, C.warn)
+    return
+  }
   const abs = isAbsolute(item.path) ? item.path : join(agent.cwd, item.path)
 
   try {

package/src/tui/config-helpers.mjs

@@ -1,6 +1,7 @@
 /** persistRaw / syncProviderField / maskKey: config read/write helpers.
  *  Extracted from index.mjs for shared use by slash-commands, wizard, and pickers.
- *  createConfigHelpers(agent) returns { persistRaw, syncProviderField, maskKey }
+ *  createConfigHelpers(agent) returns { persistRaw, syncProviderField, maskKey }；模块级另导出
+ *  carryoverDefaultModel（会话选定写回单点——SESSION.md §6.21 判据句 6；见下方定义）。
  *  R10 F5（D-F5b）：persistRaw 全链（磁盘新鲜读→mutate→写）收口进 config.mjs
  *  writeConfigAtomic——mtime 门控 + .bak + 冲突放弃（见 MULTI-INSTANCE-COLLAB.md §2a.2）。
  *  createConfigHelpers(agent, opts)：opts.configPath 为测试注入缝（默认 configPath——
@@ -44,3 +45,35 @@ export function createConfigHelpers(agent, opts = {}) {
 
   return { persistRaw, syncProviderField, maskKey }
 }
+
+/** 会话选定写回单点（SESSION.md §6.21 判据句 6——用户显式选定 ⇒ 同拍写回 config.defaultModel
+ *  = "<provider>:<model>"；新会话起点随用户最后一次显式选择）。门内聚于本单点（KD-883-1——
+ *  call-site 零判据、零复合串）：
+ *  ① 槽面实变门：slotBefore 复合串 = 选定复合 ⇒ 零写（回声 ∕ 重选——系统同步不劫持全局默认）；
+ *  ② 等值门：现值 `loadConfig().defaultModel` 同串 ⇒ 零写（防盘面抖动 ∥ 探针空转）。
+ *  写经核 `writeConfigAtomic` + `_configPath()`（mtime 门控 + `.bak` 现场）；失败不反扑会话写、
+ *  绝不抛出——畸形档 ∥ 写错误 ⇒ `{ ok:false, reason }`。返回 `{ ok:true, written:boolean }`。 */
+export async function carryoverDefaultModel({ provider, model, slotBefore = null } = {}) {
+  const composite = compositeOf(provider, model)
+  if (composite === null) return { ok: false, reason: "invalid model reference — expected provider:model" }
+  try {
+    const { loadConfig } = await import("@thincoder/core/config.mjs")
+    const { writeConfigAtomic, _configPath } = await import("@thincoder/core/config-io.mjs")
+    const before = compositeOf(slotBefore?.activeProvider, slotBefore?.activeModel)
+    if (before === composite) return { ok: true, written: false } // ① 槽面实变门（档缺 ⇒ null ⇒ 判真）
+    if (loadConfig().defaultModel === composite) return { ok: true, written: false } // ② 等值门
+    const r = writeConfigAtomic(_configPath(), (raw) => { raw.defaultModel = composite })
+    if (!r.ok) return { ok: false, reason: r.reason }
+    return { ok: true, written: true }
+  } catch (error) {
+    return { ok: false, reason: error?.message ?? String(error) }
+  }
+}
+
+/** 复合串（比较单元构造单源——首冒号分割语义 = parseModelRef 同族）：双段非空 ⇒
+ *  "provider:model"；档缺 ∕ 半缺 ⇒ null（无基线——不参与相等判定）。 */
+function compositeOf(provider, model) {
+  const p = typeof provider === "string" && provider ? provider : null
+  const m = typeof model === "string" && model ? model : null
+  return p && m ? `${p}:${m}` : null
+}