@thincoder/core 0.9.2 → 0.9.4

package/CHANGELOG.md

@@ -0,0 +1,76 @@
+# Changelog（@thincoder/core）
+
+All notable changes to the core package are documented here.
+Format: Keep a Changelog · 中文 · 号在发布时定（CalVer——见 `docs/RELEASE.md` §4）。
+
+## [0.9.4] — 2026-09-22
+
+> 0.9.3 → 0.9.4（月内序号——发布时定号）
+
+### Added
+
+- **MiMo V2.6 三款规格行**（`mimo-v2.6-pro` / `mimo-v2.6-flash` / `mimo-v2.6-pro-ultraspeed`——同日上架）：此前缺行落兜底（128K / 32K / 无视觉），现按真机实测登记——1M 上下文 · 131_072 输出 · 思考默认开（`thinking.type`）· 全模态 · 自动缓存。
+
+### Changed
+
+- **MiMo v2.5 两行存量对齐**（同日实测）：`maxOutput` 128_000 → 131_072 + 补自动缓存登记；族头注与 `assistantToolCallMessage` 文书句按 2026-09-22 复测改写（原「缺字段 → 400」句已不可复现——回显策略保持保守不变）。
+- **MiMo 预设改指**：`mimo` / `mimoplan` 默认模型 → `mimo-v2.6-pro`（v2.5 官网标注即将下线；Token Plan 端点同平台推断）。
+
+## [0.9.3] — 2026-09-22
+
+> 0.9.2 → 0.9.3（月内序号——发布时定号）
+
+### Added
+
+- **派生会话索引库**（`node:sqlite` · 零新依赖）：`read_history` 超大会话不再整档拒（>50k 消息经索引可查）+ `path:"all"` 跨会话检索（行携 `session.file` 回查锚）+ `tool_calls` 携参数；索引从记录段增量建 · 可重建（丢/坏自愈）· 主存（会话文件）零改。
+- **子代理「系统固块」**：机制性指令（审计五锚 + 批档行）改由 spawn 单点写入并拼进 system 面（前缀缓存契约——同 child 连跑 `systemPrompt` 逐字节相等）。
+- **进程族单源**：`killProcessTree` 收口为 `tools/process-tree.mjs`（核 / VSC 本地副本全消除）。
+- **退出即释放会话认领**：正常退出释放本进程认领（端标记保留作路标）——重启恢复不再依赖进程探测兜底。
+- **认领释放扩面**：ACP `session/close` · 跨 cwd 释放 · 被占槽返回可区分信号（零写）。
+
+### Changed
+
+- **批档工具词面协议结构化**：`batch status` enum 化（散文走 `note`）+ `create` 补 `source` / `prev` 前缀归一 / 占位自动；append/status 占位残留机检（fail-closed）。
+- **工程模式 `task` 工具机械停用**（追踪面 = 批档 + 台账；普通模式零改）。
+- **设置面**：敏感键谓词导出 + 非敏感父对象 JSON 化渲染（`[object Object]` 瑕疙消除）。
+- FTS 语言面外提 `fts-text.mjs`（`segmentCJK` / `buildFtsQuery` 单源 + re-export 面）。
+
+### Fixed
+
+- 会话索引自愈链（坏库 / 删库现场保留 + 重建）· 段轮转与等长改写的水位判别 · 源消失级联清行。
+
+## [0.9.2] — 2026-09-21
+
+> 0.9.1 → 0.9.2（月内序号——发布时定号）
+
+### Added
+
+- **PROJECT-MANIFEST 模型（按用点解析）**：项目发现五级梯（会话锚 → 带档祖先 → 一层子档 → 工作区……）+ owning-ancestor 归属 + 建档流；整档缺失不再静默（启动降级 + 明示提示）。
+- **批档生命周期工具** `batch`（create / append / status / close——原 `batch_segment` 更名，别名保留）。
+- **台账执行人列**（F-LX1）：executor 归属 + 判存活显示。
+- **信号行两档标签**（digest / ask）+ ask 参数 + 起始行（F-UC8）。
+- **会话认领释放**（F-CR1/CR2）：释放 + 拒绝零写入。
+
+### Changed
+
+- **非阻塞启动**：异步会话 GC · 陈旧清扫 · traces 清理（启动不再被大扫除卡住）。
+- **工程模式排除 `plan` 角色**（FR31——装配 / 命令 / 残留三面一致）。
+- **包面**：README 补建（static 工具口径收正）+ LICENSE + npm 元数据；`files` 白名单不变。
+
+### Fixed
+
+- 批别名残留（测试断言 / 提示词文档引用 / 错误串）· VSC 子代理块标题行与 CLI 对齐（标题段补全）。
+
+## [0.9.1] — 2026-09-21
+
+> 核首发（2026-09 当月推导——registry 无号 ⇒ `0.<当月>.1`；首发即本段 ✗ 无更早历史——核内容此前散在两产品仓 ✗ 无独立版本号可考 ✗）。
+
+### Added
+
+- **核包首发 `@thincoder/core@0.9.1`**：两产品共享机制收敛后的单一权威源——agent 执行环 / 子代理调度（spawn-gate · async 池 · notify_parent）· advisor 评审 · provider 层（SSE 流式 · thinking 映射 · 重试）· 记忆三层 · 工具系统 · 会话存储 · MCP 客户端 · git 集成 · 台账。
+- **提示词与工具文档随包分发**：`prompts/` 15 档 + `tool-docs/` 24 档（一致性断言 D 对象——与 CLI 装机目录 / vsix 三处逐字相等）。
+- **发布门禁**：`prepublishOnly` = `npm test`（与 CLI/VSC 门禁对称——2026-09-21 首发 补上）。
+
+### Changed
+
+- 两产品 `dependencies` 同步收正 `^0.1.0 → ^0.9.1`（声明面与 registry 实发对齐——断言 A）。

package/README.md

@@ -75,6 +75,7 @@ Version numbers are calendar-based (CalVer): `year.month.monthly-count`, where t
 2026 (`0` = 2026). `0.9.1` is therefore the first core release of September 2026.
 
 The number marks release time, not API compatibility — read `CHANGELOG.md` for what changed.
