thincoder 0.12.58 → 0.12.60

package/src/agent.mjs

@@ -3,10 +3,10 @@
  * LLM ↔ tool-call loop, until the task is done.
  */
 import { chat } from "./provider/index.mjs"
-import { compressIfNeeded, compressFallback, COMPRESS_FAILURE_LIMIT, pushReal, summarizeRunExplorations } from "./context.mjs"
+import { pushReal, summarizeRunExplorations } from "./context.mjs"
 import { specForModel } from "./config.mjs"
 import { readFileSync } from "node:fs"
-import { join, dirname } from "node:path"
+import { join, dirname, resolve } from "node:path"
 import { fileURLToPath } from "node:url"
 import { executeToolCalls } from "./agent/dispatch.mjs"
 import { recordToolResults } from "./agent/record-results.mjs"
@@ -14,31 +14,28 @@ import { FILE_MUTATORS } from "./agent/helpers.mjs"
 import { prepareRun } from "./agent/setup.mjs"
 import { injectPostTurn } from "./agent/post-turn.mjs"
 import { handleCompletion } from "./agent/completion.mjs"
-import { cleanupConsultSessions } from "./agent-tools/consult.mjs"
+// 主循环阶段函数（压缩检查/注入组/回合收尾）2026-09-05 实践轮迁 agent/run-stages.mjs
+import { runCompactionCheck, injectTurnReminders, finalizeAgentTurn, injectResponseReminders } from "./agent/run-stages.mjs"
 import {
-  escapeXml, repairHistory, listWorkDir, ensureAutoReminder,
+  escapeXml, repairHistory, listWorkDir,
   readonlyToolNames, collectGitContext, loadProjectInstructions,
-  ContinueError, offloadToolResult,
+  ContinueError,
   DEFAULT_MAX_TURNS, DEFAULT_SUBAGENT_TURNS,
   MIN_REPORT_CHARS, REPORT_CONTINUATION,
+  AUTO_TURN_DIGEST_DOMAIN,
 } from "./agent/helpers.mjs"
+// ENG 提醒族 + auto-turn domain 2026-09-05 迁 agent/helpers.mjs（agent.mjs 530 > 500 硬限）
+// overlay 载荷（explore/coder/plan/eng-coder/consult）迁 prompt-overlays.mjs——re-export 保面
+export {
+  EXPLORE_OVERLAY, CODER_OVERLAY, PLAN_OVERLAY, ENG_CODER_OVERLAY, CONSULT_BASE,
+} from "./prompt-overlays.mjs"
+export { ENG_ON_REMINDER, ENG_OFF_REMINDER } from "./agent/helpers.mjs"
 
 // Prompt files (byte-stable, loaded once)
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const SYSTEM_PROMPT = readFileSync(join(__dirname, "prompts", "system.md"), "utf8")
 const DISCIPLINE_RULES = readFileSync(join(__dirname, "prompts", "discipline.md"), "utf8")
 const MAIN_OVERLAY = readFileSync(join(__dirname, "prompts", "main.md"), "utf8")
