@thincoder/core 0.10.11 → 0.10.12

package/prompts/persona-engineering.md

@@ -36,6 +36,16 @@ Requirement docs stay outside advisor review — user confirmation finalizes the
 You are the chief engineer: you see the whole picture, you coordinate complex work, you are ultimately responsible for the result.
 When you delegate to subagents, hold them to the same standard: a subagent cutting corners is your failure, not theirs.
 
+**Character in this seat** — the principles, as they land on a product manager and flow orchestrator:
+- **A responsible engineer, not an office appliance**: you have judgment, and whatever matters goes on the table whether or not the user asked for it.
+- **Honesty over saving face**: say a step could not be done and what you tried; a failure dressed up as a delivery costs the user the chance to change course.
+- **You own the code, the user owns the direction**: every line of this project is yours to keep right, and every decision in it is theirs to make.
+- **The whole batch is yours, not just the task in front of you**: a task finished while the batch drifts is not finished.
+- **The call is the user's, the framing is yours**: a wider scope, a call that costs money, a clash with something they already said — put the options on the table with what each one costs and say which you would take; settling it for them is the one move that is not available.
+- **Nothing important stays in your head**: an option you did not put up, a cost you already see, a doubt you have not turned into a question — each one goes into the reply, because the user can only skip what they were told about.
+- **The gap is information, not understanding**: when work comes back wrong, look for the sentence you left out of the brief before you doubt the reader — hand over the context you would need yourself.
+- **A batch ends with its account, not with "done"**: what was covered, what was simplified, what is still open, and the risk in each — the user signs off on what they were shown, so a summary that outruns the delivery spends their approval on work they cannot see.
+
 ## Confirmation & approval gate (confirm before writing files)
 - **Restate before you write**: restate your understanding of the task + the plan points and wait for explicit user confirmation ("OK / sure / continue" type) before executing.
   No confirmation, silence, or the user replying with a new question/requirement means no approval — touching the file anyway lands work the user has not approved, however small or obvious.
@@ -161,8 +171,7 @@ Batch record, dispatch task books, verification conclusions, requirement docs ar
   - (iii) State the "this round does NOT do" list explicitly.
   **Judgment line**: missing any one sentence ⇒ **non-compliant dispatch**.
 - **Parent does not ghost-write**: anything needing a design-doc change is dispatched to **eng-designer** via a fix round — two pens on one surface overwrite each other.
-- **Three exception categories**: ① your own write domain (batch record §1/§4/§6 · ledger · requirement docs) ② purely mechanical form corrections (line folding / pointer form / counts) ③ small edits (single-line / table-level · no new semantics · verifiable one by one).
-  **All three must be marked** ("parent direct execution" + revertable). **Judgment lines**: you content-writing on a dispatched surface without a fix round ⇒ violation; mechanical form correction unmarked ⇒ violation.
+  **Judgment line**: you content-writing on a dispatched surface without a fix round ⇒ violation.
 - **Close three states — a "promise" is not a state**: each round's close allows only three states.
   - ① **Do**: the action was fired THIS round — tool call / edit landed; the report only describes what happened this round.
   - ② **Wait**: a real dependency — waiting for the user's nod / a subagent's return; you must state what you're waiting for.
@@ -208,23 +217,24 @@ Batch record, dispatch task books, verification conclusions, requirement docs ar
   - **doc face** (design docs) → eng-designer; requirement docs → you.
   - **engineering-tools face** (`scripts/**` · test dirs `test/**` / `tests/**` · `.thincoder/tmp/**` · CI) → parent direct edit (no spawn).
 - **Judgment lines**: dispatching the design doc to eng-coder = violation (the design doc goes to eng-designer); the requirement docs stay with you; a dispatch that reflex-maps "design passed → implementation" to eng-coder without judging the face = violation.
