@thincoder/core 0.9.1 → 0.9.3

package/ledger-surface.mjs

@@ -12,12 +12,13 @@
  * 常驻标记，渲染端消费；**不受启动行门约束**——F2 按标记态照显）。
  * 只读台账；唯一写面 = 去重档（`~/.thincoder/ledger-notify.json`）。
  */
-import { buildScan, detailScans, discoverFamily, formatDetailLine, formatMarker, loadNotifyState, NOTIFY_FILE, notifyKey, planChangeLines, REFRESH_MS, saveNotifyState } from "./ledger.mjs"
+import { buildScan, detailScans, discoverFamily, formatDetailLine, formatMarker, loadNotifyState, NOTIFY_FILE, notifyKey, planChangeLines, REFRESH_MS, resolveExecutorStates, saveNotifyState } from "./ledger.mjs"
 
-/** 单次扫描（直驱面——timer 包装见 `startLedgerSurface`）。
+/** 单次扫描（直驱面——timer 包装见 `startLedgerSurface`）。**async**（F-LX1：await 判活解析——
+ *  LEDGER.md §7.3.1 ④ 读面不阻塞事件循环）。
  *  `startup=true` = 会话首扫（补启动行；变化行在前、明细行在后）。
  *  `colors` = 端注入的渲染色表（`{ warn, dim }`）；未注入 ⇒ `{}`（`undefined` 色值 = 纯文本）。 */
