@thincoder/core 0.10.7 → 0.10.8

package/config-watch.mjs

@@ -1,13 +1,13 @@
 /**
  * config-watch.mjs — config.json 外部写盘感知·**纯逻辑面**（R8 · 桌面功能对位批「上提」KD-T2——
- * 自 `thincoder-vscode/src/extension/config-watch.mjs:35-77` 逐字随迁：去抖 300ms ∕ stat 元组
+ * 自 `thincoder-vscode/src/extension/config-watch.mjs` 的 `startConfigWatch` 逐字随迁：去抖 300ms ∕ stat 元组
  * （`mtimeMs:size`）比对 ∕ 自写抑制；原批 = 第 21 批 B5 · `docs/design/SETTINGS.md` §2.6）。
  *
  * `~/.thincoder/config.json` 为多端共享单文件：CLI（`/advisor`、`settings set`）或手工编辑写盘后，
  * 常开面板原本零感知（只在打开面板/保存时拉快照）。机制（零语义改）：
  *   宿主 fs 事件 →（端落子）`onEvent` → 去抖 → 元组比对 → 变化才 `onChange`（事件驱动零空转）。
  * 自写抑制：本端自身写盘同样改元组 ⇒ 裸推送会在用户编辑中被快照重建；写盘成功后核 `config-io`
- * `saveRaw` 同步回调 `onConfigSelfWrite`（`config-io.mjs:107`）⇒ `noteSelfWrite()` 把基线刷到当前
+ * `saveRaw` 同步回调 `onConfigSelfWrite`（`config-io.mjs`）⇒ `noteSelfWrite()` 把基线刷到当前
  * 元组 ⇒ 事件到达时元组已等于基线 ⇒ 零推送；外部写无回调 ⇒ 元组异于基线 ⇒ 推送。
  *
  * 平台面两注入（核内零宿主绑定）：① `attach`（fs 事件源工厂——端落子：VSC = `createFileSystemWatcher`、

package/config.mjs

@@ -64,6 +64,13 @@ export const DEFAULTS = {
     // §6.30.3 门三件③（D-TW5）：timer 空闲自唤醒开关——默认开（工具描述面已承诺到点提醒）；
     // false ⇒ 端侧不武装闩（回既有回合边界投递——零调度器面）。键面随 DEFAULTS 派生进 settings 类型表。
     timerWake: true,
+    // 注入开关（PROMPT-SYSTEM.md §6.24 · 台账 #1420）：文档类 ∥ 记忆类自动注入——默认开；
+    // 判据 `!== false`（缺省 = 现行为零变）。消费点 = 核 `agent/setup.mjs` 判点（逐 run 现读）。
+    // 2026-10-15（§6.27 · 台账 #1465）：① 项目指令块独立成键——`injectDocs` 收窄为只管 ② 相关文档块；
+    // 两键完全正交（关任一方另一方照常）。`injectProjectRules` 判点 = 核 `agent/setup.mjs`（`prepareRun` 项目指令段）。
+    injectDocs: true,
+    injectProjectRules: true,
+    injectMemories: true,
   },
   memory: {
     dbPath: join(configDir, "memory.db"),

package/declaration.mjs

@@ -7,7 +7,7 @@
  */
 import { existsSync, readdirSync, statSync } from "node:fs"
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path"
-import { DEFAULT_MANIFEST, MANIFEST_REL, docRootPaths, manifestFilePath, owningProject, readManifest } from "./manifest.mjs"
+import { DEFAULT_MANIFEST, MANIFEST_REL, docRootPaths, manifestFilePath, onManifestInit, owningProject, readManifest } from "./manifest.mjs"
 import { isSkippedRelPath } from "./memory/file-walk.mjs" // 面⑦ 子目录扫描的跳过段谓词单源（零环：file-walk 不引本档）
 import { logEvent } from "./log.mjs"
 
@@ -311,6 +311,10 @@ export function clearDeclarationCache() {
   _scopeCache.clear()
 }
 