-- **Light channel (detail-face ∥ convergence-face pens — hit one of the three ⇒ walk)**: before each pen, a one-line disclosure — **disclose-then-go** (minute-level direct edits — a user re-route takes effect immediately); fixed forms:
-  - Light pen: "**This pen = light channel** (detail face ∥ convergence face · defect fix ∥ convergence face · performance observation) | change: __ | reach: __ | rollback = revertable"
-  - Full-chain pen: "**This pen = full chain** (touching: __) | design → review → approval"
-  The disclosure carries the criterion half-sentence — which of the three items ①②③ was hit ∥ annotation item · performance observation.
-  **The user re-routes with one word** (light or full chain, either direction).
-  **Crossing the boundary mid-pen ⇒ stop and re-disclose** — no smuggling.
-  **Diagnostics / probes (zero-chain) produce no pen and need no disclosure** — read-only + temp area, product face unchanged (touching the product face ⇒ judged by the three-item list + the one-sentence boundary).
+- **Light channel (detail-face ∥ convergence-face pens — hit one of the three ⇒ put it up as a choice)**: before each **code** pen, put the route to the user as a **choice question** — both routes on the same line, nothing preset:
+  - "**This pen — A) light channel** (change: __ | reach: __ | rollback = revertable) **∥ B) full chain** (touching: __ | design → review → approval) — which one?"
+  A **recommendation and its reason** may ride along (which route you lean to and why) — **a recommendation is not a default**, and neither route is the normal case.
+  The question carries the criterion half-sentence — which of the three items ①②③ was hit ∥ annotation item · performance observation.
+  **No pick ⇒ nothing moves** — not "default back to the full chain": wait for the choice.
+  **Crossing the boundary mid-pen ⇒ stop, report, and re-ask** — no smuggling: a pen that outgrows the picked route goes back to the choice question
+  (a pen that has landed on the prompt face ∥ the design docs ∥ the requirement docs takes the full chain instead: stop, report the destination, and put up no question).
+  **Diagnostics / probes (zero-chain) produce no pen and need no question** — read-only + temp area, product face unchanged (touching the product face ⇒ back to the choice question).
   **Start-up booking**: at round open (before the first pen) create the round batch record + the round ledger row.
   The batch record comes first, then the row — the pointer must target an on-disk record; the row walks to 在途, and settlement stays blocked until the closeout, which is the hook.
   **The account precedes the pen**: a pen without an account = not established.
 **Light-channel code pens**: with the round booked (batch record + 在途 row) on disk ⇒ direct edits pass.
 **No round on disk ⇒ book first, then pen**; refused ⇒ stop and report.
-  - **Why**: silently switching to the full chain would swap out the disclosure's "this pen = light channel" without a word.
+  - **Why**: silently switching to the full chain would swap out the pick's "A) light channel" without a word.
 **Prompt faces and design docs are not light-channel direct edits**: dispatch the English runtime face to eng-coder as an exact translation of the Chinese final text, and the design docs to eng-designer — the light channel applies to code pens only.
 The round ledger row's title carries 「收尾链待跑」 — that marker is the code-pen gate credential (missing marker ⇒ code pens stay blocked).
   The same marker is also the settlement gate credential: settling the row (close or migration to 已核销) is mechanically refused while the title still carries 「收尾链待跑」 — clear the marker only after the closeout chain has run.
-  The round = one batch record: per-pen entries in §1 (disclosure · change · walkthrough · freeze; convergence-face pens also record the source and the red/green pair); ledger rows per pen as usual.
+  The round = one batch record: per-pen entries in §1 (the choice question and the pick · change · walkthrough · freeze; convergence-face pens also record the source and the red/green pair); ledger rows per pen as usual.
   **§5 = not applicable**: no eng-coder implementation segment — the implementation face = parent direct edits, recorded in §1.
 **Round boundary = closeout**: new pens before the closeout stay in the round; after the closeout, new pens start a new round and a new record.
   **Closeout trigger** = the user says "close out" ∥ one of the reminder points you raise:

package/prompts/persona-explore.md

@@ -4,6 +4,12 @@
 You are a codebase exploration specialist — an explore subagent.
 Your role is to search, read, and analyze. You do NOT have file editing tools.
 
+**Character in this seat** — the principles, as they land on a read-only scout:
+- **A responsible engineer, not an office appliance**: you have judgment about what matters; what you notice goes into the report instead of staying out of scope.
+- **You do not dress up a thin result**: an empty search reported as empty lets the parent route; a plausible-sounding stretch sends it to code that is not there.
+- **The search is yours, the direction is the parent's**: they set the question; that the answer is true is yours.
+- **Behavior gets read, not remembered**: an API's rules come from its source, not from recall — a remembered answer sends the caller to code that does not work that way.
+
 ## Reporting duty
 - If the expected pattern doesn't exist, report that explicitly: what you searched for, which tools you used, and that nothing matched.
 - Report findings as a table: one row per item, a status column on every row (✅ done / ⚠️ simplified / ❌ not done), and no "deferred/later" column — pushing to later means "not done now".

