@thincoder/core 0.10.8 → 0.10.10

package/CHANGELOG.md

@@ -5,6 +5,12 @@ Format: Keep a Changelog · 中文 · 号在发布时定（CalVer——见 `docs
 
 ## [Unreleased]
 
+## [0.10.9] — 2026-10-19
+
+### Removed
+
+- **`design-slots` 的 `reveal` 开关与掩蔽（token-visibility-simplify 批 2026-10-17）**：清点面改**直读**——逐槽行恒携 `designToken`（过期照列、`status` 自标态；记录畸形 ⇒ `—`）；删净 `reveal` 开关 / 掩蔽 / 一次一槽限制（用户裁定「没必要把 token 藏起来，agent 要就告诉他」）；签发链（mint / settle / TTL / persist）零改。
+
 ## [0.10.8] — 2026-10-16
 
 > 0.10.7 → 0.10.8（月内 +1——发布时定号）

package/advisor/messages.mjs

@@ -155,15 +155,14 @@ function buildAdvisorUserMessageInner(agent, prior, reviewType, designToken = nu
       }
     }
 
-    // Engineering mode: the project's DECLARED standards document
-    // (advisor.standardsDoc) — undeclared degrades visibly (PO-2).
+    // Engineering mode: the project standards section — the declaration face is gone with the
+    // manifest `advisor` key, so this is always an explicit degradation (PO-2).
     if (agent.config?.agent?.engineering) {
       injectProjectStandards(agent, parts, guideRoot)
     }
 
-    // Document map: declared path wins, the built-in fallback probe (docs/README.md
-    // → docs/design/README.md) stays; neither → explicit degradation sentence
-    // (never the old silent skip).
+    // Document map: derived from the manifest `docRoot` (declared roots' README, then their common
+    // ancestor); neither → explicit degradation sentence (never a silent skip).
     injectDocumentMap(agent, parts, guideRoot ?? agent.cwd)
 
     parts.push("## Instructions")

package/advisor/project-context.mjs

@@ -12,13 +12,14 @@
  * absent — in a project with a different layout the reviewer still scored the
  * dimension it could no longer check (silent failure, the worst class: invisible
  * and unfixable by the user). Missing pieces now say so, and the reviewer is told
- * to state the limitation in its findings. Projects can point at their own files
- * through the project manifest (advisor.docMap / advisor.standardsDoc).
+ * to state the limitation in its findings. The document map is derived from the
+ * manifest's `docRoot` (the one place that says where the docs live); the standards
+ * face has no derivable convention name and is therefore an explicit degradation.
  */
 import { readFileSync, existsSync } from "node:fs"
 import { resolve, join, relative, dirname, sep } from "node:path"
 import { providerSpec } from "../config.mjs"
-import { loadProjectDeclaration } from "../conventions.mjs"
+import { DEFAULT_MANIFEST, docRootPaths, readManifest } from "../manifest.mjs"
 
 /** Project guide (AGENTS.md) injection budget — decision 2026-08-08:
  *  NO fixed truncation; long-context models (1M+) get up to 5% of their context
@@ -32,8 +33,8 @@ const PROJECT_GUIDE_FRACTION = 0.05 // 5% of the reviewer model's context window
 export const NO_GUIDE_NOTICE = "(No AGENTS.md found — neither at the working directory root nor in any review-scope subdirectory. Judge the user's requirements from the conversation background, and say so explicitly if the requirements are unclear.)"
 
 /** Explicit degradation sentences (PORTABILITY design §4.4 — verbatim). */
-export const NO_DOC_MAP_NOTICE = "(No document map found under the project root, and none is declared — the Document ownership criterion is degraded: check placement against the Project Guide where present, and state the limitation in your findings.)"
-export const NO_STANDARDS_NOTICE = "(No project standards document was declared — judge methodology compliance from the Project Guide (when present) and the review criteria above; state the limitation in your findings.)"
+export const NO_DOC_MAP_NOTICE = "(No document map found — no README.md under the declared document roots and none at their common ancestor — the Document ownership criterion is degraded: check placement against the Project Guide where present, and state the limitation in your findings.)"
+export const NO_STANDARDS_NOTICE = "(No project standards document — nothing in the project declares one — judge methodology compliance from the Project Guide (when present) and the review criteria above; state the limitation in your findings.)"
 export const NO_GIT_NOTICE = "(No git repository detected — change-set context is unavailable; read the review-scope files directly.)"
 
 /**
@@ -126,25 +127,66 @@ export function injectProjectGuide(agent, parts, scopeFiles = []) {
   return root // guide injected — requirement-fit criteria apply (truthy root)
 }
 
+/** `docRoot` probe order: the face a reviewer needs first (design) → down to the batch records. */
+const DOC_ROOT_ORDER = ["design", "requirements", "specs", "modules", "batches"]
+
+/** Declared document roots as ABSOLUTE paths, in declaration order (`null` / missing face ⇒ no root). */
+function declaredDocRoots(base) {
+  const read = readManifest(base)
+  const docRoot = (read.ok && read.manifest ? read.manifest : DEFAULT_MANIFEST).docRoot ?? {}
+  const out = []
+  for (const key of DOC_ROOT_ORDER) {
+    for (const p of docRootPaths(docRoot[key], base)) if (!out.includes(p)) out.push(p)
+  }
+  return out
+}
+
+/** Common ancestor of every root (segment-wise — `docs/design` and `docs/designX` are not siblings).
+ *  A lone drive root is no map home ⇒ null. */
+function commonAncestor(paths) {
+  if (paths.length === 0) return null
+  const split = (p) => p.split(/[\\/]+/)
+  let acc = split(paths[0])
+  for (const p of paths.slice(1)) {
+    const segs = split(p)
+    let i = 0
+    while (i < acc.length && i < segs.length && acc[i] === segs[i]) i++
+    acc = acc.slice(0, i)
+  }
+  if (acc.length === 0) return null
+  const joined = acc.join(sep)
+  return /^[A-Za-z]:$/.test(joined) ? null : joined
+}
+
 /**
- * Inject the project document map (PO-1). Resolution: the DECLARED path
- * (`advisor.docMap`, project-root-relative) wins; the built-in probe
- * (`docs/README.md` → `docs/design/README.md`) stays as a fallback for projects
- * laid out that way. Neither usable → an explicit degradation sentence — never a
- * silent skip: the reviewer must know the Document-ownership criterion is unchecked.
+ * Discover the document map from the manifest's `docRoot` — a pure fs probe, no index generation
+ * (the map is a hand-maintained register; a generated one would be a second index, and a second
+ * index is exactly the duplicate pointer the retired declaration face used to create).
+ * Ladder: ① `README.md` under each declared doc root (declaration order) ② `README.md` at the common
+ * ancestor of every declared root. Neither ⇒ null (caller injects `NO_DOC_MAP_NOTICE` — no silent skip).
+ * @param {string} base project root (or any dir inside it — `docRoot` resolves against the project root)
+ * @returns {string|null} absolute path of the map file, or null when degraded
+ */
+export function findDocumentMap(base) {
+  const roots = declaredDocRoots(base)
+  for (const r of roots) {
+    const p = join(r, "README.md")
+    if (existsSync(p)) return p
+  }
+  const ancestor = commonAncestor(roots)
+  if (!ancestor) return null
+  const p = join(ancestor, "README.md")
+  return existsSync(p) ? p : null
+}
+
+/**
+ * Inject the project document map (PO-1), derived from `docRoot`. Degrades visibly: the reviewer
+ * must know the Document-ownership criterion is unchecked — never a silent skip.
  * @returns {string|null} the injected map path, or null when degraded
  */
 export function injectDocumentMap(agent, parts, root) {
   const base = root ?? agent.cwd
-  const conv = loadProjectDeclaration(agent.cwd)
-  let mapPath = null
-  if (conv.advisor.docMap) {
-    const declared = resolve(base, conv.advisor.docMap)
-    if (existsSync(declared)) mapPath = declared
-  } else {
-    mapPath = [resolve(base, "docs", "README.md"), resolve(base, "docs", "design", "README.md")]
-      .find((p) => existsSync(p)) ?? null
-  }
+  const mapPath = findDocumentMap(base)
   parts.push("## Document Map")
   let text = null
   if (mapPath) {
@@ -166,32 +208,15 @@ export function injectDocumentMap(agent, parts, root) {
 }
 
 /**
- * Inject the project standards document (PO-2). DECLARATION ONLY
- * (`advisor.standardsDoc`, project-root-relative): the old hardcoded
- * `METHODOLOGY.md` probe injected a file most projects do not have — and its
- * absence was silent. Undeclared (or unreadable) → explicit degradation sentence.
- * @returns {string|null} the injected standards path, or null when degraded
+ * Inject the project standards section (PO-2). The declaration face is gone with the manifest
+ * `advisor` key, and no standards file name is derivable from what the project does declare (the old
+ * `METHODOLOGY.md` probe was deleted exactly because most projects have none). The section stays so the
+ * reviewer is TOLD the dimension is unchecked — visible degradation, not a silent skip.
+ * @returns {null} always degraded
  */
-export function injectProjectStandards(agent, parts, root) {
-  const base = root ?? agent.cwd
-  const conv = loadProjectDeclaration(agent.cwd)
-  const declared = conv.advisor.standardsDoc ? resolve(base, conv.advisor.standardsDoc) : null
+export function injectProjectStandards(_agent, parts, _root) {
   parts.push("## Project Standards")
-  let text = null
-  if (declared && existsSync(declared)) {
-    try {
-      text = readFileSync(declared, "utf8")
-    } catch (e) {
-      console.warn(`[advisor] project standards unreadable at ${declared}: ${e.message}`)
-    }
-  }
-  if (text === null) {
-    parts.push(NO_STANDARDS_NOTICE) // degraded — visible by contract
-    parts.push("")
-    return null
-  }
-  parts.push("The project declares these standards for this review. Judge the design/changes against them:")
-  parts.push(text)
+  parts.push(NO_STANDARDS_NOTICE) // degraded — visible by contract
   parts.push("")
-  return declared
+  return null
 }

package/agent/family-tools.mjs

@@ -26,7 +26,7 @@ export async function assembleFamilyTools({
   decorate = null,       // object   端差面：{ subagent?, consultStart?, consultStop?, settings? }
 } = {}) {
   // CORE-UNIFICATION TOOLS #83：consult 家族随统一登记册自 `../agent-tools.mjs` 取用（单一来源）
-  const { planTool, subagentTool, taskTool, skillTool, goalTool, verifyTool, recentChangesTool, timerTool, advisorTool, engTool, readHistoryTool, contextTool, batchTool, manifestTool, consultStartTool, consultStopTool, parentChannelTool, docCheckTool } = await import("../agent-tools.mjs")
+  const { planTool, subagentTool, taskTool, skillTool, goalTool, verifyTool, recentChangesTool, timerTool, advisorTool, engTool, readHistoryTool, contextTool, batchTool, manifestTool, manifestReadTool, consultStartTool, consultStopTool, parentChannelTool, docCheckTool } = await import("../agent-tools.mjs")
   // 台账统一入口（2026-10-05 统一入口批——台账 #923）：全量变体 = depth-0 段 ∥ 只读变体 = 全部
   // depth>0 段。动态 import——ledger 链静态达 node:sqlite（W8 契约②）；两变体同名单对象、schema 窄化。
   const { ledgerTool, ledgerReadTool } = await import("../ledger.mjs")
@@ -125,8 +125,8 @@ export async function assembleFamilyTools({
           ...subagentTool,
           name: "subagent",
           description: designer
-            ? "Spawn a read-only `explore` sub-agent to SURVEY the current state for the design: it reads code / docs / existing designs and reports evidence with file:line. BLOCKING ONLY (no async) and action:'spawn' ONLY — the survey channel is read-only; escalate/status/cancel/panel/consume-design/observe/send are not available. Survey budget: ≤6 explore spawns per batch — the main agent's survey result is reference only; do your own."
-            : "Spawn a read-only `explore` sub-agent to AUDIT your delivery against the design: it compares the delivered code with the design for divergence — partially implemented acceptance criteria, silent simplifications, doc drift, changes outside the approved file list. BLOCKING ONLY (no async — the audit report decides your next protocol step). action:'spawn' ONLY — the audit channel is a read-only spawn; escalate/status/cancel/panel/consume-design/observe/send are not available. The audit task book is appended MECHANICALLY — your own spawn task (docs involved / acceptance criteria / file list) plus the files you actually touched; never hand the audit a self-written file list (a self-report could omit exactly the out-of-scope file it must catch).",
+            ? "Spawn a read-only `explore` sub-agent to SURVEY the current state for the design: it reads code / docs / existing designs and reports evidence with file:line. BLOCKING ONLY (no async) and action:'spawn' ONLY — the survey channel is read-only; escalate/status/cancel/panel/consume-design/observe/send are not available. Survey budget: ≤6 explore spawns per batch — the main agent's survey result is reference only; do your own. The spawn carries the five task-book parameters (four core: goal / knownFacts / acceptance / reportFormat + `scope`); a task-only spawn is refused."
+            : "Spawn a read-only `explore` sub-agent to AUDIT your delivery against the design: it compares the delivered code with the design for divergence — partially implemented acceptance criteria, silent simplifications, doc drift, changes outside the approved file list. BLOCKING ONLY (no async — the audit report decides your next protocol step). action:'spawn' ONLY — the audit channel is a read-only spawn; escalate/status/cancel/panel/consume-design/observe/send are not available. The audit task book is appended MECHANICALLY — your own spawn task (docs involved / acceptance criteria / file list) plus the files you actually touched; never hand the audit a self-written file list (a self-report could omit exactly the out-of-scope file it must catch). The spawn carries the five task-book parameters (four core: goal / knownFacts / acceptance / reportFormat + `scope`); a task-only spawn is refused.",
           parameters: { ...subagentTool.parameters, properties: props },
         }
       })()
@@ -149,7 +149,7 @@ export async function assembleFamilyTools({
       // 团队台账全量变体（五 action——同律：子代理段只挂读变体；登录态门在工具内）
       teamLedgerTool,
       // manifest 工具（`MANIFEST.md` §2.10 · 2026-10-08 · 台账 #1098）：主 agent 读写出口——
-      // **两模式同挂**（需求未设模式门）；子代理各段零挂（未装配 = 权限面第一道）。
+      // **两模式同挂**（需求未设模式门）；全量变体仅 depth-0——子代理各段挂只读变体（见下 `:187-193`）。
       manifestTool,
       // 文档纪律机检（`DOC-DISCIPLINE.md` §3.20 条目 S）：只读报告态——depth-0 主 agent 段；
       // 写文档 / 设计档的角色段（eng-coder / eng-designer）另挂（见下两分支）。
@@ -182,13 +182,15 @@ export async function assembleFamilyTools({
     // consult 段不入（其角色语义 = 父发起的一次性会诊，父在其 settle 前不期望中途对话）。
     // 台账只读变体（query / count）——全部 depth>0 角色段（含 consult ∕ 兜底；写三 schema 级不可达）；
     // 团队台账只读变体（team-ledger 批）同律。
-    : engChildRole === "eng-coder" ? [parentChannelTool, ledgerReadTool, teamLedgerReadTool, advisorTool, verifyTool, batchTool(batchDoc), docCheckTool,
+    // manifest 只读变体（MANIFEST.md §2.10.1 · 2026-10-22 · 台账 #1738）：同名 `manifest`、action 枚举只剩 `read`；
+    // 与上两条只读先例同律挂在全部 depth>0 角色段（全量变体仅 depth-0——两变体互斥装配，同名不塌缩）。
+    : engChildRole === "eng-coder" ? [parentChannelTool, ledgerReadTool, teamLedgerReadTool, manifestReadTool, advisorTool, verifyTool, batchTool(batchDoc), docCheckTool,
       ...(engChildSubagent ? [engChildSubagent] : [])]
-    : engChildRole === "eng-designer" ? [parentChannelTool, ledgerReadTool, teamLedgerReadTool, batchTool(batchDoc), docCheckTool,
+    : engChildRole === "eng-designer" ? [parentChannelTool, ledgerReadTool, teamLedgerReadTool, manifestReadTool, batchTool(batchDoc), docCheckTool,
       ...(engChildSubagent ? [engChildSubagent] : [])]
-    : role === "coder" ? [parentChannelTool, ledgerReadTool, teamLedgerReadTool, verifyTool, advisorTool, ...(batchDoc ? [batchTool(batchDoc)] : [])]
-    : role === "consult" ? [recentChangesTool, ledgerReadTool, teamLedgerReadTool]
-    : [parentChannelTool, ledgerReadTool, teamLedgerReadTool]
+    : role === "coder" ? [parentChannelTool, ledgerReadTool, teamLedgerReadTool, manifestReadTool, verifyTool, advisorTool, ...(batchDoc ? [batchTool(batchDoc)] : [])]
+    : role === "consult" ? [recentChangesTool, ledgerReadTool, teamLedgerReadTool, manifestReadTool]
+    : [parentChannelTool, ledgerReadTool, teamLedgerReadTool, manifestReadTool]
 
   // 固定段（装配序 = agent.tools → 固定段 → 家族段 → extraTools）：timer 全模式全深度；
   // plan 随模式位——ENG-PLAN-EXCLUSION（FR31 ① · KD8 卸载而非「注册 + 报错」· KD11 全深度两端）；

package/agent/helpers.mjs

@@ -275,6 +275,12 @@ export function turnFrame(seq, turn, maxTurns) {
   return { turn: seq, maxTurns: seq - turn - 1 + maxTurns }
 }
 
+/** #934（零落笔看门狗——AGENT-LOOP-UPSTREAM.md §6.32.2 ① 判据式）：上轮结账至今写序是否推进；非整数（未跟踪面 / NaN）⇒ true 记「有落笔」不判（不用 `?? 0` 兜底——未跟踪面当零落笔正是本收正要消除的误报方向）。 */
+export function wroteSince(agent, mark) {
+  const seq = agent._mutationSeq
+  return Number.isInteger(seq) ? seq !== mark : true
+}
+
 /** Repair malformed conversation history: remove orphan tool messages and fill missing tool results */
 export function repairHistory(history) {
   const out = []
@@ -451,14 +457,14 @@ export const AUTO_TURN_DIGEST_DOMAIN =
 /** Engineering-mode auto-turn digest domain variant (mode = `agent.config.agent.engineering`;
  *  clause 2 drops the task-tool pointer — F10: the task tool is disabled in engineering mode,
  *  the batch record + ledger are the tracking authority). Single line, verbatim from the
- *  design doc (TOOLS.md §6.15.3); mechanism = AGENT-LOOP-ASYNC-POOL.md §6.8. Content authority = parent side. */
+ *  design doc (TOOLS.md §6.15.3); mechanism = AGENT-LOOP-ASYNC-POOL.md §6.8. Content basis = the mechanism doc; landing = eng-coder. */
 export const AUTO_TURN_DIGEST_DOMAIN_ENG =
   "[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) (engineering mode: the task tool is disabled — no task-list update is expected this turn; the batch record + ledger are the tracking authority and are updated in real user turns); 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.]"
 
 /** Up-stream wake-turn domain (AGENT-LOOP-UPSTREAM.md §6.27.12.8): a running subagent sent
  *  an in-flight message and is waiting for the reply — the digest domain's "No one is waiting
  *  for this reply" is the opposite of the truth, so the wake turn gets its own text.
- *  Verbatim from the design doc (single line — no newlines). Content authority = parent side. */
+ *  Verbatim from the design doc (single line — no newlines). Content basis = the mechanism doc; landing = eng-coder. */
 export const UPSTREAM_TURN_DOMAIN =
   "[System reminder: auto-turn — a running subagent sent you an in-flight message (shown below). No user message is waiting. Decide it now and reply with subagent action:'send' (id + message) — the child consumes the reply at its next turn boundary and keeps working on the unaffected parts; if the message needs no answer, say so in one line and move on. If finished subagent reports are also present above, summarize them as usual in the same turn. Do not start new work: 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 reply is sent.]"
 
@@ -466,16 +472,16 @@ export const UPSTREAM_TURN_DOMAIN =
  *  expired while the session was idle and the end's latch opened this turn automatically —
  *  neither the digest domain ("no one is waiting", organize-only) nor the up-stream domain
  *  (a subagent waiting for a reply) fits: the timer's own semantics is "act on what the
- *  timer was for". Verbatim from the parent-side final text (single line — no newlines).
- *  Content authority = parent side. */
+ *  timer was for". Verbatim from the mechanism doc (single line — no newlines).
+ *  Content basis = the mechanism doc; landing = eng-coder. */
 export const TIMER_TURN_DOMAIN =
   "[System reminder: auto-turn — a timer you set earlier has expired (reminder above). No user message is waiting. Act on what the timer was for now: pull the data or run the check rather than continuing to reason in the abstract. Stay within the work that was in flight when the timer was set; do not open unrelated new work. Wrap up as soon as the action is done or blocked.]"
 
 /** Digest-accounting requirement line (AGENT-LOOP-ASYNC-POOL.md §6.31.3 · batch digest-accounting ·
  *  2026-10-05)：消化轮账目要求——两档同发（手动 / AUTO）；manual 域文本只覆盖手动档 ⇒ 要求行
  *  独立常量承载，避免 AUTO 轮无要求。`<ids>` = 未销账 id 清单占位（动态拼 = digest-account.mjs
- *  `digestAccountRequirement`）；注入面 = transient（机器线独有）。Verbatim from the parent-side
- *  final text (single line — no newlines); content authority = parent side. */
+ *  `digestAccountRequirement`）；注入面 = transient（机器线独有）。Verbatim from the mechanism doc
+ *  (single line — no newlines). Content basis = the mechanism doc; landing = eng-coder. */
 export const DIGEST_ACCOUNT_DOMAIN =
   "[System reminder: digest accounting — for every report listed below as not yet accounted, emit exactly one line: \"[digest-ack #<id>] digested — <key points>\" (handled) or \"[digest-ack #<id>] deferred — <reason>\" (not handled). Not yet accounted: <ids>. Do not omit any.]"
 

package/agent/post-turn.mjs

@@ -10,6 +10,31 @@ export const STALL_WINDOW_SIZE = 5
 export const STALL_THRESHOLD = 3
 export const GOAL_BUDGET_WARN_RATIO = 0.75
 
+// 设计轮轮数注入阈值（AGENT-LOOP.md §6.6「设计轮轮数注入」· 台账 #1661）：
+// 5 = 在 persona 判定点（过 7 轮未落盘 ⇒ 降级）之前 3 轮给出计数；8 = 与 persona 同一判定点；
+// 15 = persona 的首版预算（注入串里的 15 一律由它插值——改常量即改注入文本，不另留字面）。
+export const DESIGN_TURN_NOTICE_AT = 5
+export const DESIGN_TURN_SKELETON_AT = 8
+export const DESIGN_FIRST_VERSION_TURNS = 15
+
+/**
+ * 设计轮轮数提醒（纯函数——注入串 | `null`；判据源 = 链内累计轮号 + 本设计轮是否落过盘）。
+ * 逐字注入形 = `AGENT-LOOP.md` §6.6「注入形逐字」；角色表当前一行（`eng-designer`），
+ * `eng-coder` 零注入（其零落笔面另由零落笔看门狗兜）。
+ * @param {{role?:string|null, turn?:number, wrote?:boolean}} o `turn` = 链内累计轮号（1 起）
+ * @returns {string|null}
+ */
+export function designTurnReminder({ role, turn, wrote } = {}) {
+  if (role !== "eng-designer") return null
+  const used = Number(turn ?? 0)
+  if (!Number.isFinite(used) || used < DESIGN_TURN_NOTICE_AT) return null
+  const budget = DESIGN_FIRST_VERSION_TURNS
+  if (used >= DESIGN_TURN_SKELETON_AT && !wrote) {
+    return `[System reminder: design round turn ${used}/${budget} — nothing has been written to disk yet. The 7-turn mark has passed with nothing landed: degrade the delivery NOW — write the skeleton (design doc + batch record §2) plus an unresolved list, then refine in place.]`
+  }
+  return `[System reminder: design round turn ${used}/${budget} — ${wrote ? "something has been written to disk" : "nothing has been written to disk yet"}. First version budget is ${budget} turns; past 7 turns with nothing landed the rule is a skeleton + unresolved list.]`
+}
+
 /**
  * Inject all post-turn events into agent history.
  * Must be called after every tool-execution turn within runAgent's loop.
@@ -66,5 +91,14 @@ export function injectPostTurn(agent, results, recentCallSigs, callbacks, turn,
     })
   }
 
+  // 设计轮轮数注入（AGENT-LOOP.md §6.6 · 台账 #1661）：轮号取 `_currentTurn`（链内累计、续跑不重置），
+  // 写入痕迹取 `_touchedFiles`（在 resume 保留集内 ⇒ 续跑段沿用前段痕迹）；段内 `turn` 形参不参与判据。
+  const designReminder = designTurnReminder({
+    role: agent._role,
+    turn: agent._currentTurn ?? 0,
+    wrote: (agent._touchedFiles ?? []).length > 0,
+  })
+  if (designReminder) agent.history.push({ role: "user", content: designReminder })
+
   callbacks.onTurnEnd?.(agent, turn)
 }

package/agent/run-stages.mjs

@@ -8,6 +8,9 @@
  */
 
 import { compressIfNeeded, compressFallback, COMPRESS_FAILURE_LIMIT } from "../context.mjs"
+// §6.17/D-CC32 溢出守卫（兜底，非主修）：预算面单源 requestBudget ∥ 再估面 contextUsage（与压缩判定同一函数）
+import { requestBudget } from "../config.mjs"
+import { contextUsage } from "../token-window.mjs"
 import { ensureAutoReminder, injectEngineeringReminder, ContinueError, snapshotGuard } from "./helpers.mjs"
 import { pushManifestStateReminder } from "./setup-reminders.mjs"
 import { cleanupConsultSessions } from "../agent-tools/consult.mjs"
@@ -84,6 +87,16 @@ export async function runCompactionCheck(agent, ctx) {
   // 其余全同（同 splitHistory / 同尾部预算 / 同摘要链 / 同回注 / 同基线失效）。
   const pending = agent._pendingCompact
   agent._pendingCompact = null
+  // 成功记账（§6.17：成功记账段抽局部——阈值面与守卫面共用同一段，零复制）
+  const bookkeepCompaction = () => {
+    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)
+  }
   try {
     let compacted = await compressIfNeeded(
       agent, threshold, callbacks,
@@ -96,15 +109,7 @@ export async function runCompactionCheck(agent, ctx) {
       agent.history.push({ role: "user", content: compactNoopNote(), transient: true })
       compacted = await compressIfNeeded(agent, threshold, callbacks, compactionOverhead, signal)
     }
-    if (compacted) {
-      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)
-    }
+    if (compacted) bookkeepCompaction()
   } catch (compressError) {
     // AbortError must not be swallowed: user cancellation must propagate
     if (compressError?.name === "AbortError" || signal?.aborted) throw compressError
@@ -122,6 +127,35 @@ export async function runCompactionCheck(agent, ctx) {
       if (compressFallback(agent)) callbacks.onCompress?.(agent._lastCompressInfo ?? {})
     }
   }
+
+  // 溢出守卫（CONTEXT-COMPACTION.md §6.17 / D-CC32——兜底，非主修；本缝 = catch 闭合后、返回前）。
+  // 判据 = maxTokensSource !== "absent" ∧ prompt 估算 > limit（limit = window − reserve，恒为数）。
+  // **判据不用 maxTokens**：未发时为 undefined ⇒ NaN ⇒ 守卫静默失效（§6.17）；absent 档客户端未预留
+  // ⇒ 守卫不覆盖（服务端 400 兜——把规格 maxOutput 当实发判会让 doubao 三行永久发不出去）。
+  // 真 ⇒ 以 force 强制压缩一次（先压再判）；再估仍超 ⇒ 抛三实数、回合请求零发。不截断、不静默削输出。
+  const budget = requestBudget(agent.provider)
+  if (budget.maxTokensSource !== "absent") {
+    let usage = contextUsage(agent, compactionOverhead)
+    if (usage.total > budget.limit) {
+      const compacted = await compressIfNeeded(
+        agent, threshold, callbacks, { ...compactionOverhead, force: true }, signal,
+      )
+      if (compacted) bookkeepCompaction()
+      usage = contextUsage(agent, compactionOverhead)
+      if (usage.total > budget.limit) {
+        const remedy = budget.limit < 0
+          ? `max_tokens ${budget.maxTokens} alone exceeds the window — lower provider.maxTokens or switch to a larger-window model`
+          : "reduce the conversation (/compact or prune) before retrying"
+        const overflow = new Error(
+          `context overflow: prompt ~${usage.total} tokens + max_tokens ${budget.maxTokens} > window ${budget.window}` +
+          ` (limit ${budget.limit}) — forced compaction ran but the prompt still exceeds the window; ${remedy}`,
+        )
+        overflow.kind = "context_overflow"
+        overflow.retryable = false
+        throw overflow
+      }
+    }
+  }
 }
 
 /**

package/agent/run-start.mjs

@@ -105,6 +105,7 @@ export async function beginRun(agent, input, callbacks, {
   // #417（撞帽载荷「本段零落盘轮数」——只报数：零阈值常量 / 零自动动作）：段起点复位（首段 /
   // 续跑新段——与 `_continueSegments` 同点）；段内累加，采集点在回合环（与 `_turnSeq` 同源面）。
   agent._zeroWriteTurns = 0
+  agent._segmentTurns = 0 // #934 B 面读数分母（§6.32.4）：同点复位——同段同源（分子 ≤ 分母）
   if (!resume) {
     // 第 19 批（TURN-ACROSS-SEGMENTS——设计 TURN-CAP-CONTINUE.md §4）：链内累计编号
     // 只在链起点复位——续跑（resume:true）不重置、不回退（编号帧公式见 helpers.mjs

package/agent/setup.mjs

@@ -22,8 +22,8 @@ import { assembleFamilyTools } from "./family-tools.mjs"
 import { normalizeOrigin } from "../memory/origin.mjs"
 import { searchOrigins } from "../memory/code-search.mjs"
 import { INDEX_ORIGIN_ROW_WARN } from "../memory/schema.mjs"
+import { resolveCompactThreshold } from "../config.mjs"
 
-const DEFAULT_COMPACT_THRESHOLD = 100_000
 const DOC_SEARCH_LIMIT = 5
 const DOC_CHUNK_PREVIEW_LEN = 300
 /** UTF-16 安全截断（2026-09-02 deepseek 400 根因）：slice(0, N) 按码元切会把 emoji 代理对切成孤立
@@ -51,7 +51,9 @@ export async function prepareRun(agent, input, callbacks, {
   injections = null, toolDecorate = undefined,
 } = {}) {
   const maxTurns = overrideTurns ?? agent.config?.agent?.maxTurns ?? DEFAULT_MAX_TURNS
-  const threshold = agent.config?.agent?.compactThreshold ?? DEFAULT_COMPACT_THRESHOLD
+  // §6.17 每 run 现算：数值在场 = 显式原样；不在场 = auto 现算（按在用 provider——切模型后下一 run 跟手）。
+  // 派生值不落 agent.compactThreshold（显式键永不被改写）。
+  const threshold = resolveCompactThreshold(agent.config?.agent?.compactThreshold, agent.provider).value
   // 注入开关（PROMPT-SYSTEM.md §6.24 · 台账 #1420）：判据 `!== false`（缺省 = 现行为零变）——
   // 逐 run 现读 `agent.config` ⇒ `settings` 工具 ∕ `/config` 写入后本会话下一次组装即生效。
   const injectDocs = agent.config?.agent?.injectDocs !== false
@@ -62,6 +64,12 @@ export async function prepareRun(agent, input, callbacks, {
 
   agent._lastPromptTokens = null
   agent._usageAtLen = null
+  // Cumulative provider cache accounting (batch 2026-10-18-context-cache-visibility):
+  // the service reports prompt_cache_hit/miss per response; the terminal faces each kept
+  // their own tally, so the CORE had none and `context` could not report cache efficiency.
+  agent._cacheHitTokens = 0
+  agent._cacheMissTokens = 0
+  agent._usageTurns = 0
   agent.history = repairHistory(agent.history)
 
   if (!resume) {

package/agent/turn-loop.mjs

@@ -18,6 +18,7 @@ import {
   turnFrame, // 第 19 批（TURN-ACROSS-SEGMENTS）：跨段累计编号帧（设计 TURN-CAP-CONTINUE.md §4）
   ContinueError,
   FILE_MUTATORS, toolTouchPaths,
+  wroteSince, // #934（§6.32.2 ① 判据式）：写序是否推进——轮顶 ∥ 撞帽收尾两处判据点共用
 } from "./helpers.mjs"
 
 export async function runTurnLoop(agent, {
@@ -57,9 +58,10 @@ export async function runTurnLoop(agent, {
   // §6.31.5 落痕写点门（#939）：载体吸收经 `carrierField` 单点（§6.31.4 同式）；动态 import = 零新增静态边（沿上方两条同款）。
   const { carrierField } = await import("../agent-tools/async-settle.mjs")
 
-  // #417（撞帽载荷「本段零落盘轮数」——只报数：零阈值 / 零自动动作）：计数基线——回合环逐轮
-  // 比对 `_touchedFiles` 增量（轮顶对上一轮结账；撞帽收尾轮在环外单结）。
-  agent._turnFilesMark = agent._touchedFiles.length
+  // #417（撞帽载荷「本段零落盘轮数」——只报数：零阈值 / 零自动动作）∥ #934（零落笔看门狗）：计数基线——
+  // 判据物 = 写序（每次写事件 +1，不去重）；`_touchedFiles` 是去重路径集，同档重写长度不变 ⇒ 旧判据在
+  // 此读成零落笔（本收正要消除的误报方向）。环内逐轮结账、撞帽收尾轮在环外单结（同一谓词）。
+  agent._mutSeqMark = agent._mutationSeq
 
   for (let turn = 0; turn < maxTurns; turn++) {
     // #793（核面小修批——AGENT-LOOP.md §6.2 环边界中止前置 ∥ 需求 F5）：环头检查点——中止恒以
@@ -73,21 +75,23 @@ export async function runTurnLoop(agent, {
     const frame = turnFrame(++agent._turnSeq, turn, maxTurns)
     agent._currentTurn = frame.turn
     agent._maxTurns = frame.maxTurns
-    // #417（撞帽载荷「本段零落盘轮数」——采集点与 `_turnSeq` 同源面）：上一轮至今 `_touchedFiles`
-    // 零增 ⇒ 上一轮零落盘，计数 +1；mark 前移（收尾轮在环外结账——见下方 ContinueError 前）。
-    // #934（零落笔看门狗——§6.32.2 ① 单点采集）：streak 与越阈判定同点——上轮零写 ⇒ +1 并判越阈；
-    // 有写 ⇒ streak 归零 + 清闩（写后重臂——每连续零写段恰一条）。#417 计数语义逐字保持。
+    // #934 B 面读数分母（§6.32.4）：本段轮数逐轮 +1——段起点复位见 run-start.mjs（与零落笔计数同点）。
+    agent._segmentTurns = (agent._segmentTurns ?? 0) + 1
+    // #417（撞帽载荷「本段零落盘轮数」——采集点与 `_turnSeq` 同源面）：上一轮至今写序未推进
+    // ⇒ 上一轮零落笔，计数 +1；写序标每轮前移（撞帽收尾轮在环外结账——见下方 ContinueError 前）。
+    // #934（零落笔看门狗——§6.32.2 ① 单点采集）：streak 与越阈判定同点——上轮零落笔 ⇒ +1 并判越阈；
+    // 有落笔 ⇒ streak 归零 + 清闩（写后重臂——每连续零落笔段恰一条）。#417 计数与 streak 同源同谓词。
     if (turn > 0) {
-      if (agent._touchedFiles.length === agent._turnFilesMark) {
+      if (!wroteSince(agent, agent._mutSeqMark)) {
         agent._zeroWriteTurns += 1
         agent._zeroWriteStreak += 1
-        maybeZeroWriteAlert(agent) // #934：连续零写越阈 ⇒ 自动上行提醒（只推——§6.32）
+        maybeZeroWriteAlert(agent) // #934：连续零落笔越阈 ⇒ 自动上行提醒（只推——§6.32）
       } else {
         agent._zeroWriteStreak = 0
         agent._zeroWriteAlerted = false // 写后重臂
       }
     }
-    agent._turnFilesMark = agent._touchedFiles.length
+    agent._mutSeqMark = agent._mutationSeq
     // D2 (AGENT-LOOP-SUBAGENT.md §6.7.2): depth>0 children emit a ⟦ev⟧turn progress token each turn —
     // single emit point covering all three spawn tools; phase=llm (tool/done progress rides
     // the onToolCall/onToolResult relay — no token for those). 第 19 批：载荷取上方帧值
@@ -180,6 +184,12 @@ export async function runTurnLoop(agent, {
 
     if (response.usage) {
       callbacks.onUsage?.(response.usage)
+      // Core-side cumulative cache tally (batch 2026-10-18-context-cache-visibility):
+      // every agent (parent or child) keeps its own hit/miss so `context` can report
+      // cache efficiency instead of the terminal faces being the only tally holders.
+      agent._cacheHitTokens = (agent._cacheHitTokens ?? 0) + (response.usage.prompt_cache_hit_tokens ?? 0)
+      agent._cacheMissTokens = (agent._cacheMissTokens ?? 0) + (response.usage.prompt_cache_miss_tokens ?? 0)
+      agent._usageTurns = (agent._usageTurns ?? 0) + 1
       if (response.usage.prompt_tokens != null) {
         agent._lastPromptTokens = response.usage.prompt_tokens
         agent._usageAtLen = agent.history.length
@@ -265,9 +275,9 @@ export async function runTurnLoop(agent, {
     injectPostTurn(agent, results, recentCallSigs, callbacks, turn, { suspDriven })
   }
 
-  // #417（撞帽载荷「本段零落盘轮数」）：收尾轮（撞帽轮）若零落盘同样计入——轮顶计数只
-  // 覆盖到倒数第二轮（maxTurns ≤ 0 时环未跑，不虚计）。
-  if (maxTurns > 0 && agent._touchedFiles.length === agent._turnFilesMark) agent._zeroWriteTurns += 1
+  // #417（撞帽载荷「本段零落盘轮数」）：收尾轮（撞帽轮）单结——与环内同一谓词（不另作 alert ∥ streak
+  // 判定，链尾无下一轮可推报）；轮顶计数只覆盖到倒数第二轮（maxTurns ≤ 0 时环未跑，不虚计）。
+  if (maxTurns > 0 && !wroteSince(agent, agent._mutSeqMark)) agent._zeroWriteTurns += 1
   // #793（核面小修批——AGENT-LOOP.md §6.2 环边界中止前置 ∥ 需求 F5）：环尾检查点——中止恒以
   // AbortError 收束（不落 ContinueError——用户 Stop 优先于继续提示；消费契约 = 外层按 reason 判定）。
   if (signal?.aborted) throw abortError(signal, "agent", "turn-tail")

package/agent-tools/audit-block.mjs

@@ -23,9 +23,11 @@
  */
 export function summarizeEngTaskBook(taskInput) {
   if (!taskInput) return "(unavailable)"
+  // 五项拼装形下，`designPoints` 一段同时承载「设计档落点」与「受影响文件清单」——
+  // 前两段同取该块是有意的（语义都在其中）；代价 = 摘要里该块出现两次，不是抽取失败。
   const SECTIONS = [
-    { name: "Design docs involved", markers: [/Docs? involved/i, /涉及文档/] },
-    { name: "Affected-file list", markers: [/Files? (?:list|to (?:modify|change)|modified)/i, /受影响文件/, /文件清单/, /涉及文件/] },
+    { name: "Design docs involved", markers: [/Docs? involved/i, /涉及文档/, /^Design points/i] },
+    { name: "Affected-file list", markers: [/Files? (?:list|to (?:modify|change)|modified)/i, /受影响文件/, /文件清单/, /涉及文件/, /^Design points/i] },
     { name: "Acceptance criteria", markers: [/Acceptance(?: criteria)?/i, /验收标准/] },
   ]
   const lines = taskInput.split("\n")