@thincoder/core 0.9.5 → 0.10.2

package/agent/suspension.mjs

@@ -9,7 +9,8 @@
  *
  * 载体注入（端差面 = 池 / pending / 标志挂谁）：`ctx.carrier` = 字段集按核内异步面
  * 现行口径的对象（`_asyncSubagents` · `_asyncAdvisors` · `_consultSessions` ·
- * `_pendingAsyncResults` · `_suspended`）——CLI 形 = `agent` 对象；VSC 形 = depth-0
+ * `_pendingAsyncResults` · `_suspended`；#9 后台 bash 任务池 `_bgTasks` 同列）
+ * ——CLI 形 = `agent` 对象；VSC 形 = depth-0
  * `history` 数组（附加属性不污染会话文件）。机制对载体零预设（空字段一律 `?.` 读）。
  *
  * 核内零文案、零渲染、零端名分支（契约 5 / 10）：状态行文本 / 提示行 / 消息族全在宿主侧，
@@ -18,7 +19,13 @@
  * ctx 接口（注入面）：
  *   - carrier           池 / pending / 标志载体（见上）
  *   - runTurn(text, opts)  回合执行器（digest = `("", { autoTurn: true })`；上行唤醒轮 =
- *                          `("", { autoTurn: true, upstreamTurn: true })`——旗标仅供域文本选择）
+ *                          `("", { autoTurn: true, upstreamTurn: true })`；timer 轮 =
+ *                          `("", { autoTurn: true, timerTurn: true })`——旗标仅供域文本选择）
+ *   - inputQueue        **opt-in** 宿主既有输入队列数组（增补 C）：驱动就地消费该数组——宿主
+ *                       其余入队 ∕ 读取面与驱动同一数组（零同步面）；缺省核内新建（既有宿主零变）
+ *   - takeInput(queue)  **opt-in** 取项缝（增补 C）：批次策略（富条目 / 合并批 / 消费回执行）
+ *                       归宿主；缺省 `shift`；返回 null/undefined ⇒ 本步零动作、落第 2 步
+ *                       （首动作不可消费的防御面——条目不消费留队）。可异步（宿主取项含动态 import）
  *   - abortSignal       会话中止信号（兜底监听 + abort 清场判据）
  *   - hooks.onCounts(counts)      计数变化通知（{ running, queued, pending, done }）
  *   - hooks.onDigest(phase, counts) 消化轮边界（start / end）
@@ -26,6 +33,11 @@
  *   - hooks.freezeAll()           退出冻结（兜底残项）
  *   - injectResidual(entry)       残余注入面（idle 退出清场；宿主装配端注入器——CLI =
  *                                 逐族注入分发 / VSC = pending 单容器注入器）
+ *   - timerFace        **opt-in** timer 面（§6.30.10）：`{ deadline(), deliver() }`——`deadline()`
+ *                      每轮步骤 4 现算（number|null；缺省 / null ⇒ 零注册，等待仍三态）；
+ *                      `deliver()` 到期兑现面（返回布尔 = 是否已交付；交付真 ⇒ timer 轮）。
+ *                      缺省不传 ⇒ 既有行为逐字等价（现宿主零传）。
+ *   - timer / clear    等待原语注入缝（缺省 `setTimeout` / `clearTimeout`——用例零真实等待）
  */
 
 import { parkAsyncPending } from "../agent-tools/async-settle.mjs"