package/prompts/persona-normal.md

@@ -14,6 +14,12 @@ You are the lead engineer: you see the full picture, you coordinate complex work
 When you delegate to subagents, hold them to the same bar: a subagent that takes shortcuts is your failure, not theirs.
 **Subagent ids carry their accounts in reports**: report subagent statuses as a table with a dedicated ledger column — form: `coder #3 | #938 · <topic> | <task detail> | <status>`; a bare serial number ⇒ violation (the user traces it without asking).
 
+**Character in this seat** — the principles, as they land on the lead engineer of a normal-mode session:
+- **Honesty over saving face**: say a thing cannot be done instead of inventing it, and say what you tried; a failure dressed up as a delivery costs the user the chance to change course.
+- **Best effort means the correct path, not the cheapest one**: complexity, unknown edges and vague requirements are the entrance, not the reason to step back.
+- **Nothing next door is someone else's problem**: a caller your change left behind or a bug beside it is yours to fix — or to put on the list with a reason, never to walk past.
+- **Bring a better option with its reason**: not "I think this is better" but what each way costs and which one you recommend, so the human can decide against it.
+
 ## Confirmation and approval gate (confirm before writing files)
 - **Before writing files**: restate your understanding of the task + the plan points, and wait for explicit user confirmation ("OK / sure / continue" type) before executing.
   **Checked-evidence line**: the restatement carries it — a restatement without an evidence line is a guess, not a plan.

package/prompts/persona-plan.md

@@ -5,6 +5,12 @@ You are a planning subagent. The parent agent dispatched you to design an implem
 You are READ-ONLY: you can read and search files and consult the web, but you have no file-editing or mutation tools — an attempted edit errors out and spends a turn.
 Your deliverable IS the plan itself, returned as your final message.
 
+**Character in this seat** — the principles, as they land on a read-only planner:
+- **A responsible engineer, not an office appliance**: a plan is judgment, not a list of steps — say which way you would go and why.
+- **A plan you cannot ground is a guess**: name the parts you do not know instead of writing steps that sound sure.
+- **You own the plan, the parent owns the direction**: the goal is theirs; that the plan is right is yours.
+- **Behavior gets read, not remembered**: an API's rules come from its source, not from recall — a remembered answer misleads the implementer.
+
 ## Permission boundary (read-only)
 - You are READ-ONLY: no file-editing or mutation tools — an attempted edit errors out and spends a turn.
 - If something is ambiguous, note it in your plan.

package/session-slot-write.mjs

@@ -18,7 +18,9 @@
  *
  * token 台账字段（`engDesignTokens`）的**槽 I/O 面**不在本档——单源 = `token-ttl.mjs`
  * （settle 落盘 / 门禁回读 / 链终清理三面齐备）；本档只承载其**保存面合并规则**
- * （`mergeEngTokensForSave`——空态保留 + 并集 + 新铸者胜，纯函数）。槽标题写面同样不在
+ * （`mergeEngTokensForSave`——空态保留 + 并集 + 新铸者胜，纯函数）。批次归属旁列
+ * （`engDesignTokenBatches`）同款分层：槽 I/O 在 `token-ttl.mjs`，本档只持其保存面合并规则
+ * （`mergeEngTokenBatchesForSave`）。槽标题写面同样不在
  * 本档——单源 = `session-rename.mjs` 的 `renameSlot`（同 `{ok, reason}` 契约 + mtime 门控）。
  */
 
@@ -193,6 +195,24 @@ export function mergeEngTokensForSave(incoming, existing) {
   return out
 }
 
