thincoder 0.12.59 → 0.12.61

package/src/advisor.mjs

@@ -2,7 +2,8 @@
  * advisor.mjs — advisor system-prompt selection, follow-up building, session assembly.
  * User-message building lives in advisor/messages.mjs; execution (tool loop, provider
  * resolution, review entry) in advisor/run.mjs; history extraction in advisor/history.mjs.
- * repos.mjs still hosts the doc-file classifier (isDocFile) used by mutation tracking.
+ * Path classification (code / doc / temp) and the project declaration surface live in
+ * ../conventions.mjs — the single authority every gate consumes (repos.mjs included).
  *
  * The advisor runs as a read-only exploration sub-agent with tools
  * (read, glob, grep, ls, lsp, code_search) — ZERO git, every round. The change
@@ -45,13 +46,13 @@ import { readFileSync } from "node:fs"
 import { join, dirname } from "node:path"
 import { fileURLToPath } from "node:url"
 import { extractAgentResponseTable } from "./advisor/history.mjs"
-import { buildAdvisorUserMessage, resolveScopeFiles, buildObjectDeclarationBlock } from "./advisor/messages.mjs"
+import { buildAdvisorUserMessage, resolveScopeFiles, buildObjectDeclarationBlock, buildDesignApprovalBlock } from "./advisor/messages.mjs"
 import { buildConvergenceBody } from "./advisor/convergence.mjs"
 import { escapeLiteralEscapes } from "./escape.mjs"
 // Re-export for run.mjs and tests (keeps their imports from "../advisor.mjs" stable)
 export { ADVISOR_MD_PATH, extractAgentResponseTable, extractConversationBackground } from "./advisor/history.mjs"
 export { buildAdvisorUserMessage } from "./advisor/messages.mjs"
-export { buildObjectDeclarationBlock } from "./advisor/messages.mjs"
+export { buildObjectDeclarationBlock, buildDesignApprovalBlock } from "./advisor/messages.mjs"
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 
@@ -195,8 +196,10 @@ export { escapeLiteralEscapes }
  * @param {Object|null} [object] — review-object declaration (§18.8 D-OA1): passed through
  *   to the user-message builders; mechanically injected at the start of every review
  *   round (round 1 design/code + round 2+ follow-up). Absent → legacy behavior.
+ * @param {string|null} [designId] — §29.1 F2a: injected next to the design token in
+ *   the Approval Signal (round 1 + round 2+ — both values, verbatim anchor).
  */
