@thincoder/core 0.9.5 → 0.10.2

package/agent-tools/async-settle.mjs

@@ -43,7 +43,8 @@ import { refillAdvisorQueue } from "./advisor-async.mjs"
 /**
  * 载体字段读取吸收（#94——「VSC 的跨 runAgent 存活载体面按核内结构归一」）：
  * §2.3 载体口径 = `_asyncSubagents` · `_asyncAdvisors` · `_consultSessions` ·
- * `_pendingAsyncResults` · `_suspended`（AGENT-LOOP.md §2.3 seam 表）。
+ * `_pendingAsyncResults` · `_suspended`（AGENT-LOOP.md §2.3 seam 表）；#9 后台任务池
+ * `_bgTasks` 同列（写侧父字段 + 借用/别名 history——见 `bash-async.mjs` `ensureBgPool`）。
  * CLI 形：字段直接挂 agent（跨 run 存活）；VSC 形：字段挂 depth-0 `history`
  * （agent per-run 重建——run 起始把 history 容器绑到 agent 字段，绑定不变式）。
  * 本函数吸收两形为同一读取：父对象字段优先，缺字段回退 `parent.history`。
@@ -91,7 +92,7 @@ export function tombstoneOf(parent, id) {
 /**
  * 条目 controller 链到基信号单点（#98 VSC 侧并入——interrupt 豁免面；原 subagent-run /
  * advisor-async / escalate-async / consult 四处逐字同构）：
- * - 基信号**已 aborted** 且非 interrupt ⇒ 立即 abort（reason 逐跳保留——§20.3 站点 #10）；
+ * - 基信号**已 aborted** 且非 interrupt ⇒ 立即 abort（reason 逐跳保留——AGENT-LOOP-SUBAGENT.md §6.12 站点 #10）；
  * - interrupt aborted（Ctrl+I——中断消息注入后同回合续跑）⇒ **不逐链中止**（池保留；
  *   子代理 / 评审继续跑完，settle 照常注入——「Ctrl+I keeps the pool」意图对齐）；
  * - 未来 abort ⇒ 非 interrupt 才逐链传播（Stop / 会话中止全停语义不变）。
@@ -111,11 +112,12 @@ export function bindChildController(ctrl, baseSignal) {
 // ─── D1 池 accessor（吸收双池）────────────────────────────────────────────────
 
 /** 池 accessor（D1）：role "advisor" → `_asyncAdvisors`（独立评审池——无队列独立调度）·
- *  role "consult" → `_consultSessions`（会话池）· 其余 → `_asyncSubagents`（子代理/飞刀
- *  共享槽位队列池）。载体经 `carrierField` 吸收（#94）；未初始化返 null——调用方以
- *  `?? new Map()` / 可选链处置。 */
+ *  role "consult" → `_consultSessions`（会话池）· role "bg" → `_bgTasks`（#9 后台 bash
+ *  任务池）· 其余 → `_asyncSubagents`（子代理/飞刀共享槽位队列池）。载体经 `carrierField`
+ *  吸收（#94）；未初始化返 null——调用方以 `?? new Map()` / 可选链处置。 */
 export function getAsyncPool(parent, role) {
-  const field = role === "advisor" ? "_asyncAdvisors" : role === "consult" ? "_consultSessions" : "_asyncSubagents"
+  const field = role === "advisor" ? "_asyncAdvisors" : role === "consult" ? "_consultSessions"
+    : role === "bg" ? "_bgTasks" : "_asyncSubagents"
   return carrierField(parent, field) ?? null
 }
 
