@thincoder/core 0.9.4 → 0.10.1

package/agent-tools/bash-async.mjs

@@ -0,0 +1,281 @@
+/**
+ * bash-async.mjs — #9 `bash` 后台任务池（异步 ∥ 后台执行；设计 = 批档
+ * `docs/batches/2026-09-29-tools-carryover.md` §2.1——口径同源 = consult ∥ escalate 族，
+ * AGENT-LOOP-ASYNC-POOL.md §6.8 ∥ §6.10）。
+ *
+ * 本档 = 后台任务单点（池 ∥ 起跑 ∥ 结算 ∥ 杀）：
+ * - 池：分域池 `_bgTasks`（模式照 `_asyncAdvisors`——独立池 + 载体吸收：写侧父字段、读侧
+ *   `carrierField`——缺省借用/别名 `history` 侧，VSC 形跨 runAgent 存活）。
+ * - 起跑：id 沿 `nextSubagentId` 共用命名空间（`bash#N` 前缀区分域）；帽 `BG_TASK_MAX = 4`
+ *   （对齐 `ASYNC_POOL_LIMITS` 单域 4）——超限**显式拒**（零静默丢；无排队面）。
+ * - 输出面：全量流式落盘 `configDir/tool-results/<ts>-bash-<id>.log`（轮转复用
+ *   `cleanupOldToolResults`）；内存尾部环形缓冲（注入面取尾截：≤120 行 ∧ ≤8KB 双帽 +
+ *   截尾注记；全量恒在 log——不经预算 offload）。
+ * - 送达：进程退出/被杀 ⇒ 结算 ⇒ 停靠 pending 单容器（consult 族同式「恒出池」）⇒ 唤醒挂起
+ *   驱动（`wakeAsyncWaiters`）⇒ 消化轮 run-start 注入（`injectBgResult`——子代理族注入器
+ *   `injectAsyncResult` 按 role="bg" 分发到本档）。
+ * - 超时：async **不收**同步径默认 120s（长任务 = 本形目的）；显式 `timeout` 到点杀树
+ *   （结算状态 `killed: timeout`）。
+ * - 收尾两档（D9-7）：回合中断（Ctrl+I）**不杀**——`bindChildController` interrupt 豁免，
+ *   池保留（后续经 wait_for ∥ settle 消费）∥ 会话中止（Ctrl+C ∥ Stop）⇒ 条目控制器中止 ⇒
+ *   `async-discard.mjs` 收尾面逐条杀树 + 出池 + 墓碑（单不变量「杀 ⟺ 控制器已中止」）。
+ * - 边界（v1）：不做可见面板块 ∥ 状态行段；不做跨会话存活（会话结束即清——进程退出径无钩子）。
+ *
+ * 模块图：→ agent-tools/async-settle.mjs（池 accessor ∥ pending 停靠 ∥ 墓碑 ∥ 唤醒 ∥ 控制器
+ * 链结）· subagent-scheduler.mjs（取号/令牌/入池键守卫）· tools/process-tree.mjs（树杀）·
+ * tools/shared.mjs（解码/清洗——与同步径同源）· tools/bash.mjs（`buildBashEnv` 单源）·
+ * agent/helpers.mjs（转义 ∥ 轮转清理）· config.mjs（configDir）· context.mjs（pushReal）
+ * ——叶子向、无环。
+ * 入径 = `tools/bash.mjs` / `tools/ops.mjs` **动态 import**（W8 契约②：本档静态链含
+ * agent-tools 族 ⇒ 端壳静态闭包不得经工具档命中 node:sqlite）。
+ */
+import { createWriteStream } from "node:fs"
+import { mkdir } from "node:fs/promises"
+import { join } from "node:path"
+import { spawn } from "node:child_process"
+import { configDir } from "../config.mjs"
+import { cleanupOldToolResults, escapeXml } from "../agent/helpers.mjs"
+import { pushReal } from "../context.mjs"
+import { makeDecoder, sanitizeOutput } from "../tools/shared.mjs"
+import { killProcessTree } from "../tools/process-tree.mjs"
+import { buildBashEnv } from "../tools/bash.mjs"
+import {
+  bindChildController, buildChildSignal, carrierField, getAsyncPool, parkAsyncPending,
+  tombstoneOf, wakeAsyncWaiters, writeTombstone,
+} from "./async-settle.mjs"
+import { assertPoolKeyFree, consumeSubagentToken, nextSubagentId } from "./subagent-scheduler.mjs"
+
+/** 后台任务帽（对齐 `ASYNC_POOL_LIMITS` 单域 4——AGENT-LOOP-ASYNC-POOL.md §6.10）。超限显式拒。 */
+export const BG_TASK_MAX = 4
+
+/** 注入面双帽（批档 §2.1.3 送达面）：≤120 行 ∧ ≤8KB；全量恒在 log。 */
+const DIGEST_TAIL_MAX_LINES = 120
+const DIGEST_TAIL_MAX_CHARS = 8 * 1024
+/** 内存尾部环形缓冲保留量（缓冲仅需覆盖注入帽——多留一成余量）。 */
+const TAIL_KEEP_CHARS = 32 * 1024
+/** exit→close 宽限（同同步径后台注记面：孙进程握管道时 close 不来——`bash.mjs` 1500ms 同值）。 */
+const EXIT_GRACE_MS = 1500
+
+/** 测试缝：log 目录重定向（单测沙箱——生产从不调用；`_setDigestOffloadDirForTest` 同式）。 */
+let _bgTaskLogDir = null
+export function _setBgTaskLogDirForTest(dir) { _bgTaskLogDir = dir }
+function bgTaskLogDir() { return _bgTaskLogDir ?? join(configDir, "tool-results") }
+
+/** 池写侧（绑定不变式：主容器落父字段；缺省借用 `history` 侧 + 载体别名——`writeTombstone`
+ *  借用法同式，VSC 形跨 runAgent 存活；CLI 形父字段恒在场——零差分）。 */
+function ensureBgPool(parent) {
+  if (parent._bgTasks instanceof Map) return parent._bgTasks
+  const borrowed = carrierField(parent, "_bgTasks")
+  if (borrowed instanceof Map) { parent._bgTasks = borrowed; return borrowed }
+  parent._bgTasks = new Map()
+  if (parent?.history && typeof parent.history === "object") parent.history._bgTasks = parent._bgTasks
+  return parent._bgTasks
+}
+
+/** 条目读取（键形单源：写侧 `set(String(id))` ⇒ 读一律 String 归一；双形键兜底照子代理族）。 */
+export function bgTaskEntry(parent, id) {
+  const pool = getAsyncPool(parent, "bg")
+  if (!(pool instanceof Map)) return null
+  const key = String(id)
+  return pool.get(key) ?? pool.get(Number(key)) ?? null
+}
+
+/** `wait_for` 条件 `bash id:N done` 判据（同式 `subagent id:N done`）：池内 done ∥ **出池即 done**
+ *  （结算恒出池——pending 停靠/丢弃/消费皆已结束，无可等待物；未知 id 亦按 done-by-vacuity）。 */
+export function bgTaskDone(parent, id) {
+  const entry = bgTaskEntry(parent, id)
+  if (!entry) return true
+  return entry.done === true || entry.status === "done"
+}
+
+/** 杀单点：条目进程树（process kill ∥ discard 收尾面共用——树杀函数单源 = `tools/process-tree.mjs`）。 */
+export function killBgTree(entry) {
+  if (entry?.child) killProcessTree(entry.child)
+}
+
+/**
+ * 起跑（ack 即返）。失败面 = 显式 `{ error }`（帽/深度/上下文——零静默丢）。
+ * @returns {{ id: number, ack: string, entry: object } | { error: string }}
+ */
+export async function launchBgTask(parent, ctx, { command, timeout = null, shell = null } = {}) {
+  if (!parent) return { error: "no agent context — background tasks run in a depth-0 session only" }
+  if ((ctx?.depth ?? 0) > 0) {
+    return { error: "bash async is depth-0 only — a child agent has no background task pool (run the command synchronously)" }
+  }
+  const pool = ensureBgPool(parent)
+  const running = [...pool.values()].filter((e) => e.done !== true)
+  if (running.length >= BG_TASK_MAX) {
+    return {
+      error: `background task cap reached (${running.length}/${BG_TASK_MAX} running: ${running.map((e) => `bash#${e.id}`).join(", ")})` +
+        ` — wait for one to settle (wait_for "bash id:N done") or kill one (process action='kill' id:N)`,
+    }
+  }
+  const dir = bgTaskLogDir()
+  await cleanupOldToolResults(dir)
+  await mkdir(dir, { recursive: true })
+  // ED-5：取号 → 消费同步配对（无 await 间隙）+ 入池键守卫（同 id 二次入池 = 静默覆写 ⇒ 抛）
+  // ——守卫前置于 spawn：命中即抛时零副作用（无孤儿进程/无半开 log）。
+  const id = nextSubagentId(parent)
+  consumeSubagentToken(parent, id, "bash async launch", "bash")
+  assertPoolKeyFree(pool, id, "bash")
+  const logPath = join(dir, `${Date.now()}-bash-${id}.log`)
+  const cwd = ctx?.cwd ?? parent.cwd ?? process.cwd()
+  // UTF-8 码页前缀 = 同步径同款（win32 + 默认 shell）；解码走 `makeDecoder`（同源）。
+  const effectiveCommand = process.platform === "win32" && !shell ? `chcp 65001 >nul && ${command}` : command
+  const child = spawn(effectiveCommand, [], {
+    cwd,
+    shell: shell ?? true,
+    windowsHide: true,
+    detached: process.platform !== "win32",
+    stdio: ["ignore", "pipe", "pipe"],
+    env: buildBashEnv(),
+  })
+  const entry = {
+    id, role: "bg", command, child, logPath,
+    status: "running", done: false, cancelled: false, discarded: false,
+    startedAt: Date.now(), endedAt: null, exit: null, killed: null, error: null,
+    report: null, tail: "", tailDropped: false, bytes: 0,
+    timeoutMs: null, timer: null, graceTimer: null, controller: null,
+    logStream: null, _settle: null, promise: null,
+  }
+  entry.promise = new Promise((res) => { entry._settle = res })
+  entry.logStream = createWriteStream(logPath, { flags: "a" })
+  entry.logStream.on("error", () => { /* log 写失败不进结算语义——尽力面 */ })
+  const outDecoder = makeDecoder()
+  const errDecoder = makeDecoder()
+  const appendChunk = (s) => {
+    if (!s) return
+    entry.bytes += s.length
+    try { entry.logStream.write(s) } catch { /* 同上——尽力面 */ }
+    entry.tail += s
+    if (entry.tail.length > TAIL_KEEP_CHARS) {
+      entry.tail = entry.tail.slice(entry.tail.length - TAIL_KEEP_CHARS)
+      entry.tailDropped = true
+    }
+  }
+  child.stdout.on("data", (d) => appendChunk(sanitizeOutput(outDecoder(d))))
+  child.stderr.on("data", (d) => appendChunk(sanitizeOutput(errDecoder(d))))
+  // 会话/回合信号链（#98 链结单点——interrupt 豁免内建）：非 interrupt 中止 ⇒ 控制器中止 ⇒
+  // discard 收尾面（杀树 + 出池 + 墓碑）；回合中断（Ctrl+I）⇒ 不动（F2 同款豁免）。
+  const ctrl = new AbortController()
+  entry.controller = ctrl
+  bindChildController(ctrl, buildChildSignal(parent, ctx))
+  // 显式 timeout（async 缺省无超时——本形目的）：到点杀树，结算状态 `killed: timeout`。
+  if (Number.isFinite(timeout) && timeout > 0) {
+    entry.timeoutMs = timeout
+    entry.timer = setTimeout(() => {
+      entry.killed = "timeout"
+      killBgTree(entry)
+    }, timeout)
+  }
+  child.on("error", (error) => {
+    entry.error = error?.message ?? String(error)
+    finalizeBgEntry(parent, entry, { code: null, signal: null })
+  })
+  child.on("exit", (code, exitSignal) => {
+    if (entry.done) return
+    // 宽限窗（同步径同判据）：孙进程握管道 ⇒ close 不来——到点按「可能仍在跑」收尾。
+    entry.graceTimer = setTimeout(() => {
+      finalizeBgEntry(parent, entry, { code, signal: exitSignal, background: true })
+    }, EXIT_GRACE_MS)
+  })
+  child.on("close", (code, exitSignal) => {
+    finalizeBgEntry(parent, entry, { code, signal: exitSignal })
+  })
+  pool.set(String(id), entry)
+  return { id, ack: `bash#${id} started (running) — log: ${logPath}`, entry }
+}
+
+/**
+ * 结算单点（close ∥ exit 宽限 ∥ spawn error 三径合流；幂等：entry.done 即返）。
+ * 杀/丢弃两态（报告不可达）⇒ 只落终态与唤醒；正常退出 ⇒ 停靠 pending + 唤醒挂起驱动。
+ */
+function finalizeBgEntry(parent, entry, { code = null, signal = null, background = false } = {}) {
+  if (entry.done) return
+  entry.done = true
+  entry.status = "done"
+  entry.endedAt = Date.now()
+  entry.exit = { code, signal, background }
+  if (entry.graceTimer) { clearTimeout(entry.graceTimer); entry.graceTimer = null }
+  if (entry.timer) { clearTimeout(entry.timer); entry.timer = null }
+  try { entry.logStream?.end() } catch { /* 尽力面 */ }
+  getAsyncPool(parent, "bg")?.delete(String(entry.id))
+  if (entry.cancelled === true || entry.discarded === true) {
+    entry._settle?.() // 定向杀 ∥ 会话中止收尾——不注入（状态/墓碑已由杀点落定）
+    return
+  }
+  entry.report = renderTail(entry).text
+  parkAsyncPending(parent, entry)
+  entry._settleSeq = (parent._asyncSettleSeq = (parent._asyncSettleSeq ?? 0) + 1)
+  entry._settle?.()
+  wakeAsyncWaiters(parent)
+}
+
+/** 注入面尾截（双帽 + 截尾判据：行帽/字符帽/环形缓冲丢头三径合一）。 */
+function renderTail(entry) {
+  let text = String(entry.tail ?? "")
+  let truncated = entry.tailDropped === true
+  const lines = text.split("\n")
+  if (lines.length > DIGEST_TAIL_MAX_LINES) {
+    text = lines.slice(-DIGEST_TAIL_MAX_LINES).join("\n")
+    truncated = true
+  }
+  if (text.length > DIGEST_TAIL_MAX_CHARS) {
+    text = text.slice(-DIGEST_TAIL_MAX_CHARS)
+    truncated = true
+  }
+  return { text, truncated }
+}
+
+/** 注入器（digest 单点族成员——`injectAsyncResult` 按 role="bg" 分发；消费即墓碑）。 */
+export async function injectBgResult(parent, entry) {
+  const exit = entry.exit ?? {}
+  const status = entry.killed === "timeout"
+    ? "killed: timeout"
+    : entry.error != null ? `spawn failed: ${entry.error}`
+    : exit.background ? `exit code ${exit.code} (a child process still holds the output pipe — output may be incomplete; it may still be running)`
+    : exit.signal ? `killed: ${exit.signal}`
+    : `exit code ${exit.code}`
+  const seconds = (Math.max(0, (entry.endedAt ?? Date.now()) - entry.startedAt) / 1000).toFixed(1)
+  const head = `[System reminder: background bash#${entry.id} finished — \`${entry.command}\` (${status}, ${seconds}s) — full log: ${entry.logPath}]`
+  const { text, truncated } = renderTail(entry)
+  const body = text.trim() ? escapeXml(text) : "(no output)"
+  const note = truncated ? `\n[... tail truncated — the full output is in the log: ${entry.logPath}]` : ""
+  pushReal(parent, { role: "user", content: `${head}\n${body}${note}` })
+  writeTombstone(parent, entry.id, entry.error != null ? "failed" : "consumed", "bg")
+}
+
+/**
+ * 杀单点（id 靶——`process` action='kill'）：杀树 + 出池 + 墓碑（cancelled）；重复 = 幂等
+ * （经终态墓碑返回同一确认——`cancelAsyncAdvisor` 同式）。
+ * @returns {{ id: string, status: "cancelled" | "error", error?: string, logPath?: string }}
+ */
+export function killBgTask(parent, id) {
+  const key = String(id)
+  if (!key || key === "undefined" || key === "null") {
+    return { id: key, status: "error", error: "process kill id: requires a background bash task id (bash#N from the async ack)" }
+  }
+  const pool = getAsyncPool(parent, "bg")
+  const entry = bgTaskEntry(parent, key)
+  if (!entry) {
+    const tomb = tombstoneOf(parent, key)
+    if (tomb?.status === "cancelled" && tomb.role === "bg") return { id: key, status: "cancelled" } // 幂等确认
+    return { id: key, status: "error", error: `unknown background bash task id: ${key} — it has finished, was killed, or was never started` }
+  }
+  if (entry.done) return { id: key, status: "error", error: `bash#${key} has already finished — nothing to kill` }
+  if (entry.cancelled) return { id: key, status: "cancelled", logPath: entry.logPath } // 杀已在途——幂等
+  entry.cancelled = true
+  killBgTree(entry)
+  pool?.delete(key)
+  writeTombstone(parent, key, "cancelled", "bg")
+  return { id: key, status: "cancelled", logPath: entry.logPath }
+}
+
+/** 杀单点（pid 靶——`process` action='kill'）：`killProcessTree` 同款（win32 `taskkill /T /F` ∥
+ *  POSIX 组杀 + 直杀兜底）；pid 形态非法 ⇒ false（调用方给显式错误）。 */
+export function killBgPid(pid) {
+  const n = Number(pid)
+  if (!Number.isInteger(n) || n <= 0) return false
+  killProcessTree({ pid: n, kill: (sig) => process.kill(n, sig) })
+  return true
+}

