@thincoder/core 0.9.5 → 0.10.2

package/agent-tools/subagent-run.mjs

@@ -2,9 +2,11 @@
  * subagent-run.mjs — async spawn 执行器 executeAsyncSpawn（2026-09-05 module-split：
  * subagent.mjs 726 > 500 硬限——execute 的 async 分支 verbatim 迁入（闭包变量参数化：
  * parent/ctx/role/args + buildSpawnChild 产物），语义零变——subagent.mjs execute 调
- * 用（只此一处）；§20 补位/排队刷新仍来自 subagent-scheduler.mjs。
+ * 用（只此一处）；AGENT-LOOP-SUBAGENT.md §6.9 补位/排队刷新仍来自 subagent-scheduler.mjs。
  */
 
+import { createHash } from "node:crypto"
+import { basename } from "node:path"
 import { ASYNC_POOL_LIMITS, poolDomainOf, poolLimitsFor, runningPoolCount } from "./subagent-async.mjs"
 import { runChildPipeline } from "./subagent-async.mjs"
 import { logEvent } from "../log.mjs"
@@ -15,6 +17,12 @@ import {
 } from "./subagent-scheduler.mjs"
 // ASYNC-RESULT-CONTAINER.md D3/D6：settle 公共收尾单点 + child signal 构建单点
 import { bindChildController, buildChildSignal, settleAsyncEntry } from "./async-settle.mjs"