@@ -155,7 +157,7 @@ export function buildChildSignal(parent, ctx) {
 // ─── D3 settle 共享 helper ───────────────────────────────────────────────────
 
 /**
- * §23.3.1 消化窗口持有释放（TUI-OOM-ROOTCAUSE——D-SM2 表 2 候选 1）：注入完成后置空条目
+ * AGENT-LOOP.md §6.15 消化窗口持有释放（TUI-OOM-ROOTCAUSE——D-SM2 表 2 候选 1）：注入完成后置空条目
  * 对子代理对象的引用（`childAgent`/`report`——条目前此从不显式释放，挂起期 = 分钟级驻留）。
  * 幂等（重入不抛）；池内/挂起未消化窗口语义零变（settle 时刻不释放——表 2 候选 2 否决：
  * status/observe 在窗口内仍读 child 摘要）。三消费点（回合尾收集 / run 起始 pending 注入 /
@@ -178,10 +180,10 @@ export function releaseSettledEntry(entry) {
  *   ③ 分流：cancelled（出池 + cancelled 墓碑 + ⟦ev⟧stopped + 族提醒——不入 pending）→
  *      parentAborted（守卫抑制——不落事件不入流——中止清池在回合尾/挂起中止统一做）→
  *      settled（族 onAccounting hook 记账 → 挂起期（或 consult 族恒停靠）移交 pending
- *      单容器 + 出池 + ⟦ev⟧settled；回合内 ⟦ev⟧done 留池 done:true）；
+ *      单容器 + 出池，非挂起期留池 done:true；两态一律 ⟦ev⟧settled——⟦ev⟧done = 消费面补发）；
  *   ④ 公共尾部：settleSeq 递增 + `_settle` 唤醒 waiter + 腾槽补位（subagent/escalate 族
  *      恒补——settle/cancel 释放槽 → maybeRefillAsync + refreshQueuedTokens——AGENT-LOOP.md
- *      §10 "settle/cancel 释放槽后…启动到槽满"；advisor 经 refillAdvisorQueue 补位
+ *      AGENT-LOOP-SUBAGENT.md §6.9 "settle/cancel 释放槽后…启动到槽满"；advisor 经 refillAdvisorQueue 补位
  *      （ED-4——评审池有排队语义后不再豁免）；consult（会话池）豁免）。
  * opts（设计签名 `{pool, onAccounting}` + 实现参数 ctx）：
  * - pool：条目所在池 Map（出池 delete 目标；consult 传 null——会话池无条目）。
@@ -193,7 +195,7 @@ export function releaseSettledEntry(entry) {
  *   设计偏差注（advisor code review 发现——交付报告同步）：设计 D3 把 maybeRefillAsync
  *   归入 onAccounting hook（仅 settled 分支执行）——running 取消的 cancelled 分支将不再
  *   补位（槽释放但 queued 头停滞——挂起会话无回合尾补位覆盖），违背既有不变式
- *   （AGENT-LOOP.md §10 + subagent-scheduler maybeRefillAsync 文档 "called from every
+ *   （AGENT-LOOP-SUBAGENT.md §6.9 + subagent-scheduler maybeRefillAsync 文档 "called from every
  *   settle"）与 VSC 镜像（无条件 refill）。修正：腾槽补位移入公共尾部（subagent/escalate
  *   族恒补——旧行为零回归；advisor/consult 豁免——同 VSC refill!==false 语义）。
  */
@@ -235,7 +237,7 @@ export function settleAsyncEntry(parent, entry, opts = {}) {
     // AGENT-LOOP-SUBAGENT.md §6.7.2 cancelled settle 分支（D-M6）：不入 pending、不参与回合尾直注入——清池 +
     // 终态墓碑（dependsOn 取消语义）+ ⟦ev⟧stopped 冻结 + 族提醒（半成品警示对模型可见）。
     pool?.delete(String(entry.id))
-    writeTombstone(parent, entry.id, "cancelled", role) // §20 D-SD5：单点写入（#94 载体吸收）
+    writeTombstone(parent, entry.id, "cancelled", role) // AGENT-LOOP-SUBAGENT.md §6.9 D-SD5：单点写入（#94 载体吸收）
     ctx?.callbacks?.onToken?.(`${entry.relayPrefix}⟦ev⟧stopped\x1e0\x1e0\x1estopped\x1e`)
     if (role === "advisor") {
       // ②-6b：评审取消——token 未签发提醒（settleAdvisorRun 不消费预算）。
@@ -249,7 +251,7 @@ export function settleAsyncEntry(parent, entry, opts = {}) {
         content: `[System reminder: async escalate #${entry.id} (${entry.tag}) cancelled by user — partial changes not merged/audited]`,
       })
     } else {
-      // §20 D-SD5：running 依赖取消——提醒列出依赖者（供模型决策）。
+      // §6.9 D-SD5：running 依赖取消——提醒列出依赖者（供模型决策）。
       const dependents = dependentLabels(parent, String(entry.id))
       const autoNote = parent.autoApprove
         ? " — AUTO session: they auto-start on slot availability (round2 #3)"
@@ -264,22 +266,23 @@ export function settleAsyncEntry(parent, entry, opts = {}) {
     // escalate 腾槽补位）——可改写 entry.report（settle 分支输出——digest 原样进）。
     onAccounting?.(parent, entry)
     // 挂起分流（AGENT-LOOP-ASYNC-POOL.md §6.8 D-S8 + D-S3 记账——以读取时刻为准）：挂起期 settle → 移交 pending
-    // 单容器（digest 注入）+ 出池 + ⟦ev⟧settled 驻留；回合内 → ⟦ev⟧done 立即冻结
-    // （条目留池——done-in-pool 统一表示——回合尾 collectSettledAsync 注入）。
+    // 单容器（digest 注入）+ 出池；非挂起期 ⇒ 留池 done-in-pool（回合尾 collectSettledAsync 注入兜底 ∥
+    // 挂起会话 sweep 消费链照旧）。
     // consult 族恒停靠（settle 即出会话池入 pending——无 TUI 冻结事件——子块各自冻结）。
     if (suspended || role === "consult") {
       parkAsyncPending(parent, entry)
       pool?.delete(String(entry.id))
-      ctx?.callbacks?.onToken?.(`${entry.relayPrefix}⟦ev⟧settled\x1e0\x1e0\x1esettled\x1e`)
-    } else {
-      ctx?.callbacks?.onToken?.(`${entry.relayPrefix}⟦ev⟧done\x1e0\x1e0\x1edone\x1e`)
     }
+    // 发射单点（块到达时点归位批 · #746｜§6.8「settle 延迟冻结（两态统一）」）：settle 一律 ⟦ev⟧settled
+    // （区块头恒中间态「done · awaiting digestion」驻留面板）；⟦ev⟧done = 消费面补发（消费窗清单单源
+    // = §6.8）⇒ 冻结 ∥ 归档恒落消费时点——回合运行中零归档触发器（「S 不夹运行中回合」结构不变式）。
+    ctx?.callbacks?.onToken?.(`${entry.relayPrefix}⟦ev⟧settled\x1e0\x1e0\x1esettled\x1e`)
   }
   // ④ 公共尾部：settleSeq 递增 + _settle 唤醒（never rejects）+ 唤醒挂起驱动 waiter
   entry._settleSeq = (parent._asyncSettleSeq = (parent._asyncSettleSeq ?? 0) + 1)
   entry._settle?.()
   wakeAsyncWaiters(parent) // §6.27.12.4 ①：挂起驱动唤醒单点（settle 尾 / 上行 ask 入队尾两处调用）
-  // §20 D-SD4 释放点：settle/cancel 释放槽 + 依赖终态转移 → 补位（依赖满足者/域冲突
+  // §6.9 D-SD4 释放点：settle/cancel 释放槽 + 依赖终态转移 → 补位（依赖满足者/域冲突
   // 解除者自动启动——槽 ≤4）→ 排队态面板刷新（等待块头标注随终态更新——dependency
   // cancelled / 位置前移）。subagent/escalate 族恒补（旧行为零回归——cancelled 分支
   // 同样补位）；advisor（ED-4——独立评审池的排队语义）经 refillAdvisorQueue 补位；

package/agent-tools/audit-block.mjs

@@ -9,7 +9,7 @@
  */
 
 /**
- * §18.7 D-TS5 (A2): mechanically summarize the parent spawn task book for the
+ * AGENT-LOOP-SUBAGENT.md §6.7.6 D-TS5 (A2): mechanically summarize the parent spawn task book for the
  * audit spawn — the three audit-relevant elements VERBATIM (design doc paths /
  * affected-file list / acceptance criteria); verbose context/background is
  * dropped (the auditor can read the design docs themselves — they stay
@@ -70,8 +70,8 @@ export function summarizeEngTaskBook(taskInput) {
 export function buildAuditBlock(ctx) {
   const touched = (ctx.agent._touchedFiles ?? []).map((f) => `- ${f}`).join("\n") || "- (none yet)"
   return `[Audit scope — mechanical context, independent of the eng-coder's self-report:]\n` +
-    // §18.7 D-TS4 A1：审计指令模板（四类偏差 + 范围限制 + 校验清单格式）——审计语义
-    // 不再靠模型自悟；范围限制是 §18.5 D-AG3 声明（下方 Zero-git scope authority）
+    // §6.7.6 D-TS4 A1：审计指令模板（四类偏差 + 范围限制 + 校验清单格式）——审计语义
+    // 不再靠模型自悟；范围限制是 §6.7.4 D-AG3 声明（下方 Zero-git scope authority）
     // 的同源一句指注，不重复声明。
     `[Audit instructions — mechanical template:]\n` +
     `You are auditing an eng-coder delivery against its approved design — audit for EXACTLY these four deviation categories:\n` +
@@ -83,21 +83,21 @@ export function buildAuditBlock(ctx) {
     `workspace changes not listed there are unrelated to this delivery and are NOT grounds for an out-of-list finding.\n` +
     `Scope discipline (F-TS6 A1): read ONLY the audited files and the design-doc sections relevant to this delivery — do NOT re-read whole documents.\n` +
     `Every deviation item MUST be fieldized: file:line + design reference (doc path + section/AC id) + severity + evidence (quoted code or doc text).\n` +
-    // §18.7 D-TS5 A2：任务书从全量 verbatim 改机械摘要块（三要素逐字——排除冗长上下文）。
+    // §6.7.6 D-TS5 A2：任务书从全量 verbatim 改机械摘要块（三要素逐字——排除冗长上下文）。
     `[Parent spawn task book — mechanical summary: design docs + affected-file list + acceptance criteria verbatim; verbose context/background dropped — the design docs are still available for reading outside this input:]\n` +
     `${summarizeEngTaskBook(ctx.agent._engTaskInput)}\n` +
     `Files actually touched by the eng-coder (mechanical union — audit these against the file list):\n${touched}\n` +
     // §18.5 D-AG3（2026-09-04）：审计零 git 范围权威声明——本审计任务零 git（不注入
-    // git 上下文——§18.5 全角色零 git）；_touchedFiles 为审计范围；工作区未列于
+    // git 上下文——§6.7.4 全角色零 git）；_touchedFiles 为审计范围；工作区未列于
     // _touchedFiles 的改动与本任务无关，不作超清单依据（VS Code auditTaskBook 同款措辞）。
     "Zero-git scope authority: this audit task receives NO git context — nothing is injected. " +
     "The evidence base is the design documents, the current disk state (read/glob/grep), and the _touchedFiles list above. " +
     "Workspace changes NOT listed in _touchedFiles are unrelated to this delivery — they are NOT grounds for an out-of-file-list finding." +
-    // §18.13 D-A1.2：审计预算句——A1 指令模板 + A2 摘要块之后、A3 报告模板之前（定序——评审 #7）。
+    // §6.7.6 D-A1.2：审计预算句——A1 指令模板 + A2 摘要块之后、A3 报告模板之前（定序——评审 #7）。
     // 逐字设计锚（D-A1.2 代码块）：只读该读的——10 轮机械预算——超时报 PROBLEM 下结论。
     // 前导 \n 与 A3 同款块分隔约定（上一句 Zero-git 句末无换行——不触碰既有句）。
     `\n[Audit budget — mechanical]: read ONLY the touched files listed above and the design-doc sections the parent task book names (affected-files table, acceptance criteria, status line). Do NOT read whole documents. Budget = 10 tool rounds max — if you cannot conclude within it, report PROBLEM (inconclusive) rather than continuing to explore.\n` +
-    // §18.7 D-TS6 A3：审计输出报告格式模板（三态——字段化行——不让模型自由发挥）。
+    // §6.7.6 D-TS6 A3：审计输出报告格式模板（三态——字段化行——不让模型自由发挥）。
     `\n[Audit report format — mechanical template:]\n` +
     `Report EXACTLY one of three states:\n` +
     `- CLEAN — no deviation across the four categories: reply the line "Four deviation categories: none found." (四类偏差均未发现);\n` +

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

@@ -19,7 +19,7 @@ import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSy
 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"
@@ -56,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——声明面单源，恒非空）；单根目录读错按无候选处理。
@@ -69,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)
@@ -140,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)
@@ -153,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 的错误串与
@@ -170,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).")
   }
 }
 
@@ -278,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)