thincoder 0.12.59 → 0.12.61

package/src/agent.mjs

@@ -3,43 +3,43 @@
  * 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 { abortError, annotateAbort } from "./abort-provenance.mjs"
+import { pushReal, summarizeRunExplorations } from "./context.mjs"
 import { specForModel } from "./config.mjs"
-import { readFileSync } from "node:fs"
-import { join, dirname } from "node:path"
-import { fileURLToPath } from "node:url"
+import { resolve } from "node:path"
 import { executeToolCalls } from "./agent/dispatch.mjs"
 import { recordToolResults } from "./agent/record-results.mjs"
 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"
-import { logEvent } from "./log.mjs"
+// PROMPT-SYSTEM 施工② G1（2026-09-10）：六件槽位常量装载收口 prompt-overlays.mjs
+// （与子代理角色常量同源——单一权威锚 D1）；旧三件文件读取随本批退役。
+// 槽位常量通过下方 re-export 面（mod: rel — re-export 保 import 面）；本文件自身零直接消费。
+// 主循环阶段函数（压缩检查/注入组/回合收尾）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,
+  turnFrame, // 第 19 批（TURN-ACROSS-SEGMENTS）：跨段累计编号帧（设计 §19.3）
   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 硬限）
+// PROMPT-SYSTEM 施工② G1（2026-09-10）：六件槽位常量装载收口 prompt-overlays.mjs
+// （与子代理角色常量同源——单一权威锚 D1）；本文件 re-export 保 import 面。
+export {
+  PERSONA_ENGINEERING, PERSONA_NORMAL, COMMON,
+  DISCIPLINE_ENGINEERING, DISCIPLINE_NORMAL,
+  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
+// Role → persona slot mapping note（施工② G3）: 子代理人格由 assemblePrompt 场景表按
+// role 承载（persona-explore/coder/plan/eng-coder.md——D1 表 = 蓝图 §3.2 1:1）；
+// spawn 侧 overlay 概念已退役（prompt-overlays.mjs 不再导出 OVERLAY 别名常量）。
 
 // exported for consumption by agent-tools.mjs
 export {
@@ -50,40 +50,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.]"
-
-/** Manual-tier auto-turn digest domain (AGENT-LOOP.md §17 D-S6): organize-only.
- *  Injected per manual auto-turn run — writes/execute/spawns/questions are also
- *  mechanically denied (no permission handler + spawn gate); this steers first. */
-const AUTO_TURN_DIGEST_DOMAIN =
-  "[System reminder: auto-turn — background async subagents finished while there was no user message, and this turn runs automatically to digest their reports (the finished-report reminders above). No one is waiting for this reply, so organize only: 1) summarize each finished report's key points into this conversation for the user to read later; 2) update the task list with the task tool (allowed) to mark finished work done; 3) write decision points with a suggested next step as text — do not execute it. 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 summaries are written.]"
-
-/** 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,
@@ -97,8 +66,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(), // §11.2 D-24b: per-review convergence instances (rounds/prior/designId)
+    _mutationSeq: 0, _mutLog: [], // §11.2 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: [],
@@ -114,7 +87,7 @@ 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, autoTurn = false, suspDriven = false } = {}) {
+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) {
@@ -125,15 +98,25 @@ export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal
   // §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")
-    for (const e of pendingAsync.splice(0)) await injectAsyncResult(agent, e)
+    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(
+    // G1/G2（施工②）：prompt 装配收口 prepareRun 内部（assemblePrompt——prompt-overlays.mjs
+    // 槽位常量，与子代理角色常量同源——单一权威锚 D1）；本调用不再携带 prompt 常量。
     agent, input, callbacks,
-    { depth, signal, overrideTurns, resume: resume || autoTurn, systemPrompt: SYSTEM_PROMPT, disciplineRules: DISCIPLINE_RULES, mainOverlay: MAIN_OVERLAY },
+    { depth, signal, overrideTurns, resume: resume || autoTurn },
   )
 
   // Exploration-distillation boundary (CONTEXT-COMPACTION §5): prepareRun already
@@ -143,6 +126,10 @@ export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal
   // Per-run bookkeeping reset — PRESERVED on `resume` (ContinueError continuation):
   // mutation/guard continuity and the convergence budget must survive a continuation.
   if (!resume) {
+    // 第 19 批（TURN-ACROSS-SEGMENTS——设计 TURN-CAP-CONTINUE.md §19.3）：链内累计编号
+    // 只在链起点复位——续跑（resume:true）不重置、不回退（编号帧公式见 helpers.mjs
+    // turnFrame）。与下方 mutation/guard 复位同条件同点（全档唯一复位点）。
+    agent._turnSeq = 0
     // §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
@@ -160,18 +147,19 @@ export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal
       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 // check action read counter is per-run (§15 D-A2): a fresh user turn restarts from 1
     }
   }
   // §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 keep theirs
-  if (depth === 0) agent._engDesignReviewed = false
-  // _engDesignToken survives across turns (design review → approval → eng-coder spawn);
-  // lifecycle: invalidated on failed re-review (advisor.mjs), issued on a passing one.
+  // 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
@@ -194,64 +182,37 @@ export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal
   let thrownError = null
   try {
     for (let turn = 0; turn < maxTurns; turn++) {
-    // Update turn counter for status bar display
-    agent._currentTurn = turn + 1
-    agent._maxTurns = maxTurns
+    // 第 19 批（TURN-ACROSS-SEGMENTS——设计 TURN-CAP-CONTINUE.md §19.3）：编号帧——
+    // `_turnSeq` 每轮 +1（跨段累计，仅 `!resume` 链起点复位）；面向消费面的两字段
+    // （状态行 + ⟦ev⟧turn / ⟦ev⟧approval 事件共用）在此同点赋值（编号唯一权威；帧
+    // 公式 = helpers.mjs turnFrame）。段内帽判定不读帧（下行循环条件只读段内
+    // turn / maxTurns——N6）。
+    const frame = turnFrame(++agent._turnSeq, turn, maxTurns)
+    agent._currentTurn = frame.turn
+    agent._maxTurns = frame.maxTurns
     // 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).
+    // the onToolCall/onToolResult relay — no token for those). 第 19 批：载荷取上方帧值
+    // （agent._currentTurn / _maxTurns——字段形态 / 字段数 / phase 零变化，N5）。
     if (depth > 0 && callbacks.onToken) {
-      callbacks.onToken(`⟦ev⟧turn\x1e${turn + 1}\x1e${maxTurns}\x1ellm\x1e`)
+      callbacks.onToken(`⟦ev⟧turn\x1e${agent._currentTurn}\x1e${agent._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, tokensFreed, elapsedMs } —
-          // the TUI panel renders it; callers that ignore the arg keep prior 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 (CONTEXT-COMPACTION §7 D-C1): a failed compression is surfaced to the panel;
-        // COMPRESS_FAILURE_LIMIT consecutive failures still degrade to compressFallback.
-        callbacks?.onCompressFail?.(compressError)
-        if (agent._compressFailures >= COMPRESS_FAILURE_LIMIT) {
-          agent._compressFailures = 0
-          if (compressFallback(agent)) callbacks.onCompress?.(agent._lastCompressInfo ?? {})
-        }
-      }
-    }
-
-    // Plan-mode reminder cadence: re-inject constraint reminders while plan mode is active
-    // (sparse every 2 turns, full every 5 / on new user message) so the restriction never fades.
-    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 })
-      }
+      // 2026-09-05 实践轮：压缩检查/降级计数提为 runCompactionCheck（agent/run-stages.mjs——
+      // CLI 对位 VS run-stages）——循环骨架此处只剩检查调用（recentCallSigs 对象引用回流）。
+      await runCompactionCheck(agent, { threshold, callbacks, compactionOverhead, signal, recentCallSigs })
     }
 
-    // Engineering-mode status injection on every new user message (design-before-code
-    // vs standard discipline) — see injectEngineeringReminder.
-    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
@@ -327,15 +288,9 @@ export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal
       continue
     }
 
-    // Stream rule warnings (action: "warn"): stream completed; inject de-duplicated
-    // warnings so the model sees them before its next response.
-    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): commit partial output + inject the
     // message, then signal the outer loop to recreate the controller and resume.
@@ -347,7 +302,8 @@ export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal
         role: "user",
         content: `[User interrupt: ${response.interruptMessage}]`,
       })
-      throw Object.assign(new Error("User interrupted"), { name: "AbortError" })
+      // §20.3 站点 #8（第 24 批）：错误对象已自带 name/message——只补来源标注（缺 abortInfo 才补）
+      throw annotateAbort(Object.assign(new Error("User interrupted"), { name: "AbortError" }), signal, "agent", "interrupted-response")
     }
 
     if (response.usage) {
@@ -359,18 +315,7 @@ export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal
     }
 
     // Warn on abnormal finish reasons — the response may be incomplete/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.]`,
-      })
-    }
+    // 2026-09-05 实践轮：finish-reason 注入随流规则警告提为 injectResponseReminders。
 
     if (response.toolCalls.length === 0) {
       const cr = handleCompletion(agent, response, depth, turn, guardPushbacks, honestReminderInjected, advisorPushbacks, callbacks)
@@ -390,7 +335,7 @@ export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal
     }
 
     // abort after chat completes, before committing history: don't commit a half-finished turn
-    if (signal?.aborted) throw new DOMException("Aborted", "AbortError")
+    if (signal?.aborted) throw abortError(signal, "agent", "post-chat")
 
     pushReal(agent, {
       role: "assistant",
@@ -412,6 +357,9 @@ export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal
       // 中断变更记账（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
@@ -423,7 +371,7 @@ 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 尽力而为） */ }
@@ -457,73 +405,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 handling (AGENT-LOOP.md §15 D-A3 + §17 D-S1). Lifecycle:
-    // - Ctrl+C (plain abort): children were aborted with the parent signal — clear
-    //   WITHOUT injecting stale errors (user explicitly stopped). Ctrl+I (interrupt)
-    //   keeps the pool: the turn resumes with the interrupt message, children stay
-    //   tracked (in a suspension session children hold agent._sessionSignal and a
-    //   digest's own Ctrl+I must not orphan them).
-    // - ContinueError (turn cap): no wait, no injection — children keep running and
-    //   the RESUME run's turn-end collection takes over.
-    // - anything else: inject the SETTLED entries only; running/queued stay in the
-    //   pool for the suspension session (D-S1 — no allSettled turn-end wait).
-    if (signal?.aborted && !signal?.reason?.interrupt) {
-      if (agent._asyncSubagents?.size > 0) {
-        logEvent("ev:stopped", { poolN: agent._asyncSubagents?.size ?? 0, where: "turn-end-abort" })
-      }
-      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 collectSettledAsync(agent, { suspDriven })
-      agent._asyncCheckLastN = 0
-    }
-    agent._inAutoTurn = false
-    // §17 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)) {
-      agent._inheritedGuard = {
-        _mutatedThisRun: agent._mutatedThisRun, _verifiedThisRun: agent._verifiedThisRun,
-        _verifyPassed: agent._verifyPassed, _calledAdvisorThisRun: agent._calledAdvisorThisRun,
-        _touchedFiles: agent._touchedFiles, _verifyRetries: agent._verifyRetries,
-        _advisorRound: agent._advisorRound,
-      }
-    }
-  }
-}
-
-/**
- * Turn-end async subagent collection (AGENT-LOOP.md §17 D-S1 + §17.5 supersede):
- * two modes, selected by the caller's driver context (17.5.2/17.5.4 #2):
- * - suspDriven=false (fallback — headless/direct runAgent callers without a
- *   suspension driver): inject every entry that SETTLED during this run
- *   (XML-escaped report/error — child reports may carry file/webpage content;
- *   >64K offloaded with preview + path) and remove it from the pool. Running/
- *   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
- *   条目留池等消化轮注入；check/status 在 sweep 前仍从池读——17.5.2 不变面)。
- * 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). */
-async function collectSettledAsync(agent, { suspDriven = false } = {}) {
-  const map = agent._asyncSubagents
-  if (!map || map.size === 0) return
-  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 // §17.5: settled stays pooled — the suspension session digests it
-  for (const e of [...map.values()]) {
-    if (!e.done) continue // still running — stays in the pool (D-S1)
-    await injectAsyncResult(agent, e)
-    map.delete(String(e.id))
+    // 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, depth })
   }
 }