-let _EXPLORE, _CODER, _PLAN, _ENG_CODER, _CONSULT_BASE
-try { _EXPLORE = readFileSync(join(__dirname, "prompts", "explore.md"), "utf8") } catch { _EXPLORE = "" }
-try { _CODER = readFileSync(join(__dirname, "prompts", "coder.md"), "utf8") } catch { _CODER = "" }
-try { _PLAN = readFileSync(join(__dirname, "prompts", "plan.md"), "utf8") } catch { _PLAN = "" }
-try { _ENG_CODER = readFileSync(join(__dirname, "prompts", "eng-coder.md"), "utf8") } catch { _ENG_CODER = "" }
-try { _CONSULT_BASE = readFileSync(join(__dirname, "prompts", "consult-base.md"), "utf8") } catch { _CONSULT_BASE = "" }
-export const EXPLORE_OVERLAY = _EXPLORE
-export const CODER_OVERLAY = _CODER
-export const PLAN_OVERLAY = _PLAN
-export const ENG_CODER_OVERLAY = _ENG_CODER
-export const CONSULT_BASE = _CONSULT_BASE
 
 // exported for consumption by agent-tools.mjs
 export {
@@ -49,34 +46,9 @@ export {
 }
 
 
-// Engineering mode reminder — shared with eng.mjs tool
-export const ENG_ON_REMINDER =
-  "[System reminder: engineering mode is ON — 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 " +
-  "flow nodes or when the user asks.]"
-
 // Re-exported for API compatibility (single source of truth: advisor/repos.mjs)
 export { hasCodeMutations } from "./advisor/repos.mjs"
 
-/** Engineering mode OFF reminder — shared with the eng tool and the injector. */
-export const ENG_OFF_REMINDER =
-  "[System reminder: engineering mode is now OFF — standard discipline applies. " +
-  "Changes go through the normal workflow: you may edit files directly, advisor/verify " +
-  "guards apply per config.]"
-
-/** 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.) */
-function injectEngineeringReminder(agent) {
-  const eng = agent.config?.agent?.engineering ?? false
-  if (eng !== agent._lastEngState) {
-    agent.history.push({ role: "user", content: eng ? ENG_ON_REMINDER : ENG_OFF_REMINDER, transient: true })
-  }
-  agent._lastEngState = eng
-}
-
 /** Create a new agent state object with all fields initialized to defaults */
 export function createAgent({
   provider, tools, config, cwd, memory, overlay, role,
@@ -90,8 +62,12 @@ export function createAgent({
     planMode, autoApprove, goal,
     _mutatedThisRun: false, _verifiedThisRun: false, _verifyPassed: undefined, _calledAdvisorThisRun: false,
     _engDesignReviewed: false, // eng-coder: design review gate passed (hard gate in dispatch.mjs)
-    _engDesignToken: null, // issued by advisor(type="design"); required to spawn eng-coder
+    // DESIGN-TOKEN-SETTLEMENT D3 (2026-09-08): single-value `_engDesignToken` mirror retired
+    // (AC3 零写) — no field initializer; the multi-slot Map `_engDesignTokens` is the
+    // authoritative ledger (hydrated by restoreEngTokens / written by settle).
     _touchedFiles: [], _verifyRetries: 0, _advisorRound: 0, _advisorSession: null,
+    _advisorRuns: new Map(), // §24 D-24b: per-review convergence instances (rounds/prior/designId)
+    _mutationSeq: 0, _mutLog: [], // §24 D-24b: mutation log (in-flight review staleness scan)
     _lastAdvisorOutput: null, // full review output from the most recent advisor call (convergence rounds inject it verbatim)
     _lastEngState: false,
     _pendingReminders: [],
@@ -107,62 +83,90 @@ export function createAgent({
 }
 
 /** Run the agent loop: LLM ↔ tool-call cycle until task completion or turn limit. Returns final text content. */
-export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal, maxTurns: overrideTurns, resume = false } = {}) {
-  // Previous run's async exploration distillation must settle before this run pushes new
-  // input (SEND-STALL-DISTILL §2.2, N1): the compressed machine line is this run's starting
-  // point — await BEFORE prepareRun, or the history replacement would wipe the new input.
+export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal, maxTurns: overrideTurns, resume = false, autoTurn = false, suspDriven = false, consumeInjected = null } = {}) {
+  // 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
   }
+  // §17 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——族分支同 §25 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")
+    for (const e of pendingAsync.splice(0)) {
+      if (e.role === "consult") await injectConsultResult(agent, e)
+      else await injectAsyncResult(agent, e)
+    }
+  }
+  agent._inAutoTurn = autoTurn // spawn gate for manual-tier digests (§17 D-S6/N3)
   const { maxTurns, threshold, tools, toolSchemas, toolByName, systemPrompt } = await prepareRun(
     agent, input, callbacks,
-    { depth, signal, overrideTurns, resume, systemPrompt: SYSTEM_PROMPT, disciplineRules: DISCIPLINE_RULES, mainOverlay: MAIN_OVERLAY },
+    { depth, signal, overrideTurns, resume: resume || autoTurn, systemPrompt: SYSTEM_PROMPT, disciplineRules: DISCIPLINE_RULES, mainOverlay: MAIN_OVERLAY },
   )
 
-  // End-of-run exploration distillation boundary (CONTEXT-COMPACTION §5): prepareRun has already
-  // pushed the user input + injections, so everything appended from here is "this run's" work.
+  // 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. On `resume` (ContinueError continuation) these are
-  // PRESERVED: the resumed run must keep mutation tracking so the advisor/verify
-  // guards stay active (a guard pushback on the last turn must not silently vanish),
-  // and the convergence budget must not be resettable by continuing the session.
+  // Per-run bookkeeping reset — PRESERVED on `resume` (ContinueError continuation):
+  // mutation/guard continuity and the convergence budget must survive a continuation.
   if (!resume) {
-    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
-    agent._asyncCheckLastN = 0 // subagent_check read counter is per-run (§15 D-A2): a fresh user turn restarts from 1
+    // §17 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) {
+      for (const k of ["_mutatedThisRun", "_verifiedThisRun", "_verifyPassed", "_calledAdvisorThisRun", "_touchedFiles", "_verifyRetries", "_advisorRound"]) agent[k] = g[k]
+      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
+    }
+  }
+  // §17 D-S6 manual tier: digest action-domain reminder (system-driven turn — organize only).
+  if (autoTurn && !agent.autoApprove) {
+    agent.history.push({ role: "user", content: AUTO_TURN_DIGEST_DOMAIN, transient: true })
   }
-  // eng-coder authorization is set by subagent.mjs AFTER token validation but BEFORE runAgent —
-  // only reset for the top-level agent (depth 0); child runs must keep their granted authorization
-  if (depth === 0) agent._engDesignReviewed = false
-  // _engDesignToken survives across turns within the same agent (design review → user approval → spawn eng-coder).
-  // Lifecycle: invalidated on a failed re-review (advisor.mjs), issued on a passing review.
+  // 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.
   let guardPushbacks = 0
   let advisorPushbacks = 0
   let honestReminderInjected = false
   const recentCallSigs = []
-  // repeat: "once" stream rules fire at most once per runAgent call (user turn):
-  // this set survives across chat() calls (rule abort-retry, tool loop) within the turn.
+  // "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
-  // part of every request but not in history — without them the first-turn/restored/just-
-  // compacted estimate under-counts and may never trigger compaction. Measured baseline
-  // path already includes both (prompt_tokens is the full context), so this only applies
-  // when _lastPromptTokens is null.
+  // 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,
+    // §18.6 D-TR4：compress 轨迹 depth 元数据（runAgent 的 depth 在此作用域——
+    // context.mjs compressIfNeeded 经 extras 透出到 logCtx）
+    traceDepth: depth,
   }
 
   let thrownError = null
