@thincoder/core 0.9.4 → 0.10.1

package/agent/setup.mjs

@@ -10,14 +10,18 @@ import { search as memorySearch, docSearch } from "../memory.mjs"
 import { pushReal } from "../context.mjs"
 import { toOpenAISchema } from "../tools/index.mjs"
 import { loadSkills, formatSkillListing } from "../skills.mjs"
+import { scopedRulesBlock } from "../rules.mjs"
 import { assemblePrompt } from "../prompt-overlays.mjs"
 import {
   escapeXml, repairHistory, listWorkDir,
   collectGitContext, loadProjectInstructions, OUTLINE_INJECT_PREFIX,
   DEFAULT_MAX_TURNS, ensureAutoReminder,
 } from "./helpers.mjs"
-import { pushEnvStateReminder, pushPeerReminder } from "./setup-reminders.mjs"
+import { pushEnvStateReminder, pushPeerReminder, pushInjections } from "./setup-reminders.mjs"
 import { assembleFamilyTools } from "./family-tools.mjs"
+import { normalizeOrigin } from "../memory/origin.mjs"
+import { searchOrigins } from "../memory/code-search.mjs"
+import { INDEX_ORIGIN_ROW_WARN } from "../memory/schema.mjs"
 
 const DEFAULT_COMPACT_THRESHOLD = 100_000
 const DOC_SEARCH_LIMIT = 5