+// #1376：eng 建档路（`manifest.mjs` `resolveEngineeringManifest` init 支）成功 ⇒ 同清两缓存——
+// 反向注册（本档已向依赖 manifest.mjs，其侧零出边保持——KD-M1-33）；失败路径不广播、文件面零变。
+onManifestInit(clearDeclarationCache)
+
 /** Retired-carrier warning (existence check only — zero content parsing, zero fallback). */
 function warnRetiredCarrier(root) {
   console.warn(`[declaration] ${RETIRED_REL_PATH} is retired and no longer read — move codePaths / index.*Extensions / advisor.{docMap,standardsDoc} into PROJECT-MANIFEST.json`)

package/doc-check/anchors.mjs

@@ -0,0 +1,100 @@
+/**
+ * doc-check/anchors.mjs — 文档纪律机检 · 起步判据 ①（锚）：指针抽取 + 解析序 + 节在盘判定。
+ *
+ * 判据句单源 = `docs/core/design/DOC-DISCIPLINE.md` §3.20 判据 ①（本节只实现，不重述口径）：
+ * · 文档指针 = 档 token（含 `.md`，可带目录段）± 节指示（紧随 `§` + 编号 N / N.M / N.M.K）；
+ *   **行号坐标（`:N`）不作节指示**——行号不作引用；
+ * · 档不在盘 ⇒ `档缺`；带节指示 ∧ 节不在盘 ⇒ `节缺`。
+ *
+ * 抽取面：逐行扫；fenced 块整块跳过；可执行行（`isExecutableLine`）整行跳过（命令保字面）。
+ * 解析序：① 仓根相对 → ② 域根相对（`scanDirs` 逐根）→ ③ 引用方档所在目录相对 →
+ *   ④ 域内唯一 basename 索引；同名 ≥2 ⇒ **不判**（列报告面）。
+ * 节在盘：目标档内存在标题行，其标题编号（标题文本去 `^#{1,6}\s` 后的首个 `\d+(?:\.\d+)*`）= 指针节号。
+ * 残余登记（fail-open 方向——归评审核验面）：裸档名在域内多义 ⇒ 不判；未闭合围栏 ⇒ 至档尾免；
+ *   指针行的坐标尾不入判、同行的档 token 照判。
+ */
+import { readFileSync, statSync } from "node:fs"
+import { basename, dirname, resolve } from "node:path"
+import { fenceMark, isExecutableLine } from "./width.mjs"
+
+/** 文档指针 token：`(目录段/)*名.md` + 可选行号坐标尾 + 可选节指示（`§` + 编号）。
+ *  左界守卫排除更长 token 的尾段；右界排除后续字母数字（`.md` 之后紧邻 `[\w]` ⇒ 非完整 token）。 */
+const ANCHOR_RE = /(?<![A-Za-z0-9_.\-\\/@])((?:[A-Za-z0-9_.\-]+\/)*[A-Za-z0-9_.\-]+\.md)(?::\d+(?:-\d+)?)?(?:\s*§\s*(\d+(?:\.\d+)*))?(?![\w])/g
+
+/** 文件存在性（目录 / 读错 ⇒ false）。 */
+function isFile(p) { try { return statSync(p).isFile() } catch { return false } }
+
+/** 标题编号（标题文本去 `^#{1,6}\s` 后的首个 `\d+(?:\.\d+)*`）；非标题行 ⇒ null。 */
+function headingNumber(line) {
+  const m = /^#{1,6}\s+/.exec(line)
+  if (!m) return null
+  const n = /\d+(?:\.\d+)*/.exec(line.slice(m[0].length))
+  return n ? n[0] : null
+}
+
+/** 节在盘：目标档内任一标题行的编号 = 指针节号（字符串逐字等值——两处同归一形）。 */
+function sectionOnDisk(path, num) {
+  let text = ""
+  try { text = readFileSync(path, "utf8") } catch { return false }
+  for (const l of text.split("\n")) if (headingNumber(l) === num) return true
+  return false
+}
+
+/** 档解析（判据 ① 的解析序 ①–④）：命中 ⇒ `{ ok, path }`；同名 ≥2 ⇒ `{ ambiguous, candidates }`；零命中 ⇒ `{ ok:false }`。
+ *  行号坐标尾（`:N`）不参与档解析——token 只取 `.md` 段（抽取面已剥离坐标尾与节指示）。 */
+function resolveDoc(token, refFile, base, scanDirs, index) {
+  const p1 = resolve(base, token)
+  if (isFile(p1)) return { ok: true, path: p1 } // ① 仓根相对
+  for (const d of scanDirs) { const p = resolve(base, d, token); if (isFile(p)) return { ok: true, path: p } } // ② 域根相对
+  const p3 = resolve(dirname(refFile), token)
+  if (isFile(p3)) return { ok: true, path: p3 } // ③ 引用方档所在目录相对
+  const cands = index.get(basename(token)) ?? [] // ④ 域内唯一 basename 索引
+  if (cands.length === 1) return { ok: true, path: cands[0] }
+  if (cands.length > 1) return { ambiguous: true, candidates: cands }
+  return { ok: false }
+}
+
+/**
+ * 锚判据主行程：域内逐档逐行抽取 + 解析 + 节在盘判定。
+ * @param {string} root 项目根（判据参数已由调用方自 `checkConfig` 读出）
+ * @param {{scanDirs?:string[], files?:string[]}} o `files` = 域内 `.md` 全集（单源 = `scanDomain`）
+ * @returns {{hits:Array, reports:Array}} hits = 命中（`档缺` / `节缺`）；reports = 报告面（多义——不作判）
+ */
+export function checkAnchors(root, { scanDirs = [], files = [] } = {}) {
+  const base = resolve(root)
+  const dirs = Array.isArray(scanDirs) ? scanDirs : []
+  const index = new Map()
+  for (const f of files) {
+    const k = basename(f)
+    if (!index.has(k)) index.set(k, [])
+    index.get(k).push(f)
+  }
+  const hits = []
+  const reports = []
+  for (const f of files) {
+    let text = ""
+    try { text = readFileSync(f, "utf8") } catch { continue }
+    const re = new RegExp(ANCHOR_RE.source, "g") // 每档一份实例（零共享 lastIndex 状态）
+    let fence = null // 围栏标记（` ∥ ~）；null = 不在块内
+    text.split("\n").forEach((l, i) => {
+      const mark = fenceMark(l)
+      if (mark !== null) { // 围栏块整块跳过：起于围栏行、止于同形围栏行（未闭合 ⇒ 至档尾免）
+        if (fence === null) fence = mark
+        else if (mark === fence) fence = null
+        return
+      }
+      if (fence !== null) return
+      if (isExecutableLine(l)) return // 可执行行整行跳过
+      let m
+      while ((m = re.exec(l)) !== null) {
+        const token = m[1]
+        const num = m[2] ?? null
+        const r = resolveDoc(token, f, base, dirs, index)
+        if (r.ambiguous) { reports.push({ file: f, line: i + 1, token, candidates: r.candidates }); continue }
+        if (!r.ok) { hits.push({ file: f, line: i + 1, token, clazz: "档缺" }); continue }
+        if (num !== null && !sectionOnDisk(r.path, num)) hits.push({ file: f, line: i + 1, token, clazz: "节缺", section: num, target: r.path })
+      }
+    })
+  }
+  return { hits, reports }
+}

package/doc-check/index.mjs

@@ -0,0 +1,61 @@
+/**
+ * doc-check/index.mjs — 文档纪律机检 · 引擎入口（域扫描 + 声明面读取 + 报面行）。
+ *
+ * 判据两条（起步 · 闭集——口径单源 = `docs/core/design/DOC-DISCIPLINE.md` §3.20 条目 S）：
+ *   ① 锚（档缺 / 节缺）——实现 = `./anchors.mjs`；② 行宽——口径 = §3.18 条目 Q，实现 = `./width.mjs`。
+ * 判据参数由**被开发项目**的 `PROJECT-MANIFEST.json` `checkConfig` 声明（不硬编码任何本仓路径）。
+ * 纯函数：**零门禁 / 零退出码 / 零阻断**——报告态由工具面 `agent-tools/doc-check.mjs` 呈现；
+ * 输出不得被读作拒执行的理由（用户令 > 机检）。
+ */
+import { relative, resolve } from "node:path"
+import { MANIFEST_REL, readManifest } from "../manifest.mjs"
+import { scanDomain, checkDocWidths } from "./width.mjs"
+import { checkAnchors } from "./anchors.mjs"
+
+/** 相对路径显示形（正斜杠——跨平台同形）。 */
+const rel = (root, p) => relative(root, p).replace(/\\/g, "/")
+
+/**
+ * 跑一次文档纪律机检（报告态）。
+ * @param {string} root 项目根（判据参数取该根的 `PROJECT-MANIFEST.json` `checkConfig`）
+ * @returns {{report:string, hits:{total:number, anchors:number, width:number}, anchorHits:Array,
+ *   widthHits:Array, anchorReports:Array, files:string[], scanDirs:string[], lineWidth:number,
+ *   zones:string[], exclude:string[]}}
+ */
+export function runDocCheck(root) {
+  const base = resolve(root)
+  const read = readManifest(base)
+  if (!read.ok) {
+    throw new Error(`doc_check: cannot read ${MANIFEST_REL} at ${base} — the check parameters come from that project's checkConfig (${read.reason ?? read.errors.join("；")})`)
+  }
+  const cfg = read.manifest.checkConfig ?? {}
+  const scanDirs = (Array.isArray(cfg.scanDirs) ? cfg.scanDirs : []).filter((d) => typeof d === "string" && d !== "")
+  const exclude = Array.isArray(cfg.anchors?.exclude) ? cfg.anchors.exclude : []
+  const lineWidth = cfg.lineWidth
+  const zones = (Array.isArray(cfg.widthExemptZones) ? cfg.widthExemptZones : []).filter((z) => typeof z === "string" && z !== "")
+
+  const files = scanDomain(base, { scanDirs, exclude })
+  const anchors = checkAnchors(base, { scanDirs, files })
+  const widths = checkDocWidths(base, { lineWidth, scanDirs, exclude, exemptZones: zones, files })
+
+  const total = anchors.hits.length + widths.length
+  const out = [
+    "文档纪律机检（报告态 · 非门禁）",
+    `射程：${base} · ${scanDirs.join(" + ") || "（无）"}（${files.length} 档）· 阈值 ${lineWidth} 字符 · 区带豁免：${zones.length ? zones.join(" ∥ ") : "无"} · 排除：${exclude.length ? exclude.join(" ∥ ") : "（无）"}`,
+    "声明：判据参数依据 `PROJECT-MANIFEST.json` `checkConfig`",
+    `命中 ${total} 条（锚 ${anchors.hits.length} · 行宽 ${widths.length}）`,
+  ]
+  // 报告面（不作判）：域内同名 ≥2 ⇒ 多义不判（残余登记——fail-open 方向，归评审核验面）
+  for (const r of anchors.reports) {
+    out.push(`报告 锚·多义 ${rel(base, r.file)}:${r.line} \`${r.token}\`（同名 ${r.candidates.length}：${r.candidates.map((c) => rel(base, c)).join(" ∥ ")}——报告面，不作判）`)
+  }
+  for (const h of anchors.hits) {
+    out.push(h.clazz === "档缺"
+      ? `✗ 锚·档缺 ${rel(base, h.file)}:${h.line} \`${h.token}\``
+      : `✗ 锚·节缺 ${rel(base, h.file)}:${h.line} \`${h.token}\`（目标 ${rel(base, h.target)} 无 §${h.section}）`)
+  }
+  for (const w of widths) out.push(`✗ 行宽 ${rel(base, w.file)}:${w.line}（${w.len} 字符）`)
+  out.push(total ? `结论：${total} 条命中——报告态，不作拒执行的理由` : "结论：0 条命中（锚 ∥ 行宽 均清）")
+
+  return { report: out.join("\n"), hits: { total, anchors: anchors.hits.length, width: widths.length }, anchorHits: anchors.hits, widthHits: widths, anchorReports: anchors.reports, files, scanDirs, lineWidth, zones, exclude }
+}

package/doc-check/width.mjs

@@ -0,0 +1,131 @@
+/**
+ * doc-check/width.mjs — 文档纪律机检的产品档位（行宽谓词族 + 域扫描 + 行宽判据——实现单源）。
+ *
+ * 口径单源 = `docs/core/design/DOC-DISCIPLINE.md` §3.18 条目 Q（度量 / 域 / 豁免类 / 阈值）；
+ * 产品内建裁定 = 同档 §3.20 条目 S——谓词单源随迁：本仓 `scripts/doc-check-width.mjs` 改述为
+ * **再出口缝**（薄档 · 零逻辑 · 逐名再出口），盘上不留第二份谓词实现。
+ * 度量 = `[...line].length`（CJK 计 1——不引显示宽度 / 字体）；阈值 / 域 / 排除全部读
+ * `PROJECT-MANIFEST.json` 的 `checkConfig`——零硬编码本仓路径，换项目开箱可用。
+ * 豁免五类 = 表格行 ∥ fenced 块 ∥ 可执行行 ∥ 连续引文 ∥ 区带：**只认结构谓词**，
+ * 无行级白名单（按行号 / 注释声明的豁免不入判）。
+ * 边界：本档零门禁 / 零退出码 / 零阻断——报告态由 `agent-tools/doc-check.mjs` 呈现。
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs"
+import { join, resolve } from "node:path"
+import { MANIFEST_REL } from "../manifest.mjs"
+
+/** 域发现跳过目录（不视作候选产品域；递归亦不进入）。 */
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", "coverage", ".turbo", ".thincoder"])
+
+/** 域发现（声明面）：cwd 根（持 manifest）+ 各持自身 manifest 的一级子目录——判据 = manifest 在场，无路径硬编码。 */
+export function discoverDomains(root) {
+  const rootAbs = resolve(root)
+  const hasManifest = (p) => { try { return statSync(join(p, MANIFEST_REL)).isFile() } catch { return false } }
+  const out = []
+  if (hasManifest(rootAbs)) out.push(rootAbs)
+  let names = []
+  try { names = readdirSync(rootAbs) } catch { /* 不可读：仅根域 */ }
+  for (const n of names) {
+    if (SKIP_DIRS.has(n) || n.startsWith("dist-")) continue
+    const p = join(rootAbs, n)
+    try { if (statSync(p).isDirectory() && hasManifest(p)) out.push(p) } catch { /* 跳过 */ }
+  }
+  return out
+}
+
+/** 递归列 .md（跳过 SKIP_DIRS ∧ 声明面 exclude 段——exclude 逐层生效）。 */
+function walkMd(dir, exclude, out) {
+  let names = []
+  try { names = readdirSync(dir) } catch { return out }
+  for (const n of names) {
+    if (SKIP_DIRS.has(n) || n.startsWith("dist-") || exclude.includes(n)) continue
+    const p = join(dir, n)
+    let st
+    try { st = statSync(p) } catch { continue }
+    if (st.isDirectory()) walkMd(p, exclude, out)
+    else if (n.endsWith(".md")) out.push(p)
+  }
+  return out
+}
+
+/** 源域（单源）：`scanDirs` × `exclude` 声明面下的全部 .md——锚检查与行宽检查同一文件集。 */
+export function scanDomain(base, { scanDirs = [], exclude = [] } = {}) {
+  const ex = Array.isArray(exclude) ? exclude : []
+  const out = []
+  for (const d of Array.isArray(scanDirs) ? scanDirs : []) walkMd(resolve(base, d), ex, out)
+  return [...new Set(out)].sort()
+}
+
+/** 表格行谓词（markdown 表格行结构性不可折行——行宽豁免，与锚检查同源）。 */
+export const isTableRow = (l) => /^\s*\|.*\|\s*$/.test(String(l))
+
+/** 围栏标记（行首可选空白 + 三反引号 ∥ 三波浪号 ⇒ 标记字符；非围栏行 ⇒ null）——**单源**：
+ *  `isFenceLine` 与两处块扫描（本节行宽 ∥ `./anchors.mjs` 锚抽取）同取此式，使「同形围栏行止」只此一解
+ *  （同一模块内同符两义 = 单源可漂的结构口子）。 */
+export function fenceMark(l) {
+  const m = /^\s*(`{3,}|~{3,})/.exec(String(l))
+  return m ? m[1][0] : null
+}
+
+/** 围栏行谓词（单源 = `fenceMark`）——围栏行自身与块内整行均豁免。 */
+export const isFenceLine = (l) => fenceMark(l) !== null
+
+/** 引文块行谓词（行首可选空白 + `>`）——连续 `>` 行整块豁免（引证须逐字连续、不可折，同表行理据）。 */
+export const isQuoteLine = (l) => /^\s*>/.test(String(l))
+
+/** 区带头谓词（§3.15 谓词面）：标题文本去首部编号（`^\d+(?:\.\d+)*[.、]?\s*`）后——等于区带名 ∨ 以
+ *  「区带名 + （∕(」起（容括注后缀，如 `变更记录（续）`）；闭集外一律不纳（fail-closed）。 */
+export function isZoneHead(headingText, zones = []) {
+  const text = String(headingText).replace(/^\d+(?:\.\d+)*[.、]?\s*/, "")
+  return zones.some((z) => typeof z === "string" && z !== "" && (text === z || text.startsWith(z + "（") || text.startsWith(z + "(")))
+}
+
+/** 行内可执行坐标（命令 / 搜索模式串码段）——整行豁免（证据与命令保字面，与锚判据同源）。 */
+export function isExecutableLine(line) {
+  const l = String(line)
+  if (/`[^`\n]*&&[^`\n]*`/.test(l)) return true // 命令链（cd … && …）
+  if (/`[^`\n]*\b(?:cd|node|npm|npx|grep|rg|git)\s[^`\n]*`/.test(l)) return true // 码段内命令词
+  if (/`[^`\n]*(?:\[\^|\\\.|\(\?<|\(\?:|\{\d)/.test(l)) return true // 码段内搜索模式串片段
+  return false
+}
+
+/** 行内位置是否在反引号码段内（引述面不判）。 */
+export function inCodeSpan(line, idx) {
+  return (String(line).slice(0, idx).match(/`/g) ?? []).length % 2 === 1
+}
+
+/** 行宽判据（单判据 = `checkConfig.lineWidth`）：`[...line].length` > 阈值 ∧ 非表格行 ∧ 非 fenced 块内
+ *  ∧ 非可执行行 ∧ 非连续引文 ∧ 非区带内 ⇔ 命中（口径逐字 = §3.18 条目 Q）。
+ *  单遍扫描携标题栈（`^(#{1,6})\s` 行入栈——同级 ∥ 更高级出栈）：行所属标题链任一为区带头 ⇒ 豁免。
+ *  围栏未闭合 ⇒ 至档尾整块免（fail-open 方向——§3.18 残余登记 ①）；`exemptZones` 缺省 ∥ 空集 ⇒ 零豁免。 */
+export function checkDocWidths(base, { lineWidth, scanDirs, exclude, exemptZones = [], files } = {}) {
+  const zones = (Array.isArray(exemptZones) ? exemptZones : []).filter((z) => typeof z === "string" && z !== "")
+  const hits = []
+  // `files` 给定时直接用（调用方已扫同一域 ⇒ 域只走一遍、文件集由值保证同一）；缺省自扫（既有调用面不变）。
+  for (const f of files ?? scanDomain(base, { scanDirs, exclude })) {
+    let text = ""
+    try { text = readFileSync(f, "utf8") } catch { continue }
+    const stack = [] // 标题栈 —— { level, exempt }；exempt = 自身 ∥ 祖先命中区带
+    let fence = null // 围栏标记（` ∥ ~）；null = 不在块内
+    text.split("\n").forEach((l, i) => {
+      const mark = fenceMark(l)
+      if (mark !== null) {
+        if (fence === null) fence = mark
+        else if (mark === fence) fence = null
+        return // 围栏行自身免
+      }
+      if (fence !== null) return // 块内整块免（未闭合 ⇒ 至档尾免）
+      const hm = /^(#{1,6})\s+(.*)$/.exec(l)
+      if (hm) {
+        while (stack.length && stack[stack.length - 1].level >= hm[1].length) stack.pop()
+        const self = isZoneHead(hm[2].trim(), zones)
+        stack.push({ level: hm[1].length, exempt: self || (stack[stack.length - 1]?.exempt ?? false) })
+        return
+      }
+      const inZone = stack[stack.length - 1]?.exempt === true
+      const len = [...l].length
+      if (len > lineWidth && !isTableRow(l) && !isExecutableLine(l) && !isQuoteLine(l) && !inZone) hits.push({ file: f, line: i + 1, len })
+    })
+  }
+  return hits
+}

package/file-refs.mjs

@@ -3,12 +3,12 @@
  * 上提源 = VSC `thincoder-vscode/src/extension/file-refs.mjs` 自持档（逐字搬——regex ∕ 4000 截断 ∕
  * `[File: …]` 围栏 ∕ 摘要块格式零语义改良）；本档 = **单源**；两端各持薄壳（端侧 `node:fs` 探针注入）：
  * VSC `thincoder-vscode/src/extension/file-refs.mjs` ∥ 桌面 `thincoder-desktop/src/main/file-refs.mjs`。
- * 消费面：VSC 注入 `panel-chat.mjs:187` ∕ 恢复剥离 `panel-session.mjs:185` ∕ 标题剥离
- * `panel-session-write.mjs:139`；桌面注入缝 = `turn-driver.mjs`（起跑前单点，`turn-face.mjs`）∥
- * 恢复剥离 = `session-slots.mjs` `pageHistory` ∥ 标题剥离 = 核 `generate-title.mjs:132`（读源处）。
- * 文本形逐字冻结（`docs/vsc/design/WEBVIEW.md:154`「落线文本逐字不变」契约）：上提不携任何行为面改动。
+ * 消费面：VSC 注入 `panel-chat.mjs` 的 `injectAtRefs` ∕ 恢复剥离 `panel-session.mjs` 的 `stripAtRefs` ∕ 标题剥离
+ * `panel-session-write.mjs` 的 `generateTitle`；桌面注入缝 = `turn-driver.mjs`（起跑前单点，`turn-face.mjs`）∥
+ * 恢复剥离 = `session-slots.mjs` `pageHistory` ∥ 标题剥离 = 核 `generate-title.mjs` 的 `ensureSessionTitle`（读源处）。
+ * 文本形逐字冻结（`docs/vsc/design/WEBVIEW.md` §4.4「落线文本逐字不变」契约）：上提不携任何行为面改动。
  * 判据 = **盘面探针注入缝**（`probe = { readFileSync, existsSync, statSync }` —— `node:fs` 同名面；
- * 缺 ∕ 形违 ⇒ 抛 —— fail-loud：盘面闸未接线不得静默扮成「零引用」，沿 `file-links.mjs:29-31` 先例）。
+ * 缺 ∕ 形违 ⇒ 抛 —— fail-loud：盘面闸未接线不得静默扮成「零引用」，沿 `file-links.mjs` 的 `extractFileLinks` 先例）。
  * `stripAtRefs` = 注入语法的逆变换：fail-closed 判据逐字依赖注入输出格式 —— 语法与其逆变换同住一处，
  * 零第二实现（本档为唯一产者）。
  */
@@ -26,7 +26,7 @@ function probeOf(probe) {
 }
 
 /** Scan text for @path references and replace with inline file content.
- *  零文本（非串 ∥ 空串）先于探针校验早退（零判据——探针不检，同序沿核 `file-links.mjs:28`）。 */
+ *  零文本（非串 ∥ 空串）先于探针校验早退（零判据——探针不检，同序沿核 `file-links.mjs` 的 `extractFileLinks`）。 */
 export function injectAtRefs(text, cwd, probe) {
   if (typeof text !== "string" || text === "") return text
   const io = probeOf(probe)

package/generate-title.mjs

@@ -14,7 +14,7 @@ import { resolveProviderSecrets } from "./env-ref.mjs"
 // （`isRealUserMsg`——纯函数零依赖，无环）。
 import { isRealUserMsg } from "./history-window.mjs"
 // #632（缺面族批补 · @ 文件引用对齐 · 2026-09-29）：标题源剥离单源——注入形不得进标题请求（核件
-// `file-refs.mjs`；CLI 无注入 ⇒ 零动作；VSC 同位转口 = `panel-session-write.mjs:139`）。
+// `file-refs.mjs`；CLI 无注入 ⇒ 零动作；VSC 同位转口 = `panel-session-write.mjs` 的 `generateTitle`）。
 import { stripAtRefs } from "./file-refs.mjs"
 // #363③（off 形族单源——MODEL-SPECS.md §16.2 / §16.4）：禁思考形与「是否可禁」一律引核
 // （`thinkOffShape` / `thinkOffPath`——本档零副本）；spec 查表同单源（`specForModel`）。

package/hooks.mjs

@@ -98,7 +98,7 @@ async function runOneHook(event, hook, ctx) {
     // Timeout guard（#135-④：`timeout` ms 到点杀掉子进程 + 放行——原由 spawn 的 `timeout`
     // 选项承担，见上）。句柄捕获 + `unref()`：进程存活期间守卫照常触发（真 CLI 运行事件循环
     // 另有 handle），但不再单独维持事件循环存活 ⇒ 子进程钩子用例的测试进程零尾挂；
-    // 任一出口经 `done` 收尾 clearTimeout（house 先例 = mcp/transport-stdio.mjs:20）。
+    // 任一出口经 `done` 收尾 clearTimeout（house 先例 = `mcp/transport-stdio.mjs` 的 `killTree`）。
     guard = setTimeout(() => {
       try { proc.kill() } catch { /* already gone */ }
       done(0)

package/i18n.mjs

@@ -7,7 +7,7 @@
  *  - `projectDictionary(locale)` = **VSC 字典投影**：核常量 → VSC `locales/*.json` 的扁平
  *    字典形态（VSC 的 `i18n.mjs` `t()` 壳在 S2 接线时并入本投影，壳内零文案）。
  *
- * 契约（CORE-UNIFICATION §2.12.2 第 12 行 · 输出文案类）：**机器消费面冻结**——本表键值
+ * 契约（CORE-UNIFICATION §2.12.2「输出文案类」）：**机器消费面冻结**——本表键值
  * 与现 VSC `locales/{en,zh}.json` 逐字一致（已锁定串不得改）；人读文案后续变更须登记 +
  * CHANGELOG（S2 落地物）。`${name}` = 插值占位（两端同约定）。
  *
@@ -76,6 +76,16 @@ export const CORE_MESSAGES = Object.freeze({
   "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 收正" },
+  // ── SSH 会话（批 ssh-session · 台账 #1436 · TOOLS.md §6.22 ⑧——凭据窗词面单源；三端经本字典投影）──
+  "ssh.credentialTitle": { en: "SSH credential", zh: "SSH 凭据" },
+  "ssh.credentialPrompt": { en: "Enter the login credential for ${host}", zh: "输入 ${host} 的登录凭据" },
+  "ssh.secretTitle": { en: "SSH secret", zh: "SSH 密文" },
+  "ssh.secretPrompt": { en: "Enter the secret for ${host}", zh: "输入 ${host} 的密文" },
+  "ssh.field.user": { en: "Username", zh: "用户名" },
+  "ssh.field.password": { en: "Password", zh: "密码" },
+  "ssh.field.secret": { en: "Secret", zh: "密文" },
+  // 无 UI 失败句（E6；三端投影单源）：en 侧 = CLI 端 `SECRET_NO_UI_TEXT` 逐字（端常量收正为核键）。
+  "ssh.no_ui": { en: "ssh credential input requires an interactive UI (none in this context) - use key-based auth or ssh-agent", zh: "ssh 凭据输入需要交互界面（当前场合没有）——请改用密钥认证或 ssh-agent" },
 })
 // 深度冻结（机器消费面冻结——嵌套 { en, zh } 也冻结；浅冻结下值可被静默改写）。
 for (const entry of Object.values(CORE_MESSAGES)) Object.freeze(entry)

package/ledger-cmd.mjs

@@ -11,8 +11,7 @@
  * 消费侧静态 import 会破 W8 契约②）。
  */
 import { resolve } from "node:path"
-import { ALLOWED_MIGRATIONS, nowIso, openLedger, PENDING_STATUSES, AGING_DAYS } from "./ledger-db.mjs"
-import { resolveProjectRoot } from "./manifest.mjs"
+import { AGING_DAYS, ALLOWED_MIGRATIONS, nowIso, openLedger, PENDING_STATUSES, resolveLedgerRoot } from "./ledger-db.mjs"
 import { resolveDeclaredRef } from "./declaration.mjs"
 
 /** 逐行老化判真（LEDGER.md §13.4 · 2026-10-07 批 ledger-tool）：未决四态（`PENDING_STATUSES`）∧
@@ -60,8 +59,8 @@ export function ledgerCount({ cwd } = {}) {
  *  （首个 `§` 前子串，trim）须经基准 `resolve(base, …)` 指向存在的档；缺文件部分（`§2` / 空串 /
  *  全空白）⇒ 拒；不在册 / 非文件 ⇒ 拒（throw，行不变）。
  *  判位与迁移表判同层（落盘前）；文案前缀 = 调用函数名（与同函数既有两条文案同款）。
- *  基准 `base` = **与台账库关联键同源**（2026-09-18 fix 轮 · O1 收正）：`resolveProjectRoot(cwd) ??
- *  resolve(cwd ?? ".")`——同表达式见 `ledger-db.mjs` `ledgerDbPath`；容器根会话（锚 cwd 下唯一注册
+ *  基准 `base` = **与台账库关联键同源**（设计档 §6.1 口径 2——根推导单源）：`resolveLedgerRoot(cwd)?.root
+ *  ?? resolve(cwd ?? ".")`——同一子表达式见 `ledger-db.mjs` `ledgerDbPath`；容器根会话（锚 cwd 下唯一注册
  *  子仓 P）与子仓会话 ⇒ 库键与指针基准同取 P（同库同基准；原实现 `resolve(cwd, …)` = 原始 cwd 会误拒）。
  *  #832 ∥ #834：声明源前缀形同判——判定单源 = `declaration.mjs` `resolveDeclaredRef`（① 仓根解析 →
  *  ② 声明源前缀解析序；同名多仓 ⇒ 声明序首者）——**与迁移旗（`ledger-migrate.mjs` `writeGateFlag`）
@@ -71,7 +70,7 @@ function assertTaskBookGate(cwd, fnName, status, taskBook) {
   if (taskBook == null) throw new Error(`${fnName}：task_book 必填（在途 / 待核销 须携任务书指针）`)
   const part = String(taskBook).split("§")[0].trim()
   if (!part) throw new Error(`${fnName}：task_book 不可解析（缺文件部分）：${taskBook}`)
-  const base = resolveProjectRoot(cwd) ?? resolve(cwd ?? ".")
+  const base = resolveLedgerRoot(cwd)?.root ?? resolve(cwd ?? ".")
   const { ok, abs } = resolveDeclaredRef(base, part)
   if (!ok) throw new Error(`${fnName}：task_book 指向的档不存在：${taskBook}（解析 = ${abs}）`)
 }

package/ledger-db.mjs

@@ -6,6 +6,9 @@
  * 靠 DDL（AC-M2-2），不靠应用层 if。归档 = 软删除（状态值，无物理 DELETE——KD-M2-4）。
  * 本档静态 import node:sqlite ⇒ 消费侧一律动态 import 本模块链（W8 契约②——KD-M2-3）。
  *
+ * 项目根推导单源（`resolveLedgerRoot`）+ 同级枚举（`ledgerChildren`）居本档——键 / 库位 / 根同源
+ * （设计档 `LEDGER.md` §2.1「根解析面」/ §3.8）：读写同一判据（档在盘 ∨ 以目录自身路径为键的库在盘）。
+ *
  * 落点（2026-09-17 用户裁定收正）：台账库**不在项目目录**——住用户数据目录
  * `~/.thincoder/ledger/<sha1(normalizeCwd(项目根绝对路径))[:16]>.db`（工作树外、天然不进 git；
  * 同区先例 = configDir 的 memory.db / tool-results）。项目根仅作**关联键**，不在项目内留任何文件。
@@ -13,12 +16,12 @@
  * `normalizeCwd`——与 session / checkpoint / traces / peers 同契约，跨端同 cwd 同键同库。
  */
 import { createHash } from "node:crypto"
-import { existsSync, mkdirSync } from "node:fs"
-import { join, resolve } from "node:path"
+import { existsSync, mkdirSync, opendirSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
 import { DatabaseSync } from "node:sqlite"
 
 import { configDir } from "./config-io.mjs"
-import { projectRootView, resolveProjectRoot } from "./manifest.mjs"
+import { MANIFEST_REL, projectRootView } from "./manifest.mjs"
 // 归一步单源（KD-LN1——直引，不抽新 util：先例 = peer-domains.mjs / traces/trace-store.mjs）。
 import { normalizeCwd } from "./session-slots.mjs"
 
@@ -42,14 +45,89 @@ export function ledgerKey(root) {
   return createHash("sha1").update(normalizeCwd(root)).digest("hex").slice(0, 16)
 }
 
+/** 键控库文件路径（根 → 库位）——**内部形**：根推导内部判「库在盘」时用它，**不得经 `ledgerDbPath`**
+ *  （互指即环，设计档 §3.8「无自指」）。库目录 = `ledgerDir`（`_setLedgerDirForTest` 覆盖 ⇒ 夹具根外零写）。 */
+const keyedDbFile = (root) => join(ledgerDir, `${ledgerKey(root)}.db`)
+
+/** 「已注册」判据（设计档 §2.1——**唯一**事实，两臂取一即成立）：
+ *  档臂 = 该目录带项目声明档 `PROJECT-MANIFEST.json`（档在盘）；
+ *  库臂 = 以该目录自身路径为键的键控库在盘 ∧ 该目录**非工作区态**（键控库存在 ≠ 可作项目）；
+ *  工作区判据只在库在盘时才查（`projectRootView` 含 fs 扫描——档臂已中即短路）。 */
+function isRegistered(dir) {
+  if (existsSync(join(dir, MANIFEST_REL))) return true
+  if (!existsSync(keyedDbFile(dir))) return false
+  return projectRootView(dir).state !== "workspace"
+}
+
+/** 同级枚举上限（成本有界：父目录超此规模 = 缓存 / 临时等非仓族形态 → 退化空集）。
+ *  2026-10-16 批 ledger-root-derivation 自 `ledger.mjs` 随迁（根推导收敛序 ∥ 族发现同级枚举同源）。 */
+export const MAX_SIBLING_SCAN = 100
+
+/** 目录下**已注册**（档 ∨ 库——§2.1 单谓词）的直接子目录（目录名升序；不可读 ∥ 超限 ⇒ 空集；
+ *  **惰性枚举 + 上限**——大目录零全量扫描）。消费面 = 根推导收敛序 ∥ 族发现 ∥ 轻通道闸候选枚举。
+ *  `ledger` = 该子目录根的键控库路径（谓词含档臂 ⇒ 可能尚未在盘）。2026-10-16 批自 `ledger.mjs` 随迁。 */
+export function ledgerChildren(dir) {
+  const out = []
+  let handle
+  try { handle = opendirSync(dir) } catch { return out }
+  try {
+    let n = 0
+    for (;;) {
+      const ent = handle.readSync()
+      if (!ent) break
+      if (++n > MAX_SIBLING_SCAN) return []
+      if (!ent.isDirectory()) continue
+      const root = join(dir, ent.name)
+      if (!isRegistered(root)) continue
+      out.push({ root, ledger: keyedDbFile(root) })
+    }
+  } catch { /* 读中断 → 已得子集（尽力而为） */ }
+  finally { try { handle.closeSync() } catch { /* 已关 */ } }
+  return out.sort((a, b) => (a.root < b.root ? -1 : a.root > b.root ? 1 : 0))
+}
+
+/** 项目根推导**单源**（设计档 §2.1「根解析面」/ §3.8——读写同一判据、同一实现）：
+ *  自 `target`（「动作目标路径」；缺省 = `.`）起沿**祖先链**向上（含自身）取**最近一个「已注册」目录**
+ *  ⇒ `{ root, basis: 'ancestor' }`（自明——回执逐字零改）。
+ *  祖先链无命中 ∧ `descend: true` ⇒ **向下收敛**锚的直接子目录（`ledgerChildren` 同款惰性枚举 +
+ *  上限、名序升序）：恰一 ⇒ 取之；≥2 ⇒ ① 先取**有键控库**者（账已在盘 = 事实）② 该集名序首者 ⇒
+ *  `{ root, basis: 'descendant' }`（向下发现——**须报明**）；零已注册子目录 ⇒ `null`（无根）。
+ *  `descend: false` ⇒ 只问祖先支（族发现 ∥ 标记面——容器 ∥ 工作区锚 ⇒ `null` ⇒ 族求和）。
+ *  **无自指**：内部「库在盘」判据只用 `ledgerKey` + `keyedDbFile`（不经 `ledgerDbPath`）。
+ *  @param {string} [target] 动作目标路径（目录）
+ *  @param {{descend?: boolean}} [opts] `descend` 缺省 `true`（动作面——`openLedger` / `ledgerDbPath` / 单范围读）
+ *  @returns {{root: string, basis: 'ancestor'|'descendant'}|null} 项目根 + 判据来源 / 无根（`null`） */
+export function resolveLedgerRoot(target, { descend = true } = {}) {
+  const start = resolve(target ?? ".")
+  let dir = start
+  for (;;) {
+    if (isRegistered(dir)) return { root: dir, basis: "ancestor" }
+    const parent = dirname(dir)
+    if (parent === dir) break // 盘根 → 祖先链无已注册者
+    dir = parent
+  }
+  if (!descend) return null
+  const children = ledgerChildren(start)
+  if (children.length === 0) return null
+  if (children.length === 1) return { root: children[0].root, basis: "descendant" }
+  const withDb = children.filter((c) => existsSync(c.ledger))
+  return { root: (withDb.length > 0 ? withDb : children)[0].root, basis: "descendant" }
+}
+
+/** 无根文案（单源——设计档 §3.8「无根契约」逐字；`openLedger` 写面 ∥ `ledgerDbPath` 共用同一句）。 */
+const noRootMessage = (start) =>
+  `台账：自 ${start} 未能推导项目根——祖先链与本级子目录均无已注册项目（带 PROJECT-MANIFEST.json 或已有键控台账库）`
+
 /** 项目根 → 库路径（稳定键 = `ledgerKey` 前 16 位——路径唯一标识，不含分隔符）。
- *  项目根与 manifest 同一判据（归属 ∨ 发现——`resolveProjectRoot`；无 manifest ⇒ `resolve(cwd ?? ".")`
- *  兜底且**单值**）——与写门指针基准同一子表达式（键另加 `normalizeCwd` 一步，§2.1）。
+ *  **归单源**（2026-10-16 批 ledger-root-derivation）：根 = `resolveLedgerRoot(cwd)`——与读面 / 写面
+ *  同一推导；无根 ⇒ 抛**同一**无根文案（键需根，不产第二答案）。
  *  v2 键归一（2026-09-25 批）：盘符本大写（CLI）⇒ 键恒等零变；小写盘符（VSC `uri.fsPath`）
  *  并入同键 ⇒ 同项目两端同库（收正前 = 同项目两键两库）。 */
 export function ledgerDbPath(cwd) {
-  const root = resolveProjectRoot(cwd) ?? resolve(cwd ?? ".")
-  return join(ledgerDir, `${ledgerKey(root)}.db`)
+  const start = resolve(cwd ?? ".")
+  const derived = resolveLedgerRoot(start)
+  if (!derived) throw new Error(noRootMessage(start))
+  return keyedDbFile(derived.root)
 }
 
 /** 未决四态（「活条目」口径 = 计数单源 WHERE 集；已核销 / 已废弃 = 归档态）。 */
@@ -135,25 +213,26 @@ function markSchemaVersion(db) {
   if (v < LEDGER_SCHEMA_VERSION) db.exec(`PRAGMA user_version = ${LEDGER_SCHEMA_VERSION}`)
 }
 
-/** 开库（cwd = 项目根——仅作关联键）→ DatabaseSync 句柄 + 幂等建表 + 老库幂等迁移（executor 列）。
- *  读面（create=false）：库文件不存在 → 返回 null（空账——读面不建库、无副作用）。
- *  写面（create=true）：库文件不存在自动建（台账目录随之创建）；项目根目录不存在 → 抛友好错误。
+/** 开库（cwd = 「动作目标路径」）→ DatabaseSync 句柄 + 幂等建表 + 老库幂等迁移（executor 列）。
+ *  **根推导**（设计档 §2.1 / §3.8）：项目根 = `resolveLedgerRoot(cwd)`——读写同一判据；嵌套取近者、
+ *  容器锚向下收敛。**无根（`null`）**：写面（`create:true`）抛（fail-loud、零落盘零建库）；读面空账
+ *  （`null`——与「库不在 = 空账」同形）。
+ *  读面（create=false）：库文件不存在 → 返回 null（读面不建库、无副作用）。
+ *  写面（create=true）：库文件不存在自动建（台账目录随之创建）。
  *  **只读态**（readOnly=true——读面专用）：只读句柄 + 零 DDL / ALTER + items 探针（见 openReadOnly）；
  *  如实副作用：旧库（缺 executor 列）**读**不再自动补列——补列归写面开库；读出行缺列按 null 归一。
- *  **歧义锚**（≥2 候选——`projectRootView` `ambiguous` 态）⇒ **显式拒**（列候选 + 显式项目根指引；
- *  零写——不静默回退锚；族锚「项目不可解析」，AC-M2-17）；兜底 `resolve(cwd ?? ".")` 只属 none 态。 */
+ *  「目录不存在」的真错照抛（fail-loud——先于推导，文案逐字零改）。 */
 export function openLedger(cwd, { create = false, readOnly = false } = {}) {
-  const dir = resolve(cwd ?? ".")
-  // 歧义锚 ⇒ 显式拒（零写——消「缺省空读 / 错写落锚」双面症；读 / 写五工具同经本门）。
-  const view = projectRootView(dir)
-  if (view.state === "ambiguous") {
-    const list = view.candidates.map((c) => `- ${c}`).join("\n")
-    throw new Error(`项目不可解析：cwd ${dir} 下候选项目不是恰好一个（下列 ${view.candidates.length} 个）——台账按项目根键控，请显式给出项目根 cwd：\n${list}`)
+  const start = resolve(cwd ?? ".")
+  if (!existsSync(start)) {
+    throw new Error(`项目目录不存在：${start}——cwd 请给存在的项目根（相对路径按当前工作目录解析；缺省 = 会话项目根）`)
   }
-  const file = ledgerDbPath(dir)
-  if (!existsSync(dir)) {
-    throw new Error(`项目目录不存在：${dir}——cwd 请给存在的项目根（相对路径按当前工作目录解析；缺省 = 会话项目根）`)
+  const derived = resolveLedgerRoot(start)
+  if (!derived) {
+    if (create) throw new Error(noRootMessage(start)) // 写面抛——零落盘零建库
+    return null // 读面空账（未注册目录下旧行为亦为空 ⇒ 零回归）
   }
+  const file = keyedDbFile(derived.root)
   if (!existsSync(file) && !create) return null
   if (readOnly) return openReadOnly(file)
   try { mkdirSync(ledgerDir, { recursive: true }) } catch { /* 已存在 / 并发建目录竞争——忽略 */ }