@thincoder/core 0.9.1

package/agent/record-results.mjs

@@ -0,0 +1,174 @@
+/**
+ * record-results.mjs — tool result commit + mutation accounting (split from
+ * agent.mjs 2026-08-30, consult P2: the 100-line loop was pure bookkeeping
+ * mixed into the run loop; it now lives behind one call).
+ *
+ * Contract (moved verbatim from the run loop):
+ *  - Multimodal tool results ({ text, images }) close the tool pairing with a
+ *    tool message, then inject the images as a multimodal user message — but
+ *    NEVER between tool messages of parallel calls (strict providers 400 when
+ *    a tool message does not immediately follow its assistant tool_calls), so
+ *    image injections are DEFERRED until all results are committed.
+ *  - Non-vision models get a text-only System-reminder instead of image parts
+ *    (image parts 400 on every subsequent request — defense-in-depth).
+ *  - FILE_MUTATORS invalidate advisor/verify state (code changed → prior
+ *    review/verify is stale); non-mutating side-effect tools (bash/git)
+ *    invalidate verify only (user decision 2026-08-08: reviews trigger on
+ *    code mutations, not environment changes).
+ *  - advisor calls always advance _advisorRound (convergence budget counts
+ *    attempts, not successes — 轮次仅作提示词衰减与显示，**无机械上限**). §15 F16 (2026-09-11 第 13 批): the SYNC
+ *    called-mark is gated by the single incomplete-tail predicate
+ *    (advisorIncompleteMarker) — a truncated-then-settled CODE review must not
+ *    count as covered (the guard re-pushes); design reviews keep the mark
+ *    (no code face — settle-side `failureVerdict` parity).
+ *  - Mutations feed _touchedFiles and fire-and-forget memory reindex.
+ */
+import { pushReal } from "../context.mjs"
+import { specForModel } from "../config.mjs"
+import { FILE_MUTATORS } from "./helpers.mjs"
+import { resolve } from "node:path"
+import { advisorRuns, stripApprovedSuffix } from "../agent-tools/advisor-async.mjs"
+import { looksLikeReviewOutput, advisorIncompleteMarker } from "../advisor/run.mjs"
+
+let _reindexFile = null
+
+export async function recordToolResults(agent, toolByName, results) {
+  // Multimodal user messages (injected images / not-injected reminders) must NOT be pushed
+  // between tool results of parallel calls — strict providers (DeepSeek) 400 when a tool
+  // message does not immediately follow its assistant tool_calls. Defer to after the loop.
+  // real: image injections are real messages (pushReal → _fullHistory); reminders stay machine-only.
+  const deferredUserMsgs = []
+
+  for (const { toolCall, result, ok } of results) {
+    const tool = toolByName.get(toolCall.name)
+    // Multimodal tools return JSON { text, images } — inject as multimodal user message
+    if (tool?.multimodal && ok) {
+      try {
+        const parsed = JSON.parse(result)
+        if (parsed.images?.length) {
+          // tool message first — closes the tool_call pairing (OpenAI API requires tool result immediately after assistant with tool_calls)
+          pushReal(agent, { role: "tool", tool_call_id: toolCall.id, name: toolCall.name, content: parsed.text })
+          if (specForModel(agent.provider.model).multimodal) {
+            // then inject multimodal user message with base64 images for the model to actually "see" them on the next turn
+            deferredUserMsgs.push({
+              real: true,
+              msg: {
+                role: "user",
+                content: [{ type: "text", text: parsed.text }, ...parsed.images],
+              },
+            })
+          } else {
+            // Non-vision model: image parts must never enter history — text-only APIs 400 on them on EVERY
+            // subsequent request, poisoning the conversation. (read_image itself already refuses; this is defense-in-depth.)
+            deferredUserMsgs.push({
+              real: false,
+              msg: {
+                role: "user",
+                content: `[System reminder: the image returned by ${toolCall.name} was NOT injected — model ${agent.provider.model} does not support image input. Do not call ${toolCall.name} again under this provider; verify visual output programmatically instead.]`,
+              },
+            })
+          }
+          continue
+        }
+      } catch { /* Parse failure doesn't affect normal tool messages */ }
+    }
+    pushReal(agent, { role: "tool", tool_call_id: toolCall.id, name: toolCall.name, content: result })
+    if (tool && ok) {
+      if (FILE_MUTATORS.has(toolCall.name)) {
+        // Direct file edit — code was changed. The prior advisor review and
+        // verify are stale: a review that ran before the edit no longer
+        // covers the current file state.
+        // §29 fix A（AGENT-LOOP.md §29——2026-09-07）：mutation-seq 记账已移到 dispatch
+        // runOne 执行成功即刻（唯一记账点——取代本批后段 + agent.mjs 中断分支——不双计）——
+        // 此处仅剩 guard 标志失效（顺序语义：批内同消息的 sync advisor 提交仍在其后置位）。
+        agent._mutatedThisRun = true
+        agent._calledAdvisorThisRun = false
+        agent._verifiedThisRun = false
+        agent._verifyPassed = undefined
+      } else if (!tool.readonly && !tool.sideEffectExempt) {
+        // Non-mutating side-effect tools (bash, git): do NOT invalidate the
+        // advisor review — a review is triggered by CODE MUTATIONS only
+        // (user decision 2026-08-08: the guard rule is "review after code
+        // changes", not "review after any environment change"; bash is
+        // barred from writing files, so it cannot change the reviewed code).
+        // Verify IS invalidated: its state snapshot (git diff, file list)
+        // may be stale after git/shell operations.
+        if (agent._verifiedThisRun) {
+          agent._verifiedThisRun = false
+          agent._verifyPassed = undefined
+        }
+      }
+      if (toolCall.name === "verify") agent._verifiedThisRun = true
+      if (toolCall.name === "advisor") {
+        // §11.2 D-24b (settle accounting split — fix #2): an ASYNC launch returns an
+        // ack and settles later — the settle callback owns its called/round/token
+        // accounting. Only the SYNC path (depth>0 / explicit async:false) accounts
+        // here — per-review instance round++ (marker-keyed by tool call id) + the
+        // legacy mirror._advisorRound_ counter stays for display/back-compat.
+        // REFUSED launches (type gate / scope guard / same-scope in flight / launch
+        // refusal) count as neither a call nor a completion: no called-mark (the guard
+        // must keep pushing until a review really runs), no round advance.
+        const refused = agent._advisorRefusals?.has(toolCall.id)
+        const asyncAck = agent._advisorAsyncAcks?.has(toolCall.id)
+        if (refused) {
+          agent._advisorRefusals.delete(toolCall.id)
+        } else if (asyncAck) {
+          agent._advisorAsyncAcks.delete(toolCall.id)
+        } else {
+          const reviewId = agent._advisorSyncCalls?.get(toolCall.id)
+          const run = reviewId !== undefined ? advisorRuns(agent).get(reviewId) : undefined
+          // F16 同步面（第 13 批 §15.2——ADVISOR-CONVERGENCE.md §15）：未完成尾 + 非设计面
+          // （含类型不可判——run 缺失的 legacy 直调）⇒ 不置「已覆盖」（与 settle 面
+          // 逐条 parity；设计评审保持计入——无代码面）。
+          const incomplete = advisorIncompleteMarker(String(result))
+          if (!(incomplete && run?.reviewType !== "design")) agent._calledAdvisorThisRun = true
+          if (reviewId !== undefined) {
+            if (run) {
+              run.round++
+              agent._advisorRound = run.round
+              // Prior of round 2+ = the last REVIEW-LOOKING output (run.mjs parity).
+              // F2e (§29.1): the sync settle's engine-approved suffix (stored on the
+              // run by settleDesignReview) is stripped with exact truncation — the
+              // prior never carries the raw token / designId.
+              if (looksLikeReviewOutput(result)) {
+                run.priorOutput = stripApprovedSuffix(result, run.approvedSuffix)
+              }
+            } else {
+              agent._advisorRound++
+            }
+            agent._advisorSyncCalls.delete(toolCall.id)
+          } else {
+            // Direct/legacy callers without a resolution marker — plain mirror
+            // increment (the per-review registry never saw this call).
+            agent._advisorRound++
+          }
+        }
+      }
+      if (FILE_MUTATORS.has(toolCall.name)) {
+        const args = JSON.parse(toolCall.arguments)
+        const paths = tool.touchedPaths ? tool.touchedPaths(args) : [args.path]
+        for (const p of paths) {
+          const abs = resolve(agent.cwd, p)
+          if (!agent._touchedFiles.includes(abs)) agent._touchedFiles.push(abs)
+          if (agent.memory) {
+            // Fire-and-forget: don't block the agent loop on indexing.
+            // Reuses a single cached import; errors surface as pending reminders on next turn.
+            if (!_reindexFile) {
+              const mod = await import("../memory.mjs")
+              _reindexFile = mod.reindexFile
+            }
+            _reindexFile(agent.memory, agent.cwd, abs).catch((e) => {
+              agent._pendingReminders.push(`[System reminder: background indexing failed for ${toolCall.name} on ${abs}: ${e.message}. This does not affect your work — the code index will catch up on next reindex.]`)
+            })
+          }
+        }
+      }
+    }
+  }
+
+  // All tool results committed — now safe to inject deferred multimodal user messages
+  for (const { real, msg } of deferredUserMsgs) {
+    if (real) pushReal(agent, msg)
+    else agent.history.push(msg)
+  }
+}