@@ -41,6 +45,10 @@ const MEMORY_SEARCH_LIMIT = 3
  */
 export async function prepareRun(agent, input, callbacks, {
   depth = 0, signal, overrideTurns, resume, extraTools = null,
+  // P4-I（批次档 §2.5 A1 + 父侧 2026-09-29 裁定①）：端壳装配缝——注入串 ∕ 工具装饰；
+  // 两项缺省（null ∕ undefined）⇒ 现行行为逐字零变（CLI ∕ desktop 不传即零变）。
+  // （A2 提示尾块载位已退役——B7 3a：核自持 `.cursor/rules` 尾块，见下方 depth-0 块。）
+  injections = null, toolDecorate = undefined,
 } = {}) {
   const maxTurns = overrideTurns ?? agent.config?.agent?.maxTurns ?? DEFAULT_MAX_TURNS
   const threshold = agent.config?.agent?.compactThreshold ?? DEFAULT_COMPACT_THRESHOLD
@@ -91,7 +99,8 @@ export async function prepareRun(agent, input, callbacks, {
       if (agent.memory && !agent.history.some((m) => typeof m.content === "string" && m.content.startsWith(OUTLINE_INJECT_PREFIX))) {
         try {
           const { buildSummary } = await import("../tools/repomap.mjs")
-          const summary = await buildSummary(agent.memory.db, agent.cwd)
+          // §6.14 B4：origin 限定 + 文件数上界（越界 ⇒ 提示行 + 跳过大纲构建——见 repomap.mjs）
+          const summary = await buildSummary(agent.memory.db, agent.cwd, { origin: normalizeOrigin(agent.memory.codeOrigin) })
           if (summary && !summary.startsWith("(no indexed")) {
             agent.history.push({ role: "user", content: `${OUTLINE_INJECT_PREFIX}\n${summary}]`, transient: true })
           }
@@ -103,8 +112,16 @@ export async function prepareRun(agent, input, callbacks, {
     if (agent.memory && depth === 0) {
       const docs = await docSearch(agent.memory, input, { limit: DOC_SEARCH_LIMIT })
       if (docs.length > 0) {
-        const count = agent.memory.db.prepare(`SELECT COUNT(*) AS n FROM doc_chunks`).get()?.n ?? 0
-        const more = count > docs.length ? ` (${count} chunks indexed total — call doc_search if you need more)` : ""
+        // §6.14 B3 + §6.15：origin 集限定 + 有界计数（子查询 LIMIT = WARN+1 形——越界回「20000+」；跨 origin 全扫不再回升）
+        const origins = searchOrigins(agent.memory)
+        const bound = INDEX_ORIGIN_ROW_WARN + 1
+        const countFilter = origins.length === 1 ? " WHERE origin = ?" : origins.length > 1 ? ` WHERE origin IN (${origins.map(() => "?").join(", ")})` : ""
+        const countRow = agent.memory.db.prepare(
+          `SELECT COUNT(*) AS n FROM (SELECT 1 FROM doc_chunks${countFilter} LIMIT ${bound})`,
+        ).get(...origins)
+        const count = Number(countRow?.n ?? 0)
+        const countLabel = count >= bound ? `${INDEX_ORIGIN_ROW_WARN}+` : String(count)
+        const more = count > docs.length ? ` (${countLabel} chunks indexed total — call doc_search if you need more)` : ""
         agent.history.push({
           role: "user",
           content:
@@ -137,6 +154,9 @@ export async function prepareRun(agent, input, callbacks, {
     pushEnvStateReminder(agent)
     await pushPeerReminder(agent)
   }
+  // A1（§2.5——端壳编辑器上下文注入，序位 = env/peer 之后、time 之前）：端采集内容经
+  // `pushInjections` 单点落机器线（transient + 同文去重）；缺省 null ⇒ 零行为。
+  pushInjections(agent.history, injections)
 
   // Time grounding for EVERY agent depth AND every resume, pushed LAST (after the user
   // input): transient on the HUMAN line — dropped on persist; on the MACHINE line — kept
@@ -165,6 +185,9 @@ export async function prepareRun(agent, input, callbacks, {
     engineering: agent.config?.agent?.engineering === true,
     consultModels: agent.config?.agent?.consultModels ?? [],
     batchDoc: agent._batchDoc ?? null,
+    // 裁定①（P4-I · 父侧 2026-09-29）：端壳装饰体透传（`assembleFamilyTools` 既有 `decorate`
+    // 参数面——缺省 undefined ⇒ 核默认形态逐字零变，CLI ∕ desktop 不传即零变）。
+    decorate: toolDecorate,
   })
   // 两段式：绑定值（基础集）→ 家族段 → caller 注入面（§2.3F 不相交义务在注入方）。
   const tools = [...agent.tools, ...familyTools, ...(Array.isArray(extraTools) ? extraTools : [])]
@@ -232,6 +255,11 @@ export async function prepareRun(agent, input, callbacks, {
     const skills = await loadSkills(agent.cwd)
     const listing = formatSkillListing(skills)
     if (listing) systemPrompt += `\n\n${listing}`
+    // B7 3a：`.cursor/rules` 常驻集尾块（原端壳 A2 载位退役——核自持；序位 = skills 清单之后）。
+    // 尾块 ∕ JIT 两缝同门 `depth === 0`（子代理不携——B1 §2.5-A2 在册态）；同点缓存 `agent._rules`
+    // （JIT 判定只读该缓存——`loadScopedRules` 本 run 唯一一次目录读取）。
+    const scopedBlock = scopedRulesBlock(agent, agent.cwd)
+    if (scopedBlock) systemPrompt += scopedBlock
   }
 
   ensureAutoReminder(agent)

package/agent/spawn-child.mjs

@@ -1,5 +1,5 @@
 /**
- * spawn-child.mjs — 生成侧统一子代理管线（AGENT-LOOP.md §7.2 D3）。
+ * spawn-child.mjs — 生成侧统一子代理管线（AGENT-LOOP-SUBAGENT.md §6.7.2）。
  *
  * 收编 subagent/escalate/consult 三份机械同构的重复实现：
  *   - allocRelay / emitRelayModel: relay 取号段 ∥ 出生声明（`[model]`）发射段——两段分离
@@ -20,8 +20,8 @@ import { specForModel } from "../config.mjs"
 import { ContinueError } from "../agent.mjs"
 import { relayPrefixOf } from "./relay-prefix.mjs"
 import { appendCappedText } from "../text-budget.mjs"
-// 第 27 批 §12.3①：relay 前缀文法单一权威模块（`src/agent/relay-prefix.mjs`）——
-// 生成侧枢纽再导出（TUI/ACP 消费方可经此导入；消费方按 §12.3① 直连模块亦可）。
+// 第 27 批：relay 前缀文法单一权威模块（`src/agent/relay-prefix.mjs`）——
+// 生成侧枢纽再导出（TUI/ACP 消费方可经此导入；消费方直连模块亦可）。
 export { RELAY_PREFIX_RE, parseRelayPath, relayPrefixOf } from "./relay-prefix.mjs"
 
 /** 事件 token 哨兵串（D1）——LLM 正常内容混淆概率极低；字段分隔用 RS (\x1e)。 */
@@ -35,7 +35,7 @@ const RS = "\x1e"
 export { TURN_CAP_MARK, STOPPED_MARK } from "./child-marks.mjs"
 
 /**
- * §18 D-E3 工程子代理内部 spawn 机械门（AGENT-LOOP.md §18 D-E2 round5 #2 后备 +
+ * D-E3 工程子代理内部 spawn 机械门（AGENT-LOOP-SUBAGENT.md §6.7.6 后备 +
  * ENGINEERING-MODE.md §2.15 D）：eng-coder（偏差审计）与 **eng-designer（自己勘察）**
  * 同为受限通道——depth>0 且父角色 ∈ 集合时，内部 spawn 只允许 role='explore'、
  * async 强制同步。
@@ -109,7 +109,7 @@ export function makeRelay(parent, label, emit, model) {
 // Single source for the event grammar branch lists (consult P3, 2026-08-30):
 // stripEventToken (display) and stripEventTokensForCapture (capture) shared them
 // literally — extending the event set meant touching both regexes.
-// "done" = §15 D-A3 async-child completion event (emitted by the parent's
+// "done" = AGENT-LOOP-SUBAGENT.md §6.7.3 D-A3 async-child completion event (emitted by the parent's
 // turn-end collection, not by children — listed so the grammar stays honest).
 const EVENT_PHASE = "turn|approval|done"
 const EVENT_TYPE = "llm|tool|approval|done"
@@ -139,7 +139,7 @@ export function stripEventTokensForCapture(text) {
  * - onToolOutput 带**已加前缀**的 name 走父 onToolOutput（name 形如
  *   "coder#1/bash"，消费端剥前缀路由进对应区块；chunk 对象/裸串原样透传）。
  * 父回调缺省时不包装（headless 嵌入）。
- * §27 R23 D-R23c1：包装产物在 onToken 上留 `_relayPrefix` 标记——同步收尾段据此
+ * docs/cli/design/TUI.md §6.8.2 R23 D-R23c1：包装产物在 onToken 上留 `_relayPrefix` 标记——同步收尾段据此
  * 判定"ctx.callbacks 已是嵌套 wrapper"（本 spawn 处于更深一层——eng-coder 内
  * explore）→ emitNestedChildEvent 补发射内层完成事件（T-R23c.2b 断言源）。
  */
@@ -163,7 +163,7 @@ export function wrapChildCallbacks(relayPrefix, parentCallbacks = {}) {
 }
 
 /**
- * §27 R23 D-R23c1（生成侧补发射——评审 #1 🅰）：sync spawn 同步收尾时若父回调已是
+ * §6.8.2 R23 D-R23c1（生成侧补发射——评审 #1 🅰）：sync spawn 同步收尾时若父回调已是
  * 嵌套 wrapper（onToken 带 `_relayPrefix` 标记——即本 spawn 的父本身是子代理，如
  * eng-coder 内 explore 审计）→ 发内层 done/stopped 事件（带完整嵌套前缀——wrapper
  * 链自动补外层前缀）→ 主 TUI routeSubToken 路由到子块定格。非嵌套（depth-0 直连主
@@ -178,7 +178,7 @@ export function emitNestedChildEvent(ctx, relayPrefix, kind) {
   return true
 }
 
-/** 捕获额度（TUI-OOM-ROOTCAUSE——AGENT-LOOP.md §23.3.1 表 1 候选 1：滞后水位截断）：
+/** 捕获额度（TUI-OOM-ROOTCAUSE——AGENT-LOOP.md §6.15：滞后水位截断）：
  *  `_capturedOutput` 是子代理流式文本的第二份全量拷贝（原无上限——勘察 C2）；超 hard 即
  *  裁至头 16K + 标记 + 尾 48K（摊还 O(1)）——消费面读时已各自 slice(0, 2000/4000)，头尾
  *  保真覆盖；停止报告内联场景出现截断标记（可断言——D-SM1）。纯函数本体住
@@ -235,7 +235,7 @@ export async function runWithContinue(runner, child, input, callbacks, runOpts,
   // Review #4 fix: strip sentinel/control chars from the capture — `output` feeds
   // onDeclined's partial-output return, which lands in the PARENT LLM history where
   // the display-layer sanitizeDisplay backstop does not apply.
-  // TUI-OOM-ROOTCAUSE（§23.3.1）：捕获滞后水位截断——超 CAPTURE_CAP_OPTS.hard 裁至
+  // TUI-OOM-ROOTCAUSE（AGENT-LOOP.md §6.15）：捕获滞后水位截断——超 CAPTURE_CAP_OPTS.hard 裁至
   // 头 + 标记 + 尾（_capturedOutput 有界；续跑同闭包累积，语义一致）。
   const capture = callbacks?.onToken
     ? (t) => { output = appendCappedText(output, stripEventTokensForCapture(String(t)), CAPTURE_CAP_OPTS); child._capturedOutput = output; callbacks.onToken(t) }

package/agent/suspension.mjs

@@ -1,5 +1,5 @@
 /**
- * agent/suspension.mjs — §17 挂起 / 唤醒驱动（核内形态——AGENT-LOOP.md §2.3 #184 定案）。
+ * agent/suspension.mjs — 挂起 / 唤醒驱动（核内形态——AGENT-LOOP.md §2.3 #184 定案；机制面 = AGENT-LOOP-ASYNC-POOL.md §6.8）。
  *
  * 语义（两端同源，逐字承两端现行挂起驱动——CLI 侧 tui 面 / VSC 侧 extension 面，同语义移植）：
  * 回合尾后台池仍 live → 挂起会话——池项 settle → 入 pending；pending 非空 **或存在未 drain 的
@@ -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
+}