@thincoder/core 0.10.4 → 0.10.6

package/agent-tools/batch.mjs

@@ -12,9 +12,10 @@
  * eng 子代理 `depth > 0`（`agent._role` 定段）；评审实例 ctx 无 depth 但工具以 `review: true`
  * 绑定。create/close 仅 depth-0 放行；depth-0 的 append/status/close 可选 `path`（D-BR21：
  * 缺省 = findInFlightBatch 取唯一在飞批，0/复数 ⇒ throw）；子代理/评审传 path ⇒ 拒（目标 =
- * spawn/实例注入，语法上写不到别处——运行期门拒）。append 段白名单：depth-0 → §1/§4/§6 ·
- * eng-designer → §2 · 评审 → §3 · eng-coder → §5；status 写域 = 调用者自己段（主 agent 仅 §1
- * ——轮 2 #3 裁定②）。append 迁移面错误串**逐字保持 "batch_segment:" 前缀**（§4.1 全表锚断言）；
+ * spawn/实例注入，语法上写不到别处——运行期门拒）。append 段白名单（**模式感知**——§4.16）：
+ * depth-0 → 工程 §1/§4/§6 ∥ 普通 §1/§2/§4/§5/§6 · eng-designer → §2 · 评审 → §3 · eng-coder → §5 ·
+ * coder（普通模式分支增表——SEGMENT_BY_ROLE_NORMAL）→ §5；status 写域 = 调用者自己段（模式感知
+ * ——见 batch-lifecycle.mjs）。append 迁移面错误串**逐字保持 "batch_segment:" 前缀**（§4.1 全表锚断言）；
  * "batch:" 前缀 = 本批新增错误面（create/close/status/findInFlight/path 门/dispatch）。
  *
  * 导出面：`batchTool`（主名）· `resolveBatchDocPath` · `batchDocBases` · `batchDocForReview` ·
@@ -29,7 +30,7 @@ import { readFileSync, writeFileSync } from "node:fs"
 
 // 描述面 = `tool-docs/batch.md`（#15 描述外置统一——工厂形描述经 DESC 单一解析面，工厂调用期取值）
 import { DESC } from "../tools/shared.mjs"
-import { SEGMENT_BY_ROLE, readBatchStatusLine, sectionHeaderRe, findPlaceholderResidue, placeholderResidueError } from "./batch-skeleton.mjs"
+import { SEGMENT_BY_ROLE, SEGMENT_BY_ROLE_NORMAL, DEPTH0_SEGMENTS, readBatchStatusLine, sectionHeaderRe, findPlaceholderResidue, placeholderResidueError } from "./batch-skeleton.mjs"
 import { batchDocBases, resolveBatchDocPath } from "./batch-paths.mjs"
 import { closeBatchRecord, createBatchRecord, findInFlightBatch, statusBatchRecord } from "./batch-lifecycle.mjs"
 
