@thincoder/core 0.10.9 → 0.10.11

package/CHANGELOG.md

@@ -3,7 +3,31 @@
 All notable changes to the core package are documented here.
 Format: Keep a Changelog · 中文 · 号在发布时定（CalVer——见 `docs/RELEASE.md` §4）。
 
-## [Unreleased]
+## [0.10.11] — 2026-10-25
+
+### Added
+
+- **`providers[].modelContext`（按模型的人工上下文声明，单位 K）**：键 = 模型 ID（末段归一等价——`qwen/ZHIPU/GLM-5.3` ≡ `glm-5.3`），值 = 正整数 K（`128` = 128K）。
+- **模型上下文五级解析链**：`modelContext` > 旧键 `providers[].context` > 渠道 `/models` 自报（`context_window` / `context_length` / `max_model_len`，取第一个合法值）> `MODEL_SPECS` 静态表 > 默认 128K；列表自报值是 token（直接采用），人工声明是 K（核内唯一乘点 ×1024）。
+- **核导出 `providerSpecResolution(provider)` / `formatContextK(tokens)`**：来源五值（`modelContext` / `provider-override` / `list` / `spec` / `default`）与三端同一展示格式器。
+
+### Changed
+
+- **旧键 `providers[].context` 退役为只读过渡层（A7 兼容）**：仍可读（L2，K 单位，仅未被 `modelContext` 点名的模型），但不再写入新配置——K 单位旧编辑命令退役，三端写面改用 `modelContext`（三端同批，随各端包发布）；实际用到 L2 时告警一次并给出迁移形 `modelContext: { "<模型>": <K> }`（单位同为 K）。
+- **`requestBudget().windowSource` 扩为五值**：读 `providerSpecResolution().source`（原二值 `provider-override` / `spec`），五个枚举值原样入 `Request budget:` 行（不并类）。
+- **模型名匹配改「末段唯一」**：按 `/` 拆分后只取最后一段查表，不再先扫完整名——`glm-5.3/zzz` 由误命中 `glm-5.3`（1M 上下文）改为未命中（`DEFAULT_SPEC` + 告警）；`kimi/kimi-k3` 表行退役（末段 `kimi-k3` 已有同值行，含 `/` 的键不可达）。
+
+## [0.10.10] — 2026-10-22
+
+### Added
+
+- **子代理 `manifest` 只读面**：同名工具、`action` 枚举只剩 `read`（schema 级不可达 + execute 入口再拒一次），挂全部 depth>0 角色段；写面仍归主 agent——`init` / `write` 不在其装配，只读位也不落在全量变体上，审批门不被绕过。`readAction` 增 `canInit`：子代理侧缺档 / 无项目两态的引导行不再指向它调不到的 `init`。
+- **`thincoder-core/prompts/common.md` 新增「动手前先查文档」一节**：代码只记形状，理由与后果住在文档里；一次会话只完成大任务的一步、上下文只是项目已知内容的一小部分，不先查就是拿局部当整体。
+
+### Changed
+
+- **提示词面 16 档重写（一条规则一行）**：`>300` 字符行 290 → **0**（最长 1,486 → 300，为未改动原行）；整句加粗 / 回查指代 / 出处括注 / 写死配置值 / 本仓路径 / 中文评审面六类残留清零。判据 = 「换个仓还成立吗」——规则只写行为，不写归属、不写配置值、不写本仓路径（配置值改教模型用 `settings` 读，路径改教用 `manifest` 取 `docRoot`）。
+- **`tool-docs` 计数随动**：53 → 54 档（枚举工具 52 → 53）。
 
 ## [0.10.9] — 2026-10-19
 