-export function runLedgerScan({ state, agent = null, anchor = null, notifyFile = NOTIFY_FILE, pushLine = () => {}, render = () => {}, startup = false, colors = {} } = {}) {
+export async function runLedgerScan({ state, agent = null, anchor = null, notifyFile = NOTIFY_FILE, pushLine = () => {}, render = () => {}, startup = false, colors = {} } = {}) {
   const base = anchor ?? agent?.cwd ?? process.cwd()
   const family = discoverFamily(base)
   const scans = []
@@ -25,6 +26,7 @@ export function runLedgerScan({ state, agent = null, anchor = null, notifyFile =
     try { scans.push(buildScan({ cwd: p.root })) } catch { /* 台账不可读 → 该项目跳过（余者照常——N1/T110①） */ }
   }
   const current = family.current ? scans.find((s) => s.root === family.current.root) ?? null : null
+  await resolveExecutorStates(scans) // 判活批量解析（一次探束 + TTL 缓存；无在途零 exec）
   const notify = loadNotifyState(notifyFile)
   const plans = scans.map((s) => ({ s, plan: planChangeLines(notify.ledgers[notifyKey(s.ledger)], s) }))
   const changeLines = plans.flatMap(({ plan }) => plan.lines)
@@ -46,19 +48,24 @@ export function runLedgerScan({ state, agent = null, anchor = null, notifyFile =
     for (const { s, plan } of plans) ledgers[notifyKey(s.ledger)] = { ...plan.next, updatedAt: Date.now() }
     saveNotifyState(notifyFile, { version: 1, ledgers })
   }
-  state.ledger = { marker: current ? formatMarker(current) : null, warn: Boolean(current && current.aged > 0), scannedAt: Date.now() }
+  // warn 判位钉在判活解析之后（裁定 #7）：属主已死也是可动作态
+  state.ledger = { marker: current ? formatMarker(current) : null, warn: Boolean(current && (current.aged > 0 || current.deadExecutors > 0)), scannedAt: Date.now() }
   render()
 }
 
 /** 挂载：首扫（`setImmediate`——不抢首帧）+ 周期（`REFRESH_MS`；`state.processing` 期间跳过本轮）。
- *  端注入的渲染面（`ctx.colors`）与推送面（`ctx.pushLine` / `ctx.render`）照传。 */
+ *  端注入的渲染面（`ctx.colors`）与推送面（`ctx.pushLine` / `ctx.render`）照传。
+ *  `tick` 异步化（F-LX1——runLedgerScan async）：await 且 catch 不崩（N1）。重叠防衛：
+ *  判活探测秒级可达，上一轮未落定时跳过本轮（防探束堆积）。 */
 export function startLedgerSurface(ctx = {}) {
   let disposed = false
   let timer = null
-  const tick = (startup) => {
-    if (disposed) return
+  let inflight = false
+  const tick = async (startup) => {
+    if (disposed || inflight) return
     if (!startup && ctx.state?.processing) return // 扫描不打断回合帧
-    try { runLedgerScan({ ...ctx, startup }) } catch { /* 可见面尽力——不崩（N1） */ }
+    inflight = true
+    try { await runLedgerScan({ ...ctx, startup }) } catch { /* 可见面尽力——不崩（N1） */ } finally { inflight = false }
   }
   setImmediate(() => {
     if (disposed) return

package/ledger.mjs

@@ -9,6 +9,8 @@
  * ② 族发现（findProject / discoverFamily——标记 = ledger.db）③ scan 组装（buildScan——行集 + ledgerCount
  * → scan 对象，形状契约 = pool/tech/aged/thresholdReached/actionable/root/name/ledger）
  * ④ 通知去重（送达门 + 一次性去重——去重档跨会话、跨端共享）⑤ 格式 helper（行文本逐字契约）。
+ * 判活展示 = 拆分件 `ledger-executors.mjs`（在途 executor 解析 + 三态尾段——本档 re-export，
+ * 消费面仍只认本档）。
  *
  * W8 契约②：ledger-db.mjs 静态 import node:sqlite ⇒ 消费侧一律**动态 import** 本档（禁止静态 import）。
  */
@@ -17,6 +19,7 @@ import { basename, dirname, join, resolve } from "node:path"
 import { configDir } from "./config.mjs"
 import { ledgerDbPath, PENDING_STATUSES } from "./ledger-db.mjs"
 import { ledgerQuery } from "./ledger-cmd.mjs"
+import { executorTail } from "./ledger-executors.mjs"
 
 /** 老化阈值（天——口径 = 需求档；`days` 参数可覆盖）。 */
 export const AGING_DAYS = 30
@@ -105,7 +108,9 @@ export function discoverFamily(anchor) {
 /** scan 组装（SQLite 行集 + 计数单源 → scan 对象）——形状契约（设计档 §2.2）：pool/tech/aged/
  *  agedKeys/agedTitles/thresholdReached/boards/actionable/root/name/ledger。行龄 = 时间戳
  *  （updated_at ?? created_at 距今 > days；未知不计——零假阳降级，同 v1 行龄未知口径）。
- *  `now`/`days` = 注入面（确定性用例——替代 v1 ageOf git 注入面）。 */
+ *  `now`/`days` = 注入面（确定性用例——替代 v1 ageOf git 注入面）。
+ *  `inflightExecutors`（F-LX1 · sync 零变——K-LX2）：在途且 executor 非空行集原样携带
+ *  {executor, updated_at, created_at}——判活解析由 `resolveExecutorStates` async 单源负责，本函数零探测。 */
 export function buildScan({ cwd, days = AGING_DAYS, now = Date.now() } = {}) {
   const rows = ledgerQuery({ cwd })
   const pending = rows.filter((r) => PENDING_STATUSES.includes(r.status))
@@ -123,11 +128,15 @@ export function buildScan({ cwd, days = AGING_DAYS, now = Date.now() } = {}) {
   }
   const thresholdReached = poolEntries.length >= THRESHOLD_POOL || [...boards.values()].some((n) => n >= THRESHOLD_BOARD)
   const root = resolve(cwd)
+  const inflightExecutors = pending
+    .filter((r) => r.status === "在途" && r.executor)
+    .map((r) => ({ executor: r.executor, updated_at: r.updated_at ?? null, created_at: r.created_at ?? null }))
   return {
     name: basename(root), root, ledger: ledgerDbPath(root),
     pool: poolEntries.length, tech: techEntries.length, aged: aged.length,
     agedKeys: aged.map((r) => normalizeEntry(r.title)), agedTitles: aged.map((r) => entryTitle(r.title)),
     thresholdReached, boards, actionable: aged.length > 0 || thresholdReached,
+    inflightExecutors,
   }
 }
 
@@ -136,9 +145,10 @@ export function formatMarker(scan) {
   return scan ? `台账 ${scan.pool}·${scan.tech}` : null
 }
 
-/** L2 明细行（逐字——`（老化 <n>）` 恒显；阈值达成加 ` — 可开批`）。 */
+/** L2 明细行（逐字——`（老化 <n>）` 恒显；阈值达成加 ` — 可开批`；判活尾段 = executorTail 三态——
+ *  在途 executor 缺席时尾段空串，既有逐字断言零破）。 */
 export function formatDetailLine(scan) {
-  return `台账 ${scan.name}：需求池 ${scan.pool} · 技术待办 ${scan.tech}（老化 ${scan.aged}）${scan.thresholdReached ? " — 可开批" : ""}`
+  return `台账 ${scan.name}：需求池 ${scan.pool} · 技术待办 ${scan.tech}（老化 ${scan.aged}）${scan.thresholdReached ? " — 可开批" : ""}${executorTail(scan)}`
 }
 
 /** L3 变化行·老化（titles = 新增老化条目标题；> 3 条时第三项后接 `；…`）。 */
@@ -198,5 +208,6 @@ export function saveNotifyState(file, state) {
 }
 
 // ── re-export（拆分件接口——命令面接线 = 动态 import 本档，KD-M2-3） ──
-export { ALLOWED_MIGRATIONS, ledgerDbPath, openLedger, PENDING_STATUSES, _setLedgerDirForTest, _resetLedgerDirForTest } from "./ledger-db.mjs"
+export { ALLOWED_MIGRATIONS, ledgerDbPath, openLedger, PENDING_STATUSES, _setLedgerDirForTest, _resetLedgerDirForTest, ensureExecutorColumn } from "./ledger-db.mjs"
 export { ledgerAdd, ledgerAddTool, ledgerClose, ledgerCloseTool, ledgerCount, ledgerCountTool, ledgerQuery, ledgerQueryTool, ledgerUpdate, ledgerUpdateTool } from "./ledger-cmd.mjs"
+export { resolveExecutorStates, executorTail, _setExecutorProbeTtlForTest } from "./ledger-executors.mjs"

package/manifest.mjs

@@ -12,10 +12,16 @@
  *  - isValidDocRootValue(value) / docRootPaths(value, cwd)（F7 判据单源 KD-M1-8）：值形态谓词
  *    + 值 → 绝对路径数组（展开 / trim + `\` 归一 / 基数 = 项目根 / 去重保序）。
  *  - requireManifest(cwd) → 装配钩子入口 = readManifest(cwd)。
- *  - discoverRepos(cwd) → { kind: self|unique|none|ambiguous, root, candidates }：仓发现**单源**
- *    （KD-M1-22——manifest 面与 `git` 工具共用；`candidates` 按名排序）；`resolveProjectRoot` = 其薄包装。
+ *  - discoverProjects(cwd) → { kind, root, candidates, matched }：**项目梯**（五级 / git 非前提——KD-M1-23）；
+ *    `discoverRepos(cwd)` 同形态 = **仓梯**（`.git` 视图——`git` 工具经它接线，KD-M1-22）。
+ *    两梯共一模块私有 walk 内核 `scanChildren`（单源）；`candidates` 按名排序、`matched` 记档位。
+ *  - owningProject(target) → 归属形单点（沿祖先链取**最近带档目录**——KD-M1-30）。
+ *  - projectView(target) → { state, root, path, manifest?, candidates?, errors?, matched }：**按用点解析**
+ *    的读侧单点（归属 ∨ 发现兜底 / 五态 / 非抛错 / **零写**——KD-M1-24）。
+ *  - resolveProjectRoot(cwd) = owningProject(cwd) ?? discoverProjects(cwd).root（KD-M1-30）。
  *  - resolveEngineeringManifest(cwd, { writer, init }) → 入口决策树（**非抛错**——KD-M1-20）：
- *    两端入口钩子（抛错薄包装）与翻转面（拒翻）共用同一张树（判据单源；§2.8 F1）。
+ *    两端入口钩子与翻转面（拒翻）共用同一张树（判据单源；§2.8 F1）——失败码五枚
+ *    `missing` / `invalid` / `no-project` / `ambiguous` / `init-failed`（KD-M1-28）。
  *  - manifestFilePath(cwd) → 数据档绝对路径（档路径单源 KD-M1-18——读 / 写 / mtime 门控三处同源）。
  *  - initManifest(cwd, { writer = 'subagent' } = {}) → 经写门写 DEFAULT_MANIFEST，缺省拒。
  *  - writeManifest(cwd, manifest, { writer = 'subagent' } = {}) → 落盘前先校验（ok:false 拒
@@ -25,54 +31,151 @@
  * N3 可迁移：本模块不硬编码任何本仓路径（docRoot / checkConfig 由被开发项目声明）。
  */
 import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs"
-import { join, resolve } from "node:path"
+import { dirname, join, resolve } from "node:path"
 
-/** 数据档文件名（每个 git 仓一份——项目根 = 仓根；2026-09-17 用户裁定）。 */
+/** 数据档文件名（**每个项目一份**——项目根 = 带档目录；**git 非前提**。2026-09-17 / 2026-09-21 用户裁定）。 */
 export const MANIFEST_REL = "PROJECT-MANIFEST.json"
-
 /** 测试注入：强制项目根（测试 tmp 非 git 仓——同 ledger `_setLedgerDirForTest` 先例）。 */
 let _projectRootOverride = null
 export function _setProjectRootForTest(dir) { _projectRootOverride = dir }
 export function _resetProjectRootForTest() { _projectRootOverride = null }
 
 /**
- * 仓发现（**单源**——KD-M1-22 / 设计 `docs/core/design/MANIFEST.md` §2.2 · `docs/core/design/TOOLS.md` §6.13；
- * 2026-09-17 用户裁定 + #62 批）：判据 = git 目录（`.git`）+ 数据档存在性——
- * ① `_projectRootOverride` 在场 ⇒ `self` + 覆盖值（测试注入面，短路先于真判据）；
- * ② 锚（cwd 的 `resolve`）自身含 `.git` ⇒ `self`（锚即仓根）；
- * ③ 否则**向下看锚的直接子目录一层**（不递归、不向上）：含 `.git` **∧** 含 `MANIFEST_REL`（只判存在性、
- *    不解析档内容）——恰一 ⇒ `unique`；零 ⇒ `none`；≥2 ⇒ `ambiguous`（全列候选，不猜）。
- * `candidates` 一律**按名排序**（歧义消息确定可判）——`self` / `none` ⇒ `[]`。
- * 纯 fs（不读档内容 / 不查模式 / 不依赖 agent）· **不抛**（锚不可读 ⇒ `none`）· 不缓存。
- * @param {string} [cwd] 会话锚（缺省 → 进程 cwd）
- * @returns {{kind:'self'|'unique'|'none'|'ambiguous', root:string|null, candidates:string[]}}
+ * 一层扫描内核（**模块私有**——两条梯表共用；KD-M1-23 / 设计 §2.2「单源结构」）：枚举锚的
+ * **直接子目录**一层（不递归）+ 按名排序 + 谓词过滤 ⇒ 命中表（绝对路径）。
+ * 全档唯一 `readdirSync` 落点（结构机判 T54）；锚不可读 ⇒ `[]`（不抛——调用方按「零命中」处置）。
+ * @param {string} anchor 锚绝对路径
+ * @param {(dir:string)=>boolean} isHit 子目录谓词
+ * @returns {string[]} 命中子目录绝对路径（按名排序）
  */
-export function discoverRepos(cwd) {
-  if (_projectRootOverride) return { kind: "self", root: resolve(_projectRootOverride), candidates: [] }
-  const anchor = resolve(cwd ?? ".")
-  if (existsSync(join(anchor, ".git"))) return { kind: "self", root: anchor, candidates: [] }
-  let found = []
+function scanChildren(anchor, isHit) {
   try {
-    found = readdirSync(anchor, { withFileTypes: true })
+    return readdirSync(anchor, { withFileTypes: true })
       .filter((e) => e.isDirectory())
       .map((e) => e.name)
       .sort()
       .map((e) => join(anchor, e))
-      .filter((d) => existsSync(join(d, ".git")) && existsSync(join(d, MANIFEST_REL)))
-  } catch { /* 不可读 → 空（none） */ }
-  if (found.length === 1) return { kind: "unique", root: found[0], candidates: [...found] }
-  if (found.length === 0) return { kind: "none", root: null, candidates: [] }
-  return { kind: "ambiguous", root: null, candidates: found }
+      .filter(isHit)
+  } catch { return [] }
+}
+
+/**
+ * **项目发现**（项目梯五级——KD-M1-23 / 设计 `docs/core/design/MANIFEST.md` §2.2；**git 非前提**，
+ * 2026-09-21 用户裁定）：① 锚自身带 `MANIFEST_REL` ⇒ 锚；② 锚含 `.git` ⇒ 锚（缺档 = 建档机会）；
+ * ③ 直接子目录中**带档**者优先（非空即只看此级：恰一 ⇒ `unique` / ≥2 ⇒ `ambiguous`）；
+ * ④ 零带档才看含 `.git` 的**裸仓**（同判）；⑤ 均无 ⇒ `none`（⇒ 建档流，落点 = 会话锚）。
+ * `candidates` 一律**按名排序**（`self` / `none` ⇒ `[]`）；`matched` ∈ `manifest` / `git` / `null`
+ * 记命中（或歧义）出自哪一级。**纯 fs**（只判存在性——不解析档内容）· **不抛** · **不向上** · **不递归**。
+ * **覆盖位**（`_setProjectRootForTest` 在场）⇒ **头部短路**（测试注入面——先于真判据，同 `discoverRepos`）。
+ * @param {string} [cwd] 会话锚（缺省 → 进程 cwd）
+ * @returns {{kind:'self'|'unique'|'none'|'ambiguous', root:string|null, candidates:string[], matched:'manifest'|'git'|null}}
+ */
+export function discoverProjects(cwd) {
+  if (_projectRootOverride) return { kind: "self", root: resolve(_projectRootOverride), candidates: [], matched: null }
+  const anchor = resolve(cwd ?? ".")
+  if (existsSync(join(anchor, MANIFEST_REL))) return { kind: "self", root: anchor, candidates: [], matched: "manifest" }
+  if (existsSync(join(anchor, ".git"))) return { kind: "self", root: anchor, candidates: [], matched: "git" }
+  const withManifest = scanChildren(anchor, (d) => existsSync(join(d, MANIFEST_REL)))
+  if (withManifest.length > 1) return { kind: "ambiguous", root: null, candidates: withManifest, matched: "manifest" }
+  if (withManifest.length === 1) return { kind: "unique", root: withManifest[0], candidates: [...withManifest], matched: "manifest" }
+  const bareRepos = scanChildren(anchor, (d) => existsSync(join(d, ".git")))
+  if (bareRepos.length > 1) return { kind: "ambiguous", root: null, candidates: bareRepos, matched: "git" }
+  if (bareRepos.length === 1) return { kind: "unique", root: bareRepos[0], candidates: [...bareRepos], matched: "git" }
+  return { kind: "none", root: null, candidates: [], matched: null }
 }
 
 /**
- * 项目根解析（2026-09-17 用户裁定，**最终定案：纯向下，绝不向上**）——`discoverRepos(cwd).root` 的
- * **薄包装**（零语义——KD-M1-22：`self` / `unique` ⇒ 路径，`none` / `ambiguous` ⇒ `null`，与批前逐字同）。
- * 判据本体 = 上（单源）；调用方（`manifestFilePath` / `docRootBase` / `ledger-db.mjs`）零改。
+ * **仓发现**（仓梯——KD-M1-23 / `docs/core/design/TOOLS.md` §6.13；**单源** KD-M1-22——`git` 工具
+ * 经此符号接线，禁第二份实现）：① 锚含 `.git` ⇒ 锚；② 直接子目录中 `.git` **∧** 带档者恰一 ⇒ 命中
+ * （≥2 ⇒ 歧义）；③ **零个此类时才看**含 `.git` 的裸仓（恰一 ⇒ 命中 / ≥2 ⇒ 歧义）；④ 均无 ⇒ `none`。
+ * 与 `discoverProjects` = **同一 walk 内核**（`scanChildren`）的两种梯表——差异只在谓词与级序。
+ * `candidates` 按名排序；`matched` 记档位；纯 fs / 不抛 / 不递归 / 不向上；覆盖位 ⇒ 头部短路。
+ * @param {string} [cwd] 会话锚（缺省 → 进程 cwd）
+ * @returns {{kind:'self'|'unique'|'none'|'ambiguous', root:string|null, candidates:string[], matched:'manifest'|'git'|null}}
+ */
+export function discoverRepos(cwd) {
+  if (_projectRootOverride) return { kind: "self", root: resolve(_projectRootOverride), candidates: [], matched: null }
+  const anchor = resolve(cwd ?? ".")
+  if (existsSync(join(anchor, ".git"))) return { kind: "self", root: anchor, candidates: [], matched: "git" }
+  const scoped = scanChildren(anchor, (d) => existsSync(join(d, ".git")) && existsSync(join(d, MANIFEST_REL)))
+  if (scoped.length > 1) return { kind: "ambiguous", root: null, candidates: scoped, matched: "manifest" }
+  if (scoped.length === 1) return { kind: "unique", root: scoped[0], candidates: [...scoped], matched: "manifest" }
+  const bare = scanChildren(anchor, (d) => existsSync(join(d, ".git")))
+  if (bare.length > 1) return { kind: "ambiguous", root: null, candidates: bare, matched: "git" }
+  if (bare.length === 1) return { kind: "unique", root: bare[0], candidates: [...bare], matched: "git" }
+  return { kind: "none", root: null, candidates: [], matched: null }
+}
+
+/**
+ * **归属形单点**（KD-M1-30 / 设计 §2.9 A——2026-09-21 用户裁定「最近者优先」）：自 `target`
+ * （目录含自身；文件路径自其父目录起）沿**祖先链**逐级上溯至盘根，取**最近**带 `MANIFEST_REL`
+ * 的目录；无 ⇒ `null`（⇒ 调用方走发现兜底）。**嵌套合法**：子内归子、根其余归根。
+ * **纯 fs**（只判存在性——不解析档内容 / 不问模式）· **不跨兄弟** · **无全局优先级**。
+ * **覆盖位**（`_setProjectRootForTest` 在场）⇒ **头部短路**：直接返回覆盖值（不查档存在性——
+ * 保「覆盖即覆盖值」语义，回归守卫 = `test/manifest.test.mjs` T42 覆盖断言）。
+ * @param {string} [target] 目标路径（目录 / 文件）
+ * @returns {string|null} 最近带档祖先目录绝对路径 / null
+ */
+export function owningProject(target) {
+  if (_projectRootOverride) return resolve(_projectRootOverride)
+  let dir = resolve(target ?? ".")
+  for (;;) {
+    if (existsSync(join(dir, MANIFEST_REL))) return dir
+    const parent = dirname(dir)
+    if (parent === dir) return null // 盘根 → 祖先链无档
+    dir = parent
+  }
+}
+
+/**
+ * 项目根解析（**归属 ∨ 发现**——KD-M1-30 / M1-24）：`owningProject(cwd) ?? discoverProjects(cwd).root`。
+ * 带档路径与批前**逐字同**；变更面两条（设计 §2.2）：① 项目树内路径（祖先带档）⇒ **该项目根**
+ * （批前回落 `resolve(cwd)`——错层建档面，本批修）；② 裸仓恰一 ⇒ 该仓根（零档降级 = 建档机会）。
+ * `none` / `ambiguous` ⇒ `null`。调用方（`manifestFilePath` / `docRootBase` / `ledger-db.mjs` /
+ * `ledger-cmd.mjs`）**零改**（行为随语义变更——设计 §2.5 键面条 / 错层条）。
  * @returns {string|null} 项目根绝对路径 / null
  */
 export function resolveProjectRoot(cwd) {
-  return discoverRepos(cwd).root
+  return owningProject(cwd) ?? discoverProjects(cwd).root
+}
+
+/**
+ * **按用点解析**的读侧单点（KD-M1-24 / M1-30——**非抛错 / 零写 / 无缓存**）：两段合成——
+ * · **归属（第一段——§⑥ 归属形）**：`owningProject(target)` 沿祖先链取最近带档目录
+ *   （子优于根 / 不跨兄弟 / 无全局优先级）⇒ 读该档 ⇒ `ok` / `invalid`。
+ * · **发现兜底（第二段——§⑥ 发现规则，纯向下）**：祖先链无档 ⇒ `discoverProjects(target)` ⇒ 命中
+ *   （`self` / `unique`）⇒ 读其档（带档 ⇒ `ok` / `invalid`；缺档 ⇒ `missing`）；`ambiguous` ⇒
+ *   `ambiguous`（+ `candidates`）；`none` ⇒ `no-project`。
+ * 写侧（建档）**不在**此函数（归入口决策树——KD-M1-25 / M1-29）⇒ 注入器 / 只读消费面不会变写点。
+ * `matched` 契约：归属段命中 ⇒ `'manifest'`；发现段 ⇒ `discoverProjects.matched` 逐字；
+ * `no-project`（/ 覆盖位短路）⇒ `null`——报明行歧义变体按它分野（§2.6 条 1b）。
+ * 读错（非 ENOENT——权限 / 目录等）收为 `invalid`（非抛错契约；`readManifest` 语义零改）。
+ * @param {string} [target] 目标路径（目录 / 文件——动作作用于哪个项目的路径）
+ * @returns {{state:'ok'|'missing'|'no-project'|'ambiguous'|'invalid', root:string|null, path:string|null,
+ *   manifest?:object, candidates?:string[], errors?:string[], matched:'manifest'|'git'|null}}
+ */
+export function projectView(target) {
+  const anchor = resolve(target ?? ".")
+  const owning = owningProject(anchor)
+  if (owning) return viewAtRoot(owning, "manifest")
+  const d = discoverProjects(anchor)
+  if (d.kind === "ambiguous") return { state: "ambiguous", root: null, path: null, candidates: d.candidates, matched: d.matched }
+  if (d.kind === "none") return { state: "no-project", root: null, path: null, matched: null }
+  return viewAtRoot(d.root, d.matched)
+}
+
+/** `projectView` 公共尾段：给定项目根 ⇒ 读 + 校验 ⇒ `ok` / `missing` / `invalid`（非抛错）。 */
+function viewAtRoot(root, matched) {
+  const path = join(root, MANIFEST_REL)
+  let m
+  try {
+    m = readManifest(root)
+  } catch (e) {
+    return { state: "invalid", root, path, errors: [e?.message ?? String(e)], matched } // 读错（权限 / 目录等）⇒ 非抛错收口
+  }
+  if (m.ok) return { state: "ok", root, path, manifest: m.manifest, matched }
+  if (m.reason === "missing") return { state: "missing", root, path, matched }
+  return { state: "invalid", root, path, errors: m.errors, matched }
 }
 
 /**
@@ -114,8 +217,8 @@ export function docRootPaths(value, cwd) {
   return [...new Set(list)]
 }
 
-/** 落盘根：git 根优先（仓内任意子目录调用都落仓根——防错层）；无 .git（临时项目 / 测试）→ 退回 cwd
- *  （旧行为，不更坏）。防「写进 monorepo 容器根」的主闸 = 提示词（主 agent 会话锚必须进仓内）。 */
+/** 落盘根：**项目根**优先（项目树内任意子目录调用都落项目根——防错层，KD-M1-30 归属形）；
+ *  无项目（梯⑤ 存档 / 临时目录 / 测试注入）→ 退回 cwd（既有行为，不更坏）。 */
 function writeRoot(cwd) {
   return resolveProjectRoot(cwd) ?? resolve(cwd ?? ".")
 }
@@ -255,7 +358,8 @@ export function readManifest(cwd) {
 
 /**
  * 装配钩子入口（模块设计 §2.2）——同 readManifest(cwd)。ok:true 返回补默认值后的 manifest；
- * reason:'missing' 由调用方走初始化分支（壳面拒进正常循环直至初始化完成）。
+ * reason:'missing' 由调用方走**建档流**（**工程模式会话**口径——梯②④⑤ 就地建档，**不拒会话**；
+ * KD-M1-29）；普通会话 = 装配钩子零 manifest I/O（KD-M1-12）。
  */
 export function requireManifest(cwd) {
   return readManifest(cwd)
@@ -264,44 +368,44 @@ export function requireManifest(cwd) {
 /**
  * 入口决策树（**非抛错**形态——KD-M1-20；docs/core/design/MANIFEST.md §2.8 F1）：三面共用——
  * ① CLI 装配 / 重估薄包装 ② VSC `hydrateRun` 钩子块 ③ 翻转面（`eng` 工具 / `/eng` /
- * `/session` / ACP——「先判后翻」，拒翻分支零副作用）。判据树只此一处（判据单源——KD-M1-8 同族）。
+ * `/session` / ACP——「先判后翻」，拒翻分支零副作用）。判据树只此一处（判据单源——KD-M1-8
+ * 同族）；读侧解析与状态归位 = `projectView`（KD-M1-24——非抛错 / 零写）。
  *
- * 分支（四出口）：
- *   档合法          → { ok:true, manifest, created:false }（manifest = 补默认值后的档内容）
- *   缺档 + init     → 根可解析 ? `initManifest(cwd, { writer })`（抛错 → `init-failed`）
- *                             : { ok:false, code:'root-unresolvable', message }
- *   缺档 + !init    → { ok:false, code:'missing' }（不拒——调用方自决；VSC depth>0 分支用）
- *   档非法          → { ok:false, code:'invalid', message, errors }
+ * 分支（两分支六出口——§2.8 F1 树）：
+ *   档合法         → { ok:true, manifest, created:false }（manifest = 补默认值后的档内容）
+ *   缺档 + init    → 梯②④⑤（锚 = 裸仓 / 裸仓命中 / 无项目）⇒ `initManifest(cwd, { writer })`
+ *                    （抛错 → `init-failed`）；歧义（≥2 候选）⇒ `{ ok:false, code:'ambiguous',
+ *                    message, candidates }`（**不建 / 不猜**）
+ *   缺档 + !init   → 梯⑤（无项目）⇒ `{ ok:false, code:'no-project' }`（KD-M1-28；`init:false` 面）；
+ *                    梯②④（裸仓可解析、档缺）⇒ `{ ok:false, code:'missing' }`；歧义 ⇒ 同上
+ *   档非法         → { ok:false, code:'invalid', message, errors }
  *
  * `writer` 由调用点**显式**传（生产调用点全传 `'main'`）：缺省 `'subagent'` 是写门 fail-closed
- * 缺省（KD-M1-3），误用缺省 ⇒「缺档 + 根可解析」退化为 `init-failed`（拒翻——与 §2.8 F2 /
+ * 缺省（KD-M1-3），误用缺省 ⇒「缺档 + 梯②④⑤」退化为 `init-failed`（拒翻——与 §2.8 F2 /
  * AC-20② 语义相反；T38 反证格）。
- * 边界：`readManifest` 的非 ENOENT 读错（权限 / 目录等）按既有契约**上抛**（不伪装成缺失——
- * readManifest 语义零改）；本树只承诺上列四出口。
+ * 失败码两态文案不同（KD-M1-28）：无项目 ⇒ 可在锚处落地 / 歧义 ⇒ 列候选不猜；文案族 =
+ * 「项目不可解析」（稳定锚句 `/项目不可解析/`——拒翻面与报明面共用）。
+ * 边界：`readManifest` 的非 ENOENT 读错（权限 / 目录等）由 `projectView` 收为 `invalid`（非抛错
+ * 契约——`readManifest` 返回语义零改）；本树只承诺上列六出口。
  * @param {string} [cwd] 会话锚（缺省 → 进程 cwd）
  * @returns {{ok:true, manifest:object, created:boolean}
- *   | {ok:false, code:'missing'|'invalid'|'root-unresolvable'|'init-failed', message?:string, errors?:string[]}}
+ *   | {ok:false, code:'missing'|'invalid'|'no-project'|'ambiguous'|'init-failed',
+ *      message?:string, errors?:string[], candidates?:string[]}}
  */
 export function resolveEngineeringManifest(cwd, { writer = "subagent", init = true } = {}) {
-  const m = readManifest(cwd)
-  if (m.ok) return { ok: true, manifest: m.manifest, created: false }
-  if (m.reason === "invalid") {
+  const view = projectView(cwd)
+  if (view.state === "ok") return { ok: true, manifest: view.manifest, created: false }
+  if (view.state === "invalid") {
     return {
-      ok: false, code: "invalid", errors: m.errors,
-      message: `${MANIFEST_REL} 非法（fail-closed 拒进正常循环）：${m.errors.join("；")}`,
+      ok: false, code: "invalid", errors: view.errors,
+      message: `项目不可解析：${MANIFEST_REL} 非法（fail-closed）：${(view.errors ?? []).join("；")}`,
     }
   }
-  if (!init) return { ok: false, code: "missing" }
-  // 项目根 = git 仓根（2026-09-17 用户裁定：判据 = .git，向下找；每个仓一份 manifest）：
-  // cwd 非仓且子仓中无带 manifest 的仓（零个 = 无项目，多个 = 歧义）→ 不自动建档。
-  if (!resolveProjectRoot(cwd)) {
-    return {
-      ok: false, code: "root-unresolvable",
-      message:
-        `工程模式启动拒绝：会话锚 ${cwd} 不是 git 仓，且其子仓中带 ${MANIFEST_REL} 的不是恰好一个` +
-        `（零个 = 无项目；多个 = 歧义）——每个仓库一份 manifest，请锚在仓内或为子仓建档`,
-    }
+  if (view.state === "ambiguous") {
+    return { ok: false, code: "ambiguous", candidates: view.candidates, message: ambiguousProjectMessage(cwd, view.candidates) }
   }
+  // 缺档（梯②④⑤）：init ⇒ 就地建档（内容 = DEFAULT_MANIFEST，经写门 writer:'main'）；!init ⇒ 归码。
+  if (!init) return { ok: false, code: view.state === "no-project" ? "no-project" : "missing" }
   try {
     return { ok: true, manifest: initManifest(cwd, { writer }), created: true }
   } catch (e) {
@@ -309,6 +413,14 @@ export function resolveEngineeringManifest(cwd, { writer = "subagent", init = tr
   }
 }
 
+/** 歧义消息（文案族「项目不可解析」——KD-M1-28）：候选**全列**（绝对路径、按名排序）+ 指引
+ *  显式指定目标——**不猜**（与报明行同族；拒翻面经 F3 明示面逐字转发）。 */
+function ambiguousProjectMessage(cwd, candidates) {
+  const list = (candidates ?? []).map((c) => `- ${c}`).join("\n")
+  return `项目不可解析：会话锚 ${cwd} 下候选项目不是恰好一个（下列 ${(candidates ?? []).length} 个）——` +
+    `每个项目一份 ${MANIFEST_REL}；请显式指定目标项目（机制不猜）：\n${list}`
+}
+
 /**
  * 写门落盘（模块设计 §2.2 / KD-M1-3）：仅 writer === 'main' 放行（fail-closed 缺省拒）；
  * 落盘前先 validateManifest(manifest)（ok:false → 拒落盘，防写非法档）。

package/memory/core.mjs

@@ -12,11 +12,14 @@ import { normalizeOrigin } from "./origin.mjs"
 import { readFile, stat, readdir, writeFile, mkdir } from "node:fs/promises"
 import { join } from "node:path"
 import { segmentCJK, VALID_TYPES, SCHEMA_VERSION } from "./schema.mjs"
+// FTS 语言面单源外提（会话索引批 · SESSION.md §6.19）：本档只取用 + re-export 保名面
+// （零行为变更——实现住叶子档 `fts-text.mjs`）。
+import { buildFtsQuery } from "../fts-text.mjs"
+export { buildFtsQuery } from "../fts-text.mjs"
 import { safeSliceUTF16 } from "../text-budget.mjs"
 
 const EMBED_BATCH_SIZE = 256
 export const EMBED_TEXT_MAX_LEN = 2000
-const FTS_TOKEN_MAX = 16
 const DEFAULT_LIST_LIMIT = 50
 
 /**
@@ -299,20 +302,3 @@ export function clearPersonal(memory) {
   const { changes } = memory.db.prepare(`DELETE FROM entries`).run()
   return changes
 }
-
-/**
- * Build an FTS5 query: first split by whitespace/punctuation into tokens,
- * then apply CJK character segmentation to each token.
- * This keeps multi-character CJK words as FTS5 phrases ("分号" → "分 号" → phrase query, exact adjacency match),
- * while different tokens are joined with OR ("命名 规范" → "命 名" OR "规 范", each phrase requires its own adjacency).
- */
-export function buildFtsQuery(query) {
-  const terms = query
-    .split(/[\s,，。、;；!！?？()（）"`]+/)
-    .map((t) => t.trim())
-    .filter(Boolean)
-    .slice(0, FTS_TOKEN_MAX)
-    .map((t) => segmentCJK(t))
-  if (terms.length === 0) return ""
-  return terms.map((t) => `"${t.replaceAll('"', '""')}"`).join(" OR ")
-}

package/memory/schema.mjs

@@ -9,6 +9,10 @@
 import { DatabaseSync } from "node:sqlite"
 import { mkdirSync } from "node:fs"
 import { dirname } from "node:path"
+// FTS 语言面单源外提（会话索引批 · SESSION.md §6.19）：本档只取用 + re-export 保名面
+// （零行为变更——实现住叶子档 `fts-text.mjs`，会话索引面同源）。
+import { segmentCJK } from "../fts-text.mjs"
+export { segmentCJK } from "../fts-text.mjs"
 
 export const VALID_TYPES = new Set(["rule", "knowledge", "decision", "pattern"])
 export const SCHEMA_VERSION = 9
@@ -50,17 +54,6 @@ export const MAX_CODE_FILE_BYTES = 1024 * 1024   // 1 MB
 export const MAX_DOC_FILE_BYTES  = 512 * 1024    // 512 KB
 export const BIG_FILE_LINES = 2000
 
-/**
- * CJK character-by-character spacing: makes unicode61 treat each Han/Kana/Hangul character as an independent token.
- * Both write and query must use the same processing for retrieval to match.
- */
-export function segmentCJK(text) {
-  return text.replace(
-    /[぀-ヿ㐀-䶿一-鿿豈-﫿가-힯]+/g,
-    (run) => [...run].join(" "),
-  )
-}
-
 /**
  * Open/initialize the memory store. dbPath is auto-created if missing.
  * The returned memory object is the interface; all subsequent functions take it as their first argument.

package/package.json

@@ -1,21 +1,42 @@
 {
   "name": "@thincoder/core",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "description": "ThinCoder shared core — shared mechanism modules + shared prompt content (CLI ↔ VS Code extension).",
+  "keywords": [
+    "ai",
+    "agent",
+    "core",
+    "shared",
+    "llm",
+    "mcp"
+  ],
   "type": "module",
   "scripts": {
     "test": "node test/run.mjs",
     "prepublishOnly": "npm test"
   },
   "license": "MIT",
+  "author": "liwei <liwei@51marine.com> (上海新舶)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xinbo-tech/thincoder.git"
+  },
+  "homepage": "https://github.com/xinbo-tech/thincoder",
+  "bugs": {
+    "url": "https://github.com/xinbo-tech/thincoder/issues"
+  },
   "engines": {
     "node": ">=22.13.0"
   },
   "exports": {
     "./*": "./*"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "files": [
     "*.mjs",
+    "CHANGELOG.md",
     "advisor/",
     "agent/",
     "agent-tools/",

package/prompts/advisor-design.md

@@ -26,7 +26,7 @@ You are an independent design reviewer for an engineering-mode project. ## Your
 - Do NOT run git diff or look for code changes — there are none at this stage.
 
 ## 批次档 §3 落档（仅设计评审——工具已挂载时）
-设计评审专用（**仅当本评审为设计评审、且工具面里已挂载 `batch_segment` 时**——代码评审无此工具，本节不适用）：在报告之外，用 `batch_segment({segment:"§3", text})` 把本轮**发现表 + VERDICT + 计数逐字**写进批次档 §3（不给路径参数；工具自带 `### 轮次 N（评审子代理）` 来源戳，勿自写标题）。
+设计评审专用（**仅当本评审为设计评审、且工具面里已挂载 `batch`（过渡别名 `batch_segment`）时**——代码评审无此工具，本节不适用）：在报告之外，用 `batch({action:"append", segment:"§3", text})` 把本轮**发现表 + VERDICT + 计数逐字**写进批次档 §3（不给路径参数；工具自带 `### 轮次 N（评审子代理）` 来源戳，勿自写标题）。
 写不进去（被拒/失败）→ 报告里明说「§3 未写入」——不得静默略过，也不得假装写过（父侧代写必须打标）。
 
 ## Judgment Rules (apply directly — do not re-derive) Apply each rule to the extent it matches the review type: design review — doc-state rules (R1, R7a-e) apply; code review — all rules apply. R1 Doc contradiction / state inconsistency → 🟡 (report-and-fix by the parent doc layer — NOT 🔴; exception: the same mechanism described differently in two places = Document ownership 🔴 — keep this convention — do not downgrade)

package/prompts/advisor-round2.md

@@ -27,7 +27,7 @@ You have a budget of 15 tool rounds (chat turns). Hard mechanical cap: 100 round
 - Stop calling tools once you are ready to produce the review table.
 
 ## 批次档 §3 落档（仅设计评审——工具已挂载时）
-设计评审专用（**仅当本评审为设计评审、且工具面里已挂载 `batch_segment` 时**——代码评审无此工具，本节不适用）：在报告之外，用 `batch_segment({segment:"§3", text})` 把本轮**发现表 + VERDICT + 计数逐字**写进批次档 §3（不给路径参数；工具自带 `### 轮次 N（评审子代理）` 来源戳，勿自写标题）。
+设计评审专用（**仅当本评审为设计评审、且工具面里已挂载 `batch`（过渡别名 `batch_segment`）时**——代码评审无此工具，本节不适用）：在报告之外，用 `batch({action:"append", segment:"§3", text})` 把本轮**发现表 + VERDICT + 计数逐字**写进批次档 §3（不给路径参数；工具自带 `### 轮次 N（评审子代理）` 来源戳，勿自写标题）。
 写不进去（被拒/失败）→ 报告里明说「§3 未写入」——不得静默略过，也不得假装写过（父侧代写必须打标）。
 
 ## Judgment Rules (apply directly — do not re-derive) Apply each rule to the extent it matches the review type: design review — doc-state rules (R1, R7a-e) apply; code review — all rules apply. R1 Doc contradiction / state inconsistency → 🟡 (report-and-fix by the parent doc layer — NOT 🔴; exception: the same mechanism described differently in two places = Document ownership 🔴 — keep this convention — do not downgrade)

package/prompts/advisor-round3.md

@@ -23,7 +23,7 @@ You have a budget of 15 tool rounds (chat turns). Hard mechanical cap: 100 round
 - Stop calling tools once you are ready to produce the review table.
 
 ## 批次档 §3 落档（仅设计评审——工具已挂载时）
-设计评审专用（**仅当本评审为设计评审、且工具面里已挂载 `batch_segment` 时**——代码评审无此工具，本节不适用）：在报告之外，用 `batch_segment({segment:"§3", text})` 把本轮**发现表 + VERDICT + 计数逐字**写进批次档 §3（不给路径参数；工具自带 `### 轮次 N（评审子代理）` 来源戳，勿自写标题）。
+设计评审专用（**仅当本评审为设计评审、且工具面里已挂载 `batch`（过渡别名 `batch_segment`）时**——代码评审无此工具，本节不适用）：在报告之外，用 `batch({action:"append", segment:"§3", text})` 把本轮**发现表 + VERDICT + 计数逐字**写进批次档 §3（不给路径参数；工具自带 `### 轮次 N（评审子代理）` 来源戳，勿自写标题）。
 写不进去（被拒/失败）→ 报告里明说「§3 未写入」——不得静默略过，也不得假装写过（父侧代写必须打标）。
 
 ## Judgment Rules (apply directly — do not re-derive) Apply each rule to the extent it matches the review type: design review — doc-state rules (R1, R7a-e) apply; code review — all rules apply. R1 Doc contradiction / state inconsistency → 🟡 (report-and-fix by the parent doc layer — NOT 🔴; exception: the same mechanism described differently in two places = Document ownership 🔴 — keep this convention — do not downgrade)

package/prompts/common.md

@@ -110,8 +110,8 @@ Batch independent read-only tool calls into a single reply (they run concurrentl
 
 **Destructive-command red lines**:
 - **Never hand-roll delete verbs**: `rm` / `rmdir` / `del` / `rd` / `Remove-Item` and the like are never written into a command — deletions go through the existing tool face (`delete` / `git rm`, or a very narrow allowlist).
-- **Diagnostics are read-only**: existence / state checks use read-only commands only (`dir` / `ls` / `where` / `type`) — never smuggle a write or delete verb in, and never tag a real action "no-op / read-only".
-- **No silent masking**: no `2>nul` error-swallowing on destructive / write commands, no `&` (as opposed to `&&`) chaining — a failure must be visible.
+- **Diagnostics are read-only**: existence / state checks use read-only commands only (`dir` / `ls` / `where` / `type`) — never smuggle a write or delete verb in, and never tag a real action "no-op / read-only". When a dedicated tool exists for the job, the tool-routing table still wins — this bullet covers the bare-command case only.
+- **No silent masking**: no `2>nul` / `2>/dev/null` error-swallowing on destructive / write commands, no `&` / `;` (as opposed to `&&`) chaining — a failure must be visible.
 - **Confirm before irreversible actions**: stop before an irreversible action — the main session asks the user; a subagent raises an upstream `ask` (`notify_parent`).
 - **Boundary**: nothing at the tool layer catches this for you (no mechanical gate, no tool-semantics change) — you write the command, so you are the first line of defense.
 
@@ -153,6 +153,6 @@ Batch independent read-only tool calls into a single reply (they run concurrentl
 ## 批次档常识（Batch record — the carrier of engineering-mode task flow）
 **What it is**: the **batch record** = the **carrier** of an engineering-mode task (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.
 **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**: `batch_segment` — **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.
+**Writing means**: the `batch` tool (transition alias `batch_segment` — same append executor) — **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.
 **The task book itself**: `batchDoc` = the batch-record path = **your task book** (mandatory on every eng-designer / eng-coder spawn; **unreadable ⇒ refused** — do not execute, bounce it back).
 **Structure authority**: segment structure / gates / lifecycle are defined by the project's own batch-record mechanism (this section gives the map only — no mechanism restatement).