@@ -93,10 +94,12 @@ function segmentNumber(raw) {
 }
 
 /** 身份 → 可写段号；无写权身份 → null。评审实例绑定优先（评审者的身份即"设计评审"。）
- *  depth-0 的段白名单（append = §1/§4/§6）由 appendBatchRecord 分支，不经本表。 */
-function allowedSegment(agent, review) {
+ *  depth-0 的段白名单（append——模式感知，§4.16）由 appendBatchRecord 分支，不经本表；
+ *  普通模式分支额外合并 coder 增表（`SEGMENT_BY_ROLE_NORMAL`——**合并查只在普通模式分支**）。 */
+function allowedSegment(agent, review, engineering) {
   if (review) return 3
-  return SEGMENT_BY_ROLE[agent?._role] ?? null
+  const role = agent?._role
+  return SEGMENT_BY_ROLE[role] ?? (engineering ? null : SEGMENT_BY_ROLE_NORMAL[role]) ?? null
 }
 
 /**
@@ -146,8 +149,9 @@ function insertIntoSection(src, seg, text) {
 
 /**
  * append 执行体（action=append——原 batch_segment execute 迁移 + depth-0 分支）：
- *  - 段白名单：depth-0 → §1/§4/§6（新错误面，"batch:" 前缀）；eng-designer → §2 · 评审 → §3 ·
- *    eng-coder → §5（迁移错误面，"batch_segment:" 前缀**逐字保持**）；
+ *  - 段白名单（**模式感知**——§4.16）：depth-0 工程 → §1/§4/§6（新错误面，"batch:" 前缀）∥
+ *    depth-0 普通 → §1/§2/§4/§5/§6（模式化新串）；eng-designer → §2 · 评审 → §3 ·
+ *    eng-coder → §5 · coder（普通模式分支增表）→ §5（迁移错误面，"batch_segment:" 前缀**逐字保持**）；
  *  - 目标定位（D-BR21）：depth-0 path 可选（缺省 = findInFlightBatch 唯一在飞批）；子代理/评审
  *    传 path ⇒ 拒，目标 = spawn/实例绑定；
  *  - 其余（gate / text 校验 / 剥凭证 / 骨架保护 / **死占位机检（F11-C）** / 插入 / 记账 / 回执）逐字保持原语义。
@@ -156,20 +160,29 @@ function appendBatchRecord({ args, ctx, review, batchDoc, onWritten }) {
   const agent = ctx?.agent ?? {}
   const cwd = agent.cwd ?? process.cwd()
   const depth0 = ctx?.depth === 0
-  const seg = allowedSegment(agent, review)
+  // 模式位执行期实读（§4.16——同款先例 = task.mjs execute 门；翻转即时生效——D-BR26）
+  const engineering = !!agent?.config?.agent?.engineering
+  const seg = allowedSegment(agent, review, engineering)
   if (!depth0 && seg === null) {
-    throw new Error("batch_segment: no segment is writable by this caller — the channel exists for eng-designer (§2), eng-coder (§5) and design reviews bound to a batch record (§3); the parent agent writes §1/§4/§6 through ordinary document writes.")
+    throw new Error(engineering
+      ? "batch_segment: no segment is writable by this caller — the channel exists for eng-designer (§2), eng-coder (§5) and design reviews bound to a batch record (§3); the parent agent writes §1/§4/§6 through ordinary document writes."
+      : "batch_segment: no segment is writable by this caller — the channel exists for eng-designer (§2), eng-coder (§5) and design reviews bound to a batch record (§3); in normal mode the parent agent writes §1/§2/§4/§5/§6 through ordinary document writes.")
   }
   const n = segmentNumber(args?.segment)
   if (n === null) {
     if (depth0) {
-      throw new Error(`batch: unknown segment ${JSON.stringify(args?.segment ?? null)} — depth-0 append writes §1/§4/§6 of the in-flight record (pass the section number you write, e.g. "§4").`)
+      throw new Error(engineering
+        ? `batch: unknown segment ${JSON.stringify(args?.segment ?? null)} — depth-0 append writes §1/§4/§6 of the in-flight record (pass the section number you write, e.g. "§4").`
+        : `batch: unknown segment ${JSON.stringify(args?.segment ?? null)} — in normal mode depth-0 append writes §1/§2/§4/§5/§6 of the in-flight record (pass the section number you write, e.g. "§4").`)
     }
     throw new Error(`batch_segment: unknown segment ${JSON.stringify(args?.segment ?? null)} — pass the section number you write (e.g. "§${seg}").`)
   }
   if (depth0) {
-    if (n !== 1 && n !== 4 && n !== 6) {
-      throw new Error(`batch: §${n} is not yours to write — depth-0 append writes §1/§4/§6 only (一段一作者: §2 = eng-designer, §3 = design review, §5 = eng-coder).`)
+    const domain = engineering ? DEPTH0_SEGMENTS.append.engineering : DEPTH0_SEGMENTS.append.normal
+    if (!domain.includes(n)) {
+      throw new Error(engineering
+        ? `batch: §${n} is not yours to write — depth-0 append writes §1/§4/§6 only (一段一作者: §2 = eng-designer, §3 = design review, §5 = eng-coder).`
+        : `batch: §${n} is not yours to write — in normal mode depth-0 append writes §1/§2/§4/§5/§6 (一段一作者: §3 = design review only). Nothing was written.`)
     }
   } else if (n !== seg) {
     throw new Error(`batch_segment: §${n} is not yours to write — this caller writes §${seg} only (一段一作者: eng-designer → §2, design review → §3, eng-coder → §5).`)
@@ -246,7 +259,7 @@ export function batchTool(batchDoc = null, { review = false } = {}) {
         },
         segment: {
           type: "string",
-          description: "append/status only — the batch-record section you are writing (e.g. \"§4\"). Declares the section number only; your identity decides what is actually writable (main agent: append §1/§4/§6 · status §1; eng-designer §2; design review §3; eng-coder §5).",
+          description: "append/status only — the batch-record section you are writing (e.g. \"§4\"). Declares the section number only; your identity decides what is actually writable (main agent: append §1/§4/§6 · status §1 (engineering) / append §1/§2/§4/§5/§6 · status §1/§2/§5 (normal); eng-designer §2; eng-coder §5; normal-mode coder with a batchDoc binding §5; design review §3).",
         },
         text: {
           type: "string",

package/agent-tools/browser-async.mjs

@@ -0,0 +1,198 @@
+/**
+ * browser-async.mjs — browser 后台动作任务桥（池 ∥ 起跑 ∥ 结算 ∥ 注入 ∥ 杀单点——复用 bg 族单点，D2）。
+ * 设计权威 = `docs/core/design/BROWSER-TOOL.md` §2.11（异步通道——F-BT18）∥ §2.9（后台动作仍受动作
+ * 预算——timeoutMs 可覆写）∥ §2.10（外部关闭在飞 ⇒ 同因由结算）；批档 = `docs/batches/2026-10-07-browser-async-fix.md` §2。
+ *
+ * - 形态：`async:true`（depth-0 专项——schema 删参 + 运行期第二道）⇒ ack
+ *   `browser#<N> started (running) — <action> <subject>` 即返 ⇒ 后台同队执行（同一串行队列——单页
+ *   不引入并发）⇒ 结算**恒停靠** `_pendingAsyncResults` + 唤醒挂起驱动（bg 同式——消化轮注入）。
+ * - 池：`_browserTasks`（角色 "browser"；帽 `BROWSER_TASK_MAX = 4` 对齐单域 4，第 5 条显式拒——零静默丢）。
+ * - 取消：`process action=kill id:N`（id 路由先 bg 后 browser）⇒ queued 丢队（从未运行）∥ running
+ *   abort（动作展开）⇒ 结算 cancelled（墓碑 + 无摘要；重复幂等）；**不杀浏览器**（重置经 `close`）。
+ *   取消柄 = 条目控制器信号（`browser/session.mjs` `runAction` 的 `{signal}` 缝——一条机制两个因由）。
+ * - 收尾：Stop ∥ 会话中止 ⇒ `async-discard.mjs` `BROWSER_SPEC`（dispose = 条目控制器 abort）+ 墓碑
+ *   `discarded` 出池 + 整批一次提醒（模型可见凭据）；回合中断（Ctrl+I）经 `bindChildController` 豁免
+ *   （池保留——bg 同款）。竞态窗（条目先自行结算、收尾面未及见）⇒ 按 bg 族兜底：正常两态照常停靠
+ *   （摘要必达——零静默丢失），**不**自落「仅墓碑」降级支（墓碑不是模型可见凭据）。
+ * - 注入：`injectBrowserResult`（digest 单点族成员——`injectAsyncResult` 按 role="browser" 分发）；
+ *   回执正文受动作面既有上限（≤20,000 字符）⇒ 无需 offload 径。
+ * - 等待：`wait_for "browser id:N done"`（`browserTaskDone`——池内 done ∥ 出池即 done）。
+ * 入径 = `tools/browser.mjs` ∥ `tools/ops.mjs` **动态 import**（W8 契约②）；模块图：→ browser/session.mjs
+ * （入队面）· agent-tools/async-settle.mjs · subagent-scheduler.mjs（取号 / 令牌 / 键守卫）·
+ * agent/helpers.mjs（escapeXml）· context.mjs（pushReal）——叶子向、无环。
+ */
+import { escapeXml } from "../agent/helpers.mjs"
+import { pushReal } from "../context.mjs"
+import { runAction } from "../browser/session.mjs"
+import {
+  bindChildController, buildChildSignal, carrierField, getAsyncPool, parkAsyncPending,
+  tombstoneOf, wakeAsyncWaiters, writeTombstone,
+} from "./async-settle.mjs"
+import { assertPoolKeyFree, consumeSubagentToken, nextSubagentId } from "./subagent-scheduler.mjs"
+
+/** 后台动作帽（对齐 `ASYNC_POOL_LIMITS` 单域 4——KD-22）。超限显式拒。 */
+export const BROWSER_TASK_MAX = 4
+
+/** 池写侧（绑定不变式：主容器落父字段；缺省借用 / 别名 `history` 侧——同 `bash-async.mjs` 同式）。 */
+function ensureBrowserPool(parent) {
+  if (parent._browserTasks instanceof Map) return parent._browserTasks
+  const borrowed = carrierField(parent, "_browserTasks")
+  if (borrowed instanceof Map) { parent._browserTasks = borrowed; return borrowed }
+  parent._browserTasks = new Map()
+  if (parent?.history && typeof parent.history === "object") parent.history._browserTasks = parent._browserTasks
+  return parent._browserTasks
+}
+
+/** 条目读取（键形单源：写侧 `set(String(id))` ⇒ 读一律 String 归一；双形键兜底照 bg 族）。 */
+export function browserTaskEntry(parent, id) {
+  const pool = getAsyncPool(parent, "browser")
+  if (!(pool instanceof Map)) return null
+  const key = String(id)
+  return pool.get(key) ?? pool.get(Number(key)) ?? null
+}
+
+/** `wait_for` 条件 `browser id:N done` 判据（同式 bg）：池内 done ∥ **出池即 done**（结算恒出池——
+ *  pending 停靠 / 杀 / 丢弃皆已结束）；未知 id 亦按 done-by-vacuity。 */
+export function browserTaskDone(parent, id) {
+  const entry = browserTaskEntry(parent, id)
+  if (!entry) return true
+  return entry.done === true || entry.status === "done"
+}
+
+/** 条目中止（同一机制两处调用：kill 径 `killBrowserTask` ∥ discard 收尾面 `BROWSER_SPEC.dispose`）：
+ *  条目控制器 abort ⇒ `runAction` 信号径传导（queued 丢队 ∥ running 动作展开）；重复幂等
+ *  （`AbortController.abort` 幂等）。 */
+function abortBrowserEntry(entry) {
+  try { entry?.controller?.abort?.({ abortTrigger: "browser-kill" }) } catch { /* 已中止 */ }
+}
+
+/** subject 标签（ack ∥ 摘要共用）：动作对象头——navigate = url ∥ ref / selector / url / key / op /
+ *  from / networkIdle ∥ 坐标 ∥ expression 头 ∥ text 头；全空 ⇒ 空串。 */
+export function browserSubject(action, args = {}) {
+  const pick = action === "navigate" ? (args.url ?? null)
+    : (args.ref ?? args.selector ?? args.url ?? args.key ?? args.op ?? args.from
+      ?? (args.networkIdle === true ? "networkIdle" : null))
+  if (pick != null && String(pick) !== "") return String(pick)
+  if (String(args.x ?? "") !== "" && String(args.y ?? "") !== "" && Number.isFinite(Number(args.x)) && Number.isFinite(Number(args.y))) {
+    return `${args.x},${args.y}`
+  }
+  if (typeof args.expression === "string" && args.expression) return args.expression.slice(0, 60)
+  if (typeof args.text === "string" && args.text) return args.text.slice(0, 40)
+  return ""
+}
+
+/**
+ * 起跑（ack 即返——调用方不被动作阻塞）。失败面 = 显式 `{ error }`（帽 / 深度 / 上下文——零静默丢）。
+ * @returns {{ id: number, ack: string, entry: object } | { error: string }}
+ */
+export async function launchBrowserTask(parent, ctx, args = {}) {
+  if (!parent) return { error: "no agent context — background browser tasks run in a depth-0 session only" }
+  if ((ctx?.depth ?? 0) > 0) {
+    return { error: "browser async is depth-0 only — a child agent has no background task pool (run the action synchronously)" }
+  }
+  const action = String(args.action ?? "")
+  const pool = ensureBrowserPool(parent)
+  const running = [...pool.values()].filter((e) => e.done !== true)
+  if (running.length >= BROWSER_TASK_MAX) {
+    return {
+      error: `browser task cap reached (${running.length}/${BROWSER_TASK_MAX} running: ${running.map((e) => `browser#${e.id}`).join(", ")})` +
+        ` — wait for one to settle (wait_for "browser id:N done") or kill one (process action='kill' id:N)`,
+    }
+  }
+  // ED-5：取号 → 消费同步配对（无 await 间隙）+ 入池键守卫（同 bash-async 同式——守卫前置于起跑，命中即抛零副作用）。
+  const id = nextSubagentId(parent)
+  consumeSubagentToken(parent, id, "browser async launch", "browser")
+  assertPoolKeyFree(pool, id, "browser")
+  const { async: _asyncFlag, ...actionArgs } = args // `async` 不入动作参数面（零语义泄漏）
+  const subject = browserSubject(action, actionArgs)
+  const ctrl = new AbortController()
+  const entry = {
+    id, role: "browser", action, args: actionArgs, subject,
+    status: "running", done: false, cancelled: false, discarded: false,
+    controller: ctrl, startedAt: Date.now(), endedAt: null,
+    receipt: null, error: null, failed: null, _settle: null, promise: null,
+  }
+  entry.promise = new Promise((res) => { entry._settle = res })
+  // 会话 / 回合信号链（同 bg）：非 interrupt 中止 ⇒ 控制器中止 ⇒ 动作展开 + discard 收尾面；
+  // 回合中断（Ctrl+I）⇒ 不动（池保留）。
+  bindChildController(ctrl, buildChildSignal(parent, ctx))
+  entry.promiseRun = Promise.resolve()
+    .then(() => runAction(action, actionArgs, ctx, { signal: ctrl.signal }))
+    .then(
+      (receipt) => { entry.receipt = String(receipt) },
+      (e) => { entry.error = e?.message ?? String(e) },
+    )
+    .finally(() => finalizeBrowserEntry(parent, entry))
+  pool.set(String(id), entry)
+  return { id, ack: `browser#${id} started (running) — ${action}${subject ? ` ${subject}` : ""}`, entry }
+}
+
+/**
+ * 结算单点（回执 / 拒绝两径合流；幂等：entry.done 即返）。取消 / 丢弃两态 ⇒ 只落终态与唤醒（无摘要——
+ * 凭据 = 杀点确认 ∥ 收尾整批提醒）；其余（含会话中止竞态窗——收尾面未及见）⇒ 恒停靠 pending + 唤醒
+ * 挂起驱动（消化轮注入——零静默丢失；同 `bash-async.mjs` finalize 同式，**不**自落「仅墓碑」支）。
+ */
+function finalizeBrowserEntry(parent, entry) {
+  if (entry.done) return
+  entry.done = true
+  entry.status = "done"
+  entry.endedAt = Date.now()
+  getAsyncPool(parent, "browser")?.delete(String(entry.id))
+  if (entry.cancelled === true || entry.discarded === true) {
+    entry._settle?.() // 定向杀 ∥ 会话中止收尾——不注入（墓碑已由杀点 / 收尾面落定）
+    return
+  }
+  const receipt = entry.receipt ?? ""
+  if (entry.error == null && receipt.startsWith("Error:")) {
+    entry.failed = receipt.split("\n")[0].replace(/^Error:\s*/, "")
+  }
+  parkAsyncPending(parent, entry)
+  entry._settleSeq = (parent._asyncSettleSeq = (parent._asyncSettleSeq ?? 0) + 1)
+  entry._settle?.()
+  wakeAsyncWaiters(parent)
+}
+
+/** 状态词截断（摘要首行单行可读——超长因由截 200 字符）。 */
+function clip(text, max = 200) {
+  const s = String(text)
+  return s.length > max ? `${s.slice(0, max)}…` : s
+}
+
+/** 注入器（digest 单点族成员——`injectAsyncResult` 按 role="browser" 分发；消费即墓碑）。 */
+export async function injectBrowserResult(parent, entry) {
+  const seconds = (Math.max(0, (entry.endedAt ?? Date.now()) - entry.startedAt) / 1000).toFixed(1)
+  const label = `${entry.action}${entry.subject ? ` ${entry.subject}` : ""}`
+  const status = entry.error != null ? `failed: ${clip(entry.error)}`
+    : entry.failed != null ? `failed: ${clip(entry.failed)}`
+    : "ok"
+  const head = `[System reminder: background browser#${entry.id} finished — ${label} (${status}, ${seconds}s)]`
+  const body = escapeXml(String(entry.receipt ?? entry.error ?? "(no result)"))
+  pushReal(parent, { role: "user", content: `${head}\n${body}` })
+  writeTombstone(parent, entry.id, entry.error != null || entry.failed != null ? "failed" : "consumed", "browser")
+}
+
+/**
+ * 杀单点（id 靶——`process` action='kill'）：queued ⇒ 丢队（从未运行）∥ running ⇒ abort（动作展开）
+ * ⇒ 结算 cancelled（墓碑 + 无摘要）；**不杀浏览器**；重复 = 幂等（经终态墓碑返回同一确认——bg 同式）。
+ * @returns {{ id: string, status: "cancelled" | "error", error?: string }}
+ */
+export function killBrowserTask(parent, id) {
+  const key = String(id)
+  if (!key || key === "undefined" || key === "null") {
+    return { id: key, status: "error", error: "process kill id: requires a background browser task id (browser#N from the async ack)" }
+  }
+  const pool = getAsyncPool(parent, "browser")
+  const entry = browserTaskEntry(parent, key)
+  if (!entry) {
+    const tomb = tombstoneOf(parent, key)
+    if (tomb?.status === "cancelled" && tomb.role === "browser") return { id: key, status: "cancelled" } // 幂等确认
+    return { id: key, status: "error", error: `unknown background browser task id: ${key} — it has finished, was killed, or was never started` }
+  }
+  if (entry.done) return { id: key, status: "error", error: `browser#${key} has already finished — nothing to kill` }
+  if (entry.cancelled) return { id: key, status: "cancelled" } // 杀已在途——幂等
+  entry.cancelled = true
+  abortBrowserEntry(entry)
+  pool?.delete(key)
+  writeTombstone(parent, key, "cancelled", "browser")
+  return { id: key, status: "cancelled" }
+}

package/agent-tools/checkpoint.mjs

@@ -59,7 +59,7 @@ export function registerTurnCapCheckpoint(child, carrier, { turn = 0, signal } =
   if (signal?.aborted) return Promise.resolve(false) // ② 已中止 ⇒ 立即降级（不进挂起）
   const key = String(carrier.id ?? "")
   const rec = { child, carrier, turn }
-  // 先臂后报请（顺序即防御）：`rec.resolve` 与中止监听在入队**前**就位——否则
+  // 先布防、后报请（顺序即防御）：`rec.resolve` 与中止监听在入队**前**就位——否则
   // `pushChildUpstream` 同步唤醒等待栓的窗口里「登记已写、resolve 未挂」，兑现假成功而挂起不收敛。
   let abortedNow = signal?.aborted === true
   const promise = new Promise((resolve) => {

package/agent-tools/design-slots.mjs

@@ -0,0 +1,232 @@
+/**
+ * design-slots.mjs — design-token 槽位清点 + 消费核（2026-10-07 批 ledger-tool · 台账 #927 并入）。
+ * 设计单源 = `docs/core/design/DESIGN-TOKEN-SETTLEMENT.md` §10（F-SL1 清点面 / F-SL2 批量消费）。
+ *
+ * 面一 `executeDesignSlotsAction`（`subagent` action `design-slots`——只读）：
+ *   数据源 = 槽文件权威表（`readEngTokensFromSlot`——无 TTL 过滤原样）∪ 内存 Map（并集去重，
+ *   冲突以槽为准——D-S3 同源）；**零写**（不 reconcile 回写、不落盘）。列表面 = 逐槽一行
+ *   （designId ∥ live/expired ∥ ageDays ∥ expiresAt ∥ 批；龄序 = 最老在前）+ 计数尾行；
+ *   「批」= `_advisorRuns` 按 designId 命中 run 的 `docSetKey` 中 `batches/` 段档取 basename
+ *   （KD-SL2——零新存储；不可得 ⇒ `—`）。
+ * 面二 `executeConsumeDesignAction`（`subagent` action `consume-design` 消费核——自
+ *   `subagent-spawn.mjs` 迁入）：选择器恰一（`designId` ∥ `designIds` ∥ `expired` ∥
+ *   `olderThanDays`——KD-SL3 fail-closed 不猜）；目标集 = 并集视图按选择器解析 → 逐枚移出
+ *   （`removeDesignTokenSlot` 同款 token 值守护）→ **单次** `persistEngTokens` 落盘（D-S6 单点）；
+ *   落盘失败 ⇒ 内存快照整体回滚 + 抛（KD-SL4——不留半消费态）。单枚形态（designId / 无选择器
+ *   单槽）：语义 / 拒文 / 回执**现行逐字不变**。
+ *
+ * 签发链行为零改（mint / settle / TTL / persist 存储形——#868 面另论）；工程模式父侧（depth-0）限定
+ * （门 = 本档两执行器；depth 面由装配与受限变体门承载）。
+ */
+import { persistEngTokens, readEngTokensFromSlot, reconcileEngTokensFromSlot, removeDesignTokenSlot, tokenExpired, tokenExpiryMs } from "../token-ttl.mjs"
+import { effectiveTokenTtlMs } from "./design-token.mjs"
+import { advisorRuns } from "./advisor-async.mjs"
+
+const DAY_MS = 86400000
+
+/** 槽并集视图（F-SL1 数据源 / F-SL2 目标集解析）：内存 Map 先行、槽文件权威表覆盖（同 id 冲突以槽
+ *  为准——D-S3 同源）；纯读——零回写、零落盘。 */
+function unionSlots(agent) {
+  const merged = new Map()
+  const mem = agent?._engDesignTokens
+  if (mem instanceof Map) for (const [id, t] of mem) merged.set(id, t)
+  const file = readEngTokensFromSlot(agent)
+  if (file) for (const [id, t] of Object.entries(file)) merged.set(id, t)
+  return merged
+}
+
+/** 「批」列派生（KD-SL2——零新存储）：会话内评审实例注册表 `_advisorRuns` 按 designId 命中的**最新**
+ *  run ⇒ `docSetKey`（被审文档绝对路径集 JSON）中 `batches/` 段档取 basename；不可得（跨重启 /
+ *  模式重进 / 注册表回收）⇒ `—`（如实降级）。 */
+function batchOf(agent, designId) {
+  const runs = advisorRuns(agent)
+  if (!(runs instanceof Map)) return "—"
+  for (const run of [...runs.values()].reverse()) {
+    if (run?.designId !== designId || typeof run.docSetKey !== "string") continue
+    const name = batchBasename(run.docSetKey)
+    if (name) return name
+  }
+  return "—"
+}
+
+/** docSetKey（JSON 串）→ `batches/` 段档 basename（首命中）；不可解析 / 无命中 ⇒ null。 */
+function batchBasename(docSetKey) {
+  let list = null
+  try { list = JSON.parse(docSetKey) } catch { return null }
+  if (!Array.isArray(list)) return null
+  for (const p of list) {
+    if (typeof p !== "string") continue
+    const parts = p.split(/[\\/]/)
+    const i = parts.lastIndexOf("batches")
+    if (i >= 0 && i < parts.length - 1 && parts[i + 1]) return parts[i + 1]
+  }
+  return null
+}
+
+/** 槽事实（清点列与选择器共用）：状态 = `tokenExpired` 单源；`ageDays` = now − (expiresAt −
+ *  `effectiveTokenTtlMs`) 派生（TTL 配置曾改时为近似——如实注）；`expiresAt` 精确；畸形 / 格式外
+ *  token ⇒ 两项 `—`（不可判龄）。 */
+function slotFacts(agent, designId, token, now, ttlMs) {
+  const expiry = typeof token === "string" ? tokenExpiryMs(token) : null
+  return {
+    designId, token,
+    expired: typeof token === "string" && tokenExpired(token, now),
+    ageDays: expiry === null ? null : (now - (expiry - ttlMs)) / DAY_MS,
+    expiresAt: expiry,
+    batch: batchOf(agent, designId),
+  }
+}
+
+/** 龄序比较（最老在前——剩余有效期升序；不可判龄（畸形串）排尾——不冒充最老）。 */
+const byOldest = (a, b) => (b.ageDays ?? -Infinity) - (a.ageDays ?? -Infinity)
+
+/**
+ * `subagent` action `design-slots`（F-SL1——只读清点面）：工程模式父侧限定（与 consume-design
+ * 同门）。输出 = 行文本（逐槽行 + 计数尾行）；字段 / 序 / 降级标记 = 契约，行内措辞 = 实现面。
+ * 分类 = 只读（planMode 放行 / 免审批 / digest 放行——谓词在 `agent/dispatch-gates.mjs`）。
+ */
+export function executeDesignSlotsAction(args, ctx) {
+  const parent = ctx?.agent
+  if (!parent?.config?.agent?.engineering) {
+    throw new Error("Engineering mode is not active — design-slots applies only to engineering-mode design tokens (spawn 同门).")
+  }
+  const now = Date.now()
+  const ttlMs = effectiveTokenTtlMs(parent)
+  const entries = [...unionSlots(parent)].map(([id, t]) => slotFacts(parent, id, t, now, ttlMs))
+  entries.sort(byOldest)
+  const lines = entries.map((e) =>
+    `- designId=${e.designId} status=${e.expired ? "expired" : "live"} ageDays=${e.ageDays === null ? "—" : e.ageDays.toFixed(1)} expiresAt=${e.expiresAt === null ? "—" : new Date(e.expiresAt).toISOString()} batch=${e.batch}`)
+  const live = entries.filter((e) => !e.expired).length
+  lines.push(`design-slots: ${entries.length} slot(s) — ${live} live / ${entries.length - live} expired`)
+  return lines.join("\n")
+}
+
+/**
+ * `subagent` action `consume-design` 消费核（F-SL2；自 `subagent-spawn.mjs` 迁入——2026-10-07）：
+ * 选择器恰一——`designId`（现行 · 单枚）∥ `designIds`（显式非空清单）∥ `expired:true`（全部过期项）
+ * ∥ `olderThanDays:N`（ageDays > N）；多选择器同给 / 选择器缺失且多槽 ⇒ 拒（fail-closed——不猜）。
+ * 单枚形态走 `consumeSingle`（拒文 / 回执逐字不变）；批量走 `consumeBatch`（逐枚行 + `consumed N` 计数行）。
+ */
+export function executeConsumeDesignAction(args, ctx) {
+  const parent = ctx?.agent
+  if (!parent?.config?.agent?.engineering) {
+    throw new Error("Engineering mode is not active — consume-design applies only to engineering-mode design tokens (spawn 同门).")
+  }
+  const slots = parent?._engDesignTokens
+  const hasSlots = slots instanceof Map && slots.size > 0
+  const designId = args?.designId ? String(args.designId) : undefined
+  const selectors = []
+  if (designId !== undefined) selectors.push("designId")
+  if (args?.designIds !== undefined && args?.designIds !== null) selectors.push("designIds")
+  if (args?.expired !== undefined && args?.expired !== null) selectors.push("expired")
+  if (args?.olderThanDays !== undefined && args?.olderThanDays !== null) selectors.push("olderThanDays")
+  if (selectors.length > 1) {
+    throw new Error(`consume-design: pass exactly ONE selector — designId / designIds / expired / olderThanDays (got: ${selectors.join(" + ")}); a batch consume never guesses its target set.`)
+  }
+  if (selectors.length === 0) {
+    // 无选择器 = 单枚兼容形态（现行语义零变）：缺 designId 且多槽 ⇒ 拒（不误消费任一槽）
+    if (hasSlots && slots.size > 1) {
+      throw new Error(`consume-design: Multiple approved designs in this session (${slots.size}) — pass the designId parameter (echoed with each token) to choose which design to close out.`)
+    }
+    return consumeSingle(parent, undefined)
+  }
+  if (selectors[0] === "designId") return consumeSingle(parent, designId)
+  return consumeBatch(parent, selectors[0], args)
+}
+
+/** 单枚消费（现行形态逐字保留——读内存槽；未知 / 已消费 ⇒ 幂等 no-op；落盘失败 ⇒ 槽回滚 + 抛）。 */
+function consumeSingle(parent, designId) {
+  const slots = parent?._engDesignTokens
+  const hasSlots = slots instanceof Map && slots.size > 0
+  // 读槽值：给定 designId → 精确槽（未知/已消费 → undefined）；缺省 → 唯一槽
+  let token = null
+  if (designId && hasSlots) token = slots.get(designId) ?? null
+  else if (!designId && hasSlots) token = [...slots.values()][0]
+  // 未知 designId / 已消费 / 无任何槽 → 幂等 no-op 提示（不报错——评审 #3 定死）
+  if (!token) {
+    return `consume-design: no live slot${designId ? ` for designId ${designId}` : ""} (already consumed or never issued) — idempotent no-op, nothing changed.`
+  }
+  const slotId = designId ?? [...slots.keys()][0]
+  removeDesignTokenSlot(parent, designId, token)
+  try {
+    persistEngTokens(parent)
+  } catch (e) {
+    if (slotId) parent._engDesignTokens.set(slotId, token)
+    throw new Error(`consume-design: the slot was removed in memory but could NOT be durably deleted from the slot file (${e.message}) — the slot is restored in memory; retry consume-design.`)
+  }
+  return `design slot consumed — designId ${designId ?? "(single-design session)"} is closed out; a further eng-coder spawn for this design is mechanically rejected, and any new work (including deviation fixes) requires a fresh advisor(type='design') review and token.`
+}
+
+/** 批量消费（F-SL2 / KD-SL3 / KD-SL4）：目标集 = 并集视图按选择器解析；逐枚移出（token 值守护）→
+ *  单次 persist；落盘失败 ⇒ 内存快照整体回滚 + 抛。回执 = 逐枚行 + 计数行（`consumed N`）。
+ *  落盘前先经 D2 权威表 reconcile（槽 = 权威；未选中的**活**槽因此并入内存、随 persist 保住——
+ *  过期项则随本次落盘一并出清，即「落盘携带（如实）」注）。 */
+function consumeBatch(parent, selector, args) {
+  const now = Date.now()
+  const ttlMs = effectiveTokenTtlMs(parent)
+  const snapshot = parent._engDesignTokens instanceof Map ? new Map(parent._engDesignTokens) : null
+  reconcileEngTokensFromSlot(parent)
+  const union = unionSlots(parent)
+  const targets = []
+  const seen = new Set()
+  if (selector === "designIds") {
+    if (!Array.isArray(args.designIds) || args.designIds.length === 0) {
+      throw new Error("consume-design: designIds must be a non-empty array of design ids — pass an explicit list, or use expired / olderThanDays.")
+    }
+    for (const raw of args.designIds) {
+      const id = typeof raw === "string" ? raw.trim() : ""
+      if (!id) throw new Error(`consume-design: designIds entries must be non-empty strings (got ${JSON.stringify(raw)}).`)
+      if (seen.has(id)) continue // 重复条目去重（同一 id 只计一次——回执计数不虚增）
+      seen.add(id)
+      const token = union.get(id) ?? null
+      targets.push({ designId: id, token, consumed: token !== null }) // 未知 / 已消费 ⇒ 逐枚 no-op（幂等）
+    }
+  } else if (selector === "expired") {
+    if (args.expired !== true) {
+      throw new Error("consume-design: expired must be true — it selects every expired slot; pass designIds / olderThanDays for other shapes.")
+    }
+    for (const [id, t] of union) {
+      if (typeof t === "string" && tokenExpired(t, now)) {
+        const expiry = tokenExpiryMs(t)
+        targets.push({ designId: id, token: t, consumed: true, ageDays: expiry === null ? null : (now - (expiry - ttlMs)) / DAY_MS })
+      }
+    }
+    targets.sort(byOldest)
+  } else {
+    const n = args.olderThanDays
+    if (typeof n !== "number" || !Number.isFinite(n) || n < 0) {
+      throw new Error("consume-design: olderThanDays must be a non-negative number — pass the day threshold (e.g. olderThanDays: 30).")
+    }
+    for (const [id, t] of union) {
+      const expiry = typeof t === "string" ? tokenExpiryMs(t) : null
+      if (expiry === null) continue // 畸形串不可判龄——不被龄选择器选中（清点面照列）
+      const ageDays = (now - (expiry - ttlMs)) / DAY_MS
+      if (ageDays > n) targets.push({ designId: id, token: t, consumed: true, ageDays })
+    }
+    targets.sort(byOldest)
+  }
+  const removals = targets.filter((t) => t.consumed)
+  for (const t of removals) removeDesignTokenSlot(parent, t.designId, t.token)
+  if (removals.length > 0) {
+    try {
+      persistEngTokens(parent)
+    } catch (e) {
+      // KD-SL4：内存快照整体回滚 + 抛（不留半消费态——可重试）
+      if (snapshot) {
+        const map = parent._engDesignTokens instanceof Map ? parent._engDesignTokens : (parent._engDesignTokens = new Map())
+        map.clear()
+        for (const [id, v] of snapshot) map.set(id, v)
+      } else {
+        delete parent._engDesignTokens
+      }
+      throw new Error(`consume-design: ${removals.length} slot(s) were removed in memory but could NOT be durably deleted from the slot file (${e.message}) — the slots are restored in memory; retry consume-design.`)
+    }
+  }
+  const lines = targets.map((t) => (t.consumed
+    ? `- designId ${t.designId} — consumed`
+    : `- designId ${t.designId} — no live slot (already consumed or never issued) — idempotent no-op, nothing changed.`))
+  lines.push(removals.length > 0
+    ? `consumed ${removals.length} design slot(s) — a further eng-coder spawn for these designs is mechanically rejected; any new work (including deviation fixes) requires a fresh advisor(type='design') review and token.`
+    : "consumed 0 design slot(s) — nothing changed (idempotent no-op).")
+  return lines.join("\n")
+}

package/agent-tools/digest-budget.mjs

@@ -55,7 +55,7 @@ export function digestBudgetOver(agent, size) {
   return over
 }
 
-/** Test seam: 落盘目录重定向（单测沙箱——生产从不调用）。 */
+/** Test seam: 落盘目录重定向（单元测试沙箱——生产从不调用）。 */
 let _digestOffloadDirOverride = null
 export function _setDigestOffloadDirForTest(dir) { _digestOffloadDirOverride = dir }