@thincoder/core 0.9.4 → 0.10.1

package/agent/helpers.mjs

@@ -85,6 +85,38 @@ const MAX_GIT_CHANGES_DISPLAY = 20
 export const OUTLINE_INJECT_PREFIX = "[System reminder: project dependency outline:"
 export const FILE_MUTATORS = new Set(["write", "edit", "insert_after", "apply_patch", "delete", "hashline_edit"])
 
+/**
+ * 工具自报触达面提取**单源谓词**（`docs/core/design/TOOLS.md` §6.17 / D-TO12——批 GUARD-SCHEDULER ·
+ * 台账 #327）：与 `FILE_MUTATORS` 同址（门禁 / 变更记账 / L3 足迹 / 作用域规则四条面的公共输入）。
+ * 契约（恒数组 · 恒零抛）：
+ * - `args` 为 null **或非对象** ⇒ 一律规范化为 `{}` 再交钩子；
+ * - 有钩子 ⇒ **钩子裁决**；无钩子 ⇒ `file_ops` **动作感知**（D-TO13 · 台账 #333）——`action === "copy"`
+ *   ⇒ `[args.dest]`（源仅读取，不属写域）；`move` / `rename` / 未知或缺失 `action` ⇒ `[args.source,
+ *   args.dest]`（保守双算）；其余工具单参兜底（形态零变——缺 path 同样返含 `undefined` 的单元素
+ *   数组，由消费方按「未知路径 ⇒ 保守」自行判定）；
+ * - 钩子 throw / 返回非数组 ⇒ `[]`；
+ * - **不过滤非字符串项**（未知路径的保守判据归门禁自身——`thincoder-cli/test/portability-classification.test.mjs`
+ *   T-22 语义零变）。
+ * @param {Object|undefined} tool — 工具对象（可选钩子 `touchedPaths(args)`）
+ * @param {unknown} args — 工具入参（畸形入参不抛）
+ * @returns {unknown[]} 触达路径候选（可能含非字符串项——消费方过滤）
+ */
+export function toolTouchPaths(tool, args) {
+  const a = args && typeof args === "object" ? args : {}
+  const hook = tool?.touchedPaths
+  if (typeof hook !== "function") {
+    if (tool?.name === "file_ops") return a.action === "copy" ? [a.dest] : [a.source, a.dest]
+    return [a.path]
+  }
+  try {
+    const out = hook(a)
+    return Array.isArray(out) ? out : []
+  } catch {
+    return []
+  }
+}
+
+
 /** Escape XML special characters in a string for safe embedding in XML/HTML */
 export function escapeXml(s) {
   return String(s).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;")
@@ -210,7 +242,7 @@ export class ContinueError extends Error {
   }
 }
 