@@ -42,11 +54,13 @@ function consultRunningChildren(carrier) {
 
 /** 后台池存活判据（D-S2/F5 口径——CLI 为准）：running/queued 的池条目，或已 settle 未注入
  * （pending 非空 = D-S3「未注入」），或运行中 consult children（会诊跨回合）。回合尾与每次
- * 轮末都评估退出。 */
+ * 轮末都评估退出。**#9 三域并入**：`_bgTasks`（后台 bash 任务）在途亦为 live——settle 经
+ * pending 停靠驱动消化轮（`bash-async.mjs` 恒停靠）。 */
 export function poolLive(carrier) {
   const sub = carrier?._asyncSubagents
   const adv = carrier?._asyncAdvisors
-  return (sub && sub.size > 0) || (adv && adv.size > 0)
+  const bg = carrier?._bgTasks
+  return (sub && sub.size > 0) || (adv && adv.size > 0) || (bg && bg.size > 0)
     || (carrier?._pendingAsyncResults?.length ?? 0) > 0
     || consultRunningChildren(carrier) > 0
 }
@@ -94,13 +108,17 @@ function consultLiveCount(carrier) {
 
 /**
  * 退出清场（单点——驱动 finally 与单测共用）：
- *  - abort：清池不注入（用户显式停——陈旧结果不回灌）+ 会诊会话清理标记；
+ *  - abort：**只清已死**（§6.20 口径——增补 D：`discardAbortedPool` ∕ `discardAbortedAdvisors`
+ *    单点，与核 run-stages 回合尾中止同式；存活 ∕ 已 settle 条目留池——settled 报告沿后续
+ *    回合边界注入到达，不静默丢）+ pending 单容器清 + 会诊会话清理标记；
  *  - idle：残余直注入（极端竞态残项——结果零丢失；注入器由宿主注入，缺省 no-op 保残项）。
  */
 export async function finishSuspension(carrier, { aborted = false, injectResidual = null } = {}) {
   if (aborted) {
-    carrier._asyncSubagents?.clear()
-    carrier._asyncAdvisors?.clear()
+    const { discardAbortedPool, discardAbortedAdvisors, discardAbortedBgTasks } = await import("../agent-tools/async-discard.mjs")
+    discardAbortedPool(carrier)
+    discardAbortedAdvisors(carrier)
+    discardAbortedBgTasks(carrier) // #9 收尾档②：后台 bash 任务逐条杀树 + 出池 + 墓碑（杀 ⟺ 控制器已中止）
     carrier._pendingAsyncResults = []
     if (carrier._consultSessions instanceof Map) {
       const { cleanupConsultSessions } = await import("../agent-tools/consult.mjs")
@@ -114,13 +132,19 @@ export async function finishSuspension(carrier, { aborted = false, injectResidua
   }
 }
 
-/** 等待下一次 settle（池 waiter——核内异步面 settle 尾部唤醒）或宿主唤醒（wake——用户输入）。
- *  双路单次兑现（settle / wake / aborted 三态，先到先得）；cleanup 摘除全部注册。 */
-function waitForSettleOrWake(carrier, abortSignal, latch) {
+/** 等待下一次 settle（池 waiter——核内异步面 settle 尾部唤醒）/ 宿主唤醒（wake——用户输入）/
+ *  **timer 到期**（opt-in——§6.30.10 等待第四态，与 settle / wake 同槽先到先得）。
+ *  `deadline != null` ⇒ 一次性注册（`unref()` 尽力——不阻断宿主退出）；缺省 / null ⇒ 三态逐字等价。
+ *  cleanup 摘除全部注册（含未触发句柄——尽力清）；到期兑现交循环支（本原语零交付语义）。 */
+function waitForSettleOrWake(carrier, abortSignal, latch, { deadline = null, timer = setTimeout, clear = clearTimeout } = {}) {
   return new Promise((resolve) => {
     let finished = false
+    let handle = null
     const cleanup = () => {
       latch.wake = null
+      const h = handle
+      handle = null
+      if (h !== null) { try { clear(h) } catch { /* 已触发 / 不可清——尽力面 */ } }
       const i = (carrier._asyncWaiters ?? []).indexOf(onSettle)
       if (i >= 0) carrier._asyncWaiters.splice(i, 1)
       abortSignal?.removeEventListener("abort", onAbort)
@@ -133,8 +157,14 @@ function waitForSettleOrWake(carrier, abortSignal, latch) {
     }
     const onSettle = () => finish("settle")
     const onAbort = () => finish("aborted")
+    const onTimer = () => finish("timer")
     ;(carrier._asyncWaiters ??= []).push(onSettle)
     latch.wake = () => finish("wake")
+    // opt-in deadline（§6.30.10 等待第四态）：无在途 / 未传 ⇒ 零注册（等待仍三态）。宿主不变式 = 到期即出列 / 关即 null（否则「已到期 ∧ 交付假」会 0ms 反复重注册）。
+    if (deadline != null) {
+      handle = timer(onTimer, Math.max(0, deadline - Date.now()))
+      try { handle?.unref?.() } catch { /* unref 失败不阻断 */ }
+    }
     if (abortSignal?.aborted) { onAbort(); return }
     abortSignal?.addEventListener("abort", onAbort, { once: true })
   })
@@ -143,17 +173,23 @@ function waitForSettleOrWake(carrier, abortSignal, latch) {
 /**
  * 启动挂起会话（同步返回句柄；宿主 `await handle.done` ⇒ `{ reason, residualInput }`）。
  *
- * 状态机行表（承 AGENT-LOOP.md §9/§7 行表）：
+ * 状态机行表（承 AGENT-LOOP-ASYNC-POOL.md §6.8 行表）：
  * 1. 用户输入优先（D-S5）：pendingInput 非空 → 以该消息开普通回合（`_suspended=false`）；
  * 2. pending 非空 或 存在未 drain 的 ask（`upstreamWaiting`）→ 合并消化轮 / 唤醒轮（auto-turn；
  *    注入由宿主 runTurn 首行完成——单注入点）；
  * 3. 池空（无 running / queued / 未注入）→ 自然退出；
- * 4. 等下一 settle / 宿主唤醒（handle.wake）。
+ * 4. 等下一 settle / 宿主唤醒（handle.wake）/ timer 到期（opt-in——兑现真 ⇒ timer 轮）。
  * 每轮消化 / 用户回合后：hooks.reclaim(consumed) 逐条回收（不等池空）。
  */
 export function startSuspension(ctx) {
-  const { carrier, runTurn, abortSignal = null, hooks = {}, injectResidual = null } = ctx
-  const pendingInput = []
+  const {
+    carrier, runTurn, abortSignal = null, hooks = {}, injectResidual = null,
+    timerFace = null, timer = setTimeout, clear = clearTimeout,
+    inputQueue = null, takeInput = null,
+  } = ctx
+  // 输入队列（增补 C）：宿主既有数组（VSC ∕ CLI 形——宿主其余读者与驱动同一数组）优先；
+  // 缺省核内新建（desktop 形——经 `pushInput` 入槽）。
+  const pendingInput = Array.isArray(inputQueue) ? inputQueue : []
   const latch = { wake: null }
   let finished = false
 
@@ -173,19 +209,23 @@ export function startSuspension(ctx) {
       while (true) {
         if (abortSignal?.aborted) { aborted = true; break }
         sweepSettledToPending(carrier)
-        // 1. 用户输入优先：单槽（至多一条待交接——宿主在 busy 期拒收提交）。
+        // 1. 用户输入优先（D-S5）：队列非空 → 取项缝（增补 C——缺省 `shift`；富条目 ∕ 合并批
+        //    由宿主 `takeInput` 实现）开普通回合（`_suspended=false`）；首动作不可消费
+        //    （`takeInput ⇒ null`）⇒ 本步零动作、条目不消费，落第 2 步。
         if (pendingInput.length > 0) {
-          const head = String(pendingInput.shift())
-          const afterRun = consumedByRun()
-          carrier._suspended = false // 用户回合 = 普通回合语义（settle 即冻结 + 回合尾直注入）
-          try {
-            await runTurn(head)
-          } finally {
-            carrier._suspended = true
+          const item = takeInput ? await takeInput(pendingInput) : pendingInput.shift()
+          if (item != null) {
+            const afterRun = consumedByRun()
+            carrier._suspended = false // 用户回合 = 普通回合语义（settle 即冻结 + 回合尾直注入）
+            try {
+              await runTurn(item)
+            } finally {
+              carrier._suspended = true
+            }
+            hooks.reclaim?.(afterRun())
+            hooks.onCounts?.(backgroundCounts(carrier))
+            continue
           }
-          hooks.reclaim?.(afterRun())
-          hooks.onCounts?.(backgroundCounts(carrier))
-          continue
         }
         // 2. pending 非空 或 未 drain 的 ask → 合并消化轮 / 上行唤醒轮（单注入点由 runTurn
         //    首行完成：pending 经 run 起始注入器，ask 经回合头 `drainChildUpstream`）。
@@ -210,9 +250,28 @@ export function startSuspension(ctx) {
         }
         // 3. 池空 → 自然退出。
         if (!poolLive(carrier)) break
-        // 4. 等下一 settle / 宿主唤醒。
-        const why = await waitForSettleOrWake(carrier, abortSignal, latch)
+        // 4. 等下一 settle / 宿主唤醒 / timer 到期（opt-in——§6.30.10 等待第四态；deadline 每轮现算）。
+        const why = await waitForSettleOrWake(carrier, abortSignal, latch, {
+          deadline: timerFace?.deadline?.() ?? null, timer, clear,
+        })
         if (why === "aborted") { aborted = true; break }
+        // 4b. 窗内到期兑现（§6.30.10 循环兑现支）：交付真 ⇒ timer 轮（轮后序同消化轮形 = reclaim +
+        //     onCounts 两钩，不发 digest 边界）；交付面契约 = 同步 · 严格布尔（`=== true`——非布尔返值
+        //     即静默零轮）；池空窗退交宿主空闲闩（到期件已出列——零重复投递）；交付假 ⇒ 循环重入。
+        if (why === "timer" && timerFace?.deliver?.() === true) {
+          const afterRun = consumedByRun()
+          try {
+            await runTurn("", { autoTurn: true, timerTurn: true })
+          } catch (e) {
+            // timer 轮自身的回合级中止不是会话停止——容纳并重入循环（timer 轮不发 digest 边界 ⇒
+            // 中止路径零边界、不补发轮后序钩子；池空 / pending 空自然退出——与消化支同判，§6.30.10）。
+            if (e?.name === "AbortError" && !abortSignal?.aborted) continue
+            throw e
+          }
+          hooks.reclaim?.(afterRun())
+          hooks.onCounts?.(backgroundCounts(carrier))
+          continue
+        }
       }
     } finally {
       if (!finished) {
@@ -231,8 +290,9 @@ export function startSuspension(ctx) {
   })()
 
   return {
-    /** 挂起空闲期入槽（单槽语义：宿主 busy 期拒收；至多一条待交接）。 */
-    pushInput(msg) { pendingInput.push(String(msg)) },
+    /** 挂起空闲期入槽（宿主 busy 期拒收——条数策略归宿主）。**保留原值**（增补 C：富条目
+     *  ——VSC ∕ CLI 载体对象；消费面 = 宿主 `takeInput`；`String()` 化归宿主需要时自做）。 */
+    pushInput(msg) { pendingInput.push(msg) },
     /** 宿主唤醒（用户输入落槽后 / 宿主 settle 回调路径——settle 由池 waiter 另一路唤醒）。 */
     wake() { latch.wake?.() },
     done,

package/agent/timers.mjs

@@ -0,0 +1,113 @@
+/**
+ * agent/timers.mjs — timer 到期件（载体①：在途 timer 的单一权威读面）+ 空闲唤醒机制（闩 ∕ 派发 ∕ 火策略）。
+ *
+ * 机制单源 = `docs/core/design/AGENT-LOOP-ASYNC-POOL.md` §6.30.2（载体定形 D-TW1）：
+ * 读面三件纯函数住本档——最近到期时点 / 到期出列（幂等）/ 历史注入单点。消费面三处共用
+ * 同一读点（零第二份过滤语义）：① 回合边界轮询（`agent/post-turn.mjs`——行为零变）；
+ * ② 空闲闩 deadline；③ 挂起窗 deadline；显示面（状态行标记 / `/timers`）同读源。
+ *
+ * 载体仍在 agent 字段 `_pendingTimers`（条目形 `{ id, expiresAt, message }`）——**唯一写点** =
+ * timer 工具 `thincoder-core/agent-tools/timer.mjs`；跨 run 存活 = 规范语义（D-TW3，无 per-run 复位）。
+ *
+ * 空闲唤醒族（2026-09-28 流程批 R4 **上提核件** · 纯搬 + 转口 · 零语义改；上提源 = VSC
+ * `thincoder-vscode/src/extension/timer-watch.mjs:46` ∕ `:73` ∕ `:94`——as-of 2026-09-28 R4 读数；两端现址（B3 收编后，实读 2026-09-29）=
+ * VSC `:63`（闩 ∕ 装配）· `:29`（派发）· `:48`（火）∥ CLI `:41`（闩转口）· `:34`（派发转口）· `:57`（火））：`createTimerWatch` = 一次性最近截止闩
+ * （起 ∕ 停 ∕ 重臂 ∕ `unref`）· `deliverExpiredTimers` = 到期批派发（出列幂等 ⇒ 注入单点 ⇒ 落流缝）·
+ * `fireTimerWake` = 火策略（非空闲零动作 ∕ 零交付零开轮）。端面表壳留端（桌面键面 ∕ `ev:timer` 出词；
+ * VSC ∕ CLI 自持副本已随 B3 迁移轮退场（2026-09-29——双写窗口收口），本档 = 单源）。
+ */
+
+/** 在途条数帽（§6.30.3 门三件②成本闸）：超限 ⇒ timer 工具**显式拒**（不静默丢 / 不静默清；
+ *  形态先例 = 队满「拒 + 提示 + 保留」）。与 CLI 排队容量 `QUEUED_MAX_ITEMS`（8）同值同形。 */
+export const TIMER_MAX_PENDING = 8
+
+/** 最近到期时点（毫秒）或 `null`（空在途）——端闩 / 挂起窗 deadline / 显示面共用同源（每帧活读）。 */
+export function pendingTimerDeadline(agent) {
+  const timers = agent?._pendingTimers ?? []
+  let min = null
+  for (const t of timers) {
+    const at = t?.expiresAt
+    if (typeof at !== "number" || !Number.isFinite(at)) continue
+    if (min === null || at < min) min = at
+  }
+  return min
+}
+
+/** 到期出列（**幂等**）：取走 `expiresAt <= now` 的条目并返回（在途表内移除）——二次调用零返
+ *  （§6.30.3 成本闸②「到期即消费」——绝不重复投递）。未到期项原序保留。 */
+export function takeExpiredTimers(agent, now = Date.now()) {
+  const timers = agent?._pendingTimers ?? []
+  const expired = timers.filter((t) => t.expiresAt <= now)
+  if (expired.length === 0) return []
+  agent._pendingTimers = timers.filter((t) => t.expiresAt > now)
+  return expired
+}
+
+/** 历史注入单点（逐字形态 = 既有注入单源）：逐条 `[System reminder: ⏰ timer — <message>]` 落历史，
+ *  返回注入的原文（显示面复用同一串——零第二份字面）。 */
+export function injectTimerReminders(agent, entries) {
+  const lines = []
+  for (const t of entries ?? []) {
+    const line = `[System reminder: ⏰ timer — ${t.message}]`
+    agent.history.push({ role: "user", content: line })
+    lines.push(line)
+  }
+  return lines
+}
+
+/** 开关判据（§6.30.3 门三件③ D-TW5 · 上提源 = VSC `timer-watch.mjs:33`——as-of 2026-09-28 R4 读数，B3 收编后该端副本退场）
+ *  （现转口 = CLI `timer-watch.mjs:18`）：默认开——只有显式 `false` 才关
+ *  （键 `agent.timerWake`；与 CLI 同口径 `!== false`）。关 ⇒ 闩零注册 ⇒ 回仅回合边界投递（既有语义）。 */
+export function timerWakeEnabled(agent) {
+  return agent?.config?.agent?.timerWake !== false
+}
+
+/** 到期批派发（**两路共用**：空闲闩 fire ∥ 挂起窗 `timerFace.deliver` · 上提源 = VSC `timer-watch.mjs:73`
+ *  核心体——as-of 2026-09-28 R4 读数；现址 = VSC `:29` · CLI `:34`）：出列（幂等——绝不重复投递）→ 注入单点 → 逐条落流缝（`onLine`——端侧 `ev:timer` ∕ webview ∕
+ *  TUI 行）。返回交付原文（核注入单源逐字；零到期 ∕ 无载体 ⇒ 空数组——在途不动 = 零静默丢）。
+ *  `now` = 时点值（默认现刻；与 `takeExpiredTimers` 同形——调用方传钟、本档取时点）。 */
+export function deliverExpiredTimers(agent, { now = Date.now(), onLine = null } = {}) {
+  const lines = injectTimerReminders(agent, takeExpiredTimers(agent, now))
+  for (const line of lines) onLine?.(line)
+  return lines
+}
+
+/** 一次性最近截止闩（单槽 · 上提源 = VSC `timer-watch.mjs:46` 逐字——as-of 2026-09-28 R4 读数；现址 = VSC `:63`（闩 ∕ 装配）· CLI `:41`（闩转口））：`sync()` = 按当前在途最近到期时点
+ *  （重）武装——无在途 ∕ 开关关 ∕ 无载体 ⇒ 撤旧零注册；`disarm()` = 撤闩清点。到点自撤 · `unref()`（尽力面）。
+ *  `getAgent` / `onFire` 缺省宽容沿用源（未接线 = 惰性零注册）；`timer` ∕ `clear` ∕ `now` = 注入缝（默认平台全局）。
+ *  @returns {{ sync: Function, disarm: Function }}——`sync()` ⇒ 武装延迟（毫秒）或 `null`（未武装） */
+export function createTimerWatch({ getAgent, onFire, timer = setTimeout, clear = clearTimeout, now = Date.now } = {}) {
+  let handle = null
+  const disarm = () => {
+    const h = handle
+    handle = null
+    if (h !== null) { try { clear(h) } catch { /* 已触发 / 不可清——尽力面 */ } }
+  }
+  const sync = () => {
+    const agent = getAgent?.()
+    const deadline = timerWakeEnabled(agent) ? pendingTimerDeadline(agent) : null
+    if (deadline == null) { disarm(); return null } // 无在途 / 开关关 / 无载体——撤旧，零注册
+    disarm() // 单槽：重复武装 = 撤旧立新（延迟按最近到期重算）
+    const delay = Math.max(0, deadline - now())
+    handle = timer(() => { handle = null; onFire?.() }, delay)
+    try { handle?.unref?.() } catch { /* unref 失败不阻断（一次性闩自然退出） */ }
+    return delay
+  }
+  return { sync, disarm }
+}
+
+/** 空闲唤醒火策略（上提源 = VSC `timer-watch.mjs:94`——as-of 2026-09-28 R4 读数；现址 = VSC `:48` · CLI `:57`；桌面同形）：
+ *  **非空闲零动作**——回合在飞 ∕ 挂起窗
+ *  由各自既有路径接管，在途表零触碰（链尾重同步再武装）；空闲 ⇒ 派发；交付真 ⇒ 开 timer 轮（开轮面 =
+ *  `openTurn` 缝，承担 `{ autoTurn: true, timerTurn: true }` 语义）。`deliver` 契约 = 同步 · 严格布尔
+ *  （判定 `=== true`——同 §6.30.10 `timerFace.deliver`）；缝缺 ⇒ 抛（fail-loud——未接线不得静默零开轮）。
+ *  `busy` = 非空闲判据（宿主现算：在飞回合 ∕ 窗内 ⇒ true）；返回是否开轮。 */
+export async function fireTimerWake({ busy = false, deliver, openTurn } = {}) {
+  if (typeof deliver !== "function" || typeof openTurn !== "function") {
+    throw new Error("[timers] fireTimerWake requires deliver/openTurn seams (unwired seams must not pass silently)")
+  }
+  if (busy) return false
+  if (deliver() !== true) return false
+  await openTurn()
+  return true
+}

package/agent/turn-loop.mjs

@@ -0,0 +1,244 @@
+/**
+ * agent/turn-loop.mjs — runAgent 回合环（2026-09-29 P2 三拆：agent.mjs runAgent 段 2 ∕ 3 ∕ 5 ∕ 6
+ * verbatim 迁入——循环局部 ∕ `_ctxBasis` ∕ drainChildUpstream ∕ for 循环本体 ∕ 零落盘结账 +
+ * ContinueError；模型调用段经 callModelTurn 外提 agent/chat-call.mjs）。
+ * 接口 = runTurnLoop(agent, ctx)；控制流零转换（`continue` ∕ `return cr.content` ∕ `throw` 全留环内）。
+ */
+import { resolve } from "node:path"
+import { pushReal, summarizeRunExplorations } from "../context.mjs"
+import { abortError, annotateAbort } from "../abort-provenance.mjs"
+import { specForModel, assistantToolCallMessage } from "../config.mjs"
+import { executeToolCalls } from "./dispatch.mjs"
+import { recordToolResults } from "./record-results.mjs"
+import { injectPostTurn } from "./post-turn.mjs"
+import { handleCompletion } from "./completion.mjs"
+import { runCompactionCheck, injectTurnReminders, injectResponseReminders } from "./run-stages.mjs"
+import { callModelTurn } from "./chat-call.mjs"
+import {
+  turnFrame, // 第 19 批（TURN-ACROSS-SEGMENTS）：跨段累计编号帧（设计 TURN-CAP-CONTINUE.md §4）
+  ContinueError,
+  FILE_MUTATORS, toolTouchPaths,
+} from "./helpers.mjs"
+
+export async function runTurnLoop(agent, {
+  maxTurns, threshold, toolSchemas, toolByName, systemPrompt,
+  depth, signal, autoTurn, streamOutput,
+  consumeInjected, consumeQueuedInput, callbacks, distillSignal,
+}) {
+  let guardPushbacks = 0
+  let advisorPushbacks = 0
+  let honestReminderInjected = false
+  const recentCallSigs = []
+  // "once" stream rules fire at most once per runAgent call; the set survives across
+  // chat() calls (rule abort-retry, tool loop) within the turn.
+  const streamRuleFired = new Set()
+
+  // Compaction overhead for the pure-estimation path: system prompt + tools schema are
+  // in every request but not in history — without them the first-turn/just-compacted
+  // estimate under-counts and may never trigger. Measured path already includes both.
+  const compactionOverhead = {
+    systemPrompt,
+    tools: toolSchemas,
+    // TRACES.md §6.1 D-TR4：compress 轨迹 depth 元数据（runAgent 的 depth 在此作用域——
+    // context.mjs compressIfNeeded 经 extras 透出到 logCtx）
+    traceDepth: depth,
+  }
+  // F-CC1（§6.16.4 阈值单源接线）：本回合压缩判定所用的阈值 + 固定开销面暂存——
+  // `context` 工具的 stats 报**同一口径**（不自行重算第二口径；VSC checkAndCompact 同款暂存）。
+  agent._ctxBasis = { threshold, overhead: compactionOverhead }
+
+  // SUBAGENT-UPSTREAM-CHANNEL（AGENT-LOOP-UPSTREAM.md §6.27.4 消费点）：子 → 父在飞消息的
+  // 回合边界注入单点取用一次（模块缓存 ⇒ 每 run 一次代价）；动态 import = 零新增静态边
+  // （先例 = 上方 injectAsyncResult :113-117）。
+  const { drainChildUpstream } = await import("../agent-tools/parent-channel.mjs")
+
+  // #417（撞帽载荷「本段零落盘轮数」——只报数：零阈值 / 零自动动作）：计数基线——回合环逐轮
+  // 比对 `_touchedFiles` 增量（轮顶对上一轮结账；撞帽收尾轮在环外单结）。
+  agent._turnFilesMark = agent._touchedFiles.length
+
+  for (let turn = 0; turn < maxTurns; turn++) {
+    // 第 19 批（TURN-ACROSS-SEGMENTS——设计 TURN-CAP-CONTINUE.md §4）：编号帧——
+    // `_turnSeq` 每轮 +1（跨段累计，仅 `!resume` 链起点复位）；面向消费面的两字段
+    // （状态行 + ⟦ev⟧turn / ⟦ev⟧approval 事件共用）在此同点赋值（编号唯一权威；帧
+    // 公式 = helpers.mjs turnFrame）。段内帽判定不读帧（下行循环条件只读段内
+    // turn / maxTurns——N6）。
+    const frame = turnFrame(++agent._turnSeq, turn, maxTurns)
+    agent._currentTurn = frame.turn
+    agent._maxTurns = frame.maxTurns
+    // #417（撞帽载荷「本段零落盘轮数」——采集点与 `_turnSeq` 同源面）：上一轮至今 `_touchedFiles`
+    // 零增 ⇒ 上一轮零落盘，计数 +1；mark 前移（收尾轮在环外结账——见下方 ContinueError 前）。
+    if (turn > 0 && agent._touchedFiles.length === agent._turnFilesMark) agent._zeroWriteTurns += 1
+    agent._turnFilesMark = agent._touchedFiles.length
+    // D2 (AGENT-LOOP-SUBAGENT.md §6.7.2): depth>0 children emit a ⟦ev⟧turn progress token each turn —
+    // single emit point covering all three spawn tools; phase=llm (tool/done progress rides
+    // the onToolCall/onToolResult relay — no token for those). 第 19 批：载荷取上方帧值
+    // （agent._currentTurn / _maxTurns——字段形态 / 字段数 / phase 零变化，N5）。
+    if (depth > 0 && callbacks.onToken) {
+      callbacks.onToken(`⟦ev⟧turn\x1e${agent._currentTurn}\x1e${agent._maxTurns}\x1ellm\x1e`)
+    }
+    // §2.5 #78 并入（VSC 帧回调）：每轮帧另经结构化回调发出（池条目 entry.turn 的
+    // VSC 等价通道——⟦ev⟧turn token 解析的宿主面随时可用；签名扩展向后兼容）。
+    callbacks.onAgentTurn?.(frame.turn, frame.maxTurns)
+
+    // SUBAGENT-OBSERVE-SEND D2: 子代理回合边界消费点——每轮开头把父侧经 subagent
+    // action:'send' 注入队列（entry._injected）的消息按普通 user 回合推入子历史
+    // （pushReal → 下一轮 chat 即含该指令）。由 executeAsyncSpawn 经 childRunOpts 贯通的
+    // consumeInjected 回调承载（异步子代理专属——缺省 null：主会话/阻塞子代理零开销）。
+    consumeInjected?.(agent)
+    // 子代理在飞消息（子 → 父；§6.27）：空队列 no-op；非空 ⇒ 恰一条合并 user 消息注入。
+    drainChildUpstream(agent)
+    // ③ 用户 → 主会话投递（步边界 pickup——queue-visible 批 fix 轮 2026-09-24 · F16）：循环头
+    // 回合边界缝（核只给缝、不给策略——取批 / pushReal / 呈现归端侧闭包）；缺省 null，系统轮不传
+    // （`AGENT-LOOP-ASYNC-POOL.md` §6.8「步边界 pickup」· 适用面 = 用户回合）。
+    consumeQueuedInput?.(agent)
+
+    const lastRole = agent.history.at(-1)?.role
+    if (lastRole === "user" || lastRole === "tool") {
+      // 2026-09-05 实践轮：压缩检查/降级计数提为 runCompactionCheck（agent/run-stages.mjs——
+      // CLI 对位 VS run-stages）——循环骨架此处只剩检查调用（recentCallSigs 对象引用回流）。
+      await runCompactionCheck(agent, { threshold, callbacks, compactionOverhead, signal, recentCallSigs })
+    }
+
+    // 2026-09-05 实践轮：plan cadence + eng 状态注入提为 injectTurnReminders（run-stages）
+    await injectTurnReminders(agent, { depth })
+
+    const response = await callModelTurn(agent, {
+      systemPrompt, toolSchemas, streamOutput, callbacks, signal, streamRuleFired, autoTurn, depth, turn,
+    })
+
+    // 内置工具（Responses web_search）结果本地化：服务端已执行——入历史为 tool 消息；
+    // 服务端 item id 是 msg_xxx 非 web_search_call_ 前缀——必须合成前缀（toItems 识别锚点），
+    // 原始 id 存入 content（真机冒烟 2026-08-31 验证）。
+    for (const btr of response.builtinToolResults ?? []) {
+      if (!btr?.id) continue
+      pushReal(agent, {
+        role: "tool",
+        tool_call_id: `web_search_call_${btr.id}`,
+        content: JSON.stringify({ id: btr.id, query: btr.query ?? "", sources: btr.sources ?? [], status: btr.status ?? "completed" }),
+      })
+    }
+
+    // Stream rule triggered mid-generation (action: "abort"): halt, inject the rule's
+    // message as a reminder, retry from the same context.
+    if (response.ruleTriggered) {
+      if (response.content) {
+        pushReal(agent, { role: "assistant", content: response.content })
+      }
+      const label = response.ruleName ? ` — stream rule "${response.ruleName}"` : ""
+      agent.history.push({
+        role: "user",
+        content: `[System reminder${label}: ${response.ruleMessage}]`,
+      })
+      continue
+    }
+
+    // Stream rule warnings / finish-reason 警告（2026-09-05 实践轮——提为
+    // injectResponseReminders，agent/run-stages.mjs——verbatim，语义零变）
+    injectResponseReminders(agent, response)
+
+    // User interrupted mid-generation (Ctrl+I): commit partial output + inject the
+    // message, then signal the outer loop to recreate the controller and resume.
+    if (response.interrupted) {
+      if (response.content) {
+        pushReal(agent, { role: "assistant", content: response.content })
+      }
+      agent.history.push({
+        role: "user",
+        content: `[User interrupt: ${response.interruptMessage}]`,
+      })
+      // AGENT-LOOP-SUBAGENT.md §6.12 站点 #8（第 24 批）：错误对象已自带 name/message——只补来源标注（缺 abortInfo 才补）
+      throw annotateAbort(Object.assign(new Error("User interrupted"), { name: "AbortError" }), signal, "agent", "interrupted-response")
+    }
+
+    if (response.usage) {
+      callbacks.onUsage?.(response.usage)
+      if (response.usage.prompt_tokens != null) {
+        agent._lastPromptTokens = response.usage.prompt_tokens
+        agent._usageAtLen = agent.history.length
+      }
+    }
+
+    // Warn on abnormal finish reasons — the response may be incomplete/truncated.
+    // 2026-09-05 实践轮：finish-reason 注入随流规则警告提为 injectResponseReminders。
+
+    if (response.toolCalls.length === 0) {
+      const cr = handleCompletion(agent, response, depth, turn, guardPushbacks, honestReminderInjected, advisorPushbacks, callbacks)
+      guardPushbacks = cr.guardPushbacks
+      honestReminderInjected = cr.honestReminderInjected
+      advisorPushbacks = cr.advisorPushbacks
+      if (cr.action === "continue") continue
+      if (depth === 0) {
+        // End-of-run exploration distillation (CONTEXT-COMPACTION §5 + SEND-STALL-DISTILL
+        // §2.1): async — the promise hangs on _pendingDistill, settling at the next run's
+        // start or the TUI exit flush. Silent (N3): failure never blocks return/history.
+        // TRACES.md §6.1 D-TR4：depth 透传（distill 轨迹元数据——与 compress 同通道）；extras = 会话续写前缀面（§6.15）
+        // §2.5-B（P4-I）：端壳经 `opts.distillSignal` 供蒸馏专用中止信号（与运行 signal 分离——
+        // 运行 controller 重建不杀蒸馏）；缺省（null）⇒ `signal` 逐字零变。
+        const distill = summarizeRunExplorations(agent, callbacks, distillSignal ?? signal, depth,
+          { systemPrompt, tools: toolSchemas }).catch(() => {}) // 与回合请求同源（无第二构造点）
+        agent._pendingDistill = distill
+      }
+      return cr.content
+    }
+
+    // abort after chat completes, before committing history: don't commit a half-finished turn
+    if (signal?.aborted) throw abortError(signal, "agent", "post-chat")
+
+    pushReal(agent, assistantToolCallMessage(response, specForModel(agent.provider.model)))
+
+    const results = await executeToolCalls(agent, toolByName, response.toolCalls, callbacks, depth, signal)
+
+    // Ctrl+I interrupt during tool execution: skip committing partial results — inject
+    // the interrupt and retry (placeholder results keep strict providers pairable).
+    if (signal?.reason?.interrupt) {
+      // 中断变更记账（2026-08-31 评审 #4）：此分支的工具已全部执行完成（磁盘已变，execute 已完成），
+      // 真实结果按语义不进历史（placeholder 替代）——但变更必须记账：否则 guard 看到
+      // "本轮未改代码" 放行，评审/verify 门禁被绕过（文件改了却没评审）。
+      // §29 fix A（2026-09-07）：mutation-seq 记账已收敛到 dispatch runOne 执行成功即刻
+      // （唯一记账点——本分支不再 noteMutations——不双计——中断+同批 launch seq 单计
+      // 回归断言见 §29 T-A1i）；此处仅剩 guard 标志 + touchedFiles 记账。
+      for (const { toolCall, ok } of results) {
+        const tool = toolByName.get(toolCall.name)
+        if (!ok || !tool || !FILE_MUTATORS.has(toolCall.name)) continue
+        agent._mutatedThisRun = true
+        agent._calledAdvisorThisRun = false
+        agent._verifiedThisRun = false
+        agent._verifyPassed = undefined
+        try {
+          const args = JSON.parse(toolCall.arguments)
+          const paths = toolTouchPaths(tool, args)
+          for (const p of paths) {
+            const abs = resolve(agent.cwd, p)
+            if (!agent._touchedFiles.includes(abs)) agent._touchedFiles.push(abs)
+          }
+        } catch { /* 畸形 args 不影响记账（touchedFiles 尽力而为） */ }
+      }
+      // The assistant tool_calls were committed above — synthesize placeholder tool
+      // results BEFORE the interrupt message (strict providers 400 on dangling
+      // tool_calls; consult P1, 2026-08-30).
+      for (const tc of response.toolCalls) {
+        agent.history.push({ role: "tool", tool_call_id: tc.id, content: "[Tool execution interrupted — results discarded]" })
+      }
+      agent.history.push({
+        role: "user",
+        content: `[User interrupt: ${signal.reason.message}]`,
+      })
+      callbacks.onTurnEnd?.(agent, turn)
+      continue
+    }
+
+    // Model is executing tools → real work: reset guard pushback counters
+    guardPushbacks = 0
+    advisorPushbacks = 0
+
+    // Commit tool results (pairing, multimodal deferral, mutation accounting, reindex)
+    await recordToolResults(agent, toolByName, results)
+
+    injectPostTurn(agent, results, recentCallSigs, callbacks, turn)
+  }
+
+  // #417（撞帽载荷「本段零落盘轮数」）：收尾轮（撞帽轮）若零落盘同样计入——轮顶计数只
+  // 覆盖到倒数第二轮（maxTurns ≤ 0 时环未跑，不虚计）。
+  if (maxTurns > 0 && agent._touchedFiles.length === agent._turnFilesMark) agent._zeroWriteTurns += 1
+  throw new ContinueError(maxTurns)
+}