thincoder 0.12.59 → 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,32 +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"
-import { logEvent } from "./log.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,
   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 {
@@ -50,40 +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.]"
-
-/** 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 +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: [],
@@ -114,7 +83,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,10 +94,18 @@ 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(
@@ -160,18 +137,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
@@ -204,54 +182,21 @@ export async function runAgent(agent, input, callbacks = {}, { depth = 0, signal
       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, 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 +272,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.
@@ -359,18 +298,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)
@@ -412,6 +340,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 +354,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 +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 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 })
   }
 }

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 类知识通常建议手动撰写；确认提取吗？)")

package/src/cli/make-agent.mjs

@@ -7,6 +7,8 @@ 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"
 
 /** Assemble an agent with memory, MCP tools, and code/doc indices attached (sync all layers, then return) */
 export async function assembleAgent() {
@@ -49,7 +51,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 ?? []

package/src/cli/memory-command.mjs

@@ -1,7 +1,8 @@
 import { 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);

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)

package/src/cli/setup-wizard.mjs

@@ -1,6 +1,5 @@
-import { existsSync, readFileSync } from "node:fs"
 import { createInterface } from "node:readline"
-import { configPath, saveConfig, PROVIDER_PRESETS } from "../config.mjs"
+import { configPath, writeConfigAtomic, PROVIDER_PRESETS } from "../config.mjs"
 
 /** First-time setup (TTY chat / distill): ask a few questions to configure a provider, save to disk, return runtime provider. Cancel returns null. */
 export async function setupWizard() {
@@ -52,16 +51,22 @@ export async function setupWizard() {
       return null
     }
     const embedKey = (await ask("Optional: embedding API key (SiliconFlow, for vector search; press Enter to skip): ")).trim()
-    const raw = existsSync(configPath) ? JSON.parse(readFileSync(configPath, "utf8")) : {}
-    const providers = raw.providers?.length ? raw.providers : []
-    const existing = providers.find((p) => p.name === name)
-    if (existing) Object.assign(existing, { baseURL, model, apiKey })
-    else providers.push({ name, baseURL, model, apiKey })
-    raw.providers = providers
-    raw.activeProvider = name
-    delete raw.activeModel  // reset to default model
-    if (embedKey) raw.embedding = { ...(raw.embedding ?? {}), apiKey: embedKey }
-    saveConfig(raw)
+    // D-F5b：磁盘新鲜读 → mutate → mtime 门控写（writeConfigAtomic 收口）；冲突 = 放弃
+    // + 提示重试（首配场景另有实例同时写盘——极低概率；不自动合并——决策点① A）
+    const r = writeConfigAtomic(configPath, (raw) => {
+      const providers = raw.providers?.length ? raw.providers : []
+      const existing = providers.find((p) => p.name === name)
+      if (existing) Object.assign(existing, { baseURL, model, apiKey })
+      else providers.push({ name, baseURL, model, apiKey })
+      raw.providers = providers
+      raw.activeProvider = name
+      delete raw.activeModel  // reset to default model
+      if (embedKey) raw.embedding = { ...(raw.embedding ?? {}), apiKey: embedKey }
+    })
+    if (!r.ok) {
+      console.error("config changed on disk concurrently — retry")
+      return null
+    }
     console.error(`Configured: ${name} / ${model} (saved to ${configPath})`)
     console.error(embedKey ? "Vector search enabled\n" : "(No embedding key configured: memory search will use text-only FTS. Add embedding.apiKey to config.json to enable vector search later.)\n")
     return { name, baseURL, model, apiKey }

package/src/config.mjs

@@ -5,9 +5,9 @@
  * API key can fall back to environment variables (when not configured in providers).
  */
 
-import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs"
 import { homedir } from "node:os"
-import { join } from "node:path"
+import { dirname, join } from "node:path"
 
 export const configDir = join(homedir(), ".thincoder")
 export const configPath = join(configDir, "config.json")
@@ -55,6 +55,14 @@ export const DEFAULTS = {
     advisor: { guard: false },  // code review is always available; guard: true pushes completion back until reviewed (opt-in). Also accepts provider/model/thinking/reasoningEffort/timeoutMs overrides. Deprecated: enabled (2026-08-21)
     autoThink: false,     // auto-classify task difficulty and set reasoning effort per-turn
     engineering: false,   // strict methodology enforcement — read METHODOLOGY.md, design-before-code
+    // Async subagent pool limits per role domain (AGENT-LOOP.md §24 D-24a/R14):
+    // { engCoder, other } — eng-coder pool / other-role pool, defaults 4/4 (user
+    // ruling "eng-coder 四路，其他 4 路"). Runtime-validated at every pool admission
+    // (positive integer ≥1, invalid/absent keys fall back to 4 — settings tool and
+    // the /config 并发池 menu write this key; change applies to the next spawn).
+    // ⚠ 与 subagent-async.mjs ASYNC_POOL_LIMITS 逐键同值（运行时回退常量）——耦合锚
+    // T-24a4 断言锁住——勿单侧改默认。
+    poolLimits: { engCoder: 4, other: 4 },
   },
   memory: {
     dbPath: join(configDir, "memory.db"),
@@ -368,12 +376,52 @@ function mcpFingerprint(s) {
 }
 
 /**
- * Save configuration. Preserves providers list structure and activeProvider pointer.
- * providers[i].apiKey is only written when explicitly passed in (does not overwrite env-var-fallback keys).
+ * R10 F5（D-F5b，2026-09-06）——config.json 写前 mtime 门控收口函数（session-rename
+ * mtime-conflict 先例同型——MULTI-INSTANCE-COLLAB.md §2a.2）。所有 config.json 写点
+ * （config-helpers persistRaw / cmd-config saveProxy / cli setup-wizard / settings
+ * writeDisk）都经它落盘。
+ *
+ * 本函数持有整条「新鲜读 → mutate 单操作 → 写前重 stat → 写」链：
+ * - t0 = 写前重 stat 的比对基线，取在**新鲜读之前**（stat→read 序）：若对端在本端
+ *   stat 与 read 之间的微窗口写入，只会造成假冲突（放弃重试），绝不会带着旧内容覆盖
+ *   对端新值——read→stat 序存在漏检窗口（stat 已反映对端新 mtime → 门控放行旧内容）。
+ * - 写前重 stat ≠ t0 → **放弃**本次写（D-F5a 后各流已是 fresh 单操作语义，磁盘上对端
+ *   的新值保持在线不抹）；先 copy `.bak-{ts}` 留现场（仅冲突时——config 低频写不膨胀；
+ *   copy 而非 rename：冲突即放弃、本体不动，"保现场"是额外副本，非轮转腾位）。
+ * - 返回 { ok:false, reason:"mtime-conflict" }，调用方提示 "config changed on disk
+ *   concurrently — retry"——不自动合并（config 是用户显式操作——重试比猜测合并安全，
+ *   决策点① A）。
+ * - 文件缺失（首写）→ t0 = null；对端在本端读后创建 → null ≠ 新 mtime → 冲突放弃。
+ * - 畸形文件拒写（throw，绝不静默覆盖）；写后 chmod 0600 尽力而为（saveConfig 旧语义）。
+ *
+ * @param path config.json 路径（生产默认 configPath；测试注入 tmp 路径）
+ * @param mutate 在磁盘新鲜 raw 上执行单操作的同步回调（如 push/splice/单字段补丁）
+ * @returns { ok: true } | { ok: false, reason: "mtime-conflict" }
  */
-export function saveConfig(config) {
-  mkdirSync(configDir, { recursive: true })
+export function writeConfigAtomic(path, mutate) {
+  const mtimeOf = (p) => {
+    try { return statSync(p).mtimeMs } catch { return null } // 缺失 → null（t0 比对基线）
+  }
+  const t0 = mtimeOf(path) // stat 先于 read（安全方向——见头注释）
+  const text = existsSync(path) ? readFileSync(path, "utf8") : null
+  let raw = {}
+  if (text !== null) {
+    try {
+      raw = JSON.parse(text)
+    } catch (error) {
+      throw new Error(`config file not parseable — refusing to overwrite: ${path} — ${error.message}`, { cause: error })
+    }
+  }
+  mutate(raw)
+  const t1 = mtimeOf(path)
+  if (t0 !== t1) {
+    // 对端在我们新鲜读后改过磁盘 → 放弃本次写（对端内容保持在线）；.bak 副本留现场
+    try { if (existsSync(path)) copyFileSync(path, `${path}.bak-${Date.now()}`) } catch { /* 现场保留失败不阻断冲突报告 */ }
+    return { ok: false, reason: "mtime-conflict" }
+  }
+  mkdirSync(dirname(path), { recursive: true })
   // 0600: config.json contains API keys, must not be world-readable (POSIX; chmod is best-effort on Windows)
-  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", { encoding: "utf8", mode: 0o600 })
-  try { chmodSync(configPath, 0o600) } catch { /* may fail on Windows, ignore */ }
+  writeFileSync(path, JSON.stringify(raw, null, 2) + "\n", { encoding: "utf8", mode: 0o600 })
+  try { chmodSync(path, 0o600) } catch { /* may fail on Windows, ignore */ }
+  return { ok: true }
 }