package/src/cli/distill-command.mjs

@@ -1,4 +1,4 @@
-import { join } from "node:path"
+import { isAbsolute, join } from "node:path"
 import { loadConfig, configPath } from "../config.mjs"
 import { createMemory } from "../memory.mjs"
 import { teamConfig, gitAuthor } from "./make-agent.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")
@@ -58,15 +64,15 @@ export async function distillCommand(args, exitSoon) {
   }
 
   const opts = {
-    projectDir: config.memory.projectDir ? join(process.cwd(), config.memory.projectDir) : null,
+    projectDir: config.memory.projectDir ? (isAbsolute(config.memory.projectDir) ? config.memory.projectDir : join(process.cwd(), config.memory.projectDir)) : null,
     team,
     author: gitAuthor(),
   }
   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 类知识通常建议手动撰写；确认提取吗？)")

package/src/cli/make-agent.mjs

@@ -1,5 +1,5 @@
 import { execSync } from "node:child_process"
-import { join } from "node:path"
+import { isAbsolute, join } from "node:path"
 import { createAgent } from "../agent.mjs"
 import { loadConfig, configDir } from "../config.mjs"
 import { createMemory, memoryTools, syncDir, codeSearchTool, docSearchTool } from "../memory.mjs"
@@ -7,9 +7,21 @@ import { settingsTool } from "../agent-tools/settings.mjs"
 import { repoOutlineTool } from "../tools/repomap.mjs"
 import { builtinTools } from "../tools/index.mjs"
 import { discoverRules } from "../rules.mjs"