+Per-release notes and artifacts: `CHANGELOG.md` in this package and the [GitHub Releases](https://github.com/xinbo-tech/thincoder/releases) page.
 
 ## Contributing
 

package/agent/completion.mjs

@@ -53,7 +53,9 @@ export function handleCompletion(agent, response, depth, turn, guardPushbacks, h
   // pending item can't be resolved). After the single reminder the model is free
   // to finish — updating the task list (task tool) resets the budget, so a fresh
   // list state earns one fresh reminder.
-  if (depth === 0 && agent.tasks.some((t) => t.status === "pending") && (agent._taskPushbacks ?? 0) < 1) {
+  // F10（催更门连带）：工程模式下 task 工具机械停用（装配摘除 + execute 拒）⇒ 不再发指向被拒
+  // 工具的提醒（死胡同提醒防线）；列表本体与 `_taskPushbacks` 预算语义零改。
+  if (depth === 0 && !agent.config?.agent?.engineering && 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

@@ -7,7 +7,8 @@
  * consult 池来源）经 `decorate` 注入——**不传 = 核默认形态**（CLI = 迁出前逐字）。
  *
  * 返回 = 家族段数组（**非**工程模式：`[task, plan, timer, ...depth 家族 / 角色段]`；工程模式：
- * 固定段 = `[task, timer]`——plan 不入表，FR31 ① / KD8）——**不含** `agent.tools`
+ * 固定段 = `[timer]`——plan 不入表（FR31 ① / KD8）· task 不入表（F10——工程模式机械停用，
+ * 同 KD8 卸载处置））——**不含** `agent.tools`
  * 展开与 `extraTools`（调用点各自展开：核 `agent/setup.mjs` 两段式）。
  *
  * 登记册**动态**载入：`agent-tools.mjs` 静态图经 consult/subagent 族可达核 agent 栈
@@ -25,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, batchTool, consultStartTool, consultStopTool, parentChannelTool } = await import("../agent-tools.mjs")
+  const { planTool, subagentTool, taskTool, skillTool, goalTool, verifyTool, recentChangesTool, timerTool, advisorTool, engTool, readHistoryTool, contextTool, batchTool, consultStartTool, consultStopTool, parentChannelTool } = await import("../agent-tools.mjs")
   // 写命令（主 agent 专用）——动态 import 且**仅 depth===0 载入**（ledger 链静态达 node:sqlite——
   // W8 契约②；子代理路径不注册 = 零载入——depth>0 解构得空、不引用即无副作用）
   const { ledgerAddTool, ledgerUpdateTool, ledgerCloseTool } = depth === 0 ? await import("../ledger.mjs") : {}
@@ -138,7 +139,7 @@ export async function assembleFamilyTools({
     : []
 
   const depthOnly = depth === 0
-    ? [decorate?.subagent ?? filteredSubagent, skillTool, goalTool, engTool, verifyTool, recentChangesTool, readHistoryTool, advisorTool, batchTool(null),
+    ? [decorate?.subagent ?? filteredSubagent, skillTool, goalTool, engTool, verifyTool, recentChangesTool, readHistoryTool, contextTool, advisorTool, batchTool(null),
       ...consultTools,
       // 台账写命令（M2——仅主 agent；查询面 ledger_count 住基础集 tools/index.mjs）。
       // fail-closed：子代理不挂载 = 写面机械不可达。
@@ -162,7 +163,7 @@ export async function assembleFamilyTools({
     // 挂载形态已随单名化收口退役（过渡别名 §4.14 不入生产挂载面）；depth-0 主 agent 同表挂载
     // `batch`（D-BR18 扩权——create/close + append §1/§4/§6 + status §1（轮 2 裁定②：§4/§6
     // 状态面走普通文档写），目标走可选 path / 在飞扫描）。
-    // SUBAGENT-UPSTREAM-CHANNEL（AGENT-LOOP-SUBAGENT.md §6.27.4 装配接线）：子代理上行通道
+    // SUBAGENT-UPSTREAM-CHANNEL（AGENT-LOOP-UPSTREAM.md §6.27.4 装配接线）：子代理上行通道
     // （`notify_parent`）随 depth>0 段**前置**——4 处携带 = eng-coder / eng-designer / coder / 兜底段
     // （未列名 depth>0 role 落同一兜底段 ⇒ 亦装配；语义 =「depth>0 且非 consult 皆装配」）；
     // 计数口径：`consult` 分支不入 ⇒ 「5 个插入点」读法已作废（实读 `thincoder-core/agent/family-tools.mjs:165-169`）。
@@ -173,12 +174,14 @@ export async function assembleFamilyTools({
     : role === "consult" ? [recentChangesTool]
     : [parentChannelTool]
 
-  // 固定段（装配序 = agent.tools → 固定段 → 家族段 → extraTools）：task/timer 全模式全深度；
-  // plan 随模式位——ENG-PLAN-EXCLUSION（FR31 ① · KD8 卸载而非「注册 + 报错」· KD11 全深度两端）：
-  // plan **不入表**（模型不可见——看不见的选项不会被选）；普通模式固定段逐字不变（FR31 边界）。
+  // 固定段（装配序 = agent.tools → 固定段 → 家族段 → extraTools）：timer 全模式全深度；
+  // plan 随模式位——ENG-PLAN-EXCLUSION（FR31 ① · KD8 卸载而非「注册 + 报错」· KD11 全深度两端）；
+  // task 随模式位——F10（task 工程模式机械停用；同 KD8 处置：**不入表**——模型不可见、零 token 税；
+  // execute 层另有机械拒兜底，见 `agent-tools/task.mjs`）。
+  // 工程模式固定段 = plan / task 皆**不入表**；普通模式固定段逐字不变（FR31 边界 / F10 边界）。
   // 判据 = 单一模式位 `engineering`（不带深度分支——子代理面随同排除，role enum
-  // `:44-49` + spawn 门已同向）。
+  // `:44-49` + spawn 门 / task execute 门已同向）。
   return engineering
-    ? [taskTool, timerTool, ...depthOnly]
+    ? [timerTool, ...depthOnly]
     : [taskTool, planTool, timerTool, ...depthOnly]
 }

package/agent/helpers.mjs

@@ -386,13 +386,22 @@ export const ENG_OFF_REMINDER =
   "Changes go through the normal workflow: you may edit files directly, advisor/verify " +
   "guards apply per config.]"
 
-/** Manual-tier auto-turn digest domain (AGENT-LOOP.md §17 D-S6): organize-only.
+/** Manual-tier auto-turn digest domain (normal-mode base — engineering variant =
+ *  AUTO_TURN_DIGEST_DOMAIN_ENG below): organize-only. Mechanism = AGENT-LOOP-ASYNC-POOL.md §6.8;
+ *  mode variant text = TOOLS.md §6.15.3.
  *  Injected per manual auto-turn run — writes/execute/spawns/questions are also
  *  mechanically denied (no permission handler + spawn gate); this steers first. */
 export const AUTO_TURN_DIGEST_DOMAIN =
   "[System reminder: auto-turn — background async subagents finished while there was no user message, and this turn runs automatically to digest their reports (the finished-report reminders above). No one is waiting for this reply, so organize only: 1) summarize each finished report's key points into this conversation for the user to read later; 2) update the task list with the task tool (allowed) to mark finished work done; 3) write decision points with a suggested next step as text — do not execute it. FORBIDDEN this turn (mechanically enforced): modifying files, bash/execute/verify, spawning subagents, asking questions — those need a real user message. End the turn once the summaries are written.]"
 
-/** Up-stream wake-turn domain (AGENT-LOOP-SUBAGENT.md §6.27.12.8): a running subagent sent
+/** 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. */
+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. */

package/agent/run-stages.mjs

@@ -11,10 +11,10 @@ import { compressIfNeeded, compressFallback, COMPRESS_FAILURE_LIMIT } from "../c
 import { ensureAutoReminder, injectEngineeringReminder, ContinueError, snapshotGuard } from "./helpers.mjs"
 import { pushManifestStateReminder } from "./setup-reminders.mjs"
 import { cleanupConsultSessions } from "../agent-tools/consult.mjs"
-import { logEvent } from "../log.mjs"
+import { logEvent, errText } from "../log.mjs"
 // ASYNC-RESULT-CONTAINER.md D1：池 accessor（absorb 双池——advisor 独立池无队列）
 import { getAsyncPool, releaseSettledEntry } from "../agent-tools/async-settle.mjs"
-// 批 4 CLI-ASYNC-DISCARD（AGENT-LOOP-SUBAGENT.md §6.20）：中止分支「只清已死」收尾单点
+// 批 4 CLI-ASYNC-DISCARD（AGENT-LOOP-ASYNC-POOL.md §6.20）：中止分支「只清已死」收尾单点
 import { discardAbortedPool, discardAbortedAdvisors } from "../agent-tools/async-discard.mjs"
 // R10 L3 (MULTI-INSTANCE-COLLAB §2a.5 D-L3a)：回合末域登记 flush（写工具钩子累积 →
 // 整写一次本实例 peers 文件——无写入跳过；失败容忍不抛）
@@ -59,11 +59,28 @@ export function injectResponseReminders(agent, response) {
  * 计数复位（recentCallSigs——runAgent 回合级局部——经 ctx 传对象引用）/压缩完成事件
  * /AUTO 提醒重注入。失败：AbortError 透传；计数 + Q3 onCompressFail；
  * COMPRESS_FAILURE_LIMIT 连续失败降级 compressFallback（确定性截断——不发 LLM）。
+ * 模型主动压缩（`context` 工具）由本点消费（§6.16.2——取用即清槽；no-op 与失败各落一行注记）。
  */
 export async function runCompactionCheck(agent, ctx) {
   const { threshold, callbacks, compactionOverhead, signal, recentCallSigs } = ctx
+  // F-CC2（CONTEXT-COMPACTION.md §6.16.2）：模型主动压缩（`context` 工具）在**本安全点**消费——
+  // 取用即清槽（失败不重放；重发由模型再调）；`force` 只跳过阈值早退（模型判定优先于阈值），
+  // 其余全同（同 splitHistory / 同尾部预算 / 同摘要链 / 同回注 / 同基线失效）。
+  const pending = agent._pendingCompact
+  agent._pendingCompact = null
   try {
-    if (await compressIfNeeded(agent, threshold, callbacks, compactionOverhead, signal)) {
+    let compacted = await compressIfNeeded(
+      agent, threshold, callbacks,
+      pending ? { ...compactionOverhead, force: true, focus: pending.focus } : compactionOverhead,
+      signal,
+    )
+    if (!compacted && pending) {
+      // 强制面无可压（短历史无中段）⇒ 记 no-op 注记后**照常**跑阈值面（阈值面不因模型请求让位）
+      const { compactNoopNote } = await import("../agent-tools/context.mjs")
+      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
@@ -79,6 +96,11 @@ export async function runCompactionCheck(agent, ctx) {
     // 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 (pending) {
+      // 失败注记（§6.16.2 回执面②）：模型面告知缺口——既有失败链 / 面板面零改，仅补一行机器注记
+      const { compactFailureNote } = await import("../agent-tools/context.mjs")
+      agent.history.push({ role: "user", content: compactFailureNote(errText(compressError), agent._compressFailures), transient: true })
+    }
     if (agent._compressFailures >= COMPRESS_FAILURE_LIMIT) {
       agent._compressFailures = 0
       if (compressFallback(agent)) callbacks.onCompress?.(agent._lastCompressInfo ?? {})
@@ -151,7 +173,7 @@ export async function finalizeAgentTurn(agent, ctx) {
   // driver aborts them on its own abort unwind.
   // Async subagent turn-end handling (AGENT-LOOP.md §15 D-A3 + §17 D-S1). Lifecycle:
   // - Ctrl+C (plain abort): children were aborted with the parent signal — discard dead
-  //   entries (tombstone/out-of-pool/notice — AGENT-LOOP-SUBAGENT.md §6.20; no stale
+  //   entries (tombstone/out-of-pool/notice — AGENT-LOOP-ASYNC-POOL.md §6.20; no stale
   //   errors injected — user explicitly stopped); consultation sessions are cross-turn
   //   background work since R17 — the abort branch is the ONLY normal-path place that
   //   aborts them (cleanupConsultSessions marks stopped → they never reach the digest).
@@ -205,7 +227,7 @@ export async function finalizeAgentTurn(agent, ctx) {
 }
 
 /**
- * Turn-end async subagent collection (AGENT-LOOP.md §17 D-S1 + §17.5 supersede):
+ * Turn-end async subagent collection (AGENT-LOOP-ASYNC-POOL.md §6.8 — D-S1 + suspension 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

package/agent/setup.mjs

@@ -212,6 +212,12 @@ export async function prepareRun(agent, input, callbacks, {
   // let——下方按 projectRules / skills listing 尾部追加（L326/L331 +=）再赋值；
   // const 声明会 TypeError: Assignment to constant variable（每次 run 必炸）。
   let systemPrompt = base
+  // 派单固块（台账 #23 · AGENT-LOOP-SUBAGENT.md §6.26）：spawn 级固定的机制性指令（批次档路径行 /
+  // 审计模板）随 system 面下发——固块值在 child 生命周期内恒定 ⇒ run 内前缀逐字节稳定（前缀缓存
+  // 不破），且不在 `agent.history` 内 ⇒ 压缩只重建 history（吞不掉）。拼接位 = 槽位装配之后、
+  // 项目指令之前；`_spawnSystemBlock` 为 null/undefined ⇒ 分支不进（depth-0 / explore / plan /
+  // consult 的 system 逐字节同改前）。
+  if (agent._spawnSystemBlock) systemPrompt += `\n\n${agent._spawnSystemBlock}`
 
   // Time injection deliberately does NOT live here: system prompts must be byte-identical
   // across runs (provider prefix caches). The time rides a transient user reminder per turn

package/agent/write-gate.mjs

@@ -10,9 +10,9 @@
  *    展开走 `docRootPaths`）。缺 `docRoot` 键 → `readManifest`
  *    的 fillDefaults 已补默认（架构 §2.3 E2 便利 fallback 落点）；整档缺失 / 非法 JSON →
  *    `{ok:false}` → 回退 DEFAULT_MANIFEST.docRoot（本函数是壳门之下的便利层——E2 的
- *    「整档缺失 → 拒进正常循环」由壳面 requireManifest 在启动期拦（**工程模式会话**口径——
- *    普通会话装配钩子零 manifest I/O，KD-M1-12）：CLI make-agent.mjs / VSC
- *    setup.mjs 均 fail-closed）；读错（权限等）→ 上抛不伪装成缺失（manifest.mjs 契约）。
+ *    「整档缺失」由壳面 requireManifest 按用点处置（判 + 报明 / 建档，**不抛**——
+ *    启动侧恒不拒，KD-M1-25；**工程模式会话**口径——普通会话装配钩子零 manifest I/O，
+ *    KD-M1-12）：CLI make-agent.mjs / VSC setup.mjs 同判）；读错（权限等）→ 上抛不伪装成缺失（manifest.mjs 契约）。
  *    M6 的 `advisor.mjs` design-review 分类分支消费本导出
  *    （KD-M6-1——同源不重复实现；落 dispatch.mjs 会让 advisor 反向 import 门禁簇成环）。
  * 2. `freezeWindowConflict(agent, absPaths)` —— D5 冻结窗口判据组装：被审文件集 =
@@ -37,8 +37,8 @@ const REVIEW_ROOT_KEYS = ["requirements", "specs", "design", "modules", "batches
  * 评审目标解析单点（M4 §2.1#1）：读 manifest `docRoot` → 评审对象 / 被审文件的绝对路径
  * 集合（目录级，反斜杠归一；子键值形态 = 串 | 多根数组，逐键经 `docRootPaths` 展开）。
  * 缺 `docRoot` 键 → readManifest 已补默认；整档缺失 / 非法 →
- * `{ok:false}` → 回退 DEFAULT_MANIFEST.docRoot（便利层——E2 的「拒进正常循环」由壳面
- * requireManifest 在启动期拦（**工程模式会话**口径——KD-M1-12），本函数不重复拦）；
+ * `{ok:false}` → 回退 DEFAULT_MANIFEST.docRoot（便利层——E2 的「整档缺失」由壳面
+ * requireManifest 按用点处置（判 + 报明 / 建档，**不抛**——启动侧恒不拒，KD-M1-25；**工程模式会话**口径——KD-M1-12），本函数不重复拦）；
  * 读错（权限等）→ 上抛 fail-closed。
  * @param {Object} agent
  * @returns {string[]} 评审目标目录的绝对路径（去重）

package/agent-tools/advisor-async.mjs

@@ -1,5 +1,5 @@
 /**
- * advisor-async.mjs — async advisor reviews (AGENT-LOOP-SUBAGENT.md §6.10 — R13, 2026-09-06).
+ * advisor-async.mjs — async advisor reviews (AGENT-LOOP-ASYNC-POOL.md §6.10 — R13, 2026-09-06).
  *
  * The advisor tool runs reviews in a background pool at depth 0 (default async —
  * ruling ②-3 A): the launch returns an ack, the turn ends naturally, the session
@@ -20,7 +20,7 @@
  *  3. the async pool (agent._asyncAdvisors — ADVISOR_POOL_LIMIT = 4 default,
  *     agent.poolLimits.advisor configurable — POOL-CONFIG-UNIFIED; same-scope
  *     running launches are refused at once — never queued (F-5); over-limit +
- *     DIFFERENT scope launches QUEUE (ED-4 2026-09-16 — AGENT-LOOP-SUBAGENT.md §6.10:
+ *     DIFFERENT scope launches QUEUE (ED-4 2026-09-16 — AGENT-LOOP-ASYNC-POOL.md §6.10:
  *     agent._asyncAdvisorQueue, ack {queued, position}, slot release auto-start,
  *     queued cancel dequeue+renumber — the former over-limit refusal ②-6a is
  *     retired); cancel (ruling ②-6b — directed abort → cancelled settle: no
@@ -280,7 +280,7 @@ function relayAdvisorOutput(callbacks, prefix, chunk) {
   }
 }
 
-// ─── ED-4（2026-09-16 · AGENT-LOOP-SUBAGENT.md §6.10）：评审池排队（槽释放自动起跑）────────
+// ─── ED-4（2026-09-16 · AGENT-LOOP-ASYNC-POOL.md §6.10）：评审池排队（槽释放自动起跑）────────
 
 /** 排队出队单点（ED-4）：`_asyncAdvisorQueue` 剔除目标条目 + 余项 position 按 `1..n`
  *  重编号；读面经**载体吸收**（`carrierField`——#21⑤b）：部分 parent（只携池 + `history`）
@@ -368,7 +368,7 @@ export function launchAsyncAdvisor(parent, ctx, launch) {
     const idFields = { type: reviewType, scope: scopeSummary(documents?.length ? documents : paths), round: `${(run?.round ?? 0) + 1}/uncapped`, criterion: "scope-in-flight" }
     return { error: withIdentityLine(`Advisor: 此 scope 已有评审在跑——settle 后逐个发起 — ${scopeNote}; round/prior continuation would be ambiguous while it is in flight — wait for it to settle, then launch the next review.`, idFields) }
   }
-  // ED-4（AGENT-LOOP-SUBAGENT.md §6.10）：池满 + 异 scope ⇒ 排队（非拒）——ack 含 queued +
+  // ED-4（AGENT-LOOP-ASYNC-POOL.md §6.10）：池满 + 异 scope ⇒ 排队（非拒）——ack 含 queued +
   // position；running 计数只算 running 条目（排队不占槽）。原 ②-6a 拒发退役。
   const queued = runningAdvisorCount(parent) >= limit
   parent._asyncAdvisors ??= new Map()

package/agent-tools/advisor.mjs

@@ -215,7 +215,7 @@ export const advisorTool = {
         ? "；D5 冻结窗口：被审文档（含批次档）在报告送达前零写入——在途写入会被拒绝，写入将使本轮结算为陈旧 (pass 不发 token)"
         : ""
       if (ack.queued) {
-        // ED-4（2026-09-16 · AGENT-LOOP-SUBAGENT.md §6.10）：排队 ack——模型可见状态如实 queued +
+        // ED-4（2026-09-16 · AGENT-LOOP-ASYNC-POOL.md §6.10）：排队 ack——模型可见状态如实 queued +
         // position（评审槽空自动启动——不误导模型等待即刻 digest）。
         return JSON.stringify({
           id: ack.id, kind: "advisor", status: "queued", position: ack.position,

package/agent-tools/async-discard.mjs

@@ -1,6 +1,6 @@
 /**
  * async-discard.mjs — 中止清池的「只清已死」收尾单点（批 4 CLI-ASYNC-DISCARD——CLI 侧对称；
- * 设计权威 = `docs/core/design/AGENT-LOOP-SUBAGENT.md` §6.20，需求 = `docs/core/requirements/AGENT-LOOP.md` §4.10）。
+ * 设计权威 = `docs/core/design/AGENT-LOOP-ASYNC-POOL.md` §6.20，需求 = `docs/core/requirements/AGENT-LOOP.md` §4.10）。
  *
  * 原作 = 两接线点中止分支的无差别清池（`thincoder-core/agent/run-stages.mjs` 回合尾中止 ·
  * `thincoder-cli/src/tui/suspension-drive.mjs` 挂起会话中止）——`_asyncSubagents.clear()` +

package/agent-tools/audit-block.mjs

@@ -0,0 +1,106 @@
+/**
+ * audit-block.mjs — 审计块构造器（AGENT-LOOP-SUBAGENT.md §6.26 · 台账 #23）。
+ *
+ * 自 `subagent-spawn.mjs` **逐字搬移**（D23-3 外提：spawn 档越 300 软线 + 块构造成纯函数
+ * ⇒ 判据面可直测；D23-4：块内文本零改——含块内自指词，整块搬移不改真值）。本档承载
+ * spawn 级固定机制性指令的第二块（审计模板 + A2 任务书摘要 + touched 快照）：
+ * 装配侧只收集（`thincoder-core/agent-tools/subagent-spawn.mjs`），下发面 = system 固块
+ * （`child._spawnSystemBlock` → 核 `prepareRun` 拼接——`thincoder-core/agent/setup.mjs`）。
+ */
+
+/**
+ * §18.7 D-TS5 (A2): mechanically summarize the parent spawn task book for the
+ * audit spawn — the three audit-relevant elements VERBATIM (design doc paths /
+ * affected-file list / acceptance criteria); verbose context/background is
+ * dropped (the auditor can read the design docs themselves — they stay
+ * available outside this input). Independence preserved: the input is
+ * _engTaskInput (mechanically kept by the parent spawn) — never the
+ * eng-coder's self-report. Sections are located by header marker, prioritizing
+ * header lines (structured task books: "## 文件清单 …") and falling back to
+ * inline markers (flat one-line task books); a section runs to the next header
+ * of the SAME OR HIGHER level ("## 文件清单" survives a "### 修改" sub-header).
+ * Marker not found → the section is reported as missing (never fabricate).
+ */
+export function summarizeEngTaskBook(taskInput) {
+  if (!taskInput) return "(unavailable)"
+  const SECTIONS = [
+    { name: "Design docs involved", markers: [/Docs? involved/i, /涉及文档/] },
+    { name: "Affected-file list", markers: [/Files? (?:list|to (?:modify|change)|modified)/i, /受影响文件/, /文件清单/, /涉及文件/] },
+    { name: "Acceptance criteria", markers: [/Acceptance(?: criteria)?/i, /验收标准/] },
+  ]
+  const lines = taskInput.split("\n")
+  const headerLevel = (l) => {
+    const m = l.match(/^\s*(#{1,6})\s/)
+    return m ? m[1].length : 0
+  }
+  const headerIdx = lines.map((l, i) => (headerLevel(l) > 0 ? i : -1)).filter((i) => i >= 0)
+  const boundsFor = (from, level) => {
+    for (const j of headerIdx) {
+      if (j > from && (level === 0 || headerLevel(lines[j]) <= level)) return j
+    }
+    return lines.length
+  }
+  const out = []
+  for (const { name, markers } of SECTIONS) {
+    let from = -1
+    let level = 0
+    for (const i of headerIdx) {
+      if (markers.some((m) => m.test(lines[i]))) { from = i; level = headerLevel(lines[i]); break }
+    }
+    if (from === -1) {
+      for (let i = 0; i < lines.length; i++) {
+        if (markers.some((m) => m.test(lines[i]))) { from = i; level = 0; break }
+      }
+    }
+    if (from === -1) { out.push(`${name}: (not found in the parent task book)`); continue }
+    const body = lines.slice(from, boundsFor(from, level)).join("\n").trim()
+    out.push(body || `${name}: (empty section)`)
+  }
+  return out.join("\n\n")
+}
+
+/**
+ * 审计块（spawn 级固定 ⇒ system 固块——§6.26 分类裁定表第 2 行）：纯函数——touched 快照
+ * （`ctx.agent._touchedFiles`——机制面证据，非 eng-coder 自述）+ A2 任务书摘要
+ * （`summarizeEngTaskBook(ctx.agent._engTaskInput)`）+ 指令 / 范围 / 零 git 权威 / 预算 /
+ * 报告格式五段模板**逐字**。零副作用（只读 ctx）；块内文本与搬移前逐字节一致。
+ * @param {{ agent?: { _touchedFiles?: string[], _engTaskInput?: string } }} ctx
+ * @returns {string} 块文本（不含与其它块之间的分隔符——分隔由装配侧 `join("\n\n")` 施加）
+ */
+export function buildAuditBlock(ctx) {
+  const touched = (ctx.agent._touchedFiles ?? []).map((f) => `- ${f}`).join("\n") || "- (none yet)"
+  return `[Audit scope — mechanical context, independent of the eng-coder's self-report:]\n` +
+    // §18.7 D-TS4 A1：审计指令模板（四类偏差 + 范围限制 + 校验清单格式）——审计语义
+    // 不再靠模型自悟；范围限制是 §18.5 D-AG3 声明（下方 Zero-git scope authority）
+    // 的同源一句指注，不重复声明。
+    `[Audit instructions — mechanical template:]\n` +
+    `You are auditing an eng-coder delivery against its approved design — audit for EXACTLY these four deviation categories:\n` +
+    `- PARTIAL: an acceptance criterion implemented partially or not at all;\n` +
+    `- SILENT-SIMPLIFICATION: a "simpler approximation" of a specified behavior substituted for the spec;\n` +
+    `- DOC-DRIFT: code changed without the owning design-doc section (module map / affected-files table) updated in the same delivery;\n` +
+    `- OUT-OF-LIST: changes outside the approved file list.\n` +
+    `Audit scope = _touchedFiles above UNION the files confirmed by the parent task book (single source — the Zero-git scope authority note below; NOT a second copy): ` +
+    `workspace changes not listed there are unrelated to this delivery and are NOT grounds for an out-of-list finding.\n` +
+    `Scope discipline (F-TS6 A1): read ONLY the audited files and the design-doc sections relevant to this delivery — do NOT re-read whole documents.\n` +
+    `Every deviation item MUST be fieldized: file:line + design reference (doc path + section/AC id) + severity + evidence (quoted code or doc text).\n` +
+    // §18.7 D-TS5 A2：任务书从全量 verbatim 改机械摘要块（三要素逐字——排除冗长上下文）。
+    `[Parent spawn task book — mechanical summary: design docs + affected-file list + acceptance criteria verbatim; verbose context/background dropped — the design docs are still available for reading outside this input:]\n` +
+    `${summarizeEngTaskBook(ctx.agent._engTaskInput)}\n` +
+    `Files actually touched by the eng-coder (mechanical union — audit these against the file list):\n${touched}\n` +
+    // §18.5 D-AG3（2026-09-04）：审计零 git 范围权威声明——本审计任务零 git（不注入
+    // git 上下文——§18.5 全角色零 git）；_touchedFiles 为审计范围；工作区未列于
+    // _touchedFiles 的改动与本任务无关，不作超清单依据（VS Code auditTaskBook 同款措辞）。
+    "Zero-git scope authority: this audit task receives NO git context — nothing is injected. " +
+    "The evidence base is the design documents, the current disk state (read/glob/grep), and the _touchedFiles list above. " +
+    "Workspace changes NOT listed in _touchedFiles are unrelated to this delivery — they are NOT grounds for an out-of-file-list finding." +
+    // §18.13 D-A1.2：审计预算句——A1 指令模板 + A2 摘要块之后、A3 报告模板之前（定序——评审 #7）。
+    // 逐字设计锚（D-A1.2 代码块）：只读该读的——10 轮机械预算——超时报 PROBLEM 下结论。
+    // 前导 \n 与 A3 同款块分隔约定（上一句 Zero-git 句末无换行——不触碰既有句）。
+    `\n[Audit budget — mechanical]: read ONLY the touched files listed above and the design-doc sections the parent task book names (affected-files table, acceptance criteria, status line). Do NOT read whole documents. Budget = 10 tool rounds max — if you cannot conclude within it, report PROBLEM (inconclusive) rather than continuing to explore.\n` +
+    // §18.7 D-TS6 A3：审计输出报告格式模板（三态——字段化行——不让模型自由发挥）。
+    `\n[Audit report format — mechanical template:]\n` +
+    `Report EXACTLY one of three states:\n` +
+    `- CLEAN — no deviation across the four categories: reply the line "Four deviation categories: none found." (四类偏差均未发现);\n` +
+    `- DEVIATIONS — one row per deviation, every row fieldized: | category | file:line | design reference | severity | evidence |;\n` +
+    `- PROBLEM — the audit itself could not run / inconclusive: state what blocked it.\n`
+}

package/agent-tools/batch-lifecycle.mjs

@@ -4,7 +4,8 @@
  * create（建档，§4.11）/ status（段属主状态行流转，§4.12）/ close（收口冻结，§4.13）+
  * depth-0 在飞批定位（findInFlightBatch——D-BR21）。判定字面全部单源自 batch-skeleton.mjs
  * （SEGMENT_BY_ROLE / STATUS_WORDS / STATUS_LINE_RE / readBatchStatusLine / sectionHeaderRe /
- * batchSkeleton）；路径解析单源（resolveBatchDocPath / batchDocBases）与 #84 记账缝住 batch.mjs
+ * batchSkeleton / TEMPLATE_PLACEHOLDERS / findPlaceholderResidue / placeholderResidueError）；
+ * 路径解析单源（resolveBatchDocPath / batchDocBases）与 #84 记账缝住 batch.mjs
  * 主档——**依赖单向（KD-4）：skeleton ← lifecycle ← 主档**，主档把解析后的 cwd/bases/目标闭包
  * 传进来，本档不回 import 主档（防环）。
  *
@@ -19,6 +20,7 @@ import { dirname, isAbsolute, resolve, sep } from "node:path"
 
 import {
   SEGMENT_BY_ROLE, STATUS_WORDS, STATUS_LINE_RE, readBatchStatusLine, sectionHeaderRe, batchSkeleton,
+  TEMPLATE_PLACEHOLDERS, findPlaceholderResidue, placeholderResidueError,
 } from "./batch-skeleton.mjs"
 
 /** 可读文件判据（存在且为文件——目录/缺失同判不可读；与主档同名 helper 同型——KD-4 单向
@@ -100,6 +102,8 @@ function assertInsideBases(abs, bases, raw) {
  * create——建档（§4.11，仅 depth-0）。六段骨架一次预齐（骨架模板单源 = batchSkeleton），
  * 建档即过 gate（§1 占位状态行含「进行中」）；fail-closed：非 .md / 越基底 / 目标已存在 ⇒ throw
  * （不覆盖既有批档，BR-20）；目录缺失 ⇒ mkdir -p 后落位（BR-25）。不代建台账条目。
+ * F11-B：`source` **必填**（topic 同款空拒——骨架编制行实参化；不传 = 死占位残留必被 F11-C 拒
+ * ⇒ create 即拒，不留死锁）；`prev` 传入值**幂等剥**「前情 = 」前缀（值规范化；默认值零变）。
  * @returns {string} 成功消息（含落盘绝对路径）
  */
 export function createBatchRecord({ args, ctx, review, cwd, bases, onWritten }) {
@@ -124,10 +128,20 @@ export function createBatchRecord({ args, ctx, review, cwd, bases, onWritten })
   if (!topic) {
     throw new Error("batch: create requires topic — the batch subject word shared by the record header (档名与档头共用——keep the file name aligned with it). Nothing was written.")
   }
+  const source = typeof args?.source === "string" ? args.source.trim() : ""
+  if (!source) {
+    throw new Error("batch: create requires source — the record's origin line (来源 = …). Pass where this batch came from (the request / discussion that started it); it lands in the header's 编制 line. Nothing was written.")
+  }
+  if (/\r?\n/.test(source)) {
+    throw new Error("batch: create source must be a single line — a multi-line source would break the header's 编制 line. Nothing was written.")
+  }
   const date = typeof args?.date === "string" && args.date.trim() ? args.date.trim() : todayLocal()
-  const prev = typeof args?.prev === "string" && args.prev.trim() ? args.prev.trim() : "无（独立批）"
+  // F11-B：prev 幂等 strip——调用方自带「前情 = 」前缀（单或重复）一并剥净（`+` 量词；归一化目的
+  // = 值规范化，无前缀值原样通过）。默认值形态「无（独立批）」零变。
+  const prevRaw = typeof args?.prev === "string" ? args.prev.trim() : ""
+  const prev = prevRaw ? (prevRaw.replace(/^(?:前情\s*[=：:]\s*)+/g, "").trim() || "无（独立批）") : "无（独立批）"
   mkdirSync(dirname(abs), { recursive: true })
-  writeFileSync(abs, batchSkeleton({ date, topic, prev }))
+  writeFileSync(abs, batchSkeleton({ date, topic, source, prev }))
   onWritten?.(ctx?.agent ?? {}, abs)
   return `batch: created ${abs} — six-section skeleton written (§1 status line carries the gate-legal 「进行中」 placeholder; register the ledger entry yourself — create does not).`
 }
@@ -168,30 +182,65 @@ function assertGateOpen(src) {
   }
 }
 
-/** status 值域校验（fix 轮 #1 + 词面纪律）：值在**全词表 union**（各段项去重并集——含他段
- *  生命周期词与 §1 gate 词对）中必须恰命中一个关键字，且该关键字属于本段词表项——0 个 ⇒ 词表外
- *  拒；≥2 个 ⇒ 混词拒；唯一命中不属本段 ⇒ 词表外拒（该段值域不含）。「进行中…已收口」双词无论
- *  写哪段皆拒（最小词面：已收口优先误冻结防线——2026-09-20 词面纪律）。 */
+/** 全词表去重并集（各段项——value 命中判据与 note 零命判据共用同一口径）。 */
+function statusVocabulary() {
+  return [...new Set(Object.values(STATUS_WORDS).flatMap((w) => Object.values(w)))]
+}
+
+/** 状态行值装饰白名单（F11-A 谓词收紧）：首尾非字母数字符号（emoji / 标点 / 空白）+ 尾部
+ *  ISO 日期（YYYY-MM-DD）+ 首尾空白。剥白名单后**余核必须逐字等于**该关键词——余核 ≠ 关键词
+ *  （散文内嵌）⇒ 拒（散文说明走独立 `note` 字段落括注）。
+ *  读侧（gate）零变：`readBatchStatusLine` / `assertGateOpen` 仍子串包含——冻结门语义不动；
+ *  收紧只在写入面 value。 */
+const LEAD_DECOR_RE = /^[^\p{L}\p{N}]+/u
+const TAIL_DECOR_RE = /[^\p{L}\p{N}]+$/u
+const ISO_TAIL_RE = /\d{4}-\d{2}-\d{2}\s*$/
+function stripDecorations(value) {
+  return value.replace(LEAD_DECOR_RE, "").replace(ISO_TAIL_RE, "").replace(TAIL_DECOR_RE, "")
+}
+
+/** status 值域校验（fix 轮 #1 + 词面纪律 + 本批 F11-A 谓词收紧）：值在**全词表 union**中必须恰
+ *  命中一个关键字（判读序不动：≥2 命中 ⇒ 混词拒在前；0 命中 / 唯一命中不属本段 ⇒ 词表外拒），
+ *  且剥装饰白名单后**余核逐字 = 该关键词**（余核 ≠ 关键词 = 散文内嵌 ⇒ 词表外拒同串）。
+ *  「进行中…已收口」双词无论写哪段皆拒（最小词面：已收口优先误冻结防线——2026-09-20 词面纪律）。 */
 function assertStatusValue(seg, value) {
   const words = Object.values(STATUS_WORDS[seg] ?? {})
   if (!words.length) {
     throw new Error(`batch: §${seg} has no status word list — status is undefined for this section (STATUS_WORDS 分段词表无该项). Nothing was written.`)
   }
-  const vocabulary = [...new Set(Object.values(STATUS_WORDS).flatMap((w) => Object.values(w)))]
-  const hits = vocabulary.filter((w) => value.includes(w))
-  if (hits.length === 0 || (hits.length === 1 && !words.includes(hits[0]))) {
-    throw new Error(`batch: status value ${JSON.stringify(value)} is not in the legal keyword set for §${seg} (${words.join(" / ")}) — STATUS_WORDS 分段词表是唯一值域（D-BR19）. Nothing was written.`)
-  }
+  const hits = statusVocabulary().filter((w) => value.includes(w))
   if (hits.length > 1) {
     throw new Error(`batch: status value contains multiple keywords (${hits.join(" + ")}) — one status line carries exactly ONE keyword (词面纪律: mixed values mis-freeze via 已收口-priority). Nothing was written.`)
   }
+  if (hits.length === 0 || !words.includes(hits[0]) || stripDecorations(value) !== hits[0]) {
+    throw new Error(`batch: status value ${JSON.stringify(value)} is not in the legal keyword set for §${seg} (${words.join(" / ")}) — STATUS_WORDS 分段词表是唯一值域（D-BR19；合法值 = 恰一关键词 + 装饰白名单〔首尾符号 / 尾部 ISO 日期 / 空白〕，散文说明走 note 字段落括注）. Nothing was written.`)
+  }
+}
+
+/** status `note` 字段校验（F11-A——落盘形态 = 状态行行内括注）：单行 + **全词表零命中**
+ *  （括注永不误触冻结门——§1 判定是子串包含；已收口优先误冻结防线的第二道）+ 死占位判据零命中
+ *  （括注不得成为骨架占位的新驻留面）。 */
+function assertStatusNote(note) {
+  if (/\r?\n/.test(note)) {
+    throw new Error("batch: status note must be a single line — a multi-line note would break the one-line status-line form. Nothing was written.")
+  }
+  const hits = statusVocabulary().filter((w) => note.includes(w))
+  if (hits.length) {
+    throw new Error(`batch: status note must not contain any STATUS_WORDS keyword (${hits.join(" + ")}) — a parenthetical carrying a keyword would be read as gate truth (§1 substring predicate). Put the keyword in value, the prose in note. Nothing was written.`)
+  }
+  const residues = TEMPLATE_PLACEHOLDERS.filter((ph) => note.includes(ph))
+  if (residues.length) {
+    throw new Error(`batch: status note must not carry skeleton placeholders (${residues.join(" · ")}) — fill them in the record header instead of parking them in the status line. Nothing was written.`)
+  }
 }
 
 /**
  * status——状态行流转（§4.12，段属主）。写域 = 调用者自己段内 `**状态行**：` 行（eng-designer →
  * §2 · 评审 → §3 · eng-coder → §5 · 主 agent → §1——轮 2 #3 裁定②）；值域 = STATUS_WORDS 该段项
- * 恰一词；冻结真值不变（gate 只读 §1）。path 参数 = 仅 depth-0（D-BR21）——子代理/评审传 path
- * ⇒ 拒（目标 = spawn/实例注入，语法上写不到别处）。
+ * 恰一词（**余核 = 关键词**——F11-A 谓词收紧），散文说明走独立 `note` 字段（落状态行括注）；
+ * 冻结真值不变（gate 只读 §1）。path 参数 = 仅 depth-0（D-BR21）——子代理/评审传 path
+ * ⇒ 拒（目标 = spawn/实例注入，语法上写不到别处）。F11-C 挂点 = 写盘前（assertStatusValue 后）：
+ * 档头 / 目标段含骨架死占位 ⇒ 拒（close 不拦——收口是主 agent 终态动作）。
  * @returns {string} 成功消息
  */
 export function statusBatchRecord({ args, ctx, review, pickTarget, onWritten }) {
@@ -216,14 +265,21 @@ export function statusBatchRecord({ args, ctx, review, pickTarget, onWritten })
   if (/\r?\n/.test(value)) {
     throw new Error("batch: status value must be a single line — a multi-line value would break the one-line status-line form. Nothing was written.")
   }
+  // note（可选）：散文说明的承载面——落状态行行内括注（value 内散文不再容忍）。缺省 / 空串 = 无括注。
+  const note = typeof args?.note === "string" ? args.note.trim() : ""
   assertStatusValue(seg, value)
+  if (note) assertStatusNote(note)
+  const lineValue = note ? `${value}（${note}）` : value
   const abs = pickTarget(args?.path)
   const src = readFileSync(abs, "utf8")
   assertGateOpen(src)
-  const written = updateSectionStatusLine(src, seg, value)
+  // F11-C（写盘前）：档头 + 本段死占位残留 ⇒ 拒（他段占位不归本段作者管）
+  const residues = findPlaceholderResidue(src, seg)
+  if (residues.length) throw new Error(placeholderResidueError(residues))
+  const written = updateSectionStatusLine(src, seg, lineValue)
   writeFileSync(abs, written)
   onWritten?.(ctx?.agent ?? {}, abs)
-  return `batch: §${seg} status line updated to ${JSON.stringify(value)} — the freeze gate (§1) is a read-only domain for non-§1 writes (frozen truth stays = the §1 line).`
+  return `batch: §${seg} status line updated to ${JSON.stringify(lineValue)} — the freeze gate (§1) is a read-only domain for non-§1 writes (frozen truth stays = the §1 line).`
 }
 
 /**