@thincoder/core 0.10.3 → 0.10.4

package/agent-tools/zero-write-watch.mjs

@@ -0,0 +1,77 @@
+/**
+ * zero-write-watch.mjs — 零落笔看门狗叶（批 subagent-zero-write-watchdog · 台账 #934）。
+ * 设计权威 = `docs/core/design/AGENT-LOOP-UPSTREAM.md` §6.32；需求 = `docs/core/requirements/AGENT-LOOP.md` §4.16。
+ *
+ * 两族（§6.32.2）：子代理族 = eng-coder / eng-designer **连续** N 轮零文件写（采集点邻单点 =
+ * `agent/turn-loop.mjs` 轮顶——streak 更新与越阈判定同点）；评审族 = 异步评审 **连续** N 轮零评审
+ * 文本产出（`advisor/loop.mjs` 循环局部计数 + 可选钩子 `seams.onStallRound`）。
+ *
+ * 送达 = 复用 §6.27 上行通道（`pushChildUpstream`——note 类：同队列同消费点、零唤醒、零新容器）；
+ * **只推提醒**——不自动杀 / 不自动转向 / 不代父侧动作（§6.32.10-1）。
+ * 防轰炸 = 闩 + 写后重臂（子代理族：`_zeroWriteAlerted`；评审族：单次运行闩——§6.32.3）。
+ * 文案单源 = 本档两族文本函数（§6.32.4 逐字——父侧定稿；`from` + 轮数为唯一变量）。
+ * 零依赖叶：静态 import 只取 `parent-channel.mjs` 的 `pushChildUpstream`（不引池 / 端面 / 循环）。
+ */
+import { pushChildUpstream } from "./parent-channel.mjs"
+
+/** 阈值单源（连续轮数——两族共用；§6.32.2 阈值固定 50，不做配置键）。 */
+export const ZERO_WRITE_ALERT_ROUNDS = 50
+
+/** 子代理族触面（用户点名三角色中的两位——有文件写面；explore / plan / consult / 普通 coder / depth-0 不设）。 */
+const WATCH_ROLES = new Set(["eng-coder", "eng-designer"])
+
+/** 子代理族文案（§6.32.4 逐字——父侧定稿；`from` = `_upstream.label`，形 `role#id`）。 */
+export function zeroWriteAlertText(from, rounds) {
+  return `[zero-write watchdog] ${from}: ${rounds} consecutive rounds with no file write — take a look (subagent action:'status' for the live view).`
+}
+
+/** 评审族文案（§6.32.4 逐字——父侧定稿；`from` = `advisor#<entry id>`）。 */
+export function advisorAlertText(from, rounds) {
+  return `[zero-write watchdog] ${from}: ${rounds} consecutive rounds with no review output — take a look (subagent action:'status' / 'cancel').`
+}
+
+/**
+ * 子代理族判定 + 推送（§6.32.6）——门 = `_role` ∈ 触面 ∧ `_upstream.parent` 在场 ∧
+ * `_zeroWriteStreak` **为整数** ≥ 阈值（缺字段 / 非整数 ⇒ 不判——不冒充 `0`）∧ 未闩；
+ * 命中 ⇒ `pushChildUpstream({parent, from: _upstream.label, kind: "note", message})` + 置闩。
+ * **恒零抛**（兜底捕获兑现——自动源无模型可报错；失败面静默跳过）。
+ * @param {object} child 子 agent（eng-coder / eng-designer 形态；`_upstream` 由 spawn 站点装配）。
+ * @returns {boolean} 是否命中推送（测试面）。
+ */
+export function maybeZeroWriteAlert(child) {
+  try {
+    if (!WATCH_ROLES.has(child?._role)) return false
+    const upstream = child._upstream
+    if (!upstream?.parent) return false
+    const streak = child._zeroWriteStreak
+    if (!Number.isInteger(streak) || streak < ZERO_WRITE_ALERT_ROUNDS) return false
+    if (child._zeroWriteAlerted) return false
+    pushChildUpstream({
+      parent: upstream.parent,
+      from: upstream.label,
+      kind: "note",
+      message: zeroWriteAlertText(upstream.label, streak),
+    })
+    child._zeroWriteAlerted = true
+    return true
+  } catch {
+    return false // 恒零抛兑现（§6.32.6——失败面静默跳过）
+  }
+}
+
+/**
+ * 评审族推送（组合文案 + push——呼点 = 评审环路钩子 `seams.onStallRound`，单次运行至多一次）。
+ * **恒零抛**（实现面兜底捕获兑现——抛错不得上抛为评审 failed 面；§6.32.6）。
+ * @param {object} parent 父 agent（接收方——`pushChildUpstream` 载体吸收同款）。
+ * @param {string} from 来源标签（`advisor#<entry id>`）。
+ * @param {number} rounds 连续无产出轮数。
+ * @returns {boolean} 是否推送成功（测试面）。
+ */
+export function pushAdvisorAlert(parent, from, rounds) {
+  try {
+    pushChildUpstream({ parent, from, kind: "note", message: advisorAlertText(from, rounds) })
+    return true
+  } catch {
+    return false
+  }
+}

package/agent.mjs

@@ -100,6 +100,6 @@ export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal
     // 2026-09-05 实践轮：回合收尾（consult 清理/async 池分流/guard 继承——原 425-462
     // 段 + collectSettledAsync 466-494 整体迁 agent/run-stages.mjs finalizeAgentTurn——
     // CLI 对位 VS run-stages——finally 只剩一行调用 + 骨架注释）。