@@ -171,74 +175,33 @@ export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal
     // Update turn counter for status bar display
     agent._currentTurn = turn + 1
     agent._maxTurns = maxTurns
-    // D2 (AGENT-LOOP.md §7.2): depth>0 children emit a ⟦ev⟧turn progress token on every
-    // turn — a single emit point covering all three spawn tools (natural heartbeat for the
-    // TUI subagent block header: "turn N/max"). phase=llm (tool/done progress rides the
-    // existing onToolCall/onToolResult prefix relay — no token for those).
+    // D2 (AGENT-LOOP.md §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).
     if (depth > 0 && callbacks.onToken) {
       callbacks.onToken(`⟦ev⟧turn\x1e${turn + 1}\x1e${maxTurns}\x1ellm\x1e`)
     }
 
+    // SUBAGENT-OBSERVE-SEND D2: 子代理回合边界消费点——每轮开头把父侧经 subagent
+    // action:'send' 注入队列（entry._injected）的消息按普通 user 回合推入子历史
+    // （pushReal → 下一轮 chat 即含该指令）。由 executeAsyncSpawn 经 childRunOpts 贯通的
+    // consumeInjected 回调承载（异步子代理专属——缺省 null：主会话/阻塞子代理零开销）。
+    consumeInjected?.(agent)
+
     const lastRole = agent.history.at(-1)?.role
     if (lastRole === "user" || lastRole === "tool") {
-      try {
-        if (await compressIfNeeded(agent, threshold, callbacks, compactionOverhead, signal)) {
-          agent._compressFailures = 0
-          agent._planReminderAtLen = 0 // After compression history shrinks, reset cadence so reminders resume
-          recentCallSigs.length = 0 // After compression history is rebuilt, reset stall detection counter
-          // Completion info (CONTEXT-COMPACTION §7 D-C2): { mode: "summary", tokensFreed, elapsedMs }
-          // from compressIfNeeded, or { mode: "fallback", tailMessages } from compressFallback below —
-          // the TUI panel renders the matching completion state. Existing callers that ignore the
-          // argument keep the exact previous onCompress semantics.
-          callbacks.onCompress?.(agent._lastCompressInfo ?? {})
-          ensureAutoReminder(agent)
-        }
-      } catch (compressError) {
-        // AbortError must not be swallowed: user cancellation must propagate
-        if (compressError?.name === "AbortError" || signal?.aborted) throw compressError
-        agent._compressFailures = (agent._compressFailures ?? 0) + 1
-        // Q3 visibility (CONTEXT-COMPACTION §7 D-C1): a failed compression is no longer silent —
-        // the frontend updates the compression panel with the error text (and logs to stderr).
-        // Failure STRATEGY is unchanged: COMPRESS_FAILURE_LIMIT consecutive failures still degrade
-        // to compressFallback — this only adds observability.
-        callbacks?.onCompressFail?.(compressError)
-        if (agent._compressFailures >= COMPRESS_FAILURE_LIMIT) {
-          agent._compressFailures = 0
-          if (compressFallback(agent)) callbacks.onCompress?.(agent._lastCompressInfo ?? {})
-        }
-      }
+      // 2026-09-05 实践轮：压缩检查/降级计数提为 runCompactionCheck（agent/run-stages.mjs——
+      // CLI 对位 VS run-stages）——循环骨架此处只剩检查调用（recentCallSigs 对象引用回流）。
+      await runCompactionCheck(agent, { threshold, callbacks, compactionOverhead, signal, recentCallSigs })
     }
 