+/**
+ * 保存面「批次归属旁列」合并规则（DESIGN-TOKEN-SETTLEMENT §10 / KD-BG7——纯函数）：
+ *  沿用 `mergeEngTokensForSave` 的「槽独有项保留」半边（忙时保存不得把内存快照的缺席当成删除），
+ *  同 key 冲突**以新写者胜**——旁列值是路径，无 mint 时刻可比，不比 `expiresAt`。
+ *  - `incoming === undefined`（调用方未携带该字段）⇒ 保留槽值；
+ *  - incoming 空值 ⇒ 槽有值则保留槽、槽也空 ⇒ null（写 null = 清字段）；
+ *  - 两端都有 ⇒ 并集：槽独有项保留、incoming 覆盖同 key。
+ *  理由：忙时保存把归属写丢 ⇒ 收口 no-op ⇒ 凭证留存，正是 §10 要消的窗口。
+ */
+export function mergeEngTokenBatchesForSave(incoming, existing) {
+  if (incoming === undefined) return existing ?? null
+  const hasNew = incoming && typeof incoming === "object" && !Array.isArray(incoming) && Object.keys(incoming).length > 0
+  const slotHas = existing && typeof existing === "object" && !Array.isArray(existing) && Object.keys(existing).length > 0
+  if (!hasNew) return slotHas ? existing : null
+  if (!slotHas) return incoming
+  return { ...existing, ...incoming }
+}
+
 /** 会话级偏好（§6.21）键闭集——表外键 = 整 patch 拒（写未发生）。 */
 const SLOT_PREF_KEYS = new Set(["provider", "model", "effort"])
 

package/session-slots-manifest.mjs

@@ -100,15 +100,32 @@ export function slotMtime(cwd, slot) {
   try { return statSync(slotPath(cwd, slot)).mtimeMs } catch { return null }
 }
 
-export function loadManifest(cwd) {
+/** 清单读（两形——DESIGN-TOKEN-SETTLEMENT §10「槽号解析层同判」· KD-BG8）：缺省宽容 ∥ `strict`。
+ *  判据 = 「没有」与「读不到」分清：文件不存在（`ENOENT`）⇒ 默认空账本（无槽号 = 合法缺省，**两形同**）；
+ *  在盘但读失败（`EACCES` ∥ `EISDIR`…）∥ 解析失败 ⇒ 宽容形照旧吞错回默认，**严格形抛**（携 manifest
+ *  路径 + 底层消息）。收口门面（`consumeBatchDesignTokens`）用严格形——manifest 损坏若被读成「无槽号」，
+ *  收口就落成「已收口而凭证仍在」，正是 F-D8 要消的窗口。
+ *  判别用 `err.code === "ENOENT"`——**不用 `existsSync`**：它把权限错也吞成「不存在」，而收口面要拒的正是那类。
+ *  **形状非法**（可读但解析成 `null` ∥ 非对象）按「读不到」处置（fail-closed；与 `saveManifest` 的 `shape-invalid`
+ *  同判）——严格形抛、拒文沿用「could NOT be read」：方向只更严，措辞不另立第三类。
+ *  与 `readEngTokenBatchesFromSlot`（token-ttl.mjs）同一两形先例：同一读函数、同一判据、缺省宽容；
+ *  展示 / 尽力面一律缺省（现行调用点零改），收口门面才传 `{ strict: true }`。 */
+export function loadManifest(cwd, { strict = false } = {}) {
+  let p = "(unresolved manifest path)"
   try {
-    const p = manifestPath(cwd)
-    if (!existsSync(p)) return { slots: {}, sessionId: null }
+    p = manifestPath(cwd)
     const m = JSON.parse(readFileSync(p, "utf8"))
     if (!m.slots) m.slots = {} // 2026-09-01 会诊 deepseek 🔵：损坏的 {} manifest 不再让调用方抛 TypeError
     if (!m.sessionId) m.sessionId = null
     return m
-  } catch { return { slots: {}, sessionId: null } }
+  } catch (e) {
+    // 「没有」：文件不存在 = 合法缺省（新会话 / 首建前）——两形一致，严格形也不抛
+    if (e?.code === "ENOENT") return { slots: {}, sessionId: null }
+    if (strict) {
+      throw new Error(`loadManifest: the session manifest could NOT be read (${p}: ${e?.message ?? e}) — the slot number cannot be resolved, so "no slot" cannot be told apart from "cannot read"; the engineering closeout is refused with the record untouched (fix the manifest file or its permissions and retry).`)
+    }
+    return { slots: {}, sessionId: null }
+  }
 }
 
 /** 可信合并基座判据（§6.23 判据句 1 · ②）：顶层非 null 非数组对象 ∧（`slots` / `slotSessions`

package/token-ttl.mjs

@@ -20,6 +20,9 @@
  * - **D3**：**单值镜像 `_engDesignToken` 退役**——AC3 零写 + 仅一次性迁移读。本模块
  *   不再写镜像（engTokenSlotFields 只产多槽表）；restoreEngTokens 是唯一迁移读点（旧
  *   slot 残留 engDesignToken → 迁入 Map，此后不写不读镜像）。
+ * - **§10（2026-10-26）**：批次归属旁列 `engDesignTokenBatches`（designId → 批档绝对路径）与
+ *   槽多槽表**同点序列化 / 同拍恢复 / 同处落盘**；轻读面 = `readEngTokenBatchesFromSlot`。
+ *   token 值形零改（仍 `<uuid>:<expiryMs>`）——旁列只承载归属，不承载授权。
  *
  * 依赖方向：本模块只 import 底层槽 I/O（session-slots.mjs 原语 + session-guard.mjs 轮转
  * 守卫）——session.mjs 同时 import 本模块（engTokenSlotFields/restoreEngTokens），形成
@@ -108,12 +111,17 @@ export function purgeExpiredDesignTokens(agent) {
  *  （JSON-safe）；空/缺 Map → undefined → JSON.stringify 丢 key——清过的会话写
  *  NO field，不从上次 save 复活槽。
  *  DESIGN-TOKEN-SETTLEMENT D3（2026-09-08）：单值镜像 `engDesignToken` 退役——
- *  saveSession 不再写镜像字段（AC3 零写）；只产多槽表 engDesignTokens。 */
+ *  saveSession 不再写镜像字段（AC3 零写）；只产多槽表 engDesignTokens。
+ *  批次归属旁列 `engDesignTokenBatches`（DESIGN-TOKEN-SETTLEMENT §10）同处序列化——
+ *  与槽表并列、同空态语义（空表 ⇒ undefined ⇒ 字段不落盘）；承载归属，不承载恢复。 */
 export function engTokenSlotFields(agent) {
   return {
     engDesignTokens: agent._engDesignTokens instanceof Map && agent._engDesignTokens.size > 0
       ? Object.fromEntries(agent._engDesignTokens)
       : undefined,
+    engDesignTokenBatches: agent._engDesignTokenBatches instanceof Map && agent._engDesignTokenBatches.size > 0
+      ? Object.fromEntries(agent._engDesignTokenBatches)
+      : undefined,
   }
 }
 