package/agent/relay-prefix.mjs

@@ -0,0 +1,39 @@
+/**
+ * relay-prefix.mjs — relay 前缀（`role#id/`）文法**单一权威**（第 27 批 §12.3①——R-A2.3）。
+ *
+ * 零依赖（不 import 任何模块）——TUI（`src/tui/`）与 ACP（`src/acp/`）双向可导入，无环；
+ * 生成侧 `src/agent/spawn-child.mjs` 再导出（枢纽）。文法 = 自
+ * `src/tui/subagent-blocks.mjs` 逐字迁入（第 27 批 §12.3②——零语义改动）。
+ */
+
+/** `role#id/` prefix router — hyphen included since the eng-coder fix (2026-08-21). */
+export const RELAY_PREFIX_RE = /^([\w-]+)#(\d+)\//
+
+/** 嵌套 relay 前缀通用解析（循环解析任意深度——显示契约 docs/design/TUI.md §6）：
+ *  `eng-coder#2/explore#1/read` → { head（块路由）, inner[], label（inner 链——R23：
+ *  子块折叠键/外层 currentTool 全路径用）, rest }。
+ *  单层 = inner[]/label ""——与既有单段匹配语义零改；无前缀 → null。 */
+export function parseRelayPath(text) {
+  const segments = []
+  let rest = String(text)
+  for (;;) {
+    const m = rest.match(RELAY_PREFIX_RE)
+    if (!m) break
+    segments.push(`${m[1]}#${m[2]}`)
+    rest = rest.slice(m[0].length)
+  }
+  if (segments.length === 0) return null
+  return {
+    head: segments[0],
+    inner: segments.slice(1),
+    label: segments.slice(1).join("/"),
+    rest,
+  }
+}
+
+/** 构造向单一实现（本批统一的两处构造点——`makeRelay` 与 async 取号分支共用；
+ * 另两处字面构造（escalate/advisor async）不在本批声明面——批次档 §2 修正轮登记，如需收敛另批）：
+ *  `relayPrefixOf("coder", 3)` → `"coder#3/"`。 */
+export function relayPrefixOf(label, id) {
+  return `${label}#${id}/`
+}