-/** §17 D-S6 auto-turn guard 标记集（核内单源）：快照/回填两 helper 共用本清单——
+/** AGENT-LOOP-ASYNC-POOL.md §6.8 D-S6 auto-turn guard 标记集（核内单源）：快照/回填两 helper 共用本清单——
  *  端侧宿主载体（`panel._guardCarry`）与核载体（`agent._inheritedGuard`）同清单。 */
 export const INHERITED_GUARD_KEYS = [
   "_mutatedThisRun", "_verifiedThisRun", "_verifyPassed", "_calledAdvisorThisRun",
@@ -231,7 +263,7 @@ export function restoreGuard(target, snap) {
   for (const k of INHERITED_GUARD_KEYS) if (k in snap) target[k] = snap[k]
 }
 
-/** 跨段累计编号帧（TURN-CAP-CONTINUE.md §19.3——第 19 批 TURN-ACROSS-SEGMENTS）：
+/** 跨段累计编号帧（TURN-CAP-CONTINUE.md §4——第 19 批 TURN-ACROSS-SEGMENTS）：
  *  唯一计算点（纯函数）——把链内累计序数换算成面向消费面的编号载荷。
  *  - seq      = 该轮链内累计序数（1 起——`agent._turnSeq` 每轮 +1，续跑不重置）
  *  - turn     = 段内轮号（0 起——段内帽判定的循环变量）
@@ -337,6 +369,25 @@ export function readonlyToolNames(tools) {
   return new Set(tools.filter((t) => t.readonly).map((t) => t.name))
 }
 
+/** Depth>0 tool exclusions — subagents never get the interactive main-session tools (`question`:
+ *  no user to ask; the routing guidance already lives in every persona file). Single source for
+ *  the repo: the shell-side depth>0 filter consumes this set (design = TOOLS.md §6.16 / D-TO11). */
+export const SUBAGENT_TOOL_EXCLUSIONS = new Set(["question"])
+
+/** Apply the depth>0 exclusion set — always returns a NEW array (parent table untouched).
+ *  #9（TOOLS.md §6.19）：`bash` 的 `async` 参仅 depth-0——子代副本删参（照 `family-tools.mjs:98`
+ *  先例；返回值仍恒新数组、未命中条目原对象直传）。运行期第二道在 `tools/bash.mjs` execute
+ *  （照 `read_image`「schema 门 + 运行期第二道」双线先例）。 */
+export function excludeSubagentTools(tools) {
+  return tools
+    .filter((t) => !SUBAGENT_TOOL_EXCLUSIONS.has(t.name))
+    .map((t) => {
+      if (t.name !== "bash" || !t.parameters?.properties || !("async" in t.parameters.properties)) return t
+      const { async: _asyncDrop, ...restProps } = t.parameters.properties
+      return { ...t, parameters: { ...t.parameters, properties: restProps } }
+    })
+}
+
 const MAX_INSTRUCTION_CHARS = 32_000
 
 /** Load AGENTS.md / project_rules.md from user home and project root.
@@ -374,7 +425,7 @@ export async function loadProjectInstructions(cwd) {
 
 /** Engineering mode reminder — shared with eng.mjs tool. */
 export const ENG_ON_REMINDER =
-  "[System reminder: engineering mode is ON — design-before-code enforced. " +
+  "[System reminder: engineering mode is ON (session-scoped) — design-before-code enforced. " +
   "Workflow: Requirements doc → Design doc → advisor(type='design') → " +
   "user approval → eng-coder implementation. Code changes go through eng-coder " +
   "subagents only. Advisor calls are NOT per-turn-mandatory — call only at " +
@@ -408,6 +459,15 @@ export const AUTO_TURN_DIGEST_DOMAIN_ENG =
 export const UPSTREAM_TURN_DOMAIN =
   "[System reminder: auto-turn — a running subagent sent you an in-flight message (shown below). No user message is waiting. Decide it now and reply with subagent action:'send' (id + message) — the child consumes the reply at its next turn boundary and keeps working on the unaffected parts; if the message needs no answer, say so in one line and move on. If finished subagent reports are also present above, summarize them as usual in the same turn. Do not start new work: FORBIDDEN this turn (mechanically enforced): modifying files, bash/execute/verify, spawning subagents, asking questions — those need a real user message. End the turn once the reply is sent.]"
 
+/** Timer wake-turn domain (AGENT-LOOP-ASYNC-POOL.md §6.30.3 D-TW4): a pending timer
+ *  expired while the session was idle and the end's latch opened this turn automatically —
+ *  neither the digest domain ("no one is waiting", organize-only) nor the up-stream domain
+ *  (a subagent waiting for a reply) fits: the timer's own semantics is "act on what the
+ *  timer was for". Verbatim from the parent-side final text (single line — no newlines).
+ *  Content authority = parent side. */
+export const TIMER_TURN_DOMAIN =
+  "[System reminder: auto-turn — a timer you set earlier has expired (reminder above). No user message is waiting. Act on what the timer was for now: pull the data or run the check rather than continuing to reason in the abstract. Stay within the work that was in flight when the timer was set; do not open unrelated new work. Wrap up as soon as the action is done or blocked.]"
+
 /** Engineering-mode status injection — one reminder on EVERY transition (2026-08-25:
  *  OFF is announced too — the model must know the gates lifted; silence after /eng-off
  *  left it guessing. Covers TUI /eng, resume, and any path bypassing the eng tool.) */

package/agent/live-beat.mjs

@@ -0,0 +1,49 @@
+/**
+ * agent/live-beat.mjs — 存活投影心跳（拍间隔 ∕ 单拍 ∕ 起 ∕ 停 —— 幂等 · 清点）——「桌面处理流 · VSC 对齐」批 R6 上提产物。
+ *
+ * 上提源（迁移前坐标）= VSC `thincoder-vscode/src/extension/panel-messages.mjs:45`（`LIVE_HEARTBEAT_MS = 2000`）
+ * `:50`（单拍 `liveHeartbeatBeat`）`:62-75`（起 ∕ 停 `startLiveHeartbeat` ∕ `stopLiveHeartbeat`）；
+ * 桌面先例 = `thincoder-desktop/src/main/subagent-face.mjs`（拍体逐键清点）。**纯搬 + 转口，零语义改**：
+ * 拍间隔 ∕ 单拍 ∕ 起停 ∕ 幂等 ∕ 清点入核。两处 VSC 端面判据**随拍体留端**（非本档语义）：
+ * 「未就绪不拍」前置（`panel._wvReady`）与拍日志（`ev:subreassert`）。
+ *
+ * 拍体（`beat` 注入）= 各端存活再断言本体：VSC = `reassertLiveChildren(panel)`（`thincoder-vscode/src/
+ * extension/suspension.mjs:148` 投影面）；桌面 = 逐键 `bridge(key).reassertLive(agent)`（只发在飞实例）。
+ * 回值 = 本拍投递条数（**清点**读数 —— 拍体自清点，本档原样透传）。
+ * **`setInterval` ∕ `unref` 转注入缝**：`timer(fn, ms) ⇒ handle` ∕ `clear(handle)` 由调用方注入
+ * （缺省 = 平台 `setInterval` ∕ `clearInterval`；句柄 `unref` = 可选面 —— 在场即调，不阻进程退出）。
+ * 消费面 = 桌面 `thincoder-desktop/src/main/subagent-face.mjs` · VSC `panel-messages.mjs` 拍家族——已随 parity-b4
+ * 迁移轮改指本档（2026-09-29，双写窗口收口；两处 VSC 端面判据随拍体留端）。
+ */
+
+/** 拍间隔（毫秒）——单源（VSC 同值 `panel-messages.mjs:45`）：起拍即按此周期。 */
+export const LIVE_HEARTBEAT_MS = 2000
+
+/**
+ * 起 ∕ 停 ∕ 单拍（幂等）：
+ *  - `beat()` = 单拍直驱（回值 = 本拍投递条数 —— 测试直驱面 ∕ 手动补拍）；
+ *  - `start()` = 起拍（**单拍幂等**：已起 ⇒ 返既有句柄、零重起）；回值 = 定时器句柄；
+ *  - `stop()` = 停拍（未起 ⇒ 零动作）；停后 `start()` 可再起（新句柄 —— 起 ∕ 停两向）。
+ * `timer` ∕ `clear` = 定时器注入缝（缺省 = 平台全局；假钟注入 ⇒ 平 node 直测）。`beat` 缺 ∕ 非函数 ⇒ 抛
+ * （fail-loud —— 拍体未接线不得静默空转成「零投拍」）。
+ */
+export function createLiveBeat({ beat, timer = (fn, ms) => setInterval(fn, ms), clear = (handle) => clearInterval(handle) } = {}) {
+  if (typeof beat !== "function") {
+    throw new TypeError("createLiveBeat: beat seam missing — inject the beat function (the projection must not silently idle)")
+  }
+  let handle = null
+  return {
+    beat,
+    start() {
+      if (handle !== null) return handle
+      handle = timer(beat, LIVE_HEARTBEAT_MS)
+      handle?.unref?.() // 不阻进程退出（句柄可选面）
+      return handle
+    },
+    stop() {
+      if (handle === null) return
+      clear(handle)
+      handle = null
+    },
+  }
+}

package/agent/post-turn.mjs

@@ -4,6 +4,7 @@
  * stall detection, and goal status tracking.
  */
 import { escapeXml, tryCanonicalize, DEFAULT_GOAL_TURNS } from "./helpers.mjs"
+import { takeExpiredTimers, injectTimerReminders } from "./timers.mjs"
 
 export const STALL_WINDOW_SIZE = 5
 export const STALL_THRESHOLD = 3
@@ -15,14 +16,9 @@ export const GOAL_BUDGET_WARN_RATIO = 0.75
  */
 export function injectPostTurn(agent, results, recentCallSigs, callbacks, turn) {
   // Expired timers — inject reminders when thinking budget is up
-  if (agent._pendingTimers.length > 0) {
-    const now = Date.now()
-    const expired = agent._pendingTimers.filter((t) => t.expiresAt <= now)
-    agent._pendingTimers = agent._pendingTimers.filter((t) => t.expiresAt > now)
-    for (const t of expired) {
-      agent.history.push({ role: "user", content: `[System reminder: ⏰ timer — ${t.message}]` })
-    }
-  }
+  // AGENT-LOOP-ASYNC-POOL.md §6.30.2：过滤 / 注入语义单源于 `agent/timers.mjs`（CLI 空闲闩 /
+  // 挂起窗同读）；本处 = 回合边界轮询调用点——行为零变（最近到期 / 出列幂等 / 逐字形态逐条不变）。
+  injectTimerReminders(agent, takeExpiredTimers(agent))
 
   // Pending reminders
   if (agent._pendingReminders.length > 0) {

package/agent/record-results.mjs

@@ -25,7 +25,7 @@
  */
 import { pushReal } from "../context.mjs"
 import { specForModel } from "../config.mjs"
-import { FILE_MUTATORS } from "./helpers.mjs"
+import { FILE_MUTATORS, toolTouchPaths } from "./helpers.mjs"
 import { resolve } from "node:path"
 import { advisorRuns, stripApprovedSuffix } from "../agent-tools/advisor-async.mjs"
 import { looksLikeReviewOutput, advisorIncompleteMarker } from "../advisor/run.mjs"
@@ -78,7 +78,7 @@ export async function recordToolResults(agent, toolByName, results) {
         // Direct file edit — code was changed. The prior advisor review and
         // verify are stale: a review that ran before the edit no longer
         // covers the current file state.
-        // §29 fix A（AGENT-LOOP.md §29——2026-09-07）：mutation-seq 记账已移到 dispatch
+        // fix A（2026-09-07）：mutation-seq 记账已移到 dispatch
         // runOne 执行成功即刻（唯一记账点——取代本批后段 + agent.mjs 中断分支——不双计）——
         // 此处仅剩 guard 标志失效（顺序语义：批内同消息的 sync advisor 提交仍在其后置位）。
         agent._mutatedThisRun = true
@@ -100,7 +100,7 @@ export async function recordToolResults(agent, toolByName, results) {
       }
       if (toolCall.name === "verify") agent._verifiedThisRun = true
       if (toolCall.name === "advisor") {
-        // §11.2 D-24b (settle accounting split — fix #2): an ASYNC launch returns an
+        // AGENT-LOOP-ASYNC-POOL.md §6.10 D-24b (settle accounting split — fix #2): an ASYNC launch returns an
         // ack and settles later — the settle callback owns its called/round/token
         // accounting. Only the SYNC path (depth>0 / explicit async:false) accounts
         // here — per-review instance round++ (marker-keyed by tool call id) + the
@@ -117,7 +117,7 @@ export async function recordToolResults(agent, toolByName, results) {
         } else {
           const reviewId = agent._advisorSyncCalls?.get(toolCall.id)
           const run = reviewId !== undefined ? advisorRuns(agent).get(reviewId) : undefined
-          // F16 同步面（第 13 批 §15.2——ADVISOR-CONVERGENCE.md §15）：未完成尾 + 非设计面
+          // F16 同步面（第 13 批——ADVISOR-GUARDS.md §6）：未完成尾 + 非设计面
           // （含类型不可判——run 缺失的 legacy 直调）⇒ 不置「已覆盖」（与 settle 面
           // 逐条 parity；设计评审保持计入——无代码面）。
           const incomplete = advisorIncompleteMarker(String(result))
@@ -127,7 +127,7 @@ export async function recordToolResults(agent, toolByName, results) {
               run.round++
               agent._advisorRound = run.round
               // Prior of round 2+ = the last REVIEW-LOOKING output (run.mjs parity).
-              // F2e (§29.1): the sync settle's engine-approved suffix (stored on the
+              // F2e: the sync settle's engine-approved suffix (stored on the
               // run by settleDesignReview) is stripped with exact truncation — the
               // prior never carries the raw token / designId.
               if (looksLikeReviewOutput(result)) {
@@ -145,23 +145,26 @@ export async function recordToolResults(agent, toolByName, results) {
         }
       }
       if (FILE_MUTATORS.has(toolCall.name)) {
-        const args = JSON.parse(toolCall.arguments)
-        const paths = tool.touchedPaths ? tool.touchedPaths(args) : [args.path]
-        for (const p of paths) {
-          const abs = resolve(agent.cwd, p)
-          if (!agent._touchedFiles.includes(abs)) agent._touchedFiles.push(abs)
-          if (agent.memory) {
-            // Fire-and-forget: don't block the agent loop on indexing.
-            // Reuses a single cached import; errors surface as pending reminders on next turn.
-            if (!_reindexFile) {
-              const mod = await import("../memory.mjs")
-              _reindexFile = mod.reindexFile
+        try {
+          const args = JSON.parse(toolCall.arguments)
+          const paths = toolTouchPaths(tool, args)
+          for (const p of paths) {
+            if (typeof p !== "string" || !p) continue // 非字符串项不拖累合法路径（与 dispatch / VSC 消费面同口径）
+            const abs = resolve(agent.cwd, p)
+            if (!agent._touchedFiles.includes(abs)) agent._touchedFiles.push(abs)
+            if (agent.memory) {
+              // Fire-and-forget: don't block the agent loop on indexing.
+              // Reuses a single cached import; errors surface as pending reminders on next turn.
+              if (!_reindexFile) {
+                const mod = await import("../memory.mjs")
+                _reindexFile = mod.reindexFile
+              }
+              _reindexFile(agent.memory, agent.cwd, abs).catch((e) => {
+                agent._pendingReminders.push(`[System reminder: background indexing failed for ${toolCall.name} on ${abs}: ${e.message}. This does not affect your work — the code index will catch up on next reindex.]`)
+              })
             }
-            _reindexFile(agent.memory, agent.cwd, abs).catch((e) => {
-              agent._pendingReminders.push(`[System reminder: background indexing failed for ${toolCall.name} on ${abs}: ${e.message}. This does not affect your work — the code index will catch up on next reindex.]`)
-            })
           }
-        }
+        } catch { /* #327：畸形 args（含 null）/ 畸形路径不再裸抛——touchedFiles 尽力而为 */ }
       }
     }
   }

package/agent/relay-prefix.mjs

@@ -1,9 +1,9 @@
 /**
- * relay-prefix.mjs — relay 前缀（`role#id/`）文法**单一权威**（第 27 批 §12.3①——R-A2.3）。
+ * relay-prefix.mjs — relay 前缀（`role#id/`）文法**单一权威**（第 27 批——R-A2.3）。
  *
  * 零依赖（不 import 任何模块）——TUI（`src/tui/`）与 ACP（`src/acp/`）双向可导入，无环；
  * 生成侧 `src/agent/spawn-child.mjs` 再导出（枢纽）。文法 = 自
- * `src/tui/subagent-blocks.mjs` 逐字迁入（第 27 批 §12.3②——零语义改动）。
+ * `src/tui/subagent-blocks.mjs` 逐字迁入（第 27 批——零语义改动）。
  */
 
 /** `role#id/` prefix router — hyphen included since the eng-coder fix (2026-08-21). */

package/agent/run-stages.mjs

@@ -15,11 +15,12 @@ import { logEvent, errText } from "../log.mjs"
 // ASYNC-RESULT-CONTAINER.md D1：池 accessor（absorb 双池——advisor 独立池无队列）
 import { getAsyncPool, releaseSettledEntry } from "../agent-tools/async-settle.mjs"
 // 批 4 CLI-ASYNC-DISCARD（AGENT-LOOP-ASYNC-POOL.md §6.20）：中止分支「只清已死」收尾单点
-import { discardAbortedPool, discardAbortedAdvisors } from "../agent-tools/async-discard.mjs"
+// （#9：+ 后台 bash 任务族——逐条杀树 + 出池 + 墓碑）
+import { discardAbortedPool, discardAbortedAdvisors, discardAbortedBgTasks } from "../agent-tools/async-discard.mjs"
 // R10 L3 (MULTI-INSTANCE-COLLAB §2a.5 D-L3a)：回合末域登记 flush（写工具钩子累积 →
 // 整写一次本实例 peers 文件——无写入跳过；失败容忍不抛）
 import { flushPeerDomains } from "../peer-domains.mjs"
-// 第 30 批 D1（Stop 钩子——AGENT-LOOP.md §21）：主会话 run 终止事件（触发块见 finalizeAgentTurn）
+// 第 30 批 D1（Stop 钩子——AGENT-LOOP.md §6.13）：主会话 run 终止事件（触发块见 finalizeAgentTurn）
 import { runHooks } from "../hooks.mjs"
 
 /**
@@ -164,14 +165,14 @@ export async function finalizeAgentTurn(agent, ctx) {
       },
     }).catch(() => {})
   }
-  // R17（AGENT-LOOP.md §25 D-R17a）: consultation sessions are cross-turn
+  // R17（CONSULTATION.md §6.2）: consultation sessions are cross-turn
   // background work now — NO unconditional turn-end cleanup (the old rule aborted
   // leftover consult children at every turn end because check-loop consumption was
   // turn-scoped). Sessions stay alive across normal turn ends (and ContinueError
   // resumes); the Ctrl+C abort branch below is the only path that aborts them
   // (cleanupConsultSessions — marked stopped → no digest), and the suspension
   // driver aborts them on its own abort unwind.
-  // Async subagent turn-end handling (AGENT-LOOP.md §15 D-A3 + §17 D-S1). Lifecycle:
+  // Async subagent turn-end handling (AGENT-LOOP-SUBAGENT.md §6.7.3 D-A3 + AGENT-LOOP-ASYNC-POOL.md §6.8 D-S1). Lifecycle:
   // - Ctrl+C (plain abort): children were aborted with the parent signal — discard dead
   //   entries (tombstone/out-of-pool/notice — AGENT-LOOP-ASYNC-POOL.md §6.20; no stale
   //   errors injected — user explicitly stopped); consultation sessions are cross-turn
@@ -188,12 +189,15 @@ export async function finalizeAgentTurn(agent, ctx) {
   if (signal?.aborted && !signal?.reason?.interrupt) {
     const subPool = getAsyncPool(agent, "subagent")
     const advPool = getAsyncPool(agent, "advisor")
-    if ((subPool?.size ?? 0) > 0 || (advPool?.size ?? 0) > 0) {
-      logEvent("ev:stopped", { poolN: (subPool?.size ?? 0) + (advPool?.size ?? 0), where: "turn-end-abort" })
+    const bgPool = getAsyncPool(agent, "bg") // #9：后台 bash 任务池（第三域）
+    if ((subPool?.size ?? 0) > 0 || (advPool?.size ?? 0) > 0 || (bgPool?.size ?? 0) > 0) {
+      logEvent("ev:stopped", { poolN: (subPool?.size ?? 0) + (advPool?.size ?? 0) + (bgPool?.size ?? 0), where: "turn-end-abort" })
     }
-    // §6.20：只清已死条目（存活/已 settle 留池——收尾见 async-discard.mjs；原无条件清池已弃）。
+    // §6.20：只清已死条目（存活/已 settle 留池——收尾见 async-discard.mjs；原无条件清池已弃）；
+    // #9：后台 bash 任务同面（杀 ⟺ 控制器已中止——逐条杀树 + 出池 + 墓碑）。
     discardAbortedPool(agent)
     discardAbortedAdvisors(agent)
+    discardAbortedBgTasks(agent)
     // R17: the consult family dies with the user stop (marked stopped — no digest).
     cleanupConsultSessions(agent)
     // ASYNC-RESULT-CONTAINER.md D2：pending 单容器——中止丢弃 consult/escalate 族停靠
@@ -204,7 +208,7 @@ export async function finalizeAgentTurn(agent, ctx) {
     // keep _asyncSubagents/_asyncAdvisors/_consultSessions — the resumed run continues them
   } else {
     const injectedAdvisor = await collectSettledAsync(agent, { suspDriven })
-    // §11.2 D-24b: a normally-ended USER run with no review/child activity closes
+    // AGENT-LOOP-ASYNC-POOL.md §6.10 D-24b: a normally-ended USER run with no review/child activity closes
     // the OPEN code instances — the converged/abandoned thread must not burn the
     // 5-round cap of a later task (the next code review starts a fresh round 1).
     // Digest auto-turns are exempt (their disposition precedes the fix round).
@@ -217,7 +221,7 @@ export async function finalizeAgentTurn(agent, ctx) {
     }
   }
   agent._inAutoTurn = false
-  // §17 D-S6: auto-turn guard marks survive into the next USER run (restored at its
+  // AGENT-LOOP-ASYNC-POOL.md §6.8 D-S6: auto-turn guard marks survive into the next USER run (restored at its
   // !resume reset above). Normal ends only — abort discards; ContinueError lets the
   // auto-resumed run snapshot at its own end.
   if (autoTurn && !(signal?.aborted && !signal?.reason?.interrupt) && !(thrownError instanceof ContinueError)) {
@@ -236,13 +240,13 @@ export async function finalizeAgentTurn(agent, ctx) {
  *   queued STAY — no allSettled wait. Results never lost without a session.
  * - suspDriven=true (the interaction layer runs suspensionSession after this
  *   run): NO direct inject — settled entries STAY pooled (settled not consumed)
- *   for the session's first sweepSettledToPending → digest turn (§17.5 — done
- *   条目留池等消化轮注入；status 在 sweep 前仍从池读——17.5.2 不变面（§19.8：check 已删——自动通道为唯一消费方）)。
+ *   for the session's first sweepSettledToPending → digest turn (AGENT-LOOP-ASYNC-POOL.md §6.8 — done
+ *   条目留池等消化轮注入；status 在 sweep 前仍从池读——17.5.2 不变面（AGENT-LOOP-SUBAGENT.md §6.7.5：check 已删——自动通道为唯一消费方）)。
  * maybeRefillAsync runs in both modes (starts queued heads whose slot freed).
  * Single ownership: entries settled inside a suspension session were moved to
  * _pendingAsyncResults by the settle callback, so this only sees user-turn
- * settles (no double inject — D-S3 points ①/②). The ⟦ev⟧done freeze is NOT
- * emitted here — each settle callback emits it (§15 D-A3).
+ * settles (no double inject — D-S3 points ①/②). settle 回调只发 ⟦ev⟧settled；
+ * ⟦ev⟧done 冻结落消费窗（#746 · ASYNC-POOL §6.8）。
  * 2026-09-05 实践轮：自 agent.mjs 迁入（agent.mjs 内仅 finalize 引用——随收尾同迁）。
  */
 async function collectSettledAsync(agent, { suspDriven = false } = {}) {
@@ -250,14 +254,14 @@ async function collectSettledAsync(agent, { suspDriven = false } = {}) {
   if (maps.length === 0) return false
   const { maybeRefillAsync, injectAsyncResult } = await import("../agent-tools/subagent.mjs")
   maybeRefillAsync(agent) // start queued heads now that slots may have freed — no waiting
-  if (suspDriven) return false // §17.5: settled stays pooled — the suspension session digests it
+  if (suspDriven) return false // AGENT-LOOP-ASYNC-POOL.md §6.8: settled stays pooled — the suspension session digests it
   let injectedAdvisor = false
   for (const map of maps) {
     for (const e of [...map.values()]) {
       if (!e.done) continue // still running — stays in the pool (D-S1)
       await injectAsyncResult(agent, e)
       if (e.role === "advisor") injectedAdvisor = true
-      // TUI-OOM-ROOTCAUSE（§23.3.1 消费点①——回合尾收集）：注入完成 → 释放条目持有
+      // TUI-OOM-ROOTCAUSE（AGENT-LOOP.md §6.15 消费点①——回合尾收集）：注入完成 → 释放条目持有
       releaseSettledEntry(e)
       map.delete(String(e.id))
     }

package/agent/run-start.mjs

@@ -0,0 +1,111 @@
+/**
+ * agent/run-start.mjs — runAgent 起跑前段（2026-09-29 P2 三拆：agent.mjs runAgent 段 1
+ * verbatim 迁入——distill 等待 ∕ pendingAsync 注入 ∕ prepareRun ∕ 复位块 ∕ 域文本 ∕ 授权注释块）。
+ * 接口 = beginRun(agent, input, callbacks, opts) → 主循环装配面（`tools` 死绑定去——KD-8）。
+ */
+import { prepareRun } from "./setup.mjs"
+import {
+  restoreGuard, // digest D-S6 读侧单点（AGENT-LOOP-ASYNC-POOL.md §6.8；P2 机制层端差批 §2.18——键清单归核）
+  AUTO_TURN_DIGEST_DOMAIN,
+  AUTO_TURN_DIGEST_DOMAIN_ENG, // §6.15.3（F10 第三面）：工程模式 digest 基座变体（task 指针改批次档 + 台账）
+  UPSTREAM_TURN_DOMAIN, // §6.27.12.8：上行唤醒轮域文本（手动档——ask 轮不沿用 digest 域文本）
+  TIMER_TURN_DOMAIN, // §6.30.3 D-TW4：timer 唤醒轮域文本（第三变体——到期 timer 自动开轮）
+} from "./helpers.mjs"
+
+export async function beginRun(agent, input, callbacks, {
+  depth = 0, signal, overrideTurns, resume = false, autoTurn = false, upstreamTurn = false, timerTurn = false,
+  extraTools = null, injections = null, turnDomainText = null, toolDecorate = undefined,
+} = {}) {
+  // Previous run's async exploration distillation must settle before this run pushes
+  // input (SEND-STALL-DISTILL §2.2 N1) — await first, or its history replace wipes it.
+  if (agent._pendingDistill) {
+    const p = agent._pendingDistill
+    agent._pendingDistill = null
+    await p
+  }
+  // AGENT-LOOP-ASYNC-POOL.md §6.8 D-S3: suspension-settled async results inject before EVERY run's prepareRun
+  // (user + auto-turn); spliced = consumed. collectSettledAsync owns a different
+  // container, so no double-inject across the two consumption points.
+  // ASYNC-RESULT-CONTAINER.md D2 (2026-09-08)：pending 单容器 `_pendingAsyncResults`
+  // +role——四族（subagent/advisor/escalate/consult）统一停靠；注入器按 role 分发
+  // （consult → injectConsultResult；其余 → injectAsyncResult——族分支同 CONSULTATION.md §6.2 D-R17a/b）
+  // ——单容器一处清，不再逐族三段。
+  const pendingAsync = agent._pendingAsyncResults
+  if (pendingAsync?.length) {
+    const { injectAsyncResult } = await import("../agent-tools/subagent.mjs")
+    const { injectConsultResult } = await import("../agent-tools/consult.mjs")
+    // TUI-OOM-ROOTCAUSE（AGENT-LOOP.md §6.15 消费点②——run 起始 pending 注入）：
+    // 注入完成后释放条目对子代理对象的持有（childAgent/report 置空——幂等 helper）。
+    const { releaseSettledEntry } = await import("../agent-tools/async-settle.mjs")
+    for (const e of pendingAsync.splice(0)) {
+      if (e.role === "consult") await injectConsultResult(agent, e)
+      else await injectAsyncResult(agent, e)
+      releaseSettledEntry(e)
+    }
+  }
+  agent._inAutoTurn = autoTurn // spawn gate for manual-tier digests (AGENT-LOOP-ASYNC-POOL.md §6.8 D-S6/N3；上行唤醒轮同持 autoTurn——§6.27.12.4 ①)
+  const { maxTurns, threshold, toolSchemas, toolByName, systemPrompt } = await prepareRun(
+    // G1/G2（施工②）：prompt 装配收口 prepareRun 内部（assemblePrompt——prompt-overlays.mjs
+    // 槽位常量，与子代理角色常量同源——单一权威锚 D1）；本调用不再携带 prompt 常量。
+    agent, input, callbacks,
+    { depth, signal, overrideTurns, resume: resume || autoTurn, extraTools, injections, toolDecorate },
+  )
+
+  // Exploration-distillation boundary (CONTEXT-COMPACTION §5): prepareRun already
+  // pushed input + injections — appended from here counts as "this run's" work.
+  agent._runStartHistoryLen = agent.history.length
+
+  // Per-run bookkeeping reset — PRESERVED on `resume` (ContinueError continuation):
+  // mutation/guard continuity and the convergence budget must survive a continuation.
+  // §2.3 链内段数（TURN-CAP-CONTINUE.md §4）：首段 1、每次续跑 +1——复位条件同 `_turnSeq`
+  // （链起点复位、续跑不回退）；消费面 = 检查点 ask 载荷 / 池条目留痕二元。
+  agent._continueSegments = resume ? (agent._continueSegments ?? 1) + 1 : 1
+  // #417（撞帽载荷「本段零落盘轮数」——只报数：零阈值常量 / 零自动动作）：段起点复位（首段 /
+  // 续跑新段——与 `_continueSegments` 同点）；段内累加，采集点在回合环（与 `_turnSeq` 同源面）。
+  agent._zeroWriteTurns = 0
+  if (!resume) {
+    // 第 19 批（TURN-ACROSS-SEGMENTS——设计 TURN-CAP-CONTINUE.md §4）：链内累计编号
+    // 只在链起点复位——续跑（resume:true）不重置、不回退（编号帧公式见 helpers.mjs
+    // turnFrame）。与下方 mutation/guard 复位同条件同点（全档唯一复位点）。
+    agent._turnSeq = 0
+    // AGENT-LOOP-ASYNC-POOL.md §6.8 D-S6: an auto-turn's guard marks are inherited by the next USER run (not
+    // reset) so auto-turn changes never escape the guard silently.
+    const g = agent._inheritedGuard
+    if (g) {
+      restoreGuard(agent, g)
+      agent._inheritedGuard = null
+    } else {
+      agent._mutatedThisRun = false
+      agent._verifiedThisRun = false
+      agent._verifyPassed = undefined
+      agent._calledAdvisorThisRun = false
+      agent._touchedFiles = []
+      agent._verifyRetries = 0
+      agent._advisorRound = 0
+      agent._advisorSession = null // advisor session is per-run: discard when the task ends, next task starts fresh
+      agent._emptyRetries = 0 // empty-response retry budget is per-run: a fresh user turn restarts from zero
+      agent._compressFailures = 0 // compaction summary-failure counter is per-run: a fresh user turn restarts from zero
+      // F-CC2（§6.16.2）：模型主动压缩的排队槽也是回合级——上一回合末尾未被安全点消费的请求不得跨回合生效
+      agent._pendingCompact = null
+    }
+  }
+  // digest D-S6 manual tier（AGENT-LOOP-ASYNC-POOL.md §6.8）: action-domain reminder (system-driven turn — organize only).
+  // §6.27.12.4 ②: an up-stream wake turn answers a RUNNING subagent waiting for the reply — it
+  // must not reuse the digest text ("no one is waiting" is the opposite of the truth).
+  // §6.30.3 D-TW4: timer wake turn (third auto-turn variant) — 到期 timer 自动开轮，仅作域文本选择
+  // （`upstreamTurn` 优先不回归：ask 轮是「有人在等回复」，比 timer 轮更紧）。
+  if ((autoTurn || upstreamTurn) && !agent.autoApprove) {
+    // §2.5-A3（P4-I）：端壳经 `opts.turnDomainText` 供「核基座 + 端 overlay」组合串（组合点 =
+    // 端 `turn-domains.mjs` composeTurnDomain）；缺省（null）⇒ 核基座逐字零变（选择序不变）。
+    const domainBase = upstreamTurn ? UPSTREAM_TURN_DOMAIN : timerTurn ? TIMER_TURN_DOMAIN : (agent.config?.agent?.engineering === true ? AUTO_TURN_DIGEST_DOMAIN_ENG : AUTO_TURN_DIGEST_DOMAIN)
+    agent.history.push({ role: "user", content: turnDomainText ?? domainBase, transient: true })
+  }
+  // eng-coder authorization (_engDesignReviewed) is eng-coder-only: set by subagent-spawn.mjs
+  // (spawn gate) / design-token.mjs (design review pass) BEFORE the child runAgent — the
+  // depth-0 parent never reads or writes it (the parent gate reads anyLiveDesignSlot; the
+  // depth-0 per-turn reset was removed 2026-09-08, ENG-SESSION-PROVIDER-CLEANUP D1.3).
+  // Design slots (_engDesignTokens Map) survive across turns (design review → approval →
+  // eng-coder spawn) — persisted to the session slot at settle time (DESIGN-TOKEN-
+  // SETTLEMENT D1); lifecycle: issued on a passing review, consumed by consume-design / TTL.
+  return { maxTurns, threshold, toolSchemas, toolByName, systemPrompt }
+}

package/agent/setup-reminders.mjs

@@ -3,7 +3,7 @@
  * (SESSION.md §6.11 — 2026-09-06 需求池 R5/R8/R9/R11 合并设计; R10 L1 peer 注入同文件).
  *
  * One unified transient user reminder per turn covers the whole self-awareness
- * family: env identity (R8 — §6.10 D-1 END 常量先例：静态常量，不做 cmdline 判别),
+ * family: env identity (R8 — §6.10 D-1 端名先例：值 = 进程端名（§6.20 端名缝 sessionEnd()），不做 cmdline 判别),
  * engineering mode (R9), active model (R11), session slot (F1), restart awareness
  * (R5 resumed). §6.11（2026-09-08）：resumed 按会话跟踪——恢复事件由 session.mjs
  * applySession 武装（agent._envResumed——载入历史非空 = 恢复）；进程重启句独立走
@@ -29,16 +29,16 @@
  */
 import { statSync } from "node:fs"
 import { resolve } from "node:path"
-import { END } from "../session-slots.mjs"
+import { sessionEnd } from "../session-slots.mjs"
 import { peerInstances } from "../peer-instances.mjs"
 import { specForModel } from "../config.mjs"
 import { manifestFilePath, readManifest, projectView } from "../manifest.mjs"
 
-/** env-state line builder — pure, unit-testable.
+/** env-state line builder — 对入参 + 进程端名确定（§6.20 端名缝 sessionEnd()；setSessionEnd 注入 ⇒ 单测可用）。
  *  §6.11（F1）：slot 字段入行——位置在 model 后 resumed 前（N3：无绑定 → 显式 null——
  *  不读 manifest active 共享指针——粘性 _slot 才是"本 agent 之槽"）。 */
 export function envStateLine({ mode, model, slot, resumed }) {
-  return `[System reminder: env: ${END}, mode: ${mode}, model: ${model}, slot: ${slot}, resumed: ${resumed ? "yes" : "no"}.]`
+  return `[System reminder: env: ${sessionEnd()}, mode: ${mode}, model: ${model}, slot: ${slot}, resumed: ${resumed ? "yes" : "no"}.]`
 }
 
 /**
@@ -63,16 +63,16 @@ export function pushEnvStateReminder(agent) {
 /** 情境行前缀——本行族识别符（摘旧行 / 会话重建认领同用；行形逐字见 manifestStateLine）。 */
 const MANIFEST_LINE_PREFIX = "[System reminder: project state: "
 
-/** phase → discipline 标签映射（判据单源 = 需求 v2 §9.1）；未知值不在表内 → 无标签。 */
-const MANIFEST_DISCIPLINE = Object.freeze({ "initial-dev": "light", production: "strict" })
+/** phase → rigor 标签映射（判据单源 = 需求 v2）；未知值不在表内 → 无标签。 */
+const MANIFEST_RIGOR = Object.freeze({ "initial-dev": "light", production: "strict" })
 
 /** 情境行构造 — pure, unit-testable（模块契约 `docs/core/design/MANIFEST.md` §2.6，与
  *  envStateLine 同族）。行形逐字（**单字段**——2026-09-17 裁撤批后）：
- *  `[System reminder: project state: phase: <值> (discipline: <light|strict>).]`
+ *  `[System reminder: project state: phase: <值> (rigor: <light|strict>).]`
  *  未知 phase → 只出值、不编判据（无标签）。 */
 export function manifestStateLine({ phase }) {
-  const discipline = MANIFEST_DISCIPLINE[phase]
-  return `${MANIFEST_LINE_PREFIX}phase: ${phase}${discipline ? ` (discipline: ${discipline})` : ""}.]`
+  const rigor = MANIFEST_RIGOR[phase]
+  return `${MANIFEST_LINE_PREFIX}phase: ${phase}${rigor ? ` (rigor: ${rigor})` : ""}.]`
 }
 
 /**