@thincoder/core 0.10.12 → 0.11.1

package/agent-tools/batch-paths.mjs

@@ -15,9 +15,11 @@
  * 依赖（KD-4 单向）：本档为**叶档**——只 import `node:*` 与 `../manifest.mjs`；主档 re-export 保既有面。
  */
 import { existsSync, statSync } from "node:fs"
-import { isAbsolute, relative, resolve, sep } from "node:path"
+import { isAbsolute, parse, relative, resolve, sep } from "node:path"
 
 import { docRootBase, docRootPaths, owningProject, projectRootView, readManifest, resolveProjectRoot } from "../manifest.mjs"
+// 候选序单源 = 统一解析层（`docs/core/design/PATH-RESOLUTION.md` §2.2）；本档只留本面参数与落位判据。
+import { danglingSameNameHint, resolvePathTarget } from "../path-resolve.mjs"
 
 /** 可读文件判据（存在且为文件——目录 / 缺失同判不可读）。 */
 function readableFile(abs) {
@@ -26,7 +28,7 @@ function readableFile(abs) {
 
 /** 工作区锚候选（判定单点 = `projectRootView`——`workspace` 态 ⇒ 候选全列**按名排序**；余者 null）。 */
 function workspaceCandidates(cwd) {
-  const view = projectRootView(cwd ?? process.cwd())
+  const view = projectRootView(cwd)
   return view.state === "workspace" ? view.candidates : null
 }
 
@@ -44,7 +46,7 @@ export function batchProjectRoot(cwd) {
 
 /** manifest **声明基底**（声明面；manifest 缺失 / 非法 / 读错 ⇒ 空集——v1 单基底语义零变）。 */
 function declaredBases(cwd) {
-  const base = cwd ?? process.cwd()
+  const base = cwd
   let man = { ok: false }
   try { man = readManifest(base) } catch { /* 读错 → 按无 manifest 处理（回退默认基底） */ }
   return man.ok ? docRootPaths(man.manifest?.docRoot?.batches, base) : []
@@ -103,53 +105,56 @@ const anchoredEscapeError = (raw) => new Error(`batch: create path is anchored a
 const workspaceCreateError = (raw, candidates) => new Error(`batch: create target "${raw}" belongs to no project — the session anchor holds ${candidates.length} project(s) below it: ${candidates.join(", ")}. Pass an explicit path under a project (e.g. "${candidates[0]}/docs/batches/<file>.md").`)
 const ambiguousLandingError = (raw, landings) => new Error(`batch: create path resolves under more than one declared batch-record base — refusing to pick one (fail-closed); pass an explicit path (absolute preferred). Path: ${raw}. Candidates: ${landings.join(", ")}`)
 
-/** 工作区锚读面候选分支（条 5）：逐候选项目——项目根形（`resolve(candidate, p)`）∥ 声明基底形
- *  （候选按名排序、并集保序——「首个可读」在此即为确定判读）。 */
-function workspaceReadLegs(cwd, p) {
-  const ws = workspaceCandidates(cwd)
-  if (!ws) return []
-  const out = []
-  for (const c of ws) {
-    out.push(resolve(c, p))
-    for (const b of declaredBases(c)) out.push(resolve(b, p))
+/**
+ * **读面**解析的四态本体（候选序 + 判态全部经统一解析层——本面只声明自己的参数：
+ * `order:"near-first"`（近基根 = cwd / 会话锚 先）+ `kind:"file"` + `crossRepo:"dangling"`，
+ * `bases` = `docRoot.batches` 声明面（读面无 manifest ⇒ 无这一级））。锚定串只解析项目根形
+ * （不二次拼接——§4.15 判据，见 `resolveBatchReadPath`）。
+ * 导出面供 spawn 门拼「追加同名候选」（§2.6：既有文案逐字在前，新信息追加在后）。
+ * @returns {object} 统一解析层的四态结果（`docs/core/design/PATH-RESOLUTION.md` §2.1）
+ */
+export function resolveBatchReadResult(cwd, given) {
+  const base = cwd
+  const raw = typeof given === "string" ? given.trim() : ""
+  if (!raw) return { state: "dangling", missing: String(given ?? ""), sameName: [], level: "path", tried: [] }
+  const p = raw.replace(/\\/g, "/")
+  if (anchoredPrefix(p, basePrefixes(base, batchDocBases(base)))) {
+    // 锚定形：只解析项目根形（已含基底相对前缀者不再二次拼接）
+    const root = batchProjectRoot(base)
+    return resolvePathTarget(root, p, { kind: "file", order: "root-first", bases: [root] })
   }
-  return out
+  return resolvePathTarget(base, raw, { kind: "file", order: "near-first", bases: declaredBases(base) })
 }
 
 /**
- * **读面**解析（append / status / close 与评审门 / spawn 门共用）：首个**可读**候选胜；无 ⇒ null
- * （调用方各自抛既有文案）。锚定串只解析项目根形（跳过 ①③——已含基底相对前缀者不再二次拼接）。
- * @param {string} cwd 会话锚（缺省 → 进程 cwd）
+ * **读面**解析（append / status / close 与评审门 / spawn 门共用）：解析出唯一落点且可读 ⇒ 该绝对路径；
+ * 其余（无果 / 判不出唯一）⇒ null（调用方各自抛既有文案）。
+ * @param {string} cwd 会话锚
  * @param {string} given 参数原值（相对 / 绝对、`\` 与 `/` 混写均可）
  * @returns {string|null} 可读文件的绝对路径 / null
  */
 export function resolveBatchReadPath(cwd, given) {
-  const base = cwd ?? process.cwd()
-  const raw = typeof given === "string" ? given.trim() : ""
-  if (!raw) return null
-  const p = raw.replace(/\\/g, "/")
-  if (anchoredPrefix(p, basePrefixes(base, batchDocBases(base)))) {
-    const abs = resolve(batchProjectRoot(base), p)
-    return readableFile(abs) ? abs : null
-  }
-  const candidates = [resolve(base, p), resolve(batchProjectRoot(base), p), ...declaredBases(base).map((b) => resolve(b, p)), ...workspaceReadLegs(base, p)]
-  for (const abs of candidates) if (readableFile(abs)) return abs
-  return null
+  const r = resolveBatchReadResult(cwd, given)
+  return r.state === "resolved" && readableFile(r.abs) ? r.abs : null
 }
 
 /**
  * 批次档路径门禁（评审侧 `BATCH-RECORD.md` §4.2 口径 = **「若传则须可读」**）：空 / 非字符串 / 不可读 → throw。
- * 非空且可读 → 返回绝对路径（`\` 归一——照 `files` / `batchDoc` spawn 门先例）。错误文案逐字零变（零回归硬约束）。
+ * 非空且可读 → 返回绝对路径（`\` 归一——照 `files` / `batchDoc` spawn 门先例）。既有文案逐字在前，
+ * 层的同名候选 / 候选全列**追加在后**（§2.6：新信息只追加）。
  */
 export function resolveBatchDocPath(cwd, given) {
-  const base = cwd ?? process.cwd()
+  const base = cwd
   const raw = typeof given === "string" ? given.trim() : ""
   if (!raw) {
     throw new Error("batchDoc must be a non-empty path to the batch record — pass the batch record currently in flight, or omit the parameter entirely when no batch record is in flight.")
   }
-  const abs = resolveBatchReadPath(base, raw)
-  if (abs) return abs
-  throw new Error(`batchDoc is not a readable file: ${raw} — pass the path of the batch record currently in flight (a path that resolves to an existing file), or omit the parameter when no batch record is in flight.`)
+  const r = resolveBatchReadResult(base, raw)
+  if (r.state === "resolved" && readableFile(r.abs)) return r.abs
+  const hint = r.state === "dangling"
+    ? (danglingSameNameHint(r) ? ` ${danglingSameNameHint(r)}` : "")
+    : r.state === "ambiguous" ? ` Candidates: ${r.candidates.join(" ∥ ")}` : ""
+  throw new Error(`batchDoc is not a readable file: ${raw} — pass the path of the batch record currently in flight (a path that resolves to an existing file), or omit the parameter when no batch record is in flight.${hint ? `；${hint.trim()}` : ""}`)
 }
 
 /**
@@ -163,7 +168,7 @@ export function resolveBatchDocPath(cwd, given) {
  * @returns {string} 落位绝对路径
  */
 export function resolveBatchCreatePath(cwd, given, bases) {
-  const base = cwd ?? process.cwd()
+  const base = cwd
   const raw = String(given ?? "").trim()
   const p = raw.replace(/\\/g, "/")
   let roots = bases
@@ -183,13 +188,15 @@ export function resolveBatchCreatePath(cwd, given, bases) {
     if (!insideBases(abs, roots)) throw anchoredEscapeError(raw)
     return abs
   }
-  for (const abs of [resolve(base, p), resolve(batchProjectRoot(base), p)]) {
-    if (insideBases(abs, roots)) return abs
+  // 候选序由统一解析层给（① 近基根 cwd/会话锚 → ② 项目根）；落位判据（落基底内）在原地判
+  for (const anchor of [base, batchProjectRoot(base)]) {
+    const r = resolvePathTarget(anchor, p, { kind: "none", order: "near-first", bases: roots })
+    if (r.state === "resolved" && insideBases(r.abs, roots)) return r.abs
   }
   // ③ 基底自有项目根形（#942 条 6）：owningProject 可判者逐基底取值；distinct 落点 ≥2 ⇒ 拒
   const owned = []
   for (const b of roots) {
-    const ownRoot = owningProject(b)
+    const ownRoot = owningProject(b, parse(b).root)
     if (!ownRoot) continue
     const abs = resolve(ownRoot, p)
     if (insideBases(abs, roots) && !owned.some((x) => samePath(x, abs))) owned.push(abs)
@@ -199,10 +206,8 @@ export function resolveBatchCreatePath(cwd, given, bases) {
   // ④ 基底相对形收窄单段（归一后无 `/` 才走原基底分支——多段串不二次拼接）
   const leafRel = roots.length ? relative(roots[0], resolve(roots[0], p)) : ""
   if (leafRel && !leafRel.startsWith("..") && !leafRel.includes(sep)) {
-    for (const b of roots) {
-      const abs = resolve(b, p)
-      if (insideBases(abs, roots)) return abs
-    }
+    const r = resolvePathTarget(roots[0], p, { kind: "none", order: "near-first", bases: roots })
+    if (r.state === "resolved" && insideBases(r.abs, roots)) return r.abs
   }
   throw outsideBasesError(raw)
 }

package/agent-tools/batch-read.mjs

@@ -20,7 +20,7 @@ const SEGMENTS = [1, 2, 3, 4, 5, 6]
 /** 批次档列举（只读）：`{ batches: [{ file, path, sections }] }`——`path` = 绝对路径（`/` 归一）、
  *  `file` = basename、`batches` 按路径升序；单档读错跳过（尽力面）。`bases` 缺省 = `batchDocBases(cwd)`。 */
 export function listBatchRecords({ cwd, bases } = {}) {
-  const base = cwd ?? process.cwd()
+  const base = cwd
   const roots = bases ?? batchDocBases(base)
   const files = new Set()
   for (const root of roots) for (const abs of collectMarkdownFiles(root)) files.add(abs.replace(/\\/g, "/"))

package/agent-tools/batch-reopen.mjs

@@ -0,0 +1,142 @@
+/**
+ * agent-tools/batch-reopen.mjs — 重开径（`§1` 已收口 → 进行中）与台账回收调点（从 `batch-lifecycle.mjs`
+ * 拆出，2026-10-27）。
+ *
+ * 权威规格 = `docs/core/design/BATCH-RECORD.md` §4.18-B（重开的档面语义）+ `docs/core/design/BATCH-LEDGER-REVIEW-UNIFY.md`
+ * §2.13（重开回收：收口的反面——批档开 ⇒ 台账行回工作位）。
+ *
+ * 两件事：
+ * ① `rewriteAsReopen` —— 一次写盘、两处落笔：状态行原位改写 + §1 段尾追记行（append-only：行数 +1、
+ *    仅状态行原位替换、余行逐字节不变）。
+ * ② `reclaimOnReopen` —— 台账写点（`ledgerReclaimBatch`）：`待核销 → 在途`（行回工作位）；`已核销` 不动
+ *    （终态）+ 回执点名；其余状态零触。**失败不否决重开**（重开是从误冻结里出来的唯一通路，台账库忙不该
+ *    把档锁死）——失败 ⇒ 重开照成、回执点名失败原文 + 后果 + 出路。
+ *
+ * 触发判据**不在这里**：只由 `batch-lifecycle.mjs` 的 `reopen` 合取触发（`seg === 1 ∧ depth0 ∧ ¬review ∧
+ * 值 = 进行中 ∧ 前态 = closed`）——两处各推一次必然漂移，本档只承接「已判定要重开」之后的动作。
+ */
+import { dirname, relative } from "node:path"
+
+import { STATUS_LINE_RE, sectionHeaderRe, updateSectionStatusLine } from "./batch-skeleton.mjs"
+
+/** 本地今天（YYYY-MM-DD）——重开日期戳（close 侧同一枚，经本档导出复用——日期口径只此一处）。 */
+export function todayLocal() {
+  const d = new Date()
+  const p = (n) => String(n).padStart(2, "0")
+  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`
+}
+
+/** note 单行判据（两径共用——非重开径落状态行括注、重开径落 §1 追记行，两者都是一行；重开径不取
+ *  `assertStatusNote` 的另两条判据〔词表零命中 / 死占位〕——理由允许携状态词表关键字，而追记行不是
+ *  状态行形态、不参与 gate 判读）。 */
+export function assertSingleLineNote(note) {
+  if (/\r?\n/.test(note)) {
+    throw new Error("batch: status note must be a single line — a multi-line note would break the one-line status-line form. Nothing was written.")
+  }
+}
+
+/** 重开缺理由拒绝句（§4.18-B J4——触发合取缺 note；逐字文本 = `TOOLS.md` §6.24 J4）。 */
+export function reopenReasonError() {
+  return "batch: 重开需理由（reopen requires a reason）— reopening a frozen record reverses a recorded decision, so the reason must be stated: pass it as `note` (it lands verbatim in the §1 reopen record). Nothing was written."
+}
+
+/** §1 状态行值原文（改写前的读取面——readBatchStatusLine 只给三态，日期字面须自己读）。
+ *  **取值区 = §1 段头区**（`## §1` 标题之后、下一 `^#{2,}` 起行之前——与写面同一条定位面）：
+ *  回执要的是真段级那一行，段体 / 轮次块里引述的状态行不算。 */
+export function readBatchStatusLineRaw(src) {
+  const s1 = /^## §1(?=\s|$)/m.exec(src)
+  if (!s1) return null
+  const zone = src.slice(s1.index + s1[0].length)
+  const cut = zone.search(/^#{2,}/m) // 区界判据与写面同一条：任意 `##` / `###` 起行都结束段头区
+  const body = cut < 0 ? zone : zone.slice(0, cut)
+  return body.split(/\r?\n/).map((line) => STATUS_LINE_RE.exec(line)).find(Boolean)?.[1] ?? null
+}
+
+/**
+ * §N 段尾追加一行（§4.18-B——重开追记行载体；append-only：只追加，既有行字节零变）。
+ * 位置 = 段体尾部（下一 `## §` 段头之前 ∥ 文末）；追加行 EOL = §N 段头行自身行尾
+ * （`\r\n` ⇒ CRLF ∥ 其余 ⇒ `\n`——探测窗 = 段头行整体〔含行尾〕）。段标题缺失 ⇒ throw。
+ */
+export function appendLineToSection(src, seg, line) {
+  const hdr = sectionHeaderRe(seg).exec(src)
+  if (!hdr) {
+    throw new Error(`batch: the batch record has no "## §${seg}" section header — cannot append to its tail (create is the skeleton's only authoritative entry). Nothing was written.`)
+  }
+  const headerLine = /^## §\d[^\r\n]*\r?\n/m.exec(src.slice(hdr.index))
+  const eol = headerLine?.[0].endsWith("\r\n") ? "\r\n" : "\n"
+  const nextRe = /^## §\d/gm
+  nextRe.lastIndex = hdr.index + hdr[0].length
+  const next = nextRe.exec(src)
+  const endIdx = next ? next.index : src.length
+  let before = src.slice(0, endIdx)
+  const after = src.slice(endIdx)
+  // 只保证「行自成行」：段尾无换行 ⇒ 补一个段头行行尾；已有换行零补（不插空行——只追加判据 = 行数 +1）
+  if (!before.endsWith(eol)) before += eol
+  return before + line + eol + after
+}
+
+/**
+ * 重开写盘全文（§4.18-B——已收口档 status(进行中, note 非空)）：一次写盘、两处落笔——
+ * ① §1 状态行 → `进行中（重开 <YYYY-MM-DD>）`；② §1 **段尾追加**追记行
+ * `**重开记录**：<日期> · 原收口 <旧日期> · 理由 = <note> · 操作者 = 主 agent`
+ * （原收口 = 改写前状态行的收口日期字面，无日期字面 ⇒ `未标日期`）。
+ * EOL = §1 段头行自身行尾（CRLF 档 ⇒ CRLF）。
+ * @param {string} src — 档全文（closed 态）
+ * @param {string} note — 重开理由（调用面已验非空单行）
+ * @returns {string} 写盘用新全文
+ */
+export function rewriteAsReopen(src, note) {
+  const prevLine = (readBatchStatusLineRaw(src) ?? "").trim()
+  const prevDate = /已收口\s*(\d{4}-\d{2}-\d{2})/.exec(prevLine)?.[1] ?? "未标日期"
+  const date = todayLocal()
+  const withStatus = updateSectionStatusLine(src, 1, `进行中（重开 ${date}）`)
+  return appendLineToSection(withStatus, 1, `**重开记录**：${date} · 原收口 ${prevDate} · 理由 = ${note} · 操作者 = 主 agent`)
+}
+
+/**
+ * 重开回收调点（设计档 §2.13）：写入单源 = `ledgerReclaimBatch`（本档只供 `cwd` 基准、会话 id 与回执形；
+ * 工具层零 SQL）。`cwd` = **批档所属项目根**（`resolveLedgerRoot(dirname(<batchDoc>), boundary)?.root`——
+ * 不用会话锚：多根工作区锚会收到别的项目根 ⇒ 选行零命中 ⇒ 唯一的机器写静默失效）；`boundary` = 会话锚。
+ * 无根 ⇒ 传 `null`（核心不取行，`failed` 点名——不落兜底基准）。
+ * **失败不抛**（台账忙 ∥ 无根均不否决重开——档面写与台账库分属两存储）。
+ * @param {string} abs — 本批批档绝对路径
+ * @param {string} boundary — 会话锚（上溯上界）
+ * @returns {Promise<{batch:string, reclaimed:Array, unreclaimable:Array, failed:string|null}>}
+ */
+export async function reclaimOnReopen(abs, boundary) {
+  try {
+    const { ledgerReclaimBatch, resolveLedgerRoot } = await import("../ledger.mjs") // 动态 import：ledger-db 静态引 node:sqlite（W8 契约②）
+    const { getSessionId } = await import("../session-slots.mjs") // 同一动态 import 面：executor = 本会话（AC-M2-7）
+    const root = resolveLedgerRoot(dirname(abs), boundary)?.root ?? null
+    // 句内路径统一正斜杠（与 `task_book` 列值同形——`<批名>` 是给人读的事实句，不是平台路径）
+    return ledgerReclaimBatch({
+      cwd: root,
+      batch: root ? relative(root, abs).replace(/\\/g, "/") : abs,
+      boundary,
+      executorSessionId: getSessionId(),
+    })
+  } catch (e) {
+    // 非预期异常（模块加载失败 ∥ 根推导内读声明抛）同样不得否决重开——降为同一返回形（台账零改）
+    return { batch: abs, reclaimed: [], unreclaimable: [], failed: String(e?.message ?? e) }
+  }
+}
+
+/**
+ * 重开回收回执（设计档 §2.13 逐字；空行不出）：`failed` 非空 ⇒ 只出第三行（替代前两行）。
+ * 第三行 = 失败原文 + 后果 + 出路——「行仍 `待核销` ⇒ 台账里没有该档的在途行（写锁会拒每一笔写盘），
+ * 库恢复后 update → 在途」。
+ * @param {{reclaimed:Array, unreclaimable:Array, failed:string|null}|null} result
+ */
+export function reopenReceiptLine(result) {
+  if (!result) return ""
+  const face = (r) => `#${r.id} 「${r.title}」`
+  if (result.failed) {
+    return `\n[ledger reopen] 回收失败：${result.failed}——台账零改；行仍 待核销 的，台账里没有该档的在途行（写锁会拒每一笔写盘），库恢复后 update → 在途`
+  }
+  const lines = []
+  if ((result.reclaimed ?? []).length) lines.push(`\n[ledger reopen] 本批待核销行 → 在途 ${result.reclaimed.length} 行：${result.reclaimed.map(face).join("；")}`)
+  if ((result.unreclaimable ?? []).length) {
+    lines.push(`\n[ledger reopen] 本批已核销行不可回收 ${result.unreclaimable.length} 行：${result.unreclaimable.map(face).join("；")}——已核销为终态，重开不回收；要继续做须另立新行（新档 §1「前情」指回本档）`)
+  }
+  return lines.join("")
+}