package/agent/run-stages.mjs

@@ -0,0 +1,244 @@
+/**
+ * run-stages.mjs — runAgent 主循环的阶段函数族（CLI，2026-09-05 实践轮：agent.mjs
+ * runAgent 383 ≥300 按骨干—细节两层提取——VS Code 端同构文件（双端 parity——拆分
+ * 两端同步））。本文件承载：回合压缩检查（runCompactionCheck）、回合注入组
+ * （injectTurnReminders——plan cadence + eng 状态）、回合收尾（finalizeAgentTurn——
+ * consult 清理/async 池分流/guard 继承）与其收集器（collectSettledAsync——自
+ * agent.mjs 迁入，agent.mjs 内无其他引用）。verbatim 迁移 + 签名化，语义零变。
+ */
+
+import { compressIfNeeded, compressFallback, COMPRESS_FAILURE_LIMIT } from "../context.mjs"
+import { ensureAutoReminder, injectEngineeringReminder, ContinueError, snapshotGuard } from "./helpers.mjs"
+import { pushManifestStateReminder } from "./setup-reminders.mjs"
+import { cleanupConsultSessions } from "../agent-tools/consult.mjs"
+import { logEvent } from "../log.mjs"
+// ASYNC-RESULT-CONTAINER.md D1：池 accessor（absorb 双池——advisor 独立池无队列）
+import { getAsyncPool, releaseSettledEntry } from "../agent-tools/async-settle.mjs"
+// 批 4 CLI-ASYNC-DISCARD（AGENT-LOOP-SUBAGENT.md §6.20）：中止分支「只清已死」收尾单点
+import { discardAbortedPool, discardAbortedAdvisors } from "../agent-tools/async-discard.mjs"
+// R10 L3 (MULTI-INSTANCE-COLLAB §2a.5 D-L3a)：回合末域登记 flush（写工具钩子累积 →
+// 整写一次本实例 peers 文件——无写入跳过；失败容忍不抛）
+import { flushPeerDomains } from "../peer-domains.mjs"
+// 第 30 批 D1（Stop 钩子——AGENT-LOOP.md §21）：主会话 run 终止事件（触发块见 finalizeAgentTurn）
+import { runHooks } from "../hooks.mjs"
+
+/**
+ * 响应后置提醒注入（2026-09-05 实践轮——自 runAgent 响应处理链提取，verbatim）：
+ * 流规则 warning（warn 动作——流已完成——去重注入，模型下轮可见）+ 异常 finish
+ * reason 警告（响应可能不完整/截断——reasonMap 人类化描述注入）。
+ */
+export function injectResponseReminders(agent, response) {
+  // 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")}]`,
+    })
+  }
+
+  // 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 实践轮——自 runAgent 主循环提取）：仅安全点（history 以
+ * 完整交换结尾——user/tool 位）。成功：失败计数清零/计划提醒 cadence 复位/停滞检测
+ * 计数复位（recentCallSigs——runAgent 回合级局部——经 ctx 传对象引用）/压缩完成事件
+ * /AUTO 提醒重注入。失败：AbortError 透传；计数 + Q3 onCompressFail；
+ * COMPRESS_FAILURE_LIMIT 连续失败降级 compressFallback（确定性截断——不发 LLM）。
+ */
+export async function runCompactionCheck(agent, ctx) {
+  const { threshold, callbacks, compactionOverhead, signal, recentCallSigs } = ctx
+  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 ?? {})
+    }
+  }
+}
+
+/**
+ * 回合注入组（2026-09-05 实践轮——自 runAgent 主循环提取）：plan-mode 提醒 cadence
+ * （稀疏 2 轮/满 5 轮/新用户消息重置——限制不淡化）+ 工程模式状态注入（depth-0 每新
+ * 用户消息一次——见 injectEngineeringReminder）。verbatim——语义零变。
+ */
+export async function injectTurnReminders(agent, ctx) {
+  const { depth } = ctx
+  // 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 })
+    }
+  }
+
+  // Engineering-mode status injection on every new user message (design-before-code
+  // vs standard discipline) — see injectEngineeringReminder.
+  if (depth === 0) {
+    injectEngineeringReminder(agent)
+    pushManifestStateReminder(agent, { depth }) // M1 情境行（MANIFEST.md §2.6——同序组，eng 之后）
+  }
+}
+
+/**
+ * 回合收尾（2026-09-05 实践轮——自 runAgent finally 提取，verbatim + 签名化）：写足迹
+ * flush → Stop 钩子（第 30 批 D1——ctx.depth === 0 的主会话 run 终止事件，
+ * fire-and-forget）→ consult 清理（无孤儿烧 token 的 consult children）→ async 池回合尾
+ * 分流（Ctrl+C 清池不注入 / ContinueError 留池续跑 / 其余 collectSettledAsync）→ auto-turn
+ * guard 标记继承（对象字段清单——正常结束才继承；中止丢弃；ContinueError 由续跑快照）。
+ */
+export async function finalizeAgentTurn(agent, ctx) {
+  const { signal, autoTurn, suspDriven, thrownError, depth } = ctx
+  // R10 L3（MULTI-INSTANCE-COLLAB §2a.5 D-L3a）：回合末登记 flush——本回合写足迹整写
+  // 一次（首行执行：收尾链后续任何异常都不吞登记）；无写入 → 跳过（hot 窗口自然衰减）。
+  flushPeerDomains(agent)
+  // 第 30 批 D1（Stop 钩子）：主会话 run 终止 → fire-and-forget（非阻塞；失败静默——与 PostToolUse 同语义）。
+  // 排除用户中止（Ctrl+C / Ctrl+I——中止后 TUI 重建 controller 续跑或已显式停回合）与 AbortError 展开。
+  if (depth === 0 && !signal?.aborted && thrownError?.name !== "AbortError") {
+    runHooks("Stop", {
+      agent,
+      error: thrownError && !(thrownError instanceof ContinueError) ? thrownError : undefined,
+      extra: {
+        turn: agent._currentTurn ?? 0,
+        reason: thrownError instanceof ContinueError ? "maxTurns" : thrownError ? "error" : "done",
+      },
+    }).catch(() => {})
+  }
+  // R17（AGENT-LOOP.md §25 D-R17a）: consultation sessions are cross-turn
+  // background work now — NO unconditional turn-end cleanup (the old rule aborted
+  // leftover consult children at every turn end because check-loop consumption was
+  // turn-scoped). Sessions stay alive across normal turn ends (and ContinueError
+  // resumes); the Ctrl+C abort branch below is the only path that aborts them
+  // (cleanupConsultSessions — marked stopped → no digest), and the suspension
+  // driver aborts them on its own abort unwind.
+  // Async subagent turn-end handling (AGENT-LOOP.md §15 D-A3 + §17 D-S1). Lifecycle:
+  // - Ctrl+C (plain abort): children were aborted with the parent signal — discard dead
+  //   entries (tombstone/out-of-pool/notice — AGENT-LOOP-SUBAGENT.md §6.20; no stale
+  //   errors injected — user explicitly stopped); consultation sessions are cross-turn
+  //   background work since R17 — the abort branch is the ONLY normal-path place that
+  //   aborts them (cleanupConsultSessions marks stopped → they never reach the digest).
+  // - Ctrl+I (interrupt): keeps the pool AND the consult sessions: 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) {
+    const subPool = getAsyncPool(agent, "subagent")
+    const advPool = getAsyncPool(agent, "advisor")
+    if ((subPool?.size ?? 0) > 0 || (advPool?.size ?? 0) > 0) {
+      logEvent("ev:stopped", { poolN: (subPool?.size ?? 0) + (advPool?.size ?? 0), where: "turn-end-abort" })
+    }
+    // §6.20：只清已死条目（存活/已 settle 留池——收尾见 async-discard.mjs；原无条件清池已弃）。
+    discardAbortedPool(agent)
+    discardAbortedAdvisors(agent)
+    // R17: the consult family dies with the user stop (marked stopped — no digest).
+    cleanupConsultSessions(agent)
+    // ASYNC-RESULT-CONTAINER.md D2：pending 单容器——中止丢弃 consult/escalate 族停靠
+    // （原 _pendingConsultResults/_pendingEscalateResults 同口径——VSC 同语义 filter）；
+    // subagent/advisor 停靠保留（挂起期 settle 的已完成结果不随中止丢）。
+    agent._pendingAsyncResults = (agent._pendingAsyncResults ?? []).filter((e) => e.role !== "consult" && e.role !== "escalate")
+  } else if (thrownError instanceof ContinueError) {
+    // keep _asyncSubagents/_asyncAdvisors/_consultSessions — the resumed run continues them
+  } else {
+    const injectedAdvisor = await collectSettledAsync(agent, { suspDriven })
+    // §11.2 D-24b: a normally-ended USER run with no review/child activity closes
+    // the OPEN code instances — the converged/abandoned thread must not burn the
+    // 5-round cap of a later task (the next code review starts a fresh round 1).
+    // Digest auto-turns are exempt (their disposition precedes the fix round).
+    // A run whose turn-end collection just INJECTED a settled review report
+    // (headless, suspDriven=false) must NOT close: the model has not digested
+    // the findings yet — the fix round that follows still continues the thread.
+    if (!autoTurn && !injectedAdvisor) {
+      const { closeOpenCodeAdvisorRuns } = await import("../agent-tools/advisor-async.mjs")
+      closeOpenCodeAdvisorRuns(agent)
+    }
+  }
+  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)) {
+    // 键清单/快照形态单源 = helpers.mjs（P2 机制层端差批 §2.18——端侧经同一 helper 取同清单）
+    agent._inheritedGuard = snapshotGuard(agent)
+  }
+}
+
+/**
+ * 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
+ *   条目留池等消化轮注入；status 在 sweep 前仍从池读——17.5.2 不变面（§19.8：check 已删——自动通道为唯一消费方）)。
+ * maybeRefillAsync runs in both modes (starts queued heads whose slot freed).
+ * Single ownership: entries settled inside a suspension session were moved to
+ * _pendingAsyncResults by the settle callback, so this only sees user-turn
+ * settles (no double inject — D-S3 points ①/②). The ⟦ev⟧done freeze is NOT
+ * emitted here — each settle callback emits it (§15 D-A3).
+ * 2026-09-05 实践轮：自 agent.mjs 迁入（agent.mjs 内仅 finalize 引用——随收尾同迁）。
+ */
+async function collectSettledAsync(agent, { suspDriven = false } = {}) {
+  const maps = [getAsyncPool(agent, "subagent"), getAsyncPool(agent, "advisor")].filter((m) => m instanceof Map && m.size > 0)
+  if (maps.length === 0) return false
+  const { maybeRefillAsync, injectAsyncResult } = await import("../agent-tools/subagent.mjs")
+  maybeRefillAsync(agent) // start queued heads now that slots may have freed — no waiting
+  if (suspDriven) return false // §17.5: settled stays pooled — the suspension session digests it
+  let injectedAdvisor = false
+  for (const map of maps) {
+    for (const e of [...map.values()]) {
+      if (!e.done) continue // still running — stays in the pool (D-S1)
+      await injectAsyncResult(agent, e)
+      if (e.role === "advisor") injectedAdvisor = true
+      // TUI-OOM-ROOTCAUSE（§23.3.1 消费点①——回合尾收集）：注入完成 → 释放条目持有
+      releaseSettledEntry(e)
+      map.delete(String(e.id))
+    }
+  }
+  return injectedAdvisor
+}