@@ -191,7 +215,9 @@ Format: Keep a Changelog · 中文 · 号在发布时定（CalVer——见 `docs
 
 ### Added
 
-- **规格表覆盖扩面（新名专行）**：`qwen-flash` / `qwen-vl-max`（实测输出上限 32_768——服务端直报 `[1, 32768]`；前者思考默认可开、后者不支持）、`claude-fable-5.1`（1_000_000 / 128_000）、`gemini-3.1-pro`（1_048_576 / 65_536）、`stepfun/step-3.7-flash`（262_144）；kimi-code 平台三行（`kimi-for-coding` / `kimi-for-coding-highspeed` / `k3-256k`——含 effort 枚举与默认档）——掉兜底名不再退默认。
+- **规格表覆盖扩面（新名专行）**：`qwen-flash` / `qwen-vl-max`（实测输出上限 32_768——服务端直报 `[1, 32768]`；前者思考默认可开、后者不支持）、
+  `claude-fable-5.1`（1_000_000 / 128_000）、`gemini-3.1-pro`（1_048_576 / 65_536）、`stepfun/step-3.7-flash`（262_144）；
+  kimi-code 平台三行（`kimi-for-coding` / `kimi-for-coding-highspeed` / `k3-256k`——含 effort 枚举与默认档）——掉兜底名不再退默认。
 - **bench 受测 10 档规格行**：此前经泛前缀/兜底解析的受测模型补独立行 + 视觉声明分态登记。
 - **跨实例意图认领层（P1）**：`peers/{sessionId}.json` 增 claims 意图域（TTL 30 分钟租约 · 进程死亡即失效）；写前命中他实例活认领 ⇒ 软提示（不阻写；与写后足迹登记分开存）。
 

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/completion.mjs

@@ -8,6 +8,7 @@
 import { hasCodeMutations } from "../advisor/repos.mjs"
 import { pushReal } from "../context.mjs"
 import { advisorReviewPending, effectiveAdvisorRound } from "../agent-tools/advisor-async.mjs"
+import { poolLive } from "./suspension.mjs"
 
 const MAX_VERIFY_PUSHBACKS = 2
 const MAX_VERIFY_RETRIES = 3
@@ -59,7 +60,9 @@ export function handleCompletion(agent, response, depth, turn, guardPushbacks, h
   // list state earns one fresh reminder.
   // F10（催更门连带）：工程模式下 task 工具机械停用（装配摘除 + execute 拒）⇒ 不再发指向被拒
   // 工具的提醒（死胡同提醒防线）；列表本体与 `_taskPushbacks` 预算语义零改。
-  if (depth === 0 && !agent.config?.agent?.engineering && agent.tasks.some((t) => t.status === "pending") && (agent._taskPushbacks ?? 0) < 1) {
+  // TIMEOUT-DIGEST.md §2.3（#29）：后台池 live 时不推回——池在飞时回合本就还会被 settle 唤醒，
+  // 此时催 task 只会拖回合；判据复用 `poolLive`（与挂起尾巴同一口径，不立第二处）。
+  if (depth === 0 && !agent.config?.agent?.engineering && !poolLive(agent) && agent.tasks.some((t) => t.status === "pending") && (agent._taskPushbacks ?? 0) < 1) {
     agent._taskPushbacks = (agent._taskPushbacks ?? 0) + 1
     const pending = agent.tasks.filter((t) => t.status === "pending").map((t) => t.title).join(", ")
     pushReal(agent, { role: "assistant", content: response.content })

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")
@@ -95,8 +95,8 @@ export async function assembleFamilyTools({
         // async, the check/status params (id/n), the eng-coder token params
         // (designToken/designId are meaningless for a read-only spawn; the parent
         // spawn already carried the token) and batchDoc (an audit child derives no
-        // batch parameter — its task book rides the mechanical summary of the
-        // parent's _engTaskInput instead). Schema noise would invite the
+        // batch parameter — its task book rides the parent's batch record §2 instead
+        // (the audit block carries the batchDoc path)). Schema noise would invite the
         // model to pass irrelevant args.
         delete props.async // sync only — the parent blocks on the child's report
         delete props.id
@@ -126,7 +126,7 @@ export async function assembleFamilyTools({
           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. 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.",
+            : "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 context is appended MECHANICALLY — the batch record path (its §2 is the delivery's task book, read it before judging) 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

@@ -150,24 +150,26 @@ export async function cleanupOldToolResults(dir) {
   }
 }
 
-/** Offload oversized tool results (>64K chars) to disk, returning a head+tail preview + file path
- *  (2026-09-04 §5 — dual-end preview; the failed-offload fallback uses the same dual-end slice).
- *  Writes trigger write-time self-cleanup of the offload dir first (dir param overridable for tests). */
-export async function offloadToolResult(text, callId, dir = join(configDir, "tool-results")) {
-  if (text.length <= TOOL_RESULT_OFFLOAD_LIMIT) return text
+/** Offload a tool result / report to disk (§2.2): `force` = write regardless of size (async
+ *  subagent reports must survive the parent turn). Rendering splits on the SAME constant as the old
+ *  gate: ≤ TOOL_RESULT_OFFLOAD_LIMIT ⇒ body once + path (never dual-end — a short body would come
+ *  out twice with `middle omitted: 0 chars`); > ⇒ dual-end preview + path. Writes self-clean first. */
+export async function offloadToolResult(text, callId, dir = join(configDir, "tool-results"), { force = false } = {}) {
+  const overLimit = text.length > TOOL_RESULT_OFFLOAD_LIMIT
+  if (!force && !overLimit) return text
   try {
     await cleanupOldToolResults(dir)
     await mkdir(dir, { recursive: true })
     const file = join(dir, `${Date.now()}-${String(callId).replace(/[^a-zA-Z0-9_-]/g, "_")}.log`)
     await writeFile(file, text, "utf8")
-    return (
-      buildDualEndPreview(text) +
-      `\n\n[... output too large (${text.length} chars total), full content saved to: ${file}\n` +
+    if (!overLimit) return `${text}\n\n[... full content saved to: ${file}\nPage through it with the read tool (offset/limit) if you need the full text later.]`
+    return buildDualEndPreview(text) + `\n\n[... output too large (${text.length} chars total), full content saved to: ${file}\n` +
       `Page through it with the read tool (offset/limit) or sed -n 'START,ENDp' — do NOT re-run the tool blindly.]`
-    )
   } catch {
-    // review #3: fallback uses the same dual-end slice (head + omitted note + tail, no path hint)
-    return buildDualEndPreview(text) + `\n\n[... truncated: ${text.length} chars total, offload to disk failed]`
+    // 写盘失败不吞报告：>LIMIT 走双端预览 + 原文案；≤LIMIT 正文整段在前（不谎称 truncated）
+    const body = overLimit ? buildDualEndPreview(text) : text
+    return body + (overLimit ? `\n\n[... truncated: ${text.length} chars total, offload to disk failed]`
+      : `\n\n[... full text kept inline above (${text.length} chars), offload to disk failed]`)
   }
 }
 
@@ -275,6 +277,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 = []

package/agent/light-round.mjs

@@ -21,9 +21,6 @@ import { projectRootView, resolveProjectRoot } from "../manifest.mjs"
 import { resolveDeclaredRef } from "../declaration.mjs"
 import { readBatchStatusLine } from "../agent-tools/batch-skeleton.mjs"
 
-/** 轮型标记（§2.3 开轮形升格为闸凭据；全链批行无此标记 ⇒ 不构成信号）。 */
-const ROUND_MARKER = "收尾链待跑"
-
 /** 轻通道轮在盘谓词（异步 · 只读 · fail-closed）。契约见头注。
  * @param {object} agent — 会话 agent（读 `cwd`）
  * @returns {Promise<boolean>} true = 放行（在盘轮次）；读错 ∥ 不可判 ⇒ false（照拦）
@@ -33,7 +30,7 @@ export async function lightRoundOpen(agent) {
     const cwd = agent?.cwd
     if (typeof cwd !== "string" || cwd.trim() === "") return false
     // W8 契约②：node:sqlite 链只经动态 import 进入（勿升静态）——候选枚举与逐候选查行同取本档公共面。
-    const { ledgerChildren, ledgerQuery } = await import("../ledger.mjs")
+    const { ledgerChildren, ledgerQuery, ROUND_MARKER } = await import("../ledger.mjs")
     const anchor = resolve(cwd)
     // 候选面 = 锚自身 + 直接子目录一层（纯向下；子项枚举单源 = `ledgerChildren`）。
     const candidates = [anchor, ...ledgerChildren(anchor).map((p) => p.root)]

package/agent/record-results.mjs

@@ -26,6 +26,8 @@
 import { pushReal } from "../context.mjs"
 import { specForModel } from "../config.mjs"
 import { FILE_MUTATORS, toolTouchPaths } from "./helpers.mjs"
+// F-LC6（LIGHT-CHANNEL §2.9 · 台账 #1753）：无账之笔提醒叶（谓词 + 文案 + 闩单源）。
+import { unbookedPenNotice } from "./unbooked-pen.mjs"
 import { capHistoryImages } from "../provider/normalize.mjs"
 import { resolve } from "node:path"
 import { advisorRuns, stripApprovedSuffix } from "../agent-tools/advisor-async.mjs"
@@ -82,7 +84,10 @@ export async function recordToolResults(agent, toolByName, results) {
         }
       } catch { /* Parse failure doesn't affect normal tool messages */ }
     }
-    pushReal(agent, { role: "tool", tool_call_id: toolCall.id, name: toolCall.name, content: result })
+    // F-LC6（LIGHT-CHANNEL §2.9）：主 agent 会话首笔产品源文件笔 ⇒ 回执末尾追加一行通道提醒
+    // （零拦截——只拼回执文本、入史时机不变；命中后本会话不再提示）。
+    const penNotice = unbookedPenNotice(agent, toolCall, ok, tool)
+    pushReal(agent, { role: "tool", tool_call_id: toolCall.id, name: toolCall.name, content: penNotice ? result + penNotice : result })
     if (tool && ok) {
       if (FILE_MUTATORS.has(toolCall.name)) {
         // Direct file edit — code was changed. The prior advisor review and

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-reminders.mjs

@@ -88,7 +88,7 @@ export function manifestStateLine({ phase }) {
  */
 export function manifestReportLine({ state, cwd, root, path, candidates, errors, matched } = {}) {
   if (state === "no-project") {
-    return `${MANIFEST_LINE_PREFIX}none — no project at ${cwd} (no manifest on the ancestor chain, none below). ` +
+    return `${MANIFEST_LINE_PREFIX}none — no project at ${cwd} (no manifest at this directory, none in the direct children). ` +
       `Parameters fall back to defaults. Create PROJECT-MANIFEST.json here to land a project (git optional).]`
   }
   if (state === "workspace") {

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 批：载荷取上方帧值
@@ -271,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/unbooked-pen.mjs

@@ -0,0 +1,62 @@
+/**
+ * unbooked-pen.mjs — 无账之笔提醒叶（批 unbooked-pen · 台账 #1753）。
+ * 设计权威 = `docs/core/design/LIGHT-CHANNEL.md` §2.9（F-LC6）；需求 = `docs/core/requirements/LIGHT-CHANNEL.md` §2.6。
+ *
+ * 机制：每会话**首次**由主 agent 落下**产品源文件**笔时，在工具回执末尾追加一行通道确认提醒。
+ * 只提示——不拦、不放行、不改任何判据；文案为条件句（轻通道笔须先挂轮，全链笔交 eng-coder）。
+ * 承载形对齐先例 `agent-tools/zero-write-watch.mjs`（谓词叶 + 文案函数 + 闩 + 非阻塞）。
+ * 零环：只 import 既有单源（`FILE_MUTATORS` ∥ `toolTouchPaths` ∥ `isCodePath` ∥ `declarationForTarget`），
+ * 只被 `agent/record-results.mjs` import（不反向引）。
+ */
+import { resolve } from "node:path"
+import { FILE_MUTATORS, toolTouchPaths } from "./helpers.mjs"
+import { declarationForTarget } from "../declaration.mjs"
+import { isCodePath } from "../conventions.mjs"
+
+/** 笔集（§2.9 ②）：`FILE_MUTATORS` **减** `delete`——减式派生，不另抄第二份工具名清单
+ *  （`FILE_MUTATORS` 增删成员时本集自动跟上）。`delete` 不入集：删产品源文件须 `force`、
+ *  是显式动作，本批无场景（K20）。 */
+export const PEN_TOOLS = new Set([...FILE_MUTATORS].filter((name) => name !== "delete"))
+
+/** 文案单源（§2.9 文案块逐字——条件句 + 后果句；改文案只改这一处）。 */
+export function unbookedPenText() {
+  return "[pen check] first product-source write this session — confirm the channel before it lands: a light-channel pen needs its round booked first (batch record + an in-flight ledger row pointing at the record); a full-chain pen goes to eng-coder. A pen with no account is invisible at closeout, so the ledger settlement misses it."
+}
+
+/**
+ * 四合取 + 一闩判定（§2.9 触发面）——命中：置闩并返回回执后缀（`\n` + 文案行）；未中：空串。
+ * ① 身份 = 主 agent（`_role == null`——主会话装配不传 role，子代理 spawn 面统一传角色）
+ * ② 工具 ∈ `PEN_TOOLS` ③ `ok === true` ④ 任一目标分类为产品源文件
+ *    （逐目标 `resolve(cwd, p)` → `declarationForTarget(abs)` → `isCodePath(abs, conv)`——与父侧门
+ *     `agent/dispatch.mjs:111-118` 同式；出辖目标不判，任一命中即触发）
+ * 闩 = `agent._unbookedPenNotified`（每会话一次——不按轮、不按文件）。
+ * @param {object} agent 主 agent（读 `cwd` ∥ `_role` ∥ 闩位）
+ * @param {{name: string, arguments?: string}} toolCall
+ * @param {boolean} ok 工具结果成功位（被拒的笔没有落盘，提醒无对象）
+ * @param {object} [tool] 工具对象——只用于 `toolTouchPaths` 的可选钩子 `touchedPaths`
+ *   （`apply_patch` ∥ 多目标 `edit` 的目标解析靠它；缺省按单参 `path`）
+ * @returns {string} 命中 = 回执后缀；未中 = ""
+ */
+export function unbookedPenNotice(agent, toolCall, ok, tool) {
+  if (!agent || agent._role != null) return ""
+  if (!tool) return ""
+  if (ok !== true) return ""
+  if (agent._unbookedPenNotified) return ""
+  if (!PEN_TOOLS.has(toolCall?.name)) return ""
+  try {
+    const args = JSON.parse(toolCall.arguments || "{}")
+    const hit = toolTouchPaths(tool, args).some((p) => {
+      if (typeof p !== "string" || !p.trim()) return false
+      const abs = resolve(agent.cwd, p)
+      const conv = declarationForTarget(abs)
+      return !!conv && isCodePath(abs, conv)
+    })
+    if (!hit) return ""
+  } catch {
+    // 恒零抛（先例 zero-write-watch.mjs 同款）：提醒是兜底面——判定失败不得中断回执提交
+    // （畸形 args ∥ 非标准装配的 cwd）。退回空串 = 本笔不提示，判据面零变。
+    return ""
+  }
+  agent._unbookedPenNotified = true
+  return `\n${unbookedPenText()}`
+}