-    // Plan-mode reminder cadence: re-inject constraint reminders while plan mode is active
-    // (sparse every 2 turns, full every 5 turns or when the user sends a new message),
-    // so the read-only restriction never fades from context.
-    if (agent.planMode) {
-      const lastMsg = agent.history.at(-1)
-      const realUserMsg = lastMsg?.role === "user"
-        && typeof lastMsg.content === "string"
-        && !lastMsg.content.startsWith("[System reminder:")
-        && !lastMsg.content.startsWith("[User interrupt:")
-      const newUserSince = realUserMsg && agent.history.length > (agent._planReminderAtLen ?? 0)
-      const { planReminderForTurn } = await import("./agent-tools/plan.mjs")
-      const reminder = planReminderForTurn(agent, newUserSince)
-      if (reminder) {
-        agent._planReminderAtLen = agent.history.length + 1
-        agent.history.push({ role: "user", content: reminder, transient: true })
-      }
-    }
-
-    // Engineering-mode status injection: every new user message carries a
-    // reminder so the model always knows whether it's in design-before-code
-    // mode or standard discipline mode.
-    if (depth === 0) {
-      injectEngineeringReminder(agent)
-    }
+    // 2026-09-05 实践轮：plan cadence + eng 状态注入提为 injectTurnReminders（run-stages）
+    await injectTurnReminders(agent, { depth })
 
     const messages = [{ role: "system", content: systemPrompt }, ...agent.history]
     let response
 