-    await finalizeAgentTurn(agent, { signal, autoTurn, suspDriven, thrownError, depth })
+    await finalizeAgentTurn(agent, { signal, autoTurn, upstreamTurn, timerTurn, suspDriven, thrownError, depth })
   }
 }

package/conventions.mjs

@@ -26,9 +26,10 @@
  *   code — inside a declared code segment (default: the path segment `src`), or the
  *          fallback;  doc — documentation extension outside any code segment and not
  *          scratch;  temp — tmp-* name or .tmp/.temp extension;  aux — a default
- *          auxiliary-path segment sequence (test / tests / scripts / .thincoder/tmp —
- *          F9) that matched no code segment and neither doc nor temp.
- * Precedence: code segment → temp → doc → aux → fallback code.
+ *          auxiliary-path segment sequence (test / tests / scripts / .thincoder/tmp — F9)
+ *          that matched no code segment and neither doc nor temp;  state — a project state
+ *          file (`PROJECT-MANIFEST.json` basename ∥ `.thincoder/conventions.json` pair — #941).
+ * Precedence: code segment → temp → doc → aux → state → fallback code.
  *
  * Segment matching runs on the PROJECT-ROOT-RELATIVE FACE of a path (D17 · 2026-09-28): the
  * machine layout ABOVE the project root never participates. An absolute path outside the
@@ -128,18 +129,32 @@ function hasAuxSegment(p, conv) {
   return hasSegmentSequence(p, DEFAULT_AUX_PATHS, conv?.root, false)
 }
 
-/** "code" | "doc" | "temp" | "aux" — the single classification decision.
+/** Project state-file markers (data — #941 · PORTABILITY D19): manifest basename (any layer) ∥
+ *  retired-carrier pair; single sources: `MANIFEST_REL` ∥ `RETIRED_REL_PATH`. */
+const STATE_BASENAME = "project-manifest.json"
+const STATE_PAIR = ".thincoder/conventions.json"
+
+/** True when `s` names a project state file (basename any layer ∥ segment pair; case-insensitive — no face, D17). */
+function isStateFile(s) {
+  const segs = segmentsOf(s)
+  if (segs.length > 0 && lowerSeg(segs[segs.length - 1]) === STATE_BASENAME) return true
+  return hasSequenceIn(segs, [STATE_PAIR])
+}
+
+/** "code" | "doc" | "temp" | "aux" | "state" — the single classification decision.
  *  Precedence: code segment first (src/** stays product code even when the name
  *  looks scratch — the pre-existing unconditional-src rule), then temp, then a
  *  documentation extension, then an auxiliary-path segment sequence (test / tests
- *  / scripts / .thincoder/tmp — F9), else code (anything not doc/temp/aux is product
- *  code). Both segment checks run on the project-root-relative face (D17 — `faceOf`). */
+ *  / scripts / .thincoder/tmp — F9), then a project state file (#941), else code
+ *  (anything not doc/temp/aux/state is product code). Segment checks face-bound (D17);
+ *  state matches by name marker. */
 export function classifyPath(p, conv) {
   const s = String(p ?? "")
   if (hasCodeSegment(s, conv)) return "code"
   if (TEMP_FILE.test(s)) return "temp"
   if (DOC_FILE.test(s)) return "doc"
   if (hasAuxSegment(s, conv)) return "aux"
+  if (isStateFile(s)) return "state"
   return "code"
 }
 
@@ -165,6 +180,11 @@ export function isAuxPath(p, conv) {
   return classifyPath(p, conv) === "aux"
 }
 
+/** True when the path is a project state file (`classifyPath === "state"` — #941; derived form). */
+export function isStatePath(p, conv) {
+  return classifyPath(p, conv) === "state"
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // 迁出面（2026-10-01 拆分批 · #755 ∥ #786）：声明装载面外提 `declaration.mjs`——本档经
 // 转口保名（消费面 / 批内件 import 面零改；`DEFAULT_DECLARATION` 另供本档分类裁判缺省取用）。

package/escape.mjs

@@ -52,7 +52,7 @@ export function escapeLiteralEscapes(text) {
   return out
 }
 
-/** 净化孤立 UTF-16 代理对（毒源②）：高代理无低代理跟随 / 低代理无高代理前置 → 替换为 。 */
+/** 净化孤立 UTF-16 代理对（毒源②）：高代理无低代理跟随 / 低代理无高代理前置 → 剥除（出串零该码元——码 :66/:68 实读为准）。 */
 export function sanitizeLoneSurrogates(text) {
   text = String(text ?? "")
   let out = ""

package/i18n.mjs

@@ -41,6 +41,9 @@ export const CORE_MESSAGES = Object.freeze({
   "digest.turnLabelAsk": { en: "[auto-turn: answering ${from}: ${msg}]", zh: "自动回合：答复 ${from}：${msg}" },
   "digest.capAuto": { en: "[auto-turn: continuing past turn cap…]", zh: "自动回合：越过轮次上限，继续推进…" },
   "digest.capStop": { en: "[auto-turn stopped at ${turns} turns — partial digest; finished reports stay in history]", zh: "自动回合在 ${turns} 轮处停止——部分消化；已完成的报告保留在历史中" },
+  // 消化账务批 · 2026-10-05 · 台账 #930（§6.31.6 端面残余行——判据 = `unsettledCount(carrier)`；
+  // 消费面 = CLI 痕行 ∥ 桌面 / VSC 行元素；三端共读本键）
+  "digest.residue": { en: "${n} background report(s) not accounted — they will be re-delivered", zh: "有 ${n} 份后台报告未销账——将自动重投" },
   // ── 限流 / 供应商状态行 ──
   "status.rateWait": { en: "TPM throttle wait ~${s}s", zh: "TPM 限流等待 ~${s}s" },
   "status.rateLimited": { en: "Rate-limited 429, retry in ${s}s", zh: "限流 429，${s}s 后重试" },
@@ -69,6 +72,8 @@ export const CORE_MESSAGES = Object.freeze({
   "status.turn": { en: "turn ${n}/${m}", zh: "轮次 ${n}/${m}" },
   "tool.running": { en: "running…", zh: "执行中…" },
   "tool.done": { en: "done", zh: "完成" },
+  // ── 台账（ledger）· F-LX3 变体键库首跑提示（批 2026-10-05-ledger-variant-db-notice · 台账 #935 · LEDGER.md §12.2 逐字；消费面 = CLI TUI 启动行）
+  "ledger.variantDbNotice": { en: "Legacy variant-key ledger DB found for this project (pre-upgrade; rows may be outside the current ledger): thincoder ledger audit to inspect; thincoder ledger migrate to reconcile", zh: "检测到本项目的存量变体键台账库（升级遗留，数据可能未并入当前库）：thincoder ledger audit 查看；thincoder ledger migrate 收正" },
 })
 // 深度冻结（机器消费面冻结——嵌套 { en, zh } 也冻结；浅冻结下值可被静默改写）。
 for (const entry of Object.values(CORE_MESSAGES)) Object.freeze(entry)

package/ledger-tools.mjs

@@ -1,14 +1,16 @@
 /**
- * ledger-tools.mjs — 台账五工具定义（查询二 = 只读全角色 / 写三 = 仅主 agent 装配）+ 工具层参数守卫。
- * 自 `ledger-cmd.mjs` 拆出（2026-09-28 守卫族微修批 · 台账 #473——纯搬移、语义零变；核函数留原档）。
- * 守卫 = **声明派生**（设计档 §3.2：枚举 / 必填 / 类型取自工具自身 `parameters`，不在守卫内复写——
- * D2「声明即校验」）；判于核函数之前 ⇒ 非法入参零写、零库动作、零 SQLite 原文外泄。读面二具同拍
- * （#473：非法过滤参数 ⇒ 拒——不再「静默空集 / 绑原文」）。
- * 接线：族出口 = `ledger.mjs`（re-export——消费面 tools/index.mjs · agent/family-tools.mjs 零改）；
- * 消费侧一律动态 import `ledger.mjs`（ledger-db.mjs 静态 import node:sqlite ⇒ W8 契约②）。
+ * ledger-tools.mjs — 台账**统一入口** `ledger`（action 分派）+ 五旧名弃用壳 + 工具层参数守卫。
+ * 自 `ledger-cmd.mjs` 拆出（2026-09-28 守卫族微修批 · 台账 #473）；2026-10-05 统一入口批
+ * （台账 #923）合五工具为一：模型面恰一名 `ledger`（两变体同名单对象、schema 窄化——
+ * 全量 = depth-0 五 action ∥ 只读 = depth>0 二 action）；旧五名 = code 面弃用壳（不入任何装配面）。
+ * 守卫 = **声明派生**（设计档 §3.2 / §11.3：判序① 入参归一 → ② 入口级 action 判（消费 action）→
+ * ③ 余键喂该 action 伪工具对象走 P2–P6——声明源 = 前身旧工具 `parameters` 逐字；helper `assertToolArgs`
+ * 零改）；判于核函数之前 ⇒ 非法入参零写、零库动作、零 SQLite 原文外泄。
+ * 接线：族出口 = `ledger.mjs`（re-export——消费面 agent/family-tools.mjs；旧读二装配面已清零）；
+ * 消费侧一律动态 import（`ledger-db.mjs` 静态 import node:sqlite ⇒ W8 契约②）。
  */
 import { ledgerAdd, ledgerClose, ledgerCount, ledgerQuery, ledgerUpdate } from "./ledger-cmd.mjs"
-import { DESC } from "./tools/shared.mjs" // #15 描述外置：文本单点 = tool-docs/ledger_*.md（DESC 单解析面）
+import { DESC } from "./tools/shared.mjs" // #15 描述外置：文本单点 = tool-docs/ledger.md（DESC 单解析面）
 
 /** 工具 cwd 供值面（缺省 → 当前项目根）。 */
 const cwdOf = (ctx) => ctx?.agent?.cwd ?? ctx?.cwd ?? process.cwd()
@@ -68,51 +70,22 @@ function assertToolArgs(tool, args) {
   return args
 }
 
-// ── 工具定义（接线：查询 → tools/index.mjs 全角色面；写 → family-tools.mjs depthOnly 分支） ──
+// ── 统一入口（设计档 §11.2 / §11.3） ─────────────────────────────────────────
 
-export const ledgerQueryTool = {
-  name: "ledger_query",
-  description: DESC("ledger_query"), // #15 外置：文本单点 = tool-docs/ledger_query.md（两池词表逐字保留）
-  parameters: {
-    type: "object",
-    properties: {
-      cwd: { type: "string", description: "项目根目录——台账按项目根关联存储于用户数据目录（工作树外、不进 git）。相对路径按当前工作目录解析；查/写别的项目请给绝对路径。缺省 = 当前会话项目根" },
-      status: { type: "string", enum: ["待讨论", "待设计", "在途", "待核销", "已核销", "已废弃"], description: "按状态过滤（六态之一，缺省 = 不过滤）" },
-      kind: { type: "string", enum: ["requirement", "tech_todo"], description: "按类别过滤" },
-      board: { type: "string", description: "按归属板块过滤（需求档文档名）" },
-    },
-    additionalProperties: false,
-  },
-  readonly: true,
-  async execute(args, ctx) {
-    args = assertToolArgs(ledgerQueryTool, args)
-    return JSON.stringify(ledgerQuery({ cwd: args.cwd ?? cwdOf(ctx), status: args.status, kind: args.kind, board: args.board }), null, 2)
-  },
-}
+/** action 枚举（全量 / 只读两变体；顺序 = 文档与按钮序）。 */
+const FULL_ACTIONS = ["add", "update", "close", "query", "count"]
+const READ_ACTIONS = ["query", "count"]
 
-export const ledgerCountTool = {
-  name: "ledger_count",
-  description: DESC("ledger_count"), // #15 外置：文本单点 = tool-docs/ledger_count.md
-  parameters: {
-    type: "object",
-    properties: { cwd: { type: "string", description: "项目根目录——台账按项目根关联存储于用户数据目录（工作树外、不进 git）。相对路径按当前工作目录解析；查/写别的项目请给绝对路径。缺省 = 当前会话项目根" } },
-    additionalProperties: false,
-  },
-  readonly: true,
-  async execute(args, ctx) {
-    args = assertToolArgs(ledgerCountTool, args)
-    return JSON.stringify({ count: ledgerCount({ cwd: args.cwd ?? cwdOf(ctx) }) })
-  },
-}
+/** cwd 参数描述（五前身声明同文——文本单点）。 */
+const CWD_DESC = "项目根目录——台账按项目根关联存储于用户数据目录（工作树外、不进 git）。相对路径按当前工作目录解析；查/写别的项目请给绝对路径。缺省 = 当前会话项目根"
 
-export const ledgerAddTool = {
-  name: "ledger_add",
-  description: DESC("ledger_add"), // #15 外置：文本单点 = tool-docs/ledger_add.md（两池词表逐字保留）
-  parameters: {
+/** 各 action 声明条目（= 前身旧工具 `parameters` 逐字；伪工具对象守卫 + 弃用壳共用单源）。 */
+const ACTION_SPECS = {
+  add: {
     type: "object",
     required: ["kind", "title"],
     properties: {
-      cwd: { type: "string", description: "项目根目录——台账按项目根关联存储于用户数据目录（工作树外、不进 git）。相对路径按当前工作目录解析；查/写别的项目请给绝对路径。缺省 = 当前会话项目根" },
+      cwd: { type: "string", description: CWD_DESC },
       kind: { type: "string", enum: ["requirement", "tech_todo"], description: "类别" },
       title: { type: "string", description: "条目标题" },
       board: { type: "string", description: "归属板块（需求档文档名，可空）" },
@@ -123,23 +96,11 @@ export const ledgerAddTool = {
     },
     additionalProperties: false,
   },
-  readonly: false,
-  async execute(args, ctx) {
-    args = assertToolArgs(ledgerAddTool, args)
-    const { cwd, ...row } = args
-    const id = ledgerAdd({ cwd: cwd ?? cwdOf(ctx), row })
-    return JSON.stringify({ id, status: "待讨论" })
-  },
-}
-
-export const ledgerUpdateTool = {
-  name: "ledger_update",
-  description: DESC("ledger_update"), // #15 外置：文本单点 = tool-docs/ledger_update.md
-  parameters: {
+  update: {
     type: "object",
     required: ["id"],
     properties: {
-      cwd: { type: "string", description: "项目根目录——台账按项目根关联存储于用户数据目录（工作树外、不进 git）。相对路径按当前工作目录解析；查/写别的项目请给绝对路径。缺省 = 当前会话项目根" },
+      cwd: { type: "string", description: CWD_DESC },
       id: { type: "number", description: "条目 id" },
       status: { type: "string", enum: ["待讨论", "待设计", "在途", "待核销", "已核销", "已废弃"], description: "目标状态（六态之一，缺省 = 不变）" },
       title: { type: "string", description: "标题（缺省 = 不变）" },
@@ -152,37 +113,139 @@ export const ledgerUpdateTool = {
     },
     additionalProperties: false,
   },
-  readonly: false,
-  async execute(args, ctx) {
-    args = assertToolArgs(ledgerUpdateTool, args)
-    const { cwd, id, ...patch } = args
-    let executorSessionId
-    if (patch.executor == null) {
-      // 显式 `null` ≡ 略去（§3.1 `null` 口径 · #474——与缺省同分支）；动态 import——零新静态边（K-LX1）；
-      // 工具层供值，核心函数保持参数注入纯函数
-      const { getSessionId } = await import("./session-slots.mjs")
-      executorSessionId = getSessionId()
-    }
-    return JSON.stringify(ledgerUpdate({ cwd: cwd ?? cwdOf(ctx), id, patch, executorSessionId }))
-  },
-}
-
-export const ledgerCloseTool = {
-  name: "ledger_close",
-  description: DESC("ledger_close"), // #15 外置：文本单点 = tool-docs/ledger_close.md
-  parameters: {
+  close: {
     type: "object",
     required: ["id", "status"],
     properties: {
-      cwd: { type: "string", description: "项目根目录——台账按项目根关联存储于用户数据目录（工作树外、不进 git）。相对路径按当前工作目录解析；查/写别的项目请给绝对路径。缺省 = 当前会话项目根" },
+      cwd: { type: "string", description: CWD_DESC },
       id: { type: "number", description: "条目 id" },
       status: { type: "string", enum: ["已核销", "已废弃"], description: "目标态（勾销 / 追认核销 / 撤回）" },
     },
     additionalProperties: false,
   },
-  readonly: false,
-  async execute(args, ctx) {
-    args = assertToolArgs(ledgerCloseTool, args)
-    return JSON.stringify(ledgerClose({ cwd: args.cwd ?? cwdOf(ctx), id: args.id, status: args.status }))
+  query: {
+    type: "object",
+    properties: {
+      cwd: { type: "string", description: CWD_DESC },
+      status: { type: "string", enum: ["待讨论", "待设计", "在途", "待核销", "已核销", "已废弃"], description: "按状态过滤（六态之一，缺省 = 不过滤）" },
+      kind: { type: "string", enum: ["requirement", "tech_todo"], description: "按类别过滤" },
+      board: { type: "string", description: "按归属板块过滤（需求档文档名）" },
+    },
+    additionalProperties: false,
+  },
+  count: {
+    type: "object",
+    properties: { cwd: { type: "string", description: CWD_DESC } },
+    additionalProperties: false,
+  },
+}
+
+/** 并集 schema（§11.2——`action` 枚举 + 五 action 参数并集；per-action 必填由运行时守卫裁）。 */
+const UNION_PARAMETERS = {
+  type: "object",
+  required: ["action"],
+  properties: {
+    action: { type: "string", enum: FULL_ACTIONS, description: "" }, // 变体构造时填描述
+    cwd: { type: "string", description: CWD_DESC },
+    kind: { type: "string", enum: ["requirement", "tech_todo"], description: "类别（add 必填 / query 过滤；缺省 = 不过滤）" },
+    title: { type: "string", description: "条目标题（add 必填；update 可改——空串 / 全空白 ⇒ 拒）" },
+    board: { type: "string", description: "归属板块（需求档文档名；add 可空 / update 缺省 = 不变 / query 过滤）" },
+    req_doc: { type: "string", description: "需求档指针（add 可空 / update 缺省 = 不变）" },
+    task_book: { type: "string", description: "任务书指针（add 可空 / update 缺省 = 不变；在途 / 待核销必填——咬合 CHECK）" },
+    evidence: { type: "string", description: "最小证据行（add 可空 / update 缺省 = 不变；追认核销须非空）" },
+    trigger: { type: "string", enum: ["归批", "条件", "认账不排期"], description: "技术待办触发（add / update 可空）" },
+    id: { type: "number", description: "条目 id（update / close 必填）" },
+    status: { type: "string", enum: ["待讨论", "待设计", "在途", "待核销", "已核销", "已废弃"], description: "状态（close 必填 ∈ {已核销, 已废弃}；update 迁移 / query 过滤——六态之一）" },
+    executor: { type: "string", description: "执行者 sessionId（update 可选——接手改写归属；缺省 = 按状态迁移语义）" },
   },
+  additionalProperties: false,
+}
+
+/** 变体构造（同名单对象、schema 窄化、两形永不同装配——先例 = `subagent` 工具 depth 面变体）：
+ *  全量（depth-0 五 action；`writeFace:true` —— `readonly:false` + 动作级分类钩子，写面保持侧效门，
+ *  query / count 归只读类 = 旧读二 `readonly:true` 同行为：planMode 放行 / 免审批）∥ 只读（depth>0
+ *  二 action；`readonly:true`，写三 schema 级不可达）。形态显式声明（不按 actions 长度推导——增量
+ *  变体不改错标文案）。 */
+function makeLedgerTool(actions, { readonly = false, writeFace = false } = {}) {
+  const entryTool = { name: "ledger", parameters: { type: "object", required: ["action"], properties: { action: { type: "string", enum: actions } } } }
+  return {
+    name: "ledger",
+    description: DESC("ledger"), // 文本单点 = tool-docs/ledger.md（五档要点合一）
+    parameters: {
+      ...UNION_PARAMETERS,
+      properties: {
+        ...UNION_PARAMETERS.properties,
+        action: {
+          ...UNION_PARAMETERS.properties.action,
+          enum: actions,
+          description: writeFace
+            ? "操作（五值）：add 新增 / update 更新 / close 收口 / query 查询 / count 计数——写三仅主 agent 装配面"
+            : "操作（只读二值）：query 查询 / count 计数",
+        },
+      },
+    },
+    readonly,
+    isReadonlyAction(args) { return READ_ACTIONS.includes(args?.action) },
+    async execute(args, ctx) {
+      // ① 入参归一（判序①——P1 同式；缺省 / null ⇒ {}）
+      if (args == null) args = {}
+      else if (typeof args !== "object" || Array.isArray(args)) throw new Error(`ledger：参数须为对象（收到 ${argPreview(args)}）`)
+      // ② 入口级 action 判（P3 缺失 / P5 非法——消费 action；取值域 = 本装配面枚举）
+      const { action, ...rest0 } = args
+      assertToolArgs(entryTool, { action })
+      // ③ 余键喂该 action 伪工具对象（声明源 = 前身工具 parameters 逐字——`action` 键不入 P2 域）
+      const rest = assertToolArgs({ name: `ledger(${action})`, parameters: ACTION_SPECS[action] }, rest0)
+      // ④ 路由既有核函数（包装细节携自原工具 execute 逐字保留：cwd 缺省 / JSON 缩进 / getSessionId 动态 import）
+      switch (action) {
+        case "add": {
+          const { cwd, ...row } = rest
+          const id = ledgerAdd({ cwd: cwd ?? cwdOf(ctx), row })
+          return JSON.stringify({ id, status: "待讨论" })
+        }
+        case "update": {
+          const { cwd, id, ...patch } = rest
+          let executorSessionId
+          if (patch.executor == null) {
+            // 显式 `null` ≡ 略去（§3.1 `null` 口径 · #474——与缺省同分支）；动态 import——零新静态边（K-LX1）
+            const { getSessionId } = await import("./session-slots.mjs")
+            executorSessionId = getSessionId()
+          }
+          return JSON.stringify(ledgerUpdate({ cwd: cwd ?? cwdOf(ctx), id, patch, executorSessionId }))
+        }
+        case "close":
+          return JSON.stringify(ledgerClose({ cwd: rest.cwd ?? cwdOf(ctx), id: rest.id, status: rest.status }))
+        case "query":
+          return JSON.stringify(ledgerQuery({ cwd: rest.cwd ?? cwdOf(ctx), status: rest.status, kind: rest.kind, board: rest.board }), null, 2)
+        case "count":
+          return JSON.stringify({ count: ledgerCount({ cwd: rest.cwd ?? cwdOf(ctx) }) })
+        default:
+          // 不可达（② 枚举守门已先拒）——fail-loud 兜底（防未来变体增量 drift）
+          throw new Error(`ledger：action 非法：${argPreview(action)}（取值 ∈ ${enumText(actions)}）`)
+      }
+    },
+  }
 }
+
+/** 统一入口两变体（同名 `ledger`——depth-0 装配全量 ∥ depth>0 各角色段装配只读）。 */
+export const ledgerTool = makeLedgerTool(FULL_ACTIONS, { writeFace: true })
+export const ledgerReadTool = makeLedgerTool(READ_ACTIONS, { readonly: true })
+
+// ── 旧五名弃用壳（设计档 §11.4——code 面保留、不入任何装配面） ────────────────
+
+/** 弃用文案（含旧名 + 统一入口 + 对应 action 指引；execute 抛它 ⇒ 零库动作）。
+ *  description 同文静态化——不经 `DESC`（旧五档退场后 DESC 加载必炸；壳面规避）。 */
+const deprecatedLine = (old, action) => `${old} 已退役（本名不再装配）——请改用统一入口 ledger：action="${action}"（参数面与原工具相同）。`
+
+const deprecatedShell = (old, action, readonly) => ({
+  name: old,
+  description: deprecatedLine(old, action),
+  parameters: ACTION_SPECS[action],
+  readonly,
+  async execute() { throw new Error(deprecatedLine(old, action)) },
+})
+
+export const ledgerQueryTool = deprecatedShell("ledger_query", "query", true)
+export const ledgerCountTool = deprecatedShell("ledger_count", "count", true)
+export const ledgerAddTool = deprecatedShell("ledger_add", "add", false)
+export const ledgerUpdateTool = deprecatedShell("ledger_update", "update", false)
+export const ledgerCloseTool = deprecatedShell("ledger_close", "close", false)

package/ledger-variant-notice.mjs

@@ -0,0 +1,47 @@
+/**
+ * ledger-variant-notice.mjs — 变体键库首跑检测提示（F-LX3 · 设计档 `docs/core/design/LEDGER.md` §12 ·
+ * 批 `docs/batches/2026-10-05-ledger-variant-db-notice.md` · 台账 #935）。
+ *
+ * 升级到含键归一的版本后，存量变体键库（旧产物写入的盘符翻转拼写键——`legacyKeyVariants`）不再无声搁浅：
+ * CLI 主入口启动时对**当前项目根**检测，命中 ⇒ 单行 i18n 提示（`thincoder ledger audit` 查看 ∥
+ * `thincoder ledger migrate` 收正）；**只提示，零自动动作**（不迁移 / 不删档 / 不建库 / 零写）。
+ * 判据 = 变体键档**文件存在**（KD-VN1——零开库：不触 SQLite / 不建 WAL；坏档 / 空库不漏报）。
+ * 每进程至多一次 = 模块级闩（首唤检测 / 后唤零动作——重置缝 `_resetLedgerVariantNoticeForTest`，
+ * 先例 = `_resetLedgerDirForTest`）。降级 = 全径 try ⇒ 返回 `null`（零抛零阻塞——启动链不受累）。
+ * 本档静态链入 `ledger-migrate.mjs`（node:sqlite）⇒ 消费侧一律动态 import（W8 契约②）。
+ * 检测面零新建哈希式：键式直引 `ledgerKey` ∥ 变体枚举直引 `legacyKeyVariants`（单源不二写）。
+ */
+import { statSync } from "node:fs"
+import { join, resolve } from "node:path"
+
+import { t } from "./i18n.mjs"
+import { ledgerDirPath, ledgerKey } from "./ledger-db.mjs"
+import { legacyKeyVariants } from "./ledger-migrate.mjs"
+import { resolveProjectRoot } from "./manifest.mjs"
+
+/** 默认探针（吞错形——与 `migrate` 源枚举过滤同判据）：`statSync(p).isFile()`，任何 stat 失败 ⇒ false。 */
+const defaultExists = (p) => { try { return statSync(p).isFile() } catch { return false } }
+
+/** 一次为限闩（「每进程」= ESM 模块实例的天然粒度——首唤检测 / 后唤零动作）。 */
+let noticeChecked = false
+
+/** 测试重置缝（同 `_resetLedgerDirForTest` 先例——闩为进程级事实，直测需复位）。 */
+export function _resetLedgerVariantNoticeForTest() { noticeChecked = false }
+
+/**
+ * 检测当前项目根的变体键库：命中 ⇒ 单行提示文案（i18n 键 `ledger.variantDbNotice`——zh ∥ en 单源），
+ * 无 ∥ 已查过 ∥ 任何异常（根解析 / 探针 / 文案解析）⇒ `null`（静默降级——零抛）。
+ * 命中判据 = 变体键（`k !== 主键`）中有档在盘（文件存在——零开库）；主库在否不影响判定。
+ * @param {{cwd?: string, dir?: string, locale?: string, exists?: (p: string) => boolean}} [opts]
+ * @returns {string|null} 单行文案 / null
+ */
+export function ledgerVariantNotice({ cwd = process.cwd(), dir = ledgerDirPath(), locale = "en", exists = defaultExists } = {}) {
+  if (noticeChecked) return null
+  noticeChecked = true
+  try {
+    const root = resolveProjectRoot(cwd) ?? resolve(cwd ?? ".")
+    const targetKey = ledgerKey(root)
+    const hit = legacyKeyVariants(root).filter((k) => k !== targetKey).some((k) => exists(join(dir, `${k}.db`)))
+    return hit ? t("ledger.variantDbNotice", {}, locale) : null
+  } catch { return null }
+}

package/ledger.mjs

@@ -6,7 +6,7 @@
  * 锁死、COUNT 单源计数、事务保证收口原子、归档 = 软删除。行龄源 = SQLite 时间戳（无 git blame）。
  *
  * 面：① 命令族（查询 = 只读全角色 / 写 = 仅主 agent——核函数 `ledger-cmd.mjs` + 工具定义 `ledger-tools.mjs`
- * 两源，接线见 tools/index.mjs 与 agent/family-tools.mjs）
+ * 两源，接线见 `agent/family-tools.mjs`——统一入口 `ledger` 两变体，2026-10-05 统一入口批）
  * ② 族发现（findProject / discoverFamily——标记 = ledger.db）③ scan 组装（buildScan——行集 + ledgerCount
  * → scan 对象，形状契约 = pool/tech/aged/thresholdReached/actionable/root/name/ledger）
  * ④ 格式 helper（L1 标记 ∥ L2 明细行逐字契约——含标记范围归约 `scopeMarkerOf`，§7.2）。
@@ -188,6 +188,6 @@ export function detailScans(scans, current) {
 // ── re-export（拆分件接口——命令面接线 = 动态 import 本档，KD-M2-3） ──
 export { ALLOWED_MIGRATIONS, ledgerDbPath, ledgerKey, ledgerDirPath, openLedger, PENDING_STATUSES, _setLedgerDirForTest, _resetLedgerDirForTest, ensureExecutorColumn } from "./ledger-db.mjs"
 export { ledgerAdd, ledgerClose, ledgerCount, ledgerQuery, ledgerUpdate } from "./ledger-cmd.mjs"
-export { ledgerAddTool, ledgerCloseTool, ledgerCountTool, ledgerQueryTool, ledgerUpdateTool } from "./ledger-tools.mjs"
+export { ledgerTool, ledgerReadTool, ledgerAddTool, ledgerCloseTool, ledgerCountTool, ledgerQueryTool, ledgerUpdateTool } from "./ledger-tools.mjs"
 export { runLedgerAudit, runLedgerMigrate } from "./ledger-migrate.mjs"
 export { resolveExecutorStates, executorTail, _setExecutorProbeTtlForTest } from "./ledger-executors.mjs"

package/manifest-schema.mjs

@@ -12,12 +12,14 @@
 
 /**
  * `docRoot` 子键**值形态判据**（F7 / KD-M1-6 / KD-M1-8——判据单源）：非空字符串（`trim` 后
- * 非空），或非空数组且元素皆非空字符串（**同款口径**：元素 `trim` 后非空）；其余（空串 /
- * 空白串 / 空数组 / 数组含非串 / 空串 / 空白串元素 / 非串非数组）为非法。
+ * 非空），或非空数组且元素皆非空字符串（**同款口径**：元素 `trim` 后非空），或 `null`
+ * （**「本面无」合法哨兵**——KD-M1-37）；其余（空串 / 空白串 / 空数组 / 数组含非串 / 空串 /
+ * 空白串元素 / 非串非数组）为非法。
  * @param {unknown} value docRoot 某子键的值
  * @returns {boolean}
  */
 export function isValidDocRootValue(value) {
+  if (value === null) return true
   if (typeof value === "string") return value.trim() !== ""
   if (!Array.isArray(value) || value.length === 0) return false
   return value.every((p) => typeof p === "string" && p.trim() !== "")
@@ -110,9 +112,9 @@ export function validateManifest(obj) {
     }
     for (const sub of subkeys) {
       if (!(sub in value)) { missingKeys.push(`${nested}.${sub}`); continue } // 子键路径（AC-3 / T3b）
-      // docRoot 子键值形态（F7 / KD-M1-7）：串 | 非空串数组；非法 → 拒（不静默跳过）。
+      // docRoot 子键值形态（F7 / KD-M1-7 / KD-M1-37）：串 | 非空串数组 | null（本面无）；非法 → 拒（不静默跳过）。
       if (nested === "docRoot" && !isValidDocRootValue(value[sub])) {
-        errors.push(`docRoot.${sub} 值形态非法：${JSON.stringify(value[sub])}（须为非空字符串或非空字符串数组——KD-M1-6 / KD-M1-7）`)
+        errors.push(`docRoot.${sub} 值形态非法：${JSON.stringify(value[sub])}（须为非空字符串 / 非空字符串数组 / null（本面无）——KD-M1-6 / KD-M1-7 / KD-M1-37）`)
       }
       // checkConfig.lineCounts 元素层形态（#546）：数组，元素 = { doc, section } 非空串；非法 → 拒（不静默跳过）。
       if (nested === "checkConfig" && sub === "lineCounts" && !isLineCountsValue(value[sub])) {

package/manifest.mjs

@@ -10,7 +10,7 @@
  *    未知键（#802 / KD-M1-36）→ 产 unknownKeys + 一行可见告警（console.warn + logEvent；
  *    同档同键集去重、读到零未知键清该档 memo）——非拒定性零变。
  *  - validateManifest(obj) → { ok, errors, missingKeys, unknownKeys }：枚举 / version 数值 /
- *    docRoot 子键值形态（串 | 数组，F7）+ checkConfig.lineCounts 元素层形态——**纯函数、零 fs**；不落盘。
+ *    docRoot 子键值形态（串 | 数组 | null（本面无——KD-M1-37），F7）+ checkConfig.lineCounts 元素层形态——**纯函数、零 fs**；不落盘。
  *  - 三族声明键（`codePaths` / `index.{codeExtensions,docExtensions,publicRepos}` / `advisor.{docMap,standardsDoc}`——
  *    KD-M1-31 / M1-32）：缺键补默认；形态错 = 档非法（fail-closed，与 docRoot 子键同款）；
  *    读向 = `declaration.mjs`（2026-10-01 自 `conventions.mjs` 迁出——经其转口可达）经 `readManifest` /
@@ -101,13 +101,15 @@ export function docRootBase(cwd) {
  * `docRoot` 子键值 → **绝对路径数组**（F7 / §2.7 解析管线——全在本模块一处）：展开（串 /
  * 数组统一成列表）→ 逐元素 `trim` + `\` 归一 → `resolve(docRootBase(cwd), p)`（基数 =
  * 项目根，不回退原始 cwd）→ 去重（保序）。非法形态 → `[]`（零根——拒面在 `validateManifest`，
- * 本函数不判错；两处共用 `isValidDocRootValue`，判据单源）。
- * @param {unknown} value docRoot 某子键的值（串 | 数组）
+ * 本函数不判错；两处共用 `isValidDocRootValue`，判据单源）。`null`（本面无）⇒ `[]`（**合法
+ * 零根——非错**；#944 / KD-M1-37）。
+ * @param {unknown} value docRoot 某子键的值（串 | 数组 | `null`）
  * @param {string} [cwd] 会话锚（基数由 docRootBase 解析为项目根）
  * @returns {string[]} 绝对路径（去重保序）
  */
 export function docRootPaths(value, cwd) {
   if (!isValidDocRootValue(value)) return []
+  if (value === null) return [] // 「本面无」（#944）：合法零根——非错（不展开、不报错）
   const base = docRootBase(cwd)
   const list = (Array.isArray(value) ? value : [value]).map((p) => resolve(base, p.trim().replace(/\\/g, "/")))
   return [...new Set(list)]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thincoder/core",
-  "version": "0.10.3",
+  "version": "0.10.4",
   "description": "ThinCoder shared core — shared mechanism modules + shared prompt content (CLI ↔ VS Code extension).",
   "keywords": [
     "ai",

package/prompts/common.md

@@ -155,13 +155,13 @@ Batch independent read-only tool calls into a single reply (they run concurrentl
 **What it is**: the project's **todo book** — a **requirement pool** (user requirement points) plus **tech todos** (engineering debt); persists across sessions, and it is the **only todo-tracking surface** (checklist retired).
 **Where it lives**: keyed by **project root**, stored in the **user data directory** (outside the work tree, **never in git**, no file left in the project); an empty read = that project has no ledger yet (the first write creates it).
 **Six states**: 待讨论 → 待设计 → 在途 → 待核销 (the four **unsettled states**); **已核销 / 已废弃 = archive states** (soft delete — settled entries leave the unsettled surface).
-**Who reads / writes**: **reads = every role** (`ledger_query` / `ledger_count`; `cwd` defaults to the session project root — pass an absolute path to touch another project); **writes = the main agent only** (subagent tool assemblies carry no write command).
+**Who reads / writes**: **reads = every role** (`ledger` (action=query/count); `cwd` defaults to the session project root — pass an absolute path to touch another project); **writes = the main agent only** (subagent tool assemblies carry no write command).
 **Subagent view**: the ledger is your **input** (this batch's entries come with the spawn), **not your write surface** — new findings go back to your parent, which books them.
 **A note is not a ledger**: an **unresolved** gap / difference / limitation must not rest in prose, comments or inline notes — fix it, surface it upward, or get it booked, so it lands on a **visible todo surface**; 「登记」-style in-doc registration is valid **only for ruled items** (judgment + reasons + resolution window).
 **Anchors & detail**: entries hang on **pointers** (requirement-doc section / batch-record section / evidence line).
 
 ## 批次档常识（Batch record — the carrier of task flow）
-**What it is**: the **batch record** = the **carrier** of task flow (the single file threading one implementation round from start to closeout); the path takes the form `docs/batches/<batch>-<topic>.md` — the actual location is the `batchDoc` passed at spawn, never hard-coded.
+**What it is**: the **batch record** = the **carrier** of task flow (the single file threading one implementation round from start to closeout); the path takes the form `<repo>/docs/batches/<batch>-<topic>.md` (relative paths resolve against the session cwd first, then candidate project roots — or absolute) — the actual location is the `batchDoc` passed at spawn, never hard-coded.
 **Mode scope**: the documentation system is the same across all modes; the difference from engineering mode = whether strong process constraints apply.
 **Six-segment map (one segment, one author)**: §1 discussion = the main agent · §2 batch task & design = eng-designer · §3 design review findings = the review subagent (advisor) · §4 user approval = the main agent · §5 implementation record = eng-coder · §6 verification & closeout = the main agent (the parent, as seen by subagents).
 **Writing means**: the `batch` tool — **no path parameter** (the target record is bound to you at spawn); **the segment number follows from your identity**; if the write does not land ⇒ say "§× 未写入" plainly in your report.