-export function prepareAdvisorMessages(agent, reviewType, designToken = null, documents = null, paths = null, priorParam = null, object = null) {
+export function prepareAdvisorMessages(agent, reviewType, designToken = null, documents = null, paths = null, priorParam = null, object = null, designId = null) {
   // Deterministic convergence state (decision 2026-08-08): round 2+ requires
   // _advisorRound > 0 AND a stored prior review output. No history parsing.
   // priorParam (direct callers) wins over the stored output — same derivation
@@ -209,7 +212,7 @@ export function prepareAdvisorMessages(agent, reviewType, designToken = null, do
   if (reviewType === "design" && (agent._advisorRound || 0) === 0) {
     return [
       { role: "system", content: withTime(buildAdvisorSystemPrompt(agent, prior, reviewType)) },
-      { role: "user", content: escapeLiteralEscapes(buildAdvisorUserMessage(agent, prior, reviewType, designToken, documents, paths, object)) },
+      { role: "user", content: escapeLiteralEscapes(buildAdvisorUserMessage(agent, prior, reviewType, designToken, documents, paths, object, designId)) },
     ]
   }
 
@@ -234,7 +237,7 @@ export function prepareAdvisorMessages(agent, reviewType, designToken = null, do
       agent._advisorRound = 0
     }
     // Mutations exist → KEEP the round (cap keeps advancing through retries).
-    const user = buildAdvisorUserMessage(agent, prior, reviewType, designToken, documents, paths, object)
+    const user = buildAdvisorUserMessage(agent, prior, reviewType, designToken, documents, paths, object, designId)
     return [
       { role: "system", content: withTime(buildAdvisorSystemPrompt(agent, prior, reviewType)) },
       {
@@ -263,8 +266,25 @@ export function prepareAdvisorMessages(agent, reviewType, designToken = null, do
   // scopeFiles gives the fallback (agent gave no response table) a concrete
   // review surface.
   const scopeFiles = resolveScopeFiles(agent, paths)
+  const followUp = buildAdvisorFollowUp(agent, prior, scopeFiles, object)
+  // §11.2 D-24b (design round 2+ — async fix-round continuations must be able to
+  // re-approve): re-anchor the review scope (the convergence follow-up carries no
+  // document list) and inject the round's design token with the approval signal.
+  if (reviewType === "design") {
+    const docList = Array.isArray(documents)
+      ? documents.filter((d) => typeof d === "string" && d.trim())
+      : []
+    const scopeBlock = docList.length > 0
+      ? `\n\n## Documents to Review\nThe documents below are the review scope. Review ONLY these files — do not scan git diff or read any other files.\n${docList.map((d) => `- ${d} — Read this file in full`).join("\n")}`
+      : ""
+    const tokenBlock = designToken ? `\n\n${buildDesignApprovalBlock(designToken, designId)}` : ""
+    return [
+      { role: "system", content: withTime(buildAdvisorSystemPrompt(agent, prior, reviewType)) },
+      { role: "user", content: escapeLiteralEscapes(followUp + scopeBlock + tokenBlock) },
+    ]
+  }
   return [
     { role: "system", content: withTime(buildAdvisorSystemPrompt(agent, prior, reviewType)) },
-    { role: "user", content: escapeLiteralEscapes(buildAdvisorFollowUp(agent, prior, scopeFiles, object)) },
+    { role: "user", content: escapeLiteralEscapes(followUp) },
   ]
 }

package/src/agent/completion.mjs

@@ -7,6 +7,7 @@
 import { hasCodeMutations } from "../advisor/repos.mjs"
 import { pushReal } from "../context.mjs"
 import { MAX_ADVISOR_ROUNDS } from "../advisor/run.mjs"
+import { advisorReviewPending, effectiveAdvisorRound } from "../agent-tools/advisor-async.mjs"
 
 const MAX_VERIFY_PUSHBACKS = 2
 const MAX_VERIFY_RETRIES = 3
@@ -77,18 +78,20 @@ export function handleCompletion(agent, response, depth, turn, guardPushbacks, h
       pushReal(agent, { role: "assistant", content: response.content })
       agent.history.push({
         role: "user",
-        content: "[System reminder: you modified files in this run but have not verified the changes. Before finishing: call the verify tool to run syntax checks and tests. If verify reports failures, fix them and run verify again. If verification is genuinely impossible here, say so explicitly in your reply.]",
+        content: "[System reminder: you modified files in this run but have not verified the changes. Before finishing: run the project's verification yourself (per its AGENTS.md test method), then call verify declaring the outcome via verification.status. verify mechanically gates on your declaration. If verification is genuinely impossible here, say so explicitly in your reply.]",
       })
       callbacks.onTurnEnd?.(agent, turn)
       return { action: "continue", guardPushbacks, honestReminderInjected, advisorPushbacks }
     }
-    // Verified but still failing → pushback to fix (up to MAX_VERIFY_RETRIES)
+    // Verified but not passed → pushback to fix/complete (up to MAX_VERIFY_RETRIES).
+    // _verifyPassed === false means the declaration was failed, skipped without a
+    // reason, or not declared — not necessarily that a test failed.
     if (agent._verifiedThisRun && agent._verifyPassed === false && agent._verifyRetries < MAX_VERIFY_RETRIES) {
       agent._verifyRetries++
       pushReal(agent, { role: "assistant", content: response.content })
       agent.history.push({
         role: "user",
-        content: `[System reminder: verify reported test failures (retry ${agent._verifyRetries}/${MAX_VERIFY_RETRIES}). Review the failures, fix the issues, then run verify again. If you cannot fix after ${MAX_VERIFY_RETRIES} attempts, explain honestly what's blocking you.]`,
+        content: `[System reminder: (retry ${agent._verifyRetries}/${MAX_VERIFY_RETRIES}) verify was not passed — either your verification declared failed, was skipped without a reason, or was not declared. Fix or complete your verification, then call verify again declaring the outcome. If you cannot fix after ${MAX_VERIFY_RETRIES} attempts, explain honestly what's blocking you.]`,
       })
       callbacks.onTurnEnd?.(agent, turn)
       return { action: "continue", guardPushbacks, honestReminderInjected, advisorPushbacks }
@@ -103,7 +106,7 @@ export function handleCompletion(agent, response, depth, turn, guardPushbacks, h
       pushReal(agent, { role: "assistant", content: response.content })
       agent.history.push({
         role: "user",
-        content: `[System reminder: ${MAX_VERIFY_RETRIES} verify attempts exhausted and tests are still failing. In your response to the user, you MUST state explicitly: (1) what tests are still failing, (2) what you tried, (3) what you believe the root cause is. Do not present this as complete — the user needs to know the work is unfinished.]`,
+        content: `[System reminder: ${MAX_VERIFY_RETRIES} verify attempts exhausted. You have not passed verification. Either state explicitly that your verification could not be completed, or run verify again once it is. If your verification could not be completed, say so explicitly in your reply to the user — state what you tried and what you believe is blocking you, and do not present the work as complete; the user needs to know it is unfinished.]`,
       })
       callbacks.onTurnEnd?.(agent, turn)
       return { action: "continue", guardPushbacks, honestReminderInjected, advisorPushbacks }
@@ -117,18 +120,21 @@ export function handleCompletion(agent, response, depth, turn, guardPushbacks, h
   const cfg = agent.config?.advisor
   const advisorReview = cfg?.guard === true
   if (depth === 0 && advisorReview && !agent.config?.agent?.engineering) {
-    // Cap sync: beyond MAX_ADVISOR_ROUNDS the advisor tool refuses to review
-    // (run.mjs convergence cap) — pushing back further would loop forever
-    // (fix → pushback → cap-refused call → fix …). The cap message from the
-    // last accepted review stands; the user decides manually.
-    if (agent._mutatedThisRun && !agent._calledAdvisorThisRun && hasCodeMutations(agent)
+    // §11.2 D-24b (T-24b4 — guard timing): an async review that is still in flight
+    // (or queued in the advisor pool) means the review was launched — the guard
+    // does NOT push back while it is pending (未决不算未评审); once it settles
+    // non-stale it marks _calledAdvisorThisRun, and a STALE settle leaves the
+    // mark unset so the guard pushes back here again (fix #2 — no silent skip).
+    const pending = advisorReviewPending(agent)
+    const rounds = effectiveAdvisorRound(agent)
+    if (!pending && agent._mutatedThisRun && !agent._calledAdvisorThisRun && hasCodeMutations(agent)
         && advisorPushbacks < MAX_ADVISOR_PUSHBACKS
-        && (agent._advisorRound || 0) < MAX_ADVISOR_ROUNDS) {
+        && rounds < MAX_ADVISOR_ROUNDS) {
       advisorPushbacks++
       pushReal(agent, { role: "assistant", content: response.content })
       agent.history.push({
         role: "user",
-        content: `[System reminder: you changed code in this run and MUST get an advisor review before finishing (round ${agent._advisorRound + 1}). Call the \`advisor\` tool now. This is required, not optional — do not skip it even if you believe the changes are trivial — the review will be quick either way. After the review, produce a response table for every issue found (see discipline rules for format).]`,
+        content: `[System reminder: you changed code in this run and MUST get an advisor review before finishing (round ${rounds + 1}). Call the \`advisor\` tool now. This is required, not optional — do not skip it even if you believe the changes are trivial — the review will be quick either way. After the review, produce a response table for every issue found (see discipline rules for format).]`,
       })
       callbacks.onTurnEnd?.(agent, turn)
       return { action: "continue", guardPushbacks, honestReminderInjected, advisorPushbacks }

package/src/agent/dispatch.mjs

@@ -5,10 +5,19 @@ import { logEvent, errText, headText } from "../log.mjs"
 import { offloadToolResult, FILE_MUTATORS } from "./helpers.mjs"
 import { runHooks } from "../hooks.mjs"
 import { snapshotForUndo } from "../tui/cmd-undo.mjs"
-import { isDocFile } from "../advisor/repos.mjs"
+import { isCodePath, loadConventions } from "../conventions.mjs"
+// R10 L3 (MULTI-INSTANCE-COLLAB §2a.5 D-L3b)：写工具钩子——peerCollabNote（执行前冲突
+// 检测——软提示不阻止）+ recordPeerWrites（成功后累积本回合写足迹——回合末 flush）。
+import { PEER_WRITE_TOOLS, peerCollabNote, recordPeerWrites } from "../peer-domains.mjs"
 import { writeFileSync, mkdirSync, existsSync } from "node:fs"
-import { join } from "node:path"
+import { join, resolve, relative } from "node:path"
 import { homedir } from "node:os"
+// §29 fix A（AGENT-LOOP.md §29——2026-09-07）：FILE_MUTATORS 的 mutation-seq 记账从
+// 批后提交（record-results noteMutations）移到执行成功即刻——唯一记账点（取代批后段
+// + agent.mjs 中断分支记账——不双计）——同消息 [写 + async advisor launch] 时 launch 前
+// 完成的写在 launchSeq 之前落地 → settle 不再误判 stale（§29 症状根因）。
+import { noteMutations, inflightDesignReviewConflict } from "../agent-tools/advisor-async.mjs"
+import { anyLiveDesignSlot } from "../token-ttl.mjs"
 
 const ERRORS_DIR = join(homedir(), ".thincoder", "tool-errors")
 
@@ -40,9 +49,9 @@ function logToolError(toolName, args, error) {
 
 /**
  * §19 action-level classification (AGENT-LOOP.md §19 D-M1): the merged subagent
- * tool expresses spawn (side effect) and check/status (read-only queries) through
+ * tool expresses spawn (side effect) and status (read-only query) through
  * its `action` parameter — the tool-level readonly flag can no longer express both.
- * dispatch Phase-1/Phase-2 classifies per action: check/status behave as readonly
+ * dispatch Phase-1/Phase-2 classifies per action: status behaves as readonly
  * (planMode pass / no permission ask / batchable), spawn keeps its non-readonly
  * gates, escalate runs non-readonly AND serially (the retired escalate tool had no
  * parallel flag — zero behavior change under the merged surface).
@@ -50,13 +59,13 @@ function logToolError(toolName, args, error) {
  * stops, never starts. isSubagentControlAction feeds the SAME two gate sites as
  * readonly (planMode pass / no permission ask — never joins a batch approval
  * group / no handler → not denied — digest 内 cancel 放行).
- * §19.6 panel (round1 #5): view 面归只读类（同 check/status——planMode 放行、免
+ * §19.6 panel (round1 #5): view 面归只读类（同 status——planMode 放行、免
  * 审批、可批并行）；freeze 面归控制类（同 cancel——planMode 放行、免权限审批、
  * 批审批不入组、digest 内放行）。freeze 存在（非空 key）即控制类——否则只读类。
  */
 function isSubagentReadonlyAction(toolName, args) {
   // §6 memory 工具面重构（MEMORY.md §6 D-M5）：memory search/list 是只读动作——与
-  // subagent check/status 同分类（planMode 放行/免审批——Phase-2 批并行只认工具级
+  // subagent status 同分类（planMode 放行/免审批——Phase-2 批并行只认工具级
   // readonly/parallel，memory 无 parallel → 按非只读串行，见 MEMORY.md §6.4 实现注）。
   // 动作级判定——不能按工具名（同一 memory 工具的 put/delete/clear 保持侧效门）。
   if (toolName === "memory") {
@@ -71,7 +80,10 @@ function isSubagentReadonlyAction(toolName, args) {
   }
   if (toolName !== "subagent" || !args || typeof args !== "object") return false
   const action = args.action
-  if (action === "check" || action === "status") return true
+  // §19.8: check 动作已删除——只读面仅剩 status（planMode 放行/免权限审批/可批并行）
+  if (action === "status") return true
+  // SUBAGENT-OBSERVE-SEND：observe = readonly 查询（同 status——digest/planMode 放行）
+  if (action === "observe") return true
   // §19.6 panel view 面（freeze 缺省/空 = 视图请求——readonly；非空 freeze 归控制类）
   if (action === "panel" && (args.freeze === undefined || args.freeze === null || String(args.freeze) === "")) return true
   return false
@@ -79,14 +91,44 @@ function isSubagentReadonlyAction(toolName, args) {
 function isSubagentControlAction(toolName, args) {
   if (toolName !== "subagent") return false
   if (args?.action === "cancel") return true
+  // SUBAGENT-OBSERVE-SEND：send = 控制类豁免（同 cancel——父回合内显式调用即授权——
+  // 写子输入队列属父对子轻量引导，非产品代码写——免审批、planMode 放行、digest 内放行）
+  if (args?.action === "send") return true
   // §19.6 panel freeze 面（D-P3 门控在 executor——只读/控制分类在此）
   if (args?.action === "panel" && args.freeze !== undefined && args.freeze !== null && String(args.freeze) !== "") return true
   return false
 }
+/**
+ * §2.6 token 链终消费制（2026-09-07——评审 #7d dispatch 分类）：consume-design =
+ * 非只读控制动作——planMode 拒绝（不入 readonly/control 豁免——与其他非只读动作同门）、
+ * 免权限审批、不入批审批分组（无文件写——控制类直行——只停既有状态不起新副作用）。
+ * 与 cancel 的不同：cancel 是控制类豁免（planMode 放行），consume-design 按设计
+ * planMode 拒绝——故不并入 isSubagentControlAction，单独谓词只接权限豁免位。
+ */
+function isSubagentConsumeDesignAction(toolName, args) {
+  return toolName === "subagent" && args?.action === "consume-design"
+}
 function isSubagentEscalateAction(toolName, args) {
   return toolName === "subagent" && args?.action === "escalate"
 }
 
+/**
+ * §29 fix A — 唯一记账点：FILE_MUTATORS 工具执行成功即刻记 mutation seq（abs 路径）。
+ * 取代 record-results 批后段 + agent.mjs 中断分支的 noteMutations（不双计——中断+同批
+ * launch 场景 seq 单计，AGENT-LOOP.md §29 T-A1i）。调用时机 = 写执行成功（非 Error 前缀
+ * 结果——recordPeerWrites 同款门）；routed（M2 ACP 客户端执行）成功同样记账。
+ */
+function noteExecutedMutation(agent, tool, args) { 
+  let paths
+  try {
+    paths = tool.touchedPaths ? tool.touchedPaths(args ?? {}) : [args?.path]
+  } catch { return }
+  const abs = (paths ?? [])
+    .filter((p) => typeof p === "string" && p)
+    .map((p) => resolve(agent.cwd, p))
+  if (abs.length > 0) noteMutations(agent, abs)
+}
+
 /**
  * Two-phase execution:
  * Phase 1 (serial): parse args one by one + planMode check + permission confirmation (side-effecting tools)
@@ -138,24 +180,61 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
     }
 
     // Engineering mode PARENT gate: the parent agent must not touch code files
-    // before the design review passed. Signaled by _engDesignToken — set on
-    // design-review approval, survives across turns (_engDesignReviewed is
-    // eng-coder-only and reset per run). Exemptions cover ONLY design artifacts
-    // (docs/** and root-level docs like METHODOLOGY.md/README.md/AGENTS.md/
-    // LICENSE) — writing them IS the design/methodology step. Everything under
-    // src/ (incl. src/prompts/*.md) is product code, not documentation, and
-    // needs a design token. Mechanically blocks "talk then code".
-    if (agent.config?.agent?.engineering && depth === 0 && !agent._engDesignToken
+    // before the design review passed. Signaled by a live design slot (design-review
+    // approval — persists in the session slot, survives across turns; _engDesignReviewed
+    // is eng-coder-only and reset per run). Exemptions = the non-code classes of
+    // src/conventions.mjs (documentation and temp scratch files) — writing a design
+    // document IS the design step. Anything inside a declared code segment (default:
+    // src — incl. src/prompts/*.md) is product code, not documentation, and needs a
+    // design token. The project can declare its own code paths (.thincoder/
+    // conventions.json) so a non-src layout is not silently exempted. Mechanically
+    // blocks "talk then code".
+    // DESIGN-TOKEN-SETTLEMENT D3（2026-09-08）：资格判据 = 权威槽"任一活槽存在"
+    // （anyLiveDesignSlot——查内存 Map，miss 回读槽文件——单值镜像 `_engDesignToken`
+    // 已退役，门禁不再读镜像——AC4）。
+    if (agent.config?.agent?.engineering && depth === 0
+        && !anyLiveDesignSlot(agent)
         && FILE_MUTATORS.has(toolCall.name)) {
       const paths = tool.touchedPaths ? tool.touchedPaths(args) : [args.path]
+      const conv = loadConventions(agent.cwd)
       // Unknown/missing paths (non-string, e.g. no path argument) are treated
-      // as code — cannot tell what they touch, so block conservatively.
-      const touchesCode = paths.some((p) => typeof p !== "string" || /^src[\\/]/.test(p) || !isDocFile(p))
+      // as code — cannot tell what they touch, so block conservatively. Known
+      // paths go through the single shared classifier: a declared code segment
+      // (default: "src") at ANY depth, else anything that is not documentation.
+      const touchesCode = paths.some((p) => typeof p !== "string" || isCodePath(p, conv))
       if (touchesCode) {
+        // Undeclared project → point at the declaration file (§4.3 降级可见契约).
+        const convNote = conv.declared
+          ? ""
+          : ` — this path was classified as product code by the default conventions (code paths: ${conv.codePaths.join(", ")}); declare project conventions in .thincoder/conventions.json to adjust.`
         prepared.push({
           toolCall, tool, denied: true,
           reason: "engineering design gate",
-          hint: "Engineering mode: write the design document in docs/ first, then call advisor with type='design' to review it, and wait for user approval. Implementation is done by eng-coder subagents.",
+          hint: `Engineering mode: write the design document first（location per your project's document conventions）, then call advisor with type='design' to review it, and wait for user approval. Implementation is done by eng-coder subagents.${convNote}`,
+        })
+        continue
+      }
+    }
+
+    // E（第 11 批·F17/§14.14 E-3d）：D5 冻结窗口写前拦截——设计评审在途（点火 → 结算）期间，
+    // 父侧对被审文件集（声明文档集 + 批次档）的写入会被拒绝：在途写使本轮结算 stale——pass 轮
+    // = token 直接丢失（实证：第 10 批 id=20 整轮作废）。工具面 = FILE_MUTATORS（与变更记账
+    // 同集——不记入日志的写面既不判 stale 也不拦）；判据与 reviewIsStale 同源
+    // （inflightDesignReviewConflict——同 docAbs / 同 normAbs；仅扫 running 未取消的设计条目）。
+    // 位置：只读 / autoApprove 短路之前——审批不得绕过冻结；拒绝 = 可见 denied + 逃生门
+    // （先 cancel → 改 → 重发）。
+    if (FILE_MUTATORS.has(toolCall.name)) {
+      let touched = []
+      try { touched = tool.touchedPaths ? tool.touchedPaths(args) : [args.path] } catch { touched = [] }
+      const absPaths = (touched ?? [])
+        .filter((p) => typeof p === "string" && p)
+        .map((p) => resolve(agent.cwd, p))
+      const conflict = inflightDesignReviewConflict(agent, absPaths)
+      if (conflict) {
+        prepared.push({
+          toolCall, tool, denied: true,
+          reason: "d5 freeze window",
+          hint: `write refused — design review #${conflict.id} is in flight over ${relative(agent.cwd, conflict.path)} (D5 freeze window). A write now would settle it stale — no token for a pass (the round is lost). Wait for the report, or cancel the review first (subagent action:'cancel' id:'${conflict.id}') and re-launch after the change.`,
         })
         continue
       }
@@ -171,7 +250,7 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
     // — the exemption never widens what reaches this stage (round4 #3, T-E14).
     // PreToolUse hooks still run below. Non-eng-coder children keep the manual
     // parent ask (human in the loop).
-    if (tool.readonly || isSubagentReadonlyAction(toolCall.name, args) || isSubagentControlAction(toolCall.name, args) || agent.autoApprove || agent._engTaskAuthorized) {
+    if (tool.readonly || isSubagentReadonlyAction(toolCall.name, args) || isSubagentControlAction(toolCall.name, args) || isSubagentConsumeDesignAction(toolCall.name, args) || agent.autoApprove || agent._engTaskAuthorized) {
       if (!(await runHooks("PreToolUse", { agent, toolName: toolCall.name, toolArgs: args }))) {
         prepared.push({ toolCall, tool, denied: true, reason: "blocked by PreToolUse hook" })
         continue
@@ -247,6 +326,8 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
         ? "Error: plan mode is active — only read-only tools are allowed. Exit plan mode first."
         : item.reason === "engineering design gate"
           ? `Error: design review required before any file modification. ${item.hint}`
+          : item.reason === "d5 freeze window"
+          ? `Error: ${item.hint}`
           : item.reason === "denied by user"
           ? "Error: permission denied by user"
           : item.reason === "blocked by PreToolUse hook"
@@ -267,6 +348,11 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
     const toolName = item.toolCall.name
     logEvent("tool:call", { tool: toolName, child: agent?._logId })
     try {
+      // R10 L3 (MULTI-INSTANCE-COLLAB §2a.5 D-L3b)：结构化写工具执行前查 conflicts
+      // （命中他实例 hot 域 → 结果附软提示——决策⑥ A 不阻止；一次目录 stat——N3 度量）；
+      // 足迹累积（D-L3a——"检测+记录一次完成"）延后到执行成功（实际写过的文件）。
+      const isPeerWriteTool = PEER_WRITE_TOOLS.has(toolName)
+      const peerNote = isPeerWriteTool ? peerCollabNote(agent.cwd, item.tool, item.args) : null
       // Snapshot for undo before side-effect tools (setupOutputPanel already fired in Phase 1)
       if (!item.tool?.readonly && item.args) {
         snapshotForUndo(agent, item.toolCall.name, item.args, agent.cwd)
@@ -276,9 +362,14 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
       if (callbacks.toolRouter) {
         const routed = await callbacks.toolRouter(item.toolCall.name, item.args)
         if (routed?.handled) {
-          callbacks.onToolResult?.(item.toolCall.name, routed.result, item.toolCall.id)
-          logEvent("tool:done", { tool: toolName, ms: Date.now() - toolT0, head: headText(routed.result, 200), child: agent?._logId })
-          return { ...item, result: routed.result, ok: true }
+          const routedOk = !String(routed.result).startsWith("Error:")
+          const routedResult = peerNote && routedOk ? `${routed.result}\n${peerNote}` : routed.result
+          if (isPeerWriteTool && routedOk) recordPeerWrites(agent, item.tool, item.args)
+          // §29 fix A：routed 写成功（客户端执行）同样执行期即刻记账（唯一记账点）
+          if (routedOk && FILE_MUTATORS.has(toolName)) noteExecutedMutation(agent, item.tool, item.args)
+          callbacks.onToolResult?.(item.toolCall.name, routedResult, item.toolCall.id)
+          logEvent("tool:done", { tool: toolName, ms: Date.now() - toolT0, head: headText(routedResult, 200), child: agent?._logId })
+          return { ...item, result: routedResult, ok: true }
         }
       }
       const origConsoleLog = console.log
@@ -296,18 +387,41 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
         depth,
         signal,
         callbacks,
+        // §11.2 D-24b: per-call id — the advisor tool marker-keys its launch so
+        // recordToolResults can split async-ack accounting from sync settles.
+        _toolCallId: item.toolCall.id,
         onOutput: (chunk) => callbacks.onToolOutput?.(item.toolCall.name, chunk, item.toolCall.id),
         onQuestion: callbacks.onQuestion,
         onPermissionRequest: callbacks.onPermissionRequest,
       }
       try {
-        rawResult = await item.tool.execute(item.args, toolCtx)
+        // SUBAGENT-OBSERVE-SEND D1（评审 #1）：in-flight 当前工具记账——工具执行期间在
+        // agent 上留 _inflightTools Set（子代理 observe 从 dispatch 状态读——卡在长工具
+        // 调用时 history 无新回合、恰需此信号）；finally 清除。批并行工具同入 Set（observe
+        // 如实返回多个在跑工具）。主会话同样记账——无害（无人读）。
+        const inflight = agent._inflightTools ?? (agent._inflightTools = new Set())
+        inflight.add(toolName)
+        try {
+          rawResult = await item.tool.execute(item.args, toolCtx)
+        } finally {
+          inflight.delete(toolName)
+        }
       } finally {
         console.log = origConsoleLog
         console.error = origConsoleErr
       }
       if (rawResult === undefined) throw new Error(`Tool "${item.toolCall.name}" returned undefined — all tools must return a string value`)
       const raw = String(rawResult)
+      // 写成功（非 "Error:" 字符串结果）→ 足迹计入本回合集合（flush 在 finalizeAgentTurn）
+      if (isPeerWriteTool && !raw.startsWith("Error:")) {
+        recordPeerWrites(agent, item.tool, item.args)
+      }
+      // §29 fix A：FILE_MUTATORS 执行成功即刻记账（唯一记账点——取代 record-results 批后
+      // 段 + agent.mjs 中断分支——不双计）——同批 launch 前的写在 launchSeq 之前落地 →
+      // async advisor settle 不误判 stale（同批 launch 后写仍保守 stale——T-A2/T-24b9）。
+      if (FILE_MUTATORS.has(toolName) && !raw.startsWith("Error:")) {
+        noteExecutedMutation(agent, item.tool, item.args)
+      }
       // Multimodal tools keep the raw result (base64 images ride the multimodal
     // channel); everything else offloads oversized text to disk. Flag-driven, not
     // name-driven (consult P3, 2026-08-30).
@@ -316,11 +430,15 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
       const resultWithConsole = capturedConsole.length > 0
         ? `${result}\n[console during ${item.toolCall.name}]\n${capturedConsole.join("\n")}`
         : result
-      callbacks.onToolResult?.(item.toolCall.name, resultWithConsole, item.toolCall.id, toolCtx._subagentKey)
+      // R10 L3：冲突软提示附在工具结果末尾（模型可见——不阻止写）
+      const resultForModel = peerNote && !raw.startsWith("Error:")
+        ? `${resultWithConsole}\n${peerNote}`
+        : resultWithConsole
+      callbacks.onToolResult?.(item.toolCall.name, resultForModel, item.toolCall.id, toolCtx._subagentKey)
       // PostToolUse hooks: fire-and-forget (result not awaited on hook failure)
       runHooks("PostToolUse", { agent, toolName: item.toolCall.name, toolArgs: item.args, result: raw }).catch(() => {})
-      logEvent("tool:done", { tool: toolName, ms: Date.now() - toolT0, head: headText(resultWithConsole, 200), child: agent?._logId })
-      return { ...item, result: resultWithConsole, ok: true }
+      logEvent("tool:done", { tool: toolName, ms: Date.now() - toolT0, head: headText(resultForModel, 200), child: agent?._logId })
+      return { ...item, result: resultForModel, ok: true }
     } catch (error) {
       // Persist to ~/.thincoder/tool-errors/ for post-mortem; only pass message to the model (stack traces confuse LLMs and may leak paths)
       logToolError(item.toolCall.name, item.args, error)
@@ -357,7 +475,7 @@ export async function executeToolCalls(agent, toolByName, toolCalls, callbacks,
   for (const item of prepared) {
     // escalate action keeps the retired escalate tool's serial placement (no
     // parallel flag): it flushes the batch and runs alone in call order (§19 —
-    // spawn stays parallel; check/status classify as readonly and batch freely).
+    // spawn stays parallel; status classifies as readonly and batch freely).
     if (item.tool && !item.tool.readonly
         && (!item.tool.parallel || isSubagentEscalateAction(item.tool.name, item.args))) {
       await flush()

package/src/agent/helpers.mjs

@@ -6,7 +6,8 @@ import { readFileSync, readdirSync } from "node:fs"
 import { homedir } from "node:os"
 import { writeFile, mkdir, readdir, stat, unlink } from "node:fs/promises"
 import { join } from "node:path"
-import { execSync } from "node:child_process"
+import { execFile } from "node:child_process"
+import { promisify } from "node:util"
 
 /** Single source for the AUTO-mode reminder (was duplicated in agent.mjs +
  *  setup.mjs — consult P2, 2026-08-30). */
@@ -138,20 +139,65 @@ export async function offloadToolResult(text, callId, dir = join(configDir, "too
   }
 }
 
-/** Collect git branch, recent commits, and working tree status as context text */
-export function collectGitContext(cwd) {
+// 失败冷却 v1（用户裁——GIT-ASYNC L21）：真失败/超时后 30s 内跳过该 cwd 的收集——
+// 病态 repo 周期拖慢变一次性。VSC setup-reminders.mjs 同构镜像。
+const GIT_FAILURE_COOLDOWN_MS = 30_000
+/** cwd → 最近一次 git 收集失败的 ts。评审 #2：访问时惰性清 >30s 旧条目（防无界累积）。 */
+const gitFailureCooldowns = new Map()
+// maxBuffer 沿用 execSync 默认现值 1 MiB（评审 #1——防大输出仓 ENOBUFS 翻转 → "" 破字节 parity）
+const GIT_MAX_BUFFER = 1024 * 1024
+
+const execFileAsync = promisify(execFile)
+
+/** 冷却检查 + 惰性清扫：冷却期内的 cwd 返回 true（调用方直接 "" 跳过）。 */
+function gitCooldownActive(cwd) {
+  const now = Date.now()
+  const lastFailure = gitFailureCooldowns.get(cwd)
+  if (lastFailure === undefined) return false
+  if (now - lastFailure >= GIT_FAILURE_COOLDOWN_MS) {
+    gitFailureCooldowns.delete(cwd) // 惰性清过期条目
+    return false
+  }
+  return true
+}
+
+/** Test seams — cooldown Map 状态控制（生产从不调用）：
+ *  `_gitFailureCooldownForTests(cwd, ts)` 读（ts 省略）或写 ts；`_clear…` 删条目。 */
+export function _gitFailureCooldownForTests(cwd, ts) {
+  if (ts !== undefined) gitFailureCooldowns.set(cwd, ts)
+  return gitFailureCooldowns.get(cwd)
+}
+export function _clearGitFailureCooldownForTests(cwd) {
+  gitFailureCooldowns.delete(cwd)
+}
+
+/** Git context 纯格式化（branch/log/status = trim 后原串）——独立导出供单测锁字节
+ *  parity（现拼装逐字节保留——detached/dirty>20 截断/clean 三形态——VSC 镜像）。 */
+export function composeGitContext({ branch, log, status }) {
+  const dirty = status ? status.split("\n").length : 0
+  return [
+    `Git context: on branch \`${branch || "(detached)"}\`${dirty ? `, ${dirty} uncommitted change(s)` : ", working tree clean"}.`,
+    log ? `Recent commits:\n${log}` : "",
+    status ? `Uncommitted:\n${status.split("\n").slice(0, MAX_GIT_CHANGES_DISPLAY).join("\n")}${dirty > MAX_GIT_CHANGES_DISPLAY ? `\n… (${dirty - MAX_GIT_CHANGES_DISPLAY} more)` : ""}` : "",
+  ].filter(Boolean).join("\n")
+}
+
+/** Collect git branch, recent commits, and working tree status as context text.
+ *  GIT-ASYNC L21：3×execSync 串行（最坏 15s 阻塞）→ 3×execFile 并行（Promise.all——
+ *  最坏 = 单次 5s 超时——事件循环不冻结）。单 catch → "" 保持 all-or-nothing（任一
+ *  失败/超时 → 整段不注入——非 git 快失败同路径）；catch 记冷却 ts——30s 内跳过。 */
+export async function collectGitContext(cwd) {
+  if (gitCooldownActive(cwd)) return ""
   try {
-    const opts = { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: GIT_TIMEOUT_MS }
-    const branch = execSync("git branch --show-current", opts).trim()
-    const log = execSync("git --no-pager log --oneline -5", opts).trim()
-    const status = execSync("git status --short", opts).trim()
-    const dirty = status ? status.split("\n").length : 0
-    return [
-      `Git context: on branch \`${branch || "(detached)"}\`${dirty ? `, ${dirty} uncommitted change(s)` : ", working tree clean"}.`,
-      log ? `Recent commits:\n${log}` : "",
-      status ? `Uncommitted:\n${status.split("\n").slice(0, MAX_GIT_CHANGES_DISPLAY).join("\n")}${dirty > MAX_GIT_CHANGES_DISPLAY ? `\n… (${dirty - MAX_GIT_CHANGES_DISPLAY} more)` : ""}` : "",
-    ].filter(Boolean).join("\n")
+    const opts = { cwd, encoding: "utf8", timeout: GIT_TIMEOUT_MS, windowsHide: true, maxBuffer: GIT_MAX_BUFFER }
+    const [branch, log, status] = await Promise.all([
+      execFileAsync("git", ["branch", "--show-current"], opts).then((r) => r.stdout.trim()),
+      execFileAsync("git", ["--no-pager", "log", "--oneline", "-5"], opts).then((r) => r.stdout.trim()),
+      execFileAsync("git", ["status", "--short"], opts).then((r) => r.stdout.trim()),
+    ])
+    return composeGitContext({ branch, log, status })
   } catch {
+    gitFailureCooldowns.set(cwd, Date.now()) // 真失败/超时——冷却 30s
     return ""
   }
 }
@@ -164,6 +210,18 @@ export class ContinueError extends Error {
   }
 }
 
+/** 跨段累计编号帧（TURN-CAP-CONTINUE.md §19.3——第 19 批 TURN-ACROSS-SEGMENTS）：
+ *  唯一计算点（纯函数）——把链内累计序数换算成面向消费面的编号载荷。
+ *  - seq      = 该轮链内累计序数（1 起——`agent._turnSeq` 每轮 +1，续跑不重置）
+ *  - turn     = 段内轮号（0 起——段内帽判定的循环变量）
+ *  - maxTurns = 本段预算（段内帽判定值——原样传入）
+ *  返回 { turn, maxTurns }：turn = seq（累计已跑轮数）；maxTurns = 段前累计 + 本段预算
+ *  = seq - turn - 1 + maxTurns（差额项 = 本段开始前的链内累计）。
+ *  段内帽判定不读本帧（只读段内 turn / maxTurns——N6 零机制改动）。 */
+export function turnFrame(seq, turn, maxTurns) {
+  return { turn: seq, maxTurns: seq - turn - 1 + maxTurns }
+}
+
 /** Repair malformed conversation history: remove orphan tool messages and fill missing tool results */
 export function repairHistory(history) {
   const out = []
@@ -288,3 +346,39 @@ export async function loadProjectInstructions(cwd) {
     merged
   )
 }
+
+// Engineering mode reminders + auto-turn digest domain + mode injector
+// （2026-09-05 module-split：自 agent.mjs 迁入——agent.mjs 530 > 500 硬限——agent.mjs
+// re-export 保 import 面：eng.mjs / cmd-eng.mjs / 测试从 agent.mjs import）
+
+/** 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.]"
+
+/** 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. */
+export 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.) */
+export 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
+}
+