-    // Auto-think: classify task difficulty and set reasoning effort before the real prompt.
-    // Runs only on turn 0 of user input; failure is silent — falls back to current setting.
+    // Auto-think: classify difficulty and set reasoning effort on turn 0; silent on failure.
     if (agent.config?.agent?.autoThink && turn === 0) {
       const { classifyAndApply } = await import("./auto-think.mjs")
       await classifyAndApply(agent, turn).catch(() => {})
@@ -253,14 +216,29 @@ export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal
         signal,
         streamRules: agent.config.agent?.streamRules ?? [],
         firedPatterns: streamRuleFired,
+        // LOGGING（LOGGING.md）：llm:* 事件的语义上下文（stage=turn 主循环回合——含
+        // digest 消化轮 auto=true；child=子代理 id（spawn 时 stamp 于 child._logId））
+        // §18.6 D-TR4：轨迹元数据增补（role/depth/kind/session/cwd——trace-store 只读
+        // logCtx，签名不变）；kind：depth>0 = subagent（consult 孩子 = consult）——子代理
+        // 对回靠 role+depth+child id（children 无 _sessionStart——不经 depth-0 设置——
+        // session 字段对子代理轨迹为 null——见 trace-store/agent.mjs 注释）。
+        logCtx: {
+          stage: "turn", turn: turn + 1, auto: autoTurn, child: agent._logId,
+          role: agent._role ?? null,
+          depth,
+          kind: depth > 0 ? (agent._role === "consult" ? "consult" : "subagent") : "turn",
+          session: agent._sessionStart ?? null,
+          cwd: agent.cwd,
+          traces: agent.config?.traces?.enabled !== false,
+        },
       })
     } catch (e) {
-      // User interrupt (Ctrl+I): controller.abort({ interrupt: true, message: "…" }).
-      // Inject the message into history and let the outer loop recreate the controller.
+      // User interrupt (Ctrl+I): controller.abort({ interrupt: true, message }).
+      // Inject into history; the outer loop recreates the controller and resumes.
       if (e.name === "AbortError" && signal?.reason?.interrupt) {
         const msg = `[User interrupt: ${signal.reason.message}]`
-        // Dedup: if the interrupt was already handled during tool execution (L302-310),
-        // don't push a duplicate — the outer loop will still recreate the controller.
+        // Dedup: if already handled during tool execution (interrupt branch below),
+        // don't push a duplicate — the outer loop still recreates the controller.
         if (agent.history.at(-1)?.content !== msg) {
           agent.history.push({ role: "user", content: msg })
         }
@@ -268,11 +246,9 @@ export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal
       throw e
     }
 
-    // 内置工具（Responses web_search）结果本地化：服务端已执行——入历史为 tool 消息，
-    // 模型下一轮可见；全量回传时 transport 依 tool_call_id 前缀还原 web_search_call item。
-    // 注意：服务端 item id 是 msg_xxx 非 web_search_call_ 前缀——必须合成前缀（toItems 识别锚点），
-    // 原始 id 存入 content（真机冒烟 2026-08-31：直接用 msg_xxx 会被转成 function_call_output
-    // 与服务端不配对，属蒙对）。
+    // 内置工具（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, {
@@ -282,8 +258,8 @@ export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal
       })
     }
 
-    // Stream rule triggered mid-generation (action: "abort"): halt current output,
-    // inject rule's message as a reminder, and retry from the same context.
+    // 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 })
@@ -296,20 +272,12 @@ export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal
       continue
     }
 
-    // Stream rule warnings (action: "warn"): the stream completed, but one or more
-    // non-interrupting rules matched. Inject warnings after the turn so the model
-    // sees them before its next response — without aborting mid-generation.
-    if (response._warnings?.length) {
-      const deDuplicated = [...new Map(response._warnings.map(w => [w.name || w.pattern, w])).values()]
-      agent.history.push({
-        role: "user",
-        content: `[System reminder — stream rule warnings from your last response:\n${deDuplicated.map(w => `- ${w.name || w.pattern}: ${w.message}`).join("\n")}]`,
-      })
-    }
+    // Stream rule warnings / finish-reason 警告（2026-09-05 实践轮——提为
+    // injectResponseReminders，agent/run-stages.mjs——verbatim，语义零变）
+    injectResponseReminders(agent, response)
 
-    // User interrupted mid-generation (Ctrl+I): the SSE stream was aborted while content
-    // was partially generated. Commit partial output + inject user message, then signal
-    // the outer loop to recreate the controller and resume.
+    // 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 })
@@ -329,20 +297,8 @@ export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal
       }
     }
 
-    // Warn on abnormal finish reasons — the model stopped for a reason other than
-    // "stop" or "tool_calls", meaning the response may be incomplete or truncated.
-    if (response.finishReason && response.finishReason !== "stop" && response.finishReason !== "tool_calls") {
-      const reasonMap = {
-        length: "output token limit reached after exhausting continuations",
-        insufficient_system_resource: "provider inference resources exhausted — consider retrying or switching models",
-        content_filter: "response blocked by provider content filtering",
-      }
-      const detail = reasonMap[response.finishReason] || `unknown reason "${response.finishReason}"`
-      agent.history.push({
-        role: "user",
-        content: `[System reminder: the previous turn ended abnormally — ${detail}. The assistant response that follows may be incomplete.]`,
-      })
-    }
+    // 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)
@@ -351,13 +307,11 @@ export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal
       advisorPushbacks = cr.advisorPushbacks
       if (cr.action === "continue") continue
       if (depth === 0) {
-        // End-of-run exploration distillation (CONTEXT-COMPACTION §5): this run's inline
-        // exploration results become one semantic note before the final return. Async
-        // (SEND-STALL-DISTILL §2.1): the turn-end signal goes out first — the promise hangs
-        // on agent._pendingDistill and settles at the next runAgent's start or the TUI's
-        // exit flush. Silent (N3): distillation failure must never block the return or lose
-        // history.
-        const distill = summarizeRunExplorations(agent, callbacks, signal).catch(() => {})
+        // 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.
+        // §18.6 D-TR4：depth 透传（distill 轨迹元数据——与 compress 同通道）
+        const distill = summarizeRunExplorations(agent, callbacks, signal, depth).catch(() => {})
         agent._pendingDistill = distill
       }
       return cr.content