+// R10 L2（MULTI-INSTANCE-COLLAB §2a.4 D-L2b）：peer_instances 只读工具——挂感知模块导出
+import { peerInstancesTool } from "../peer-instances.mjs"
+
+/** 第 27 批 §12.3⑤（R-A1.1）：装配期工具剔除——按 `name` 过滤的纯函数（机验锚）。
+ *  恒等语义：空列表 / 零命中 → 原数组原样返回（零意外剔除——T15）。
+ *  ACP 通道经 `assembleAgent({ excludeTools })` 传入（acp.mjs `ACP_EXCLUDED_TOOLS`）。 */
+export function applyToolExclusions(tools, excludeTools = []) {
+  const excluded = new Set(excludeTools ?? [])
+  if (excluded.size === 0) return tools
+  const kept = tools.filter((t) => !excluded.has(t?.name))
+  return kept.length === tools.length ? tools : kept
+}
 
 /** Assemble an agent with memory, MCP tools, and code/doc indices attached (sync all layers, then return) */
-export async function assembleAgent() {
+export async function assembleAgent({ excludeTools = [] } = {}) {
   const config = loadConfig()
   const provider = config.provider
   const providers = config.providersList
@@ -18,7 +30,7 @@ export async function assembleAgent() {
   const { injectProxy } = await import("../proxy.mjs")
   injectProxy(providers, config)
   // config.provider 是 loadConfig 里的独立拷贝，同步注入结果
-  provider.proxyUri = providers.find((p) => p.name === config.activeProvider)?.proxyUri
+  if (provider?.name) provider.proxyUri = providers.find((p) => p.name === provider.name)?.proxyUri
 
   const memory = createMemory({ dbPath: config.memory.dbPath })
   // Vector retrieval: enabled if embedding is configured (lazy vector generation, computed on first search)
@@ -39,7 +51,7 @@ export async function assembleAgent() {
   memory.codeOrigin = cwd
   // Project layer: sync .thincoder/memory/ dir to index on startup (sync if present, skip otherwise)
   if (config.memory.projectDir) {
-    memory.projectOrigin = join(cwd, config.memory.projectDir)
+    memory.projectOrigin = isAbsolute(config.memory.projectDir) ? config.memory.projectDir : join(cwd, config.memory.projectDir)
     await syncDir(memory, { layer: "project", dir: memory.projectOrigin })
   }
   // Team layer (optional): auto-clone on first use; startup only indexes local dir, remote pull via explicit thincoder sync
@@ -49,7 +61,7 @@ export async function assembleAgent() {
     await ensureClone(team)
     await syncDir(memory, { layer: "team", dir: team.dir })
   }
-  const baseTools = [...builtinTools, ...memoryTools(memory, { cwd, projectDir: config.memory.projectDir, author: gitAuthor(), team }), codeSearchTool(memory), docSearchTool(memory), repoOutlineTool(memory.db, cwd), settingsTool()]
+  const baseTools = [...builtinTools, ...memoryTools(memory, { cwd, projectDir: config.memory.projectDir, author: gitAuthor(), team }), codeSearchTool(memory), docSearchTool(memory), repoOutlineTool(memory.db, cwd), settingsTool(), peerInstancesTool]
 
   // MCP servers: connect in parallel (a dead server won't block startup), collect failures as warnings (stderr invisible in TUI, passed via agent object)
   const mcpServers = config.mcp?.servers ?? []
@@ -99,18 +111,24 @@ export async function assembleAgent() {
 
   const agent = createAgent({
     provider,
-    tools: [...baseTools, ...mcpTools],
+    tools: applyToolExclusions([...baseTools, ...mcpTools], excludeTools),
     config,
     cwd,
     memory,
   })
   agent.providers = providers
-  agent.activeProvider = config.activeProvider
-  agent.activeModel = config.activeModel ?? null
+  // MODEL-MERGE-SESSION：config 无 active*——会话运行时起点 = defaultModel 复合解析
+  // （provider 对象带解析后 model——API/spec 消费点零改）；无效 → {} + 原因走 D-S1 标记
+  agent.activeProvider = provider.name ?? ""
+  agent.activeModel = provider.model ?? null
   agent._mcpWarnings = mcpWarnings
   // SESSION.md §8 D-S1：assembleAgent 后唯一校验点（TUI/chat 两路径同源）——不抛错不退出，
   // 标记由调用侧消费（TUI 弹重选 / headless 报错）。空 provider 由 TUI 路径在 startTUI 前清空。
   validateProvider(agent)
+  // defaultModel 无效/未设的具体原因覆盖通用判据文案（providers 存在时更有指导性）
+  if (agent._providerInvalid && config.providerInvalidReason) {
+    agent._providerInvalidReason = config.providerInvalidReason
+  }
   return agent
 }
 

package/src/cli/memory-command.mjs

@@ -1,7 +1,8 @@
-import { join } from "node:path"
+import { isAbsolute, join } from "node:path"
 import { loadConfig } from "../config.mjs"
 import { teamConfig } from "./make-agent.mjs"
-import { put, search, list, deleteByUid } from "../memory/core.mjs"
+import { put, search, list } from "../memory/core.mjs"
+import { deleteByUid } from "../memory/delete.mjs"
 
 /** thincoder memory <list|search|put|remove> subcommands.
  *  opts.dirs: { project, team } layer directories for project/team file deletion (tests inject their own);
@@ -66,7 +67,7 @@ export async function memoryCommand(memory, args, opts = {}) {
 function cliDirs() {
   const config = loadConfig()
   const dirs = { project: null, team: null }
-  if (config.memory?.projectDir) dirs.project = join(process.cwd(), config.memory.projectDir)
+  if (config.memory?.projectDir) dirs.project = isAbsolute(config.memory.projectDir) ? config.memory.projectDir : join(process.cwd(), config.memory.projectDir)
   const team = teamConfig(config)
   if (team) dirs.team = team.dir
   return dirs

package/src/cli/permission.mjs

@@ -23,8 +23,8 @@ export function formatPermission(name, args) {
     // §6 action-routed preview: put shows content, batch delete/clear show the gate args
     const action = String(args.action ?? "")
     if (action === "put") return `[${args.type ?? ""}] ${args.title ?? ""}\n${cap(args.content ?? "", 500)}`
-    if (action === "delete") return args.id ? `id=${args.id} scope=${args.scope}` : `batch delete scope=${args.scope} type=${args.type ?? ""} keyword=${args.keyword ?? ""} confirm=${args.confirm}`
-    if (action === "clear") return `clear scope=${args.scope} confirm=${args.confirm}`
+    if (action === "delete") return args.id ? `id=${args.id}${args.layer ? ` layer=${args.layer}` : ""}` : `batch delete layer=${args.layer ?? ""} type=${args.type ?? ""} keyword=${args.keyword ?? ""} confirm=${args.confirm}`
+    if (action === "clear") return `clear layer=${args.layer ?? ""} confirm=${args.confirm}`
     return cap(summarize(args), 300)
   }
   return cap(summarize(args), 300)