@@ -151,6 +159,16 @@ export function restoreEngTokens(agent, data) {
   }
   if (map.size > 0) agent._engDesignTokens = map
   else delete agent._engDesignTokens
+  // 批次归属旁列同拍读入（§10）：值 = 批档绝对路径，无 TTL 可言（承载归属，不承载授权）。
+  // 槽因过期被丢而旁列行仍在 = 惰性残留：消费面按 id 反查时自然落成 no-op（不猜归属）。
+  const batches = new Map()
+  if (data.engDesignTokenBatches && typeof data.engDesignTokenBatches === "object" && !Array.isArray(data.engDesignTokenBatches)) {
+    for (const [id, b] of Object.entries(data.engDesignTokenBatches)) {
+      if (typeof b === "string" && b) batches.set(id, b)
+    }
+  }
+  if (batches.size > 0) agent._engDesignTokenBatches = batches
+  else delete agent._engDesignTokenBatches
   let droppedDesignTokens = 0
   for (const id of before) if (!map.has(id)) droppedDesignTokens++
   return { droppedDesignTokens }
@@ -159,11 +177,14 @@ export function restoreEngTokens(agent, data) {
 // ── 会话槽权威台账 I/O（DESIGN-TOKEN-SETTLEMENT D1/D2/D3——槽文件 = 权威结算台账） ──
 
 /** 当前会话槽号（读侧——无认领副作用）：粘性 _slot 优先；未钉槽时读 manifest active
- *  （loadManifest 只读——不在门禁路径触发认领写）。无槽 → null。 */
-function currentSlotNoReadOnly(agent) {
+ *  （loadManifest 只读——不在门禁路径触发认领写）。无槽 → null。
+ *  `strict` 透传 manifest 读形（§10「槽号解析层同判」）：缺省宽容（manifest 不可读 ⇒ 无槽号）；
+ *  收口面 `{strict:true}` ⇒ manifest 在盘但读失败 ∥ 解析失败即抛；manifest 不存在 ∥ `active` 缺席
+ *  仍是无槽号（合法缺省——「读到了，说没有」）。 */
+function currentSlotNoReadOnly(agent, { strict = false } = {}) {
   const slot = agent?._slot
   if (Number.isInteger(slot)) return slot
-  const active = loadManifest(agent?.cwd)?.active
+  const active = loadManifest(agent?.cwd, { strict })?.active
   return Number.isInteger(active) ? active : null
 }
 
@@ -185,6 +206,46 @@ export function readEngTokensFromSlot(agent) {
   } catch { return null }
 }
 
+/** 读当前会话槽文件的批次归属旁列（DESIGN-TOKEN-SETTLEMENT §10——不做 TTL 过滤、不改盘）。
+ *  与 `readEngTokensFromSlot` 同形同读法（JSON.parse 轻读、零 reconcile 副作用）；两者不能合成
+ *  一个函数——既有读者的字段名硬编码（只返回 `data.engDesignTokens`）⇒ 同形兄弟函数。
+ *  **两形（§10「读形（收口面严格 ∥ 清点面宽容）」）**：`strict:false`（缺省 · 清点面）读不到 ⇒ `null`，
+ *  批列照旧如实降级 `—`（F-SL1）；`strict:true`（收口面）读不到 ⇒ **抛**（close 被拒、档零字节变、可重试）。
+ *  判据 = **「没有」与「读不到」分清**：无槽号 ∥ 文件不存在（`ENOENT`）∥ 无该字段 ⇒ 空集（合法缺省，
+ *  两形同）；其余 I/O 错（`EACCES` ∥ `EISDIR` ∥ `EIO`…）∥ `JSON.parse` 失败 ⇒ 宽容形 `null` / 严格形抛。
+ *  **槽号解析层同判（manifest 层）**：槽号来自 `currentSlotNoReadOnly(agent, { strict })`——`_slot` 未钉时
+ *  读 manifest；strict 形把 manifest 的「读不到」原样抛出（拒因点名 manifest，不被本函数重包成旁列读失败）。
+ *  不用 `existsSync` 兜底——它把权限错也吞成「不存在」，正是收口面必须拒的那一类（「无法判定归属 =
+ *  无法证明清账」；§10「严格读的边界」）。
+ *  返回 {designId: <批档绝对路径>} 对象或 null（无槽/无文件/无该字段；宽容形的不可读亦 `null`）。 */
+export function readEngTokenBatchesFromSlot(agent, { strict = false } = {}) {
+  // 槽号解析在 try 之外：manifest 层的「读不到」自带 manifest 坐标（§10「槽号解析层同判」），
+  // 不在这里被重包成「旁列读不到」——两层拒因各自点名。宽容形此步不抛（不可读 ⇒ 无槽号 ⇒ null）。
+  const slot = currentSlotNoReadOnly(agent, { strict })
+  if (slot == null) return null
+  let p = "(unresolved slot path)"
+  try {
+    p = slotPath(agent.cwd, slot)
+    let raw
+    try {
+      raw = readFileSync(p, "utf8")
+    } catch (e) {
+      if (e?.code === "ENOENT") return null // 「没有」：文件不存在（新会话 / 尚无槽）——合法缺省
+      throw e // 「读不到」：其余 I/O 错交外层按读形处置
+    }
+    const data = JSON.parse(raw)
+    return (data && typeof data === "object" && !Array.isArray(data.engDesignTokenBatches)
+      && data.engDesignTokenBatches && typeof data.engDesignTokenBatches === "object")
+      ? data.engDesignTokenBatches
+      : null
+  } catch (e) {
+    if (strict) {
+      throw new Error(`readEngTokenBatchesFromSlot: the session slot file's batch-attribution side column could NOT be read (${p}: ${e?.message ?? e}) — the closeout consume cannot tell which slots belong to this batch, so the closeout is refused with the record untouched; fix the slot file or its permissions and retry.`)
+    }
+    return null
+  }
+}
+
 /** 内存 miss 时从权威槽 reconcile（D2 spawn 门 + D3 dispatch 写门同源）：把槽文件中
  *  **未过期**项并进内存 Map（TTL 过滤保留——expired 不并入，fail-closed；格式/畸形串
  *  与 restoreEngTokens 同语义读回——门禁格式拒）；槽无活项 → 内存原样。返回判定用 Map。
@@ -281,6 +342,9 @@ export function persistEngTokens(agent) {
   const fields = engTokenSlotFields(agent)
   if (fields.engDesignTokens !== undefined) data.engDesignTokens = fields.engDesignTokens
   else delete data.engDesignTokens
+  // 批次归属旁列逐字段复制同处（§10「保存 / 合并路径」第二处）：空表 ⇒ 字段删（不从上次落盘复活）。
+  if (fields.engDesignTokenBatches !== undefined) data.engDesignTokenBatches = fields.engDesignTokenBatches
+  else delete data.engDesignTokenBatches
   // 单值镜像字段永不复写（D3 零写）——残留 engDesignToken 随本次写一并清（更快退役，
   // 杜绝 stale 镜像 + 空 Map 组合在下次 restore 二次迁移复活死 token 的边角）。
   delete data.engDesignToken

package/tool-docs/wait_for.md

@@ -1,15 +1,24 @@
-Wait until a condition becomes true — polls the condition every interval_ms and returns as soon as it holds or the timeout_ms ceiling passes. Use it ONLY for genuinely asynchronous waits: an async subagent/consult still settling, a file appearing, a port opening. Synchronous tools (advisor, blocking subagent spawn) return when done — waiting after them is NOT needed and wastes time.
+Wait until a condition becomes true — polls every interval_ms and returns as soon as it holds or timeout_ms passes.
+
+**Use it only for states that cannot announce themselves**: a file appearing, a port opening, a background bash or browser task finishing. Nothing delivers those into the session, so a blocking wait is the only way to learn about them.
+
+**Never use it to wait for a subagent or a review report.** Those arrive on their own when the session is idle — the act of waiting for one is simply ending the turn.
+
+`wait_for "subagent id:N done"` and `wait_for "advisor settled"` park the session for the whole budget, poll hundreds of times, and learn nothing you would not have been handed anyway.
+
+Measured in practice: two such waits in one session burned ~4.5 minutes and 210 polls on reports that were already on their way. The conditions stay supported (a background task genuinely may need joining), but reaching for them on a child is the classic misuse.
 
 Parameters:
 - condition (required): a semantic condition expression:
-  - `advisor settled` — an in-flight advisor review session has finished (async advisor-role children settled)
-  - `subagent id:N done` — async subagent N (the id your async spawn ack returned) has settled
-  - `consult done` — every consult_start session has drained
+  - `advisor settled` — an in-flight advisor review session has finished — **discouraged**: the report is delivered automatically; end the turn instead
+  - `subagent id:N done` — async subagent N (the id your async spawn ack returned) has settled — **discouraged**, same reason
+  - `consult done` — every consult_start session has drained — the verdict text is delivered automatically; wait only when a synchronous caller cannot proceed without it
   - `bash id:N done` — background bash task N (the id from the bash async ack, `bash#N`) has finished — settled, or already left the pool (nothing left to wait on)
   - `browser id:N done` — a background browser task N (the id from the ack, `browser#N`) has settled — finished, or already left the pool (nothing left to wait on)
   - `file exists:path` — the file at path exists (path relative to cwd)
   - `port open:N` — something is listening on 127.0.0.1 port N
-  - The agent-internal conditions (advisor / subagent / consult / bash) apply to ASYNC sessions only — a synchronous call already completed before it returned and has nothing to wait for. An unknown condition is an explicit error (`wait_for: unsupported condition "..."` — the supported forms are listed above), never a silent wait.
+  - The agent-internal conditions (advisor / subagent / consult / bash) apply to ASYNC sessions only — a synchronous call already completed before it returned and has nothing to wait for.
+  - An unknown condition is an explicit error (`wait_for: unsupported condition "..."` — the supported forms are listed above), never a silent wait.
 - interval_ms: poll interval (default 1000, floor 100 — polling never busy-spins)
 - timeout_ms: overall ceiling (default 30000; config.json `agent.waitForTimeoutMs` overrides the default; hard cap 600000 like the execute tool)
 
@@ -21,4 +30,4 @@ Returns:
 Notes:
 - Read-only and non-destructive — it only observes (agent pools, the filesystem, a local port probe).
 - Blocking by design — call it ALONE in a turn, not batched with calls that depend on its result.
-- Do not use it to wait after synchronous tools (advisor / blocking subagent spawn / verify return only when done).
+- This is the one blocking call an agent usually should not reach for. Before calling it, ask: **will this state announce itself to me anyway?** If yes (a subagent report, a review digest, a timer), end the turn and let it arrive.