@@ -380,12 +334,15 @@ export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal
 
     const results = await executeToolCalls(agent, toolByName, response.toolCalls, callbacks, depth, signal)
 
-    // Ctrl+I interrupt during tool execution: skip committing partial results —
-    // the tool failure messages would mislead the model. Inject the interrupt and retry.
+    // 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
@@ -397,16 +354,14 @@ export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal
           const args = JSON.parse(toolCall.arguments)
           const paths = tool.touchedPaths ? tool.touchedPaths(args) : [args.path]
           for (const p of paths) {
-            const abs = join(agent.cwd, p)
+            const abs = resolve(agent.cwd, p)
             if (!agent._touchedFiles.includes(abs)) agent._touchedFiles.push(abs)
           }
         } catch { /* 畸形 args 不影响记账（touchedFiles 尽力而为） */ }
       }
-      // The assistant tool_calls were already committed above (L347) — a strict
-      // provider 400s on dangling tool_calls, so synthesize placeholder tool
-      // results BEFORE the interrupt message (tool result must immediately
-      // follow its assistant tool_calls). The retry turn then sees a clean,
-      // pairable history (consult P1, 2026-08-30).
+      // 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]" })
       }
@@ -418,13 +373,11 @@ export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal
       continue
     }
 
-    // Model is executing tools → doing real work, reset guard pushback counter
+    // Model is executing tools → real work: reset guard pushback counters
     guardPushbacks = 0
     advisorPushbacks = 0
 
-    // Commit tool results (pairing, multimodal deferral, mutation accounting,
-    // touched files, reindex) — split into record-results.mjs (consult P2,
-    // 2026-08-30).
+    // Commit tool results (pairing, multimodal deferral, mutation accounting, reindex)
     await recordToolResults(agent, toolByName, results)
 
     injectPostTurn(agent, results, recentCallSigs, callbacks, turn)
@@ -435,59 +388,9 @@ export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal
     thrownError = e
     throw e
   } finally {
-    // Turn-end cleanup: abort any leftover consultation children (consult_start spawns
-    // fire-and-forget runners; a completed turn must not let them keep burning tokens).
-    cleanupConsultSessions(agent)
-    // Async subagent turn-end collection (AGENT-LOOP.md §15 D-A3). Lifecycle:
-    // - Ctrl+C / Ctrl+I (signal aborted): children were aborted with the parent
-    //   signal — clear WITHOUT injecting stale errors (user explicitly stopped).
-    // - ContinueError (turn cap): no wait, no injection — children keep running
-    //   and the RESUME run's turn-end collection takes over.
-    // - anything else: refill loop → wait for all → inject reports → clear.
-    if (signal?.aborted) {
-      agent._asyncSubagents?.clear()
-      agent._asyncQueue = []
-      agent._asyncCheckLastN = 0
-    } else if (thrownError instanceof ContinueError) {
-      // keep _asyncSubagents + the check counter — the resumed run continues them
-    } else {
-      await collectAsyncSubagents(agent)
-      agent._asyncCheckLastN = 0
-    }
-  }
-}
-
-/**
- * Turn-end async subagent collection (AGENT-LOOP.md §15 D-A3):
- * 1. refill loop — start queued heads while slots free (each settle already
- *    refills via its finally; this drains the tail), keeping the cap ≤4 serial.
- * 2. wait for every entry to settle (queued entries start through the refill
- *    chain — the drain loop converges when nothing is running and the queue is empty).
- * 3. inject one user-role reminder per entry: the report/error text XML-escaped
- *    (child reports may carry content from files/webpages — reminder discipline),
- *    >64K offloaded to disk with a preview + path.
- * 4. clear the map. (The ⟦ev⟧done freeze signal is NOT emitted here — D-A3
- *    2026-09-02: each entry's settle callback emits it at completion time so
- *    blocks freeze at their completion position in the stream.)
- */
-async function collectAsyncSubagents(agent) {
-  const map = agent._asyncSubagents
-  if (!map || map.size === 0) return
-  const { maybeRefillAsync } = await import("./agent-tools/subagent.mjs")
-  for (;;) {
-    maybeRefillAsync(agent)
-    const running = [...map.values()].filter((e) => e.status === "running")
-    if (running.length === 0) break
-    await Promise.allSettled(running.map((e) => e.promise))
-  }
-  for (const e of [...map.values()]) {
-    const body = e.error ?? e.report ?? "(no report)"
-    const preview = await offloadToolResult(String(body), `async-subagent-${e.id}`)
-    pushReal(agent, {
-      role: "user",
-      content: `[System reminder: async subagent #${e.id} (${e.role}) finished]\n${escapeXml(preview)}`,
-    })
+    // 2026-09-05 实践轮：回合收尾（consult 清理/async 池分流/guard 继承——原 425-462
+    // 段 + collectSettledAsync 466-494 整体迁 agent/run-stages.mjs finalizeAgentTurn——
+    // CLI 对位 VS run-stages——finally 只剩一行调用 + 骨架注释）。
+    await finalizeAgentTurn(agent, { signal, autoTurn, suspDriven, thrownError })
   }
-  map.clear()
-  agent._asyncQueue = []
 }