+import { registerTurnCapCheckpoint } from "./checkpoint.mjs"
+
+/** #309 任务书文本摘要（12 hex——**不留全文**，NF-L3 同族）：条目自携与双点留痕的标识面。 */
+function taskSeal(text) {
+  return createHash("sha256").update(String(text ?? "")).digest("hex").slice(0, 12)
+}
 
 /**
  * SUBAGENT-OBSERVE-SEND D2：注入队列回合边界消费核心——把 entry._injected 全部消息按普通
@@ -32,12 +40,12 @@ export function drainInjectedQueue(entry, agent) {
 }
 
 /**
- * Async branch (AGENT-LOOP.md §15 D-A1/D-A6): spawn without waiting.
+ * Async branch (AGENT-LOOP-SUBAGENT.md §6.7.3 D-A1/D-A6): spawn without waiting.
  * The child runs the EXACT blocking pipeline (runChildPipeline — relay /
  * turn-cap / permission / MIN_REPORT_CHARS / mergeChildMutations all unchanged),
  * but the parent does not await it: the promise is parked in _asyncSubagents and
  * consumed by the auto channel (AGENT-LOOP-SUBAGENT.md §6.7.5 — turn-end collection / suspension digest;
- * the check action is gone). Slot queue (§11.1 D-24a/R14 — 分域): the entry carries a
+ * the check action is gone). Slot queue (AGENT-LOOP-ASYNC-POOL.md §6.10 — D-24a/R14 分域): the entry carries a
  * pool domain (_pool = poolDomainOf(role)); running count < limit[its domain]
  * (agent.poolLimits — default engCoder 4 / other 4) → start now; ≥ → enqueue
  * (status "queued", position = queue index) — never rejected, never requiring the
@@ -57,7 +65,7 @@ export function executeAsyncSpawn(parent, ctx, role, args, child, input, childOp
   consumeSubagentToken(parent, id, "async spawn", role)
   const entry = {
     id, role, relayPrefix,
-    // §11.1 D-24a/R14：池域字段（域判定单一事实源——poolDomainOf——role 枚举见
+    // AGENT-LOOP-ASYNC-POOL.md §6.10 D-24a/R14：池域字段（域判定单一事实源——poolDomainOf——role 枚举见
     // subagent.mjs ROLES；未知角色归 other）——running 计数/补位按域过滤。
     _pool: poolDomainOf(role),
     status: "queued", // 下面按等待态/槽位重定（避免两处判断漂移）
@@ -73,19 +81,27 @@ export function executeAsyncSpawn(parent, ctx, role, args, child, input, childOp
     // AGENT-LOOP-SUBAGENT.md §6.7.2 D-M6 (round2 #2)：条目级 AbortController——cancel 定向 abort 本
     // 条目（runAgent signal 链）；Ctrl+C 全停语义不变（基信号 abort 逐链传播）。
     controller: null,
-    // §20 D-SD2 域元数据（AGENT-LOOP.md §20）：running ∪ queued 条目全带——
+    // D-SD2 域元数据（AGENT-LOOP-SUBAGENT.md §6.9）：running ∪ queued 条目全带——
     // _files（归一化绝对路径）/ _dependsOn（字符串 id）——冲突检测与补位判据
     // 的事实源；无调度参数 spawn 两字段皆空（legacy——不参与冲突检测——零改动）。
     _files: files,
     _dependsOn: dependsOn,
+    // #309（AGENT-LOOP-SUBAGENT.md §6.29.2——可诊断性）：条目**自携**绑定档与任务书摘要
+    // （启动路径按条目闭包取值——入队/补位不再有第二个取值面）；`child:spawn` / `child:start`
+    // 双点同键面留痕（基名 + 摘要，零内容）——事后可对账「哪条任务书在哪个 id 下起跑」。
+    _batchDoc: child?._batchDoc ?? null,
+    _taskSeal: taskSeal(input),
     _lastQueuedSig: null, // ⟦ev⟧queued 去重 sig（refreshQueuedTokens）
     // SUBAGENT-OBSERVE-SEND D2：父侧 send 注入队列——父 action:'send' push 消息，子
     // 回合边界经 consumeInjected 回调消费（drain + pushReal 成 user 回合）；settle 收尾
     // 时仍残留 = 未投递（消息入队后子在下一回合边界前 settle）→ 附 settle 报告提示。
     _injected: [],
   }
-  // §20 D-SD3 准入落点：等待态（依赖未满足/域冲突/depc）→ queued（waiting-deps——
-  // 不占槽不启动——即使槽空）；纯槽满（kind slot）→ 按域计数判定（§11.1 D-24a：
+  // 留痕面基名（零内容——§6.29.2）：绑定档绝对路径 → 基名；无绑定（非工程族）⇒ null（字段不落）。
+  const batchDocBase = entry._batchDoc ? basename(entry._batchDoc) : null
+
+  // AGENT-LOOP-SUBAGENT.md §6.9 D-SD3 准入落点：等待态（依赖未满足/域冲突/depc）→ queued（waiting-deps——
+  // 不占槽不启动——即使槽空）；纯槽满（kind slot）→ 按域计数判定（§6.10 D-24a：
   // runningIn(domain) < limit(domain)——跨域互不阻塞——每次入池判定时读配置）。
   const blockers = describeBlockers(parent, entry)
   if (blockers.kind === "slot") {
@@ -102,7 +118,7 @@ export function executeAsyncSpawn(parent, ctx, role, args, child, input, childOp
   // D6 buildChildSignal 单点（ASYNC-RESULT-CONTAINER.md）。
   const ctrl = new AbortController()
   entry.controller = ctrl
-  // §20.3 站点 #10（第 24 批）：hop 逐跳保 reason；#98 链结单点（interrupt 豁免面——
+  // AGENT-LOOP-SUBAGENT.md §6.12 站点 #10（第 24 批）：hop 逐跳保 reason；#98 链结单点（interrupt 豁免面——
   // Ctrl+I 不逐链中止池内子代理）。
   bindChildController(ctrl, buildChildSignal(parent, ctx))
   // AGENT-LOOP-SUBAGENT.md §6.7.2 D-M5：turn 镜像拦截层（callbacks 包装层——在既有
@@ -118,7 +134,7 @@ export function executeAsyncSpawn(parent, ctx, role, args, child, input, childOp
       }
       return parentOnToken(t)
     }
-    // §27 R23 D-R23c1：嵌套 wrapper 标记随镜像层透传（wrapChildCallbacks 产物带
+    // docs/cli/design/TUI.md §6.8.2 R23 D-R23c1：嵌套 wrapper 标记随镜像层透传（wrapChildCallbacks 产物带
     // _relayPrefix——本层重包后丢失会让异步子代理（默认 async——depth-0）内嵌 spawn
     // 的生成侧补发射失效（emitNestedChildEvent 判据）——同步复制标记保语义）。
     trackOpts.onToken._relayPrefix = parentOnToken._relayPrefix ?? null
@@ -128,7 +144,7 @@ export function executeAsyncSpawn(parent, ctx, role, args, child, input, childOp
     entry.position = undefined
     entry.startedAt = Date.now()
     // AGENT-LOOP-SUBAGENT.md §6.7.2 D-SF1（round3 #1）：绑定子代理对象引用——绑定时刻 = 实际启动时
-    // （queued 条目 spawn-ack 时刻尚无子代理对象——§20 D-SD3b）；绑定对象 = 子代理
+    // （queued 条目 spawn-ack 时刻尚无子代理对象——§6.9 D-SD3b）；绑定对象 = 子代理
     // 对象（不是 _touchedFiles 数组引用——per-run 记账在 prepareRun 重置——数组
     // 引用会陈旧——对象引用保证 status 查询时实时读——杀前一刻最新）。
     entry.childAgent = child
@@ -147,19 +163,18 @@ export function executeAsyncSpawn(parent, ctx, role, args, child, input, childOp
     ctx.callbacks?.onToken?.(relayPrefix + "⟦ev⟧async\x1e")
     // Deferred [model] emit: the TUI block is created at ACTUAL start.
     ctx.callbacks?.onToken?.(relayPrefix + "[model]" + (childProvider.model ?? ""))
-    // Turn-cap on background children NEVER pops the continue panel (D-A3):
-    // §15 D-A3 exception (2026-09-02 unified rule, AGENT-LOOP.md §2): in an
-    // engineering && AUTO session the child auto-resumes — the user authorized
-    // unattended runs, no one is at the panel. Every other tier auto-declines
-    // and the partial-work report carries the cap reason. §18 D-E2 relies on
-    // this exception as the turn-cap fallback for the default-async eng-coder
-    // delivery (the internal protocol does not raise the 100-turn cap).
+    // #309 §6.29.2 双点留痕第二点（条目**实际启动点**——与 child:spawn 同键面）：哪条任务书在哪个 id 下起跑。
+    logEvent("child:start", { role, id: `${role}#${id}`, batchDocBase, taskSeal: entry._taskSeal })
+    // Turn-cap on background children no longer auto-resumes (TURN-CAP-CONTINUE.md §1 #7 · 2026-09-26):
+    // a capped async child registers a parent-side checkpoint and stays suspended
+    // (no panel, no re-dispatch) until the parent answers send / cancel — AUTO included.
+    // The partial-work report carries TURN_CAP_MARK when the cap stopped the run.
     runChildPipeline(child, input, trackOpts, { ...childRunOpts, signal: entry.controller.signal, consumeInjected }, {
       parent, role, args,
-      askContinue: () => Promise.resolve(Boolean(parent.config?.agent?.engineering && parent.autoApprove)),
+      askContinue: (e) => registerTurnCapCheckpoint(child, entry, { turn: e.turn, signal: entry.controller.signal }),
     })
       .then((report) => { entry.report = report })
-      // §20.3 第 3 条合成器（第 24 批）：原 message 前缀逐字保留 + 来源后缀
+      // §6.12 第 3 条合成器（第 24 批）：原 message 前缀逐字保留 + 来源后缀
       .catch((err) => { entry.error = deathLine(err, entry.controller?.signal) })
       .finally(() => {
         // SUBAGENT-OBSERVE-SEND D3（send→settle 竞态）：settle 收尾时 _injected 仍残留
@@ -187,11 +202,11 @@ export function executeAsyncSpawn(parent, ctx, role, args, child, input, childOp
   parent._asyncSubagents.set(String(id), entry)
   // LOGGING（LOGGING.md）：child:spawn（async——注册即事件；status 记 queued/running 分流；
   // 实际启动由补位 start() 触发——运行中由子内 llm/tool 事件可见）
-  logEvent("child:spawn", { role, id: `${role}#${id}`, kind: "async", status: entry.status, ms: 0 })
+  logEvent("child:spawn", { role, id: `${role}#${id}`, kind: "async", status: entry.status, ms: 0, batchDocBase, taskSeal: entry._taskSeal })
   if (entry.status === "queued") {
     parent._asyncQueue.push(entry)
     entry.position = parent._asyncQueue.length
-    // §20 D-SD3b：排队 spawn 返回即建面板 waiting 块（⟦ev⟧queued 事件——spawn 侧
+    // §6.9 D-SD3b：排队 spawn 返回即建面板 waiting 块（⟦ev⟧queued 事件——spawn 侧
     // 发——TUI routeSubToken 消费建块/更新头；启动后 ⟦ev⟧async 转 running——同 key
     // 不重建）。refreshQueuedTokens 同时校正既有排队条目的位置/等待态头。
     refreshQueuedTokens(parent, ctx.callbacks?.onToken)

package/agent-tools/subagent-scheduler.mjs

@@ -1,9 +1,9 @@
 /**
- * subagent-scheduler.mjs — §20 子 agent 任务调度器 + 文件域组（2026-09-05 自
- * subagent-async.mjs 拆分——Module Split Policy §20.9——纯迁移零行为变化——
- * AGENT-LOOP.md §20 D-SD1..SD5 + §21.1 D-SL1 环形死锁修正）。
+ * subagent-scheduler.mjs — 子 agent 任务调度器 + 文件域组（2026-09-05 自
+ * subagent-async.mjs 拆分——Module Split Policy——纯迁移零行为变化——
+ * AGENT-LOOP-SUBAGENT.md §6.9 D-SD1..SD5 + D-SL1 环形死锁修正）。
  * 内容：normalizeFileList / filesOverlap / effectiveFiles（SCHEDULER-DYNAMIC-DOMAIN
- * 动态域——声明 ∪ running touched）/ depInfo / describeBlockers / detectStall（§21.1
+ * 动态域——声明 ∪ running touched）/ depInfo / describeBlockers / detectStall（
  * P-SL2 停滞机械检测）/ queueRunnable / assertNoDepCycle / dependentLabels /
  * refreshQueuedTokens / maybeRefillAsync。
  * ASYNC_POOL_LIMITS/poolLimitsFor/runningPoolCount 回引自 subagent-async.mjs（主体保有——
@@ -24,7 +24,7 @@ import { poolLimitsFor, runningPoolCount, ASYNC_POOL_LIMITS } from "./subagent-a
 import { carrierField, getAsyncPool, tombstoneOf } from "./async-settle.mjs"
 
 // ═══════════════════════════════════════════════════════════════════════════
-// §20 子 agent 任务调度器（AGENT-LOOP.md §20——D-SD1..SD5 + 20.4 处置注）
+// 子 agent 任务调度器（AGENT-LOOP-SUBAGENT.md §6.9——D-SD1..SD5）
 // 池条目域元数据（D-SD2：entry._files/_dependsOn——running ∪ queued 全带）、准入
 // （D-SD3：域冲突/依赖未满足 → queued 等位）、补位扫描（D-SD4：最早可启动——
 // 依赖全满足 + 域无冲突——waiting 越行不阻塞 slot 位）、释放规则（D-SD5——round2
@@ -35,14 +35,14 @@ import { carrierField, getAsyncPool, tombstoneOf } from "./async-settle.mjs"
 
 /** 文件域归一化（round1 #5——路径归一化再交集）：相对 cwd 解析为绝对路径 + 去重；
  *  非字符串/空项静默跳过（声明错误 = false-negative 明示风险——v1 边界）。
- *  §20.8 D-F1.1（2026-09-04）：目录声明检测——fail-closed——尾斜杠形态 / 指向既有目录
+ *  D-F1.1（2026-09-04）：目录声明检测——fail-closed——尾斜杠形态 / 指向既有目录
  *  → throw（含路径——错误字符串英文定稿）——目录声明静默绕过冲突检测的通道闭合；
  *  调用方（subagent.mjs spawn 入口）catch → 错误即工具结果（模型可见——无静默）。
- *  已知限制（§20.8 未编号段——评审 #4）：不存在的目录声明（无尾斜杠 + 目录未创建）仍通过——不处理。
- *  §28 R26 F-R26b（2026-09-07）：父侧维护文件黑名单——归一化后 basename 全名匹配 +
+ *  已知限制（评审 #4）：不存在的目录声明（无尾斜杠 + 目录未创建）仍通过——不处理。
+ *  R26（2026-09-07）：父侧维护文件黑名单——归一化后 basename 全名匹配 +
  *  大小写不敏感（todo.md/changelog.md 精确——路径任意层含 docs/、根、.thincoder/）——
  *  命中 → throw（fail-closed——先于调度器准入——无排队残留——错误即工具结果）；
- *  提示列出全部违规条目——英文模板逐字定稿（AGENT-LOOP.md §28）。
+ *  提示列出全部违规条目——英文模板逐字定稿（AGENT-LOOP-SUBAGENT.md §6.9「父侧文件拦截（R26）」）。
  *  M5 F6（2026-09-17）：黑名单随同迁入 spawn-gates.mjs（rejectEngineeringFilePaths——族 = ledger.db / CHANGELOG + scripts/**；老台账 md 族随 M2 退役）——本函数只留调用（错误文案逐字保留）。 */
 export function normalizeFileList(files, cwd) {
   const out = []
@@ -102,7 +102,7 @@ export function effectiveFiles(e) {
 }
 
 /**
- * §20 依赖终态查询（单点事实——池条目 / pending（挂起期 settle 移交——注入前）/
+ * AGENT-LOOP-SUBAGENT.md §6.9 依赖终态查询（单点事实——池条目 / pending（挂起期 settle 移交——注入前）/
  * 终态墓碑（自动通道注入消费——consumed；取消/失败——D-SD5 分支））：
  * - ok      = settle 成功（报告已产出）/ consumed（自动通道注入消费——T-SD14 视为满足）
  * - pending = running/queued 未终态（等启动/等完成）
@@ -131,7 +131,7 @@ export function depInfo(parent, id) {
   return { state: "unknown", role: null }
 }
 
-/** §20 等待态派生（无存储——refill/status/面板/spawn 返回同一事实源）。kind：
+/** AGENT-LOOP-SUBAGENT.md §6.9 等待态派生（无存储——refill/status/面板/spawn 返回同一事实源）。kind：
  *  - slot = 无阻塞（依赖全满足 + 域无冲突）——纯槽满等位（可启动——等 slot）
  *  - wait = 依赖未完成 / 域冲突（running ∪ queued——D-SD3 同界——self 除外）
  *  - depc = 依赖取消/失败（round2 #3——非 AUTO 锁住——需父显式处置；AUTO 视为可启动）
@@ -159,7 +159,7 @@ export function describeBlockers(parent, entry) {
       const hitDeclared = filesOverlap(myFiles, e._files ?? [])
       const hit = hitDeclared ?? filesOverlap(myFiles, effectiveFiles(e))
       if (!hit) continue
-      // §21.1 D-SL1.2（环形死锁修正——与 queueRunnable 同界——展示一致）：后入
+      // AGENT-LOOP-SUBAGENT.md §6.9 D-SL1.2（环形死锁修正——与 queueRunnable 同界——展示一致）：后入
       // 者（spawn 序晚于我——数字 id 比较）不列——只列"会真正阻断我的"（running
       // 任意序 + 先入 queued）；列后入者 = 误导"等一个其实等不到的人"。
       if (e.status === "queued" && Number(e.id) > Number(entry.id)) continue
@@ -176,7 +176,7 @@ export function describeBlockers(parent, entry) {
   return { kind: "slot", detail: "" }
 }
 
-/** §21.1 P-SL2（D-SL2——混合边环形等待停滞机械检测——AGENT-LOOP.md §21.1 扩展注）：
+/** P-SL2（D-SL2——混合边环形等待停滞机械检测——AGENT-LOOP-SUBAGENT.md §6.9）：
  * 判据（收窄——零误报优先——宁可漏报不可误打断）：池内 running = 0 && queued ≥ 2 &&
  * 无 dependency-cancelled 标记条目 && 每 queued 的 blocker（files 冲突者 + 未 settle
  * 依赖目标——与 describeBlockers/queueRunnable 同界——"真正会阻断我的"语义：files 只
@@ -185,7 +185,7 @@ export function describeBlockers(parent, entry) {
  * 条目一条阻塞链——沿首个 blocker 走到首个重复节点（闭环）——每节点自带"等谁 + 为何等"
  * 理由注（`X（reason） → Y` 形态——X 等 Y 因 reason）；不满足 → null。
  * 不报（F-SL2.2 收窄判据）：running 锚点存在（依赖链/文件串行正常排队）；depc 滞留
- * （外部决策可解——§20 NF-SD 滞留有意——cancel 先入者即释放）；单 queued；blocker
+ * （外部决策可解——§6.9 NF-SD 滞留有意——cancel 先入者即释放）；单 queued；blocker
  * 外逃（unknown 依赖目标/池外条目）；blocker 空（runnable——settle/cancel 驱动 refill
  * 会启动——非停滞）。自然流程中 wait 边恒指向先入者（依赖必须先前 spawn——unknown 拒 +
  * 文件冲突只阻断后入者——id 序）——混合环仅人工注入可构造（T-SD5 同族防御断言）——
@@ -239,7 +239,7 @@ export function detectStall(parent) {
   }
   // 链组装：每 queued 条目一条——沿首个 blocker 走到首个重复节点（闭环）——每节点
   // 自带"我等谁 + 为何等"段（`X（reason） → Y`——本节点 blocker 理由注于本节点旁——
-  // 读取无歧义：X 等 Y 因为 reason——dependsOn 边不误读为目标属性——§21.1 扩展注
+  // 读取无歧义：X 等 Y 因为 reason——dependsOn 边不误读为目标属性——§6.9 扩展注
   // 示例同信息形态——闭环以起始节点重复闭合（末节点不再注——闭合自明）。
   const chains = []
   for (const start of queued) {
@@ -271,10 +271,10 @@ export function entryTerminal(entry) {
   return entry?.cancelled === true || entry?.done === true
 }
 
-/** §20 D-SD4 补位判据：依赖全满足（AUTO 下 depc 放行）+ 域无冲突（running 任意序 +
- *  queued 先入者——§21.1 D-SL1.1 序判定：同文件串行 = 先入者先启动、后入者等先入者
+/** AGENT-LOOP-SUBAGENT.md §6.9 D-SD4 补位判据：依赖全满足（AUTO 下 depc 放行）+ 域无冲突（running 任意序 +
+ *  queued 先入者——§6.9 D-SL1.1 序判定：同文件串行 = 先入者先启动、后入者等先入者
  *  ——不自锁；先入者启动后以 running 身份继续挡住后入者——self 除外）。
- *  已知限制（§21.1 评审 #4——与 §20 NF-SD 同语义——滞留有意义不静默）：先入者被
+ *  已知限制（§6.9 评审 #4——与 §6.9 NF-SD 同语义——滞留有意义不静默）：先入者被
  *  depc 锁定时（依赖取消/失败且非 AUTO——永不自动启动），后入者滞留等它——cancel
  *  先入者即释放（父显式可清；AUTO 档 depc 视为可启动——不滞留）。 */
 export function queueRunnable(parent, entry) {
@@ -292,7 +292,7 @@ export function queueRunnable(parent, entry) {
       if (e === entry) continue
       if (e.status !== "running" && e.status !== "queued") continue
       if (!filesOverlap(myFiles, effectiveFiles(e))) continue // 动态域：声明 ∪ running touched
-      // §21.1 D-SL1.1 序判定：queued 仅"先入者"（spawn 序早于我——数字 id 比较）阻断；
+      // §6.9 D-SL1.1 序判定：queued 仅"先入者"（spawn 序早于我——数字 id 比较）阻断；
       // 后入者不阻断——先入者先启动——两个 queued 同文件不再互等（环形死锁修正）。
       // 防御（评审 #3——id 形态）：池条目 id 为数字递增（_subAgentCounter——已核实）；
       // 异常形态 Number() 得 NaN → 比较 false → 不跳过 → 保守阻断（宁可多等——
@@ -304,7 +304,7 @@ export function queueRunnable(parent, entry) {
   return true
 }
 
-/** §20 D-SD5 环防御（round2 #5——自然流程不可达：unknown id 拒 + spawn 序天然无环——
+/** §6.9 D-SD5 环防御（round2 #5——自然流程不可达：unknown id 拒 + spawn 序天然无环——
  *  仅人工向池注入可构造——防御断言定位）：从新 spawn 的依赖集出发沿池内条目
  *  _dependsOn 边做路径 DFS——路径上重复访问（可达环）→ 拒绝（A→B→A 永不自启——
  *  错误明确——T-SD5）。运行/排队条目皆可成环节点；池小（≤4 槽 + 有限队列）深度有限。 */
@@ -337,7 +337,7 @@ export function dependentLabels(parent, depId) {
   return out
 }
 
-/** §20 D-SD3b 排队态面板刷新（⟦ev⟧queued 事件族——TUI routeSubToken 消费）：对全部
+/** §6.9 D-SD3b 排队态面板刷新（⟦ev⟧queued 事件族——TUI routeSubToken 消费）：对全部
  *  queued 条目重算等待态并发射变化（去重 sig——kind/position/detail 全变才发）——
  *  调用点 = 一切队列突变与等待态变迁（spawn 入队 / settle 后补位与依赖转移 / cancel
  *  出队 / 自动通道消费）。position = 队列序（D-A1 既有——cancel 前移同源）。
@@ -362,12 +362,11 @@ export function refreshQueuedTokens(parent, onToken) {
 }
 
 /**
- * Slot-queue refill (AGENT-LOOP.md §15 D-A1/D-A6 + §20 D-SD4 + §11.1 D-24a/R14 分域):
+ * Slot-queue refill (AGENT-LOOP-SUBAGENT.md §6.7.3 D-A1/D-A6 + §6.9 D-SD4 + AGENT-LOOP-ASYNC-POOL.md §6.10 D-24a/R14 分域):
  * start queue heads while a running slot is free — called from every settle
- * (completion frees a slot) and from the turn-end collection's refill loop. §20：
- * 队列现可混合 waiting-deps 与 slot-queued——扫描选"依赖全满足 + 域无冲突"的最早
+ * (completion frees a slot) and from the turn-end collection's refill loop. 队列现可混合 waiting-deps 与 slot-queued——扫描选"依赖全满足 + 域无冲突"的最早
  * 条目启动（waiting 越行不阻塞槽位；多任务同时解除按 queued 序逐个启动）。
- * §11.1 D-24a（R14）：槽位判定按域——条目 _pool 域内 running 数 < 该域上限才启动
+ * D-24a/R14（分域）：槽位判定按域——条目 _pool 域内 running 数 < 该域上限才启动
  * （同域仍 4——纯单域队列行为与旧 shift 完全一致；跨域总量 8——各域独立腾槽，
  * 互不阻塞）。配置每次补位时读（poolLimitsFor——变更即生效下个补位）。
  */
@@ -397,13 +396,15 @@ export function maybeRefillAsync(parent) {
  * next = max(counter ?? 0, poolMax) + 1——取号后 counter 同步（首取号初始化）。id 作用
  * 域 = 进程内（不做槽持久化——reload 后池清块消失，新进程从 1 无冲突——设计范围边界）。
  * spawn（subagent-spawn.mjs async 分支）、escalate（escalate-async.mjs）、async-advisor
- * 池（advisor-async.mjs——§11.2 跨池共号）共用；executeAsyncSpawn 直读 counter（分配与
+ * 池（advisor-async.mjs——§6.10 跨池共号）、**后台 bash 任务池**（bash-async.mjs——#9：
+ * `_bgTasks` 同入扫描域——VSC 形计数器不随 run 存活，缺此扫描会与在途 bg 条目撞号）共用；
+ * executeAsyncSpawn 直读 counter（分配与
  * 消费同步——无 await 间隙）。CLI 两池键均为字符串（set(String(id))——解析分支防御保留）。
  * @returns {number} 全池唯一的下一 id（单调——进程内）
  */
 export function nextSubagentId(parent) {
   let poolMax = 0
-  for (const pool of [carrierField(parent, "_asyncSubagents"), carrierField(parent, "_asyncAdvisors")]) {
+  for (const pool of [carrierField(parent, "_asyncSubagents"), carrierField(parent, "_asyncAdvisors"), carrierField(parent, "_bgTasks")]) {
     if (!pool || pool.size === 0) continue
     for (const k of pool.keys()) {
       const n = typeof k === "number" ? k : Number.parseInt(k, 10)

package/agent-tools/subagent-spawn.mjs

@@ -1,7 +1,7 @@
 /**
  * subagent-spawn.mjs — spawn 路径装配（2026-09-05 module-split：subagent.mjs 726
  * > 500 硬限——spawn 前置 helpers（effectiveSubagentModel/resolveDesignSlot——审计块
- * 构造器 2026-09-22 起另立 ./audit-block.mjs）+ §20 调度参数准入（prepareScheduling）+ child 装配
+ * 构造器 2026-09-22 起另立 ./audit-block.mjs）+ AGENT-LOOP-SUBAGENT.md §6.9 调度参数准入（prepareScheduling）+ child 装配
  * （buildSpawnChild）verbatim 迁入（仅闭包变量参数化），语义零变；executeAsyncSpawn
  * 另在 subagent-run.mjs。subagent.mjs execute 经本文件 import 调用。
  * 2026-09-07：executeConsumeDesignAction 消费执行器（token 链终消费制——与 spawn 侧
@@ -11,12 +11,13 @@
  * （`child._spawnSystemBlock` 单点绑定——消费点 = 核 `prepareRun`），`input` 只留任务书。
  */
 
+import { basename, isAbsolute, relative } from "node:path"
 import {
   createAgent,
   readonlyToolNames, escapeXml, excludeSubagentTools,
 } from "../agent.mjs"
 import { allocRelay, wrapChildCallbacks, relayPrefixOf } from "../agent/spawn-child.mjs"
-// TUI-OOM-ROOTCAUSE（AGENT-LOOP.md §23.3.1）：子代理人读线窗口常量单源（store 零依赖）。
+// TUI-OOM-ROOTCAUSE（AGENT-LOOP.md §6.15）：子代理人读线窗口常量单源（store 零依赖）。
 import { RECORD_WINDOW_MESSAGES } from "../session-store.mjs"
 import { validateDesignToken } from "./advisor.mjs"
 import { tokenExpired, removeDesignTokenSlot, reconcileEngTokensFromSlot, persistEngTokens } from "../token-ttl.mjs"
@@ -33,7 +34,35 @@ import { validateTaskBookFields } from "./spawn-gates.mjs"
 import { buildAuditBlock } from "./audit-block.mjs"
 // 批次档路径解析单源（BATCH-RECORD.md §4.15 · 台账 #287）：门内解析改经叶档（读面非抛形），
 // 与 append / create 同源——门判据仍「参数在 + 路径可读」，错误文案逐字零变。
-import { resolveBatchReadPath } from "./batch-paths.mjs"
+import { resolveBatchReadPath, batchDocBases } from "./batch-paths.mjs"
+// LOGGING（LOGGING.md）：#309 形三观测留痕走同一事件通道。
+import { logEvent } from "../log.mjs"
+
+/** #309 任务书 token 判据（`AGENT-LOOP-SUBAGENT.md` §6.29.3）：`.md` 结尾的连续路径型字面
+ *  （含盘符形态——裸名 `AGENTS.md` 无分隔符且非绝对，见调用点过滤）。 */
+const MD_PATH_TOKEN = /[A-Za-z0-9_@.:\\/-]+\.md\b/g
+
+/** #309 形三·task↔batchDoc 观测留痕（§6.29.3——**不阻断**，spawn 照常放行）：任务书文本提及
+ *  **他批存在档** ⇒ `logEvent` 留痕一条（键面 = 两侧基名，零任务书内容）；只提绑定档 / 无路径型
+ *  `.md` 字面 ⇒ 零事件。token 逐条经 `resolveBatchReadPath` 解析（路径单源），命中 = 可读 ∧
+ *  落基底内 ∧ ≠ 绑定档（同一档多 token 按解析后绝对路径去重）。 */
+function logBatchDocRefs(parent, role, task, boundAbs) {
+  const cwd = parent?.cwd ?? process.cwd()
+  const text = typeof task === "string" ? task : ""
+  const key = (p) => (process.platform === "win32" ? p.toLowerCase() : p)
+  const bases = batchDocBases(cwd) // 歧义锚 ⇒ 候选项目基底并集（#828——入基底判据覆盖面随之对齐）
+  const seen = new Set()
+  for (const m of text.matchAll(MD_PATH_TOKEN)) {
+    const token = m[0]
+    if (!/[/\\]/.test(token) && !isAbsolute(token)) continue // 裸名（AGENTS.md 形态）不取
+    const abs = resolveBatchReadPath(cwd, token)
+    if (!abs || key(abs) === key(boundAbs ?? "")) continue // 不可读 / 就是绑定档 ⇒ 零事件
+    const inBase = bases.some((b) => { const r = relative(b, abs); return r && !r.startsWith("..") && !isAbsolute(r) })
+    if (!inBase || seen.has(key(abs))) continue // 他 .md 引用（设计档 / 需求档等）/ 同档重复
+    seen.add(key(abs))
+    logEvent("child:batchdoc-ref", { role, batchDocBase: basename(boundAbs ?? ""), refBase: basename(abs) })
+  }
+}
 
 /**
  * Effective subagent model override for a role (CLI parity shared with VS Code):
@@ -76,7 +105,7 @@ export function resolveDesignSlot(parent, designIdArg) {
     const rec = reconcileEngTokensFromSlot(parent)
     if (rec && rec !== slots) slots = rec
   }
-  // F2d (§29.1): both refusal branches carry the HELD id list — after a
+  // F2d: both refusal branches carry the HELD id list — after a
   // persistence restore the parent has no digest to look the id up in; the error
   // list is the only discovery path (ids are not credentials — the token is).
   const size = slots instanceof Map ? slots.size : 0
@@ -145,14 +174,14 @@ export function executeConsumeDesignAction(args, ctx) {
   return `design slot consumed — designId ${designId ?? "(single-design session)"} is closed out; a further eng-coder spawn for this design is mechanically rejected, and any new work (including deviation fixes) requires a fresh advisor(type='design') review and token.`
 }
 
-// ── §20 spawn 调度参数准入（AGENT-LOOP.md §20 D-SD1/D-SD3 + 20.4 round2 #5/#7）──
+// ── spawn 调度参数准入（AGENT-LOOP-SUBAGENT.md §6.9 D-SD1/D-SD3）────────────
 // files/dependsOn 声明即契约（v1：不做任务书文本自动解析——不可靠）。缺省（两者皆
 // 缺）= 既有语义零改动（不参与冲突检测/无校验——legacy spawn 零开销直通）。
 // 校验序：参数形态 → 依赖 unknown id（非 consumed 墓碑——T-SD10）→ 依赖环可达
 // （T-SD5——防御断言：自然流程不可达）→ 等待态判定。判定结果：wait/depc 阻塞 →
 // async 入 queued 等位（spawn 返回带 reason——D-SD3b）；**sync spawn（async:false）
 // 命中阻塞 → 明确错误——不队列化 sync——sync 语义零变更（round2 #7——T-SD13）**。
-/** §20 准入（参数化提取——2026-09-05 module-split）：返回归一化 { files, dependsOn }。
+/** 准入（参数化提取——2026-09-05 module-split）：返回归一化 { files, dependsOn }。
  *  filesRaw 目录声明 fail-closed（检测器 throw → 错误即工具结果 JSON）。 */
 export function prepareScheduling(parent, filesRaw, dependsRaw, wantAsync) {
   const files = []
@@ -192,7 +221,7 @@ export function prepareScheduling(parent, filesRaw, dependsRaw, wantAsync) {
 }
 
 /**
- * §20 准入通过后的 child 装配（2026-09-05 module-split——自 execute 参数化提取，
+ * AGENT-LOOP-SUBAGENT.md §6.9 准入通过后的 child 装配（2026-09-05 module-split——自 execute 参数化提取，
  * 原 318-488 段 verbatim——语义零变）。副作用保留：relay 取号（sync 支 allocRelay——
  * `[model]` 出生声明归 SYNC-CANCEL 单点，#133）/ 子代理 _logId / _engTaskInput 携带 /
  * _spawnSystemBlock 绑定（台账 #23——spawn 固块单点）全部在此发生。返回阻塞/异步两路径共用的
@@ -218,6 +247,8 @@ export function buildSpawnChild(parent, ctx, args, role, wantAsync, files, depen
     if (!given) throw refusal()
     batchDocAbs = resolveBatchReadPath(parent.cwd ?? process.cwd(), given)
     if (!batchDocAbs) throw refusal(" (given path is not a readable file)")
+    // #309 形三：任务书中的他批批次档引用观测留痕（不阻断——放行不受影响）。
+    logBatchDocRefs(parent, role, args.task, batchDocAbs)
   }
 
   // M5 F2（ENGINEERING-MODE-V2-MODULE-DELEGATION §2.2）：任务书六强制字段门——
@@ -308,19 +339,19 @@ export function buildSpawnChild(parent, ctx, args, role, wantAsync, files, depen
     overlay,
     role,
   })
-  // TUI-OOM-ROOTCAUSE（AGENT-LOOP.md §23.3.1）：子代理人读线窗口置位（常量单源
+  // TUI-OOM-ROOTCAUSE（AGENT-LOOP.md §6.15）：子代理人读线窗口置位（常量单源
   // session-store.mjs）——机制复用主 agent 同路径（context.mjs pushReal 驱逐）；
   // 每个 child 原先各自一份永不压缩的 _fullHistory（勘察 C2 乘数面）。
   child._historyWindow = RECORD_WINDOW_MESSAGES
 
   // BATCH-RECORD.md §2 批次档段写入通道绑定（第 4 批）：工程角色（eng-coder/eng-designer）把批次档
-  // 绝对路径记在 child 上——setup 挂载 batch_segment 时读它。无路径参数的工具靠这条
+  // 绝对路径记在 child 上——setup 挂载 `batch` 时读它。无路径参数的工具靠这条
   // 绑定决定目标档（spawn 门已保证「参数在 + 路径可读」）。
   if (engineeringRole) child._batchDoc = batchDocAbs
 
   // Token-verified design review → child is authorized to modify files without re-reviewing
   if (role === "eng-coder") child._engDesignReviewed = true
-  // §18 D-E3 task-domain authorization: approved design + spawn task = authorization.
+  // AGENT-LOOP-SUBAGENT.md §6.7.6 D-E3 task-domain authorization: approved design + spawn task = authorization.
   // The child's OWN tools skip ONLY the onPermissionRequest ask (autoApprove
   // equivalent — dispatch.mjs permission stage); every other gate (JSON parse /
   // unknown tool / planMode / design-token) still applies (T-E14). Non-eng-coder
@@ -335,7 +366,7 @@ export function buildSpawnChild(parent, ctx, args, role, wantAsync, files, depen
     child._engDesignId = args.designId ?? null
   }
 
-  // §18.5 子代理零 git（D-AG1——2026-09-04 用户裁定）：explore/plan 一律不注入
+  // §6.7.4 子代理零 git（D-AG1——2026-09-04 用户裁定）：explore/plan 一律不注入
   // git 上下文——子代理证据链 = 任务书 ∪ 磁盘当前状态（read/glob/grep）∪（审计时）
   // _touchedFiles，无一项来自 git；注入的全工作区脏状态快照与任务域无关，会误导
   // 审计/探索（"status 里这个文件算不算超清单？"）。注入分支整体删除（B 方案
@@ -354,7 +385,7 @@ export function buildSpawnChild(parent, ctx, args, role, wantAsync, files, depen
   // 本行让子代理"拿到本档路径"）。行文不含 summarizeEngTaskBook 的三组段 marker
   // （Docs involved / Files list / Acceptance criteria）——段匹配不受影响。仅工程角色注入。
   if (engineeringRole) spawnBlocks.push(`Batch record (batchDoc): ${batchDocAbs}`)
-  // §18 D-E2 ③ (round4 #4, T-E13/T-E15): an eng-coder audit spawn's task book is
+  // AGENT-LOOP-SUBAGENT.md §6.7.6 D-E2 ③ (round4 #4, T-E13/T-E15): an eng-coder audit spawn's task book is
   // the eng-coder's OWN spawn task — mechanically kept as _engTaskInput by the
   // parent spawn and injected as the D-TS5 A2 mechanical summary (design docs /
   // affected-file list / acceptance criteria verbatim, verbose context dropped)
@@ -371,10 +402,10 @@ export function buildSpawnChild(parent, ctx, args, role, wantAsync, files, depen
   if (spawnBlocks.length > 0) child._spawnSystemBlock = spawnBlocks.join("\n\n")
 
   // Relay content/reasoning/tool/output to the parent TUI via the unified spawn-child
-  // pipeline (AGENT-LOOP.md §7.2 D3). Prefix includes a unique id: parallel child agents
+  // pipeline (AGENT-LOOP-SUBAGENT.md §6.7.2 D3). Prefix includes a unique id: parallel child agents
   // with the same role stay independent and don't overwrite each other.
   // Format: role#id/  →  onToken("coder#2/writing..."), onToolCall("coder#2/read", args)
-  // Async id allocation (AGENT-LOOP.md §15 D-A1): reserve the relay counter at
+  // Async id allocation (AGENT-LOOP-SUBAGENT.md §6.7.3 D-A1): reserve the relay counter at
   // spawn time — the returned id must be stable while the item sits in the queue.
   // The [model] token (TUI block creation) is DEFERRED to actual start so queued
   // children don't paint an empty panel block ("queued 态不显示").