package/agent/setup-reminders.mjs

@@ -0,0 +1,199 @@
+/**
+ * agent/setup-reminders.mjs — per-turn transient reminders
+ * (SESSION.md §6.11 — 2026-09-06 需求池 R5/R8/R9/R11 合并设计; R10 L1 peer 注入同文件).
+ *
+ * One unified transient user reminder per turn covers the whole self-awareness
+ * family: env identity (R8 — §6.10 D-1 END 常量先例：静态常量，不做 cmdline 判别),
+ * engineering mode (R9), active model (R11), session slot (F1), restart awareness
+ * (R5 resumed). §6.11（2026-09-08）：resumed 按会话跟踪——恢复事件由 session.mjs
+ * applySession 武装（agent._envResumed——载入历史非空 = 恢复）；进程重启句独立走
+ * agent._processRestartPending（bin 启动 resume 路径设）——双信号互不绑门（N6）。
+ * Change awareness needs no dedicated injection — every turn carries the
+ * CURRENT state, so a mode/model flip shows up in the next turn's line.
+ * git is NOT a field here (§6.11: CLI 不重复注入 clean|dirty 摘要) — the rich
+ * git-context injection (branch/commits/uncommitted — helpers.mjs
+ * collectGitContext, wired in setup.mjs) carries it.
+ * Peer awareness (R10 L1) rides the same per-turn transient channel:
+ * pushPeerReminder injects the live co-cwd instance list when present.
+ * Manifest state rides it too (#28 — `docs/core/design/MANIFEST.md` §2.6):
+ * pushManifestStateReminder carries the project phase as a self-healing single live line.
+ * #34 adds the per-turn value refresh (mtime-gated re-read — §2.6 ③b / KD-M1-17..M1-19):
+ * the line always carries the CURRENT on-disk phase, not the assembly-time snapshot.
+ *
+ * #113（S1 续轮第二批——VSC 侧并入 ④ 段）：`pushInjections`（机器行专用注入——编辑器上下文
+ * 等端侧采集内容；同文去重）与 `appendImagePointer`（粘贴图指引——非多模态模型可见报错）
+ * 两档并入——内容由端采集 / 传入（核内零端名），核供注入纪律单点。
+ */
+import { statSync } from "node:fs"
+import { END } from "../session-slots.mjs"
+import { peerInstances } from "../peer-instances.mjs"
+import { specForModel } from "../config.mjs"
+import { manifestFilePath, readManifest } from "../manifest.mjs"
+
+/** env-state line builder — pure, unit-testable.
+ *  §6.11（F1）：slot 字段入行——位置在 model 后 resumed 前（N3：无绑定 → 显式 null——
+ *  不读 manifest active 共享指针——粘性 _slot 才是"本 agent 之槽"）。 */
+export function envStateLine({ mode, model, slot, resumed }) {
+  return `[System reminder: env: ${END}, mode: ${mode}, model: ${model}, slot: ${slot}, resumed: ${resumed ? "yes" : "no"}.]`
+}
+
+/**
+ * Push the per-turn env-state reminder (setup.mjs calls it for depth-0 runs —
+ * the line describes the MAIN agent's host/mode/model/slot identity). resumed=yes
+ * exactly once per session restore: applySession (session.mjs) arms
+ * agent._envResumed when restored history is non-empty; consumed here so every
+ * later turn reads resumed=no（§6.11 F2——每次恢复一次；/new 与空历史槽切换不武装——
+ * F3 伪触发消除）。slot = 粘性 agent._slot（§6.11 N2/N3——无绑定显式 null）。
+ * Degrades safely: activeModel null → provider.model → "unknown" (T-E12);
+ * a missing config/history never throws (T-E13).
+ */
+export function pushEnvStateReminder(agent) {
+  const mode = agent.config?.agent?.engineering ? "eng" : "normal"
+  const model = agent.activeModel ?? agent.provider?.model ?? "unknown"
+  const slot = agent._slot ?? null
+  const resumed = agent._envResumed === true
+  agent._envResumed = false
+  agent.history.push({ role: "user", content: envStateLine({ mode, model, slot, resumed }), transient: true })
+}
+
+/** 情境行前缀——本行族识别符（摘旧行 / 会话重建认领同用；行形逐字见 manifestStateLine）。 */
+const MANIFEST_LINE_PREFIX = "[System reminder: project state: "
+
+/** phase → discipline 标签映射（判据单源 = 需求 v2 §9.1）；未知值不在表内 → 无标签。 */
+const MANIFEST_DISCIPLINE = Object.freeze({ "initial-dev": "light", production: "strict" })
+
+/** 情境行构造 — pure, unit-testable（模块契约 `docs/core/design/MANIFEST.md` §2.6，与
+ *  envStateLine 同族）。行形逐字（**单字段**——2026-09-17 裁撤批后）：
+ *  `[System reminder: project state: phase: <值> (discipline: <light|strict>).]`
+ *  未知 phase → 只出值、不编判据（无标签）。 */
+export function manifestStateLine({ phase }) {
+  const discipline = MANIFEST_DISCIPLINE[phase]
+  return `${MANIFEST_LINE_PREFIX}phase: ${phase}${discipline ? ` (discipline: ${discipline})` : ""}.]`
+}
+
+/**
+ * ③b 取值前置步（#34——`docs/core/design/MANIFEST.md` §2.6 条 3 · KD-M1-17–M1-19）：数据档
+ * mtime 门控重读——盘上 mtime ≠ `agent._manifestMtime`（含缓存未设 = 首次观测）⇒ `readManifest`
+ * 重读并采纳（`agent.manifest` ← 新值 + 缓存 ← 观测值）；mtime 未变 ⇒ 零重读。
+ * **失败保守**：`agent.cwd` 缺失 / stat 失败 / 读抛错 / 读回非法 ⇒ 不更新、不清零、不抛——
+ * 沿用上次已知好值，缓存不推进（⇒ 下回合重试，自愈）。路径 = `manifestFilePath(agent.cwd)`
+ * （项目根解析与读点同源——KD-M1-18，非「锚目录 + 档名」）；缓存载体 = `agent._manifestMtime`
+ * （per-agent——KD-M1-19，同族先例 `agent._slotMtime`）。本步失败只降级注入面（运行期），
+ * 与 E2 启动门槛（会话起点）两分——见 §2.5「运行期失败退化 vs 启动门槛」。
+ * @param {object} agent 主 agent（`agent.cwd` / `agent.manifest`）
+ */
+function refreshManifest(agent) {
+  if (!agent.cwd) return // 无锚 ⇒ 跳过本步（零 I/O，沿用内存值——§2.6 条 3 边界）
+  let mtimeMs
+  try {
+    mtimeMs = statSync(manifestFilePath(agent.cwd)).mtimeMs
+  } catch {
+    return // stat 失败（档删 / 不可读）⇒ 保守（不更新、不清零、不抛；缓存不推进）
+  }
+  if (agent._manifestMtime === mtimeMs) return // 未变 ⇒ 零重读（每回合仅一次路径解析 + 一次 statSync）
+  let m
+  try {
+    m = readManifest(agent.cwd)
+  } catch {
+    return // 读抛错（权限 / 目录等）⇒ 保守（同上）
+  }
+  if (!m.ok) return // 读回非法 / 缺失 ⇒ 保守（沿用旧值）
+  agent.manifest = m.manifest
+  agent._manifestMtime = mtimeMs
+}
+
+/**
+ * 情境行注入（#28——`docs/core/design/MANIFEST.md` §2.6 模块契约）：manifest 的
+ * `phase` 逐回合进模型上下文（判据序 ①–⑥ + 取值前置步 ③b = §2.6 表；#34 起值变由盘面驱动）。**自愈单活体**——
+ * 同文活体在 → 幂等（零历史变更）；值变 → 就地摘旧行 + 落新行（保 `history` 数组引用）；
+ * 压缩 / 会话重建吞行 → 下一回合重推（不落 system 槽——架构 E5.1 #5，`context.mjs`
+ * 压缩面零触碰）。`transient:true` ⇒ 不进人读线（`_fullHistory`）。
+ * @param {object} agent 主 agent（`agent.manifest` / `agent.history` / `agent.cwd`——③b 取值）
+ * @param {{depth?: number}} [opts] 注入深度（仅 depth-0）
+ * @returns {boolean} 是否落新行（测试断言用）
+ */
+export function pushManifestStateReminder(agent, { depth = 0 } = {}) {
+  if (depth !== 0) return false // ① 仅 depth-0（子代理读任务书——架构 §2.4 M5 零 manifest 读面）
+  if (agent.config?.agent?.engineering !== true) return false // ② 模式门：仅工程模式
+  if (!agent.manifest) return false // ③ 无 manifest（normal 路径 / 装配缺失）→ 零注入
+  refreshManifest(agent) // ③b 取值前置步（#34）：mtime 门控重读——行构造须取刷新后的值
+  const history = agent.history
+  const line = manifestStateLine({ phase: agent.manifest.phase })
+  // ④ 同文 user 行已在（活体）→ 幂等——零历史变更（同文口径 = pushInjections 的 history.some）
+  if (history.some((m) => m.content === line)) return false
+  // ⑤ 值已变 → 就地 splice 摘旧行（`role === "user"` 全匹配），保 history 数组引用。会话重建后
+  //    `_manifestLine` 不随历史回来 → 先按行族前缀从 history 认领现存活体（否则旧行残留 +
+  //    新行入列 = 双活体，违 §2.6 定案「单活体」）。
+  let old = agent._manifestLine
+  if (!old) {
+    for (const m of history) {
+      if (typeof m?.content === "string" && m.content.startsWith(MANIFEST_LINE_PREFIX)) old = m.content
+    }
+  }
+  if (old && old !== line) {
+    for (let i = history.length - 1; i >= 0; i--) {
+      if (history[i]?.role === "user" && history[i].content === old) history.splice(i, 1)
+    }
+  }
+  history.push({ role: "user", content: line, transient: true }) // ⑥ 落新行 + 记活体
+  agent._manifestLine = line
+  return true
+}
+
+/**
+ * R10 L1 peer reminder（MULTI-INSTANCE-COLLAB §2a.4 D-L1a——仿 pushEnvStateReminder
+ * 形态：depth-0、transient:true——注入纪律同 env-state）。有同伴（非 self > 0）才注入
+ * ——无同伴零开销（peerInstances 惰性 mtime/TTL 缓存保证：命中零 exec）。任何
+ * 感知失败静默跳过（注入绝不打断回合）。文案（设计逐字）："本目录另有 N 个活跃
+ * thincoder（{end} pid={pid}…）——文件操作注意避让"。
+ *
+ * **async**（TUI 假死批 2026-09-18）：读面已异步化（探测 `execFile` promise）；装配点
+ * `prepareRun` 本就 async ⇒ `await pushPeerReminder(agent)`——**注入时序与文案零变**
+ * （env-state 后、time reminder 前）。
+ */
+export async function pushPeerReminder(agent) {
+  let peers
+  try {
+    peers = (await peerInstances(agent.cwd)).filter((p) => !p.self)
+  } catch {
+    return // 感知失败降级——不注入
+  }
+  if (peers.length === 0) return
+  const who = peers.map((p) => (p.end ? `${p.end} pid=${p.pid}` : `pid=${p.pid}`)).join("、")
+  agent.history.push({
+    role: "user",
+    content: `[System reminder: 本目录另有 ${peers.length} 个活跃 thincoder（${who}）——文件操作注意避让]`,
+    transient: true,
+  })
+}
+
+/**
+ * 机器行专用注入单点（#113 VSC 侧并入——编辑器上下文等端侧采集内容）：`injections` =
+ * 单条或数组，每条 `{ content }`。纪律与 CLI parity：只进机器行（transient——持久化层
+ * 可丢；不进人读记录——自动上下文不得污染人读历史）；**同文去重**（幂等注入——history
+ * 已有等文消息则跳过）。非法条目静默跳过（注入绝不打断回合）。内容由**端装配**采集并
+ * 传入（核内零端名——④ 段）。
+ */
+export function pushInjections(history, injections) {
+  const list = Array.isArray(injections) ? injections : (injections ? [injections] : [])
+  for (const inj of list) {
+    if (!inj || typeof inj.content !== "string") continue
+    if (history.some((m) => m.content === inj.content)) continue
+    history.push({ role: "user", content: inj.content, transient: true })
+  }
+}
+
+/**
+ * 粘贴图指引（#113 VSC 侧并入——贴图指引按端注入）：`images` = 绝对路径列表（端侧保存
+ * 的粘贴图档）。把指引追加到**真实用户消息**尾部（content 保持字符串形态——不用旧
+ * image_url parts 数组），模型经 `read_image` 查看（其多模态路径注入图像 part）。非多模态
+ * 模型 ⇒ **抛错**（可见错误，绝不静默丢图）。depth>0 / 无图 / 消息缺失 ⇒ no-op。
+ */
+export function appendImagePointer(userMsg, images, providerModel, { depth } = {}) {
+  if (depth !== 0 || !userMsg || !Array.isArray(images) || images.length === 0) return
+  const spec = specForModel(providerModel)
+  if (!spec.multimodal) {
+    throw new Error("This model does not support pasted images. Switch to a vision-capable model (Kimi K3, Qwen, GLM, etc.) or attach the image as a file and let the model read it.")
+  }
+  userMsg.content += `\n\n[Attached images: ${images.join(" | ")}] — use the read_image tool to view them before answering.`
+}