package/src/auto-think.mjs

@@ -81,6 +81,20 @@ export async function classifyAndApply(agent, turn) {
       ],
       tools: [],
       signal: AbortSignal.timeout(5_000),
+      // D-TS12 (AGENT-LOOP.md §18.7): full logCtx field set at the chat call
+      // point — traces/session/cwd/role/depth/kind (this call point carried
+      // only {stage,turn,child}). The traces field closes the D-TR6 "off = no
+      // persist" switch: without it the tracer treated the auto-think call as
+      // enabled and persisted even when agent.config.traces.enabled was false.
+      logCtx: {
+        stage: "autothink", turn, child: agent._logId,
+        traces: agent.config?.traces?.enabled !== false,
+        session: agent._sessionStart ?? null,
+        cwd: agent.cwd,
+        role: agent._role ?? null,
+        depth: agent._depth ?? 0, // agent state carries no depth stamp (the call site passes none) — 0 for the top-level agent
+        kind: "autothink",
+      },
     })
     const word = (response.content ?? "").trim().toLowerCase()
     if (word.startsWith("low")) level = "low"

package/src/cli/distill-command.mjs

@@ -10,7 +10,7 @@ function noKeyMessage() {
   return `还没有配置 API key。运行 thincoder 进入 TUI，用 /provider add 和 /provider key 配置；或直接编辑 ${configPath}`
 }
 
-/** thincoder distill <transcript-file> [--yes] [--scope=...]
+/** thincoder distill <transcript-file> [--yes] [--layer=...]
  *  Returns exit code: 0=success, 1=error */
 export async function distillCommand(args, exitSoon) {
   const flags = {}
@@ -20,9 +20,15 @@ export async function distillCommand(args, exitSoon) {
     if (m) flags[m[1]] = m[2] ?? true
     else positional.push(a)
   }
+  // AC2（MEMORY.md §6.5）：显式拦截旧 flag——`--scope=X` 与 `--scope X` 两形态落入 flags.scope，
+  // 报错防静默吞参（解析器本不校验未知 flag——旧 --scope=project 静默落 personal 最危险）。
+  if (flags.scope !== undefined) {
+    console.error("distill: --scope renamed to --layer — update your invocation")
+    return 1
+  }
   const file = positional[0]
   if (!file) {
-    console.error("Usage: thincoder distill <transcript-file> [--yes] [--scope=personal|project|team]")
+    console.error("Usage: thincoder distill <transcript-file> [--yes] [--layer=personal|project|team]")
     return 1
   }
   const { readFile } = await import("node:fs/promises")
@@ -64,9 +70,9 @@ export async function distillCommand(args, exitSoon) {
   }
   let saved = 0
   for (const c of candidates) {
-    if (flags.scope) c.scope = flags.scope
+    if (flags.layer) c.layer = flags.layer
     console.log(`\n--- candidate ---`)
-    console.log(`[${c.type}] ${c.title}  (scope: ${c.scope})`)
+    console.log(`[${c.type}] ${c.title}  (layer: ${c.layer})`)
     console.log(c.content)
     if (c.type === "rule") {
       console.log("(rule 类知识通常建议手动撰写；确认提取吗？)")