package/agent-tools/batch-lifecycle.mjs

@@ -5,9 +5,9 @@
  * depth-0 在飞批定位（findInFlightBatch——D-BR21）。判定字面全部单源自 batch-skeleton.mjs
  * （SEGMENT_BY_ROLE / STATUS_WORDS / STATUS_LINE_RE / readBatchStatusLine / sectionHeaderRe /
  * batchSkeleton / TEMPLATE_PLACEHOLDERS / findPlaceholderResidue / placeholderResidueError）；
- * 路径解析单源（resolveBatchDocPath / batchDocBases）与 #84 记账缝住 batch.mjs
- * 主档——**依赖单向（KD-4）：skeleton ← lifecycle ← 主档**，主档把解析后的 cwd/bases/目标闭包
- * 传进来，本档不回 import 主档（防环）。
+ * 路径解析单源（`resolveBatchDocPath` / `batchDocBases` / `resolveBatchCreatePath`——住 `batch-paths.mjs`，
+ * 本档 import 取用）与 #84 记账缝住 batch.mjs 主档——**依赖单向（KD-4）：paths ← skeleton ← lifecycle
+ * ← 主档**，主档把解析后的 cwd/bases/目标闭包传进来，本档不回 import 主档（防环）。
  *
  * 身份判据（D-BR17/D-BR18/D-BR21）：主 agent 的工具调用 ctx 带 `depth === 0`（dispatch 装配）；
  * eng 子代理 `ctx.depth > 0`；评审实例 ctx 无 depth 但工具以 `review: true` 绑定。create/close
