thincoder 0.12.59 → 0.12.61

package/src/agent/record-results.mjs

@@ -16,13 +16,19 @@
  *    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).
+ *    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 { join } from "node:path"
+import { resolve } from "node:path"
+import { advisorRuns, stripApprovedSuffix } from "../agent-tools/advisor-async.mjs"
+import { looksLikeReviewOutput, advisorIncompleteMarker } from "../advisor/run.mjs"
 
 let _reindexFile = null
 
@@ -72,6 +78,9 @@ export async function recordToolResults(agent, toolByName, results) {
         // 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
@@ -91,20 +100,55 @@ export async function recordToolResults(agent, toolByName, results) {
       }
       if (toolCall.name === "verify") agent._verifiedThisRun = true
       if (toolCall.name === "advisor") {
-        agent._calledAdvisorThisRun = true
-        // All advisor calls (code and design) share the 5-round convergence
-        // budget — each advances _advisorRound toward MAX_ADVISOR_ROUNDS.
-        // Always advance the round — the convergence protocol cares about
-        // how many reviews have run (round 1→2→3→4→5), not how many succeeded.
-        // A failed/interrupted review is still a review attempt and should use
-        // the next round's prompt on retry.
-        agent._advisorRound++
+        // §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 (pool full / per-review cap) 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 = join(agent.cwd, p)
+          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.

package/src/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/src/agent/run-stages.mjs

@@ -0,0 +1,242 @@
+/**
+ * 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 } from "./helpers.mjs"
+import { cleanupConsultSessions } from "../agent-tools/consult.mjs"
+import { logEvent } from "../log.mjs"
+// ASYNC-RESULT-CONTAINER.md D1：池 accessor（absorb 双池——advisor 独立池无队列）
+import { getAsyncPool } from "../agent-tools/async-settle.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)
+  }
+}
+
+/**
+ * 回合收尾（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 — clear
+  //   WITHOUT injecting stale errors (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 → their settles never reach the digest stream).
+  // - 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" })
+    }
+    subPool?.clear()
+    advPool?.clear()
+    agent._asyncQueue = []
+    // 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)) {
+    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
+ *   条目留池等消化轮注入；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
+      map.delete(String(e.id))
+    }
+  }
+  return injectedAdvisor
+}

package/src/agent/setup-reminders.mjs

@@ -0,0 +1,69 @@
+/**
+ * agent/setup-reminders.mjs — per-turn transient reminders
+ * (SESSION.md §11.1 — 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 — §10 D-1 END 常量先例：静态常量，不做 cmdline 判别),
+ * engineering mode (R9), active model (R11), session slot (F1), restart awareness
+ * (R5 resumed). §11.2（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 (§11.1: 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.
+ */
+import { END } from "../session-slots.mjs"
+import { peerInstances } from "../peer-instances.mjs"
+
+/** env-state line builder — pure, unit-testable.
+ *  §11.2（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（§11.2 F2——每次恢复一次；/new 与空历史槽切换不武装——
+ * F3 伪触发消除）。slot = 粘性 agent._slot（§11.2 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 })
+}
+
+/**
+ * R10 L1 peer reminder（MULTI-INSTANCE-COLLAB §2a.4 D-L1a——仿 pushEnvStateReminder
+ * 形态：depth-0、transient:true——注入纪律同 env-state）。有同伴（非 self > 0）才注入
+ * ——无同伴零开销（peerInstances 惰性 mtime 缓存保证：manifest 未变零 exec）。任何
+ * 感知失败静默跳过（注入绝不打断回合）。文案（设计逐字）："本目录另有 N 个活跃
+ * thincoder（{end} pid={pid}…）——文件操作注意避让"。
+ */
+export function pushPeerReminder(agent) {
+  let peers
+  try {
+    peers = 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,
+  })
+}