@@ -16,12 +16,13 @@
  * 状态面走普通文档写）；depth-0 的 status/path 面按 D-BR21（可选 path，缺省 = 在飞批唯一时取）。
  */
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs"
-import { dirname, isAbsolute, resolve, sep } from "node:path"
+import { dirname, resolve } from "node:path"
 
 import {
-  SEGMENT_BY_ROLE, STATUS_WORDS, STATUS_LINE_RE, readBatchStatusLine, sectionHeaderRe, batchSkeleton,
+  SEGMENT_BY_ROLE, STATUS_WORDS, STATUS_LINE_RE, readBatchStatusLine, sectionHasStatusLine, sectionHeaderRe, batchSkeleton,
   TEMPLATE_PLACEHOLDERS, findPlaceholderResidue, placeholderResidueError,
 } from "./batch-skeleton.mjs"
+import { resolveBatchCreatePath } from "./batch-paths.mjs"
 
 /** 可读文件判据（存在且为文件——目录/缺失同判不可读；与主档同名 helper 同型——KD-4 单向
  *  依赖下各自持有，三行谓词不构成第二权威源）。 */
@@ -55,8 +56,22 @@ function assertMainAgentOnly(ctx, action, review) {
   }
 }
 
+/** 递归收集目录下全部 `*.md`（#369 · KD-4：显式嵌套路径为合法 create 面 ⇒ 顶层平扫会欠计
+ *  ⇒ 复数情形漏判、默认定位可落非预期档）。只认真目录（`dirent.isDirectory()`——symlink 不入，
+ *  防环）；单目录读错按无候选处理（尽力面，同旧平扫）。 */
+function collectMarkdownFiles(dir, out = []) {
+  let entries = []
+  try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return out }
+  for (const e of entries) {
+    const abs = resolve(dir, e.name)
+    if (e.isDirectory()) collectMarkdownFiles(abs, out)
+    else if (e.isFile() && e.name.endsWith(".md")) out.push(abs)
+  }
+  return out
+}
+
 /**
- * depth-0 目标定位（D-BR21）：扫描全部基底根下 `*.md`，逐档读 §1 状态行判定 open
+ * depth-0 目标定位（D-BR21）：扫描全部基底根下 `*.md`（**递归**——#369），逐档读 §1 状态行判定 open
  * （readBatchStatusLine === "open"）。0 个 ⇒ throw（无在飞批）；恰 1 个 ⇒ 返回该档绝对路径；
  * ≥2 ⇒ throw（复数在飞批——必传 path，错误消息列出候选）。
  * 基底根数组由主档传入（batchDocBases——声明面单源，恒非空）；单根目录读错按无候选处理。
@@ -68,11 +83,7 @@ export function findInFlightBatch(cwd, bases) {
   void cwd
   const candidates = []
   for (const root of bases ?? []) {
-    let entries = []
-    try { entries = readdirSync(root) } catch { continue }
-    for (const name of entries) {
-      if (!name.endsWith(".md")) continue
-      const abs = resolve(root, name)
+    for (const abs of collectMarkdownFiles(root)) {
       let src
       try { src = readFileSync(abs, "utf8") } catch { continue }
       if (readBatchStatusLine(src) === "open") candidates.push(abs)
@@ -87,21 +98,13 @@ export function findInFlightBatch(cwd, bases) {
   return candidates[0]
 }
 
-/** create 路径越界判据（fix 轮 #12）：解析后须落在某一基底根之内；win32 大小写不敏感比较。 */
-function assertInsideBases(abs, bases, raw) {
-  const norm = (p) => (process.platform === "win32" ? p.toLowerCase() : p)
-  const target = norm(abs)
-  for (const b of bases) {
-    const root = norm(b)
-    if (target === root || target.startsWith(root.endsWith(sep) ? root : root + sep)) return
-  }
-  throw new Error(`batch: create path resolves outside the batch-record base roots — a batch record must live under the declared docRoot.batches base (fail-closed). Path: ${raw}`)
-}
+/** create 路径越界判据已迁 `batch-paths.mjs`（`resolveBatchCreatePath` 内含——§4.15 单源）。 */
 
 /**
  * create——建档（§4.11，仅 depth-0）。六段骨架一次预齐（骨架模板单源 = batchSkeleton），
  * 建档即过 gate（§1 占位状态行含「进行中」）；fail-closed：非 .md / 越基底 / 目标已存在 ⇒ throw
  * （不覆盖既有批档，BR-20）；目录缺失 ⇒ mkdir -p 后落位（BR-25）。不代建台账条目。
+ * 路径解析 = `resolveBatchCreatePath`（§4.15 单源：候选序首个落基底内者 / 锚定串只解析项目根形）。
  * F11-B：`source` **必填**（topic 同款空拒——骨架编制行实参化；不传 = 死占位残留必被 F11-C 拒
  * ⇒ create 即拒，不留死锁）；`prev` 传入值**幂等剥**「前情 = 」前缀（值规范化；默认值零变）。
  * @returns {string} 成功消息（含落盘绝对路径）
@@ -119,8 +122,7 @@ export function createBatchRecord({ args, ctx, review, cwd, bases, onWritten })
   if (!primary) {
     throw new Error("batch: no batch-record base root is available — fix PROJECT-MANIFEST.json docRoot.batches (or its default) before creating a record. Nothing was written.")
   }
-  const abs = isAbsolute(raw) ? resolve(raw) : resolve(primary, raw.replace(/\\/g, "/"))
-  assertInsideBases(abs, bases, raw)
+  const abs = resolveBatchCreatePath(cwd, raw, bases)
   if (readableFile(abs)) {
     throw new Error(`batch: create target already exists — refusing to overwrite an existing batch record (fail-closed, BR-20): ${raw}`)
   }
@@ -148,9 +150,10 @@ export function createBatchRecord({ args, ctx, review, cwd, bases, onWritten })
 
 /**
  * 段内状态行单行改写（status/close 共用——append-only 的唯一豁免，域限状态行）：
- * 定位 `## §N` 段（sectionHeaderRe 单源），段内找 STATUS_LINE_RE 行整行替换为
- * `**状态行**：<value>`；缺失则段首（标题行后）插状态行 + 空行。段界外字节零变；
- * EOL 形态（\r\n | \n）随档保持。段标题缺失 ⇒ throw（create 是骨架唯一权威入口）。
+ * 定位 `## §N` 段（sectionHeaderRe 单源），段内逐行扫描 STATUS_LINE_RE 首命中行原位替换
+ * （行尾随命中行自身）；缺失则标题行后偏移插入状态行 + 空行（插入块行尾 = 标题行自身
+ * 行尾——锚行后首二字节判读）。段界外字节零变（行切分 = /\r?\n/：EOL 形态无关）。
+ * 段标题缺失 ⇒ throw（create 是骨架唯一权威入口）。
  */
 function updateSectionStatusLine(src, seg, value) {
   const hdr = sectionHeaderRe(seg).exec(src)
@@ -161,13 +164,34 @@ function updateSectionStatusLine(src, seg, value) {
   nextRe.lastIndex = hdr.index + hdr[0].length
   const next = nextRe.exec(src)
   const endIdx = next ? next.index : src.length
-  const eol = src.includes("\r\n") ? "\r\n" : "\n"
-  const lines = src.slice(hdr.index, endIdx).split(eol)
   const line = `**状态行**：${value}`
-  const idx = lines.findIndex((l) => STATUS_LINE_RE.test(l))
-  if (idx >= 0) lines[idx] = line
-  else lines.splice(1, 0, line, "", "")
-  return src.slice(0, hdr.index) + lines.join(eol) + src.slice(endIdx)
+  const parts = src.slice(hdr.index, endIdx).split(/(\r?\n)/) // 保留分隔符（奇数下标 = 行尾）——替换只动命中行
+  const idx = parts.findIndex((p) => STATUS_LINE_RE.test(p))
+  if (idx >= 0) { parts[idx] = line } else {
+    const eol = parts[1] === "\r\n" ? "\r\n" : "\n" // 缺行插入块行尾 = 标题行自身行尾
+    if (parts.length === 1) parts.splice(1, 0, eol, line, eol, "", eol, "")
+    else parts.splice(2, 0, line, eol, "", eol, "", eol)
+  }
+  return src.slice(0, hdr.index) + parts.join("") + src.slice(endIdx)
+}
+
+/** §6 段体非空白内容判据（#422①——close 前闸：段头行余文（标题文本）不计入内容；
+ *  §6 段头缺失同判空——create 是骨架唯一权威入口）。 */
+function sectionSixHasContent(src) {
+  const hdr = sectionHeaderRe(6).exec(src)
+  if (!hdr) return false
+  const nextRe = /^## §\d/gm
+  nextRe.lastIndex = hdr.index + hdr[0].length
+  const next = nextRe.exec(src)
+  const body = src.slice(hdr.index + hdr[0].length, next ? next.index : src.length)
+  const nl = body.indexOf("\n") // 跳过段头行余文（`## §6 …` 的标题部分）
+  return (nl >= 0 ? body.slice(nl + 1) : "").trim() !== ""
+}
+
+/** §6 空闸拒绝句（#422①——空 ⇒ 拒 + 提示先写 §6；防「append 被拒 ⇒ close 照常 ⇒ §6 永久为空」
+ *  复发——2026-09-26 dispatch-sizing 批实证）。 */
+function emptySectionSixError() {
+  return "batch: §6 收口段为空（non-empty gate）— close refuses: the closeout section (§6) has no content, and closing would freeze the record with that section permanently empty. Write the section first (append §6: the closeout / verification summary), then call close again. Nothing was written."
 }
 
 /** 冻结门（§4.9——append/status 同门；close 视为写同样过门）：closed/unknown 的错误串与
@@ -178,7 +202,7 @@ function assertGateOpen(src) {
     throw new Error("batch: 已收口档不回改 — the record's §1 status line contains 「已收口」, so the record is frozen: its body is never written to again (整档冻结；改 = 新批新档). Nothing was written.")
   }
   if (gate === "unknown") {
-    throw new Error("batch: 状态行不可解析或缺失 — the record has no §1 `**状态行**：` line whose value contains 已收口 or 进行中 (fail-closed: the write is refused as if frozen). Nothing was written.")
+    throw new Error("batch: 状态行不可解析或缺失 — the record has no §1 `**状态行**：` line whose value contains 已收口 or 进行中 (fail-closed: the write is refused as if frozen). Nothing was written. Do NOT close the record after a refused append — nothing landed, and closing freezes the missing section for good (失败 ⇒ 勿 close).")
   }
 }
 
@@ -286,13 +310,20 @@ export function statusBatchRecord({ args, ctx, review, pickTarget, onWritten })
  * close——收口冻结（§4.13，仅 depth-0）。§1 状态行 →「已收口 <YYYY-MM-DD>」；此后该档
  * append/status 全拒（冻结判据唯一真值 = §1 行——§4.9 零语义变）。对已收口档再 close ⇒ 拒
  * （close 本身是对冻结档的写）。不代写 §6 内容、不替代台账核销事务。
+ * 前提三规则（#422）：① §6 非空闸（空 ⇒ 拒 + 提示先写 §6）；② 拒句含「失败 ⇒ 勿 close」
+ * （append/status 面——见 batch.mjs 与上方 assertGateOpen）；③ 无状态行档 ⇒ 自建机读位
+ * （updateSectionStatusLine 缺失即插——同路收口；「有行但不可解析」仍 fail-closed）。
  * @returns {string} 成功消息
  */
 export function closeBatchRecord({ args, ctx, review, pickTarget, onWritten }) {
   assertMainAgentOnly(ctx, "close", review)
   const abs = pickTarget(args?.path)
   const src = readFileSync(abs, "utf8")
-  assertGateOpen(src)
+  // #422③：§1 无状态行档 ⇒ 自建机读位（下行走 updateSectionStatusLine 缺失即插——同路收口）；
+  // 「有行但不可解析」维持 fail-closed（assertGateOpen 拒——防误冻结）。
+  if (readBatchStatusLine(src) !== "open" && sectionHasStatusLine(src, 1)) assertGateOpen(src)
+  // #422①：§6 非空闸（空 ⇒ 拒 + 提示先写 §6）——防「append 被拒 ⇒ close 照常 ⇒ §6 永久为空」复发。
+  if (!sectionSixHasContent(src)) throw new Error(emptySectionSixError())
   const date = todayLocal()
   const written = updateSectionStatusLine(src, 1, `已收口 ${date}`)
   writeFileSync(abs, written)

package/agent-tools/batch-paths.mjs

@@ -0,0 +1,186 @@
+/**
+ * agent-tools/batch-paths.mjs — 批次档相对路径解析**单源**（`BATCH-RECORD.md` §4.15 · 台账 #287 · 2026-09-25 批）。
+ *
+ * 四处调用点全部经本档：create（`resolveBatchCreatePath`）· append / status / close 与评审门
+ * （`resolveBatchDocPath`——读面抛错形）· spawn 门（`resolveBatchReadPath`——读面非抛形）。
+ *
+ * 契约（§4.15 逐字）：**候选序** = cwd → 项目根 → 逐基底（基底 = `batchDocBases` 声明面单源）；
+ * **判据分野** = 读面取首个**可读**文件 / create 取首个**落基底根内**者；**锚定防嵌套** = 串以任一基底的
+ * 「项目根相对前缀」打头且前缀后为**路径段边界** ⇒ 只解析项目根形（不二次拼接；不落基底内 ⇒ fail-closed）；
+ * **歧义锚**（条 5 · 2026-10-02 · #828）= create 按目标所属项目落基底 ∥ 无所属显式拒；读面候选腿追加；
+ * 在飞 ∥ 写门基底集 = 候选并集（`batchDocBases`）；**零变面** = 绝对路径照旧、三个错误文案逐字、
+ * 「参数在 + 路径可读」判据句、`ok` / `none` 两态。
+ *
+ * 依赖（KD-4 单向）：本档为**叶档**——只 import `node:*` 与 `../manifest.mjs`；主档 re-export 保既有面。
+ */
+import { existsSync, statSync } from "node:fs"
+import { isAbsolute, relative, resolve, sep } from "node:path"
+
+import { docRootBase, docRootPaths, owningProject, projectRootView, readManifest, resolveProjectRoot } from "../manifest.mjs"
+
+/** 可读文件判据（存在且为文件——目录 / 缺失同判不可读）。 */
+function readableFile(abs) {
+  try { return existsSync(abs) && statSync(abs).isFile() } catch { return false }
+}
+
+/** 歧义锚候选（判定单点 = `projectRootView`——`ambiguous` 态 ⇒ 候选全列**按名排序**；余者 null）。 */
+function ambiguousCandidates(cwd) {
+  const view = projectRootView(cwd ?? process.cwd())
+  return view.state === "ambiguous" ? view.candidates : null
+}
+
+/** 路径同一性比较（win32 大小写不敏感——同越基底判据口径）。 */
+function samePath(a, b) {
+  return process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b
+}
+
+/** 「项目根」取根单源（§4.15 条 1——归属 ∨ 发现，无 manifest ⇒ `resolve(cwd ?? ".")` 兜底且**单值**）：
+ *  同式 = 台账库键 / 写门指针基准的同一子表达式（`design/LEDGER.md` §6.1 口径 2）。 */
+export function batchProjectRoot(cwd) {
+  return resolveProjectRoot(cwd) ?? resolve(cwd ?? ".")
+}
+
+/** manifest **声明基底**（声明面；manifest 缺失 / 非法 / 读错 ⇒ 空集——v1 单基底语义零变）。 */
+function declaredBases(cwd) {
+  const base = cwd ?? process.cwd()
+  let man = { ok: false }
+  try { man = readManifest(base) } catch { /* 读错 → 按无 manifest 处理（回退默认基底） */ }
+  return man.ok ? docRootPaths(man.manifest?.docRoot?.batches, base) : []
+}
+
+/** 批次档基底根数组（**声明面单源**——create / 在飞扫描 / 锚定判据共用）：manifest `docRoot.batches`
+ *  （串 | 多根数组）→ 声明基底；缺失 / 非法 ⇒ 回退默认基底 `"docs/batches"`（恒返回非空数组）。
+ *  **歧义锚**（条 5）⇒ 候选项目基底**并集**（候选按名排序、并集保序）——在飞扫描 / 写门基底集同取此值。
+ *  @param {string} cwd
+ *  @returns {string[]} */
+export function batchDocBases(cwd) {
+  const amb = ambiguousCandidates(cwd)
+  if (amb) {
+    const union = []
+    for (const c of amb) for (const b of batchDocBases(c)) if (!union.includes(b)) union.push(b)
+    return union
+  }
+  const roots = declaredBases(cwd)
+  return roots.length ? roots : [resolve(docRootBase(cwd), "docs/batches")]
+}
+
+/** 基底的项目根相对前缀（归一 `/`；基底不落项目根下 / 与前缀重合 ⇒ 不产前缀——前缀不匹配者不做启发式改写）。 */
+function basePrefixes(cwd, bases) {
+  const root = batchProjectRoot(cwd)
+  const out = []
+  for (const b of bases) {
+    const rel = relative(root, resolve(b)).replace(/\\/g, "/")
+    if (!rel || rel === ".." || rel.startsWith("../") || isAbsolute(rel)) continue
+    out.push(rel)
+  }
+  return out
+}
+
+/** 锚定判据（**按路径段**——前缀后须为 `/` 或串尾；`docs/batches-old/<x>.md` 不锚定，BR-35）。 */
+function anchoredPrefix(p, prefixes) {
+  for (const pre of prefixes) if (p === pre || p.startsWith(pre + "/")) return pre
+  return null
+}
+
+/** 越基底判据（create 面）：解析后须落在某一基底根之内；win32 大小写不敏感比较。 */
+function insideBases(abs, bases) {
+  const norm = (p) => (process.platform === "win32" ? p.toLowerCase() : p)
+  const target = norm(abs)
+  return bases.some((b) => {
+    const root = norm(b)
+    return target === root || target.startsWith(root.endsWith(sep) ? root : root + sep)
+  })
+}
+
+/** create 越基底（原文案逐字——零变面）。 */
+const outsideBasesError = (raw) => new Error(`batch: create path resolves outside the batch-record base roots — a batch record must live under the declared docRoot.batches base (fail-closed). Path: ${raw}`)
+/** create 锚定但落基底外（§4.15 新文案逐字——不二次拼接）。 */
+const anchoredEscapeError = (raw) => new Error(`batch: create path is anchored at a batch base root but does not resolve under the declared docRoot.batches root(s) — refusing to nest it (fail-closed). Path: ${raw}`)
+/** 歧义锚 create 拒面（**文案逐字** = `BATCH-RECORD.md` §4.15 条 5——机检锚 `ambiguous session anchor`）。 */
+const ambiguousCreateError = (raw, candidates) => new Error(`batch: ambiguous session anchor — create target "${raw}" belongs to no candidate project; pass an explicit project path (e.g. "${candidates[0]}/docs/batches/<file>.md"). Candidates: ${candidates.join(", ")}`)
+
+/** 歧义锚读面候选腿（条 5）：逐候选项目——项目根形（`resolve(candidate, p)`）∥ 声明基底形
+ *  （候选按名排序、并集保序——「首个可读」在此即为确定判读）。 */
+function ambiguousReadLegs(cwd, p) {
+  const amb = ambiguousCandidates(cwd)
+  if (!amb) return []
+  const out = []
+  for (const c of amb) {
+    out.push(resolve(c, p))
+    for (const b of declaredBases(c)) out.push(resolve(b, p))
+  }
+  return out
+}
+
+/**
+ * **读面**解析（append / status / close 与评审门 / spawn 门共用）：首个**可读**候选胜；无 ⇒ null
+ * （调用方各自抛既有文案）。锚定串只解析项目根形（跳过 ①③——已含基底相对前缀者不再二次拼接）。
+ * @param {string} cwd 会话锚（缺省 → 进程 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)), ...ambiguousReadLegs(base, p)]
+  for (const abs of candidates) if (readableFile(abs)) return abs
+  return null
+}
+
+/**
+ * 批次档路径门禁（评审侧 `BATCH-RECORD.md` §4.2 口径 = **「若传则须可读」**）：空 / 非字符串 / 不可读 → throw。
+ * 非空且可读 → 返回绝对路径（`\` 归一——照 `files` / `batchDoc` spawn 门先例）。错误文案逐字零变（零回归硬约束）。
+ */
+export function resolveBatchDocPath(cwd, given) {
+  const base = cwd ?? process.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.`)
+}
+
+/**
+ * **create 面**解析（§4.15 条 2/3）：绝对路径照旧取用（仍过越基底判据）；相对路径 = 候选序中首个**落基底
+ * 根内**者（新档不存在——可读性无判别力）；锚定串只解析项目根形，不落基底内 ⇒ fail-closed 新文案。
+ *  **歧义锚**（条 5）：目标所属项目（`owningProject`）∈ 锚候选集 ⇒ 基底 = 该项目声明面（落其基底内；
+ *  越出 ⇒ 既有 fail-closed）；无所属 ⇒ **显式拒**（列候选 + 显式路径指引——不静默落锚）。
+ * @param {string} cwd 会话锚
+ * @param {string} given create `path` 原值
+ * @param {string[]} bases 已解析的基底根数组（`batchDocBases` 单源；调用方传入以免重复读档）
+ * @returns {string} 落位绝对路径
+ */
+export function resolveBatchCreatePath(cwd, given, bases) {
+  const base = cwd ?? process.cwd()
+  const raw = String(given ?? "").trim()
+  const p = raw.replace(/\\/g, "/")
+  let roots = bases
+  const amb = ambiguousCandidates(base)
+  if (amb) {
+    const owner = owningProject(isAbsolute(raw) ? resolve(raw) : resolve(base, p))
+    if (!owner || !amb.some((c) => samePath(c, owner))) throw ambiguousCreateError(raw, amb)
+    roots = batchDocBases(owner)
+  }
+  if (isAbsolute(raw)) {
+    const abs = resolve(raw)
+    if (!insideBases(abs, roots)) throw outsideBasesError(raw)
+    return abs
+  }
+  if (anchoredPrefix(p, basePrefixes(base, roots))) {
+    const abs = resolve(batchProjectRoot(base), p)
+    if (!insideBases(abs, roots)) throw anchoredEscapeError(raw)
+    return abs
+  }
+  for (const abs of [resolve(base, p), resolve(batchProjectRoot(base), p), ...roots.map((b) => resolve(b, p))]) {
+    if (insideBases(abs, roots)) return abs
+  }
+  throw outsideBasesError(raw)
+}